| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLAPI 1" |
| 58 |
.TH PERLAPI 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlapi \- autogenerated documentation for the perl public API |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Xref "Perl API API api" |
| 67 |
.IX Header "DESCRIPTION" |
| 68 |
This file contains most of the documentation of the perl public API, as |
| 69 |
generated by \fIembed.pl\fR. Specifically, it is a listing of functions, |
| 70 |
macros, flags, and variables that may be used by extension writers. Besides |
| 71 |
perlintern and \fIconfig.h\fR, some items are listed here as being actually |
| 72 |
documented in another pod. |
| 73 |
.PP |
| 74 |
At the end is a list of functions which have yet |
| 75 |
to be documented. Patches welcome! The interfaces of these are subject to |
| 76 |
change without notice. |
| 77 |
.PP |
| 78 |
Some of the functions documented here are consolidated so that a single entry |
| 79 |
serves for multiple functions which all do basically the same thing, but have |
| 80 |
some slight differences. For example, one form might process magic, while |
| 81 |
another doesn't. The name of each variation is listed at the top of the |
| 82 |
single entry. But if all have the same signature (arguments and return type) |
| 83 |
except for their names, only the usage for the base form is shown. If any |
| 84 |
one of the forms has a different signature (such as returning \f(CW\*(C`const\*(C'\fR or |
| 85 |
not) every function's signature is explicitly displayed. |
| 86 |
.PP |
| 87 |
Anything not listed here or in the other mentioned pods is not part of the |
| 88 |
public API, and should not be used by extension writers at all. For these |
| 89 |
reasons, blindly using functions listed in \fIproto.h\fR is to be avoided when |
| 90 |
writing extensions. |
| 91 |
.PP |
| 92 |
In Perl, unlike C, a string of characters may generally contain embedded |
| 93 |
\&\f(CW\*(C`NUL\*(C'\fR characters. Sometimes in the documentation a Perl string is referred |
| 94 |
to as a "buffer" to distinguish it from a C string, but sometimes they are |
| 95 |
both just referred to as strings. |
| 96 |
.PP |
| 97 |
Note that all Perl API global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR |
| 98 |
prefix. Again, those not listed here are not to be used by extension writers, |
| 99 |
and may be changed or removed without notice; same with macros. |
| 100 |
Some macros are provided for compatibility with the older, |
| 101 |
unadorned names, but this support may be disabled in a future release. |
| 102 |
.PP |
| 103 |
Perl was originally written to handle US-ASCII only (that is characters |
| 104 |
whose ordinal numbers are in the range 0 \- 127). |
| 105 |
And documentation and comments may still use the term ASCII, when |
| 106 |
sometimes in fact the entire range from 0 \- 255 is meant. |
| 107 |
.PP |
| 108 |
The non-ASCII characters below 256 can have various meanings, depending on |
| 109 |
various things. (See, most notably, perllocale.) But usually the whole |
| 110 |
range can be referred to as ISO\-8859\-1. Often, the term "Latin\-1" (or |
| 111 |
"Latin1") is used as an equivalent for ISO\-8859\-1. But some people treat |
| 112 |
"Latin1" as referring just to the characters in the range 128 through 255, or |
| 113 |
sometimes from 160 through 255. |
| 114 |
This documentation uses "Latin1" and "Latin\-1" to refer to all 256 characters. |
| 115 |
.PP |
| 116 |
Note that Perl can be compiled and run under either ASCII or EBCDIC (See |
| 117 |
perlebcdic). Most of the documentation (and even comments in the code) |
| 118 |
ignore the EBCDIC possibility. |
| 119 |
For almost all purposes the differences are transparent. |
| 120 |
As an example, under EBCDIC, |
| 121 |
instead of UTF\-8, UTF-EBCDIC is used to encode Unicode strings, and so |
| 122 |
whenever this documentation refers to \f(CW\*(C`utf8\*(C'\fR |
| 123 |
(and variants of that name, including in function names), |
| 124 |
it also (essentially transparently) means \f(CW\*(C`UTF\-EBCDIC\*(C'\fR. |
| 125 |
But the ordinals of characters differ between ASCII, EBCDIC, and |
| 126 |
the UTF\- encodings, and a string encoded in UTF-EBCDIC may occupy a different |
| 127 |
number of bytes than in UTF\-8. |
| 128 |
.PP |
| 129 |
The organization of this document is tentative and subject to change. |
| 130 |
Suggestions and patches welcome |
| 131 |
perl5\[email protected] <mailto:[email protected]>. |
| 132 |
.PP |
| 133 |
The sections in this document currently are |
| 134 |
.IP """AV Handling""" 4 |
| 135 |
.IX Item """AV Handling""" |
| 136 |
.PD 0 |
| 137 |
.IP """Callback Functions""" 4 |
| 138 |
.IX Item """Callback Functions""" |
| 139 |
.IP """Casting""" 4 |
| 140 |
.IX Item """Casting""" |
| 141 |
.IP """Character case changing""" 4 |
| 142 |
.IX Item """Character case changing""" |
| 143 |
.IP """Character classification""" 4 |
| 144 |
.IX Item """Character classification""" |
| 145 |
.IP """Compiler and Preprocessor information""" 4 |
| 146 |
.IX Item """Compiler and Preprocessor information""" |
| 147 |
.IP """Compiler directives""" 4 |
| 148 |
.IX Item """Compiler directives""" |
| 149 |
.IP """Compile-time scope hooks""" 4 |
| 150 |
.IX Item """Compile-time scope hooks""" |
| 151 |
.IP """Concurrency""" 4 |
| 152 |
.IX Item """Concurrency""" |
| 153 |
.IP """COPs and Hint Hashes""" 4 |
| 154 |
.IX Item """COPs and Hint Hashes""" |
| 155 |
.IP """Custom Operators""" 4 |
| 156 |
.IX Item """Custom Operators""" |
| 157 |
.IP """CV Handling""" 4 |
| 158 |
.IX Item """CV Handling""" |
| 159 |
.IP """Debugging""" 4 |
| 160 |
.IX Item """Debugging""" |
| 161 |
.IP """Display functions""" 4 |
| 162 |
.IX Item """Display functions""" |
| 163 |
.IP """Embedding, Threads, and Interpreter Cloning""" 4 |
| 164 |
.IX Item """Embedding, Threads, and Interpreter Cloning""" |
| 165 |
.IP """Errno""" 4 |
| 166 |
.IX Item """Errno""" |
| 167 |
.IP """Exception Handling (simple) Macros""" 4 |
| 168 |
.IX Item """Exception Handling (simple) Macros""" |
| 169 |
.IP """Filesystem configuration values""" 4 |
| 170 |
.IX Item """Filesystem configuration values""" |
| 171 |
.IP """Floating point""" 4 |
| 172 |
.IX Item """Floating point""" |
| 173 |
.IP """General Configuration""" 4 |
| 174 |
.IX Item """General Configuration""" |
| 175 |
.IP """Global Variables""" 4 |
| 176 |
.IX Item """Global Variables""" |
| 177 |
.IP """GV Handling and Stashes""" 4 |
| 178 |
.IX Item """GV Handling and Stashes""" |
| 179 |
.IP """Hook manipulation""" 4 |
| 180 |
.IX Item """Hook manipulation""" |
| 181 |
.IP """HV Handling""" 4 |
| 182 |
.IX Item """HV Handling""" |
| 183 |
.IP """Input/Output""" 4 |
| 184 |
.IX Item """Input/Output""" |
| 185 |
.IP """Integer""" 4 |
| 186 |
.IX Item """Integer""" |
| 187 |
.IP """I/O Formats""" 4 |
| 188 |
.IX Item """I/O Formats""" |
| 189 |
.IP """Lexer interface""" 4 |
| 190 |
.IX Item """Lexer interface""" |
| 191 |
.IP """Locales""" 4 |
| 192 |
.IX Item """Locales""" |
| 193 |
.IP """Magic""" 4 |
| 194 |
.IX Item """Magic""" |
| 195 |
.IP """Memory Management""" 4 |
| 196 |
.IX Item """Memory Management""" |
| 197 |
.IP """MRO""" 4 |
| 198 |
.IX Item """MRO""" |
| 199 |
.IP """Multicall Functions""" 4 |
| 200 |
.IX Item """Multicall Functions""" |
| 201 |
.IP """Numeric Functions""" 4 |
| 202 |
.IX Item """Numeric Functions""" |
| 203 |
.IP """Optrees""" 4 |
| 204 |
.IX Item """Optrees""" |
| 205 |
.IP """Pack and Unpack""" 4 |
| 206 |
.IX Item """Pack and Unpack""" |
| 207 |
.IP """Pad Data Structures""" 4 |
| 208 |
.IX Item """Pad Data Structures""" |
| 209 |
.IP """Password and Group access""" 4 |
| 210 |
.IX Item """Password and Group access""" |
| 211 |
.IP """Paths to system commands""" 4 |
| 212 |
.IX Item """Paths to system commands""" |
| 213 |
.IP """Prototype information""" 4 |
| 214 |
.IX Item """Prototype information""" |
| 215 |
.IP """Reference-counted stack manipulation""" 4 |
| 216 |
.IX Item """Reference-counted stack manipulation""" |
| 217 |
.IP """REGEXP Functions""" 4 |
| 218 |
.IX Item """REGEXP Functions""" |
| 219 |
.IP """Reports and Formats""" 4 |
| 220 |
.IX Item """Reports and Formats""" |
| 221 |
.IP """Signals""" 4 |
| 222 |
.IX Item """Signals""" |
| 223 |
.IP """Site configuration""" 4 |
| 224 |
.IX Item """Site configuration""" |
| 225 |
.IP """Sockets configuration values""" 4 |
| 226 |
.IX Item """Sockets configuration values""" |
| 227 |
.IP """Source Filters""" 4 |
| 228 |
.IX Item """Source Filters""" |
| 229 |
.IP """Stack Manipulation Macros""" 4 |
| 230 |
.IX Item """Stack Manipulation Macros""" |
| 231 |
.IP """String Handling""" 4 |
| 232 |
.IX Item """String Handling""" |
| 233 |
.IP """SV Flags""" 4 |
| 234 |
.IX Item """SV Flags""" |
| 235 |
.IP """SV Handling""" 4 |
| 236 |
.IX Item """SV Handling""" |
| 237 |
.IP """Tainting""" 4 |
| 238 |
.IX Item """Tainting""" |
| 239 |
.IP """Time""" 4 |
| 240 |
.IX Item """Time""" |
| 241 |
.IP """Typedef names""" 4 |
| 242 |
.IX Item """Typedef names""" |
| 243 |
.IP """Unicode Support""" 4 |
| 244 |
.IX Item """Unicode Support""" |
| 245 |
.IP """Utility Functions""" 4 |
| 246 |
.IX Item """Utility Functions""" |
| 247 |
.IP """Versioning""" 4 |
| 248 |
.IX Item """Versioning""" |
| 249 |
.IP """Warning and Dieing""" 4 |
| 250 |
.IX Item """Warning and Dieing""" |
| 251 |
.IP """XS""" 4 |
| 252 |
.IX Item """XS""" |
| 253 |
.IP """Undocumented elements""" 4 |
| 254 |
.IX Item """Undocumented elements""" |
| 255 |
.PD |
| 256 |
.PP |
| 257 |
The listing below is alphabetical, case insensitive. |
| 258 |
.SH "AV Handling" |
| 259 |
.IX Header "AV Handling" |
| 260 |
.ie n .IP """AV""" 4 |
| 261 |
.el .IP \f(CWAV\fR 4 |
| 262 |
.IX Item "AV" |
| 263 |
Described in perlguts. |
| 264 |
.ie n .IP """AvALLOC""" 4 |
| 265 |
.el .IP \f(CWAvALLOC\fR 4 |
| 266 |
.IX Item "AvALLOC" |
| 267 |
Described in perlguts. |
| 268 |
.RS 4 |
| 269 |
.Sp |
| 270 |
.Vb 1 |
| 271 |
\& AvALLOC(AV* av) |
| 272 |
.Ve |
| 273 |
.RE |
| 274 |
.RS 4 |
| 275 |
.RE |
| 276 |
.ie n .IP """AvARRAY""" 4 |
| 277 |
.el .IP \f(CWAvARRAY\fR 4 |
| 278 |
.IX Xref "AvARRAY" |
| 279 |
.IX Item "AvARRAY" |
| 280 |
Returns a pointer to the AV's internal SV* array. |
| 281 |
.Sp |
| 282 |
This is useful for doing pointer arithmetic on the array. |
| 283 |
If all you need is to look up an array element, then prefer \f(CW\*(C`av_fetch\*(C'\fR. |
| 284 |
.RS 4 |
| 285 |
.Sp |
| 286 |
.Vb 1 |
| 287 |
\& SV** AvARRAY(AV* av) |
| 288 |
.Ve |
| 289 |
.RE |
| 290 |
.RS 4 |
| 291 |
.RE |
| 292 |
.ie n .IP """av_clear""" 4 |
| 293 |
.el .IP \f(CWav_clear\fR 4 |
| 294 |
.IX Xref "av_clear" |
| 295 |
.IX Item "av_clear" |
| 296 |
Frees all the elements of an array, leaving it empty. |
| 297 |
The XS equivalent of \f(CW\*(C`@array = ()\*(C'\fR. See also "av_undef". |
| 298 |
.Sp |
| 299 |
Note that it is possible that the actions of a destructor called directly |
| 300 |
or indirectly by freeing an element of the array could cause the reference |
| 301 |
count of the array itself to be reduced (e.g. by deleting an entry in the |
| 302 |
symbol table). So it is a possibility that the AV could have been freed |
| 303 |
(or even reallocated) on return from the call unless you hold a reference |
| 304 |
to it. |
| 305 |
.RS 4 |
| 306 |
.Sp |
| 307 |
.Vb 1 |
| 308 |
\& void av_clear(AV *av) |
| 309 |
.Ve |
| 310 |
.RE |
| 311 |
.RS 4 |
| 312 |
.RE |
| 313 |
.ie n .IP """av_count""" 4 |
| 314 |
.el .IP \f(CWav_count\fR 4 |
| 315 |
.IX Xref "av_count" |
| 316 |
.IX Item "av_count" |
| 317 |
Returns the number of elements in the array \f(CW\*(C`av\*(C'\fR. This is the true length of |
| 318 |
the array, including any undefined elements. It is always the same as |
| 319 |
\&\f(CW\*(C`av_top_index(av)\ +\ 1\*(C'\fR. |
| 320 |
.RS 4 |
| 321 |
.Sp |
| 322 |
.Vb 1 |
| 323 |
\& Size_t av_count(AV *av) |
| 324 |
.Ve |
| 325 |
.RE |
| 326 |
.RS 4 |
| 327 |
.RE |
| 328 |
.ie n .IP """av_create_and_push""" 4 |
| 329 |
.el .IP \f(CWav_create_and_push\fR 4 |
| 330 |
.IX Xref "av_create_and_push" |
| 331 |
.IX Item "av_create_and_push" |
| 332 |
Push an SV onto the end of the array, creating the array if necessary. |
| 333 |
A small internal helper function to remove a commonly duplicated idiom. |
| 334 |
.Sp |
| 335 |
NOTE: \f(CW\*(C`av_create_and_push\*(C'\fR must be explicitly called as |
| 336 |
\&\f(CW\*(C`Perl_av_create_and_push\*(C'\fR |
| 337 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 338 |
.RS 4 |
| 339 |
.Sp |
| 340 |
.Vb 2 |
| 341 |
\& void Perl_av_create_and_push(pTHX_ AV ** const avp, |
| 342 |
\& SV * const val) |
| 343 |
.Ve |
| 344 |
.RE |
| 345 |
.RS 4 |
| 346 |
.RE |
| 347 |
.ie n .IP """av_create_and_unshift_one""" 4 |
| 348 |
.el .IP \f(CWav_create_and_unshift_one\fR 4 |
| 349 |
.IX Xref "av_create_and_unshift_one" |
| 350 |
.IX Item "av_create_and_unshift_one" |
| 351 |
Unshifts an SV onto the beginning of the array, creating the array if |
| 352 |
necessary. |
| 353 |
A small internal helper function to remove a commonly duplicated idiom. |
| 354 |
.Sp |
| 355 |
NOTE: \f(CW\*(C`av_create_and_unshift_one\*(C'\fR must be explicitly called as |
| 356 |
\&\f(CW\*(C`Perl_av_create_and_unshift_one\*(C'\fR |
| 357 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 358 |
.RS 4 |
| 359 |
.Sp |
| 360 |
.Vb 2 |
| 361 |
\& SV ** Perl_av_create_and_unshift_one(pTHX_ AV ** const avp, |
| 362 |
\& SV * const val) |
| 363 |
.Ve |
| 364 |
.RE |
| 365 |
.RS 4 |
| 366 |
.RE |
| 367 |
.ie n .IP """av_delete""" 4 |
| 368 |
.el .IP \f(CWav_delete\fR 4 |
| 369 |
.IX Xref "av_delete" |
| 370 |
.IX Item "av_delete" |
| 371 |
Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array, makes the element |
| 372 |
mortal, and returns it. If \f(CW\*(C`flags\*(C'\fR equals \f(CW\*(C`G_DISCARD\*(C'\fR, the element is |
| 373 |
freed and NULL is returned. NULL is also returned if \f(CW\*(C`key\*(C'\fR is out of |
| 374 |
range. |
| 375 |
.Sp |
| 376 |
Perl equivalent: \f(CW\*(C`splice(@myarray,\ $key,\ 1,\ undef)\*(C'\fR (with the |
| 377 |
\&\f(CW\*(C`splice\*(C'\fR in void context if \f(CW\*(C`G_DISCARD\*(C'\fR is present). |
| 378 |
.RS 4 |
| 379 |
.Sp |
| 380 |
.Vb 1 |
| 381 |
\& SV * av_delete(AV *av, SSize_t key, I32 flags) |
| 382 |
.Ve |
| 383 |
.RE |
| 384 |
.RS 4 |
| 385 |
.RE |
| 386 |
.ie n .IP """av_exists""" 4 |
| 387 |
.el .IP \f(CWav_exists\fR 4 |
| 388 |
.IX Xref "av_exists" |
| 389 |
.IX Item "av_exists" |
| 390 |
Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized. |
| 391 |
.Sp |
| 392 |
This relies on the fact that uninitialized array elements are set to |
| 393 |
\&\f(CW\*(C`NULL\*(C'\fR. |
| 394 |
.Sp |
| 395 |
Perl equivalent: \f(CWexists($myarray[$key])\fR. |
| 396 |
.RS 4 |
| 397 |
.Sp |
| 398 |
.Vb 1 |
| 399 |
\& bool av_exists(AV *av, SSize_t key) |
| 400 |
.Ve |
| 401 |
.RE |
| 402 |
.RS 4 |
| 403 |
.RE |
| 404 |
.ie n .IP """av_extend""" 4 |
| 405 |
.el .IP \f(CWav_extend\fR 4 |
| 406 |
.IX Xref "av_extend" |
| 407 |
.IX Item "av_extend" |
| 408 |
Pre-extend an array so that it is capable of storing values at indexes |
| 409 |
\&\f(CW\*(C`0..key\*(C'\fR. Thus \f(CW\*(C`av_extend(av,99)\*(C'\fR guarantees that the array can store 100 |
| 410 |
elements, i.e. that \f(CW\*(C`av_store(av, 0, sv)\*(C'\fR through \f(CW\*(C`av_store(av, 99, sv)\*(C'\fR |
| 411 |
on a plain array will work without any further memory allocation. |
| 412 |
.Sp |
| 413 |
If the av argument is a tied array then will call the \f(CW\*(C`EXTEND\*(C'\fR tied |
| 414 |
array method with an argument of \f(CW\*(C`(key+1)\*(C'\fR. |
| 415 |
.RS 4 |
| 416 |
.Sp |
| 417 |
.Vb 1 |
| 418 |
\& void av_extend(AV *av, SSize_t key) |
| 419 |
.Ve |
| 420 |
.RE |
| 421 |
.RS 4 |
| 422 |
.RE |
| 423 |
.ie n .IP """av_fetch""" 4 |
| 424 |
.el .IP \f(CWav_fetch\fR 4 |
| 425 |
.IX Xref "av_fetch" |
| 426 |
.IX Item "av_fetch" |
| 427 |
Returns the SV at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the |
| 428 |
index. If \f(CW\*(C`lval\*(C'\fR is true, you are guaranteed to get a real SV back (in case |
| 429 |
it wasn't real before), which you can then modify. Check that the return |
| 430 |
value is non-NULL before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR. |
| 431 |
.Sp |
| 432 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for |
| 433 |
more information on how to use this function on tied arrays. |
| 434 |
.Sp |
| 435 |
The rough perl equivalent is \f(CW$myarray[$key]\fR. |
| 436 |
.RS 4 |
| 437 |
.Sp |
| 438 |
.Vb 1 |
| 439 |
\& SV ** av_fetch(AV *av, SSize_t key, I32 lval) |
| 440 |
.Ve |
| 441 |
.RE |
| 442 |
.RS 4 |
| 443 |
.RE |
| 444 |
.ie n .IP """AvFILL""" 4 |
| 445 |
.el .IP \f(CWAvFILL\fR 4 |
| 446 |
.IX Xref "AvFILL" |
| 447 |
.IX Item "AvFILL" |
| 448 |
Same as \f(CW"av_top_index"\fR or \f(CW"av_tindex"\fR. |
| 449 |
.RS 4 |
| 450 |
.Sp |
| 451 |
.Vb 1 |
| 452 |
\& SSize_t AvFILL(AV* av) |
| 453 |
.Ve |
| 454 |
.RE |
| 455 |
.RS 4 |
| 456 |
.RE |
| 457 |
.ie n .IP """av_fill""" 4 |
| 458 |
.el .IP \f(CWav_fill\fR 4 |
| 459 |
.IX Xref "av_fill" |
| 460 |
.IX Item "av_fill" |
| 461 |
Set the highest index in the array to the given number, equivalent to |
| 462 |
Perl's \f(CW\*(C`$#array\ =\ $fill;\*(C'\fR. |
| 463 |
.Sp |
| 464 |
The number of elements in the array will be \f(CW\*(C`fill\ +\ 1\*(C'\fR after |
| 465 |
\&\f(CWav_fill()\fR returns. If the array was previously shorter, then the |
| 466 |
additional elements appended are set to NULL. If the array |
| 467 |
was longer, then the excess elements are freed. \f(CW\*(C`av_fill(av,\ \-1)\*(C'\fR is |
| 468 |
the same as \f(CWav_clear(av)\fR. |
| 469 |
.RS 4 |
| 470 |
.Sp |
| 471 |
.Vb 1 |
| 472 |
\& void av_fill(AV *av, SSize_t fill) |
| 473 |
.Ve |
| 474 |
.RE |
| 475 |
.RS 4 |
| 476 |
.RE |
| 477 |
.ie n .IP """av_len""" 4 |
| 478 |
.el .IP \f(CWav_len\fR 4 |
| 479 |
.IX Xref "av_len" |
| 480 |
.IX Item "av_len" |
| 481 |
Same as "av_top_index". Note that, unlike what the name implies, it returns |
| 482 |
the maximum index in the array. This is unlike "sv_len", which returns what |
| 483 |
you would expect. |
| 484 |
.Sp |
| 485 |
\&\fBTo get the true number of elements in the array, instead use \fR\f(CB"av_count"\fR. |
| 486 |
.RS 4 |
| 487 |
.Sp |
| 488 |
.Vb 1 |
| 489 |
\& SSize_t av_len(AV *av) |
| 490 |
.Ve |
| 491 |
.RE |
| 492 |
.RS 4 |
| 493 |
.RE |
| 494 |
.ie n .IP """av_make""" 4 |
| 495 |
.el .IP \f(CWav_make\fR 4 |
| 496 |
.IX Xref "av_make" |
| 497 |
.IX Item "av_make" |
| 498 |
Creates a new AV and populates it with a list (\f(CW**strp\fR, length \f(CW\*(C`size\*(C'\fR) of |
| 499 |
SVs. A copy is made of each SV, so their refcounts are not changed. The new |
| 500 |
AV will have a reference count of 1. |
| 501 |
.Sp |
| 502 |
Perl equivalent: \f(CW\*(C`my @new_array = ($scalar1, $scalar2, $scalar3...);\*(C'\fR |
| 503 |
.RS 4 |
| 504 |
.Sp |
| 505 |
.Vb 1 |
| 506 |
\& AV * av_make(SSize_t size, SV **strp) |
| 507 |
.Ve |
| 508 |
.RE |
| 509 |
.RS 4 |
| 510 |
.RE |
| 511 |
.ie n .IP """av_pop""" 4 |
| 512 |
.el .IP \f(CWav_pop\fR 4 |
| 513 |
.IX Xref "av_pop" |
| 514 |
.IX Item "av_pop" |
| 515 |
Removes one SV from the end of the array, reducing its size by one and |
| 516 |
returning the SV (transferring control of one reference count) to the |
| 517 |
caller. Returns \f(CW&PL_sv_undef\fR if the array is empty. |
| 518 |
.Sp |
| 519 |
Perl equivalent: \f(CW\*(C`pop(@myarray);\*(C'\fR |
| 520 |
.RS 4 |
| 521 |
.Sp |
| 522 |
.Vb 1 |
| 523 |
\& SV * av_pop(AV *av) |
| 524 |
.Ve |
| 525 |
.RE |
| 526 |
.RS 4 |
| 527 |
.RE |
| 528 |
.ie n .IP """av_push""" 4 |
| 529 |
.el .IP \f(CWav_push\fR 4 |
| 530 |
.IX Xref "av_push" |
| 531 |
.IX Item "av_push" |
| 532 |
Pushes an SV (transferring control of one reference count) onto the end of the |
| 533 |
array. The array will grow automatically to accommodate the addition. |
| 534 |
.Sp |
| 535 |
Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR. |
| 536 |
.RS 4 |
| 537 |
.Sp |
| 538 |
.Vb 1 |
| 539 |
\& void av_push(AV *av, SV *val) |
| 540 |
.Ve |
| 541 |
.RE |
| 542 |
.RS 4 |
| 543 |
.RE |
| 544 |
.ie n .IP """av_push_simple""" 4 |
| 545 |
.el .IP \f(CWav_push_simple\fR 4 |
| 546 |
.IX Xref "av_push_simple" |
| 547 |
.IX Item "av_push_simple" |
| 548 |
This is a cut-down version of av_push that assumes that the array is very |
| 549 |
straightforward \- no magic, not readonly, and AvREAL \- and that \f(CW\*(C`key\*(C'\fR is |
| 550 |
not less than \-1. This function MUST NOT be used in situations where any |
| 551 |
of those assumptions may not hold. |
| 552 |
.Sp |
| 553 |
Pushes an SV (transferring control of one reference count) onto the end of the |
| 554 |
array. The array will grow automatically to accommodate the addition. |
| 555 |
.Sp |
| 556 |
Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR. |
| 557 |
.RS 4 |
| 558 |
.Sp |
| 559 |
.Vb 1 |
| 560 |
\& void av_push_simple(AV *av, SV *val) |
| 561 |
.Ve |
| 562 |
.RE |
| 563 |
.RS 4 |
| 564 |
.RE |
| 565 |
.ie n .IP """av_shift""" 4 |
| 566 |
.el .IP \f(CWav_shift\fR 4 |
| 567 |
.IX Xref "av_shift" |
| 568 |
.IX Item "av_shift" |
| 569 |
Removes one SV from the start of the array, reducing its size by one and |
| 570 |
returning the SV (transferring control of one reference count) to the |
| 571 |
caller. Returns \f(CW&PL_sv_undef\fR if the array is empty. |
| 572 |
.Sp |
| 573 |
Perl equivalent: \f(CW\*(C`shift(@myarray);\*(C'\fR |
| 574 |
.RS 4 |
| 575 |
.Sp |
| 576 |
.Vb 1 |
| 577 |
\& SV * av_shift(AV *av) |
| 578 |
.Ve |
| 579 |
.RE |
| 580 |
.RS 4 |
| 581 |
.RE |
| 582 |
.ie n .IP """av_store""" 4 |
| 583 |
.el .IP \f(CWav_store\fR 4 |
| 584 |
.IX Xref "av_store" |
| 585 |
.IX Item "av_store" |
| 586 |
Stores an SV in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. The |
| 587 |
return value will be \f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not |
| 588 |
need to be actually stored within the array (as in the case of tied |
| 589 |
arrays). Otherwise, it can be dereferenced |
| 590 |
to get the \f(CW\*(C`SV*\*(C'\fR that was stored |
| 591 |
there (= \f(CW\*(C`val\*(C'\fR)). |
| 592 |
.Sp |
| 593 |
Note that the caller is responsible for suitably incrementing the reference |
| 594 |
count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function |
| 595 |
returned \f(CW\*(C`NULL\*(C'\fR. |
| 596 |
.Sp |
| 597 |
Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR. |
| 598 |
.Sp |
| 599 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for |
| 600 |
more information on how to use this function on tied arrays. |
| 601 |
.RS 4 |
| 602 |
.Sp |
| 603 |
.Vb 1 |
| 604 |
\& SV ** av_store(AV *av, SSize_t key, SV *val) |
| 605 |
.Ve |
| 606 |
.RE |
| 607 |
.RS 4 |
| 608 |
.RE |
| 609 |
.ie n .IP """av_tindex""" 4 |
| 610 |
.el .IP \f(CWav_tindex\fR 4 |
| 611 |
.IX Item "av_tindex" |
| 612 |
.PD 0 |
| 613 |
.ie n .IP """av_top_index""" 4 |
| 614 |
.el .IP \f(CWav_top_index\fR 4 |
| 615 |
.IX Xref "av_tindex av_top_index" |
| 616 |
.IX Item "av_top_index" |
| 617 |
.PD |
| 618 |
These behave identically. |
| 619 |
If the array \f(CW\*(C`av\*(C'\fR is empty, these return \-1; otherwise they return the maximum |
| 620 |
value of the indices of all the array elements which are currently defined in |
| 621 |
\&\f(CW\*(C`av\*(C'\fR. |
| 622 |
.Sp |
| 623 |
They process 'get' magic. |
| 624 |
.Sp |
| 625 |
The Perl equivalent for these is \f(CW$#av\fR. |
| 626 |
.Sp |
| 627 |
Use \f(CW"av_count"\fR to get the number of elements in an array. |
| 628 |
.RS 4 |
| 629 |
.Sp |
| 630 |
.Vb 1 |
| 631 |
\& SSize_t av_tindex(AV *av) |
| 632 |
.Ve |
| 633 |
.RE |
| 634 |
.RS 4 |
| 635 |
.RE |
| 636 |
.ie n .IP """av_undef""" 4 |
| 637 |
.el .IP \f(CWav_undef\fR 4 |
| 638 |
.IX Xref "av_undef" |
| 639 |
.IX Item "av_undef" |
| 640 |
Undefines the array. The XS equivalent of \f(CWundef(@array)\fR. |
| 641 |
.Sp |
| 642 |
As well as freeing all the elements of the array (like \f(CWav_clear()\fR), this |
| 643 |
also frees the memory used by the av to store its list of scalars. |
| 644 |
.Sp |
| 645 |
See "av_clear" for a note about the array possibly being invalid on |
| 646 |
return. |
| 647 |
.RS 4 |
| 648 |
.Sp |
| 649 |
.Vb 1 |
| 650 |
\& void av_undef(AV *av) |
| 651 |
.Ve |
| 652 |
.RE |
| 653 |
.RS 4 |
| 654 |
.RE |
| 655 |
.ie n .IP """av_unshift""" 4 |
| 656 |
.el .IP \f(CWav_unshift\fR 4 |
| 657 |
.IX Xref "av_unshift" |
| 658 |
.IX Item "av_unshift" |
| 659 |
Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the |
| 660 |
array. The array will grow automatically to accommodate the addition. |
| 661 |
.Sp |
| 662 |
Perl equivalent: \f(CW\*(C`unshift\ @myarray,\ ((undef)\ x\ $num);\*(C'\fR |
| 663 |
.RS 4 |
| 664 |
.Sp |
| 665 |
.Vb 1 |
| 666 |
\& void av_unshift(AV *av, SSize_t num) |
| 667 |
.Ve |
| 668 |
.RE |
| 669 |
.RS 4 |
| 670 |
.RE |
| 671 |
.ie n .IP """get_av""" 4 |
| 672 |
.el .IP \f(CWget_av\fR 4 |
| 673 |
.IX Xref "get_av" |
| 674 |
.IX Item "get_av" |
| 675 |
Returns the AV of the specified Perl global or package array with the given |
| 676 |
name (so it won't work on lexical variables). \f(CW\*(C`flags\*(C'\fR are passed |
| 677 |
to \f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the |
| 678 |
Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero |
| 679 |
(ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is |
| 680 |
returned. |
| 681 |
.Sp |
| 682 |
Perl equivalent: \f(CW\*(C`@{"$name"}\*(C'\fR. |
| 683 |
.Sp |
| 684 |
NOTE: the \f(CWperl_get_av()\fR form is \fBdeprecated\fR. |
| 685 |
.RS 4 |
| 686 |
.Sp |
| 687 |
.Vb 1 |
| 688 |
\& AV * get_av(const char *name, I32 flags) |
| 689 |
.Ve |
| 690 |
.RE |
| 691 |
.RS 4 |
| 692 |
.RE |
| 693 |
.ie n .IP """newAV""" 4 |
| 694 |
.el .IP \f(CWnewAV\fR 4 |
| 695 |
.IX Item "newAV" |
| 696 |
.PD 0 |
| 697 |
.ie n .IP """newAV_mortal""" 4 |
| 698 |
.el .IP \f(CWnewAV_mortal\fR 4 |
| 699 |
.IX Item "newAV_mortal" |
| 700 |
.ie n .IP """newAV_alloc_x""" 4 |
| 701 |
.el .IP \f(CWnewAV_alloc_x\fR 4 |
| 702 |
.IX Item "newAV_alloc_x" |
| 703 |
.ie n .IP """newAV_alloc_xz""" 4 |
| 704 |
.el .IP \f(CWnewAV_alloc_xz\fR 4 |
| 705 |
.IX Xref "newAV newAV_mortal newAV_alloc_x newAV_alloc_xz" |
| 706 |
.IX Item "newAV_alloc_xz" |
| 707 |
.PD |
| 708 |
These all create a new AV, setting the reference count to 1. If you also know |
| 709 |
the initial elements of the array with, see "\f(CW\*(C`av_make\*(C'\fR". |
| 710 |
.Sp |
| 711 |
As background, an array consists of three things: |
| 712 |
.RS 4 |
| 713 |
.IP 1. 4 |
| 714 |
A data structure containing information about the array as a whole, such as its |
| 715 |
size and reference count. |
| 716 |
.IP 2. 4 |
| 717 |
A C language array of pointers to the individual elements. These are treated |
| 718 |
as pointers to SVs, so all must be castable to SV*. |
| 719 |
.IP 3. 4 |
| 720 |
The individual elements themselves. These could be, for instance, SVs and/or |
| 721 |
AVs and/or HVs, etc. |
| 722 |
.RE |
| 723 |
.RS 4 |
| 724 |
.Sp |
| 725 |
An empty array need only have the first data structure, and all these functions |
| 726 |
create that. They differ in what else they do, as follows: |
| 727 |
.ie n .IP """newAV"" form" 4 |
| 728 |
.el .IP "\f(CWnewAV\fR form" 4 |
| 729 |
.IX Item "newAV form" |
| 730 |
This does nothing beyond creating the whole-array data structure. |
| 731 |
The Perl equivalent is approximately \f(CW\*(C`my\ @array;\*(C'\fR |
| 732 |
.Sp |
| 733 |
This is useful when the minimum size of the array could be zero (perhaps there |
| 734 |
are likely code paths that will entirely skip using it). |
| 735 |
.Sp |
| 736 |
If the array does get used, the pointers data structure will need to be |
| 737 |
allocated at that time. This will end up being done by "av_extend">, |
| 738 |
either explicitly: |
| 739 |
.Sp |
| 740 |
.Vb 1 |
| 741 |
\& av_extend(av, len); |
| 742 |
.Ve |
| 743 |
.Sp |
| 744 |
or implicitly when the first element is stored: |
| 745 |
.Sp |
| 746 |
.Vb 1 |
| 747 |
\& (void)av_store(av, 0, sv); |
| 748 |
.Ve |
| 749 |
.Sp |
| 750 |
Unused array elements are typically initialized by \f(CW\*(C`av_extend\*(C'\fR. |
| 751 |
.ie n .IP """newAV_mortal"" form" 4 |
| 752 |
.el .IP "\f(CWnewAV_mortal\fR form" 4 |
| 753 |
.IX Item "newAV_mortal form" |
| 754 |
This also creates the whole-array data structure, but also mortalises it. |
| 755 |
(That is to say, a reference to the AV is added to the \f(CW\*(C`temps\*(C'\fR stack.) |
| 756 |
.ie n .IP """newAV_alloc_x"" form" 4 |
| 757 |
.el .IP "\f(CWnewAV_alloc_x\fR form" 4 |
| 758 |
.IX Item "newAV_alloc_x form" |
| 759 |
This effectively does a \f(CW\*(C`newAV\*(C'\fR followed by also allocating (uninitialized) |
| 760 |
space for the pointers array. This is used when you know ahead of time the |
| 761 |
likely minimum size of the array. It is more efficient to do this than doing a |
| 762 |
plain \f(CW\*(C`newAV\*(C'\fR followed by an \f(CW\*(C`av_extend\*(C'\fR. |
| 763 |
.Sp |
| 764 |
Of course the array can be extended later should it become necessary. |
| 765 |
.Sp |
| 766 |
\&\f(CW\*(C`size\*(C'\fR must be at least 1. |
| 767 |
.ie n .IP """newAV_alloc_xz"" form" 4 |
| 768 |
.el .IP "\f(CWnewAV_alloc_xz\fR form" 4 |
| 769 |
.IX Item "newAV_alloc_xz form" |
| 770 |
This is \f(CW\*(C`newAV_alloc_x\*(C'\fR, but initializes each pointer in it to NULL. This |
| 771 |
gives added safety to guard against them being read before being set. |
| 772 |
.Sp |
| 773 |
\&\f(CW\*(C`size\*(C'\fR must be at least 1. |
| 774 |
.RE |
| 775 |
.RS 4 |
| 776 |
.Sp |
| 777 |
The following examples all result in an array that can fit four elements |
| 778 |
(indexes 0 .. 3): |
| 779 |
.Sp |
| 780 |
.Vb 2 |
| 781 |
\& AV *av = newAV(); |
| 782 |
\& av_extend(av, 3); |
| 783 |
\& |
| 784 |
\& AV *av = newAV_alloc_x(4); |
| 785 |
\& |
| 786 |
\& AV *av = newAV_alloc_xz(4); |
| 787 |
.Ve |
| 788 |
.Sp |
| 789 |
In contrast, the following examples allocate an array that is only guaranteed |
| 790 |
to fit one element without extending: |
| 791 |
.Sp |
| 792 |
.Vb 2 |
| 793 |
\& AV *av = newAV_alloc_x(1); |
| 794 |
\& AV *av = newAV_alloc_xz(1); |
| 795 |
.Ve |
| 796 |
.Sp |
| 797 |
.Vb 4 |
| 798 |
\& AV * newAV () |
| 799 |
\& AV * newAV_mortal () |
| 800 |
\& AV * newAV_alloc_x (SSize_t size) |
| 801 |
\& AV * newAV_alloc_xz(SSize_t size) |
| 802 |
.Ve |
| 803 |
.RE |
| 804 |
.RS 4 |
| 805 |
.RE |
| 806 |
.ie n .IP """newAVav""" 4 |
| 807 |
.el .IP \f(CWnewAVav\fR 4 |
| 808 |
.IX Xref "newAVav" |
| 809 |
.IX Item "newAVav" |
| 810 |
Creates a new AV and populates it with values copied from an existing AV. The |
| 811 |
new AV will have a reference count of 1, and will contain newly created SVs |
| 812 |
copied from the original SV. The original source will remain unchanged. |
| 813 |
.Sp |
| 814 |
Perl equivalent: \f(CW\*(C`my @new_array = @existing_array;\*(C'\fR |
| 815 |
.RS 4 |
| 816 |
.Sp |
| 817 |
.Vb 1 |
| 818 |
\& AV * newAVav(AV *oav) |
| 819 |
.Ve |
| 820 |
.RE |
| 821 |
.RS 4 |
| 822 |
.RE |
| 823 |
.ie n .IP """newAVhv""" 4 |
| 824 |
.el .IP \f(CWnewAVhv\fR 4 |
| 825 |
.IX Xref "newAVhv" |
| 826 |
.IX Item "newAVhv" |
| 827 |
Creates a new AV and populates it with keys and values copied from an existing |
| 828 |
HV. The new AV will have a reference count of 1, and will contain newly |
| 829 |
created SVs copied from the original HV. The original source will remain |
| 830 |
unchanged. |
| 831 |
.Sp |
| 832 |
Perl equivalent: \f(CW\*(C`my @new_array = %existing_hash;\*(C'\fR |
| 833 |
.RS 4 |
| 834 |
.Sp |
| 835 |
.Vb 1 |
| 836 |
\& AV * newAVhv(HV *ohv) |
| 837 |
.Ve |
| 838 |
.RE |
| 839 |
.RS 4 |
| 840 |
.RE |
| 841 |
.ie n .IP """Nullav""" 4 |
| 842 |
.el .IP \f(CWNullav\fR 4 |
| 843 |
.IX Xref "Nullav" |
| 844 |
.IX Item "Nullav" |
| 845 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullav\*(C'\fR |
| 846 |
from a future release of Perl. Do not use it for |
| 847 |
new code; remove it from existing code. |
| 848 |
.Sp |
| 849 |
Null AV pointer. |
| 850 |
.Sp |
| 851 |
(deprecated \- use \f(CW\*(C`(AV *)NULL\*(C'\fR instead) |
| 852 |
.SH "Callback Functions" |
| 853 |
.IX Xref "G_METHOD G_METHOD_NAMED G_RETHROW G_USEHINTS SAVEf_KEEPOLDELEM SAVEf_SETMAGIC" |
| 854 |
.IX Header "Callback Functions" |
| 855 |
.ie n .IP """call_argv""" 4 |
| 856 |
.el .IP \f(CWcall_argv\fR 4 |
| 857 |
.IX Xref "call_argv" |
| 858 |
.IX Item "call_argv" |
| 859 |
Performs a callback to the specified named and package-scoped Perl subroutine |
| 860 |
with \f(CW\*(C`argv\*(C'\fR (a \f(CW\*(C`NULL\*(C'\fR\-terminated array of strings) as arguments. See |
| 861 |
perlcall. |
| 862 |
.Sp |
| 863 |
Approximate Perl equivalent: \f(CW\*(C`&{"$sub_name"}(@$argv)\*(C'\fR. |
| 864 |
.Sp |
| 865 |
NOTE: the \f(CWperl_call_argv()\fR form is \fBdeprecated\fR. |
| 866 |
.RS 4 |
| 867 |
.Sp |
| 868 |
.Vb 1 |
| 869 |
\& SSize_t call_argv(const char *sub_name, I32 flags, char **argv) |
| 870 |
.Ve |
| 871 |
.RE |
| 872 |
.RS 4 |
| 873 |
.RE |
| 874 |
.ie n .IP """call_method""" 4 |
| 875 |
.el .IP \f(CWcall_method\fR 4 |
| 876 |
.IX Xref "call_method" |
| 877 |
.IX Item "call_method" |
| 878 |
Performs a callback to the specified Perl method. The blessed object must |
| 879 |
be on the stack. See perlcall. |
| 880 |
.Sp |
| 881 |
NOTE: the \f(CWperl_call_method()\fR form is \fBdeprecated\fR. |
| 882 |
.RS 4 |
| 883 |
.Sp |
| 884 |
.Vb 1 |
| 885 |
\& SSize_t call_method(const char *methname, I32 flags) |
| 886 |
.Ve |
| 887 |
.RE |
| 888 |
.RS 4 |
| 889 |
.RE |
| 890 |
.ie n .IP """call_pv""" 4 |
| 891 |
.el .IP \f(CWcall_pv\fR 4 |
| 892 |
.IX Xref "call_pv" |
| 893 |
.IX Item "call_pv" |
| 894 |
Performs a callback to the specified Perl sub. See perlcall. |
| 895 |
.Sp |
| 896 |
NOTE: the \f(CWperl_call_pv()\fR form is \fBdeprecated\fR. |
| 897 |
.RS 4 |
| 898 |
.Sp |
| 899 |
.Vb 1 |
| 900 |
\& SSize_t call_pv(const char *sub_name, I32 flags) |
| 901 |
.Ve |
| 902 |
.RE |
| 903 |
.RS 4 |
| 904 |
.RE |
| 905 |
.ie n .IP """call_sv""" 4 |
| 906 |
.el .IP \f(CWcall_sv\fR 4 |
| 907 |
.IX Xref "call_sv" |
| 908 |
.IX Item "call_sv" |
| 909 |
Performs a callback to the Perl sub specified by the SV. |
| 910 |
.Sp |
| 911 |
If neither the \f(CW\*(C`G_METHOD\*(C'\fR nor \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, the |
| 912 |
SV may be any of a CV, a GV, a reference to a CV, a reference to a GV |
| 913 |
or \f(CWSvPV(sv)\fR will be used as the name of the sub to call. |
| 914 |
.Sp |
| 915 |
If the \f(CW\*(C`G_METHOD\*(C'\fR flag is supplied, the SV may be a reference to a CV or |
| 916 |
\&\f(CWSvPV(sv)\fR will be used as the name of the method to call. |
| 917 |
.Sp |
| 918 |
If the \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, \f(CWSvPV(sv)\fR will be used as |
| 919 |
the name of the method to call. |
| 920 |
.Sp |
| 921 |
Some other values are treated specially for internal use and should |
| 922 |
not be depended on. |
| 923 |
.Sp |
| 924 |
See perlcall. |
| 925 |
.Sp |
| 926 |
NOTE: the \f(CWperl_call_sv()\fR form is \fBdeprecated\fR. |
| 927 |
.RS 4 |
| 928 |
.Sp |
| 929 |
.Vb 1 |
| 930 |
\& SSize_t call_sv(SV *sv, I32 flags) |
| 931 |
.Ve |
| 932 |
.RE |
| 933 |
.RS 4 |
| 934 |
.RE |
| 935 |
.ie n .IP """DESTRUCTORFUNC_NOCONTEXT_t""" 4 |
| 936 |
.el .IP \f(CWDESTRUCTORFUNC_NOCONTEXT_t\fR 4 |
| 937 |
.IX Item "DESTRUCTORFUNC_NOCONTEXT_t" |
| 938 |
Described in perlguts. |
| 939 |
.ie n .IP """DESTRUCTORFUNC_t""" 4 |
| 940 |
.el .IP \f(CWDESTRUCTORFUNC_t\fR 4 |
| 941 |
.IX Item "DESTRUCTORFUNC_t" |
| 942 |
Described in perlguts. |
| 943 |
.ie n .IP """ENTER""" 4 |
| 944 |
.el .IP \f(CWENTER\fR 4 |
| 945 |
.IX Xref "ENTER" |
| 946 |
.IX Item "ENTER" |
| 947 |
Opening bracket on a callback. See \f(CW"LEAVE"\fR and perlcall. |
| 948 |
.RS 4 |
| 949 |
.Sp |
| 950 |
.Vb 1 |
| 951 |
\& ENTER; |
| 952 |
.Ve |
| 953 |
.RE |
| 954 |
.RS 4 |
| 955 |
.RE |
| 956 |
.ie n .IP """ENTER_with_name""" 4 |
| 957 |
.el .IP \f(CWENTER_with_name\fR 4 |
| 958 |
.IX Xref "ENTER_with_name" |
| 959 |
.IX Item "ENTER_with_name" |
| 960 |
Same as \f(CW"ENTER"\fR, but when debugging is enabled it also associates the |
| 961 |
given literal string with the new scope. |
| 962 |
.RS 4 |
| 963 |
.Sp |
| 964 |
.Vb 1 |
| 965 |
\& ENTER_with_name("name"); |
| 966 |
.Ve |
| 967 |
.RE |
| 968 |
.RS 4 |
| 969 |
.RE |
| 970 |
.ie n .IP """eval_pv""" 4 |
| 971 |
.el .IP \f(CWeval_pv\fR 4 |
| 972 |
.IX Xref "eval_pv" |
| 973 |
.IX Item "eval_pv" |
| 974 |
Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string in scalar context and return an SV* result. |
| 975 |
.Sp |
| 976 |
NOTE: the \f(CWperl_eval_pv()\fR form is \fBdeprecated\fR. |
| 977 |
.RS 4 |
| 978 |
.Sp |
| 979 |
.Vb 1 |
| 980 |
\& SV * eval_pv(const char *p, I32 croak_on_error) |
| 981 |
.Ve |
| 982 |
.RE |
| 983 |
.RS 4 |
| 984 |
.RE |
| 985 |
.ie n .IP """eval_sv""" 4 |
| 986 |
.el .IP \f(CWeval_sv\fR 4 |
| 987 |
.IX Xref "eval_sv" |
| 988 |
.IX Item "eval_sv" |
| 989 |
Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the SV. It supports the same flags |
| 990 |
as \f(CW\*(C`call_sv\*(C'\fR, with the obvious exception of \f(CW\*(C`G_EVAL\*(C'\fR. See perlcall. |
| 991 |
.Sp |
| 992 |
The \f(CW\*(C`G_RETHROW\*(C'\fR flag can be used if you only need \fBeval_sv()\fR to |
| 993 |
execute code specified by a string, but not catch any errors. |
| 994 |
.Sp |
| 995 |
By default the code is compiled and executed with the default hints, |
| 996 |
such as strict and features. Set \f(CW\*(C`G_USEHINTS\*(C'\fR in flags to use the |
| 997 |
current hints from \f(CW\*(C`PL_curcop\*(C'\fR. |
| 998 |
.Sp |
| 999 |
NOTE: the \f(CWperl_eval_sv()\fR form is \fBdeprecated\fR. |
| 1000 |
.RS 4 |
| 1001 |
.Sp |
| 1002 |
.Vb 1 |
| 1003 |
\& SSize_t eval_sv(SV *sv, I32 flags) |
| 1004 |
.Ve |
| 1005 |
.RE |
| 1006 |
.RS 4 |
| 1007 |
.RE |
| 1008 |
.ie n .IP """FREETMPS""" 4 |
| 1009 |
.el .IP \f(CWFREETMPS\fR 4 |
| 1010 |
.IX Xref "FREETMPS" |
| 1011 |
.IX Item "FREETMPS" |
| 1012 |
Closing bracket for temporaries on a callback. See \f(CW"SAVETMPS"\fR and |
| 1013 |
perlcall. |
| 1014 |
.RS 4 |
| 1015 |
.Sp |
| 1016 |
.Vb 1 |
| 1017 |
\& FREETMPS; |
| 1018 |
.Ve |
| 1019 |
.RE |
| 1020 |
.RS 4 |
| 1021 |
.RE |
| 1022 |
.ie n .IP """G_DISCARD""" 4 |
| 1023 |
.el .IP \f(CWG_DISCARD\fR 4 |
| 1024 |
.IX Item "G_DISCARD" |
| 1025 |
Described in perlcall. |
| 1026 |
.ie n .IP """G_EVAL""" 4 |
| 1027 |
.el .IP \f(CWG_EVAL\fR 4 |
| 1028 |
.IX Item "G_EVAL" |
| 1029 |
Described in perlcall. |
| 1030 |
.ie n .IP """GIMME""" 4 |
| 1031 |
.el .IP \f(CWGIMME\fR 4 |
| 1032 |
.IX Xref "GIMME" |
| 1033 |
.IX Item "GIMME" |
| 1034 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`GIMME\*(C'\fR |
| 1035 |
from a future release of Perl. Do not use it for |
| 1036 |
new code; remove it from existing code. |
| 1037 |
.Sp |
| 1038 |
A backward-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return |
| 1039 |
\&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR; in a void context, it returns \f(CW\*(C`G_SCALAR\*(C'\fR. |
| 1040 |
Deprecated. Use \f(CW\*(C`GIMME_V\*(C'\fR instead. |
| 1041 |
.RS 4 |
| 1042 |
.Sp |
| 1043 |
.Vb 1 |
| 1044 |
\& U32 GIMME |
| 1045 |
.Ve |
| 1046 |
.RE |
| 1047 |
.RS 4 |
| 1048 |
.RE |
| 1049 |
.ie n .IP """GIMME_V""" 4 |
| 1050 |
.el .IP \f(CWGIMME_V\fR 4 |
| 1051 |
.IX Xref "GIMME_V" |
| 1052 |
.IX Item "GIMME_V" |
| 1053 |
The XSUB-writer's equivalent to Perl's \f(CW\*(C`wantarray\*(C'\fR. Returns \f(CW\*(C`G_VOID\*(C'\fR, |
| 1054 |
\&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR for void, scalar or list context, |
| 1055 |
respectively. See perlcall for a usage example. |
| 1056 |
.RS 4 |
| 1057 |
.Sp |
| 1058 |
.Vb 1 |
| 1059 |
\& U32 GIMME_V |
| 1060 |
.Ve |
| 1061 |
.RE |
| 1062 |
.RS 4 |
| 1063 |
.RE |
| 1064 |
.ie n .IP """G_KEEPERR""" 4 |
| 1065 |
.el .IP \f(CWG_KEEPERR\fR 4 |
| 1066 |
.IX Item "G_KEEPERR" |
| 1067 |
Described in perlcall. |
| 1068 |
.ie n .IP """G_LIST""" 4 |
| 1069 |
.el .IP \f(CWG_LIST\fR 4 |
| 1070 |
.IX Item "G_LIST" |
| 1071 |
Described in perlcall. |
| 1072 |
.ie n .IP """G_NOARGS""" 4 |
| 1073 |
.el .IP \f(CWG_NOARGS\fR 4 |
| 1074 |
.IX Item "G_NOARGS" |
| 1075 |
Described in perlcall. |
| 1076 |
.ie n .IP """G_SCALAR""" 4 |
| 1077 |
.el .IP \f(CWG_SCALAR\fR 4 |
| 1078 |
.IX Item "G_SCALAR" |
| 1079 |
Described in perlcall. |
| 1080 |
.ie n .IP """G_VOID""" 4 |
| 1081 |
.el .IP \f(CWG_VOID\fR 4 |
| 1082 |
.IX Item "G_VOID" |
| 1083 |
Described in perlcall. |
| 1084 |
.ie n .IP """is_lvalue_sub""" 4 |
| 1085 |
.el .IP \f(CWis_lvalue_sub\fR 4 |
| 1086 |
.IX Xref "is_lvalue_sub" |
| 1087 |
.IX Item "is_lvalue_sub" |
| 1088 |
Returns non-zero if the sub calling this function is being called in an lvalue |
| 1089 |
context. Returns 0 otherwise. |
| 1090 |
.RS 4 |
| 1091 |
.Sp |
| 1092 |
.Vb 1 |
| 1093 |
\& I32 is_lvalue_sub() |
| 1094 |
.Ve |
| 1095 |
.RE |
| 1096 |
.RS 4 |
| 1097 |
.RE |
| 1098 |
.ie n .IP """LEAVE""" 4 |
| 1099 |
.el .IP \f(CWLEAVE\fR 4 |
| 1100 |
.IX Xref "LEAVE" |
| 1101 |
.IX Item "LEAVE" |
| 1102 |
Closing bracket on a callback. See \f(CW"ENTER"\fR and perlcall. |
| 1103 |
.RS 4 |
| 1104 |
.Sp |
| 1105 |
.Vb 1 |
| 1106 |
\& LEAVE; |
| 1107 |
.Ve |
| 1108 |
.RE |
| 1109 |
.RS 4 |
| 1110 |
.RE |
| 1111 |
.ie n .IP """LEAVE_with_name""" 4 |
| 1112 |
.el .IP \f(CWLEAVE_with_name\fR 4 |
| 1113 |
.IX Xref "LEAVE_with_name" |
| 1114 |
.IX Item "LEAVE_with_name" |
| 1115 |
Same as \f(CW"LEAVE"\fR, but when debugging is enabled it first checks that the |
| 1116 |
scope has the given name. \f(CW\*(C`name\*(C'\fR must be a literal string. |
| 1117 |
.RS 4 |
| 1118 |
.Sp |
| 1119 |
.Vb 1 |
| 1120 |
\& LEAVE_with_name("name"); |
| 1121 |
.Ve |
| 1122 |
.RE |
| 1123 |
.RS 4 |
| 1124 |
.RE |
| 1125 |
.ie n .IP """MORTALDESTRUCTOR_SV""" 4 |
| 1126 |
.el .IP \f(CWMORTALDESTRUCTOR_SV\fR 4 |
| 1127 |
.IX Item "MORTALDESTRUCTOR_SV" |
| 1128 |
Described in perlguts. |
| 1129 |
.RS 4 |
| 1130 |
.Sp |
| 1131 |
.Vb 1 |
| 1132 |
\& MORTALDESTRUCTOR_SV(SV *coderef, SV *args) |
| 1133 |
.Ve |
| 1134 |
.RE |
| 1135 |
.RS 4 |
| 1136 |
.RE |
| 1137 |
.ie n .IP """mortal_destructor_sv""" 4 |
| 1138 |
.el .IP \f(CWmortal_destructor_sv\fR 4 |
| 1139 |
.IX Xref "mortal_destructor_sv" |
| 1140 |
.IX Item "mortal_destructor_sv" |
| 1141 |
This function arranges for either a Perl code reference, or a C function |
| 1142 |
reference to be called at the \fBend of the current statement\fR. |
| 1143 |
.Sp |
| 1144 |
The \f(CW\*(C`coderef\*(C'\fR argument determines the type of function that will be |
| 1145 |
called. If it is \f(CWSvROK()\fR it is assumed to be a reference to a CV and |
| 1146 |
will arrange for the coderef to be called. If it is not \fBSvROK()\fR then it |
| 1147 |
is assumed to be a \f(CWSvIV()\fR which is \f(CWSvIOK()\fR whose value is a pointer |
| 1148 |
to a C function of type \f(CW\*(C`DESTRUCTORFUNC_t\*(C'\fR created using \f(CWPTR2INT()\fR. |
| 1149 |
Either way the \f(CW\*(C`args\*(C'\fR parameter will be provided to the callback as a |
| 1150 |
parameter, although the rules for doing so differ between the Perl and |
| 1151 |
C mode. Normally this function is only used directly for the Perl case |
| 1152 |
and the wrapper \f(CWmortal_destructor_x()\fR is used for the C function case. |
| 1153 |
.Sp |
| 1154 |
When operating in Perl callback mode the \f(CW\*(C`args\*(C'\fR parameter may be NULL |
| 1155 |
in which case the code reference is called with no arguments, otherwise |
| 1156 |
if it is an AV (SvTYPE(args) == SVt_PVAV) then the contents of the AV |
| 1157 |
will be used as the arguments to the code reference, and if it is any |
| 1158 |
other type then the \f(CW\*(C`args\*(C'\fR SV will be provided as a single argument to |
| 1159 |
the code reference. |
| 1160 |
.Sp |
| 1161 |
When operating in a C callback mode the \f(CW\*(C`args\*(C'\fR parameter will be passed |
| 1162 |
directly to the C function as a \f(CW\*(C`void *\*(C'\fR pointer. No additional |
| 1163 |
processing of the argument will be peformed, and it is the callers |
| 1164 |
responsibility to free the \f(CW\*(C`args\*(C'\fR parameter if necessary. |
| 1165 |
.Sp |
| 1166 |
Be aware that there is a signficant difference in timing between the |
| 1167 |
\&\fIend of the current statement\fR and the \fIend of the current pseudo |
| 1168 |
block\fR. If you are looking for a mechanism to trigger a function at the |
| 1169 |
end of the \fBcurrent pseudo block\fR you should look at |
| 1170 |
"\f(CW\*(C`SAVEDESTRUCTOR_X\*(C'\fR" in perlapi instead of this function. |
| 1171 |
.RS 4 |
| 1172 |
.Sp |
| 1173 |
.Vb 1 |
| 1174 |
\& void mortal_destructor_sv(SV *coderef, SV *args) |
| 1175 |
.Ve |
| 1176 |
.RE |
| 1177 |
.RS 4 |
| 1178 |
.RE |
| 1179 |
.ie n .IP """MORTALSVFUNC_X""" 4 |
| 1180 |
.el .IP \f(CWMORTALSVFUNC_X\fR 4 |
| 1181 |
.IX Item "MORTALSVFUNC_X" |
| 1182 |
Described in perlguts. |
| 1183 |
.RS 4 |
| 1184 |
.Sp |
| 1185 |
.Vb 1 |
| 1186 |
\& MORTALSVFUNC_X(SVFUNC_t f, SV *sv) |
| 1187 |
.Ve |
| 1188 |
.RE |
| 1189 |
.RS 4 |
| 1190 |
.RE |
| 1191 |
.ie n .IP """PL_errgv""" 4 |
| 1192 |
.el .IP \f(CWPL_errgv\fR 4 |
| 1193 |
.IX Item "PL_errgv" |
| 1194 |
Described in perlcall. |
| 1195 |
.ie n .IP """save_aelem""" 4 |
| 1196 |
.el .IP \f(CWsave_aelem\fR 4 |
| 1197 |
.IX Item "save_aelem" |
| 1198 |
.PD 0 |
| 1199 |
.ie n .IP """save_aelem_flags""" 4 |
| 1200 |
.el .IP \f(CWsave_aelem_flags\fR 4 |
| 1201 |
.IX Xref "save_aelem save_aelem_flags" |
| 1202 |
.IX Item "save_aelem_flags" |
| 1203 |
.PD |
| 1204 |
These each arrange for the value of the array element \f(CW\*(C`av[idx]\*(C'\fR to be restored |
| 1205 |
at the end of the enclosing \fIpseudo-block\fR. |
| 1206 |
.Sp |
| 1207 |
In \f(CW\*(C`save_aelem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR |
| 1208 |
scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR, |
| 1209 |
and any 'set' magic will be processed. |
| 1210 |
.Sp |
| 1211 |
In \f(CW\*(C`save_aelem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes |
| 1212 |
the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched. |
| 1213 |
If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a |
| 1214 |
new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original |
| 1215 |
\&\f(CW**sptr\fR. Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR |
| 1216 |
is set in in \f(CW\*(C`flags\*(C'\fR. |
| 1217 |
.RS 4 |
| 1218 |
.Sp |
| 1219 |
.Vb 3 |
| 1220 |
\& void save_aelem (AV *av, SSize_t idx, SV **sptr) |
| 1221 |
\& void save_aelem_flags(AV *av, SSize_t idx, SV **sptr, |
| 1222 |
\& const U32 flags) |
| 1223 |
.Ve |
| 1224 |
.RE |
| 1225 |
.RS 4 |
| 1226 |
.RE |
| 1227 |
.ie n .IP """save_aptr""" 4 |
| 1228 |
.el .IP \f(CWsave_aptr\fR 4 |
| 1229 |
.IX Item "save_aptr" |
| 1230 |
Described in perlguts. |
| 1231 |
.RS 4 |
| 1232 |
.Sp |
| 1233 |
.Vb 1 |
| 1234 |
\& void save_aptr(AV **aptr) |
| 1235 |
.Ve |
| 1236 |
.RE |
| 1237 |
.RS 4 |
| 1238 |
.RE |
| 1239 |
.ie n .IP """save_ary""" 4 |
| 1240 |
.el .IP \f(CWsave_ary\fR 4 |
| 1241 |
.IX Item "save_ary" |
| 1242 |
Described in perlguts. |
| 1243 |
.RS 4 |
| 1244 |
.Sp |
| 1245 |
.Vb 1 |
| 1246 |
\& AV * save_ary(GV *gv) |
| 1247 |
.Ve |
| 1248 |
.RE |
| 1249 |
.RS 4 |
| 1250 |
.RE |
| 1251 |
.ie n .IP """SAVEBOOL""" 4 |
| 1252 |
.el .IP \f(CWSAVEBOOL\fR 4 |
| 1253 |
.IX Item "SAVEBOOL" |
| 1254 |
Described in perlguts. |
| 1255 |
.RS 4 |
| 1256 |
.Sp |
| 1257 |
.Vb 1 |
| 1258 |
\& SAVEBOOL(bool i) |
| 1259 |
.Ve |
| 1260 |
.RE |
| 1261 |
.RS 4 |
| 1262 |
.RE |
| 1263 |
.ie n .IP """SAVEDELETE""" 4 |
| 1264 |
.el .IP \f(CWSAVEDELETE\fR 4 |
| 1265 |
.IX Item "SAVEDELETE" |
| 1266 |
Described in perlguts. |
| 1267 |
.RS 4 |
| 1268 |
.Sp |
| 1269 |
.Vb 1 |
| 1270 |
\& SAVEDELETE(HV * hv, char * key, I32 length) |
| 1271 |
.Ve |
| 1272 |
.RE |
| 1273 |
.RS 4 |
| 1274 |
.RE |
| 1275 |
.ie n .IP """SAVEDESTRUCTOR""" 4 |
| 1276 |
.el .IP \f(CWSAVEDESTRUCTOR\fR 4 |
| 1277 |
.IX Item "SAVEDESTRUCTOR" |
| 1278 |
Described in perlguts. |
| 1279 |
.RS 4 |
| 1280 |
.Sp |
| 1281 |
.Vb 1 |
| 1282 |
\& SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p) |
| 1283 |
.Ve |
| 1284 |
.RE |
| 1285 |
.RS 4 |
| 1286 |
.RE |
| 1287 |
.ie n .IP """SAVEDESTRUCTOR_X""" 4 |
| 1288 |
.el .IP \f(CWSAVEDESTRUCTOR_X\fR 4 |
| 1289 |
.IX Item "SAVEDESTRUCTOR_X" |
| 1290 |
Described in perlguts. |
| 1291 |
.RS 4 |
| 1292 |
.Sp |
| 1293 |
.Vb 1 |
| 1294 |
\& SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p) |
| 1295 |
.Ve |
| 1296 |
.RE |
| 1297 |
.RS 4 |
| 1298 |
.RE |
| 1299 |
.ie n .IP """SAVEFREEOP""" 4 |
| 1300 |
.el .IP \f(CWSAVEFREEOP\fR 4 |
| 1301 |
.IX Item "SAVEFREEOP" |
| 1302 |
Described in perlguts. |
| 1303 |
.RS 4 |
| 1304 |
.Sp |
| 1305 |
.Vb 1 |
| 1306 |
\& SAVEFREEOP(OP *op) |
| 1307 |
.Ve |
| 1308 |
.RE |
| 1309 |
.RS 4 |
| 1310 |
.RE |
| 1311 |
.ie n .IP """SAVEFREEPV""" 4 |
| 1312 |
.el .IP \f(CWSAVEFREEPV\fR 4 |
| 1313 |
.IX Item "SAVEFREEPV" |
| 1314 |
Described in perlguts. |
| 1315 |
.RS 4 |
| 1316 |
.Sp |
| 1317 |
.Vb 1 |
| 1318 |
\& SAVEFREEPV(char *pv) |
| 1319 |
.Ve |
| 1320 |
.RE |
| 1321 |
.RS 4 |
| 1322 |
.RE |
| 1323 |
.ie n .IP """SAVEFREERCPV""" 4 |
| 1324 |
.el .IP \f(CWSAVEFREERCPV\fR 4 |
| 1325 |
.IX Item "SAVEFREERCPV" |
| 1326 |
Described in perlguts. |
| 1327 |
.RS 4 |
| 1328 |
.Sp |
| 1329 |
.Vb 1 |
| 1330 |
\& SAVEFREERCPV(char *pv) |
| 1331 |
.Ve |
| 1332 |
.RE |
| 1333 |
.RS 4 |
| 1334 |
.RE |
| 1335 |
.ie n .IP """SAVEFREESV""" 4 |
| 1336 |
.el .IP \f(CWSAVEFREESV\fR 4 |
| 1337 |
.IX Item "SAVEFREESV" |
| 1338 |
Described in perlguts. |
| 1339 |
.RS 4 |
| 1340 |
.Sp |
| 1341 |
.Vb 1 |
| 1342 |
\& SAVEFREESV(SV* sv) |
| 1343 |
.Ve |
| 1344 |
.RE |
| 1345 |
.RS 4 |
| 1346 |
.RE |
| 1347 |
.ie n .IP """SAVEGENERICSV""" 4 |
| 1348 |
.el .IP \f(CWSAVEGENERICSV\fR 4 |
| 1349 |
.IX Item "SAVEGENERICSV" |
| 1350 |
Described in perlguts. |
| 1351 |
.RS 4 |
| 1352 |
.Sp |
| 1353 |
.Vb 1 |
| 1354 |
\& SAVEGENERICSV(char **psv) |
| 1355 |
.Ve |
| 1356 |
.RE |
| 1357 |
.RS 4 |
| 1358 |
.RE |
| 1359 |
.ie n .IP """save_hash""" 4 |
| 1360 |
.el .IP \f(CWsave_hash\fR 4 |
| 1361 |
.IX Item "save_hash" |
| 1362 |
Described in perlguts. |
| 1363 |
.RS 4 |
| 1364 |
.Sp |
| 1365 |
.Vb 1 |
| 1366 |
\& HV * save_hash(GV *gv) |
| 1367 |
.Ve |
| 1368 |
.RE |
| 1369 |
.RS 4 |
| 1370 |
.RE |
| 1371 |
.ie n .IP """save_helem""" 4 |
| 1372 |
.el .IP \f(CWsave_helem\fR 4 |
| 1373 |
.IX Item "save_helem" |
| 1374 |
.PD 0 |
| 1375 |
.ie n .IP """save_helem_flags""" 4 |
| 1376 |
.el .IP \f(CWsave_helem_flags\fR 4 |
| 1377 |
.IX Xref "save_helem save_helem_flags" |
| 1378 |
.IX Item "save_helem_flags" |
| 1379 |
.PD |
| 1380 |
These each arrange for the value of the hash element (in Perlish terms) |
| 1381 |
\&\f(CW\*(C`$hv{key}]\*(C'\fR to be restored at the end of the enclosing \fIpseudo-block\fR. |
| 1382 |
.Sp |
| 1383 |
In \f(CW\*(C`save_helem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR |
| 1384 |
scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR, |
| 1385 |
and any 'set' magic will be processed. |
| 1386 |
.Sp |
| 1387 |
In \f(CW\*(C`save_helem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes |
| 1388 |
the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched. |
| 1389 |
If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a |
| 1390 |
new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original |
| 1391 |
\&\f(CW**sptr\fR. Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR |
| 1392 |
is set in in \f(CW\*(C`flags\*(C'\fR. |
| 1393 |
.RS 4 |
| 1394 |
.Sp |
| 1395 |
.Vb 3 |
| 1396 |
\& void save_helem (HV *hv, SV *key, SV **sptr) |
| 1397 |
\& void save_helem_flags(HV *hv, SV *key, SV **sptr, |
| 1398 |
\& const U32 flags) |
| 1399 |
.Ve |
| 1400 |
.RE |
| 1401 |
.RS 4 |
| 1402 |
.RE |
| 1403 |
.ie n .IP """save_hptr""" 4 |
| 1404 |
.el .IP \f(CWsave_hptr\fR 4 |
| 1405 |
.IX Item "save_hptr" |
| 1406 |
Described in perlguts. |
| 1407 |
.RS 4 |
| 1408 |
.Sp |
| 1409 |
.Vb 1 |
| 1410 |
\& void save_hptr(HV **hptr) |
| 1411 |
.Ve |
| 1412 |
.RE |
| 1413 |
.RS 4 |
| 1414 |
.RE |
| 1415 |
.ie n .IP """SAVEINT""" 4 |
| 1416 |
.el .IP \f(CWSAVEINT\fR 4 |
| 1417 |
.IX Item "SAVEINT" |
| 1418 |
Described in perlguts. |
| 1419 |
.RS 4 |
| 1420 |
.Sp |
| 1421 |
.Vb 1 |
| 1422 |
\& SAVEINT(int i) |
| 1423 |
.Ve |
| 1424 |
.RE |
| 1425 |
.RS 4 |
| 1426 |
.RE |
| 1427 |
.ie n .IP """save_item""" 4 |
| 1428 |
.el .IP \f(CWsave_item\fR 4 |
| 1429 |
.IX Item "save_item" |
| 1430 |
Described in perlguts. |
| 1431 |
.RS 4 |
| 1432 |
.Sp |
| 1433 |
.Vb 1 |
| 1434 |
\& void save_item(SV *item) |
| 1435 |
.Ve |
| 1436 |
.RE |
| 1437 |
.RS 4 |
| 1438 |
.RE |
| 1439 |
.ie n .IP """SAVEIV""" 4 |
| 1440 |
.el .IP \f(CWSAVEIV\fR 4 |
| 1441 |
.IX Item "SAVEIV" |
| 1442 |
Described in perlguts. |
| 1443 |
.RS 4 |
| 1444 |
.Sp |
| 1445 |
.Vb 1 |
| 1446 |
\& SAVEIV(IV i) |
| 1447 |
.Ve |
| 1448 |
.RE |
| 1449 |
.RS 4 |
| 1450 |
.RE |
| 1451 |
.ie n .IP """SAVEI8""" 4 |
| 1452 |
.el .IP \f(CWSAVEI8\fR 4 |
| 1453 |
.IX Item "SAVEI8" |
| 1454 |
Described in perlguts. |
| 1455 |
.RS 4 |
| 1456 |
.Sp |
| 1457 |
.Vb 1 |
| 1458 |
\& SAVEI8(I8 i) |
| 1459 |
.Ve |
| 1460 |
.RE |
| 1461 |
.RS 4 |
| 1462 |
.RE |
| 1463 |
.ie n .IP """SAVEI16""" 4 |
| 1464 |
.el .IP \f(CWSAVEI16\fR 4 |
| 1465 |
.IX Item "SAVEI16" |
| 1466 |
Described in perlguts. |
| 1467 |
.RS 4 |
| 1468 |
.Sp |
| 1469 |
.Vb 1 |
| 1470 |
\& SAVEI16(I16 i) |
| 1471 |
.Ve |
| 1472 |
.RE |
| 1473 |
.RS 4 |
| 1474 |
.RE |
| 1475 |
.ie n .IP """SAVEI32""" 4 |
| 1476 |
.el .IP \f(CWSAVEI32\fR 4 |
| 1477 |
.IX Item "SAVEI32" |
| 1478 |
Described in perlguts. |
| 1479 |
.RS 4 |
| 1480 |
.Sp |
| 1481 |
.Vb 1 |
| 1482 |
\& SAVEI32(I32 i) |
| 1483 |
.Ve |
| 1484 |
.RE |
| 1485 |
.RS 4 |
| 1486 |
.RE |
| 1487 |
.ie n .IP """SAVELONG""" 4 |
| 1488 |
.el .IP \f(CWSAVELONG\fR 4 |
| 1489 |
.IX Item "SAVELONG" |
| 1490 |
Described in perlguts. |
| 1491 |
.RS 4 |
| 1492 |
.Sp |
| 1493 |
.Vb 1 |
| 1494 |
\& SAVELONG(long i) |
| 1495 |
.Ve |
| 1496 |
.RE |
| 1497 |
.RS 4 |
| 1498 |
.RE |
| 1499 |
.ie n .IP """SAVEMORTALIZESV""" 4 |
| 1500 |
.el .IP \f(CWSAVEMORTALIZESV\fR 4 |
| 1501 |
.IX Item "SAVEMORTALIZESV" |
| 1502 |
Described in perlguts. |
| 1503 |
.RS 4 |
| 1504 |
.Sp |
| 1505 |
.Vb 1 |
| 1506 |
\& SAVEMORTALIZESV(SV* sv) |
| 1507 |
.Ve |
| 1508 |
.RE |
| 1509 |
.RS 4 |
| 1510 |
.RE |
| 1511 |
.ie n .IP """SAVEPPTR""" 4 |
| 1512 |
.el .IP \f(CWSAVEPPTR\fR 4 |
| 1513 |
.IX Item "SAVEPPTR" |
| 1514 |
Described in perlguts. |
| 1515 |
.RS 4 |
| 1516 |
.Sp |
| 1517 |
.Vb 1 |
| 1518 |
\& SAVEPPTR(char * p) |
| 1519 |
.Ve |
| 1520 |
.RE |
| 1521 |
.RS 4 |
| 1522 |
.RE |
| 1523 |
.ie n .IP """SAVERCPV""" 4 |
| 1524 |
.el .IP \f(CWSAVERCPV\fR 4 |
| 1525 |
.IX Item "SAVERCPV" |
| 1526 |
Described in perlguts. |
| 1527 |
.RS 4 |
| 1528 |
.Sp |
| 1529 |
.Vb 1 |
| 1530 |
\& SAVERCPV(char *pv) |
| 1531 |
.Ve |
| 1532 |
.RE |
| 1533 |
.RS 4 |
| 1534 |
.RE |
| 1535 |
.ie n .IP """save_scalar""" 4 |
| 1536 |
.el .IP \f(CWsave_scalar\fR 4 |
| 1537 |
.IX Item "save_scalar" |
| 1538 |
Described in perlguts. |
| 1539 |
.RS 4 |
| 1540 |
.Sp |
| 1541 |
.Vb 1 |
| 1542 |
\& SV * save_scalar(GV *gv) |
| 1543 |
.Ve |
| 1544 |
.RE |
| 1545 |
.RS 4 |
| 1546 |
.RE |
| 1547 |
.ie n .IP """SAVESPTR""" 4 |
| 1548 |
.el .IP \f(CWSAVESPTR\fR 4 |
| 1549 |
.IX Item "SAVESPTR" |
| 1550 |
Described in perlguts. |
| 1551 |
.RS 4 |
| 1552 |
.Sp |
| 1553 |
.Vb 1 |
| 1554 |
\& SAVESPTR(SV * s) |
| 1555 |
.Ve |
| 1556 |
.RE |
| 1557 |
.RS 4 |
| 1558 |
.RE |
| 1559 |
.ie n .IP """SAVESTACK_POS""" 4 |
| 1560 |
.el .IP \f(CWSAVESTACK_POS\fR 4 |
| 1561 |
.IX Item "SAVESTACK_POS" |
| 1562 |
Described in perlguts. |
| 1563 |
.RS 4 |
| 1564 |
.Sp |
| 1565 |
.Vb 1 |
| 1566 |
\& SAVESTACK_POS() |
| 1567 |
.Ve |
| 1568 |
.RE |
| 1569 |
.RS 4 |
| 1570 |
.RE |
| 1571 |
.ie n .IP """SAVESTRLEN""" 4 |
| 1572 |
.el .IP \f(CWSAVESTRLEN\fR 4 |
| 1573 |
.IX Item "SAVESTRLEN" |
| 1574 |
Described in perlguts. |
| 1575 |
.RS 4 |
| 1576 |
.Sp |
| 1577 |
.Vb 1 |
| 1578 |
\& SAVESTRLEN(STRLEN i) |
| 1579 |
.Ve |
| 1580 |
.RE |
| 1581 |
.RS 4 |
| 1582 |
.RE |
| 1583 |
.ie n .IP """save_svref""" 4 |
| 1584 |
.el .IP \f(CWsave_svref\fR 4 |
| 1585 |
.IX Item "save_svref" |
| 1586 |
Described in perlguts. |
| 1587 |
.RS 4 |
| 1588 |
.Sp |
| 1589 |
.Vb 1 |
| 1590 |
\& SV * save_svref(SV **sptr) |
| 1591 |
.Ve |
| 1592 |
.RE |
| 1593 |
.RS 4 |
| 1594 |
.RE |
| 1595 |
.ie n .IP """SAVETMPS""" 4 |
| 1596 |
.el .IP \f(CWSAVETMPS\fR 4 |
| 1597 |
.IX Xref "SAVETMPS" |
| 1598 |
.IX Item "SAVETMPS" |
| 1599 |
Opening bracket for temporaries on a callback. See \f(CW"FREETMPS"\fR and |
| 1600 |
perlcall. |
| 1601 |
.RS 4 |
| 1602 |
.Sp |
| 1603 |
.Vb 1 |
| 1604 |
\& SAVETMPS; |
| 1605 |
.Ve |
| 1606 |
.RE |
| 1607 |
.RS 4 |
| 1608 |
.RE |
| 1609 |
.SH Casting |
| 1610 |
.IX Header "Casting" |
| 1611 |
.ie n .IP """Atof""" 4 |
| 1612 |
.el .IP \f(CWAtof\fR 4 |
| 1613 |
.IX Xref "Atof" |
| 1614 |
.IX Item "Atof" |
| 1615 |
This is a synonym for "\f(CW\*(C`my_atof\*(C'\fR". |
| 1616 |
.RS 4 |
| 1617 |
.Sp |
| 1618 |
.Vb 1 |
| 1619 |
\& NV Atof(NN const char * const s) |
| 1620 |
.Ve |
| 1621 |
.RE |
| 1622 |
.RS 4 |
| 1623 |
.RE |
| 1624 |
.ie n .IP """cBOOL""" 4 |
| 1625 |
.el .IP \f(CWcBOOL\fR 4 |
| 1626 |
.IX Xref "cBOOL" |
| 1627 |
.IX Item "cBOOL" |
| 1628 |
Cast-to-bool. When Perl was able to be compiled on pre\-C99 compilers, a |
| 1629 |
\&\f(CW\*(C`(bool)\*(C'\fR cast didn't necessarily do the right thing, so this macro was |
| 1630 |
created (and made somewhat complicated to work around bugs in old |
| 1631 |
compilers). Now, many years later, and C99 is used, this is no longer |
| 1632 |
required, but is kept for backwards compatibility. |
| 1633 |
.RS 4 |
| 1634 |
.Sp |
| 1635 |
.Vb 1 |
| 1636 |
\& bool cBOOL(bool expr) |
| 1637 |
.Ve |
| 1638 |
.RE |
| 1639 |
.RS 4 |
| 1640 |
.RE |
| 1641 |
.ie n .IP """INT2PTR""" 4 |
| 1642 |
.el .IP \f(CWINT2PTR\fR 4 |
| 1643 |
.IX Item "INT2PTR" |
| 1644 |
Described in perlguts. |
| 1645 |
.RS 4 |
| 1646 |
.Sp |
| 1647 |
.Vb 1 |
| 1648 |
\& type INT2PTR(type, int value) |
| 1649 |
.Ve |
| 1650 |
.RE |
| 1651 |
.RS 4 |
| 1652 |
.RE |
| 1653 |
.ie n .IP """I_V""" 4 |
| 1654 |
.el .IP \f(CWI_V\fR 4 |
| 1655 |
.IX Xref "I_V" |
| 1656 |
.IX Item "I_V" |
| 1657 |
Cast an NV to IV while avoiding undefined C behavior |
| 1658 |
.RS 4 |
| 1659 |
.Sp |
| 1660 |
.Vb 1 |
| 1661 |
\& IV I_V(NV what) |
| 1662 |
.Ve |
| 1663 |
.RE |
| 1664 |
.RS 4 |
| 1665 |
.RE |
| 1666 |
.ie n .IP """I_32""" 4 |
| 1667 |
.el .IP \f(CWI_32\fR 4 |
| 1668 |
.IX Xref "I_32" |
| 1669 |
.IX Item "I_32" |
| 1670 |
Cast an NV to I32 while avoiding undefined C behavior |
| 1671 |
.RS 4 |
| 1672 |
.Sp |
| 1673 |
.Vb 1 |
| 1674 |
\& I32 I_32(NV what) |
| 1675 |
.Ve |
| 1676 |
.RE |
| 1677 |
.RS 4 |
| 1678 |
.RE |
| 1679 |
.ie n .IP """PTR2IV""" 4 |
| 1680 |
.el .IP \f(CWPTR2IV\fR 4 |
| 1681 |
.IX Item "PTR2IV" |
| 1682 |
Described in perlguts. |
| 1683 |
.RS 4 |
| 1684 |
.Sp |
| 1685 |
.Vb 1 |
| 1686 |
\& IV PTR2IV(void * ptr) |
| 1687 |
.Ve |
| 1688 |
.RE |
| 1689 |
.RS 4 |
| 1690 |
.RE |
| 1691 |
.ie n .IP """PTR2nat""" 4 |
| 1692 |
.el .IP \f(CWPTR2nat\fR 4 |
| 1693 |
.IX Item "PTR2nat" |
| 1694 |
Described in perlguts. |
| 1695 |
.RS 4 |
| 1696 |
.Sp |
| 1697 |
.Vb 1 |
| 1698 |
\& IV PTR2nat(void *) |
| 1699 |
.Ve |
| 1700 |
.RE |
| 1701 |
.RS 4 |
| 1702 |
.RE |
| 1703 |
.ie n .IP """PTR2NV""" 4 |
| 1704 |
.el .IP \f(CWPTR2NV\fR 4 |
| 1705 |
.IX Item "PTR2NV" |
| 1706 |
Described in perlguts. |
| 1707 |
.RS 4 |
| 1708 |
.Sp |
| 1709 |
.Vb 1 |
| 1710 |
\& NV PTR2NV(void * ptr) |
| 1711 |
.Ve |
| 1712 |
.RE |
| 1713 |
.RS 4 |
| 1714 |
.RE |
| 1715 |
.ie n .IP """PTR2ul""" 4 |
| 1716 |
.el .IP \f(CWPTR2ul\fR 4 |
| 1717 |
.IX Item "PTR2ul" |
| 1718 |
Described in perlguts. |
| 1719 |
.RS 4 |
| 1720 |
.Sp |
| 1721 |
.Vb 1 |
| 1722 |
\& unsigned long PTR2ul(void *) |
| 1723 |
.Ve |
| 1724 |
.RE |
| 1725 |
.RS 4 |
| 1726 |
.RE |
| 1727 |
.ie n .IP """PTR2UV""" 4 |
| 1728 |
.el .IP \f(CWPTR2UV\fR 4 |
| 1729 |
.IX Item "PTR2UV" |
| 1730 |
Described in perlguts. |
| 1731 |
.RS 4 |
| 1732 |
.Sp |
| 1733 |
.Vb 1 |
| 1734 |
\& UV PTR2UV(void * ptr) |
| 1735 |
.Ve |
| 1736 |
.RE |
| 1737 |
.RS 4 |
| 1738 |
.RE |
| 1739 |
.ie n .IP """PTRV""" 4 |
| 1740 |
.el .IP \f(CWPTRV\fR 4 |
| 1741 |
.IX Item "PTRV" |
| 1742 |
Described in perlguts. |
| 1743 |
.ie n .IP """U_V""" 4 |
| 1744 |
.el .IP \f(CWU_V\fR 4 |
| 1745 |
.IX Xref "U_V" |
| 1746 |
.IX Item "U_V" |
| 1747 |
Cast an NV to UV while avoiding undefined C behavior |
| 1748 |
.RS 4 |
| 1749 |
.Sp |
| 1750 |
.Vb 1 |
| 1751 |
\& UV U_V(NV what) |
| 1752 |
.Ve |
| 1753 |
.RE |
| 1754 |
.RS 4 |
| 1755 |
.RE |
| 1756 |
.ie n .IP """U_32""" 4 |
| 1757 |
.el .IP \f(CWU_32\fR 4 |
| 1758 |
.IX Xref "U_32" |
| 1759 |
.IX Item "U_32" |
| 1760 |
Cast an NV to U32 while avoiding undefined C behavior |
| 1761 |
.RS 4 |
| 1762 |
.Sp |
| 1763 |
.Vb 1 |
| 1764 |
\& U32 U_32(NV what) |
| 1765 |
.Ve |
| 1766 |
.RE |
| 1767 |
.RS 4 |
| 1768 |
.RE |
| 1769 |
.SH "Character case changing" |
| 1770 |
.IX Header "Character case changing" |
| 1771 |
Perl uses "full" Unicode case mappings. This means that converting a single |
| 1772 |
character to another case may result in a sequence of more than one character. |
| 1773 |
For example, the uppercase of \f(CW\*(C`ß\*(C'\fR (LATIN SMALL LETTER SHARP S) is the two |
| 1774 |
character sequence \f(CW\*(C`SS\*(C'\fR. This presents some complications The lowercase of |
| 1775 |
all characters in the range 0..255 is a single character, and thus |
| 1776 |
\&\f(CW"toLOWER_L1"\fR is furnished. But, \f(CW\*(C`toUPPER_L1\*(C'\fR can't exist, as it couldn't |
| 1777 |
return a valid result for all legal inputs. Instead \f(CW"toUPPER_uvchr"\fR has |
| 1778 |
an API that does allow every possible legal result to be returned.) Likewise |
| 1779 |
no other function that is crippled by not being able to give the correct |
| 1780 |
results for the full range of possible inputs has been implemented here. |
| 1781 |
.ie n .IP """toFOLD""" 4 |
| 1782 |
.el .IP \f(CWtoFOLD\fR 4 |
| 1783 |
.IX Item "toFOLD" |
| 1784 |
.PD 0 |
| 1785 |
.ie n .IP """toFOLD_A""" 4 |
| 1786 |
.el .IP \f(CWtoFOLD_A\fR 4 |
| 1787 |
.IX Item "toFOLD_A" |
| 1788 |
.ie n .IP """toFOLD_utf8""" 4 |
| 1789 |
.el .IP \f(CWtoFOLD_utf8\fR 4 |
| 1790 |
.IX Item "toFOLD_utf8" |
| 1791 |
.ie n .IP """toFOLD_utf8_safe""" 4 |
| 1792 |
.el .IP \f(CWtoFOLD_utf8_safe\fR 4 |
| 1793 |
.IX Item "toFOLD_utf8_safe" |
| 1794 |
.ie n .IP """toFOLD_uvchr""" 4 |
| 1795 |
.el .IP \f(CWtoFOLD_uvchr\fR 4 |
| 1796 |
.IX Xref "toFOLD toFOLD_A toFOLD_utf8 toFOLD_utf8_safe toFOLD_uvchr" |
| 1797 |
.IX Item "toFOLD_uvchr" |
| 1798 |
.PD |
| 1799 |
These all return the foldcase of a character. "foldcase" is an internal case |
| 1800 |
for \f(CW\*(C`/i\*(C'\fR pattern matching. If the foldcase of character A and the foldcase of |
| 1801 |
character B are the same, they match caselessly; otherwise they don't. |
| 1802 |
.Sp |
| 1803 |
The differences in the forms are what domain they operate on, and whether the |
| 1804 |
input is specified as a code point (those forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a |
| 1805 |
UTF\-8 string (the others). In the latter case, the code point to use is the |
| 1806 |
first one in the buffer of UTF\-8 encoded code points, delineated by the |
| 1807 |
arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR. |
| 1808 |
.Sp |
| 1809 |
\&\f(CW\*(C`toFOLD\*(C'\fR and \f(CW\*(C`toFOLD_A\*(C'\fR are synonyms of each other. They return the |
| 1810 |
foldcase of any ASCII-range code point. In this range, the foldcase is |
| 1811 |
identical to the lowercase. All other inputs are returned unchanged. Since |
| 1812 |
these are macros, the input type may be any integral one, and the output will |
| 1813 |
occupy the same number of bits as the input. |
| 1814 |
.Sp |
| 1815 |
There is no \f(CW\*(C`toFOLD_L1\*(C'\fR nor \f(CW\*(C`toFOLD_LATIN1\*(C'\fR as the foldcase of some code |
| 1816 |
points in the 0..255 range is above that range or consists of multiple |
| 1817 |
characters. Instead use \f(CW\*(C`toFOLD_uvchr\*(C'\fR. |
| 1818 |
.Sp |
| 1819 |
\&\f(CW\*(C`toFOLD_uvchr\*(C'\fR returns the foldcase of any Unicode code point. The return |
| 1820 |
value is identical to that of \f(CW\*(C`toFOLD_A\*(C'\fR for input code points in the ASCII |
| 1821 |
range. The foldcase of the vast majority of Unicode code points is the same |
| 1822 |
as the code point itself. For these, and for code points above the legal |
| 1823 |
Unicode maximum, this returns the input code point unchanged. It additionally |
| 1824 |
stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its |
| 1825 |
length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to |
| 1826 |
contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow. |
| 1827 |
.Sp |
| 1828 |
NOTE: the foldcase of a code point may be more than one code point. The |
| 1829 |
return value of this function is only the first of these. The entire foldcase |
| 1830 |
is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code |
| 1831 |
point, you can do something like this: |
| 1832 |
.Sp |
| 1833 |
.Vb 3 |
| 1834 |
\& uc = toFOLD_uvchr(cp, s, &len); |
| 1835 |
\& if (len > UTF8SKIP(s)) { is multiple code points } |
| 1836 |
\& else { is a single code point } |
| 1837 |
.Ve |
| 1838 |
.Sp |
| 1839 |
\&\f(CW\*(C`toFOLD_utf8\*(C'\fR and \f(CW\*(C`toFOLD_utf8_safe\*(C'\fR are synonyms of each other. The only |
| 1840 |
difference between these and \f(CW\*(C`toFOLD_uvchr\*(C'\fR is that the source for these is |
| 1841 |
encoded in UTF\-8, instead of being a code point. It is passed as a buffer |
| 1842 |
starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR |
| 1843 |
buffer may certainly contain more than one code point; but only the first one |
| 1844 |
(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is |
| 1845 |
malformed in some way, the program may croak, or the function may return the |
| 1846 |
REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to |
| 1847 |
change in future releases. |
| 1848 |
.RS 4 |
| 1849 |
.Sp |
| 1850 |
.Vb 5 |
| 1851 |
\& UV toFOLD (UV cp) |
| 1852 |
\& UV toFOLD_A (UV cp) |
| 1853 |
\& UV toFOLD_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp) |
| 1854 |
\& UV toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp) |
| 1855 |
\& UV toFOLD_uvchr (UV cp, U8* s, STRLEN* lenp) |
| 1856 |
.Ve |
| 1857 |
.RE |
| 1858 |
.RS 4 |
| 1859 |
.RE |
| 1860 |
.ie n .IP """toLOWER""" 4 |
| 1861 |
.el .IP \f(CWtoLOWER\fR 4 |
| 1862 |
.IX Item "toLOWER" |
| 1863 |
.PD 0 |
| 1864 |
.ie n .IP """toLOWER_A""" 4 |
| 1865 |
.el .IP \f(CWtoLOWER_A\fR 4 |
| 1866 |
.IX Item "toLOWER_A" |
| 1867 |
.ie n .IP """toLOWER_LATIN1""" 4 |
| 1868 |
.el .IP \f(CWtoLOWER_LATIN1\fR 4 |
| 1869 |
.IX Item "toLOWER_LATIN1" |
| 1870 |
.ie n .IP """toLOWER_LC""" 4 |
| 1871 |
.el .IP \f(CWtoLOWER_LC\fR 4 |
| 1872 |
.IX Item "toLOWER_LC" |
| 1873 |
.ie n .IP """toLOWER_L1""" 4 |
| 1874 |
.el .IP \f(CWtoLOWER_L1\fR 4 |
| 1875 |
.IX Item "toLOWER_L1" |
| 1876 |
.ie n .IP """toLOWER_utf8""" 4 |
| 1877 |
.el .IP \f(CWtoLOWER_utf8\fR 4 |
| 1878 |
.IX Item "toLOWER_utf8" |
| 1879 |
.ie n .IP """toLOWER_utf8_safe""" 4 |
| 1880 |
.el .IP \f(CWtoLOWER_utf8_safe\fR 4 |
| 1881 |
.IX Item "toLOWER_utf8_safe" |
| 1882 |
.ie n .IP """toLOWER_uvchr""" 4 |
| 1883 |
.el .IP \f(CWtoLOWER_uvchr\fR 4 |
| 1884 |
.IX Xref "toLOWER toLOWER_A toLOWER_LATIN1 toLOWER_LC toLOWER_L1 toLOWER_utf8 toLOWER_utf8_safe toLOWER_uvchr" |
| 1885 |
.IX Item "toLOWER_uvchr" |
| 1886 |
.PD |
| 1887 |
These all return the lowercase of a character. The differences are what domain |
| 1888 |
they operate on, and whether the input is specified as a code point (those |
| 1889 |
forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter |
| 1890 |
case, the code point to use is the first one in the buffer of UTF\-8 encoded |
| 1891 |
code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR. |
| 1892 |
.Sp |
| 1893 |
\&\f(CW\*(C`toLOWER\*(C'\fR and \f(CW\*(C`toLOWER_A\*(C'\fR are synonyms of each other. They return the |
| 1894 |
lowercase of any uppercase ASCII-range code point. All other inputs are |
| 1895 |
returned unchanged. Since these are macros, the input type may be any integral |
| 1896 |
one, and the output will occupy the same number of bits as the input. |
| 1897 |
.Sp |
| 1898 |
\&\f(CW\*(C`toLOWER_L1\*(C'\fR and \f(CW\*(C`toLOWER_LATIN1\*(C'\fR are synonyms of each other. They behave |
| 1899 |
identically as \f(CW\*(C`toLOWER\*(C'\fR for ASCII-range input. But additionally will return |
| 1900 |
the lowercase of any uppercase code point in the entire 0..255 range, assuming |
| 1901 |
a Latin\-1 encoding (or the EBCDIC equivalent on such platforms). |
| 1902 |
.Sp |
| 1903 |
\&\f(CW\*(C`toLOWER_LC\*(C'\fR returns the lowercase of the input code point according to the |
| 1904 |
rules of the current POSIX locale. Input code points outside the range 0..255 |
| 1905 |
are returned unchanged. |
| 1906 |
.Sp |
| 1907 |
\&\f(CW\*(C`toLOWER_uvchr\*(C'\fR returns the lowercase of any Unicode code point. The return |
| 1908 |
value is identical to that of \f(CW\*(C`toLOWER_L1\*(C'\fR for input code points in the 0..255 |
| 1909 |
range. The lowercase of the vast majority of Unicode code points is the same |
| 1910 |
as the code point itself. For these, and for code points above the legal |
| 1911 |
Unicode maximum, this returns the input code point unchanged. It additionally |
| 1912 |
stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its |
| 1913 |
length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to |
| 1914 |
contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow. |
| 1915 |
.Sp |
| 1916 |
NOTE: the lowercase of a code point may be more than one code point. The |
| 1917 |
return value of this function is only the first of these. The entire lowercase |
| 1918 |
is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code |
| 1919 |
point, you can do something like this: |
| 1920 |
.Sp |
| 1921 |
.Vb 3 |
| 1922 |
\& uc = toLOWER_uvchr(cp, s, &len); |
| 1923 |
\& if (len > UTF8SKIP(s)) { is multiple code points } |
| 1924 |
\& else { is a single code point } |
| 1925 |
.Ve |
| 1926 |
.Sp |
| 1927 |
\&\f(CW\*(C`toLOWER_utf8\*(C'\fR and \f(CW\*(C`toLOWER_utf8_safe\*(C'\fR are synonyms of each other. The only |
| 1928 |
difference between these and \f(CW\*(C`toLOWER_uvchr\*(C'\fR is that the source for these is |
| 1929 |
encoded in UTF\-8, instead of being a code point. It is passed as a buffer |
| 1930 |
starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR |
| 1931 |
buffer may certainly contain more than one code point; but only the first one |
| 1932 |
(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is |
| 1933 |
malformed in some way, the program may croak, or the function may return the |
| 1934 |
REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to |
| 1935 |
change in future releases. |
| 1936 |
.RS 4 |
| 1937 |
.Sp |
| 1938 |
.Vb 8 |
| 1939 |
\& UV toLOWER (UV cp) |
| 1940 |
\& UV toLOWER_A (UV cp) |
| 1941 |
\& UV toLOWER_LATIN1 (UV cp) |
| 1942 |
\& UV toLOWER_LC (UV cp) |
| 1943 |
\& UV toLOWER_L1 (UV cp) |
| 1944 |
\& UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp) |
| 1945 |
\& UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp) |
| 1946 |
\& UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp) |
| 1947 |
.Ve |
| 1948 |
.RE |
| 1949 |
.RS 4 |
| 1950 |
.RE |
| 1951 |
.ie n .IP """toTITLE""" 4 |
| 1952 |
.el .IP \f(CWtoTITLE\fR 4 |
| 1953 |
.IX Item "toTITLE" |
| 1954 |
.PD 0 |
| 1955 |
.ie n .IP """toTITLE_A""" 4 |
| 1956 |
.el .IP \f(CWtoTITLE_A\fR 4 |
| 1957 |
.IX Item "toTITLE_A" |
| 1958 |
.ie n .IP """toTITLE_utf8""" 4 |
| 1959 |
.el .IP \f(CWtoTITLE_utf8\fR 4 |
| 1960 |
.IX Item "toTITLE_utf8" |
| 1961 |
.ie n .IP """toTITLE_utf8_safe""" 4 |
| 1962 |
.el .IP \f(CWtoTITLE_utf8_safe\fR 4 |
| 1963 |
.IX Item "toTITLE_utf8_safe" |
| 1964 |
.ie n .IP """toTITLE_uvchr""" 4 |
| 1965 |
.el .IP \f(CWtoTITLE_uvchr\fR 4 |
| 1966 |
.IX Xref "toTITLE toTITLE_A toTITLE_utf8 toTITLE_utf8_safe toTITLE_uvchr" |
| 1967 |
.IX Item "toTITLE_uvchr" |
| 1968 |
.PD |
| 1969 |
These all return the titlecase of a character. The differences are what domain |
| 1970 |
they operate on, and whether the input is specified as a code point (those |
| 1971 |
forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter |
| 1972 |
case, the code point to use is the first one in the buffer of UTF\-8 encoded |
| 1973 |
code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR. |
| 1974 |
.Sp |
| 1975 |
\&\f(CW\*(C`toTITLE\*(C'\fR and \f(CW\*(C`toTITLE_A\*(C'\fR are synonyms of each other. They return the |
| 1976 |
titlecase of any lowercase ASCII-range code point. In this range, the |
| 1977 |
titlecase is identical to the uppercase. All other inputs are returned |
| 1978 |
unchanged. Since these are macros, the input type may be any integral one, and |
| 1979 |
the output will occupy the same number of bits as the input. |
| 1980 |
.Sp |
| 1981 |
There is no \f(CW\*(C`toTITLE_L1\*(C'\fR nor \f(CW\*(C`toTITLE_LATIN1\*(C'\fR as the titlecase of some code |
| 1982 |
points in the 0..255 range is above that range or consists of multiple |
| 1983 |
characters. Instead use \f(CW\*(C`toTITLE_uvchr\*(C'\fR. |
| 1984 |
.Sp |
| 1985 |
\&\f(CW\*(C`toTITLE_uvchr\*(C'\fR returns the titlecase of any Unicode code point. The return |
| 1986 |
value is identical to that of \f(CW\*(C`toTITLE_A\*(C'\fR for input code points in the ASCII |
| 1987 |
range. The titlecase of the vast majority of Unicode code points is the same |
| 1988 |
as the code point itself. For these, and for code points above the legal |
| 1989 |
Unicode maximum, this returns the input code point unchanged. It additionally |
| 1990 |
stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its |
| 1991 |
length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to |
| 1992 |
contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow. |
| 1993 |
.Sp |
| 1994 |
NOTE: the titlecase of a code point may be more than one code point. The |
| 1995 |
return value of this function is only the first of these. The entire titlecase |
| 1996 |
is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code |
| 1997 |
point, you can do something like this: |
| 1998 |
.Sp |
| 1999 |
.Vb 3 |
| 2000 |
\& uc = toTITLE_uvchr(cp, s, &len); |
| 2001 |
\& if (len > UTF8SKIP(s)) { is multiple code points } |
| 2002 |
\& else { is a single code point } |
| 2003 |
.Ve |
| 2004 |
.Sp |
| 2005 |
\&\f(CW\*(C`toTITLE_utf8\*(C'\fR and \f(CW\*(C`toTITLE_utf8_safe\*(C'\fR are synonyms of each other. The only |
| 2006 |
difference between these and \f(CW\*(C`toTITLE_uvchr\*(C'\fR is that the source for these is |
| 2007 |
encoded in UTF\-8, instead of being a code point. It is passed as a buffer |
| 2008 |
starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR |
| 2009 |
buffer may certainly contain more than one code point; but only the first one |
| 2010 |
(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is |
| 2011 |
malformed in some way, the program may croak, or the function may return the |
| 2012 |
REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to |
| 2013 |
change in future releases. |
| 2014 |
.RS 4 |
| 2015 |
.Sp |
| 2016 |
.Vb 5 |
| 2017 |
\& UV toTITLE (UV cp) |
| 2018 |
\& UV toTITLE_A (UV cp) |
| 2019 |
\& UV toTITLE_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp) |
| 2020 |
\& UV toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp) |
| 2021 |
\& UV toTITLE_uvchr (UV cp, U8* s, STRLEN* lenp) |
| 2022 |
.Ve |
| 2023 |
.RE |
| 2024 |
.RS 4 |
| 2025 |
.RE |
| 2026 |
.ie n .IP """toUPPER""" 4 |
| 2027 |
.el .IP \f(CWtoUPPER\fR 4 |
| 2028 |
.IX Item "toUPPER" |
| 2029 |
.PD 0 |
| 2030 |
.ie n .IP """toUPPER_A""" 4 |
| 2031 |
.el .IP \f(CWtoUPPER_A\fR 4 |
| 2032 |
.IX Item "toUPPER_A" |
| 2033 |
.ie n .IP """toUPPER_utf8""" 4 |
| 2034 |
.el .IP \f(CWtoUPPER_utf8\fR 4 |
| 2035 |
.IX Item "toUPPER_utf8" |
| 2036 |
.ie n .IP """toUPPER_utf8_safe""" 4 |
| 2037 |
.el .IP \f(CWtoUPPER_utf8_safe\fR 4 |
| 2038 |
.IX Item "toUPPER_utf8_safe" |
| 2039 |
.ie n .IP """toUPPER_uvchr""" 4 |
| 2040 |
.el .IP \f(CWtoUPPER_uvchr\fR 4 |
| 2041 |
.IX Xref "toUPPER toUPPER_A toUPPER_utf8 toUPPER_utf8_safe toUPPER_uvchr" |
| 2042 |
.IX Item "toUPPER_uvchr" |
| 2043 |
.PD |
| 2044 |
These all return the uppercase of a character. The differences are what domain |
| 2045 |
they operate on, and whether the input is specified as a code point (those |
| 2046 |
forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter |
| 2047 |
case, the code point to use is the first one in the buffer of UTF\-8 encoded |
| 2048 |
code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR. |
| 2049 |
.Sp |
| 2050 |
\&\f(CW\*(C`toUPPER\*(C'\fR and \f(CW\*(C`toUPPER_A\*(C'\fR are synonyms of each other. They return the |
| 2051 |
uppercase of any lowercase ASCII-range code point. All other inputs are |
| 2052 |
returned unchanged. Since these are macros, the input type may be any integral |
| 2053 |
one, and the output will occupy the same number of bits as the input. |
| 2054 |
.Sp |
| 2055 |
There is no \f(CW\*(C`toUPPER_L1\*(C'\fR nor \f(CW\*(C`toUPPER_LATIN1\*(C'\fR as the uppercase of some code |
| 2056 |
points in the 0..255 range is above that range or consists of multiple |
| 2057 |
characters. Instead use \f(CW\*(C`toUPPER_uvchr\*(C'\fR. |
| 2058 |
.Sp |
| 2059 |
\&\f(CW\*(C`toUPPER_uvchr\*(C'\fR returns the uppercase of any Unicode code point. The return |
| 2060 |
value is identical to that of \f(CW\*(C`toUPPER_A\*(C'\fR for input code points in the ASCII |
| 2061 |
range. The uppercase of the vast majority of Unicode code points is the same |
| 2062 |
as the code point itself. For these, and for code points above the legal |
| 2063 |
Unicode maximum, this returns the input code point unchanged. It additionally |
| 2064 |
stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its |
| 2065 |
length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to |
| 2066 |
contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow. |
| 2067 |
.Sp |
| 2068 |
NOTE: the uppercase of a code point may be more than one code point. The |
| 2069 |
return value of this function is only the first of these. The entire uppercase |
| 2070 |
is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code |
| 2071 |
point, you can do something like this: |
| 2072 |
.Sp |
| 2073 |
.Vb 3 |
| 2074 |
\& uc = toUPPER_uvchr(cp, s, &len); |
| 2075 |
\& if (len > UTF8SKIP(s)) { is multiple code points } |
| 2076 |
\& else { is a single code point } |
| 2077 |
.Ve |
| 2078 |
.Sp |
| 2079 |
\&\f(CW\*(C`toUPPER_utf8\*(C'\fR and \f(CW\*(C`toUPPER_utf8_safe\*(C'\fR are synonyms of each other. The only |
| 2080 |
difference between these and \f(CW\*(C`toUPPER_uvchr\*(C'\fR is that the source for these is |
| 2081 |
encoded in UTF\-8, instead of being a code point. It is passed as a buffer |
| 2082 |
starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR |
| 2083 |
buffer may certainly contain more than one code point; but only the first one |
| 2084 |
(up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is |
| 2085 |
malformed in some way, the program may croak, or the function may return the |
| 2086 |
REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to |
| 2087 |
change in future releases. |
| 2088 |
.RS 4 |
| 2089 |
.Sp |
| 2090 |
.Vb 5 |
| 2091 |
\& UV toUPPER (UV cp) |
| 2092 |
\& UV toUPPER_A (UV cp) |
| 2093 |
\& UV toUPPER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp) |
| 2094 |
\& UV toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp) |
| 2095 |
\& UV toUPPER_uvchr (UV cp, U8* s, STRLEN* lenp) |
| 2096 |
.Ve |
| 2097 |
.RE |
| 2098 |
.RS 4 |
| 2099 |
.RE |
| 2100 |
.SH "Character classification" |
| 2101 |
.IX Header "Character classification" |
| 2102 |
This section is about functions (really macros) that classify characters |
| 2103 |
into types, such as punctuation versus alphabetic, etc. Most of these are |
| 2104 |
analogous to regular expression character classes. (See |
| 2105 |
"POSIX Character Classes" in perlrecharclass.) There are several variants for |
| 2106 |
each class. (Not all macros have all variants; each item below lists the |
| 2107 |
ones valid for it.) None are affected by \f(CW\*(C`use bytes\*(C'\fR, and only the ones |
| 2108 |
with \f(CW\*(C`LC\*(C'\fR in the name are affected by the current locale. |
| 2109 |
.PP |
| 2110 |
The base function, e.g., \f(CWisALPHA()\fR, takes any signed or unsigned value, |
| 2111 |
treating it as a code point, and returns a boolean as to whether or not the |
| 2112 |
character represented by it is (or on non-ASCII platforms, corresponds to) an |
| 2113 |
ASCII character in the named class based on platform, Unicode, and Perl rules. |
| 2114 |
If the input is a number that doesn't fit in an octet, FALSE is returned. |
| 2115 |
.PP |
| 2116 |
Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR (e.g., \f(CWisALPHA_A()\fR) is identical to the base function |
| 2117 |
with no suffix \f(CW"_A"\fR. This variant is used to emphasize by its name that |
| 2118 |
only ASCII-range characters can return TRUE. |
| 2119 |
.PP |
| 2120 |
Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR imposes the Latin\-1 (or EBCDIC equivalent) character set |
| 2121 |
onto the platform. That is, the code points that are ASCII are unaffected, |
| 2122 |
since ASCII is a subset of Latin\-1. But the non-ASCII code points are treated |
| 2123 |
as if they are Latin\-1 characters. For example, \f(CWisWORDCHAR_L1()\fR will return |
| 2124 |
true when called with the code point 0xDF, which is a word character in both |
| 2125 |
ASCII and EBCDIC (though it represents different characters in each). |
| 2126 |
If the input is a number that doesn't fit in an octet, FALSE is returned. |
| 2127 |
(Perl's documentation uses a colloquial definition of Latin\-1, to include all |
| 2128 |
code points below 256.) |
| 2129 |
.PP |
| 2130 |
Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR is exactly like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variant, for |
| 2131 |
inputs below 256, but if the code point is larger than 255, Unicode rules are |
| 2132 |
used to determine if it is in the character class. For example, |
| 2133 |
\&\f(CWisWORDCHAR_uvchr(0x100)\fR returns TRUE, since 0x100 is LATIN CAPITAL LETTER A |
| 2134 |
WITH MACRON in Unicode, and is a word character. |
| 2135 |
.PP |
| 2136 |
Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8_safe\*(C'\fR are like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR, |
| 2137 |
but are used for UTF\-8 encoded strings. The two forms are different names for |
| 2138 |
the same thing. Each call to one of these classifies the first character of |
| 2139 |
the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter, \f(CW\*(C`e\*(C'\fR, points to anywhere in |
| 2140 |
the string beyond the first character, up to one byte past the end of the |
| 2141 |
entire string. Although both variants are identical, the suffix \f(CW\*(C`_safe\*(C'\fR in |
| 2142 |
one name emphasizes that it will not attempt to read beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR, |
| 2143 |
provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this is asserted for in |
| 2144 |
\&\f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input character is malformed in |
| 2145 |
some way, the program may croak, or the function may return FALSE, at the |
| 2146 |
discretion of the implementation, and subject to change in future releases. |
| 2147 |
.PP |
| 2148 |
Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR is like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variants, |
| 2149 |
but the result is based on the current locale, which is what \f(CW\*(C`LC\*(C'\fR in the name |
| 2150 |
stands for. If Perl can determine that the current locale is a UTF\-8 locale, |
| 2151 |
it uses the published Unicode rules; otherwise, it uses the C library function |
| 2152 |
that gives the named classification. For example, \f(CWisDIGIT_LC()\fR when not in |
| 2153 |
a UTF\-8 locale returns the result of calling \f(CWisdigit()\fR. FALSE is always |
| 2154 |
returned if the input won't fit into an octet. On some platforms where the C |
| 2155 |
library function is known to be defective, Perl changes its result to follow |
| 2156 |
the POSIX standard's rules. |
| 2157 |
.PP |
| 2158 |
Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR acts exactly like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR for inputs less |
| 2159 |
than 256, but for larger ones it returns the Unicode classification of the code |
| 2160 |
point. |
| 2161 |
.PP |
| 2162 |
Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8_safe\*(C'\fR are like |
| 2163 |
\&\f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR, but are used for UTF\-8 encoded strings. The two forms |
| 2164 |
are different names for the same thing. Each call to one of these classifies |
| 2165 |
the first character of the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter, |
| 2166 |
\&\f(CW\*(C`e\*(C'\fR, points to anywhere in the string beyond the first character, up to one |
| 2167 |
byte past the end of the entire string. Although both variants are identical, |
| 2168 |
the suffix \f(CW\*(C`_safe\*(C'\fR in one name emphasizes that it will not attempt to read |
| 2169 |
beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR, provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this |
| 2170 |
is asserted for in \f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input |
| 2171 |
character is malformed in some way, the program may croak, or the function may |
| 2172 |
return FALSE, at the discretion of the implementation, and subject to change in |
| 2173 |
future releases. |
| 2174 |
.ie n .IP """isALNUM""" 4 |
| 2175 |
.el .IP \f(CWisALNUM\fR 4 |
| 2176 |
.IX Item "isALNUM" |
| 2177 |
.PD 0 |
| 2178 |
.ie n .IP """isALNUM_A""" 4 |
| 2179 |
.el .IP \f(CWisALNUM_A\fR 4 |
| 2180 |
.IX Item "isALNUM_A" |
| 2181 |
.ie n .IP """isALNUM_LC""" 4 |
| 2182 |
.el .IP \f(CWisALNUM_LC\fR 4 |
| 2183 |
.IX Item "isALNUM_LC" |
| 2184 |
.ie n .IP """isALNUM_LC_uvchr""" 4 |
| 2185 |
.el .IP \f(CWisALNUM_LC_uvchr\fR 4 |
| 2186 |
.IX Xref "isALNUM isALNUM_A isALNUM_LC isALNUM_LC_uvchr" |
| 2187 |
.IX Item "isALNUM_LC_uvchr" |
| 2188 |
.PD |
| 2189 |
These are each a synonym for their respectively named "\f(CW\*(C`isWORDCHAR\*(C'\fR" |
| 2190 |
variant. |
| 2191 |
.Sp |
| 2192 |
They are provided for backward compatibility, even though a word character |
| 2193 |
includes more than the standard C language meaning of alphanumeric. |
| 2194 |
To get the C language definition, use the corresponding "\f(CW\*(C`isALPHANUMERIC\*(C'\fR" |
| 2195 |
variant. |
| 2196 |
.RS 4 |
| 2197 |
.Sp |
| 2198 |
.Vb 1 |
| 2199 |
\& bool isALNUM(UV ch) |
| 2200 |
.Ve |
| 2201 |
.RE |
| 2202 |
.RS 4 |
| 2203 |
.RE |
| 2204 |
.ie n .IP """isALNUMC""" 4 |
| 2205 |
.el .IP \f(CWisALNUMC\fR 4 |
| 2206 |
.IX Item "isALNUMC" |
| 2207 |
.PD 0 |
| 2208 |
.ie n .IP """isALNUMC_A""" 4 |
| 2209 |
.el .IP \f(CWisALNUMC_A\fR 4 |
| 2210 |
.IX Item "isALNUMC_A" |
| 2211 |
.ie n .IP """isALNUMC_LC""" 4 |
| 2212 |
.el .IP \f(CWisALNUMC_LC\fR 4 |
| 2213 |
.IX Item "isALNUMC_LC" |
| 2214 |
.ie n .IP """isALNUMC_LC_uvchr""" 4 |
| 2215 |
.el .IP \f(CWisALNUMC_LC_uvchr\fR 4 |
| 2216 |
.IX Item "isALNUMC_LC_uvchr" |
| 2217 |
.ie n .IP """isALNUMC_L1""" 4 |
| 2218 |
.el .IP \f(CWisALNUMC_L1\fR 4 |
| 2219 |
.IX Xref "isALNUMC isALNUMC_A isALNUMC_LC isALNUMC_LC_uvchr isALNUMC_L1" |
| 2220 |
.IX Item "isALNUMC_L1" |
| 2221 |
.PD |
| 2222 |
These are discouraged, backward compatibility macros for "\f(CW\*(C`isALPHANUMERIC\*(C'\fR". |
| 2223 |
That is, each returns a boolean indicating whether the specified character is |
| 2224 |
one of \f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR. |
| 2225 |
.Sp |
| 2226 |
The \f(CW\*(C`C\*(C'\fR suffix in the names was meant to indicate that they correspond to the |
| 2227 |
C language \f(CWisalnum(3)\fR. |
| 2228 |
.RS 4 |
| 2229 |
.Sp |
| 2230 |
.Vb 1 |
| 2231 |
\& bool isALNUMC(UV ch) |
| 2232 |
.Ve |
| 2233 |
.RE |
| 2234 |
.RS 4 |
| 2235 |
.RE |
| 2236 |
.ie n .IP """isALPHA""" 4 |
| 2237 |
.el .IP \f(CWisALPHA\fR 4 |
| 2238 |
.IX Item "isALPHA" |
| 2239 |
.PD 0 |
| 2240 |
.ie n .IP """isALPHA_A""" 4 |
| 2241 |
.el .IP \f(CWisALPHA_A\fR 4 |
| 2242 |
.IX Item "isALPHA_A" |
| 2243 |
.ie n .IP """isALPHA_LC""" 4 |
| 2244 |
.el .IP \f(CWisALPHA_LC\fR 4 |
| 2245 |
.IX Item "isALPHA_LC" |
| 2246 |
.ie n .IP """isALPHA_LC_utf8_safe""" 4 |
| 2247 |
.el .IP \f(CWisALPHA_LC_utf8_safe\fR 4 |
| 2248 |
.IX Item "isALPHA_LC_utf8_safe" |
| 2249 |
.ie n .IP """isALPHA_LC_uvchr""" 4 |
| 2250 |
.el .IP \f(CWisALPHA_LC_uvchr\fR 4 |
| 2251 |
.IX Item "isALPHA_LC_uvchr" |
| 2252 |
.ie n .IP """isALPHA_L1""" 4 |
| 2253 |
.el .IP \f(CWisALPHA_L1\fR 4 |
| 2254 |
.IX Item "isALPHA_L1" |
| 2255 |
.ie n .IP """isALPHA_utf8""" 4 |
| 2256 |
.el .IP \f(CWisALPHA_utf8\fR 4 |
| 2257 |
.IX Item "isALPHA_utf8" |
| 2258 |
.ie n .IP """isALPHA_utf8_safe""" 4 |
| 2259 |
.el .IP \f(CWisALPHA_utf8_safe\fR 4 |
| 2260 |
.IX Item "isALPHA_utf8_safe" |
| 2261 |
.ie n .IP """isALPHA_uvchr""" 4 |
| 2262 |
.el .IP \f(CWisALPHA_uvchr\fR 4 |
| 2263 |
.IX Xref "isALPHA isALPHA_A isALPHA_LC isALPHA_LC_utf8_safe isALPHA_LC_uvchr isALPHA_L1 isALPHA_utf8 isALPHA_utf8_safe isALPHA_uvchr" |
| 2264 |
.IX Item "isALPHA_uvchr" |
| 2265 |
.PD |
| 2266 |
Returns a boolean indicating whether the specified input is one of \f(CW\*(C`[A\-Za\-z]\*(C'\fR, |
| 2267 |
analogous to \f(CW\*(C`m/[[:alpha:]]/\*(C'\fR. |
| 2268 |
See the top of this section for an explanation of |
| 2269 |
the variants. |
| 2270 |
.RS 4 |
| 2271 |
.Sp |
| 2272 |
.Vb 9 |
| 2273 |
\& bool isALPHA (UV ch) |
| 2274 |
\& bool isALPHA_A (UV ch) |
| 2275 |
\& bool isALPHA_LC (UV ch) |
| 2276 |
\& bool isALPHA_LC_utf8_safe(U8 * s, U8 *end) |
| 2277 |
\& bool isALPHA_LC_uvchr (UV ch) |
| 2278 |
\& bool isALPHA_L1 (UV ch) |
| 2279 |
\& bool isALPHA_utf8 (U8 * s, U8 * end) |
| 2280 |
\& bool isALPHA_utf8_safe (U8 * s, U8 * end) |
| 2281 |
\& bool isALPHA_uvchr (UV ch) |
| 2282 |
.Ve |
| 2283 |
.RE |
| 2284 |
.RS 4 |
| 2285 |
.RE |
| 2286 |
.ie n .IP """isALPHANUMERIC""" 4 |
| 2287 |
.el .IP \f(CWisALPHANUMERIC\fR 4 |
| 2288 |
.IX Item "isALPHANUMERIC" |
| 2289 |
.PD 0 |
| 2290 |
.ie n .IP """isALPHANUMERIC_A""" 4 |
| 2291 |
.el .IP \f(CWisALPHANUMERIC_A\fR 4 |
| 2292 |
.IX Item "isALPHANUMERIC_A" |
| 2293 |
.ie n .IP """isALPHANUMERIC_LC""" 4 |
| 2294 |
.el .IP \f(CWisALPHANUMERIC_LC\fR 4 |
| 2295 |
.IX Item "isALPHANUMERIC_LC" |
| 2296 |
.ie n .IP """isALPHANUMERIC_LC_utf8_safe""" 4 |
| 2297 |
.el .IP \f(CWisALPHANUMERIC_LC_utf8_safe\fR 4 |
| 2298 |
.IX Item "isALPHANUMERIC_LC_utf8_safe" |
| 2299 |
.ie n .IP """isALPHANUMERIC_LC_uvchr""" 4 |
| 2300 |
.el .IP \f(CWisALPHANUMERIC_LC_uvchr\fR 4 |
| 2301 |
.IX Item "isALPHANUMERIC_LC_uvchr" |
| 2302 |
.ie n .IP """isALPHANUMERIC_L1""" 4 |
| 2303 |
.el .IP \f(CWisALPHANUMERIC_L1\fR 4 |
| 2304 |
.IX Item "isALPHANUMERIC_L1" |
| 2305 |
.ie n .IP """isALPHANUMERIC_utf8""" 4 |
| 2306 |
.el .IP \f(CWisALPHANUMERIC_utf8\fR 4 |
| 2307 |
.IX Item "isALPHANUMERIC_utf8" |
| 2308 |
.ie n .IP """isALPHANUMERIC_utf8_safe""" 4 |
| 2309 |
.el .IP \f(CWisALPHANUMERIC_utf8_safe\fR 4 |
| 2310 |
.IX Item "isALPHANUMERIC_utf8_safe" |
| 2311 |
.ie n .IP """isALPHANUMERIC_uvchr""" 4 |
| 2312 |
.el .IP \f(CWisALPHANUMERIC_uvchr\fR 4 |
| 2313 |
.IX Xref "isALPHANUMERIC isALPHANUMERIC_A isALPHANUMERIC_LC isALPHANUMERIC_LC_utf8_safe isALPHANUMERIC_LC_uvchr isALPHANUMERIC_L1 isALPHANUMERIC_utf8 isALPHANUMERIC_utf8_safe isALPHANUMERIC_uvchr" |
| 2314 |
.IX Item "isALPHANUMERIC_uvchr" |
| 2315 |
.PD |
| 2316 |
Returns a boolean indicating whether the specified character is one of |
| 2317 |
\&\f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR. |
| 2318 |
See the top of this section for an explanation of |
| 2319 |
the variants. |
| 2320 |
.RS 4 |
| 2321 |
.Sp |
| 2322 |
.Vb 9 |
| 2323 |
\& bool isALPHANUMERIC (UV ch) |
| 2324 |
\& bool isALPHANUMERIC_A (UV ch) |
| 2325 |
\& bool isALPHANUMERIC_LC (UV ch) |
| 2326 |
\& bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end) |
| 2327 |
\& bool isALPHANUMERIC_LC_uvchr (UV ch) |
| 2328 |
\& bool isALPHANUMERIC_L1 (UV ch) |
| 2329 |
\& bool isALPHANUMERIC_utf8 (U8 * s, U8 * end) |
| 2330 |
\& bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end) |
| 2331 |
\& bool isALPHANUMERIC_uvchr (UV ch) |
| 2332 |
.Ve |
| 2333 |
.RE |
| 2334 |
.RS 4 |
| 2335 |
.RE |
| 2336 |
.ie n .IP """isASCII""" 4 |
| 2337 |
.el .IP \f(CWisASCII\fR 4 |
| 2338 |
.IX Item "isASCII" |
| 2339 |
.PD 0 |
| 2340 |
.ie n .IP """isASCII_A""" 4 |
| 2341 |
.el .IP \f(CWisASCII_A\fR 4 |
| 2342 |
.IX Item "isASCII_A" |
| 2343 |
.ie n .IP """isASCII_LC""" 4 |
| 2344 |
.el .IP \f(CWisASCII_LC\fR 4 |
| 2345 |
.IX Item "isASCII_LC" |
| 2346 |
.ie n .IP """isASCII_LC_utf8_safe""" 4 |
| 2347 |
.el .IP \f(CWisASCII_LC_utf8_safe\fR 4 |
| 2348 |
.IX Item "isASCII_LC_utf8_safe" |
| 2349 |
.ie n .IP """isASCII_LC_uvchr""" 4 |
| 2350 |
.el .IP \f(CWisASCII_LC_uvchr\fR 4 |
| 2351 |
.IX Item "isASCII_LC_uvchr" |
| 2352 |
.ie n .IP """isASCII_L1""" 4 |
| 2353 |
.el .IP \f(CWisASCII_L1\fR 4 |
| 2354 |
.IX Item "isASCII_L1" |
| 2355 |
.ie n .IP """isASCII_utf8""" 4 |
| 2356 |
.el .IP \f(CWisASCII_utf8\fR 4 |
| 2357 |
.IX Item "isASCII_utf8" |
| 2358 |
.ie n .IP """isASCII_utf8_safe""" 4 |
| 2359 |
.el .IP \f(CWisASCII_utf8_safe\fR 4 |
| 2360 |
.IX Item "isASCII_utf8_safe" |
| 2361 |
.ie n .IP """isASCII_uvchr""" 4 |
| 2362 |
.el .IP \f(CWisASCII_uvchr\fR 4 |
| 2363 |
.IX Xref "isASCII isASCII_A isASCII_LC isASCII_LC_utf8_safe isASCII_LC_uvchr isASCII_L1 isASCII_utf8 isASCII_utf8_safe isASCII_uvchr" |
| 2364 |
.IX Item "isASCII_uvchr" |
| 2365 |
.PD |
| 2366 |
Returns a boolean indicating whether the specified character is one of the 128 |
| 2367 |
characters in the ASCII character set, analogous to \f(CW\*(C`m/[[:ascii:]]/\*(C'\fR. |
| 2368 |
On non-ASCII platforms, it returns TRUE iff this |
| 2369 |
character corresponds to an ASCII character. Variants \f(CWisASCII_A()\fR and |
| 2370 |
\&\f(CWisASCII_L1()\fR are identical to \f(CWisASCII()\fR. |
| 2371 |
See the top of this section for an explanation of |
| 2372 |
the variants. |
| 2373 |
Note, however, that some platforms do not have the C library routine |
| 2374 |
\&\f(CWisascii()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are the |
| 2375 |
same as the corresponding ones without. |
| 2376 |
.Sp |
| 2377 |
Also note, that because all ASCII characters are UTF\-8 invariant (meaning they |
| 2378 |
have the exact same representation (always a single byte) whether encoded in |
| 2379 |
UTF\-8 or not), \f(CW\*(C`isASCII\*(C'\fR will give the correct results when called with any |
| 2380 |
byte in any string encoded or not in UTF\-8. And similarly \f(CW\*(C`isASCII_utf8\*(C'\fR and |
| 2381 |
\&\f(CW\*(C`isASCII_utf8_safe\*(C'\fR will work properly on any string encoded or not in UTF\-8. |
| 2382 |
.RS 4 |
| 2383 |
.Sp |
| 2384 |
.Vb 9 |
| 2385 |
\& bool isASCII (UV ch) |
| 2386 |
\& bool isASCII_A (UV ch) |
| 2387 |
\& bool isASCII_LC (UV ch) |
| 2388 |
\& bool isASCII_LC_utf8_safe(U8 * s, U8 *end) |
| 2389 |
\& bool isASCII_LC_uvchr (UV ch) |
| 2390 |
\& bool isASCII_L1 (UV ch) |
| 2391 |
\& bool isASCII_utf8 (U8 * s, U8 * end) |
| 2392 |
\& bool isASCII_utf8_safe (U8 * s, U8 * end) |
| 2393 |
\& bool isASCII_uvchr (UV ch) |
| 2394 |
.Ve |
| 2395 |
.RE |
| 2396 |
.RS 4 |
| 2397 |
.RE |
| 2398 |
.ie n .IP """isBLANK""" 4 |
| 2399 |
.el .IP \f(CWisBLANK\fR 4 |
| 2400 |
.IX Item "isBLANK" |
| 2401 |
.PD 0 |
| 2402 |
.ie n .IP """isBLANK_A""" 4 |
| 2403 |
.el .IP \f(CWisBLANK_A\fR 4 |
| 2404 |
.IX Item "isBLANK_A" |
| 2405 |
.ie n .IP """isBLANK_LC""" 4 |
| 2406 |
.el .IP \f(CWisBLANK_LC\fR 4 |
| 2407 |
.IX Item "isBLANK_LC" |
| 2408 |
.ie n .IP """isBLANK_LC_utf8_safe""" 4 |
| 2409 |
.el .IP \f(CWisBLANK_LC_utf8_safe\fR 4 |
| 2410 |
.IX Item "isBLANK_LC_utf8_safe" |
| 2411 |
.ie n .IP """isBLANK_LC_uvchr""" 4 |
| 2412 |
.el .IP \f(CWisBLANK_LC_uvchr\fR 4 |
| 2413 |
.IX Item "isBLANK_LC_uvchr" |
| 2414 |
.ie n .IP """isBLANK_L1""" 4 |
| 2415 |
.el .IP \f(CWisBLANK_L1\fR 4 |
| 2416 |
.IX Item "isBLANK_L1" |
| 2417 |
.ie n .IP """isBLANK_utf8""" 4 |
| 2418 |
.el .IP \f(CWisBLANK_utf8\fR 4 |
| 2419 |
.IX Item "isBLANK_utf8" |
| 2420 |
.ie n .IP """isBLANK_utf8_safe""" 4 |
| 2421 |
.el .IP \f(CWisBLANK_utf8_safe\fR 4 |
| 2422 |
.IX Item "isBLANK_utf8_safe" |
| 2423 |
.ie n .IP """isBLANK_uvchr""" 4 |
| 2424 |
.el .IP \f(CWisBLANK_uvchr\fR 4 |
| 2425 |
.IX Xref "isBLANK isBLANK_A isBLANK_LC isBLANK_LC_utf8_safe isBLANK_LC_uvchr isBLANK_L1 isBLANK_utf8 isBLANK_utf8_safe isBLANK_uvchr" |
| 2426 |
.IX Item "isBLANK_uvchr" |
| 2427 |
.PD |
| 2428 |
Returns a boolean indicating whether the specified character is a |
| 2429 |
character considered to be a blank, analogous to \f(CW\*(C`m/[[:blank:]]/\*(C'\fR. |
| 2430 |
See the top of this section for an explanation of |
| 2431 |
the variants. |
| 2432 |
Note, |
| 2433 |
however, that some platforms do not have the C library routine |
| 2434 |
\&\f(CWisblank()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are |
| 2435 |
the same as the corresponding ones without. |
| 2436 |
.RS 4 |
| 2437 |
.Sp |
| 2438 |
.Vb 9 |
| 2439 |
\& bool isBLANK (UV ch) |
| 2440 |
\& bool isBLANK_A (UV ch) |
| 2441 |
\& bool isBLANK_LC (UV ch) |
| 2442 |
\& bool isBLANK_LC_utf8_safe(U8 * s, U8 *end) |
| 2443 |
\& bool isBLANK_LC_uvchr (UV ch) |
| 2444 |
\& bool isBLANK_L1 (UV ch) |
| 2445 |
\& bool isBLANK_utf8 (U8 * s, U8 * end) |
| 2446 |
\& bool isBLANK_utf8_safe (U8 * s, U8 * end) |
| 2447 |
\& bool isBLANK_uvchr (UV ch) |
| 2448 |
.Ve |
| 2449 |
.RE |
| 2450 |
.RS 4 |
| 2451 |
.RE |
| 2452 |
.ie n .IP """isCNTRL""" 4 |
| 2453 |
.el .IP \f(CWisCNTRL\fR 4 |
| 2454 |
.IX Item "isCNTRL" |
| 2455 |
.PD 0 |
| 2456 |
.ie n .IP """isCNTRL_A""" 4 |
| 2457 |
.el .IP \f(CWisCNTRL_A\fR 4 |
| 2458 |
.IX Item "isCNTRL_A" |
| 2459 |
.ie n .IP """isCNTRL_LC""" 4 |
| 2460 |
.el .IP \f(CWisCNTRL_LC\fR 4 |
| 2461 |
.IX Item "isCNTRL_LC" |
| 2462 |
.ie n .IP """isCNTRL_LC_utf8_safe""" 4 |
| 2463 |
.el .IP \f(CWisCNTRL_LC_utf8_safe\fR 4 |
| 2464 |
.IX Item "isCNTRL_LC_utf8_safe" |
| 2465 |
.ie n .IP """isCNTRL_LC_uvchr""" 4 |
| 2466 |
.el .IP \f(CWisCNTRL_LC_uvchr\fR 4 |
| 2467 |
.IX Item "isCNTRL_LC_uvchr" |
| 2468 |
.ie n .IP """isCNTRL_L1""" 4 |
| 2469 |
.el .IP \f(CWisCNTRL_L1\fR 4 |
| 2470 |
.IX Item "isCNTRL_L1" |
| 2471 |
.ie n .IP """isCNTRL_utf8""" 4 |
| 2472 |
.el .IP \f(CWisCNTRL_utf8\fR 4 |
| 2473 |
.IX Item "isCNTRL_utf8" |
| 2474 |
.ie n .IP """isCNTRL_utf8_safe""" 4 |
| 2475 |
.el .IP \f(CWisCNTRL_utf8_safe\fR 4 |
| 2476 |
.IX Item "isCNTRL_utf8_safe" |
| 2477 |
.ie n .IP """isCNTRL_uvchr""" 4 |
| 2478 |
.el .IP \f(CWisCNTRL_uvchr\fR 4 |
| 2479 |
.IX Xref "isCNTRL isCNTRL_A isCNTRL_LC isCNTRL_LC_utf8_safe isCNTRL_LC_uvchr isCNTRL_L1 isCNTRL_utf8 isCNTRL_utf8_safe isCNTRL_uvchr" |
| 2480 |
.IX Item "isCNTRL_uvchr" |
| 2481 |
.PD |
| 2482 |
Returns a boolean indicating whether the specified character is a |
| 2483 |
control character, analogous to \f(CW\*(C`m/[[:cntrl:]]/\*(C'\fR. |
| 2484 |
See the top of this section for an explanation of |
| 2485 |
the variants. |
| 2486 |
On EBCDIC platforms, you almost always want to use the \f(CW\*(C`isCNTRL_L1\*(C'\fR variant. |
| 2487 |
.RS 4 |
| 2488 |
.Sp |
| 2489 |
.Vb 9 |
| 2490 |
\& bool isCNTRL (UV ch) |
| 2491 |
\& bool isCNTRL_A (UV ch) |
| 2492 |
\& bool isCNTRL_LC (UV ch) |
| 2493 |
\& bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end) |
| 2494 |
\& bool isCNTRL_LC_uvchr (UV ch) |
| 2495 |
\& bool isCNTRL_L1 (UV ch) |
| 2496 |
\& bool isCNTRL_utf8 (U8 * s, U8 * end) |
| 2497 |
\& bool isCNTRL_utf8_safe (U8 * s, U8 * end) |
| 2498 |
\& bool isCNTRL_uvchr (UV ch) |
| 2499 |
.Ve |
| 2500 |
.RE |
| 2501 |
.RS 4 |
| 2502 |
.RE |
| 2503 |
.ie n .IP """isDIGIT""" 4 |
| 2504 |
.el .IP \f(CWisDIGIT\fR 4 |
| 2505 |
.IX Item "isDIGIT" |
| 2506 |
.PD 0 |
| 2507 |
.ie n .IP """isDIGIT_A""" 4 |
| 2508 |
.el .IP \f(CWisDIGIT_A\fR 4 |
| 2509 |
.IX Item "isDIGIT_A" |
| 2510 |
.ie n .IP """isDIGIT_LC""" 4 |
| 2511 |
.el .IP \f(CWisDIGIT_LC\fR 4 |
| 2512 |
.IX Item "isDIGIT_LC" |
| 2513 |
.ie n .IP """isDIGIT_LC_utf8_safe""" 4 |
| 2514 |
.el .IP \f(CWisDIGIT_LC_utf8_safe\fR 4 |
| 2515 |
.IX Item "isDIGIT_LC_utf8_safe" |
| 2516 |
.ie n .IP """isDIGIT_LC_uvchr""" 4 |
| 2517 |
.el .IP \f(CWisDIGIT_LC_uvchr\fR 4 |
| 2518 |
.IX Item "isDIGIT_LC_uvchr" |
| 2519 |
.ie n .IP """isDIGIT_L1""" 4 |
| 2520 |
.el .IP \f(CWisDIGIT_L1\fR 4 |
| 2521 |
.IX Item "isDIGIT_L1" |
| 2522 |
.ie n .IP """isDIGIT_utf8""" 4 |
| 2523 |
.el .IP \f(CWisDIGIT_utf8\fR 4 |
| 2524 |
.IX Item "isDIGIT_utf8" |
| 2525 |
.ie n .IP """isDIGIT_utf8_safe""" 4 |
| 2526 |
.el .IP \f(CWisDIGIT_utf8_safe\fR 4 |
| 2527 |
.IX Item "isDIGIT_utf8_safe" |
| 2528 |
.ie n .IP """isDIGIT_uvchr""" 4 |
| 2529 |
.el .IP \f(CWisDIGIT_uvchr\fR 4 |
| 2530 |
.IX Xref "isDIGIT isDIGIT_A isDIGIT_LC isDIGIT_LC_utf8_safe isDIGIT_LC_uvchr isDIGIT_L1 isDIGIT_utf8 isDIGIT_utf8_safe isDIGIT_uvchr" |
| 2531 |
.IX Item "isDIGIT_uvchr" |
| 2532 |
.PD |
| 2533 |
Returns a boolean indicating whether the specified character is a |
| 2534 |
digit, analogous to \f(CW\*(C`m/[[:digit:]]/\*(C'\fR. |
| 2535 |
Variants \f(CW\*(C`isDIGIT_A\*(C'\fR and \f(CW\*(C`isDIGIT_L1\*(C'\fR are identical to \f(CW\*(C`isDIGIT\*(C'\fR. |
| 2536 |
See the top of this section for an explanation of |
| 2537 |
the variants. |
| 2538 |
.RS 4 |
| 2539 |
.Sp |
| 2540 |
.Vb 9 |
| 2541 |
\& bool isDIGIT (UV ch) |
| 2542 |
\& bool isDIGIT_A (UV ch) |
| 2543 |
\& bool isDIGIT_LC (UV ch) |
| 2544 |
\& bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end) |
| 2545 |
\& bool isDIGIT_LC_uvchr (UV ch) |
| 2546 |
\& bool isDIGIT_L1 (UV ch) |
| 2547 |
\& bool isDIGIT_utf8 (U8 * s, U8 * end) |
| 2548 |
\& bool isDIGIT_utf8_safe (U8 * s, U8 * end) |
| 2549 |
\& bool isDIGIT_uvchr (UV ch) |
| 2550 |
.Ve |
| 2551 |
.RE |
| 2552 |
.RS 4 |
| 2553 |
.RE |
| 2554 |
.ie n .IP """isGRAPH""" 4 |
| 2555 |
.el .IP \f(CWisGRAPH\fR 4 |
| 2556 |
.IX Item "isGRAPH" |
| 2557 |
.PD 0 |
| 2558 |
.ie n .IP """isGRAPH_A""" 4 |
| 2559 |
.el .IP \f(CWisGRAPH_A\fR 4 |
| 2560 |
.IX Item "isGRAPH_A" |
| 2561 |
.ie n .IP """isGRAPH_LC""" 4 |
| 2562 |
.el .IP \f(CWisGRAPH_LC\fR 4 |
| 2563 |
.IX Item "isGRAPH_LC" |
| 2564 |
.ie n .IP """isGRAPH_LC_utf8_safe""" 4 |
| 2565 |
.el .IP \f(CWisGRAPH_LC_utf8_safe\fR 4 |
| 2566 |
.IX Item "isGRAPH_LC_utf8_safe" |
| 2567 |
.ie n .IP """isGRAPH_LC_uvchr""" 4 |
| 2568 |
.el .IP \f(CWisGRAPH_LC_uvchr\fR 4 |
| 2569 |
.IX Item "isGRAPH_LC_uvchr" |
| 2570 |
.ie n .IP """isGRAPH_L1""" 4 |
| 2571 |
.el .IP \f(CWisGRAPH_L1\fR 4 |
| 2572 |
.IX Item "isGRAPH_L1" |
| 2573 |
.ie n .IP """isGRAPH_utf8""" 4 |
| 2574 |
.el .IP \f(CWisGRAPH_utf8\fR 4 |
| 2575 |
.IX Item "isGRAPH_utf8" |
| 2576 |
.ie n .IP """isGRAPH_utf8_safe""" 4 |
| 2577 |
.el .IP \f(CWisGRAPH_utf8_safe\fR 4 |
| 2578 |
.IX Item "isGRAPH_utf8_safe" |
| 2579 |
.ie n .IP """isGRAPH_uvchr""" 4 |
| 2580 |
.el .IP \f(CWisGRAPH_uvchr\fR 4 |
| 2581 |
.IX Xref "isGRAPH isGRAPH_A isGRAPH_LC isGRAPH_LC_utf8_safe isGRAPH_LC_uvchr isGRAPH_L1 isGRAPH_utf8 isGRAPH_utf8_safe isGRAPH_uvchr" |
| 2582 |
.IX Item "isGRAPH_uvchr" |
| 2583 |
.PD |
| 2584 |
Returns a boolean indicating whether the specified character is a |
| 2585 |
graphic character, analogous to \f(CW\*(C`m/[[:graph:]]/\*(C'\fR. |
| 2586 |
See the top of this section for an explanation of |
| 2587 |
the variants. |
| 2588 |
.RS 4 |
| 2589 |
.Sp |
| 2590 |
.Vb 9 |
| 2591 |
\& bool isGRAPH (UV ch) |
| 2592 |
\& bool isGRAPH_A (UV ch) |
| 2593 |
\& bool isGRAPH_LC (UV ch) |
| 2594 |
\& bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end) |
| 2595 |
\& bool isGRAPH_LC_uvchr (UV ch) |
| 2596 |
\& bool isGRAPH_L1 (UV ch) |
| 2597 |
\& bool isGRAPH_utf8 (U8 * s, U8 * end) |
| 2598 |
\& bool isGRAPH_utf8_safe (U8 * s, U8 * end) |
| 2599 |
\& bool isGRAPH_uvchr (UV ch) |
| 2600 |
.Ve |
| 2601 |
.RE |
| 2602 |
.RS 4 |
| 2603 |
.RE |
| 2604 |
.ie n .IP """isIDCONT""" 4 |
| 2605 |
.el .IP \f(CWisIDCONT\fR 4 |
| 2606 |
.IX Item "isIDCONT" |
| 2607 |
.PD 0 |
| 2608 |
.ie n .IP """isIDCONT_A""" 4 |
| 2609 |
.el .IP \f(CWisIDCONT_A\fR 4 |
| 2610 |
.IX Item "isIDCONT_A" |
| 2611 |
.ie n .IP """isIDCONT_LC""" 4 |
| 2612 |
.el .IP \f(CWisIDCONT_LC\fR 4 |
| 2613 |
.IX Item "isIDCONT_LC" |
| 2614 |
.ie n .IP """isIDCONT_LC_utf8_safe""" 4 |
| 2615 |
.el .IP \f(CWisIDCONT_LC_utf8_safe\fR 4 |
| 2616 |
.IX Item "isIDCONT_LC_utf8_safe" |
| 2617 |
.ie n .IP """isIDCONT_LC_uvchr""" 4 |
| 2618 |
.el .IP \f(CWisIDCONT_LC_uvchr\fR 4 |
| 2619 |
.IX Item "isIDCONT_LC_uvchr" |
| 2620 |
.ie n .IP """isIDCONT_L1""" 4 |
| 2621 |
.el .IP \f(CWisIDCONT_L1\fR 4 |
| 2622 |
.IX Item "isIDCONT_L1" |
| 2623 |
.ie n .IP """isIDCONT_utf8""" 4 |
| 2624 |
.el .IP \f(CWisIDCONT_utf8\fR 4 |
| 2625 |
.IX Item "isIDCONT_utf8" |
| 2626 |
.ie n .IP """isIDCONT_utf8_safe""" 4 |
| 2627 |
.el .IP \f(CWisIDCONT_utf8_safe\fR 4 |
| 2628 |
.IX Item "isIDCONT_utf8_safe" |
| 2629 |
.ie n .IP """isIDCONT_uvchr""" 4 |
| 2630 |
.el .IP \f(CWisIDCONT_uvchr\fR 4 |
| 2631 |
.IX Xref "isIDCONT isIDCONT_A isIDCONT_LC isIDCONT_LC_utf8_safe isIDCONT_LC_uvchr isIDCONT_L1 isIDCONT_utf8 isIDCONT_utf8_safe isIDCONT_uvchr" |
| 2632 |
.IX Item "isIDCONT_uvchr" |
| 2633 |
.PD |
| 2634 |
Returns a boolean indicating whether the specified character can be the |
| 2635 |
second or succeeding character of an identifier. This is very close to, but |
| 2636 |
not quite the same as the official Unicode property \f(CW\*(C`XID_Continue\*(C'\fR. The |
| 2637 |
difference is that this returns true only if the input character also matches |
| 2638 |
"isWORDCHAR". See the top of this section for |
| 2639 |
an explanation of the variants. |
| 2640 |
.RS 4 |
| 2641 |
.Sp |
| 2642 |
.Vb 9 |
| 2643 |
\& bool isIDCONT (UV ch) |
| 2644 |
\& bool isIDCONT_A (UV ch) |
| 2645 |
\& bool isIDCONT_LC (UV ch) |
| 2646 |
\& bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end) |
| 2647 |
\& bool isIDCONT_LC_uvchr (UV ch) |
| 2648 |
\& bool isIDCONT_L1 (UV ch) |
| 2649 |
\& bool isIDCONT_utf8 (U8 * s, U8 * end) |
| 2650 |
\& bool isIDCONT_utf8_safe (U8 * s, U8 * end) |
| 2651 |
\& bool isIDCONT_uvchr (UV ch) |
| 2652 |
.Ve |
| 2653 |
.RE |
| 2654 |
.RS 4 |
| 2655 |
.RE |
| 2656 |
.ie n .IP """isIDFIRST""" 4 |
| 2657 |
.el .IP \f(CWisIDFIRST\fR 4 |
| 2658 |
.IX Item "isIDFIRST" |
| 2659 |
.PD 0 |
| 2660 |
.ie n .IP """isIDFIRST_A""" 4 |
| 2661 |
.el .IP \f(CWisIDFIRST_A\fR 4 |
| 2662 |
.IX Item "isIDFIRST_A" |
| 2663 |
.ie n .IP """isIDFIRST_LC""" 4 |
| 2664 |
.el .IP \f(CWisIDFIRST_LC\fR 4 |
| 2665 |
.IX Item "isIDFIRST_LC" |
| 2666 |
.ie n .IP """isIDFIRST_LC_utf8_safe""" 4 |
| 2667 |
.el .IP \f(CWisIDFIRST_LC_utf8_safe\fR 4 |
| 2668 |
.IX Item "isIDFIRST_LC_utf8_safe" |
| 2669 |
.ie n .IP """isIDFIRST_LC_uvchr""" 4 |
| 2670 |
.el .IP \f(CWisIDFIRST_LC_uvchr\fR 4 |
| 2671 |
.IX Item "isIDFIRST_LC_uvchr" |
| 2672 |
.ie n .IP """isIDFIRST_L1""" 4 |
| 2673 |
.el .IP \f(CWisIDFIRST_L1\fR 4 |
| 2674 |
.IX Item "isIDFIRST_L1" |
| 2675 |
.ie n .IP """isIDFIRST_utf8""" 4 |
| 2676 |
.el .IP \f(CWisIDFIRST_utf8\fR 4 |
| 2677 |
.IX Item "isIDFIRST_utf8" |
| 2678 |
.ie n .IP """isIDFIRST_utf8_safe""" 4 |
| 2679 |
.el .IP \f(CWisIDFIRST_utf8_safe\fR 4 |
| 2680 |
.IX Item "isIDFIRST_utf8_safe" |
| 2681 |
.ie n .IP """isIDFIRST_uvchr""" 4 |
| 2682 |
.el .IP \f(CWisIDFIRST_uvchr\fR 4 |
| 2683 |
.IX Xref "isIDFIRST isIDFIRST_A isIDFIRST_LC isIDFIRST_LC_utf8_safe isIDFIRST_LC_uvchr isIDFIRST_L1 isIDFIRST_utf8 isIDFIRST_utf8_safe isIDFIRST_uvchr" |
| 2684 |
.IX Item "isIDFIRST_uvchr" |
| 2685 |
.PD |
| 2686 |
Returns a boolean indicating whether the specified character can be the first |
| 2687 |
character of an identifier. This is very close to, but not quite the same as |
| 2688 |
the official Unicode property \f(CW\*(C`XID_Start\*(C'\fR. The difference is that this |
| 2689 |
returns true only if the input character also matches "isWORDCHAR". |
| 2690 |
See the top of this section for an explanation of |
| 2691 |
the variants. |
| 2692 |
.RS 4 |
| 2693 |
.Sp |
| 2694 |
.Vb 9 |
| 2695 |
\& bool isIDFIRST (UV ch) |
| 2696 |
\& bool isIDFIRST_A (UV ch) |
| 2697 |
\& bool isIDFIRST_LC (UV ch) |
| 2698 |
\& bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end) |
| 2699 |
\& bool isIDFIRST_LC_uvchr (UV ch) |
| 2700 |
\& bool isIDFIRST_L1 (UV ch) |
| 2701 |
\& bool isIDFIRST_utf8 (U8 * s, U8 * end) |
| 2702 |
\& bool isIDFIRST_utf8_safe (U8 * s, U8 * end) |
| 2703 |
\& bool isIDFIRST_uvchr (UV ch) |
| 2704 |
.Ve |
| 2705 |
.RE |
| 2706 |
.RS 4 |
| 2707 |
.RE |
| 2708 |
.ie n .IP """isLOWER""" 4 |
| 2709 |
.el .IP \f(CWisLOWER\fR 4 |
| 2710 |
.IX Item "isLOWER" |
| 2711 |
.PD 0 |
| 2712 |
.ie n .IP """isLOWER_A""" 4 |
| 2713 |
.el .IP \f(CWisLOWER_A\fR 4 |
| 2714 |
.IX Item "isLOWER_A" |
| 2715 |
.ie n .IP """isLOWER_LC""" 4 |
| 2716 |
.el .IP \f(CWisLOWER_LC\fR 4 |
| 2717 |
.IX Item "isLOWER_LC" |
| 2718 |
.ie n .IP """isLOWER_LC_utf8_safe""" 4 |
| 2719 |
.el .IP \f(CWisLOWER_LC_utf8_safe\fR 4 |
| 2720 |
.IX Item "isLOWER_LC_utf8_safe" |
| 2721 |
.ie n .IP """isLOWER_LC_uvchr""" 4 |
| 2722 |
.el .IP \f(CWisLOWER_LC_uvchr\fR 4 |
| 2723 |
.IX Item "isLOWER_LC_uvchr" |
| 2724 |
.ie n .IP """isLOWER_L1""" 4 |
| 2725 |
.el .IP \f(CWisLOWER_L1\fR 4 |
| 2726 |
.IX Item "isLOWER_L1" |
| 2727 |
.ie n .IP """isLOWER_utf8""" 4 |
| 2728 |
.el .IP \f(CWisLOWER_utf8\fR 4 |
| 2729 |
.IX Item "isLOWER_utf8" |
| 2730 |
.ie n .IP """isLOWER_utf8_safe""" 4 |
| 2731 |
.el .IP \f(CWisLOWER_utf8_safe\fR 4 |
| 2732 |
.IX Item "isLOWER_utf8_safe" |
| 2733 |
.ie n .IP """isLOWER_uvchr""" 4 |
| 2734 |
.el .IP \f(CWisLOWER_uvchr\fR 4 |
| 2735 |
.IX Xref "isLOWER isLOWER_A isLOWER_LC isLOWER_LC_utf8_safe isLOWER_LC_uvchr isLOWER_L1 isLOWER_utf8 isLOWER_utf8_safe isLOWER_uvchr" |
| 2736 |
.IX Item "isLOWER_uvchr" |
| 2737 |
.PD |
| 2738 |
Returns a boolean indicating whether the specified character is a |
| 2739 |
lowercase character, analogous to \f(CW\*(C`m/[[:lower:]]/\*(C'\fR. |
| 2740 |
See the top of this section for an explanation of |
| 2741 |
the variants |
| 2742 |
.RS 4 |
| 2743 |
.Sp |
| 2744 |
.Vb 9 |
| 2745 |
\& bool isLOWER (UV ch) |
| 2746 |
\& bool isLOWER_A (UV ch) |
| 2747 |
\& bool isLOWER_LC (UV ch) |
| 2748 |
\& bool isLOWER_LC_utf8_safe(U8 * s, U8 *end) |
| 2749 |
\& bool isLOWER_LC_uvchr (UV ch) |
| 2750 |
\& bool isLOWER_L1 (UV ch) |
| 2751 |
\& bool isLOWER_utf8 (U8 * s, U8 * end) |
| 2752 |
\& bool isLOWER_utf8_safe (U8 * s, U8 * end) |
| 2753 |
\& bool isLOWER_uvchr (UV ch) |
| 2754 |
.Ve |
| 2755 |
.RE |
| 2756 |
.RS 4 |
| 2757 |
.RE |
| 2758 |
.ie n .IP """isOCTAL""" 4 |
| 2759 |
.el .IP \f(CWisOCTAL\fR 4 |
| 2760 |
.IX Item "isOCTAL" |
| 2761 |
.PD 0 |
| 2762 |
.ie n .IP """isOCTAL_A""" 4 |
| 2763 |
.el .IP \f(CWisOCTAL_A\fR 4 |
| 2764 |
.IX Item "isOCTAL_A" |
| 2765 |
.ie n .IP """isOCTAL_L1""" 4 |
| 2766 |
.el .IP \f(CWisOCTAL_L1\fR 4 |
| 2767 |
.IX Xref "isOCTAL isOCTAL_A isOCTAL_L1" |
| 2768 |
.IX Item "isOCTAL_L1" |
| 2769 |
.PD |
| 2770 |
Returns a boolean indicating whether the specified character is an |
| 2771 |
octal digit, [0\-7]. |
| 2772 |
The only two variants are \f(CW\*(C`isOCTAL_A\*(C'\fR and \f(CW\*(C`isOCTAL_L1\*(C'\fR; each is identical to |
| 2773 |
\&\f(CW\*(C`isOCTAL\*(C'\fR. |
| 2774 |
.RS 4 |
| 2775 |
.Sp |
| 2776 |
.Vb 1 |
| 2777 |
\& bool isOCTAL(UV ch) |
| 2778 |
.Ve |
| 2779 |
.RE |
| 2780 |
.RS 4 |
| 2781 |
.RE |
| 2782 |
.ie n .IP """isPRINT""" 4 |
| 2783 |
.el .IP \f(CWisPRINT\fR 4 |
| 2784 |
.IX Item "isPRINT" |
| 2785 |
.PD 0 |
| 2786 |
.ie n .IP """isPRINT_A""" 4 |
| 2787 |
.el .IP \f(CWisPRINT_A\fR 4 |
| 2788 |
.IX Item "isPRINT_A" |
| 2789 |
.ie n .IP """isPRINT_LC""" 4 |
| 2790 |
.el .IP \f(CWisPRINT_LC\fR 4 |
| 2791 |
.IX Item "isPRINT_LC" |
| 2792 |
.ie n .IP """isPRINT_LC_utf8_safe""" 4 |
| 2793 |
.el .IP \f(CWisPRINT_LC_utf8_safe\fR 4 |
| 2794 |
.IX Item "isPRINT_LC_utf8_safe" |
| 2795 |
.ie n .IP """isPRINT_LC_uvchr""" 4 |
| 2796 |
.el .IP \f(CWisPRINT_LC_uvchr\fR 4 |
| 2797 |
.IX Item "isPRINT_LC_uvchr" |
| 2798 |
.ie n .IP """isPRINT_L1""" 4 |
| 2799 |
.el .IP \f(CWisPRINT_L1\fR 4 |
| 2800 |
.IX Item "isPRINT_L1" |
| 2801 |
.ie n .IP """isPRINT_utf8""" 4 |
| 2802 |
.el .IP \f(CWisPRINT_utf8\fR 4 |
| 2803 |
.IX Item "isPRINT_utf8" |
| 2804 |
.ie n .IP """isPRINT_utf8_safe""" 4 |
| 2805 |
.el .IP \f(CWisPRINT_utf8_safe\fR 4 |
| 2806 |
.IX Item "isPRINT_utf8_safe" |
| 2807 |
.ie n .IP """isPRINT_uvchr""" 4 |
| 2808 |
.el .IP \f(CWisPRINT_uvchr\fR 4 |
| 2809 |
.IX Xref "isPRINT isPRINT_A isPRINT_LC isPRINT_LC_utf8_safe isPRINT_LC_uvchr isPRINT_L1 isPRINT_utf8 isPRINT_utf8_safe isPRINT_uvchr" |
| 2810 |
.IX Item "isPRINT_uvchr" |
| 2811 |
.PD |
| 2812 |
Returns a boolean indicating whether the specified character is a |
| 2813 |
printable character, analogous to \f(CW\*(C`m/[[:print:]]/\*(C'\fR. |
| 2814 |
See the top of this section for an explanation of |
| 2815 |
the variants. |
| 2816 |
.RS 4 |
| 2817 |
.Sp |
| 2818 |
.Vb 9 |
| 2819 |
\& bool isPRINT (UV ch) |
| 2820 |
\& bool isPRINT_A (UV ch) |
| 2821 |
\& bool isPRINT_LC (UV ch) |
| 2822 |
\& bool isPRINT_LC_utf8_safe(U8 * s, U8 *end) |
| 2823 |
\& bool isPRINT_LC_uvchr (UV ch) |
| 2824 |
\& bool isPRINT_L1 (UV ch) |
| 2825 |
\& bool isPRINT_utf8 (U8 * s, U8 * end) |
| 2826 |
\& bool isPRINT_utf8_safe (U8 * s, U8 * end) |
| 2827 |
\& bool isPRINT_uvchr (UV ch) |
| 2828 |
.Ve |
| 2829 |
.RE |
| 2830 |
.RS 4 |
| 2831 |
.RE |
| 2832 |
.ie n .IP """isPSXSPC""" 4 |
| 2833 |
.el .IP \f(CWisPSXSPC\fR 4 |
| 2834 |
.IX Item "isPSXSPC" |
| 2835 |
.PD 0 |
| 2836 |
.ie n .IP """isPSXSPC_A""" 4 |
| 2837 |
.el .IP \f(CWisPSXSPC_A\fR 4 |
| 2838 |
.IX Item "isPSXSPC_A" |
| 2839 |
.ie n .IP """isPSXSPC_LC""" 4 |
| 2840 |
.el .IP \f(CWisPSXSPC_LC\fR 4 |
| 2841 |
.IX Item "isPSXSPC_LC" |
| 2842 |
.ie n .IP """isPSXSPC_LC_utf8_safe""" 4 |
| 2843 |
.el .IP \f(CWisPSXSPC_LC_utf8_safe\fR 4 |
| 2844 |
.IX Item "isPSXSPC_LC_utf8_safe" |
| 2845 |
.ie n .IP """isPSXSPC_LC_uvchr""" 4 |
| 2846 |
.el .IP \f(CWisPSXSPC_LC_uvchr\fR 4 |
| 2847 |
.IX Item "isPSXSPC_LC_uvchr" |
| 2848 |
.ie n .IP """isPSXSPC_L1""" 4 |
| 2849 |
.el .IP \f(CWisPSXSPC_L1\fR 4 |
| 2850 |
.IX Item "isPSXSPC_L1" |
| 2851 |
.ie n .IP """isPSXSPC_utf8""" 4 |
| 2852 |
.el .IP \f(CWisPSXSPC_utf8\fR 4 |
| 2853 |
.IX Item "isPSXSPC_utf8" |
| 2854 |
.ie n .IP """isPSXSPC_utf8_safe""" 4 |
| 2855 |
.el .IP \f(CWisPSXSPC_utf8_safe\fR 4 |
| 2856 |
.IX Item "isPSXSPC_utf8_safe" |
| 2857 |
.ie n .IP """isPSXSPC_uvchr""" 4 |
| 2858 |
.el .IP \f(CWisPSXSPC_uvchr\fR 4 |
| 2859 |
.IX Xref "isPSXSPC isPSXSPC_A isPSXSPC_LC isPSXSPC_LC_utf8_safe isPSXSPC_LC_uvchr isPSXSPC_L1 isPSXSPC_utf8 isPSXSPC_utf8_safe isPSXSPC_uvchr" |
| 2860 |
.IX Item "isPSXSPC_uvchr" |
| 2861 |
.PD |
| 2862 |
(short for Posix Space) |
| 2863 |
Starting in 5.18, this is identical in all its forms to the |
| 2864 |
corresponding \f(CWisSPACE()\fR macros. |
| 2865 |
The locale forms of this macro are identical to their corresponding |
| 2866 |
\&\f(CWisSPACE()\fR forms in all Perl releases. In releases prior to 5.18, the |
| 2867 |
non-locale forms differ from their \f(CWisSPACE()\fR forms only in that the |
| 2868 |
\&\f(CWisSPACE()\fR forms don't match a Vertical Tab, and the \f(CWisPSXSPC()\fR forms do. |
| 2869 |
Otherwise they are identical. Thus this macro is analogous to what |
| 2870 |
\&\f(CW\*(C`m/[[:space:]]/\*(C'\fR matches in a regular expression. |
| 2871 |
See the top of this section for an explanation of |
| 2872 |
the variants. |
| 2873 |
.RS 4 |
| 2874 |
.Sp |
| 2875 |
.Vb 9 |
| 2876 |
\& bool isPSXSPC (UV ch) |
| 2877 |
\& bool isPSXSPC_A (UV ch) |
| 2878 |
\& bool isPSXSPC_LC (UV ch) |
| 2879 |
\& bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end) |
| 2880 |
\& bool isPSXSPC_LC_uvchr (UV ch) |
| 2881 |
\& bool isPSXSPC_L1 (UV ch) |
| 2882 |
\& bool isPSXSPC_utf8 (U8 * s, U8 * end) |
| 2883 |
\& bool isPSXSPC_utf8_safe (U8 * s, U8 * end) |
| 2884 |
\& bool isPSXSPC_uvchr (UV ch) |
| 2885 |
.Ve |
| 2886 |
.RE |
| 2887 |
.RS 4 |
| 2888 |
.RE |
| 2889 |
.ie n .IP """isPUNCT""" 4 |
| 2890 |
.el .IP \f(CWisPUNCT\fR 4 |
| 2891 |
.IX Item "isPUNCT" |
| 2892 |
.PD 0 |
| 2893 |
.ie n .IP """isPUNCT_A""" 4 |
| 2894 |
.el .IP \f(CWisPUNCT_A\fR 4 |
| 2895 |
.IX Item "isPUNCT_A" |
| 2896 |
.ie n .IP """isPUNCT_LC""" 4 |
| 2897 |
.el .IP \f(CWisPUNCT_LC\fR 4 |
| 2898 |
.IX Item "isPUNCT_LC" |
| 2899 |
.ie n .IP """isPUNCT_LC_utf8_safe""" 4 |
| 2900 |
.el .IP \f(CWisPUNCT_LC_utf8_safe\fR 4 |
| 2901 |
.IX Item "isPUNCT_LC_utf8_safe" |
| 2902 |
.ie n .IP """isPUNCT_LC_uvchr""" 4 |
| 2903 |
.el .IP \f(CWisPUNCT_LC_uvchr\fR 4 |
| 2904 |
.IX Item "isPUNCT_LC_uvchr" |
| 2905 |
.ie n .IP """isPUNCT_L1""" 4 |
| 2906 |
.el .IP \f(CWisPUNCT_L1\fR 4 |
| 2907 |
.IX Item "isPUNCT_L1" |
| 2908 |
.ie n .IP """isPUNCT_utf8""" 4 |
| 2909 |
.el .IP \f(CWisPUNCT_utf8\fR 4 |
| 2910 |
.IX Item "isPUNCT_utf8" |
| 2911 |
.ie n .IP """isPUNCT_utf8_safe""" 4 |
| 2912 |
.el .IP \f(CWisPUNCT_utf8_safe\fR 4 |
| 2913 |
.IX Item "isPUNCT_utf8_safe" |
| 2914 |
.ie n .IP """isPUNCT_uvchr""" 4 |
| 2915 |
.el .IP \f(CWisPUNCT_uvchr\fR 4 |
| 2916 |
.IX Xref "isPUNCT isPUNCT_A isPUNCT_LC isPUNCT_LC_utf8_safe isPUNCT_LC_uvchr isPUNCT_L1 isPUNCT_utf8 isPUNCT_utf8_safe isPUNCT_uvchr" |
| 2917 |
.IX Item "isPUNCT_uvchr" |
| 2918 |
.PD |
| 2919 |
Returns a boolean indicating whether the specified character is a |
| 2920 |
punctuation character, analogous to \f(CW\*(C`m/[[:punct:]]/\*(C'\fR. |
| 2921 |
Note that the definition of what is punctuation isn't as |
| 2922 |
straightforward as one might desire. See "POSIX Character |
| 2923 |
Classes" in perlrecharclass for details. |
| 2924 |
See the top of this section for an explanation of |
| 2925 |
the variants. |
| 2926 |
.RS 4 |
| 2927 |
.Sp |
| 2928 |
.Vb 9 |
| 2929 |
\& bool isPUNCT (UV ch) |
| 2930 |
\& bool isPUNCT_A (UV ch) |
| 2931 |
\& bool isPUNCT_LC (UV ch) |
| 2932 |
\& bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end) |
| 2933 |
\& bool isPUNCT_LC_uvchr (UV ch) |
| 2934 |
\& bool isPUNCT_L1 (UV ch) |
| 2935 |
\& bool isPUNCT_utf8 (U8 * s, U8 * end) |
| 2936 |
\& bool isPUNCT_utf8_safe (U8 * s, U8 * end) |
| 2937 |
\& bool isPUNCT_uvchr (UV ch) |
| 2938 |
.Ve |
| 2939 |
.RE |
| 2940 |
.RS 4 |
| 2941 |
.RE |
| 2942 |
.ie n .IP """isSPACE""" 4 |
| 2943 |
.el .IP \f(CWisSPACE\fR 4 |
| 2944 |
.IX Item "isSPACE" |
| 2945 |
.PD 0 |
| 2946 |
.ie n .IP """isSPACE_A""" 4 |
| 2947 |
.el .IP \f(CWisSPACE_A\fR 4 |
| 2948 |
.IX Item "isSPACE_A" |
| 2949 |
.ie n .IP """isSPACE_LC""" 4 |
| 2950 |
.el .IP \f(CWisSPACE_LC\fR 4 |
| 2951 |
.IX Item "isSPACE_LC" |
| 2952 |
.ie n .IP """isSPACE_LC_utf8_safe""" 4 |
| 2953 |
.el .IP \f(CWisSPACE_LC_utf8_safe\fR 4 |
| 2954 |
.IX Item "isSPACE_LC_utf8_safe" |
| 2955 |
.ie n .IP """isSPACE_LC_uvchr""" 4 |
| 2956 |
.el .IP \f(CWisSPACE_LC_uvchr\fR 4 |
| 2957 |
.IX Item "isSPACE_LC_uvchr" |
| 2958 |
.ie n .IP """isSPACE_L1""" 4 |
| 2959 |
.el .IP \f(CWisSPACE_L1\fR 4 |
| 2960 |
.IX Item "isSPACE_L1" |
| 2961 |
.ie n .IP """isSPACE_utf8""" 4 |
| 2962 |
.el .IP \f(CWisSPACE_utf8\fR 4 |
| 2963 |
.IX Item "isSPACE_utf8" |
| 2964 |
.ie n .IP """isSPACE_utf8_safe""" 4 |
| 2965 |
.el .IP \f(CWisSPACE_utf8_safe\fR 4 |
| 2966 |
.IX Item "isSPACE_utf8_safe" |
| 2967 |
.ie n .IP """isSPACE_uvchr""" 4 |
| 2968 |
.el .IP \f(CWisSPACE_uvchr\fR 4 |
| 2969 |
.IX Xref "isSPACE isSPACE_A isSPACE_LC isSPACE_LC_utf8_safe isSPACE_LC_uvchr isSPACE_L1 isSPACE_utf8 isSPACE_utf8_safe isSPACE_uvchr" |
| 2970 |
.IX Item "isSPACE_uvchr" |
| 2971 |
.PD |
| 2972 |
Returns a boolean indicating whether the specified character is a |
| 2973 |
whitespace character. This is analogous |
| 2974 |
to what \f(CW\*(C`m/\es/\*(C'\fR matches in a regular expression. Starting in Perl 5.18 |
| 2975 |
this also matches what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. Prior to 5.18, only the |
| 2976 |
locale forms of this macro (the ones with \f(CW\*(C`LC\*(C'\fR in their names) matched |
| 2977 |
precisely what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. In those releases, the only difference, |
| 2978 |
in the non-locale variants, was that \f(CWisSPACE()\fR did not match a vertical tab. |
| 2979 |
(See "isPSXSPC" for a macro that matches a vertical tab in all releases.) |
| 2980 |
See the top of this section for an explanation of |
| 2981 |
the variants. |
| 2982 |
.RS 4 |
| 2983 |
.Sp |
| 2984 |
.Vb 9 |
| 2985 |
\& bool isSPACE (UV ch) |
| 2986 |
\& bool isSPACE_A (UV ch) |
| 2987 |
\& bool isSPACE_LC (UV ch) |
| 2988 |
\& bool isSPACE_LC_utf8_safe(U8 * s, U8 *end) |
| 2989 |
\& bool isSPACE_LC_uvchr (UV ch) |
| 2990 |
\& bool isSPACE_L1 (UV ch) |
| 2991 |
\& bool isSPACE_utf8 (U8 * s, U8 * end) |
| 2992 |
\& bool isSPACE_utf8_safe (U8 * s, U8 * end) |
| 2993 |
\& bool isSPACE_uvchr (UV ch) |
| 2994 |
.Ve |
| 2995 |
.RE |
| 2996 |
.RS 4 |
| 2997 |
.RE |
| 2998 |
.ie n .IP """isUPPER""" 4 |
| 2999 |
.el .IP \f(CWisUPPER\fR 4 |
| 3000 |
.IX Item "isUPPER" |
| 3001 |
.PD 0 |
| 3002 |
.ie n .IP """isUPPER_A""" 4 |
| 3003 |
.el .IP \f(CWisUPPER_A\fR 4 |
| 3004 |
.IX Item "isUPPER_A" |
| 3005 |
.ie n .IP """isUPPER_LC""" 4 |
| 3006 |
.el .IP \f(CWisUPPER_LC\fR 4 |
| 3007 |
.IX Item "isUPPER_LC" |
| 3008 |
.ie n .IP """isUPPER_LC_utf8_safe""" 4 |
| 3009 |
.el .IP \f(CWisUPPER_LC_utf8_safe\fR 4 |
| 3010 |
.IX Item "isUPPER_LC_utf8_safe" |
| 3011 |
.ie n .IP """isUPPER_LC_uvchr""" 4 |
| 3012 |
.el .IP \f(CWisUPPER_LC_uvchr\fR 4 |
| 3013 |
.IX Item "isUPPER_LC_uvchr" |
| 3014 |
.ie n .IP """isUPPER_L1""" 4 |
| 3015 |
.el .IP \f(CWisUPPER_L1\fR 4 |
| 3016 |
.IX Item "isUPPER_L1" |
| 3017 |
.ie n .IP """isUPPER_utf8""" 4 |
| 3018 |
.el .IP \f(CWisUPPER_utf8\fR 4 |
| 3019 |
.IX Item "isUPPER_utf8" |
| 3020 |
.ie n .IP """isUPPER_utf8_safe""" 4 |
| 3021 |
.el .IP \f(CWisUPPER_utf8_safe\fR 4 |
| 3022 |
.IX Item "isUPPER_utf8_safe" |
| 3023 |
.ie n .IP """isUPPER_uvchr""" 4 |
| 3024 |
.el .IP \f(CWisUPPER_uvchr\fR 4 |
| 3025 |
.IX Xref "isUPPER isUPPER_A isUPPER_LC isUPPER_LC_utf8_safe isUPPER_LC_uvchr isUPPER_L1 isUPPER_utf8 isUPPER_utf8_safe isUPPER_uvchr" |
| 3026 |
.IX Item "isUPPER_uvchr" |
| 3027 |
.PD |
| 3028 |
Returns a boolean indicating whether the specified character is an |
| 3029 |
uppercase character, analogous to \f(CW\*(C`m/[[:upper:]]/\*(C'\fR. |
| 3030 |
See the top of this section for an explanation of |
| 3031 |
the variants. |
| 3032 |
.RS 4 |
| 3033 |
.Sp |
| 3034 |
.Vb 9 |
| 3035 |
\& bool isUPPER (UV ch) |
| 3036 |
\& bool isUPPER_A (UV ch) |
| 3037 |
\& bool isUPPER_LC (UV ch) |
| 3038 |
\& bool isUPPER_LC_utf8_safe(U8 * s, U8 *end) |
| 3039 |
\& bool isUPPER_LC_uvchr (UV ch) |
| 3040 |
\& bool isUPPER_L1 (UV ch) |
| 3041 |
\& bool isUPPER_utf8 (U8 * s, U8 * end) |
| 3042 |
\& bool isUPPER_utf8_safe (U8 * s, U8 * end) |
| 3043 |
\& bool isUPPER_uvchr (UV ch) |
| 3044 |
.Ve |
| 3045 |
.RE |
| 3046 |
.RS 4 |
| 3047 |
.RE |
| 3048 |
.ie n .IP """isWORDCHAR""" 4 |
| 3049 |
.el .IP \f(CWisWORDCHAR\fR 4 |
| 3050 |
.IX Item "isWORDCHAR" |
| 3051 |
.PD 0 |
| 3052 |
.ie n .IP """isWORDCHAR_A""" 4 |
| 3053 |
.el .IP \f(CWisWORDCHAR_A\fR 4 |
| 3054 |
.IX Item "isWORDCHAR_A" |
| 3055 |
.ie n .IP """isWORDCHAR_LC""" 4 |
| 3056 |
.el .IP \f(CWisWORDCHAR_LC\fR 4 |
| 3057 |
.IX Item "isWORDCHAR_LC" |
| 3058 |
.ie n .IP """isWORDCHAR_LC_utf8_safe""" 4 |
| 3059 |
.el .IP \f(CWisWORDCHAR_LC_utf8_safe\fR 4 |
| 3060 |
.IX Item "isWORDCHAR_LC_utf8_safe" |
| 3061 |
.ie n .IP """isWORDCHAR_LC_uvchr""" 4 |
| 3062 |
.el .IP \f(CWisWORDCHAR_LC_uvchr\fR 4 |
| 3063 |
.IX Item "isWORDCHAR_LC_uvchr" |
| 3064 |
.ie n .IP """isWORDCHAR_L1""" 4 |
| 3065 |
.el .IP \f(CWisWORDCHAR_L1\fR 4 |
| 3066 |
.IX Item "isWORDCHAR_L1" |
| 3067 |
.ie n .IP """isWORDCHAR_utf8""" 4 |
| 3068 |
.el .IP \f(CWisWORDCHAR_utf8\fR 4 |
| 3069 |
.IX Item "isWORDCHAR_utf8" |
| 3070 |
.ie n .IP """isWORDCHAR_utf8_safe""" 4 |
| 3071 |
.el .IP \f(CWisWORDCHAR_utf8_safe\fR 4 |
| 3072 |
.IX Item "isWORDCHAR_utf8_safe" |
| 3073 |
.ie n .IP """isWORDCHAR_uvchr""" 4 |
| 3074 |
.el .IP \f(CWisWORDCHAR_uvchr\fR 4 |
| 3075 |
.IX Xref "isWORDCHAR isWORDCHAR_A isWORDCHAR_LC isWORDCHAR_LC_utf8_safe isWORDCHAR_LC_uvchr isWORDCHAR_L1 isWORDCHAR_utf8 isWORDCHAR_utf8_safe isWORDCHAR_uvchr" |
| 3076 |
.IX Item "isWORDCHAR_uvchr" |
| 3077 |
.PD |
| 3078 |
Returns a boolean indicating whether the specified character is a character |
| 3079 |
that is a word character, analogous to what \f(CW\*(C`m/\ew/\*(C'\fR and \f(CW\*(C`m/[[:word:]]/\*(C'\fR match |
| 3080 |
in a regular expression. A word character is an alphabetic character, a |
| 3081 |
decimal digit, a connecting punctuation character (such as an underscore), or |
| 3082 |
a "mark" character that attaches to one of those (like some sort of accent). |
| 3083 |
.Sp |
| 3084 |
See the top of this section for an explanation of |
| 3085 |
the variants. |
| 3086 |
.Sp |
| 3087 |
\&\f(CW\*(C`isWORDCHAR_A\*(C'\fR, \f(CW\*(C`isWORDCHAR_L1\*(C'\fR, \f(CW\*(C`isWORDCHAR_uvchr\*(C'\fR, |
| 3088 |
\&\f(CW\*(C`isWORDCHAR_LC\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_uvchr\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_utf8\*(C'\fR, and |
| 3089 |
\&\f(CW\*(C`isWORDCHAR_LC_utf8_safe\*(C'\fR are also as described there, but additionally |
| 3090 |
include the platform's native underscore. |
| 3091 |
.RS 4 |
| 3092 |
.Sp |
| 3093 |
.Vb 9 |
| 3094 |
\& bool isWORDCHAR (UV ch) |
| 3095 |
\& bool isWORDCHAR_A (UV ch) |
| 3096 |
\& bool isWORDCHAR_LC (UV ch) |
| 3097 |
\& bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end) |
| 3098 |
\& bool isWORDCHAR_LC_uvchr (UV ch) |
| 3099 |
\& bool isWORDCHAR_L1 (UV ch) |
| 3100 |
\& bool isWORDCHAR_utf8 (U8 * s, U8 * end) |
| 3101 |
\& bool isWORDCHAR_utf8_safe (U8 * s, U8 * end) |
| 3102 |
\& bool isWORDCHAR_uvchr (UV ch) |
| 3103 |
.Ve |
| 3104 |
.RE |
| 3105 |
.RS 4 |
| 3106 |
.RE |
| 3107 |
.ie n .IP """isXDIGIT""" 4 |
| 3108 |
.el .IP \f(CWisXDIGIT\fR 4 |
| 3109 |
.IX Item "isXDIGIT" |
| 3110 |
.PD 0 |
| 3111 |
.ie n .IP """isXDIGIT_A""" 4 |
| 3112 |
.el .IP \f(CWisXDIGIT_A\fR 4 |
| 3113 |
.IX Item "isXDIGIT_A" |
| 3114 |
.ie n .IP """isXDIGIT_LC""" 4 |
| 3115 |
.el .IP \f(CWisXDIGIT_LC\fR 4 |
| 3116 |
.IX Item "isXDIGIT_LC" |
| 3117 |
.ie n .IP """isXDIGIT_LC_utf8_safe""" 4 |
| 3118 |
.el .IP \f(CWisXDIGIT_LC_utf8_safe\fR 4 |
| 3119 |
.IX Item "isXDIGIT_LC_utf8_safe" |
| 3120 |
.ie n .IP """isXDIGIT_LC_uvchr""" 4 |
| 3121 |
.el .IP \f(CWisXDIGIT_LC_uvchr\fR 4 |
| 3122 |
.IX Item "isXDIGIT_LC_uvchr" |
| 3123 |
.ie n .IP """isXDIGIT_L1""" 4 |
| 3124 |
.el .IP \f(CWisXDIGIT_L1\fR 4 |
| 3125 |
.IX Item "isXDIGIT_L1" |
| 3126 |
.ie n .IP """isXDIGIT_utf8""" 4 |
| 3127 |
.el .IP \f(CWisXDIGIT_utf8\fR 4 |
| 3128 |
.IX Item "isXDIGIT_utf8" |
| 3129 |
.ie n .IP """isXDIGIT_utf8_safe""" 4 |
| 3130 |
.el .IP \f(CWisXDIGIT_utf8_safe\fR 4 |
| 3131 |
.IX Item "isXDIGIT_utf8_safe" |
| 3132 |
.ie n .IP """isXDIGIT_uvchr""" 4 |
| 3133 |
.el .IP \f(CWisXDIGIT_uvchr\fR 4 |
| 3134 |
.IX Xref "isXDIGIT isXDIGIT_A isXDIGIT_LC isXDIGIT_LC_utf8_safe isXDIGIT_LC_uvchr isXDIGIT_L1 isXDIGIT_utf8 isXDIGIT_utf8_safe isXDIGIT_uvchr" |
| 3135 |
.IX Item "isXDIGIT_uvchr" |
| 3136 |
.PD |
| 3137 |
Returns a boolean indicating whether the specified character is a hexadecimal |
| 3138 |
digit. In the ASCII range these are \f(CW\*(C`[0\-9A\-Fa\-f]\*(C'\fR. Variants \f(CWisXDIGIT_A()\fR |
| 3139 |
and \f(CWisXDIGIT_L1()\fR are identical to \f(CWisXDIGIT()\fR. |
| 3140 |
See the top of this section for an explanation of |
| 3141 |
the variants. |
| 3142 |
.RS 4 |
| 3143 |
.Sp |
| 3144 |
.Vb 9 |
| 3145 |
\& bool isXDIGIT (UV ch) |
| 3146 |
\& bool isXDIGIT_A (UV ch) |
| 3147 |
\& bool isXDIGIT_LC (UV ch) |
| 3148 |
\& bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end) |
| 3149 |
\& bool isXDIGIT_LC_uvchr (UV ch) |
| 3150 |
\& bool isXDIGIT_L1 (UV ch) |
| 3151 |
\& bool isXDIGIT_utf8 (U8 * s, U8 * end) |
| 3152 |
\& bool isXDIGIT_utf8_safe (U8 * s, U8 * end) |
| 3153 |
\& bool isXDIGIT_uvchr (UV ch) |
| 3154 |
.Ve |
| 3155 |
.RE |
| 3156 |
.RS 4 |
| 3157 |
.RE |
| 3158 |
.SH "Compiler and Preprocessor information" |
| 3159 |
.IX Header "Compiler and Preprocessor information" |
| 3160 |
.ie n .IP """CPPLAST""" 4 |
| 3161 |
.el .IP \f(CWCPPLAST\fR 4 |
| 3162 |
.IX Xref "CPPLAST" |
| 3163 |
.IX Item "CPPLAST" |
| 3164 |
This symbol is intended to be used along with \f(CW\*(C`CPPRUN\*(C'\fR in the same manner |
| 3165 |
symbol \f(CW\*(C`CPPMINUS\*(C'\fR is used with \f(CW\*(C`CPPSTDIN\*(C'\fR. It contains either "\-" or "". |
| 3166 |
.ie n .IP """CPPMINUS""" 4 |
| 3167 |
.el .IP \f(CWCPPMINUS\fR 4 |
| 3168 |
.IX Xref "CPPMINUS" |
| 3169 |
.IX Item "CPPMINUS" |
| 3170 |
This symbol contains the second part of the string which will invoke |
| 3171 |
the C preprocessor on the standard input and produce to standard |
| 3172 |
output. This symbol will have the value "\-" if \f(CW\*(C`CPPSTDIN\*(C'\fR needs a minus |
| 3173 |
to specify standard input, otherwise the value is "". |
| 3174 |
.ie n .IP """CPPRUN""" 4 |
| 3175 |
.el .IP \f(CWCPPRUN\fR 4 |
| 3176 |
.IX Xref "CPPRUN" |
| 3177 |
.IX Item "CPPRUN" |
| 3178 |
This symbol contains the string which will invoke a C preprocessor on |
| 3179 |
the standard input and produce to standard output. It needs to end |
| 3180 |
with \f(CW\*(C`CPPLAST\*(C'\fR, after all other preprocessor flags have been specified. |
| 3181 |
The main difference with \f(CW\*(C`CPPSTDIN\*(C'\fR is that this program will never be a |
| 3182 |
pointer to a shell wrapper, i.e. it will be empty if no preprocessor is |
| 3183 |
available directly to the user. Note that it may well be different from |
| 3184 |
the preprocessor used to compile the C program. |
| 3185 |
.ie n .IP """CPPSTDIN""" 4 |
| 3186 |
.el .IP \f(CWCPPSTDIN\fR 4 |
| 3187 |
.IX Xref "CPPSTDIN" |
| 3188 |
.IX Item "CPPSTDIN" |
| 3189 |
This symbol contains the first part of the string which will invoke |
| 3190 |
the C preprocessor on the standard input and produce to standard |
| 3191 |
output. Typical value of "cc \-E" or "\fI/lib/cpp\fR", but it can also |
| 3192 |
call a wrapper. See \f(CW"CPPRUN"\fR. |
| 3193 |
.ie n .IP """HASATTRIBUTE_ALWAYS_INLINE""" 4 |
| 3194 |
.el .IP \f(CWHASATTRIBUTE_ALWAYS_INLINE\fR 4 |
| 3195 |
.IX Xref "HASATTRIBUTE_ALWAYS_INLINE" |
| 3196 |
.IX Item "HASATTRIBUTE_ALWAYS_INLINE" |
| 3197 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should always be |
| 3198 |
inlined. |
| 3199 |
.ie n .IP """HASATTRIBUTE_DEPRECATED""" 4 |
| 3200 |
.el .IP \f(CWHASATTRIBUTE_DEPRECATED\fR 4 |
| 3201 |
.IX Xref "HASATTRIBUTE_DEPRECATED" |
| 3202 |
.IX Item "HASATTRIBUTE_DEPRECATED" |
| 3203 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for marking deprecated \f(CW\*(C`APIs\*(C'\fR |
| 3204 |
.ie n .IP """HASATTRIBUTE_FORMAT""" 4 |
| 3205 |
.el .IP \f(CWHASATTRIBUTE_FORMAT\fR 4 |
| 3206 |
.IX Xref "HASATTRIBUTE_FORMAT" |
| 3207 |
.IX Item "HASATTRIBUTE_FORMAT" |
| 3208 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for checking printf-style formats |
| 3209 |
.ie n .IP """HASATTRIBUTE_NONNULL""" 4 |
| 3210 |
.el .IP \f(CWHASATTRIBUTE_NONNULL\fR 4 |
| 3211 |
.IX Xref "HASATTRIBUTE_NONNULL" |
| 3212 |
.IX Item "HASATTRIBUTE_NONNULL" |
| 3213 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for nonnull function parms. |
| 3214 |
.ie n .IP """HASATTRIBUTE_NORETURN""" 4 |
| 3215 |
.el .IP \f(CWHASATTRIBUTE_NORETURN\fR 4 |
| 3216 |
.IX Xref "HASATTRIBUTE_NORETURN" |
| 3217 |
.IX Item "HASATTRIBUTE_NORETURN" |
| 3218 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that do not return |
| 3219 |
.ie n .IP """HASATTRIBUTE_PURE""" 4 |
| 3220 |
.el .IP \f(CWHASATTRIBUTE_PURE\fR 4 |
| 3221 |
.IX Xref "HASATTRIBUTE_PURE" |
| 3222 |
.IX Item "HASATTRIBUTE_PURE" |
| 3223 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for pure functions |
| 3224 |
.ie n .IP """HASATTRIBUTE_UNUSED""" 4 |
| 3225 |
.el .IP \f(CWHASATTRIBUTE_UNUSED\fR 4 |
| 3226 |
.IX Xref "HASATTRIBUTE_UNUSED" |
| 3227 |
.IX Item "HASATTRIBUTE_UNUSED" |
| 3228 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for unused variables and arguments |
| 3229 |
.ie n .IP """HASATTRIBUTE_VISIBILITY""" 4 |
| 3230 |
.el .IP \f(CWHASATTRIBUTE_VISIBILITY\fR 4 |
| 3231 |
.IX Xref "HASATTRIBUTE_VISIBILITY" |
| 3232 |
.IX Item "HASATTRIBUTE_VISIBILITY" |
| 3233 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should have a |
| 3234 |
different visibility. |
| 3235 |
.ie n .IP """HASATTRIBUTE_WARN_UNUSED_RESULT""" 4 |
| 3236 |
.el .IP \f(CWHASATTRIBUTE_WARN_UNUSED_RESULT\fR 4 |
| 3237 |
.IX Xref "HASATTRIBUTE_WARN_UNUSED_RESULT" |
| 3238 |
.IX Item "HASATTRIBUTE_WARN_UNUSED_RESULT" |
| 3239 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for warning on unused results |
| 3240 |
.ie n .IP """HAS_BUILTIN_ADD_OVERFLOW""" 4 |
| 3241 |
.el .IP \f(CWHAS_BUILTIN_ADD_OVERFLOW\fR 4 |
| 3242 |
.IX Xref "HAS_BUILTIN_ADD_OVERFLOW" |
| 3243 |
.IX Item "HAS_BUILTIN_ADD_OVERFLOW" |
| 3244 |
This symbol, if defined, indicates that the compiler supports |
| 3245 |
\&\f(CW\*(C`_\|_builtin_add_overflow\*(C'\fR for adding integers with overflow checks. |
| 3246 |
.ie n .IP """HAS_BUILTIN_CHOOSE_EXPR""" 4 |
| 3247 |
.el .IP \f(CWHAS_BUILTIN_CHOOSE_EXPR\fR 4 |
| 3248 |
.IX Xref "HAS_BUILTIN_CHOOSE_EXPR" |
| 3249 |
.IX Item "HAS_BUILTIN_CHOOSE_EXPR" |
| 3250 |
Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for compile-time ternary-like expressions |
| 3251 |
.ie n .IP """HAS_BUILTIN_EXPECT""" 4 |
| 3252 |
.el .IP \f(CWHAS_BUILTIN_EXPECT\fR 4 |
| 3253 |
.IX Xref "HAS_BUILTIN_EXPECT" |
| 3254 |
.IX Item "HAS_BUILTIN_EXPECT" |
| 3255 |
Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for telling that certain values are more |
| 3256 |
likely |
| 3257 |
.ie n .IP """HAS_BUILTIN_MUL_OVERFLOW""" 4 |
| 3258 |
.el .IP \f(CWHAS_BUILTIN_MUL_OVERFLOW\fR 4 |
| 3259 |
.IX Xref "HAS_BUILTIN_MUL_OVERFLOW" |
| 3260 |
.IX Item "HAS_BUILTIN_MUL_OVERFLOW" |
| 3261 |
This symbol, if defined, indicates that the compiler supports |
| 3262 |
\&\f(CW\*(C`_\|_builtin_mul_overflow\*(C'\fR for multiplying integers with overflow checks. |
| 3263 |
.ie n .IP """HAS_BUILTIN_SUB_OVERFLOW""" 4 |
| 3264 |
.el .IP \f(CWHAS_BUILTIN_SUB_OVERFLOW\fR 4 |
| 3265 |
.IX Xref "HAS_BUILTIN_SUB_OVERFLOW" |
| 3266 |
.IX Item "HAS_BUILTIN_SUB_OVERFLOW" |
| 3267 |
This symbol, if defined, indicates that the compiler supports |
| 3268 |
\&\f(CW\*(C`_\|_builtin_sub_overflow\*(C'\fR for subtracting integers with overflow checks. |
| 3269 |
.ie n .IP """HAS_C99_VARIADIC_MACROS""" 4 |
| 3270 |
.el .IP \f(CWHAS_C99_VARIADIC_MACROS\fR 4 |
| 3271 |
.IX Xref "HAS_C99_VARIADIC_MACROS" |
| 3272 |
.IX Item "HAS_C99_VARIADIC_MACROS" |
| 3273 |
If defined, the compiler supports C99 variadic macros. |
| 3274 |
.ie n .IP """HAS_STATIC_INLINE""" 4 |
| 3275 |
.el .IP \f(CWHAS_STATIC_INLINE\fR 4 |
| 3276 |
.IX Xref "HAS_STATIC_INLINE" |
| 3277 |
.IX Item "HAS_STATIC_INLINE" |
| 3278 |
This symbol, if defined, indicates that the C compiler supports |
| 3279 |
C99\-style static inline. That is, the function can't be called |
| 3280 |
from another translation unit. |
| 3281 |
.ie n .IP """MEM_ALIGNBYTES""" 4 |
| 3282 |
.el .IP \f(CWMEM_ALIGNBYTES\fR 4 |
| 3283 |
.IX Xref "MEM_ALIGNBYTES" |
| 3284 |
.IX Item "MEM_ALIGNBYTES" |
| 3285 |
This symbol contains the number of bytes required to align a |
| 3286 |
double, or a long double when applicable. Usual values are 2, |
| 3287 |
4 and 8. The default is eight, for safety. For cross-compiling |
| 3288 |
or multiarch support, Configure will set a minimum of 8. |
| 3289 |
.ie n .IP """PERL_STATIC_INLINE""" 4 |
| 3290 |
.el .IP \f(CWPERL_STATIC_INLINE\fR 4 |
| 3291 |
.IX Xref "PERL_STATIC_INLINE" |
| 3292 |
.IX Item "PERL_STATIC_INLINE" |
| 3293 |
This symbol gives the best-guess incantation to use for static |
| 3294 |
inline functions. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is defined, this will |
| 3295 |
give C99\-style inline. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is not defined, |
| 3296 |
this will give a plain 'static'. It will always be defined |
| 3297 |
to something that gives static linkage. |
| 3298 |
Possibilities include |
| 3299 |
.Sp |
| 3300 |
.Vb 5 |
| 3301 |
\& static inline (c99) |
| 3302 |
\& static _\|_inline_\|_ (gcc \-ansi) |
| 3303 |
\& static _\|_inline (MSVC) |
| 3304 |
\& static _inline (older MSVC) |
| 3305 |
\& static (c89 compilers) |
| 3306 |
.Ve |
| 3307 |
.ie n .IP """PERL_THREAD_LOCAL""" 4 |
| 3308 |
.el .IP \f(CWPERL_THREAD_LOCAL\fR 4 |
| 3309 |
.IX Xref "PERL_THREAD_LOCAL" |
| 3310 |
.IX Item "PERL_THREAD_LOCAL" |
| 3311 |
This symbol, if defined, gives a linkage specification for thread-local |
| 3312 |
storage. For example, for a C11 compiler this will be \f(CW\*(C`_Thread_local\*(C'\fR. |
| 3313 |
Beware, some compilers are sensitive to the C language standard they are |
| 3314 |
told to parse. For example, suncc defaults to C11, so our probe will |
| 3315 |
report that \f(CW\*(C`_Thread_local\*(C'\fR can be used. However, if the \-std=c99 is later |
| 3316 |
added to the compiler flags, then \f(CW\*(C`_Thread_local\*(C'\fR will become a syntax |
| 3317 |
error. Hence it is important for these flags to be consistent between |
| 3318 |
probing and use. |
| 3319 |
.ie n .IP """U32_ALIGNMENT_REQUIRED""" 4 |
| 3320 |
.el .IP \f(CWU32_ALIGNMENT_REQUIRED\fR 4 |
| 3321 |
.IX Xref "U32_ALIGNMENT_REQUIRED" |
| 3322 |
.IX Item "U32_ALIGNMENT_REQUIRED" |
| 3323 |
This symbol, if defined, indicates that you must access |
| 3324 |
character data through U32\-aligned pointers. |
| 3325 |
.SH "Compiler directives" |
| 3326 |
.IX Header "Compiler directives" |
| 3327 |
.ie n .IP """_\|_ASSERT_""" 4 |
| 3328 |
.el .IP \f(CW_\|_ASSERT_\fR 4 |
| 3329 |
.IX Xref "__ASSERT_" |
| 3330 |
.IX Item "__ASSERT_" |
| 3331 |
This is a helper macro to avoid preprocessor issues, replaced by nothing |
| 3332 |
unless under DEBUGGING, where it expands to an assert of its argument, |
| 3333 |
followed by a comma (hence the comma operator). If we just used a straight |
| 3334 |
\&\fBassert()\fR, we would get a comma with nothing before it when not DEBUGGING. |
| 3335 |
.RS 4 |
| 3336 |
.Sp |
| 3337 |
.Vb 1 |
| 3338 |
\& _\|_ASSERT_(bool expr) |
| 3339 |
.Ve |
| 3340 |
.RE |
| 3341 |
.RS 4 |
| 3342 |
.RE |
| 3343 |
.ie n .IP """ASSUME""" 4 |
| 3344 |
.el .IP \f(CWASSUME\fR 4 |
| 3345 |
.IX Xref "ASSUME" |
| 3346 |
.IX Item "ASSUME" |
| 3347 |
\&\f(CW\*(C`ASSUME\*(C'\fR is like \f(CWassert()\fR, but it has a benefit in a release build. It is a |
| 3348 |
hint to a compiler about a statement of fact in a function call free |
| 3349 |
expression, which allows the compiler to generate better machine code. In a |
| 3350 |
debug build, \f(CWASSUME(x)\fR is a synonym for \f(CWassert(x)\fR. \f(CWASSUME(0)\fR means the |
| 3351 |
control path is unreachable. In a for loop, \f(CW\*(C`ASSUME\*(C'\fR can be used to hint that |
| 3352 |
a loop will run at least X times. \f(CW\*(C`ASSUME\*(C'\fR is based off MSVC's \f(CW\*(C`_\|_assume\*(C'\fR |
| 3353 |
intrinsic function, see its documents for more details. |
| 3354 |
.RS 4 |
| 3355 |
.Sp |
| 3356 |
.Vb 1 |
| 3357 |
\& ASSUME(bool expr) |
| 3358 |
.Ve |
| 3359 |
.RE |
| 3360 |
.RS 4 |
| 3361 |
.RE |
| 3362 |
.ie n .IP """dNOOP""" 4 |
| 3363 |
.el .IP \f(CWdNOOP\fR 4 |
| 3364 |
.IX Xref "dNOOP" |
| 3365 |
.IX Item "dNOOP" |
| 3366 |
Declare nothing; typically used as a placeholder to replace something that used |
| 3367 |
to declare something. Works on compilers that require declarations before any |
| 3368 |
code. |
| 3369 |
.RS 4 |
| 3370 |
.Sp |
| 3371 |
.Vb 1 |
| 3372 |
\& dNOOP; |
| 3373 |
.Ve |
| 3374 |
.RE |
| 3375 |
.RS 4 |
| 3376 |
.RE |
| 3377 |
.ie n .IP """END_EXTERN_C""" 4 |
| 3378 |
.el .IP \f(CWEND_EXTERN_C\fR 4 |
| 3379 |
.IX Xref "END_EXTERN_C" |
| 3380 |
.IX Item "END_EXTERN_C" |
| 3381 |
When not compiling using C++, expands to nothing. |
| 3382 |
Otherwise ends a section of code already begun by a \f(CW"START_EXTERN_C"\fR. |
| 3383 |
.RS 4 |
| 3384 |
.Sp |
| 3385 |
.Vb 1 |
| 3386 |
\& END_EXTERN_C |
| 3387 |
.Ve |
| 3388 |
.RE |
| 3389 |
.RS 4 |
| 3390 |
.RE |
| 3391 |
.ie n .IP """EXTERN_C""" 4 |
| 3392 |
.el .IP \f(CWEXTERN_C\fR 4 |
| 3393 |
.IX Xref "EXTERN_C" |
| 3394 |
.IX Item "EXTERN_C" |
| 3395 |
When not compiling using C++, expands to nothing. |
| 3396 |
Otherwise is used in a declaration of a function to indicate the function |
| 3397 |
should have external C linkage. This is required for things to work for just |
| 3398 |
about all functions with external linkage compiled into perl. |
| 3399 |
Often, you can use \f(CW"START_EXTERN_C"\fR ... \f(CW"END_EXTERN_C"\fR blocks |
| 3400 |
surrounding all your code that you need to have this linkage. |
| 3401 |
.Sp |
| 3402 |
Example usage: |
| 3403 |
.Sp |
| 3404 |
.Vb 1 |
| 3405 |
\& EXTERN_C int flock(int fd, int op); |
| 3406 |
.Ve |
| 3407 |
.ie n .IP """LIKELY""" 4 |
| 3408 |
.el .IP \f(CWLIKELY\fR 4 |
| 3409 |
.IX Xref "LIKELY" |
| 3410 |
.IX Item "LIKELY" |
| 3411 |
Returns the input unchanged, but at the same time it gives a branch prediction |
| 3412 |
hint to the compiler that this condition is likely to be true. |
| 3413 |
.RS 4 |
| 3414 |
.Sp |
| 3415 |
.Vb 1 |
| 3416 |
\& LIKELY(bool expr) |
| 3417 |
.Ve |
| 3418 |
.RE |
| 3419 |
.RS 4 |
| 3420 |
.RE |
| 3421 |
.ie n .IP """NOOP""" 4 |
| 3422 |
.el .IP \f(CWNOOP\fR 4 |
| 3423 |
.IX Xref "NOOP" |
| 3424 |
.IX Item "NOOP" |
| 3425 |
Do nothing; typically used as a placeholder to replace something that used to |
| 3426 |
do something. |
| 3427 |
.RS 4 |
| 3428 |
.Sp |
| 3429 |
.Vb 1 |
| 3430 |
\& NOOP; |
| 3431 |
.Ve |
| 3432 |
.RE |
| 3433 |
.RS 4 |
| 3434 |
.RE |
| 3435 |
.ie n .IP """PERL_UNUSED_ARG""" 4 |
| 3436 |
.el .IP \f(CWPERL_UNUSED_ARG\fR 4 |
| 3437 |
.IX Xref "PERL_UNUSED_ARG" |
| 3438 |
.IX Item "PERL_UNUSED_ARG" |
| 3439 |
This is used to suppress compiler warnings that a parameter to a function is |
| 3440 |
not used. This situation can arise, for example, when a parameter is needed |
| 3441 |
under some configuration conditions, but not others, so that C preprocessor |
| 3442 |
conditional compilation causes it be used just sometimes. |
| 3443 |
.RS 4 |
| 3444 |
.Sp |
| 3445 |
.Vb 1 |
| 3446 |
\& PERL_UNUSED_ARG(void x); |
| 3447 |
.Ve |
| 3448 |
.RE |
| 3449 |
.RS 4 |
| 3450 |
.RE |
| 3451 |
.ie n .IP """PERL_UNUSED_CONTEXT""" 4 |
| 3452 |
.el .IP \f(CWPERL_UNUSED_CONTEXT\fR 4 |
| 3453 |
.IX Xref "PERL_UNUSED_CONTEXT" |
| 3454 |
.IX Item "PERL_UNUSED_CONTEXT" |
| 3455 |
This is used to suppress compiler warnings that the thread context parameter to |
| 3456 |
a function is not used. This situation can arise, for example, when a |
| 3457 |
C preprocessor conditional compilation causes it be used just some times. |
| 3458 |
.RS 4 |
| 3459 |
.Sp |
| 3460 |
.Vb 1 |
| 3461 |
\& PERL_UNUSED_CONTEXT; |
| 3462 |
.Ve |
| 3463 |
.RE |
| 3464 |
.RS 4 |
| 3465 |
.RE |
| 3466 |
.ie n .IP """PERL_UNUSED_DECL""" 4 |
| 3467 |
.el .IP \f(CWPERL_UNUSED_DECL\fR 4 |
| 3468 |
.IX Xref "PERL_UNUSED_DECL" |
| 3469 |
.IX Item "PERL_UNUSED_DECL" |
| 3470 |
Tells the compiler that the parameter in the function prototype just before it |
| 3471 |
is not necessarily expected to be used in the function. Not that many |
| 3472 |
compilers understand this, so this should only be used in cases where |
| 3473 |
\&\f(CW"PERL_UNUSED_ARG"\fR can't conveniently be used. |
| 3474 |
.Sp |
| 3475 |
Example usage: |
| 3476 |
.RS 4 |
| 3477 |
.Sp |
| 3478 |
.Vb 3 |
| 3479 |
\& Signal_t |
| 3480 |
\& Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL, |
| 3481 |
\& void *uap PERL_UNUSED_DECL, bool safe) |
| 3482 |
.Ve |
| 3483 |
.RE |
| 3484 |
.RS 4 |
| 3485 |
.RE |
| 3486 |
.ie n .IP """PERL_UNUSED_RESULT""" 4 |
| 3487 |
.el .IP \f(CWPERL_UNUSED_RESULT\fR 4 |
| 3488 |
.IX Xref "PERL_UNUSED_RESULT" |
| 3489 |
.IX Item "PERL_UNUSED_RESULT" |
| 3490 |
This macro indicates to discard the return value of the function call inside |
| 3491 |
it, \fIe.g.\fR, |
| 3492 |
.Sp |
| 3493 |
.Vb 1 |
| 3494 |
\& PERL_UNUSED_RESULT(foo(a, b)) |
| 3495 |
.Ve |
| 3496 |
.Sp |
| 3497 |
The main reason for this is that the combination of \f(CW\*(C`gcc \-Wunused\-result\*(C'\fR |
| 3498 |
(part of \f(CW\*(C`\-Wall\*(C'\fR) and the \f(CW\*(C`_\|_attribute_\|_((warn_unused_result))\*(C'\fR cannot |
| 3499 |
be silenced with casting to \f(CW\*(C`void\*(C'\fR. This causes trouble when the system |
| 3500 |
header files use the attribute. |
| 3501 |
.Sp |
| 3502 |
Use \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR sparingly, though, since usually the warning |
| 3503 |
is there for a good reason: you might lose success/failure information, |
| 3504 |
or leak resources, or changes in resources. |
| 3505 |
.Sp |
| 3506 |
But sometimes you just want to ignore the return value, \fIe.g.\fR, on |
| 3507 |
codepaths soon ending up in abort, or in "best effort" attempts, |
| 3508 |
or in situations where there is no good way to handle failures. |
| 3509 |
.Sp |
| 3510 |
Sometimes \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR might not be the most natural way: |
| 3511 |
another possibility is that you can capture the return value |
| 3512 |
and use \f(CW"PERL_UNUSED_VAR"\fR on that. |
| 3513 |
.RS 4 |
| 3514 |
.Sp |
| 3515 |
.Vb 1 |
| 3516 |
\& PERL_UNUSED_RESULT(void x) |
| 3517 |
.Ve |
| 3518 |
.RE |
| 3519 |
.RS 4 |
| 3520 |
.RE |
| 3521 |
.ie n .IP """PERL_UNUSED_VAR""" 4 |
| 3522 |
.el .IP \f(CWPERL_UNUSED_VAR\fR 4 |
| 3523 |
.IX Xref "PERL_UNUSED_VAR" |
| 3524 |
.IX Item "PERL_UNUSED_VAR" |
| 3525 |
This is used to suppress compiler warnings that the variable \fIx\fR is not used. |
| 3526 |
This situation can arise, for example, when a C preprocessor conditional |
| 3527 |
compilation causes it be used just some times. |
| 3528 |
.RS 4 |
| 3529 |
.Sp |
| 3530 |
.Vb 1 |
| 3531 |
\& PERL_UNUSED_VAR(void x); |
| 3532 |
.Ve |
| 3533 |
.RE |
| 3534 |
.RS 4 |
| 3535 |
.RE |
| 3536 |
.ie n .IP """START_EXTERN_C""" 4 |
| 3537 |
.el .IP \f(CWSTART_EXTERN_C\fR 4 |
| 3538 |
.IX Xref "START_EXTERN_C" |
| 3539 |
.IX Item "START_EXTERN_C" |
| 3540 |
When not compiling using C++, expands to nothing. |
| 3541 |
Otherwise begins a section of code in which every function will effectively |
| 3542 |
have \f(CW"EXTERN_C"\fR applied to it, that is to have external C linkage. The |
| 3543 |
section is ended by a \f(CW"END_EXTERN_C"\fR. |
| 3544 |
.RS 4 |
| 3545 |
.Sp |
| 3546 |
.Vb 1 |
| 3547 |
\& START_EXTERN_C |
| 3548 |
.Ve |
| 3549 |
.RE |
| 3550 |
.RS 4 |
| 3551 |
.RE |
| 3552 |
.ie n .IP """STATIC""" 4 |
| 3553 |
.el .IP \f(CWSTATIC\fR 4 |
| 3554 |
.IX Item "STATIC" |
| 3555 |
Described in perlguts. |
| 3556 |
.ie n .IP """STMT_END""" 4 |
| 3557 |
.el .IP \f(CWSTMT_END\fR 4 |
| 3558 |
.IX Item "STMT_END" |
| 3559 |
.PD 0 |
| 3560 |
.ie n .IP """STMT_START""" 4 |
| 3561 |
.el .IP \f(CWSTMT_START\fR 4 |
| 3562 |
.IX Xref "STMT_END STMT_START" |
| 3563 |
.IX Item "STMT_START" |
| 3564 |
.PD |
| 3565 |
These allow a series of statements in a macro to be used as a single statement, |
| 3566 |
as in |
| 3567 |
.Sp |
| 3568 |
.Vb 1 |
| 3569 |
\& if (x) STMT_START { ... } STMT_END else ... |
| 3570 |
.Ve |
| 3571 |
.Sp |
| 3572 |
Note that you can't return a value out of this construct and cannot use it as |
| 3573 |
an operand to the comma operator. These limit its utility. |
| 3574 |
.Sp |
| 3575 |
But, a value could be returned by constructing the API so that a pointer is |
| 3576 |
passed and the macro dereferences this to set the return. If the value can be |
| 3577 |
any of various types, depending on context, you can handle that situation in |
| 3578 |
some situations by adding the type of the return as an extra accompanying |
| 3579 |
parameter: |
| 3580 |
.Sp |
| 3581 |
.Vb 3 |
| 3582 |
\& #define foo(param, type) STMT_START { |
| 3583 |
\& type * param; *param = do_calc; ... |
| 3584 |
\& } STMT_END |
| 3585 |
.Ve |
| 3586 |
.Sp |
| 3587 |
This could be awkward, so consider instead using a C language \f(CW\*(C`static inline\*(C'\fR |
| 3588 |
function. |
| 3589 |
.Sp |
| 3590 |
If you do use this construct, it is easy to forget that it is a macro and not a |
| 3591 |
function, and hence fall into traps that might not show up until someone |
| 3592 |
someday writes code which contains names that clash with the ones you chose |
| 3593 |
here, or calls it with a parameter which is an expression with side effects, |
| 3594 |
the consequences of which you didn't think about. See "Writing |
| 3595 |
safer macros" in perlhacktips for how to avoid these. |
| 3596 |
.ie n .IP """UNLIKELY""" 4 |
| 3597 |
.el .IP \f(CWUNLIKELY\fR 4 |
| 3598 |
.IX Xref "UNLIKELY" |
| 3599 |
.IX Item "UNLIKELY" |
| 3600 |
Returns the input unchanged, but at the same time it gives a branch prediction |
| 3601 |
hint to the compiler that this condition is likely to be false. |
| 3602 |
.RS 4 |
| 3603 |
.Sp |
| 3604 |
.Vb 1 |
| 3605 |
\& UNLIKELY(bool expr) |
| 3606 |
.Ve |
| 3607 |
.RE |
| 3608 |
.RS 4 |
| 3609 |
.RE |
| 3610 |
.SH "Compile-time scope hooks" |
| 3611 |
.IX Header "Compile-time scope hooks" |
| 3612 |
.ie n .IP """BhkDISABLE""" 4 |
| 3613 |
.el .IP \f(CWBhkDISABLE\fR 4 |
| 3614 |
.IX Xref "BhkDISABLE" |
| 3615 |
.IX Item "BhkDISABLE" |
| 3616 |
NOTE: \f(CW\*(C`BhkDISABLE\*(C'\fR is \fBexperimental\fR and may change or be |
| 3617 |
removed without notice. |
| 3618 |
.Sp |
| 3619 |
Temporarily disable an entry in this BHK structure, by clearing the |
| 3620 |
appropriate flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which |
| 3621 |
entry to disable. |
| 3622 |
.RS 4 |
| 3623 |
.Sp |
| 3624 |
.Vb 1 |
| 3625 |
\& void BhkDISABLE(BHK *hk, token which) |
| 3626 |
.Ve |
| 3627 |
.RE |
| 3628 |
.RS 4 |
| 3629 |
.RE |
| 3630 |
.ie n .IP """BhkENABLE""" 4 |
| 3631 |
.el .IP \f(CWBhkENABLE\fR 4 |
| 3632 |
.IX Xref "BhkENABLE" |
| 3633 |
.IX Item "BhkENABLE" |
| 3634 |
NOTE: \f(CW\*(C`BhkENABLE\*(C'\fR is \fBexperimental\fR and may change or be |
| 3635 |
removed without notice. |
| 3636 |
.Sp |
| 3637 |
Re-enable an entry in this BHK structure, by setting the appropriate |
| 3638 |
flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which entry to enable. |
| 3639 |
This will assert (under \-DDEBUGGING) if the entry doesn't contain a valid |
| 3640 |
pointer. |
| 3641 |
.RS 4 |
| 3642 |
.Sp |
| 3643 |
.Vb 1 |
| 3644 |
\& void BhkENABLE(BHK *hk, token which) |
| 3645 |
.Ve |
| 3646 |
.RE |
| 3647 |
.RS 4 |
| 3648 |
.RE |
| 3649 |
.ie n .IP """BhkENTRY_set""" 4 |
| 3650 |
.el .IP \f(CWBhkENTRY_set\fR 4 |
| 3651 |
.IX Xref "BhkENTRY_set" |
| 3652 |
.IX Item "BhkENTRY_set" |
| 3653 |
NOTE: \f(CW\*(C`BhkENTRY_set\*(C'\fR is \fBexperimental\fR and may change or be |
| 3654 |
removed without notice. |
| 3655 |
.Sp |
| 3656 |
Set an entry in the BHK structure, and set the flags to indicate it is |
| 3657 |
valid. \f(CW\*(C`which\*(C'\fR is a preprocessing token indicating which entry to set. |
| 3658 |
The type of \f(CW\*(C`ptr\*(C'\fR depends on the entry. |
| 3659 |
.RS 4 |
| 3660 |
.Sp |
| 3661 |
.Vb 1 |
| 3662 |
\& void BhkENTRY_set(BHK *hk, token which, void *ptr) |
| 3663 |
.Ve |
| 3664 |
.RE |
| 3665 |
.RS 4 |
| 3666 |
.RE |
| 3667 |
.ie n .IP """blockhook_register""" 4 |
| 3668 |
.el .IP \f(CWblockhook_register\fR 4 |
| 3669 |
.IX Xref "blockhook_register" |
| 3670 |
.IX Item "blockhook_register" |
| 3671 |
NOTE: \f(CW\*(C`blockhook_register\*(C'\fR is \fBexperimental\fR and may change or be |
| 3672 |
removed without notice. |
| 3673 |
.Sp |
| 3674 |
Register a set of hooks to be called when the Perl lexical scope changes |
| 3675 |
at compile time. See "Compile-time scope hooks" in perlguts. |
| 3676 |
.Sp |
| 3677 |
NOTE: \f(CW\*(C`blockhook_register\*(C'\fR must be explicitly called as |
| 3678 |
\&\f(CW\*(C`Perl_blockhook_register\*(C'\fR |
| 3679 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 3680 |
.RS 4 |
| 3681 |
.Sp |
| 3682 |
.Vb 1 |
| 3683 |
\& void Perl_blockhook_register(pTHX_ BHK *hk) |
| 3684 |
.Ve |
| 3685 |
.RE |
| 3686 |
.RS 4 |
| 3687 |
.RE |
| 3688 |
.SH Concurrency |
| 3689 |
.IX Header "Concurrency" |
| 3690 |
.ie n .IP """aTHX""" 4 |
| 3691 |
.el .IP \f(CWaTHX\fR 4 |
| 3692 |
.IX Item "aTHX" |
| 3693 |
Described in perlguts. |
| 3694 |
.ie n .IP """aTHX_""" 4 |
| 3695 |
.el .IP \f(CWaTHX_\fR 4 |
| 3696 |
.IX Item "aTHX_" |
| 3697 |
Described in perlguts. |
| 3698 |
.ie n .IP """CPERLscope""" 4 |
| 3699 |
.el .IP \f(CWCPERLscope\fR 4 |
| 3700 |
.IX Xref "CPERLscope" |
| 3701 |
.IX Item "CPERLscope" |
| 3702 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`CPERLscope\*(C'\fR |
| 3703 |
from a future release of Perl. Do not use it for |
| 3704 |
new code; remove it from existing code. |
| 3705 |
.Sp |
| 3706 |
Now a no-op. |
| 3707 |
.RS 4 |
| 3708 |
.Sp |
| 3709 |
.Vb 1 |
| 3710 |
\& void CPERLscope(void x) |
| 3711 |
.Ve |
| 3712 |
.RE |
| 3713 |
.RS 4 |
| 3714 |
.RE |
| 3715 |
.ie n .IP """dTHR""" 4 |
| 3716 |
.el .IP \f(CWdTHR\fR 4 |
| 3717 |
.IX Item "dTHR" |
| 3718 |
Described in perlguts. |
| 3719 |
.ie n .IP """dTHX""" 4 |
| 3720 |
.el .IP \f(CWdTHX\fR 4 |
| 3721 |
.IX Item "dTHX" |
| 3722 |
Described in perlguts. |
| 3723 |
.ie n .IP """dTHXa""" 4 |
| 3724 |
.el .IP \f(CWdTHXa\fR 4 |
| 3725 |
.IX Xref "dTHXa" |
| 3726 |
.IX Item "dTHXa" |
| 3727 |
On threaded perls, set \f(CW\*(C`pTHX\*(C'\fR to \f(CW\*(C`a\*(C'\fR; on unthreaded perls, do nothing |
| 3728 |
.ie n .IP """dTHXoa""" 4 |
| 3729 |
.el .IP \f(CWdTHXoa\fR 4 |
| 3730 |
.IX Xref "dTHXoa" |
| 3731 |
.IX Item "dTHXoa" |
| 3732 |
Now a synonym for \f(CW"dTHXa"\fR. |
| 3733 |
.ie n .IP """dVAR""" 4 |
| 3734 |
.el .IP \f(CWdVAR\fR 4 |
| 3735 |
.IX Xref "dVAR" |
| 3736 |
.IX Item "dVAR" |
| 3737 |
This is now a synonym for dNOOP: declare nothing |
| 3738 |
.ie n .IP """GETENV_PRESERVES_OTHER_THREAD""" 4 |
| 3739 |
.el .IP \f(CWGETENV_PRESERVES_OTHER_THREAD\fR 4 |
| 3740 |
.IX Xref "GETENV_PRESERVES_OTHER_THREAD" |
| 3741 |
.IX Item "GETENV_PRESERVES_OTHER_THREAD" |
| 3742 |
This symbol, if defined, indicates that the getenv system call doesn't |
| 3743 |
zap the static buffer of \f(CWgetenv()\fR in a different thread. |
| 3744 |
The typical \f(CWgetenv()\fR implementation will return a pointer to the proper |
| 3745 |
position in **environ. But some may instead copy them to a static |
| 3746 |
buffer in \f(CWgetenv()\fR. If there is a per-thread instance of that buffer, |
| 3747 |
or the return points to **environ, then a many\-reader/1\-writer mutex |
| 3748 |
will work; otherwise an exclusive locking mutex is required to prevent |
| 3749 |
races. |
| 3750 |
.ie n .IP """HAS_PTHREAD_ATFORK""" 4 |
| 3751 |
.el .IP \f(CWHAS_PTHREAD_ATFORK\fR 4 |
| 3752 |
.IX Xref "HAS_PTHREAD_ATFORK" |
| 3753 |
.IX Item "HAS_PTHREAD_ATFORK" |
| 3754 |
This symbol, if defined, indicates that the \f(CW\*(C`pthread_atfork\*(C'\fR routine |
| 3755 |
is available to setup fork handlers. |
| 3756 |
.ie n .IP """HAS_PTHREAD_ATTR_SETSCOPE""" 4 |
| 3757 |
.el .IP \f(CWHAS_PTHREAD_ATTR_SETSCOPE\fR 4 |
| 3758 |
.IX Xref "HAS_PTHREAD_ATTR_SETSCOPE" |
| 3759 |
.IX Item "HAS_PTHREAD_ATTR_SETSCOPE" |
| 3760 |
This symbol, if defined, indicates that the \f(CW\*(C`pthread_attr_setscope\*(C'\fR |
| 3761 |
system call is available to set the contention scope attribute of |
| 3762 |
a thread attribute object. |
| 3763 |
.ie n .IP """HAS_PTHREAD_YIELD""" 4 |
| 3764 |
.el .IP \f(CWHAS_PTHREAD_YIELD\fR 4 |
| 3765 |
.IX Xref "HAS_PTHREAD_YIELD" |
| 3766 |
.IX Item "HAS_PTHREAD_YIELD" |
| 3767 |
This symbol, if defined, indicates that the \f(CW\*(C`pthread_yield\*(C'\fR |
| 3768 |
routine is available to yield the execution of the current |
| 3769 |
thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR. |
| 3770 |
.ie n .IP """HAS_SCHED_YIELD""" 4 |
| 3771 |
.el .IP \f(CWHAS_SCHED_YIELD\fR 4 |
| 3772 |
.IX Xref "HAS_SCHED_YIELD" |
| 3773 |
.IX Item "HAS_SCHED_YIELD" |
| 3774 |
This symbol, if defined, indicates that the \f(CW\*(C`sched_yield\*(C'\fR |
| 3775 |
routine is available to yield the execution of the current |
| 3776 |
thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR. |
| 3777 |
.ie n .IP """I_MACH_CTHREADS""" 4 |
| 3778 |
.el .IP \f(CWI_MACH_CTHREADS\fR 4 |
| 3779 |
.IX Xref "I_MACH_CTHREADS" |
| 3780 |
.IX Item "I_MACH_CTHREADS" |
| 3781 |
This symbol, if defined, indicates to the C program that it should |
| 3782 |
include \fImach/cthreads.h\fR. |
| 3783 |
.RS 4 |
| 3784 |
.Sp |
| 3785 |
.Vb 3 |
| 3786 |
\& #ifdef I_MACH_CTHREADS |
| 3787 |
\& #include <mach_cthreads.h> |
| 3788 |
\& #endif |
| 3789 |
.Ve |
| 3790 |
.RE |
| 3791 |
.RS 4 |
| 3792 |
.RE |
| 3793 |
.ie n .IP """I_PTHREAD""" 4 |
| 3794 |
.el .IP \f(CWI_PTHREAD\fR 4 |
| 3795 |
.IX Xref "I_PTHREAD" |
| 3796 |
.IX Item "I_PTHREAD" |
| 3797 |
This symbol, if defined, indicates to the C program that it should |
| 3798 |
include \fIpthread.h\fR. |
| 3799 |
.RS 4 |
| 3800 |
.Sp |
| 3801 |
.Vb 3 |
| 3802 |
\& #ifdef I_PTHREAD |
| 3803 |
\& #include <pthread.h> |
| 3804 |
\& #endif |
| 3805 |
.Ve |
| 3806 |
.RE |
| 3807 |
.RS 4 |
| 3808 |
.RE |
| 3809 |
.ie n .IP """MULTIPLICITY""" 4 |
| 3810 |
.el .IP \f(CWMULTIPLICITY\fR 4 |
| 3811 |
.IX Item "MULTIPLICITY" |
| 3812 |
This symbol, if defined, indicates that Perl should |
| 3813 |
be built to use multiplicity. |
| 3814 |
.ie n .IP """OLD_PTHREAD_CREATE_JOINABLE""" 4 |
| 3815 |
.el .IP \f(CWOLD_PTHREAD_CREATE_JOINABLE\fR 4 |
| 3816 |
.IX Xref "OLD_PTHREAD_CREATE_JOINABLE" |
| 3817 |
.IX Item "OLD_PTHREAD_CREATE_JOINABLE" |
| 3818 |
This symbol, if defined, indicates how to create pthread |
| 3819 |
in joinable (aka undetached) state. \f(CW\*(C`NOTE\*(C'\fR: not defined |
| 3820 |
if \fIpthread.h\fR already has defined \f(CW\*(C`PTHREAD_CREATE_JOINABLE\*(C'\fR |
| 3821 |
(the new version of the constant). |
| 3822 |
If defined, known values are \f(CW\*(C`PTHREAD_CREATE_UNDETACHED\*(C'\fR |
| 3823 |
and \f(CW\*(C`_\|_UNDETACHED\*(C'\fR. |
| 3824 |
.ie n .IP """OLD_PTHREADS_API""" 4 |
| 3825 |
.el .IP \f(CWOLD_PTHREADS_API\fR 4 |
| 3826 |
.IX Xref "OLD_PTHREADS_API" |
| 3827 |
.IX Item "OLD_PTHREADS_API" |
| 3828 |
This symbol, if defined, indicates that Perl should |
| 3829 |
be built to use the old draft \f(CW\*(C`POSIX\*(C'\fR threads \f(CW\*(C`API\*(C'\fR. |
| 3830 |
.ie n .IP """PERL_IMPLICIT_CONTEXT""" 4 |
| 3831 |
.el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4 |
| 3832 |
.IX Item "PERL_IMPLICIT_CONTEXT" |
| 3833 |
Described in perlguts. |
| 3834 |
.ie n .IP """PERL_NO_GET_CONTEXT""" 4 |
| 3835 |
.el .IP \f(CWPERL_NO_GET_CONTEXT\fR 4 |
| 3836 |
.IX Item "PERL_NO_GET_CONTEXT" |
| 3837 |
Described in perlguts. |
| 3838 |
.ie n .IP """pTHX""" 4 |
| 3839 |
.el .IP \f(CWpTHX\fR 4 |
| 3840 |
.IX Item "pTHX" |
| 3841 |
Described in perlguts. |
| 3842 |
.ie n .IP """pTHX_""" 4 |
| 3843 |
.el .IP \f(CWpTHX_\fR 4 |
| 3844 |
.IX Item "pTHX_" |
| 3845 |
Described in perlguts. |
| 3846 |
.ie n .IP """SCHED_YIELD""" 4 |
| 3847 |
.el .IP \f(CWSCHED_YIELD\fR 4 |
| 3848 |
.IX Xref "SCHED_YIELD" |
| 3849 |
.IX Item "SCHED_YIELD" |
| 3850 |
This symbol defines the way to yield the execution of |
| 3851 |
the current thread. Known ways are \f(CW\*(C`sched_yield\*(C'\fR, |
| 3852 |
\&\f(CW\*(C`pthread_yield\*(C'\fR, and \f(CW\*(C`pthread_yield\*(C'\fR with \f(CW\*(C`NULL\*(C'\fR. |
| 3853 |
.SH "COPs and Hint Hashes" |
| 3854 |
.IX Xref "COPHH_KEY_UTF8" |
| 3855 |
.IX Header "COPs and Hint Hashes" |
| 3856 |
.ie n .IP """cop_fetch_label""" 4 |
| 3857 |
.el .IP \f(CWcop_fetch_label\fR 4 |
| 3858 |
.IX Xref "cop_fetch_label" |
| 3859 |
.IX Item "cop_fetch_label" |
| 3860 |
NOTE: \f(CW\*(C`cop_fetch_label\*(C'\fR is \fBexperimental\fR and may change or be |
| 3861 |
removed without notice. |
| 3862 |
.Sp |
| 3863 |
Returns the label attached to a cop, and stores its length in bytes into |
| 3864 |
\&\f(CW*len\fR. |
| 3865 |
Upon return, \f(CW*flags\fR will be set to either \f(CW\*(C`SVf_UTF8\*(C'\fR or 0. |
| 3866 |
.Sp |
| 3867 |
Alternatively, use the macro \f(CW"CopLABEL_len_flags"\fR; |
| 3868 |
or if you don't need to know if the label is UTF\-8 or not, the macro |
| 3869 |
\&\f(CW"CopLABEL_len"\fR; |
| 3870 |
or if you additionally don't need to know the length, \f(CW"CopLABEL"\fR. |
| 3871 |
.RS 4 |
| 3872 |
.Sp |
| 3873 |
.Vb 2 |
| 3874 |
\& const char * cop_fetch_label(COP * const cop, STRLEN *len, |
| 3875 |
\& U32 *flags) |
| 3876 |
.Ve |
| 3877 |
.RE |
| 3878 |
.RS 4 |
| 3879 |
.RE |
| 3880 |
.ie n .IP """CopFILE""" 4 |
| 3881 |
.el .IP \f(CWCopFILE\fR 4 |
| 3882 |
.IX Xref "CopFILE" |
| 3883 |
.IX Item "CopFILE" |
| 3884 |
Returns the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 3885 |
.RS 4 |
| 3886 |
.Sp |
| 3887 |
.Vb 1 |
| 3888 |
\& const char * CopFILE(const COP * c) |
| 3889 |
.Ve |
| 3890 |
.RE |
| 3891 |
.RS 4 |
| 3892 |
.RE |
| 3893 |
.ie n .IP """CopFILEAV""" 4 |
| 3894 |
.el .IP \f(CWCopFILEAV\fR 4 |
| 3895 |
.IX Xref "CopFILEAV" |
| 3896 |
.IX Item "CopFILEAV" |
| 3897 |
Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, creating it if necessary. |
| 3898 |
.RS 4 |
| 3899 |
.Sp |
| 3900 |
.Vb 1 |
| 3901 |
\& AV * CopFILEAV(const COP * c) |
| 3902 |
.Ve |
| 3903 |
.RE |
| 3904 |
.RS 4 |
| 3905 |
.RE |
| 3906 |
.ie n .IP """CopFILEAVn""" 4 |
| 3907 |
.el .IP \f(CWCopFILEAVn\fR 4 |
| 3908 |
.IX Xref "CopFILEAVn" |
| 3909 |
.IX Item "CopFILEAVn" |
| 3910 |
Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, returning NULL if it |
| 3911 |
doesn't already exist. |
| 3912 |
.RS 4 |
| 3913 |
.Sp |
| 3914 |
.Vb 1 |
| 3915 |
\& AV * CopFILEAVn(const COP * c) |
| 3916 |
.Ve |
| 3917 |
.RE |
| 3918 |
.RS 4 |
| 3919 |
.RE |
| 3920 |
.ie n .IP """CopFILE_copy""" 4 |
| 3921 |
.el .IP \f(CWCopFILE_copy\fR 4 |
| 3922 |
.IX Xref "CopFILE_copy" |
| 3923 |
.IX Item "CopFILE_copy" |
| 3924 |
Efficiently copies the cop file name from one COP to another. Wraps |
| 3925 |
the required logic to do a refcounted copy under threads or not. |
| 3926 |
.RS 4 |
| 3927 |
.Sp |
| 3928 |
.Vb 1 |
| 3929 |
\& void CopFILE_copy(COP * dst, COP * src) |
| 3930 |
.Ve |
| 3931 |
.RE |
| 3932 |
.RS 4 |
| 3933 |
.RE |
| 3934 |
.ie n .IP """CopFILE_free""" 4 |
| 3935 |
.el .IP \f(CWCopFILE_free\fR 4 |
| 3936 |
.IX Xref "CopFILE_free" |
| 3937 |
.IX Item "CopFILE_free" |
| 3938 |
Frees the file data in a cop. Under the hood this is a refcounting |
| 3939 |
operation. |
| 3940 |
.RS 4 |
| 3941 |
.Sp |
| 3942 |
.Vb 1 |
| 3943 |
\& void CopFILE_free(COP * c) |
| 3944 |
.Ve |
| 3945 |
.RE |
| 3946 |
.RS 4 |
| 3947 |
.RE |
| 3948 |
.ie n .IP """CopFILEGV""" 4 |
| 3949 |
.el .IP \f(CWCopFILEGV\fR 4 |
| 3950 |
.IX Xref "CopFILEGV" |
| 3951 |
.IX Item "CopFILEGV" |
| 3952 |
Returns the GV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 3953 |
.RS 4 |
| 3954 |
.Sp |
| 3955 |
.Vb 1 |
| 3956 |
\& GV * CopFILEGV(const COP * c) |
| 3957 |
.Ve |
| 3958 |
.RE |
| 3959 |
.RS 4 |
| 3960 |
.RE |
| 3961 |
.ie n .IP """CopFILEGV_set""" 4 |
| 3962 |
.el .IP \f(CWCopFILEGV_set\fR 4 |
| 3963 |
.IX Xref "CopFILEGV_set" |
| 3964 |
.IX Item "CopFILEGV_set" |
| 3965 |
Available only on unthreaded perls. Makes \f(CW\*(C`pv\*(C'\fR the name of the file |
| 3966 |
associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 3967 |
.RS 4 |
| 3968 |
.Sp |
| 3969 |
.Vb 1 |
| 3970 |
\& void CopFILEGV_set(COP *c, GV *gv) |
| 3971 |
.Ve |
| 3972 |
.RE |
| 3973 |
.RS 4 |
| 3974 |
.RE |
| 3975 |
.ie n .IP """CopFILE_LEN""" 4 |
| 3976 |
.el .IP \f(CWCopFILE_LEN\fR 4 |
| 3977 |
.IX Xref "CopFILE_LEN" |
| 3978 |
.IX Item "CopFILE_LEN" |
| 3979 |
Returns the length of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 3980 |
.RS 4 |
| 3981 |
.Sp |
| 3982 |
.Vb 1 |
| 3983 |
\& const char * CopFILE_LEN(const COP * c) |
| 3984 |
.Ve |
| 3985 |
.RE |
| 3986 |
.RS 4 |
| 3987 |
.RE |
| 3988 |
.ie n .IP """CopFILE_set""" 4 |
| 3989 |
.el .IP \f(CWCopFILE_set\fR 4 |
| 3990 |
.IX Xref "CopFILE_set" |
| 3991 |
.IX Item "CopFILE_set" |
| 3992 |
Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 3993 |
.RS 4 |
| 3994 |
.Sp |
| 3995 |
.Vb 1 |
| 3996 |
\& void CopFILE_set(COP * c, const char * pv) |
| 3997 |
.Ve |
| 3998 |
.RE |
| 3999 |
.RS 4 |
| 4000 |
.RE |
| 4001 |
.ie n .IP """CopFILE_setn""" 4 |
| 4002 |
.el .IP \f(CWCopFILE_setn\fR 4 |
| 4003 |
.IX Xref "CopFILE_setn" |
| 4004 |
.IX Item "CopFILE_setn" |
| 4005 |
Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 4006 |
.RS 4 |
| 4007 |
.Sp |
| 4008 |
.Vb 1 |
| 4009 |
\& void CopFILE_setn(COP * c, const char * pv, STRLEN len) |
| 4010 |
.Ve |
| 4011 |
.RE |
| 4012 |
.RS 4 |
| 4013 |
.RE |
| 4014 |
.ie n .IP """CopFILESV""" 4 |
| 4015 |
.el .IP \f(CWCopFILESV\fR 4 |
| 4016 |
.IX Xref "CopFILESV" |
| 4017 |
.IX Item "CopFILESV" |
| 4018 |
Returns the SV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 4019 |
.RS 4 |
| 4020 |
.Sp |
| 4021 |
.Vb 1 |
| 4022 |
\& SV * CopFILESV(const COP * c) |
| 4023 |
.Ve |
| 4024 |
.RE |
| 4025 |
.RS 4 |
| 4026 |
.RE |
| 4027 |
.ie n .IP """cophh_copy""" 4 |
| 4028 |
.el .IP \f(CWcophh_copy\fR 4 |
| 4029 |
.IX Xref "cophh_copy" |
| 4030 |
.IX Item "cophh_copy" |
| 4031 |
NOTE: \f(CW\*(C`cophh_copy\*(C'\fR is \fBexperimental\fR and may change or be |
| 4032 |
removed without notice. |
| 4033 |
.Sp |
| 4034 |
Make and return a complete copy of the cop hints hash \f(CW\*(C`cophh\*(C'\fR. |
| 4035 |
.RS 4 |
| 4036 |
.Sp |
| 4037 |
.Vb 1 |
| 4038 |
\& COPHH * cophh_copy(COPHH *cophh) |
| 4039 |
.Ve |
| 4040 |
.RE |
| 4041 |
.RS 4 |
| 4042 |
.RE |
| 4043 |
.ie n .IP """cophh_delete_pv""" 4 |
| 4044 |
.el .IP \f(CWcophh_delete_pv\fR 4 |
| 4045 |
.IX Item "cophh_delete_pv" |
| 4046 |
.PD 0 |
| 4047 |
.ie n .IP """cophh_delete_pvn""" 4 |
| 4048 |
.el .IP \f(CWcophh_delete_pvn\fR 4 |
| 4049 |
.IX Item "cophh_delete_pvn" |
| 4050 |
.ie n .IP """cophh_delete_pvs""" 4 |
| 4051 |
.el .IP \f(CWcophh_delete_pvs\fR 4 |
| 4052 |
.IX Item "cophh_delete_pvs" |
| 4053 |
.ie n .IP """cophh_delete_sv""" 4 |
| 4054 |
.el .IP \f(CWcophh_delete_sv\fR 4 |
| 4055 |
.IX Xref "cophh_delete_pv cophh_delete_pvn cophh_delete_pvs cophh_delete_sv" |
| 4056 |
.IX Item "cophh_delete_sv" |
| 4057 |
.PD |
| 4058 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 4059 |
removed without notice. |
| 4060 |
.Sp |
| 4061 |
These delete a key and its associated value from the cop hints hash \f(CW\*(C`cophh\*(C'\fR, |
| 4062 |
and return the modified hash. The returned hash pointer is in general |
| 4063 |
not the same as the hash pointer that was passed in. The input hash is |
| 4064 |
consumed by the function, and the pointer to it must not be subsequently |
| 4065 |
used. Use "cophh_copy" if you need both hashes. |
| 4066 |
.Sp |
| 4067 |
The forms differ in how the key is specified. In all forms, the key is pointed |
| 4068 |
to by \f(CW\*(C`key\*(C'\fR. |
| 4069 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4070 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4071 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4072 |
the string, which hence, may contain embedded-NUL characters. |
| 4073 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4074 |
using \f(CW"SvPV_const"\fR. |
| 4075 |
.Sp |
| 4076 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4077 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4078 |
automatically at compile time. |
| 4079 |
.Sp |
| 4080 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4081 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4082 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4083 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4084 |
the octets. |
| 4085 |
.RS 4 |
| 4086 |
.Sp |
| 4087 |
.Vb 7 |
| 4088 |
\& COPHH * cophh_delete_pv (COPHH *cophh, const char *key, U32 hash, |
| 4089 |
\& U32 flags) |
| 4090 |
\& COPHH * cophh_delete_pvn(COPHH *cophh, const char *key, |
| 4091 |
\& STRLEN keylen, U32 hash, U32 flags) |
| 4092 |
\& COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags) |
| 4093 |
\& COPHH * cophh_delete_sv (COPHH *cophh, SV *key, U32 hash, |
| 4094 |
\& U32 flags) |
| 4095 |
.Ve |
| 4096 |
.RE |
| 4097 |
.RS 4 |
| 4098 |
.RE |
| 4099 |
.ie n .IP """cophh_exists_pvn""" 4 |
| 4100 |
.el .IP \f(CWcophh_exists_pvn\fR 4 |
| 4101 |
.IX Xref "cophh_exists_pvn" |
| 4102 |
.IX Item "cophh_exists_pvn" |
| 4103 |
NOTE: \f(CW\*(C`cophh_exists_pvn\*(C'\fR is \fBexperimental\fR and may change or be |
| 4104 |
removed without notice. |
| 4105 |
.Sp |
| 4106 |
These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by |
| 4107 |
\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists, |
| 4108 |
and false otherwise. |
| 4109 |
.Sp |
| 4110 |
The forms differ in how the key is specified. |
| 4111 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4112 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4113 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4114 |
the string, which hence, may contain embedded-NUL characters. |
| 4115 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4116 |
using \f(CW"SvPV_const"\fR. |
| 4117 |
.Sp |
| 4118 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4119 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4120 |
automatically at compile time. |
| 4121 |
.Sp |
| 4122 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4123 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4124 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4125 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4126 |
the octets. |
| 4127 |
.RS 4 |
| 4128 |
.Sp |
| 4129 |
.Vb 2 |
| 4130 |
\& bool cophh_exists_pvn(const COPHH *cophh, const char *key, |
| 4131 |
\& STRLEN keylen, U32 hash, U32 flags) |
| 4132 |
.Ve |
| 4133 |
.RE |
| 4134 |
.RS 4 |
| 4135 |
.RE |
| 4136 |
.ie n .IP """cophh_fetch_pv""" 4 |
| 4137 |
.el .IP \f(CWcophh_fetch_pv\fR 4 |
| 4138 |
.IX Item "cophh_fetch_pv" |
| 4139 |
.PD 0 |
| 4140 |
.ie n .IP """cophh_fetch_pvn""" 4 |
| 4141 |
.el .IP \f(CWcophh_fetch_pvn\fR 4 |
| 4142 |
.IX Item "cophh_fetch_pvn" |
| 4143 |
.ie n .IP """cophh_fetch_pvs""" 4 |
| 4144 |
.el .IP \f(CWcophh_fetch_pvs\fR 4 |
| 4145 |
.IX Item "cophh_fetch_pvs" |
| 4146 |
.ie n .IP """cophh_fetch_sv""" 4 |
| 4147 |
.el .IP \f(CWcophh_fetch_sv\fR 4 |
| 4148 |
.IX Xref "cophh_fetch_pv cophh_fetch_pvn cophh_fetch_pvs cophh_fetch_sv" |
| 4149 |
.IX Item "cophh_fetch_sv" |
| 4150 |
.PD |
| 4151 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 4152 |
removed without notice. |
| 4153 |
.Sp |
| 4154 |
These look up the entry in the cop hints hash \f(CW\*(C`cophh\*(C'\fR with the key specified by |
| 4155 |
\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal |
| 4156 |
scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the |
| 4157 |
key. |
| 4158 |
.Sp |
| 4159 |
The forms differ in how the key is specified. |
| 4160 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4161 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4162 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4163 |
the string, which hence, may contain embedded-NUL characters. |
| 4164 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4165 |
using \f(CW"SvPV_const"\fR. |
| 4166 |
.Sp |
| 4167 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4168 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4169 |
automatically at compile time. |
| 4170 |
.Sp |
| 4171 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4172 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4173 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4174 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4175 |
the octets. |
| 4176 |
.RS 4 |
| 4177 |
.Sp |
| 4178 |
.Vb 7 |
| 4179 |
\& SV * cophh_fetch_pv (const COPHH *cophh, const char *key, |
| 4180 |
\& U32 hash, U32 flags) |
| 4181 |
\& SV * cophh_fetch_pvn(const COPHH *cophh, const char *key, |
| 4182 |
\& STRLEN keylen, U32 hash, U32 flags) |
| 4183 |
\& SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags) |
| 4184 |
\& SV * cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash, |
| 4185 |
\& U32 flags) |
| 4186 |
.Ve |
| 4187 |
.RE |
| 4188 |
.RS 4 |
| 4189 |
.RE |
| 4190 |
.ie n .IP """cophh_free""" 4 |
| 4191 |
.el .IP \f(CWcophh_free\fR 4 |
| 4192 |
.IX Xref "cophh_free" |
| 4193 |
.IX Item "cophh_free" |
| 4194 |
NOTE: \f(CW\*(C`cophh_free\*(C'\fR is \fBexperimental\fR and may change or be |
| 4195 |
removed without notice. |
| 4196 |
.Sp |
| 4197 |
Discard the cop hints hash \f(CW\*(C`cophh\*(C'\fR, freeing all resources associated |
| 4198 |
with it. |
| 4199 |
.RS 4 |
| 4200 |
.Sp |
| 4201 |
.Vb 1 |
| 4202 |
\& void cophh_free(COPHH *cophh) |
| 4203 |
.Ve |
| 4204 |
.RE |
| 4205 |
.RS 4 |
| 4206 |
.RE |
| 4207 |
.ie n .IP """cophh_2hv""" 4 |
| 4208 |
.el .IP \f(CWcophh_2hv\fR 4 |
| 4209 |
.IX Xref "cophh_2hv" |
| 4210 |
.IX Item "cophh_2hv" |
| 4211 |
NOTE: \f(CW\*(C`cophh_2hv\*(C'\fR is \fBexperimental\fR and may change or be |
| 4212 |
removed without notice. |
| 4213 |
.Sp |
| 4214 |
Generates and returns a standard Perl hash representing the full set of |
| 4215 |
key/value pairs in the cop hints hash \f(CW\*(C`cophh\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently |
| 4216 |
unused and must be zero. |
| 4217 |
.RS 4 |
| 4218 |
.Sp |
| 4219 |
.Vb 1 |
| 4220 |
\& HV * cophh_2hv(const COPHH *cophh, U32 flags) |
| 4221 |
.Ve |
| 4222 |
.RE |
| 4223 |
.RS 4 |
| 4224 |
.RE |
| 4225 |
.ie n .IP """cophh_new_empty""" 4 |
| 4226 |
.el .IP \f(CWcophh_new_empty\fR 4 |
| 4227 |
.IX Xref "cophh_new_empty" |
| 4228 |
.IX Item "cophh_new_empty" |
| 4229 |
NOTE: \f(CW\*(C`cophh_new_empty\*(C'\fR is \fBexperimental\fR and may change or be |
| 4230 |
removed without notice. |
| 4231 |
.Sp |
| 4232 |
Generate and return a fresh cop hints hash containing no entries. |
| 4233 |
.RS 4 |
| 4234 |
.Sp |
| 4235 |
.Vb 1 |
| 4236 |
\& COPHH * cophh_new_empty() |
| 4237 |
.Ve |
| 4238 |
.RE |
| 4239 |
.RS 4 |
| 4240 |
.RE |
| 4241 |
.ie n .IP """cophh_store_pv""" 4 |
| 4242 |
.el .IP \f(CWcophh_store_pv\fR 4 |
| 4243 |
.IX Item "cophh_store_pv" |
| 4244 |
.PD 0 |
| 4245 |
.ie n .IP """cophh_store_pvn""" 4 |
| 4246 |
.el .IP \f(CWcophh_store_pvn\fR 4 |
| 4247 |
.IX Item "cophh_store_pvn" |
| 4248 |
.ie n .IP """cophh_store_pvs""" 4 |
| 4249 |
.el .IP \f(CWcophh_store_pvs\fR 4 |
| 4250 |
.IX Item "cophh_store_pvs" |
| 4251 |
.ie n .IP """cophh_store_sv""" 4 |
| 4252 |
.el .IP \f(CWcophh_store_sv\fR 4 |
| 4253 |
.IX Xref "cophh_store_pv cophh_store_pvn cophh_store_pvs cophh_store_sv" |
| 4254 |
.IX Item "cophh_store_sv" |
| 4255 |
.PD |
| 4256 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 4257 |
removed without notice. |
| 4258 |
.Sp |
| 4259 |
These store a value, associated with a key, in the cop hints hash \f(CW\*(C`cophh\*(C'\fR, |
| 4260 |
and return the modified hash. The returned hash pointer is in general |
| 4261 |
not the same as the hash pointer that was passed in. The input hash is |
| 4262 |
consumed by the function, and the pointer to it must not be subsequently |
| 4263 |
used. Use "cophh_copy" if you need both hashes. |
| 4264 |
.Sp |
| 4265 |
\&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key. \f(CW\*(C`value\*(C'\fR is copied |
| 4266 |
by these functions, which thus do not take ownership of any reference |
| 4267 |
to it, and hence later changes to the scalar will not be reflected in the value |
| 4268 |
visible in the cop hints hash. Complex types of scalar will not be stored with |
| 4269 |
referential integrity, but will be coerced to strings. |
| 4270 |
.Sp |
| 4271 |
The forms differ in how the key is specified. In all forms, the key is pointed |
| 4272 |
to by \f(CW\*(C`key\*(C'\fR. |
| 4273 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4274 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4275 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4276 |
the string, which hence, may contain embedded-NUL characters. |
| 4277 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4278 |
using \f(CW"SvPV_const"\fR. |
| 4279 |
.Sp |
| 4280 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4281 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4282 |
automatically at compile time. |
| 4283 |
.Sp |
| 4284 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4285 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4286 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4287 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4288 |
the octets. |
| 4289 |
.RS 4 |
| 4290 |
.Sp |
| 4291 |
.Vb 9 |
| 4292 |
\& COPHH * cophh_store_pv (COPHH *cophh, const char *key, U32 hash, |
| 4293 |
\& SV *value, U32 flags) |
| 4294 |
\& COPHH * cophh_store_pvn(COPHH *cophh, const char *key, |
| 4295 |
\& STRLEN keylen, U32 hash, SV *value, |
| 4296 |
\& U32 flags) |
| 4297 |
\& COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value, |
| 4298 |
\& U32 flags) |
| 4299 |
\& COPHH * cophh_store_sv (COPHH *cophh, SV *key, U32 hash, |
| 4300 |
\& SV *value, U32 flags) |
| 4301 |
.Ve |
| 4302 |
.RE |
| 4303 |
.RS 4 |
| 4304 |
.RE |
| 4305 |
.ie n .IP """cop_hints_exists_pv""" 4 |
| 4306 |
.el .IP \f(CWcop_hints_exists_pv\fR 4 |
| 4307 |
.IX Item "cop_hints_exists_pv" |
| 4308 |
.PD 0 |
| 4309 |
.ie n .IP """cop_hints_exists_pvn""" 4 |
| 4310 |
.el .IP \f(CWcop_hints_exists_pvn\fR 4 |
| 4311 |
.IX Item "cop_hints_exists_pvn" |
| 4312 |
.ie n .IP """cop_hints_exists_pvs""" 4 |
| 4313 |
.el .IP \f(CWcop_hints_exists_pvs\fR 4 |
| 4314 |
.IX Item "cop_hints_exists_pvs" |
| 4315 |
.ie n .IP """cop_hints_exists_sv""" 4 |
| 4316 |
.el .IP \f(CWcop_hints_exists_sv\fR 4 |
| 4317 |
.IX Xref "cop_hints_exists_pv cop_hints_exists_pvn cop_hints_exists_pvs cop_hints_exists_sv" |
| 4318 |
.IX Item "cop_hints_exists_sv" |
| 4319 |
.PD |
| 4320 |
These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by |
| 4321 |
\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists, |
| 4322 |
and false otherwise. |
| 4323 |
.Sp |
| 4324 |
The forms differ in how the key is specified. In all forms, the key is pointed |
| 4325 |
to by \f(CW\*(C`key\*(C'\fR. |
| 4326 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4327 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4328 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4329 |
the string, which hence, may contain embedded-NUL characters. |
| 4330 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4331 |
using \f(CW"SvPV_const"\fR. |
| 4332 |
.Sp |
| 4333 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4334 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4335 |
automatically at compile time. |
| 4336 |
.Sp |
| 4337 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4338 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4339 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4340 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4341 |
the octets. |
| 4342 |
.RS 4 |
| 4343 |
.Sp |
| 4344 |
.Vb 7 |
| 4345 |
\& bool cop_hints_exists_pv (const COP *cop, const char *key, |
| 4346 |
\& U32 hash, U32 flags) |
| 4347 |
\& bool cop_hints_exists_pvn(const COP *cop, const char *key, |
| 4348 |
\& STRLEN keylen, U32 hash, U32 flags) |
| 4349 |
\& bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags) |
| 4350 |
\& bool cop_hints_exists_sv (const COP *cop, SV *key, U32 hash, |
| 4351 |
\& U32 flags) |
| 4352 |
.Ve |
| 4353 |
.RE |
| 4354 |
.RS 4 |
| 4355 |
.RE |
| 4356 |
.ie n .IP """cop_hints_fetch_pv""" 4 |
| 4357 |
.el .IP \f(CWcop_hints_fetch_pv\fR 4 |
| 4358 |
.IX Item "cop_hints_fetch_pv" |
| 4359 |
.PD 0 |
| 4360 |
.ie n .IP """cop_hints_fetch_pvn""" 4 |
| 4361 |
.el .IP \f(CWcop_hints_fetch_pvn\fR 4 |
| 4362 |
.IX Item "cop_hints_fetch_pvn" |
| 4363 |
.ie n .IP """cop_hints_fetch_pvs""" 4 |
| 4364 |
.el .IP \f(CWcop_hints_fetch_pvs\fR 4 |
| 4365 |
.IX Item "cop_hints_fetch_pvs" |
| 4366 |
.ie n .IP """cop_hints_fetch_sv""" 4 |
| 4367 |
.el .IP \f(CWcop_hints_fetch_sv\fR 4 |
| 4368 |
.IX Xref "cop_hints_fetch_pv cop_hints_fetch_pvn cop_hints_fetch_pvs cop_hints_fetch_sv" |
| 4369 |
.IX Item "cop_hints_fetch_sv" |
| 4370 |
.PD |
| 4371 |
These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by |
| 4372 |
\&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal |
| 4373 |
scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the |
| 4374 |
key. |
| 4375 |
.Sp |
| 4376 |
The forms differ in how the key is specified. |
| 4377 |
In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string. |
| 4378 |
In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal. |
| 4379 |
In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of |
| 4380 |
the string, which hence, may contain embedded-NUL characters. |
| 4381 |
In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that. |
| 4382 |
using \f(CW"SvPV_const"\fR. |
| 4383 |
.Sp |
| 4384 |
\&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been |
| 4385 |
precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed |
| 4386 |
automatically at compile time. |
| 4387 |
.Sp |
| 4388 |
The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR. |
| 4389 |
It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies |
| 4390 |
whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if |
| 4391 |
cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of |
| 4392 |
the octets. |
| 4393 |
.RS 4 |
| 4394 |
.Sp |
| 4395 |
.Vb 7 |
| 4396 |
\& SV * cop_hints_fetch_pv (const COP *cop, const char *key, |
| 4397 |
\& U32 hash, U32 flags) |
| 4398 |
\& SV * cop_hints_fetch_pvn(const COP *cop, const char *key, |
| 4399 |
\& STRLEN keylen, U32 hash, U32 flags) |
| 4400 |
\& SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags) |
| 4401 |
\& SV * cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash, |
| 4402 |
\& U32 flags) |
| 4403 |
.Ve |
| 4404 |
.RE |
| 4405 |
.RS 4 |
| 4406 |
.RE |
| 4407 |
.ie n .IP """cop_hints_2hv""" 4 |
| 4408 |
.el .IP \f(CWcop_hints_2hv\fR 4 |
| 4409 |
.IX Xref "cop_hints_2hv" |
| 4410 |
.IX Item "cop_hints_2hv" |
| 4411 |
Generates and returns a standard Perl hash representing the full set of |
| 4412 |
hint entries in the cop \f(CW\*(C`cop\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently unused and must |
| 4413 |
be zero. |
| 4414 |
.RS 4 |
| 4415 |
.Sp |
| 4416 |
.Vb 1 |
| 4417 |
\& HV * cop_hints_2hv(const COP *cop, U32 flags) |
| 4418 |
.Ve |
| 4419 |
.RE |
| 4420 |
.RS 4 |
| 4421 |
.RE |
| 4422 |
.ie n .IP """CopLABEL""" 4 |
| 4423 |
.el .IP \f(CWCopLABEL\fR 4 |
| 4424 |
.IX Item "CopLABEL" |
| 4425 |
.PD 0 |
| 4426 |
.ie n .IP """CopLABEL_len""" 4 |
| 4427 |
.el .IP \f(CWCopLABEL_len\fR 4 |
| 4428 |
.IX Item "CopLABEL_len" |
| 4429 |
.ie n .IP """CopLABEL_len_flags""" 4 |
| 4430 |
.el .IP \f(CWCopLABEL_len_flags\fR 4 |
| 4431 |
.IX Xref "CopLABEL CopLABEL_len CopLABEL_len_flags" |
| 4432 |
.IX Item "CopLABEL_len_flags" |
| 4433 |
.PD |
| 4434 |
These return the label attached to a cop. |
| 4435 |
.Sp |
| 4436 |
\&\f(CW\*(C`CopLABEL_len\*(C'\fR and \f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally store the number of |
| 4437 |
bytes comprising the returned label into \f(CW*len\fR. |
| 4438 |
.Sp |
| 4439 |
\&\f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally returns the UTF\-8ness of the returned label, |
| 4440 |
by setting \f(CW*flags\fR to 0 or \f(CW\*(C`SVf_UTF8\*(C'\fR. |
| 4441 |
.RS 4 |
| 4442 |
.Sp |
| 4443 |
.Vb 4 |
| 4444 |
\& const char * CopLABEL (COP *const cop) |
| 4445 |
\& const char * CopLABEL_len (COP *const cop, STRLEN *len) |
| 4446 |
\& const char * CopLABEL_len_flags(COP *const cop, STRLEN *len, |
| 4447 |
\& U32 *flags) |
| 4448 |
.Ve |
| 4449 |
.RE |
| 4450 |
.RS 4 |
| 4451 |
.RE |
| 4452 |
.ie n .IP """CopLINE""" 4 |
| 4453 |
.el .IP \f(CWCopLINE\fR 4 |
| 4454 |
.IX Xref "CopLINE" |
| 4455 |
.IX Item "CopLINE" |
| 4456 |
Returns the line number in the source code associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR |
| 4457 |
.RS 4 |
| 4458 |
.Sp |
| 4459 |
.Vb 1 |
| 4460 |
\& line_t CopLINE(const COP * c) |
| 4461 |
.Ve |
| 4462 |
.RE |
| 4463 |
.RS 4 |
| 4464 |
.RE |
| 4465 |
.ie n .IP """CopSTASH""" 4 |
| 4466 |
.el .IP \f(CWCopSTASH\fR 4 |
| 4467 |
.IX Xref "CopSTASH" |
| 4468 |
.IX Item "CopSTASH" |
| 4469 |
Returns the stash associated with \f(CW\*(C`c\*(C'\fR. |
| 4470 |
.RS 4 |
| 4471 |
.Sp |
| 4472 |
.Vb 1 |
| 4473 |
\& HV * CopSTASH(const COP * c) |
| 4474 |
.Ve |
| 4475 |
.RE |
| 4476 |
.RS 4 |
| 4477 |
.RE |
| 4478 |
.ie n .IP """CopSTASH_eq""" 4 |
| 4479 |
.el .IP \f(CWCopSTASH_eq\fR 4 |
| 4480 |
.IX Xref "CopSTASH_eq" |
| 4481 |
.IX Item "CopSTASH_eq" |
| 4482 |
Returns a boolean as to whether or not \f(CW\*(C`hv\*(C'\fR is the stash associated with \f(CW\*(C`c\*(C'\fR. |
| 4483 |
.RS 4 |
| 4484 |
.Sp |
| 4485 |
.Vb 1 |
| 4486 |
\& bool CopSTASH_eq(const COP * c, const HV * hv) |
| 4487 |
.Ve |
| 4488 |
.RE |
| 4489 |
.RS 4 |
| 4490 |
.RE |
| 4491 |
.ie n .IP """CopSTASHPV""" 4 |
| 4492 |
.el .IP \f(CWCopSTASHPV\fR 4 |
| 4493 |
.IX Xref "CopSTASHPV" |
| 4494 |
.IX Item "CopSTASHPV" |
| 4495 |
Returns the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if no |
| 4496 |
associated stash |
| 4497 |
.RS 4 |
| 4498 |
.Sp |
| 4499 |
.Vb 1 |
| 4500 |
\& char * CopSTASHPV(const COP * c) |
| 4501 |
.Ve |
| 4502 |
.RE |
| 4503 |
.RS 4 |
| 4504 |
.RE |
| 4505 |
.ie n .IP """CopSTASHPV_set""" 4 |
| 4506 |
.el .IP \f(CWCopSTASHPV_set\fR 4 |
| 4507 |
.IX Xref "CopSTASHPV_set" |
| 4508 |
.IX Item "CopSTASHPV_set" |
| 4509 |
Set the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, to the NUL-terminated C |
| 4510 |
string \f(CW\*(C`p\*(C'\fR, creating the package if necessary. |
| 4511 |
.RS 4 |
| 4512 |
.Sp |
| 4513 |
.Vb 1 |
| 4514 |
\& void CopSTASHPV_set(COP * c, const char * pv) |
| 4515 |
.Ve |
| 4516 |
.RE |
| 4517 |
.RS 4 |
| 4518 |
.RE |
| 4519 |
.ie n .IP """CopSTASH_set""" 4 |
| 4520 |
.el .IP \f(CWCopSTASH_set\fR 4 |
| 4521 |
.IX Xref "CopSTASH_set" |
| 4522 |
.IX Item "CopSTASH_set" |
| 4523 |
Set the stash associated with \f(CW\*(C`c\*(C'\fR to \f(CW\*(C`hv\*(C'\fR. |
| 4524 |
.RS 4 |
| 4525 |
.Sp |
| 4526 |
.Vb 1 |
| 4527 |
\& bool CopSTASH_set(COP * c, HV * hv) |
| 4528 |
.Ve |
| 4529 |
.RE |
| 4530 |
.RS 4 |
| 4531 |
.RE |
| 4532 |
.ie n .IP """cop_store_label""" 4 |
| 4533 |
.el .IP \f(CWcop_store_label\fR 4 |
| 4534 |
.IX Xref "cop_store_label" |
| 4535 |
.IX Item "cop_store_label" |
| 4536 |
NOTE: \f(CW\*(C`cop_store_label\*(C'\fR is \fBexperimental\fR and may change or be |
| 4537 |
removed without notice. |
| 4538 |
.Sp |
| 4539 |
Save a label into a \f(CW\*(C`cop_hints_hash\*(C'\fR. |
| 4540 |
You need to set flags to \f(CW\*(C`SVf_UTF8\*(C'\fR |
| 4541 |
for a UTF\-8 label. Any other flag is ignored. |
| 4542 |
.RS 4 |
| 4543 |
.Sp |
| 4544 |
.Vb 2 |
| 4545 |
\& void cop_store_label(COP * const cop, const char *label, |
| 4546 |
\& STRLEN len, U32 flags) |
| 4547 |
.Ve |
| 4548 |
.RE |
| 4549 |
.RS 4 |
| 4550 |
.RE |
| 4551 |
.ie n .IP """PERL_SI""" 4 |
| 4552 |
.el .IP \f(CWPERL_SI\fR 4 |
| 4553 |
.IX Xref "PERL_SI" |
| 4554 |
.IX Item "PERL_SI" |
| 4555 |
Use this typedef to declare variables that are to hold \f(CW\*(C`struct stackinfo\*(C'\fR. |
| 4556 |
.ie n .IP """PL_curcop""" 4 |
| 4557 |
.el .IP \f(CWPL_curcop\fR 4 |
| 4558 |
.IX Xref "PL_curcop" |
| 4559 |
.IX Item "PL_curcop" |
| 4560 |
The currently active COP (control op) roughly representing the current |
| 4561 |
statement in the source. |
| 4562 |
.Sp |
| 4563 |
On threaded perls, each thread has an independent copy of this variable; |
| 4564 |
each initialized at creation time with the current value of the creating |
| 4565 |
thread's copy. |
| 4566 |
.RS 4 |
| 4567 |
.Sp |
| 4568 |
.Vb 1 |
| 4569 |
\& COP* PL_curcop |
| 4570 |
.Ve |
| 4571 |
.RE |
| 4572 |
.RS 4 |
| 4573 |
.RE |
| 4574 |
.ie n .IP """RCPV_LEN""" 4 |
| 4575 |
.el .IP \f(CWRCPV_LEN\fR 4 |
| 4576 |
.IX Xref "RCPV_LEN" |
| 4577 |
.IX Item "RCPV_LEN" |
| 4578 |
Returns the length of a pv created with \f(CWrcpv_new()\fR. |
| 4579 |
Note that this reflects the length of the string from the callers |
| 4580 |
point of view, it does not include the mandatory null which is |
| 4581 |
always injected at the end of the string by \fBrcpv_new()\fR. |
| 4582 |
No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated |
| 4583 |
with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that |
| 4584 |
this is the case. |
| 4585 |
.RS 4 |
| 4586 |
.Sp |
| 4587 |
.Vb 1 |
| 4588 |
\& RCPV * RCPV_LEN(char *pv) |
| 4589 |
.Ve |
| 4590 |
.RE |
| 4591 |
.RS 4 |
| 4592 |
.RE |
| 4593 |
.ie n .IP """RCPV_REFCNT_dec""" 4 |
| 4594 |
.el .IP \f(CWRCPV_REFCNT_dec\fR 4 |
| 4595 |
.IX Xref "RCPV_REFCNT_dec" |
| 4596 |
.IX Item "RCPV_REFCNT_dec" |
| 4597 |
Decrements the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created |
| 4598 |
with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_free()\fR. |
| 4599 |
No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated |
| 4600 |
with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that |
| 4601 |
this is the case. |
| 4602 |
.RS 4 |
| 4603 |
.Sp |
| 4604 |
.Vb 1 |
| 4605 |
\& RCPV * RCPV_REFCNT_dec(char *pv) |
| 4606 |
.Ve |
| 4607 |
.RE |
| 4608 |
.RS 4 |
| 4609 |
.RE |
| 4610 |
.ie n .IP """RCPV_REFCNT_inc""" 4 |
| 4611 |
.el .IP \f(CWRCPV_REFCNT_inc\fR 4 |
| 4612 |
.IX Xref "RCPV_REFCNT_inc" |
| 4613 |
.IX Item "RCPV_REFCNT_inc" |
| 4614 |
Increments the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created |
| 4615 |
with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_copy()\fR. |
| 4616 |
No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated |
| 4617 |
with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that |
| 4618 |
this is the case. |
| 4619 |
.RS 4 |
| 4620 |
.Sp |
| 4621 |
.Vb 1 |
| 4622 |
\& RCPV * RCPV_REFCNT_inc(char *pv) |
| 4623 |
.Ve |
| 4624 |
.RE |
| 4625 |
.RS 4 |
| 4626 |
.RE |
| 4627 |
.ie n .IP """RCPV_REFCOUNT""" 4 |
| 4628 |
.el .IP \f(CWRCPV_REFCOUNT\fR 4 |
| 4629 |
.IX Xref "RCPV_REFCOUNT" |
| 4630 |
.IX Item "RCPV_REFCOUNT" |
| 4631 |
Returns the refcount for a pv created with \f(CWrcpv_new()\fR. |
| 4632 |
No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated |
| 4633 |
with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that |
| 4634 |
this is the case. |
| 4635 |
.RS 4 |
| 4636 |
.Sp |
| 4637 |
.Vb 1 |
| 4638 |
\& RCPV * RCPV_REFCOUNT(char *pv) |
| 4639 |
.Ve |
| 4640 |
.RE |
| 4641 |
.RS 4 |
| 4642 |
.RE |
| 4643 |
.ie n .IP """RCPVx""" 4 |
| 4644 |
.el .IP \f(CWRCPVx\fR 4 |
| 4645 |
.IX Xref "RCPVx" |
| 4646 |
.IX Item "RCPVx" |
| 4647 |
Returns the RCPV structure (struct rcpv) for a refcounted |
| 4648 |
string pv created with \f(CWrcpv_new()\fR. |
| 4649 |
No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated |
| 4650 |
with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that |
| 4651 |
this is the case. |
| 4652 |
.RS 4 |
| 4653 |
.Sp |
| 4654 |
.Vb 1 |
| 4655 |
\& RCPV * RCPVx(char *pv) |
| 4656 |
.Ve |
| 4657 |
.RE |
| 4658 |
.RS 4 |
| 4659 |
.RE |
| 4660 |
.SH "Custom Operators" |
| 4661 |
.IX Header "Custom Operators" |
| 4662 |
.ie n .IP """custom_op_register""" 4 |
| 4663 |
.el .IP \f(CWcustom_op_register\fR 4 |
| 4664 |
.IX Xref "custom_op_register" |
| 4665 |
.IX Item "custom_op_register" |
| 4666 |
Register a custom op. See "Custom Operators" in perlguts. |
| 4667 |
.Sp |
| 4668 |
NOTE: \f(CW\*(C`custom_op_register\*(C'\fR must be explicitly called as |
| 4669 |
\&\f(CW\*(C`Perl_custom_op_register\*(C'\fR |
| 4670 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 4671 |
.RS 4 |
| 4672 |
.Sp |
| 4673 |
.Vb 2 |
| 4674 |
\& void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr, |
| 4675 |
\& const XOP *xop) |
| 4676 |
.Ve |
| 4677 |
.RE |
| 4678 |
.RS 4 |
| 4679 |
.RE |
| 4680 |
.ie n .IP """Perl_custom_op_xop""" 4 |
| 4681 |
.el .IP \f(CWPerl_custom_op_xop\fR 4 |
| 4682 |
.IX Xref "Perl_custom_op_xop" |
| 4683 |
.IX Item "Perl_custom_op_xop" |
| 4684 |
Return the XOP structure for a given custom op. This macro should be |
| 4685 |
considered internal to \f(CW\*(C`OP_NAME\*(C'\fR and the other access macros: use them instead. |
| 4686 |
This macro does call a function. Prior |
| 4687 |
to 5.19.6, this was implemented as a |
| 4688 |
function. |
| 4689 |
.RS 4 |
| 4690 |
.Sp |
| 4691 |
.Vb 1 |
| 4692 |
\& const XOP * Perl_custom_op_xop(pTHX_ const OP *o) |
| 4693 |
.Ve |
| 4694 |
.RE |
| 4695 |
.RS 4 |
| 4696 |
.RE |
| 4697 |
.ie n .IP """XopDISABLE""" 4 |
| 4698 |
.el .IP \f(CWXopDISABLE\fR 4 |
| 4699 |
.IX Xref "XopDISABLE" |
| 4700 |
.IX Item "XopDISABLE" |
| 4701 |
Temporarily disable a member of the XOP, by clearing the appropriate flag. |
| 4702 |
.RS 4 |
| 4703 |
.Sp |
| 4704 |
.Vb 1 |
| 4705 |
\& void XopDISABLE(XOP *xop, token which) |
| 4706 |
.Ve |
| 4707 |
.RE |
| 4708 |
.RS 4 |
| 4709 |
.RE |
| 4710 |
.ie n .IP """XopENABLE""" 4 |
| 4711 |
.el .IP \f(CWXopENABLE\fR 4 |
| 4712 |
.IX Xref "XopENABLE" |
| 4713 |
.IX Item "XopENABLE" |
| 4714 |
Reenable a member of the XOP which has been disabled. |
| 4715 |
.RS 4 |
| 4716 |
.Sp |
| 4717 |
.Vb 1 |
| 4718 |
\& void XopENABLE(XOP *xop, token which) |
| 4719 |
.Ve |
| 4720 |
.RE |
| 4721 |
.RS 4 |
| 4722 |
.RE |
| 4723 |
.ie n .IP """XopENTRY""" 4 |
| 4724 |
.el .IP \f(CWXopENTRY\fR 4 |
| 4725 |
.IX Xref "XopENTRY" |
| 4726 |
.IX Item "XopENTRY" |
| 4727 |
Return a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token |
| 4728 |
indicating which entry to return. If the member is not set |
| 4729 |
this will return a default value. The return type depends |
| 4730 |
on \f(CW\*(C`which\*(C'\fR. This macro evaluates its arguments more than |
| 4731 |
once. If you are using \f(CW\*(C`Perl_custom_op_xop\*(C'\fR to retrieve a |
| 4732 |
\&\f(CW\*(C`XOP *\*(C'\fR from a \f(CW\*(C`OP *\*(C'\fR, use the more efficient "XopENTRYCUSTOM" instead. |
| 4733 |
.RS 4 |
| 4734 |
.Sp |
| 4735 |
.Vb 1 |
| 4736 |
\& XopENTRY(XOP *xop, token which) |
| 4737 |
.Ve |
| 4738 |
.RE |
| 4739 |
.RS 4 |
| 4740 |
.RE |
| 4741 |
.ie n .IP """XopENTRYCUSTOM""" 4 |
| 4742 |
.el .IP \f(CWXopENTRYCUSTOM\fR 4 |
| 4743 |
.IX Xref "XopENTRYCUSTOM" |
| 4744 |
.IX Item "XopENTRYCUSTOM" |
| 4745 |
Exactly like \f(CW\*(C`XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)\*(C'\fR but more |
| 4746 |
efficient. The \f(CW\*(C`which\*(C'\fR parameter is identical to "XopENTRY". |
| 4747 |
.RS 4 |
| 4748 |
.Sp |
| 4749 |
.Vb 1 |
| 4750 |
\& XopENTRYCUSTOM(const OP *o, token which) |
| 4751 |
.Ve |
| 4752 |
.RE |
| 4753 |
.RS 4 |
| 4754 |
.RE |
| 4755 |
.ie n .IP """XopENTRY_set""" 4 |
| 4756 |
.el .IP \f(CWXopENTRY_set\fR 4 |
| 4757 |
.IX Xref "XopENTRY_set" |
| 4758 |
.IX Item "XopENTRY_set" |
| 4759 |
Set a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token |
| 4760 |
indicating which entry to set. See "Custom Operators" in perlguts |
| 4761 |
for details about the available members and how |
| 4762 |
they are used. This macro evaluates its argument |
| 4763 |
more than once. |
| 4764 |
.RS 4 |
| 4765 |
.Sp |
| 4766 |
.Vb 1 |
| 4767 |
\& void XopENTRY_set(XOP *xop, token which, value) |
| 4768 |
.Ve |
| 4769 |
.RE |
| 4770 |
.RS 4 |
| 4771 |
.RE |
| 4772 |
.ie n .IP """XopFLAGS""" 4 |
| 4773 |
.el .IP \f(CWXopFLAGS\fR 4 |
| 4774 |
.IX Xref "XopFLAGS" |
| 4775 |
.IX Item "XopFLAGS" |
| 4776 |
Return the XOP's flags. |
| 4777 |
.RS 4 |
| 4778 |
.Sp |
| 4779 |
.Vb 1 |
| 4780 |
\& U32 XopFLAGS(XOP *xop) |
| 4781 |
.Ve |
| 4782 |
.RE |
| 4783 |
.RS 4 |
| 4784 |
.RE |
| 4785 |
.SH "CV Handling" |
| 4786 |
.IX Xref "CV GV_ADD" |
| 4787 |
.IX Header "CV Handling" |
| 4788 |
This section documents functions to manipulate CVs which are |
| 4789 |
code-values, meaning subroutines. For more information, see |
| 4790 |
perlguts. |
| 4791 |
.ie n .IP """caller_cx""" 4 |
| 4792 |
.el .IP \f(CWcaller_cx\fR 4 |
| 4793 |
.IX Xref "caller_cx" |
| 4794 |
.IX Item "caller_cx" |
| 4795 |
The XSUB-writer's equivalent of \fBcaller()\fR. The |
| 4796 |
returned \f(CW\*(C`PERL_CONTEXT\*(C'\fR structure can be interrogated to find all the |
| 4797 |
information returned to Perl by \f(CW\*(C`caller\*(C'\fR. Note that XSUBs don't get a |
| 4798 |
stack frame, so \f(CW\*(C`caller_cx(0, NULL)\*(C'\fR will return information for the |
| 4799 |
immediately-surrounding Perl code. |
| 4800 |
.Sp |
| 4801 |
This function skips over the automatic calls to \f(CW&DB::sub\fR made on the |
| 4802 |
behalf of the debugger. If the stack frame requested was a sub called by |
| 4803 |
\&\f(CW\*(C`DB::sub\*(C'\fR, the return value will be the frame for the call to |
| 4804 |
\&\f(CW\*(C`DB::sub\*(C'\fR, since that has the correct line number/etc. for the call |
| 4805 |
site. If \fIdbcxp\fR is non\-\f(CW\*(C`NULL\*(C'\fR, it will be set to a pointer to the |
| 4806 |
frame for the sub call itself. |
| 4807 |
.RS 4 |
| 4808 |
.Sp |
| 4809 |
.Vb 2 |
| 4810 |
\& const PERL_CONTEXT * caller_cx(I32 level, |
| 4811 |
\& const PERL_CONTEXT **dbcxp) |
| 4812 |
.Ve |
| 4813 |
.RE |
| 4814 |
.RS 4 |
| 4815 |
.RE |
| 4816 |
.ie n .IP """CvDEPTH""" 4 |
| 4817 |
.el .IP \f(CWCvDEPTH\fR 4 |
| 4818 |
.IX Xref "CvDEPTH" |
| 4819 |
.IX Item "CvDEPTH" |
| 4820 |
Returns the recursion level of the CV \f(CW\*(C`sv\*(C'\fR. Hence >= 2 indicates we are in a |
| 4821 |
recursive call. |
| 4822 |
.RS 4 |
| 4823 |
.Sp |
| 4824 |
.Vb 1 |
| 4825 |
\& I32 * CvDEPTH(const CV * const sv) |
| 4826 |
.Ve |
| 4827 |
.RE |
| 4828 |
.RS 4 |
| 4829 |
.RE |
| 4830 |
.ie n .IP """CvGV""" 4 |
| 4831 |
.el .IP \f(CWCvGV\fR 4 |
| 4832 |
.IX Xref "CvGV" |
| 4833 |
.IX Item "CvGV" |
| 4834 |
Returns the GV associated with the CV \f(CW\*(C`sv\*(C'\fR, reifying it if necessary. |
| 4835 |
.RS 4 |
| 4836 |
.Sp |
| 4837 |
.Vb 1 |
| 4838 |
\& GV * CvGV(CV *sv) |
| 4839 |
.Ve |
| 4840 |
.RE |
| 4841 |
.RS 4 |
| 4842 |
.RE |
| 4843 |
.ie n .IP """CvSTASH""" 4 |
| 4844 |
.el .IP \f(CWCvSTASH\fR 4 |
| 4845 |
.IX Xref "CvSTASH" |
| 4846 |
.IX Item "CvSTASH" |
| 4847 |
Returns the stash of the CV. A stash is the symbol table hash, containing |
| 4848 |
the package-scoped variables in the package where the subroutine was defined. |
| 4849 |
For more information, see perlguts. |
| 4850 |
.Sp |
| 4851 |
This also has a special use with XS AUTOLOAD subs. |
| 4852 |
See "Autoloading with XSUBs" in perlguts. |
| 4853 |
.RS 4 |
| 4854 |
.Sp |
| 4855 |
.Vb 1 |
| 4856 |
\& HV* CvSTASH(CV* cv) |
| 4857 |
.Ve |
| 4858 |
.RE |
| 4859 |
.RS 4 |
| 4860 |
.RE |
| 4861 |
.ie n .IP """find_runcv""" 4 |
| 4862 |
.el .IP \f(CWfind_runcv\fR 4 |
| 4863 |
.IX Xref "find_runcv" |
| 4864 |
.IX Item "find_runcv" |
| 4865 |
Locate the CV corresponding to the currently executing sub or eval. |
| 4866 |
If \f(CW\*(C`db_seqp\*(C'\fR is non_null, skip CVs that are in the DB package and populate |
| 4867 |
\&\f(CW*db_seqp\fR with the cop sequence number at the point that the DB:: code was |
| 4868 |
entered. (This allows debuggers to eval in the scope of the breakpoint |
| 4869 |
rather than in the scope of the debugger itself.) |
| 4870 |
.RS 4 |
| 4871 |
.Sp |
| 4872 |
.Vb 1 |
| 4873 |
\& CV * find_runcv(U32 *db_seqp) |
| 4874 |
.Ve |
| 4875 |
.RE |
| 4876 |
.RS 4 |
| 4877 |
.RE |
| 4878 |
.ie n .IP """get_cv""" 4 |
| 4879 |
.el .IP \f(CWget_cv\fR 4 |
| 4880 |
.IX Item "get_cv" |
| 4881 |
.PD 0 |
| 4882 |
.ie n .IP """get_cvn_flags""" 4 |
| 4883 |
.el .IP \f(CWget_cvn_flags\fR 4 |
| 4884 |
.IX Item "get_cvn_flags" |
| 4885 |
.ie n .IP """get_cvs""" 4 |
| 4886 |
.el .IP \f(CWget_cvs\fR 4 |
| 4887 |
.IX Xref "get_cv get_cvn_flags get_cvs" |
| 4888 |
.IX Item "get_cvs" |
| 4889 |
.PD |
| 4890 |
These return the CV of the specified Perl subroutine. \f(CW\*(C`flags\*(C'\fR are passed to |
| 4891 |
\&\f(CW\*(C`gv_fetchpvn_flags\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the Perl subroutine does not |
| 4892 |
exist then it will be declared (which has the same effect as saying |
| 4893 |
\&\f(CW\*(C`sub name;\*(C'\fR). If \f(CW\*(C`GV_ADD\*(C'\fR is not set and the subroutine does not exist, |
| 4894 |
then NULL is returned. |
| 4895 |
.Sp |
| 4896 |
The forms differ only in how the subroutine is specified.. With \f(CW\*(C`get_cvs\*(C'\fR, |
| 4897 |
the name is a literal C string, enclosed in double quotes. With \f(CW\*(C`get_cv\*(C'\fR, the |
| 4898 |
name is given by the \f(CW\*(C`name\*(C'\fR parameter, which must be a NUL-terminated C |
| 4899 |
string. With \f(CW\*(C`get_cvn_flags\*(C'\fR, the name is also given by the \f(CW\*(C`name\*(C'\fR |
| 4900 |
parameter, but it is a Perl string (possibly containing embedded NUL bytes), |
| 4901 |
and its length in bytes is contained in the \f(CW\*(C`len\*(C'\fR parameter. |
| 4902 |
.Sp |
| 4903 |
NOTE: the \f(CWperl_get_cv()\fR form is \fBdeprecated\fR. |
| 4904 |
.Sp |
| 4905 |
NOTE: the \f(CWperl_get_cvn_flags()\fR form is \fBdeprecated\fR. |
| 4906 |
.Sp |
| 4907 |
NOTE: the \f(CWperl_get_cvs()\fR form is \fBdeprecated\fR. |
| 4908 |
.RS 4 |
| 4909 |
.Sp |
| 4910 |
.Vb 3 |
| 4911 |
\& CV * get_cv (const char *name, I32 flags) |
| 4912 |
\& CV * get_cvn_flags(const char *name, STRLEN len, I32 flags) |
| 4913 |
\& CV * get_cvs ("string", I32 flags) |
| 4914 |
.Ve |
| 4915 |
.RE |
| 4916 |
.RS 4 |
| 4917 |
.RE |
| 4918 |
.ie n .IP """Nullcv""" 4 |
| 4919 |
.el .IP \f(CWNullcv\fR 4 |
| 4920 |
.IX Xref "Nullcv" |
| 4921 |
.IX Item "Nullcv" |
| 4922 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullcv\*(C'\fR |
| 4923 |
from a future release of Perl. Do not use it for |
| 4924 |
new code; remove it from existing code. |
| 4925 |
.Sp |
| 4926 |
Null CV pointer. |
| 4927 |
.Sp |
| 4928 |
(deprecated \- use \f(CW\*(C`(CV *)NULL\*(C'\fR instead) |
| 4929 |
.SH Debugging |
| 4930 |
.IX Header "Debugging" |
| 4931 |
.ie n .IP """av_dump""" 4 |
| 4932 |
.el .IP \f(CWav_dump\fR 4 |
| 4933 |
.IX Xref "av_dump" |
| 4934 |
.IX Item "av_dump" |
| 4935 |
Dumps the contents of an AV to the \f(CW\*(C`STDERR\*(C'\fR filehandle, |
| 4936 |
Similar to using Devel::Peek on an arrayref but does not |
| 4937 |
expect an RV wrapper. Dumps contents to a depth of 3 levels |
| 4938 |
deep. |
| 4939 |
.RS 4 |
| 4940 |
.Sp |
| 4941 |
.Vb 1 |
| 4942 |
\& void av_dump(AV *av) |
| 4943 |
.Ve |
| 4944 |
.RE |
| 4945 |
.RS 4 |
| 4946 |
.RE |
| 4947 |
.ie n .IP """deb""" 4 |
| 4948 |
.el .IP \f(CWdeb\fR 4 |
| 4949 |
.IX Item "deb" |
| 4950 |
.PD 0 |
| 4951 |
.ie n .IP """deb_nocontext""" 4 |
| 4952 |
.el .IP \f(CWdeb_nocontext\fR 4 |
| 4953 |
.IX Xref "deb deb_nocontext" |
| 4954 |
.IX Item "deb_nocontext" |
| 4955 |
.PD |
| 4956 |
When perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, this prints to STDERR the |
| 4957 |
information given by the arguments, prefaced by the name of the file containing |
| 4958 |
the script causing the call, and the line number within that file. |
| 4959 |
.Sp |
| 4960 |
If the \f(CW\*(C`v\*(C'\fR (verbose) debugging option is in effect, the process id is also |
| 4961 |
printed. |
| 4962 |
.Sp |
| 4963 |
The two forms differ only in that \f(CW\*(C`deb_nocontext\*(C'\fR does not take a thread |
| 4964 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 4965 |
already have the thread context. |
| 4966 |
.Sp |
| 4967 |
NOTE: \f(CW\*(C`deb\*(C'\fR must be explicitly called as |
| 4968 |
\&\f(CW\*(C`Perl_deb\*(C'\fR |
| 4969 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 4970 |
.RS 4 |
| 4971 |
.Sp |
| 4972 |
.Vb 2 |
| 4973 |
\& void Perl_deb (pTHX_ const char *pat, ...) |
| 4974 |
\& void deb_nocontext(const char *pat, ...) |
| 4975 |
.Ve |
| 4976 |
.RE |
| 4977 |
.RS 4 |
| 4978 |
.RE |
| 4979 |
.ie n .IP """debstack""" 4 |
| 4980 |
.el .IP \f(CWdebstack\fR 4 |
| 4981 |
.IX Xref "debstack" |
| 4982 |
.IX Item "debstack" |
| 4983 |
Dump the current stack |
| 4984 |
.RS 4 |
| 4985 |
.Sp |
| 4986 |
.Vb 1 |
| 4987 |
\& I32 debstack() |
| 4988 |
.Ve |
| 4989 |
.RE |
| 4990 |
.RS 4 |
| 4991 |
.RE |
| 4992 |
.ie n .IP """dump_all""" 4 |
| 4993 |
.el .IP \f(CWdump_all\fR 4 |
| 4994 |
.IX Xref "dump_all" |
| 4995 |
.IX Item "dump_all" |
| 4996 |
Dumps the entire optree of the current program starting at \f(CW\*(C`PL_main_root\*(C'\fR to |
| 4997 |
\&\f(CW\*(C`STDERR\*(C'\fR. Also dumps the optrees for all visible subroutines in |
| 4998 |
\&\f(CW\*(C`PL_defstash\*(C'\fR. |
| 4999 |
.RS 4 |
| 5000 |
.Sp |
| 5001 |
.Vb 1 |
| 5002 |
\& void dump_all() |
| 5003 |
.Ve |
| 5004 |
.RE |
| 5005 |
.RS 4 |
| 5006 |
.RE |
| 5007 |
.ie n .IP """dump_c_backtrace""" 4 |
| 5008 |
.el .IP \f(CWdump_c_backtrace\fR 4 |
| 5009 |
.IX Xref "dump_c_backtrace" |
| 5010 |
.IX Item "dump_c_backtrace" |
| 5011 |
Dumps the C backtrace to the given \f(CW\*(C`fp\*(C'\fR. |
| 5012 |
.Sp |
| 5013 |
Returns true if a backtrace could be retrieved, false if not. |
| 5014 |
.RS 4 |
| 5015 |
.Sp |
| 5016 |
.Vb 1 |
| 5017 |
\& bool dump_c_backtrace(PerlIO *fp, int max_depth, int skip) |
| 5018 |
.Ve |
| 5019 |
.RE |
| 5020 |
.RS 4 |
| 5021 |
.RE |
| 5022 |
.ie n .IP """dump_eval""" 4 |
| 5023 |
.el .IP \f(CWdump_eval\fR 4 |
| 5024 |
.IX Item "dump_eval" |
| 5025 |
Described in perlguts. |
| 5026 |
.RS 4 |
| 5027 |
.Sp |
| 5028 |
.Vb 1 |
| 5029 |
\& void dump_eval() |
| 5030 |
.Ve |
| 5031 |
.RE |
| 5032 |
.RS 4 |
| 5033 |
.RE |
| 5034 |
.ie n .IP """dump_form""" 4 |
| 5035 |
.el .IP \f(CWdump_form\fR 4 |
| 5036 |
.IX Xref "dump_form" |
| 5037 |
.IX Item "dump_form" |
| 5038 |
Dumps the contents of the format contained in the GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR, or a |
| 5039 |
message that one doesn't exist. |
| 5040 |
.RS 4 |
| 5041 |
.Sp |
| 5042 |
.Vb 1 |
| 5043 |
\& void dump_form(const GV *gv) |
| 5044 |
.Ve |
| 5045 |
.RE |
| 5046 |
.RS 4 |
| 5047 |
.RE |
| 5048 |
.ie n .IP """dump_packsubs""" 4 |
| 5049 |
.el .IP \f(CWdump_packsubs\fR 4 |
| 5050 |
.IX Xref "dump_packsubs" |
| 5051 |
.IX Item "dump_packsubs" |
| 5052 |
Dumps the optrees for all visible subroutines in \f(CW\*(C`stash\*(C'\fR. |
| 5053 |
.RS 4 |
| 5054 |
.Sp |
| 5055 |
.Vb 1 |
| 5056 |
\& void dump_packsubs(const HV *stash) |
| 5057 |
.Ve |
| 5058 |
.RE |
| 5059 |
.RS 4 |
| 5060 |
.RE |
| 5061 |
.ie n .IP """dump_sub""" 4 |
| 5062 |
.el .IP \f(CWdump_sub\fR 4 |
| 5063 |
.IX Item "dump_sub" |
| 5064 |
Described in perlguts. |
| 5065 |
.RS 4 |
| 5066 |
.Sp |
| 5067 |
.Vb 1 |
| 5068 |
\& void dump_sub(const GV *gv) |
| 5069 |
.Ve |
| 5070 |
.RE |
| 5071 |
.RS 4 |
| 5072 |
.RE |
| 5073 |
.ie n .IP """get_c_backtrace_dump""" 4 |
| 5074 |
.el .IP \f(CWget_c_backtrace_dump\fR 4 |
| 5075 |
.IX Xref "get_c_backtrace_dump" |
| 5076 |
.IX Item "get_c_backtrace_dump" |
| 5077 |
Returns a SV containing a dump of \f(CW\*(C`depth\*(C'\fR frames of the call stack, skipping |
| 5078 |
the \f(CW\*(C`skip\*(C'\fR innermost ones. \f(CW\*(C`depth\*(C'\fR of 20 is usually enough. |
| 5079 |
.Sp |
| 5080 |
The appended output looks like: |
| 5081 |
.Sp |
| 5082 |
.Vb 4 |
| 5083 |
\& ... |
| 5084 |
\& 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl |
| 5085 |
\& 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl |
| 5086 |
\& ... |
| 5087 |
.Ve |
| 5088 |
.Sp |
| 5089 |
The fields are tab-separated. The first column is the depth (zero |
| 5090 |
being the innermost non-skipped frame). In the hex:offset, the hex is |
| 5091 |
where the program counter was in \f(CW\*(C`S_parse_body\*(C'\fR, and the :offset (might |
| 5092 |
be missing) tells how much inside the \f(CW\*(C`S_parse_body\*(C'\fR the program counter was. |
| 5093 |
.Sp |
| 5094 |
The \f(CW\*(C`util.c:1716\*(C'\fR is the source code file and line number. |
| 5095 |
.Sp |
| 5096 |
The \fI/usr/bin/perl\fR is obvious (hopefully). |
| 5097 |
.Sp |
| 5098 |
Unknowns are \f(CW"\-"\fR. Unknowns can happen unfortunately quite easily: |
| 5099 |
if the platform doesn't support retrieving the information; |
| 5100 |
if the binary is missing the debug information; |
| 5101 |
if the optimizer has transformed the code by for example inlining. |
| 5102 |
.RS 4 |
| 5103 |
.Sp |
| 5104 |
.Vb 1 |
| 5105 |
\& SV * get_c_backtrace_dump(int max_depth, int skip) |
| 5106 |
.Ve |
| 5107 |
.RE |
| 5108 |
.RS 4 |
| 5109 |
.RE |
| 5110 |
.ie n .IP """gv_dump""" 4 |
| 5111 |
.el .IP \f(CWgv_dump\fR 4 |
| 5112 |
.IX Xref "gv_dump" |
| 5113 |
.IX Item "gv_dump" |
| 5114 |
Dump the name and, if they differ, the effective name of the GV \f(CW\*(C`gv\*(C'\fR to |
| 5115 |
\&\f(CW\*(C`STDERR\*(C'\fR. |
| 5116 |
.RS 4 |
| 5117 |
.Sp |
| 5118 |
.Vb 1 |
| 5119 |
\& void gv_dump(GV *gv) |
| 5120 |
.Ve |
| 5121 |
.RE |
| 5122 |
.RS 4 |
| 5123 |
.RE |
| 5124 |
.ie n .IP """HAS_BACKTRACE""" 4 |
| 5125 |
.el .IP \f(CWHAS_BACKTRACE\fR 4 |
| 5126 |
.IX Xref "HAS_BACKTRACE" |
| 5127 |
.IX Item "HAS_BACKTRACE" |
| 5128 |
This symbol, if defined, indicates that the \f(CWbacktrace()\fR routine is |
| 5129 |
available to get a stack trace. The \fIexecinfo.h\fR header must be |
| 5130 |
included to use this routine. |
| 5131 |
.ie n .IP """hv_dump""" 4 |
| 5132 |
.el .IP \f(CWhv_dump\fR 4 |
| 5133 |
.IX Xref "hv_dump" |
| 5134 |
.IX Item "hv_dump" |
| 5135 |
Dumps the contents of an HV to the \f(CW\*(C`STDERR\*(C'\fR filehandle. |
| 5136 |
Similar to using Devel::Peek on an hashref but does not |
| 5137 |
expect an RV wrapper. Dumps contents to a depth of 3 levels |
| 5138 |
deep. |
| 5139 |
.RS 4 |
| 5140 |
.Sp |
| 5141 |
.Vb 1 |
| 5142 |
\& void hv_dump(HV *hv) |
| 5143 |
.Ve |
| 5144 |
.RE |
| 5145 |
.RS 4 |
| 5146 |
.RE |
| 5147 |
.ie n .IP """magic_dump""" 4 |
| 5148 |
.el .IP \f(CWmagic_dump\fR 4 |
| 5149 |
.IX Xref "magic_dump" |
| 5150 |
.IX Item "magic_dump" |
| 5151 |
Dumps the contents of the MAGIC \f(CW\*(C`mg\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR. |
| 5152 |
.RS 4 |
| 5153 |
.Sp |
| 5154 |
.Vb 1 |
| 5155 |
\& void magic_dump(const MAGIC *mg) |
| 5156 |
.Ve |
| 5157 |
.RE |
| 5158 |
.RS 4 |
| 5159 |
.RE |
| 5160 |
.ie n .IP """op_class""" 4 |
| 5161 |
.el .IP \f(CWop_class\fR 4 |
| 5162 |
.IX Xref "op_class" |
| 5163 |
.IX Item "op_class" |
| 5164 |
Given an op, determine what type of struct it has been allocated as. |
| 5165 |
Returns one of the OPclass enums, such as OPclass_LISTOP. |
| 5166 |
.RS 4 |
| 5167 |
.Sp |
| 5168 |
.Vb 1 |
| 5169 |
\& OPclass op_class(const OP *o) |
| 5170 |
.Ve |
| 5171 |
.RE |
| 5172 |
.RS 4 |
| 5173 |
.RE |
| 5174 |
.ie n .IP """op_dump""" 4 |
| 5175 |
.el .IP \f(CWop_dump\fR 4 |
| 5176 |
.IX Xref "op_dump" |
| 5177 |
.IX Item "op_dump" |
| 5178 |
Dumps the optree starting at OP \f(CW\*(C`o\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR. |
| 5179 |
.RS 4 |
| 5180 |
.Sp |
| 5181 |
.Vb 1 |
| 5182 |
\& void op_dump(const OP *o) |
| 5183 |
.Ve |
| 5184 |
.RE |
| 5185 |
.RS 4 |
| 5186 |
.RE |
| 5187 |
.ie n .IP """PL_op""" 4 |
| 5188 |
.el .IP \f(CWPL_op\fR 4 |
| 5189 |
.IX Item "PL_op" |
| 5190 |
Described in perlhacktips. |
| 5191 |
.ie n .IP """PL_runops""" 4 |
| 5192 |
.el .IP \f(CWPL_runops\fR 4 |
| 5193 |
.IX Item "PL_runops" |
| 5194 |
Described in perlguts. |
| 5195 |
.ie n .IP """PL_sv_serial""" 4 |
| 5196 |
.el .IP \f(CWPL_sv_serial\fR 4 |
| 5197 |
.IX Item "PL_sv_serial" |
| 5198 |
Described in perlhacktips. |
| 5199 |
.ie n .IP """pmop_dump""" 4 |
| 5200 |
.el .IP \f(CWpmop_dump\fR 4 |
| 5201 |
.IX Xref "pmop_dump" |
| 5202 |
.IX Item "pmop_dump" |
| 5203 |
Dump an OP that is related to Pattern Matching, such as \f(CW\*(C`s/foo/bar/\*(C'\fR; these require |
| 5204 |
special handling. |
| 5205 |
.RS 4 |
| 5206 |
.Sp |
| 5207 |
.Vb 1 |
| 5208 |
\& void pmop_dump(PMOP *pm) |
| 5209 |
.Ve |
| 5210 |
.RE |
| 5211 |
.RS 4 |
| 5212 |
.RE |
| 5213 |
.ie n .IP """sv_dump""" 4 |
| 5214 |
.el .IP \f(CWsv_dump\fR 4 |
| 5215 |
.IX Xref "sv_dump" |
| 5216 |
.IX Item "sv_dump" |
| 5217 |
Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle. |
| 5218 |
.Sp |
| 5219 |
For an example of its output, see Devel::Peek. If |
| 5220 |
the item is an SvROK it will dump items to a depth of 4, |
| 5221 |
otherwise it will dump only the top level item, which |
| 5222 |
means that it will not dump the contents of an AV * or |
| 5223 |
HV *. For that use \f(CWav_dump()\fR or \f(CWhv_dump()\fR. |
| 5224 |
.RS 4 |
| 5225 |
.Sp |
| 5226 |
.Vb 1 |
| 5227 |
\& void sv_dump(SV *sv) |
| 5228 |
.Ve |
| 5229 |
.RE |
| 5230 |
.RS 4 |
| 5231 |
.RE |
| 5232 |
.ie n .IP """sv_dump_depth""" 4 |
| 5233 |
.el .IP \f(CWsv_dump_depth\fR 4 |
| 5234 |
.IX Xref "sv_dump_depth" |
| 5235 |
.IX Item "sv_dump_depth" |
| 5236 |
Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle |
| 5237 |
to the depth requested. This function can be used on any |
| 5238 |
SV derived type (GV, HV, AV) with an appropriate cast. |
| 5239 |
This is a more flexible variant of \fBsv_dump()\fR. For example |
| 5240 |
.Sp |
| 5241 |
.Vb 2 |
| 5242 |
\& HV *hv = ...; |
| 5243 |
\& sv_dump_depth((SV*)hv, 2); |
| 5244 |
.Ve |
| 5245 |
.Sp |
| 5246 |
would dump the hv, its keys and values, but would not recurse |
| 5247 |
into any RV values. |
| 5248 |
.RS 4 |
| 5249 |
.Sp |
| 5250 |
.Vb 1 |
| 5251 |
\& void sv_dump_depth(SV *sv, I32 depth) |
| 5252 |
.Ve |
| 5253 |
.RE |
| 5254 |
.RS 4 |
| 5255 |
.RE |
| 5256 |
.ie n .IP """vdeb""" 4 |
| 5257 |
.el .IP \f(CWvdeb\fR 4 |
| 5258 |
.IX Xref "vdeb" |
| 5259 |
.IX Item "vdeb" |
| 5260 |
This is like \f(CW"deb"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list. |
| 5261 |
.RS 4 |
| 5262 |
.Sp |
| 5263 |
.Vb 1 |
| 5264 |
\& void vdeb(const char *pat, va_list *args) |
| 5265 |
.Ve |
| 5266 |
.RE |
| 5267 |
.RS 4 |
| 5268 |
.RE |
| 5269 |
.SH "Display functions" |
| 5270 |
.IX Xref "PERL_PV_ESCAPE_ALL PERL_PV_ESCAPE_FIRSTCHAR PERL_PV_ESCAPE_NOBACKSLASH PERL_PV_ESCAPE_NOCLEAR PERL_PV_ESCAPE_NONASCII PERL_PV_ESCAPE_NON_WC PERL_PV_ESCAPE_QUOTE PERL_PV_ESCAPE_RE PERL_PV_ESCAPE_UNI PERL_PV_ESCAPE_UNI_DETECT PERL_PV_PRETTY_ELLIPSES PERL_PV_PRETTY_LTGT PERL_PV_PRETTY_QUOTE" |
| 5271 |
.IX Header "Display functions" |
| 5272 |
.ie n .IP """form""" 4 |
| 5273 |
.el .IP \f(CWform\fR 4 |
| 5274 |
.IX Item "form" |
| 5275 |
.PD 0 |
| 5276 |
.ie n .IP """form_nocontext""" 4 |
| 5277 |
.el .IP \f(CWform_nocontext\fR 4 |
| 5278 |
.IX Xref "form form_nocontext" |
| 5279 |
.IX Item "form_nocontext" |
| 5280 |
.PD |
| 5281 |
These take a sprintf-style format pattern and conventional |
| 5282 |
(non-SV) arguments and return the formatted string. |
| 5283 |
.Sp |
| 5284 |
.Vb 1 |
| 5285 |
\& (char *) Perl_form(aTHX_ const char* pat, ...) |
| 5286 |
.Ve |
| 5287 |
.Sp |
| 5288 |
They can be used any place a string (char *) is required: |
| 5289 |
.Sp |
| 5290 |
.Vb 1 |
| 5291 |
\& char * s = form_nocontext("%d.%d", major, minor); |
| 5292 |
.Ve |
| 5293 |
.Sp |
| 5294 |
They each return a temporary that will be freed "soon", automatically by the |
| 5295 |
system, at the same time that SVs operated on by \f(CW"sv_2mortal"\fR are freed. |
| 5296 |
.Sp |
| 5297 |
Use the result immediately, or copy to a stable place for longer retention. |
| 5298 |
This is contrary to the incorrect previous documentation of these that claimed |
| 5299 |
that the return was a single per-thread buffer. That was (and is) actually |
| 5300 |
true only when these are called during global destruction. |
| 5301 |
.Sp |
| 5302 |
The two forms differ only in that \f(CW\*(C`form_nocontext\*(C'\fR does not take a thread |
| 5303 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 5304 |
already have the thread context. |
| 5305 |
.Sp |
| 5306 |
\&\f(CW"vform"\fR is the same except the arguments are an encapsulated argument list. |
| 5307 |
.Sp |
| 5308 |
NOTE: \f(CW\*(C`form\*(C'\fR must be explicitly called as |
| 5309 |
\&\f(CW\*(C`Perl_form\*(C'\fR |
| 5310 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 5311 |
.RS 4 |
| 5312 |
.Sp |
| 5313 |
.Vb 2 |
| 5314 |
\& char * Perl_form (pTHX_ const char *pat, ...) |
| 5315 |
\& char * form_nocontext(const char *pat, ...) |
| 5316 |
.Ve |
| 5317 |
.RE |
| 5318 |
.RS 4 |
| 5319 |
.RE |
| 5320 |
.ie n .IP """mess""" 4 |
| 5321 |
.el .IP \f(CWmess\fR 4 |
| 5322 |
.IX Item "mess" |
| 5323 |
.PD 0 |
| 5324 |
.ie n .IP """mess_nocontext""" 4 |
| 5325 |
.el .IP \f(CWmess_nocontext\fR 4 |
| 5326 |
.IX Xref "mess mess_nocontext" |
| 5327 |
.IX Item "mess_nocontext" |
| 5328 |
.PD |
| 5329 |
These take a sprintf-style format pattern and argument list, which are used to |
| 5330 |
generate a string message. If the message does not end with a newline, then it |
| 5331 |
will be extended with some indication of the current location in the code, as |
| 5332 |
described for \f(CW"mess_sv"\fR. |
| 5333 |
.Sp |
| 5334 |
Normally, the resulting message is returned in a new mortal SV. |
| 5335 |
But during global destruction a single SV may be shared between uses of |
| 5336 |
this function. |
| 5337 |
.Sp |
| 5338 |
The two forms differ only in that \f(CW\*(C`mess_nocontext\*(C'\fR does not take a thread |
| 5339 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 5340 |
already have the thread context. |
| 5341 |
.Sp |
| 5342 |
NOTE: \f(CW\*(C`mess\*(C'\fR must be explicitly called as |
| 5343 |
\&\f(CW\*(C`Perl_mess\*(C'\fR |
| 5344 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 5345 |
.RS 4 |
| 5346 |
.Sp |
| 5347 |
.Vb 2 |
| 5348 |
\& SV * Perl_mess (pTHX_ const char *pat, ...) |
| 5349 |
\& SV * mess_nocontext(const char *pat, ...) |
| 5350 |
.Ve |
| 5351 |
.RE |
| 5352 |
.RS 4 |
| 5353 |
.RE |
| 5354 |
.ie n .IP """mess_sv""" 4 |
| 5355 |
.el .IP \f(CWmess_sv\fR 4 |
| 5356 |
.IX Xref "mess_sv" |
| 5357 |
.IX Item "mess_sv" |
| 5358 |
Expands a message, intended for the user, to include an indication of |
| 5359 |
the current location in the code, if the message does not already appear |
| 5360 |
to be complete. |
| 5361 |
.Sp |
| 5362 |
\&\f(CW\*(C`basemsg\*(C'\fR is the initial message or object. If it is a reference, it |
| 5363 |
will be used as-is and will be the result of this function. Otherwise it |
| 5364 |
is used as a string, and if it already ends with a newline, it is taken |
| 5365 |
to be complete, and the result of this function will be the same string. |
| 5366 |
If the message does not end with a newline, then a segment such as \f(CW\*(C`at |
| 5367 |
foo.pl line 37\*(C'\fR will be appended, and possibly other clauses indicating |
| 5368 |
the current state of execution. The resulting message will end with a |
| 5369 |
dot and a newline. |
| 5370 |
.Sp |
| 5371 |
Normally, the resulting message is returned in a new mortal SV. |
| 5372 |
During global destruction a single SV may be shared between uses of this |
| 5373 |
function. If \f(CW\*(C`consume\*(C'\fR is true, then the function is permitted (but not |
| 5374 |
required) to modify and return \f(CW\*(C`basemsg\*(C'\fR instead of allocating a new SV. |
| 5375 |
.RS 4 |
| 5376 |
.Sp |
| 5377 |
.Vb 1 |
| 5378 |
\& SV * mess_sv(SV *basemsg, bool consume) |
| 5379 |
.Ve |
| 5380 |
.RE |
| 5381 |
.RS 4 |
| 5382 |
.RE |
| 5383 |
.ie n .IP """pv_display""" 4 |
| 5384 |
.el .IP \f(CWpv_display\fR 4 |
| 5385 |
.IX Xref "pv_display" |
| 5386 |
.IX Item "pv_display" |
| 5387 |
Similar to |
| 5388 |
.Sp |
| 5389 |
.Vb 1 |
| 5390 |
\& pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE); |
| 5391 |
.Ve |
| 5392 |
.Sp |
| 5393 |
except that an additional "\e0" will be appended to the string when |
| 5394 |
len > cur and pv[cur] is "\e0". |
| 5395 |
.Sp |
| 5396 |
Note that the final string may be up to 7 chars longer than pvlim. |
| 5397 |
.RS 4 |
| 5398 |
.Sp |
| 5399 |
.Vb 2 |
| 5400 |
\& char * pv_display(SV *dsv, const char *pv, STRLEN cur, |
| 5401 |
\& STRLEN len, STRLEN pvlim) |
| 5402 |
.Ve |
| 5403 |
.RE |
| 5404 |
.RS 4 |
| 5405 |
.RE |
| 5406 |
.ie n .IP """pv_escape""" 4 |
| 5407 |
.el .IP \f(CWpv_escape\fR 4 |
| 5408 |
.IX Xref "pv_escape" |
| 5409 |
.IX Item "pv_escape" |
| 5410 |
Escapes at most the first \f(CW\*(C`count\*(C'\fR chars of \f(CW\*(C`pv\*(C'\fR and puts the results into |
| 5411 |
\&\f(CW\*(C`dsv\*(C'\fR such that the size of the escaped string will not exceed \f(CW\*(C`max\*(C'\fR chars |
| 5412 |
and will not contain any incomplete escape sequences. The number of bytes |
| 5413 |
escaped will be returned in the \f(CW\*(C`STRLEN *escaped\*(C'\fR parameter if it is not null. |
| 5414 |
When the \f(CW\*(C`dsv\*(C'\fR parameter is null no escaping actually occurs, but the number |
| 5415 |
of bytes that would be escaped were it not null will be calculated. |
| 5416 |
.Sp |
| 5417 |
If flags contains \f(CW\*(C`PERL_PV_ESCAPE_QUOTE\*(C'\fR then any double quotes in the string |
| 5418 |
will also be escaped. |
| 5419 |
.Sp |
| 5420 |
Normally the SV will be cleared before the escaped string is prepared, |
| 5421 |
but when \f(CW\*(C`PERL_PV_ESCAPE_NOCLEAR\*(C'\fR is set this will not occur. |
| 5422 |
.Sp |
| 5423 |
If \f(CW\*(C`PERL_PV_ESCAPE_UNI\*(C'\fR is set then the input string is treated as UTF\-8. |
| 5424 |
If \f(CW\*(C`PERL_PV_ESCAPE_UNI_DETECT\*(C'\fR is set then the input string is scanned |
| 5425 |
using \f(CWis_utf8_string()\fR to determine if it is UTF\-8. |
| 5426 |
.Sp |
| 5427 |
If \f(CW\*(C`PERL_PV_ESCAPE_ALL\*(C'\fR is set then all input chars will be output |
| 5428 |
using \f(CW\*(C`\ex01F1\*(C'\fR style escapes, otherwise if \f(CW\*(C`PERL_PV_ESCAPE_NONASCII\*(C'\fR |
| 5429 |
is set, only non-ASCII chars will be escaped using this style; |
| 5430 |
otherwise, only chars above 255 will be so escaped; other non printable |
| 5431 |
chars will use octal or common escaped patterns like \f(CW\*(C`\en\*(C'\fR. Otherwise, |
| 5432 |
if \f(CW\*(C`PERL_PV_ESCAPE_NOBACKSLASH\*(C'\fR then all chars below 255 will be |
| 5433 |
treated as printable and will be output as literals. The |
| 5434 |
\&\f(CW\*(C`PERL_PV_ESCAPE_NON_WC\*(C'\fR modifies the previous rules to cause word |
| 5435 |
chars, unicode or otherwise, to be output as literals, note this uses |
| 5436 |
the *unicode* rules for deciding on word characters. |
| 5437 |
.Sp |
| 5438 |
If \f(CW\*(C`PERL_PV_ESCAPE_FIRSTCHAR\*(C'\fR is set then only the first char of the |
| 5439 |
string will be escaped, regardless of max. If the output is to be in |
| 5440 |
hex, then it will be returned as a plain hex sequence. Thus the output |
| 5441 |
will either be a single char, an octal escape sequence, a special escape |
| 5442 |
like \f(CW\*(C`\en\*(C'\fR or a hex value. |
| 5443 |
.Sp |
| 5444 |
If \f(CW\*(C`PERL_PV_ESCAPE_RE\*(C'\fR is set then the escape char used will be a |
| 5445 |
\&\f(CW"%"\fR and not a \f(CW"\e\e"\fR. This is because regexes very often contain |
| 5446 |
backslashed sequences, whereas \f(CW"%"\fR is not a particularly common |
| 5447 |
character in patterns. |
| 5448 |
.Sp |
| 5449 |
Returns a pointer to the escaped text as held by \f(CW\*(C`dsv\*(C'\fR. |
| 5450 |
.RS 4 |
| 5451 |
.Sp |
| 5452 |
.Vb 3 |
| 5453 |
\& char * pv_escape(SV *dsv, char const * const str, |
| 5454 |
\& const STRLEN count, STRLEN max, |
| 5455 |
\& STRLEN * const escaped, U32 flags) |
| 5456 |
.Ve |
| 5457 |
.RE |
| 5458 |
.RS 4 |
| 5459 |
.RE |
| 5460 |
.ie n .IP """pv_pretty""" 4 |
| 5461 |
.el .IP \f(CWpv_pretty\fR 4 |
| 5462 |
.IX Xref "pv_pretty" |
| 5463 |
.IX Item "pv_pretty" |
| 5464 |
Converts a string into something presentable, handling escaping via |
| 5465 |
\&\f(CWpv_escape()\fR and supporting quoting and ellipses. |
| 5466 |
.Sp |
| 5467 |
If the \f(CW\*(C`PERL_PV_PRETTY_QUOTE\*(C'\fR flag is set then the result will be |
| 5468 |
double quoted with any double quotes in the string escaped. Otherwise |
| 5469 |
if the \f(CW\*(C`PERL_PV_PRETTY_LTGT\*(C'\fR flag is set then the result be wrapped in |
| 5470 |
angle brackets. |
| 5471 |
.Sp |
| 5472 |
If the \f(CW\*(C`PERL_PV_PRETTY_ELLIPSES\*(C'\fR flag is set and not all characters in |
| 5473 |
string were output then an ellipsis \f(CW\*(C`...\*(C'\fR will be appended to the |
| 5474 |
string. Note that this happens AFTER it has been quoted. |
| 5475 |
.Sp |
| 5476 |
If \f(CW\*(C`start_color\*(C'\fR is non-null then it will be inserted after the opening |
| 5477 |
quote (if there is one) but before the escaped text. If \f(CW\*(C`end_color\*(C'\fR |
| 5478 |
is non-null then it will be inserted after the escaped text but before |
| 5479 |
any quotes or ellipses. |
| 5480 |
.Sp |
| 5481 |
Returns a pointer to the prettified text as held by \f(CW\*(C`dsv\*(C'\fR. |
| 5482 |
.RS 4 |
| 5483 |
.Sp |
| 5484 |
.Vb 4 |
| 5485 |
\& char * pv_pretty(SV *dsv, char const * const str, |
| 5486 |
\& const STRLEN count, const STRLEN max, |
| 5487 |
\& char const * const start_color, |
| 5488 |
\& char const * const end_color, const U32 flags) |
| 5489 |
.Ve |
| 5490 |
.RE |
| 5491 |
.RS 4 |
| 5492 |
.RE |
| 5493 |
.ie n .IP """vform""" 4 |
| 5494 |
.el .IP \f(CWvform\fR 4 |
| 5495 |
.IX Xref "vform" |
| 5496 |
.IX Item "vform" |
| 5497 |
Like \f(CW"form"\fR except the arguments are an encapsulated argument list. |
| 5498 |
.RS 4 |
| 5499 |
.Sp |
| 5500 |
.Vb 1 |
| 5501 |
\& char * vform(const char *pat, va_list *args) |
| 5502 |
.Ve |
| 5503 |
.RE |
| 5504 |
.RS 4 |
| 5505 |
.RE |
| 5506 |
.ie n .IP """vmess""" 4 |
| 5507 |
.el .IP \f(CWvmess\fR 4 |
| 5508 |
.IX Xref "vmess" |
| 5509 |
.IX Item "vmess" |
| 5510 |
\&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated |
| 5511 |
argument list, respectively. These are used to generate a string message. If |
| 5512 |
the |
| 5513 |
message does not end with a newline, then it will be extended with |
| 5514 |
some indication of the current location in the code, as described for |
| 5515 |
"mess_sv". |
| 5516 |
.Sp |
| 5517 |
Normally, the resulting message is returned in a new mortal SV. |
| 5518 |
During global destruction a single SV may be shared between uses of |
| 5519 |
this function. |
| 5520 |
.RS 4 |
| 5521 |
.Sp |
| 5522 |
.Vb 1 |
| 5523 |
\& SV * vmess(const char *pat, va_list *args) |
| 5524 |
.Ve |
| 5525 |
.RE |
| 5526 |
.RS 4 |
| 5527 |
.RE |
| 5528 |
.SH "Embedding, Threads, and Interpreter Cloning" |
| 5529 |
.IX Xref "CV_NAME_NOTQUAL PADNAMEf_OUTER PERL_EXIT_ABORT PERL_EXIT_DESTRUCT_END PERL_EXIT_EXPECTED PERL_EXIT_WARN PERL_LOADMOD_DENY PERL_LOADMOD_IMPORT_OPS PERL_LOADMOD_NOIMPORT" |
| 5530 |
.IX Header "Embedding, Threads, and Interpreter Cloning" |
| 5531 |
.ie n .IP """call_atexit""" 4 |
| 5532 |
.el .IP \f(CWcall_atexit\fR 4 |
| 5533 |
.IX Xref "call_atexit" |
| 5534 |
.IX Item "call_atexit" |
| 5535 |
Add a function \f(CW\*(C`fn\*(C'\fR to the list of functions to be called at global |
| 5536 |
destruction. \f(CW\*(C`ptr\*(C'\fR will be passed as an argument to \f(CW\*(C`fn\*(C'\fR; it can point to a |
| 5537 |
\&\f(CW\*(C`struct\*(C'\fR so that you can pass anything you want. |
| 5538 |
.Sp |
| 5539 |
Note that under threads, \f(CW\*(C`fn\*(C'\fR may run multiple times. This is because the |
| 5540 |
list is executed each time the current or any descendent thread terminates. |
| 5541 |
.RS 4 |
| 5542 |
.Sp |
| 5543 |
.Vb 1 |
| 5544 |
\& void call_atexit(ATEXIT_t fn, void *ptr) |
| 5545 |
.Ve |
| 5546 |
.RE |
| 5547 |
.RS 4 |
| 5548 |
.RE |
| 5549 |
.ie n .IP """cv_clone""" 4 |
| 5550 |
.el .IP \f(CWcv_clone\fR 4 |
| 5551 |
.IX Xref "cv_clone" |
| 5552 |
.IX Item "cv_clone" |
| 5553 |
Clone a CV, making a lexical closure. \f(CW\*(C`proto\*(C'\fR supplies the prototype |
| 5554 |
of the function: its code, pad structure, and other attributes. |
| 5555 |
The prototype is combined with a capture of outer lexicals to which the |
| 5556 |
code refers, which are taken from the currently-executing instance of |
| 5557 |
the immediately surrounding code. |
| 5558 |
.RS 4 |
| 5559 |
.Sp |
| 5560 |
.Vb 1 |
| 5561 |
\& CV * cv_clone(CV *proto) |
| 5562 |
.Ve |
| 5563 |
.RE |
| 5564 |
.RS 4 |
| 5565 |
.RE |
| 5566 |
.ie n .IP """cv_name""" 4 |
| 5567 |
.el .IP \f(CWcv_name\fR 4 |
| 5568 |
.IX Xref "cv_name" |
| 5569 |
.IX Item "cv_name" |
| 5570 |
Returns an SV containing the name of the CV, mainly for use in error |
| 5571 |
reporting. The CV may actually be a GV instead, in which case the returned |
| 5572 |
SV holds the GV's name. Anything other than a GV or CV is treated as a |
| 5573 |
string already holding the sub name, but this could change in the future. |
| 5574 |
.Sp |
| 5575 |
An SV may be passed as a second argument. If so, the name will be assigned |
| 5576 |
to it and it will be returned. Otherwise the returned SV will be a new |
| 5577 |
mortal. |
| 5578 |
.Sp |
| 5579 |
If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`CV_NAME_NOTQUAL\*(C'\fR bit set, then the package name will not be |
| 5580 |
included. If the first argument is neither a CV nor a GV, this flag is |
| 5581 |
ignored (subject to change). |
| 5582 |
.RS 4 |
| 5583 |
.Sp |
| 5584 |
.Vb 1 |
| 5585 |
\& SV * cv_name(CV *cv, SV *sv, U32 flags) |
| 5586 |
.Ve |
| 5587 |
.RE |
| 5588 |
.RS 4 |
| 5589 |
.RE |
| 5590 |
.ie n .IP """cv_undef""" 4 |
| 5591 |
.el .IP \f(CWcv_undef\fR 4 |
| 5592 |
.IX Xref "cv_undef" |
| 5593 |
.IX Item "cv_undef" |
| 5594 |
Clear out all the active components of a CV. This can happen either |
| 5595 |
by an explicit \f(CW\*(C`undef &foo\*(C'\fR, or by the reference count going to zero. |
| 5596 |
In the former case, we keep the \f(CW\*(C`CvOUTSIDE\*(C'\fR pointer, so that any anonymous |
| 5597 |
children can still follow the full lexical scope chain. |
| 5598 |
.RS 4 |
| 5599 |
.Sp |
| 5600 |
.Vb 1 |
| 5601 |
\& void cv_undef(CV *cv) |
| 5602 |
.Ve |
| 5603 |
.RE |
| 5604 |
.RS 4 |
| 5605 |
.RE |
| 5606 |
.ie n .IP """find_rundefsv""" 4 |
| 5607 |
.el .IP \f(CWfind_rundefsv\fR 4 |
| 5608 |
.IX Xref "find_rundefsv" |
| 5609 |
.IX Item "find_rundefsv" |
| 5610 |
Returns the global variable \f(CW$_\fR. |
| 5611 |
.RS 4 |
| 5612 |
.Sp |
| 5613 |
.Vb 1 |
| 5614 |
\& SV * find_rundefsv() |
| 5615 |
.Ve |
| 5616 |
.RE |
| 5617 |
.RS 4 |
| 5618 |
.RE |
| 5619 |
.ie n .IP """get_op_descs""" 4 |
| 5620 |
.el .IP \f(CWget_op_descs\fR 4 |
| 5621 |
.IX Xref "get_op_descs" |
| 5622 |
.IX Item "get_op_descs" |
| 5623 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_descs\*(C'\fR |
| 5624 |
from a future release of Perl. Do not use it for |
| 5625 |
new code; remove it from existing code. |
| 5626 |
.Sp |
| 5627 |
Return a pointer to the array of all the descriptions of the various OPs |
| 5628 |
Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_desc[opcode]\*(C'\fR returns a |
| 5629 |
pointer to a C language string giving its description. |
| 5630 |
.RS 4 |
| 5631 |
.Sp |
| 5632 |
.Vb 1 |
| 5633 |
\& char ** get_op_descs() |
| 5634 |
.Ve |
| 5635 |
.RE |
| 5636 |
.RS 4 |
| 5637 |
.RE |
| 5638 |
.ie n .IP """get_op_names""" 4 |
| 5639 |
.el .IP \f(CWget_op_names\fR 4 |
| 5640 |
.IX Xref "get_op_names" |
| 5641 |
.IX Item "get_op_names" |
| 5642 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_names\*(C'\fR |
| 5643 |
from a future release of Perl. Do not use it for |
| 5644 |
new code; remove it from existing code. |
| 5645 |
.Sp |
| 5646 |
Return a pointer to the array of all the names of the various OPs |
| 5647 |
Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_name[opcode]\*(C'\fR returns a |
| 5648 |
pointer to a C language string giving its name. |
| 5649 |
.RS 4 |
| 5650 |
.Sp |
| 5651 |
.Vb 1 |
| 5652 |
\& char ** get_op_names() |
| 5653 |
.Ve |
| 5654 |
.RE |
| 5655 |
.RS 4 |
| 5656 |
.RE |
| 5657 |
.ie n .IP """HAS_SKIP_LOCALE_INIT""" 4 |
| 5658 |
.el .IP \f(CWHAS_SKIP_LOCALE_INIT\fR 4 |
| 5659 |
.IX Item "HAS_SKIP_LOCALE_INIT" |
| 5660 |
Described in perlembed. |
| 5661 |
.ie n .IP """intro_my""" 4 |
| 5662 |
.el .IP \f(CWintro_my\fR 4 |
| 5663 |
.IX Xref "intro_my" |
| 5664 |
.IX Item "intro_my" |
| 5665 |
"Introduce" \f(CW\*(C`my\*(C'\fR variables to visible status. This is called during parsing |
| 5666 |
at the end of each statement to make lexical variables visible to subsequent |
| 5667 |
statements. |
| 5668 |
.RS 4 |
| 5669 |
.Sp |
| 5670 |
.Vb 1 |
| 5671 |
\& U32 intro_my() |
| 5672 |
.Ve |
| 5673 |
.RE |
| 5674 |
.RS 4 |
| 5675 |
.RE |
| 5676 |
.ie n .IP """load_module""" 4 |
| 5677 |
.el .IP \f(CWload_module\fR 4 |
| 5678 |
.IX Item "load_module" |
| 5679 |
.PD 0 |
| 5680 |
.ie n .IP """load_module_nocontext""" 4 |
| 5681 |
.el .IP \f(CWload_module_nocontext\fR 4 |
| 5682 |
.IX Xref "load_module load_module_nocontext" |
| 5683 |
.IX Item "load_module_nocontext" |
| 5684 |
.PD |
| 5685 |
These load the module whose name is pointed to by the string part of \f(CW\*(C`name\*(C'\fR. |
| 5686 |
Note that the actual module name, not its filename, should be given. |
| 5687 |
Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if specified and not NULL, |
| 5688 |
provides version semantics similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional |
| 5689 |
trailing arguments can be used to specify arguments to the module's \f(CWimport()\fR |
| 5690 |
method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR; their precise handling depends |
| 5691 |
on the flags. The flags argument is a bitwise-ORed collection of any of |
| 5692 |
\&\f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR, \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR, or \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR |
| 5693 |
(or 0 for no flags). |
| 5694 |
.Sp |
| 5695 |
If \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR is set, the module is loaded as if with an empty |
| 5696 |
import list, as in \f(CW\*(C`use Foo::Bar ()\*(C'\fR; this is the only circumstance in which |
| 5697 |
the trailing optional arguments may be omitted entirely. Otherwise, if |
| 5698 |
\&\f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is set, the trailing arguments must consist of |
| 5699 |
exactly one \f(CW\*(C`OP*\*(C'\fR, containing the op tree that produces the relevant import |
| 5700 |
arguments. Otherwise, the trailing arguments must all be \f(CW\*(C`SV*\*(C'\fR values that |
| 5701 |
will be used as import arguments; and the list must be terminated with \f(CW\*(C`(SV*) |
| 5702 |
NULL\*(C'\fR. If neither \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR nor \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is |
| 5703 |
set, the trailing \f(CW\*(C`NULL\*(C'\fR pointer is needed even if no import arguments are |
| 5704 |
desired. The reference count for each specified \f(CW\*(C`SV*\*(C'\fR argument is |
| 5705 |
decremented. In addition, the \f(CW\*(C`name\*(C'\fR argument is modified. |
| 5706 |
.Sp |
| 5707 |
If \f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR is set, the module is loaded as if with \f(CW\*(C`no\*(C'\fR rather |
| 5708 |
than \f(CW\*(C`use\*(C'\fR. |
| 5709 |
.Sp |
| 5710 |
\&\f(CW\*(C`load_module\*(C'\fR and \f(CW\*(C`load_module_nocontext\*(C'\fR have the same apparent signature, |
| 5711 |
but the former hides the fact that it is accessing a thread context parameter. |
| 5712 |
So use the latter when you get a compilation error about \f(CW\*(C`pTHX\*(C'\fR. |
| 5713 |
.RS 4 |
| 5714 |
.Sp |
| 5715 |
.Vb 2 |
| 5716 |
\& void load_module (U32 flags, SV *name, SV *ver, ...) |
| 5717 |
\& void load_module_nocontext(U32 flags, SV *name, SV *ver, ...) |
| 5718 |
.Ve |
| 5719 |
.RE |
| 5720 |
.RS 4 |
| 5721 |
.RE |
| 5722 |
.ie n .IP """my_exit""" 4 |
| 5723 |
.el .IP \f(CWmy_exit\fR 4 |
| 5724 |
.IX Xref "my_exit" |
| 5725 |
.IX Item "my_exit" |
| 5726 |
A wrapper for the C library \fBexit\fR\|(3), honoring what "PL_exit_flags" in perlapi |
| 5727 |
say to do. |
| 5728 |
.RS 4 |
| 5729 |
.Sp |
| 5730 |
.Vb 1 |
| 5731 |
\& void my_exit(U32 status) |
| 5732 |
.Ve |
| 5733 |
.RE |
| 5734 |
.RS 4 |
| 5735 |
.RE |
| 5736 |
.ie n .IP """my_failure_exit""" 4 |
| 5737 |
.el .IP \f(CWmy_failure_exit\fR 4 |
| 5738 |
.IX Xref "my_failure_exit" |
| 5739 |
.IX Item "my_failure_exit" |
| 5740 |
Exit the running Perl process with an error. |
| 5741 |
.Sp |
| 5742 |
On non-VMS platforms, this is essentially equivalent to "\f(CW\*(C`my_exit\*(C'\fR", using |
| 5743 |
\&\f(CW\*(C`errno\*(C'\fR, but forces an en error code of 255 if \f(CW\*(C`errno\*(C'\fR is 0. |
| 5744 |
.Sp |
| 5745 |
On VMS, it takes care to set the appropriate severity bits in the exit status. |
| 5746 |
.RS 4 |
| 5747 |
.Sp |
| 5748 |
.Vb 1 |
| 5749 |
\& void my_failure_exit() |
| 5750 |
.Ve |
| 5751 |
.RE |
| 5752 |
.RS 4 |
| 5753 |
.RE |
| 5754 |
.ie n .IP """my_strlcat""" 4 |
| 5755 |
.el .IP \f(CWmy_strlcat\fR 4 |
| 5756 |
.IX Xref "my_strlcat" |
| 5757 |
.IX Item "my_strlcat" |
| 5758 |
The C library \f(CW\*(C`strlcat\*(C'\fR if available, or a Perl implementation of it. |
| 5759 |
This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings. |
| 5760 |
.Sp |
| 5761 |
\&\f(CWmy_strlcat()\fR appends string \f(CW\*(C`src\*(C'\fR to the end of \f(CW\*(C`dst\*(C'\fR. It will append at |
| 5762 |
most \f(CW\*(C`size\ \-\ strlen(dst)\ \-\ 1\*(C'\fR bytes. It will then \f(CW\*(C`NUL\*(C'\fR\-terminate, |
| 5763 |
unless \f(CW\*(C`size\*(C'\fR is 0 or the original \f(CW\*(C`dst\*(C'\fR string was longer than \f(CW\*(C`size\*(C'\fR (in |
| 5764 |
practice this should not happen as it means that either \f(CW\*(C`size\*(C'\fR is incorrect or |
| 5765 |
that \f(CW\*(C`dst\*(C'\fR is not a proper \f(CW\*(C`NUL\*(C'\fR\-terminated string). |
| 5766 |
.Sp |
| 5767 |
Note that \f(CW\*(C`size\*(C'\fR is the full size of the destination buffer and |
| 5768 |
the result is guaranteed to be \f(CW\*(C`NUL\*(C'\fR\-terminated if there is room. Note that |
| 5769 |
room for the \f(CW\*(C`NUL\*(C'\fR should be included in \f(CW\*(C`size\*(C'\fR. |
| 5770 |
.Sp |
| 5771 |
The return value is the total length that \f(CW\*(C`dst\*(C'\fR would have if \f(CW\*(C`size\*(C'\fR is |
| 5772 |
sufficiently large. Thus it is the initial length of \f(CW\*(C`dst\*(C'\fR plus the length of |
| 5773 |
\&\f(CW\*(C`src\*(C'\fR. If \f(CW\*(C`size\*(C'\fR is smaller than the return, the excess was not appended. |
| 5774 |
.RS 4 |
| 5775 |
.Sp |
| 5776 |
.Vb 1 |
| 5777 |
\& Size_t my_strlcat(char *dst, const char *src, Size_t size) |
| 5778 |
.Ve |
| 5779 |
.RE |
| 5780 |
.RS 4 |
| 5781 |
.RE |
| 5782 |
.ie n .IP """my_strlcpy""" 4 |
| 5783 |
.el .IP \f(CWmy_strlcpy\fR 4 |
| 5784 |
.IX Xref "my_strlcpy" |
| 5785 |
.IX Item "my_strlcpy" |
| 5786 |
The C library \f(CW\*(C`strlcpy\*(C'\fR if available, or a Perl implementation of it. |
| 5787 |
This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings. |
| 5788 |
.Sp |
| 5789 |
\&\f(CWmy_strlcpy()\fR copies up to \f(CW\*(C`size\ \-\ 1\*(C'\fR bytes from the string \f(CW\*(C`src\*(C'\fR |
| 5790 |
to \f(CW\*(C`dst\*(C'\fR, \f(CW\*(C`NUL\*(C'\fR\-terminating the result if \f(CW\*(C`size\*(C'\fR is not 0. |
| 5791 |
.Sp |
| 5792 |
The return value is the total length \f(CW\*(C`src\*(C'\fR would be if the copy completely |
| 5793 |
succeeded. If it is larger than \f(CW\*(C`size\*(C'\fR, the excess was not copied. |
| 5794 |
.RS 4 |
| 5795 |
.Sp |
| 5796 |
.Vb 1 |
| 5797 |
\& Size_t my_strlcpy(char *dst, const char *src, Size_t size) |
| 5798 |
.Ve |
| 5799 |
.RE |
| 5800 |
.RS 4 |
| 5801 |
.RE |
| 5802 |
.ie n .IP """newPADNAMELIST""" 4 |
| 5803 |
.el .IP \f(CWnewPADNAMELIST\fR 4 |
| 5804 |
.IX Xref "newPADNAMELIST" |
| 5805 |
.IX Item "newPADNAMELIST" |
| 5806 |
NOTE: \f(CW\*(C`newPADNAMELIST\*(C'\fR is \fBexperimental\fR and may change or be |
| 5807 |
removed without notice. |
| 5808 |
.Sp |
| 5809 |
Creates a new pad name list. \f(CW\*(C`max\*(C'\fR is the highest index for which space |
| 5810 |
is allocated. |
| 5811 |
.RS 4 |
| 5812 |
.Sp |
| 5813 |
.Vb 1 |
| 5814 |
\& PADNAMELIST * newPADNAMELIST(size_t max) |
| 5815 |
.Ve |
| 5816 |
.RE |
| 5817 |
.RS 4 |
| 5818 |
.RE |
| 5819 |
.ie n .IP """newPADNAMEouter""" 4 |
| 5820 |
.el .IP \f(CWnewPADNAMEouter\fR 4 |
| 5821 |
.IX Xref "newPADNAMEouter" |
| 5822 |
.IX Item "newPADNAMEouter" |
| 5823 |
NOTE: \f(CW\*(C`newPADNAMEouter\*(C'\fR is \fBexperimental\fR and may change or be |
| 5824 |
removed without notice. |
| 5825 |
.Sp |
| 5826 |
Constructs and returns a new pad name. Only use this function for names |
| 5827 |
that refer to outer lexicals. (See also "newPADNAMEpvn".) \f(CW\*(C`outer\*(C'\fR is |
| 5828 |
the outer pad name that this one mirrors. The returned pad name has the |
| 5829 |
\&\f(CW\*(C`PADNAMEf_OUTER\*(C'\fR flag already set. |
| 5830 |
.RS 4 |
| 5831 |
.Sp |
| 5832 |
.Vb 1 |
| 5833 |
\& PADNAME * newPADNAMEouter(PADNAME *outer) |
| 5834 |
.Ve |
| 5835 |
.RE |
| 5836 |
.RS 4 |
| 5837 |
.RE |
| 5838 |
.ie n .IP """newPADNAMEpvn""" 4 |
| 5839 |
.el .IP \f(CWnewPADNAMEpvn\fR 4 |
| 5840 |
.IX Xref "newPADNAMEpvn" |
| 5841 |
.IX Item "newPADNAMEpvn" |
| 5842 |
NOTE: \f(CW\*(C`newPADNAMEpvn\*(C'\fR is \fBexperimental\fR and may change or be |
| 5843 |
removed without notice. |
| 5844 |
.Sp |
| 5845 |
Constructs and returns a new pad name. \f(CW\*(C`s\*(C'\fR must be a UTF\-8 string. Do not |
| 5846 |
use this for pad names that point to outer lexicals. See |
| 5847 |
\&\f(CW"newPADNAMEouter"\fR. |
| 5848 |
.RS 4 |
| 5849 |
.Sp |
| 5850 |
.Vb 1 |
| 5851 |
\& PADNAME * newPADNAMEpvn(const char *s, STRLEN len) |
| 5852 |
.Ve |
| 5853 |
.RE |
| 5854 |
.RS 4 |
| 5855 |
.RE |
| 5856 |
.ie n .IP """nothreadhook""" 4 |
| 5857 |
.el .IP \f(CWnothreadhook\fR 4 |
| 5858 |
.IX Xref "nothreadhook" |
| 5859 |
.IX Item "nothreadhook" |
| 5860 |
Stub that provides thread hook for perl_destruct when there are |
| 5861 |
no threads. |
| 5862 |
.RS 4 |
| 5863 |
.Sp |
| 5864 |
.Vb 1 |
| 5865 |
\& int nothreadhook() |
| 5866 |
.Ve |
| 5867 |
.RE |
| 5868 |
.RS 4 |
| 5869 |
.RE |
| 5870 |
.ie n .IP """pad_add_anon""" 4 |
| 5871 |
.el .IP \f(CWpad_add_anon\fR 4 |
| 5872 |
.IX Xref "pad_add_anon" |
| 5873 |
.IX Item "pad_add_anon" |
| 5874 |
Allocates a place in the currently-compiling pad (via "pad_alloc") |
| 5875 |
for an anonymous function that is lexically scoped inside the |
| 5876 |
currently-compiling function. |
| 5877 |
The function \f(CW\*(C`func\*(C'\fR is linked into the pad, and its \f(CW\*(C`CvOUTSIDE\*(C'\fR link |
| 5878 |
to the outer scope is weakened to avoid a reference loop. |
| 5879 |
.Sp |
| 5880 |
One reference count is stolen, so you may need to do \f(CWSvREFCNT_inc(func)\fR. |
| 5881 |
.Sp |
| 5882 |
\&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the |
| 5883 |
pad entry is to support. This doesn't affect operational semantics, |
| 5884 |
but is used for debugging. |
| 5885 |
.RS 4 |
| 5886 |
.Sp |
| 5887 |
.Vb 1 |
| 5888 |
\& PADOFFSET pad_add_anon(CV *func, I32 optype) |
| 5889 |
.Ve |
| 5890 |
.RE |
| 5891 |
.RS 4 |
| 5892 |
.RE |
| 5893 |
.ie n .IP """pad_add_name_pv""" 4 |
| 5894 |
.el .IP \f(CWpad_add_name_pv\fR 4 |
| 5895 |
.IX Xref "pad_add_name_pv" |
| 5896 |
.IX Item "pad_add_name_pv" |
| 5897 |
Exactly like "pad_add_name_pvn", but takes a nul-terminated string |
| 5898 |
instead of a string/length pair. |
| 5899 |
.RS 4 |
| 5900 |
.Sp |
| 5901 |
.Vb 2 |
| 5902 |
\& PADOFFSET pad_add_name_pv(const char *name, const U32 flags, |
| 5903 |
\& HV *typestash, HV *ourstash) |
| 5904 |
.Ve |
| 5905 |
.RE |
| 5906 |
.RS 4 |
| 5907 |
.RE |
| 5908 |
.ie n .IP """pad_add_name_pvn""" 4 |
| 5909 |
.el .IP \f(CWpad_add_name_pvn\fR 4 |
| 5910 |
.IX Xref "pad_add_name_pvn" |
| 5911 |
.IX Item "pad_add_name_pvn" |
| 5912 |
Allocates a place in the currently-compiling pad for a named lexical |
| 5913 |
variable. Stores the name and other metadata in the name part of the |
| 5914 |
pad, and makes preparations to manage the variable's lexical scoping. |
| 5915 |
Returns the offset of the allocated pad slot. |
| 5916 |
.Sp |
| 5917 |
\&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name in UTF\-8, including |
| 5918 |
leading sigil. |
| 5919 |
If \f(CW\*(C`typestash\*(C'\fR is non-null, the name is for a typed lexical, and this |
| 5920 |
identifies the type. If \f(CW\*(C`ourstash\*(C'\fR is non-null, it's a lexical reference |
| 5921 |
to a package variable, and this identifies the package. The following |
| 5922 |
flags can be OR'ed together: |
| 5923 |
.Sp |
| 5924 |
.Vb 4 |
| 5925 |
\& padadd_OUR redundantly specifies if it\*(Aqs a package var |
| 5926 |
\& padadd_STATE variable will retain value persistently |
| 5927 |
\& padadd_NO_DUP_CHECK skip check for lexical shadowing |
| 5928 |
\& padadd_FIELD specifies that the lexical is a field for a class |
| 5929 |
.Ve |
| 5930 |
.RS 4 |
| 5931 |
.Sp |
| 5932 |
.Vb 3 |
| 5933 |
\& PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen, |
| 5934 |
\& U32 flags, HV *typestash, |
| 5935 |
\& HV *ourstash) |
| 5936 |
.Ve |
| 5937 |
.RE |
| 5938 |
.RS 4 |
| 5939 |
.RE |
| 5940 |
.ie n .IP """pad_add_name_sv""" 4 |
| 5941 |
.el .IP \f(CWpad_add_name_sv\fR 4 |
| 5942 |
.IX Xref "pad_add_name_sv" |
| 5943 |
.IX Item "pad_add_name_sv" |
| 5944 |
Exactly like "pad_add_name_pvn", but takes the name string in the form |
| 5945 |
of an SV instead of a string/length pair. |
| 5946 |
.RS 4 |
| 5947 |
.Sp |
| 5948 |
.Vb 2 |
| 5949 |
\& PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash, |
| 5950 |
\& HV *ourstash) |
| 5951 |
.Ve |
| 5952 |
.RE |
| 5953 |
.RS 4 |
| 5954 |
.RE |
| 5955 |
.ie n .IP """pad_alloc""" 4 |
| 5956 |
.el .IP \f(CWpad_alloc\fR 4 |
| 5957 |
.IX Xref "pad_alloc" |
| 5958 |
.IX Item "pad_alloc" |
| 5959 |
NOTE: \f(CW\*(C`pad_alloc\*(C'\fR is \fBexperimental\fR and may change or be |
| 5960 |
removed without notice. |
| 5961 |
.Sp |
| 5962 |
Allocates a place in the currently-compiling pad, |
| 5963 |
returning the offset of the allocated pad slot. |
| 5964 |
No name is initially attached to the pad slot. |
| 5965 |
\&\f(CW\*(C`tmptype\*(C'\fR is a set of flags indicating the kind of pad entry required, |
| 5966 |
which will be set in the value SV for the allocated pad entry: |
| 5967 |
.Sp |
| 5968 |
.Vb 3 |
| 5969 |
\& SVs_PADMY named lexical variable ("my", "our", "state") |
| 5970 |
\& SVs_PADTMP unnamed temporary store |
| 5971 |
\& SVf_READONLY constant shared between recursion levels |
| 5972 |
.Ve |
| 5973 |
.Sp |
| 5974 |
\&\f(CW\*(C`SVf_READONLY\*(C'\fR has been supported here only since perl 5.20. To work with |
| 5975 |
earlier versions as well, use \f(CW\*(C`SVf_READONLY|SVs_PADTMP\*(C'\fR. \f(CW\*(C`SVf_READONLY\*(C'\fR |
| 5976 |
does not cause the SV in the pad slot to be marked read-only, but simply |
| 5977 |
tells \f(CW\*(C`pad_alloc\*(C'\fR that it \fIwill\fR be made read-only (by the caller), or at |
| 5978 |
least should be treated as such. |
| 5979 |
.Sp |
| 5980 |
\&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the |
| 5981 |
pad entry is to support. This doesn't affect operational semantics, |
| 5982 |
but is used for debugging. |
| 5983 |
.RS 4 |
| 5984 |
.Sp |
| 5985 |
.Vb 1 |
| 5986 |
\& PADOFFSET pad_alloc(I32 optype, U32 tmptype) |
| 5987 |
.Ve |
| 5988 |
.RE |
| 5989 |
.RS 4 |
| 5990 |
.RE |
| 5991 |
.ie n .IP """pad_findmy_pv""" 4 |
| 5992 |
.el .IP \f(CWpad_findmy_pv\fR 4 |
| 5993 |
.IX Xref "pad_findmy_pv" |
| 5994 |
.IX Item "pad_findmy_pv" |
| 5995 |
Exactly like "pad_findmy_pvn", but takes a nul-terminated string |
| 5996 |
instead of a string/length pair. |
| 5997 |
.RS 4 |
| 5998 |
.Sp |
| 5999 |
.Vb 1 |
| 6000 |
\& PADOFFSET pad_findmy_pv(const char *name, U32 flags) |
| 6001 |
.Ve |
| 6002 |
.RE |
| 6003 |
.RS 4 |
| 6004 |
.RE |
| 6005 |
.ie n .IP """pad_findmy_pvn""" 4 |
| 6006 |
.el .IP \f(CWpad_findmy_pvn\fR 4 |
| 6007 |
.IX Xref "pad_findmy_pvn" |
| 6008 |
.IX Item "pad_findmy_pvn" |
| 6009 |
Given the name of a lexical variable, find its position in the |
| 6010 |
currently-compiling pad. |
| 6011 |
\&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name, including leading sigil. |
| 6012 |
\&\f(CW\*(C`flags\*(C'\fR is reserved and must be zero. |
| 6013 |
If it is not in the current pad but appears in the pad of any lexically |
| 6014 |
enclosing scope, then a pseudo-entry for it is added in the current pad. |
| 6015 |
Returns the offset in the current pad, |
| 6016 |
or \f(CW\*(C`NOT_IN_PAD\*(C'\fR if no such lexical is in scope. |
| 6017 |
.RS 4 |
| 6018 |
.Sp |
| 6019 |
.Vb 2 |
| 6020 |
\& PADOFFSET pad_findmy_pvn(const char *namepv, STRLEN namelen, |
| 6021 |
\& U32 flags) |
| 6022 |
.Ve |
| 6023 |
.RE |
| 6024 |
.RS 4 |
| 6025 |
.RE |
| 6026 |
.ie n .IP """pad_findmy_sv""" 4 |
| 6027 |
.el .IP \f(CWpad_findmy_sv\fR 4 |
| 6028 |
.IX Xref "pad_findmy_sv" |
| 6029 |
.IX Item "pad_findmy_sv" |
| 6030 |
Exactly like "pad_findmy_pvn", but takes the name string in the form |
| 6031 |
of an SV instead of a string/length pair. |
| 6032 |
.RS 4 |
| 6033 |
.Sp |
| 6034 |
.Vb 1 |
| 6035 |
\& PADOFFSET pad_findmy_sv(SV *name, U32 flags) |
| 6036 |
.Ve |
| 6037 |
.RE |
| 6038 |
.RS 4 |
| 6039 |
.RE |
| 6040 |
.ie n .IP """padnamelist_fetch""" 4 |
| 6041 |
.el .IP \f(CWpadnamelist_fetch\fR 4 |
| 6042 |
.IX Xref "padnamelist_fetch" |
| 6043 |
.IX Item "padnamelist_fetch" |
| 6044 |
NOTE: \f(CW\*(C`padnamelist_fetch\*(C'\fR is \fBexperimental\fR and may change or be |
| 6045 |
removed without notice. |
| 6046 |
.Sp |
| 6047 |
Fetches the pad name from the given index. |
| 6048 |
.RS 4 |
| 6049 |
.Sp |
| 6050 |
.Vb 1 |
| 6051 |
\& PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key) |
| 6052 |
.Ve |
| 6053 |
.RE |
| 6054 |
.RS 4 |
| 6055 |
.RE |
| 6056 |
.ie n .IP """padnamelist_store""" 4 |
| 6057 |
.el .IP \f(CWpadnamelist_store\fR 4 |
| 6058 |
.IX Xref "padnamelist_store" |
| 6059 |
.IX Item "padnamelist_store" |
| 6060 |
NOTE: \f(CW\*(C`padnamelist_store\*(C'\fR is \fBexperimental\fR and may change or be |
| 6061 |
removed without notice. |
| 6062 |
.Sp |
| 6063 |
Stores the pad name (which may be null) at the given index, freeing any |
| 6064 |
existing pad name in that slot. |
| 6065 |
.RS 4 |
| 6066 |
.Sp |
| 6067 |
.Vb 2 |
| 6068 |
\& PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key, |
| 6069 |
\& PADNAME *val) |
| 6070 |
.Ve |
| 6071 |
.RE |
| 6072 |
.RS 4 |
| 6073 |
.RE |
| 6074 |
.ie n .IP """pad_tidy""" 4 |
| 6075 |
.el .IP \f(CWpad_tidy\fR 4 |
| 6076 |
.IX Xref "pad_tidy" |
| 6077 |
.IX Item "pad_tidy" |
| 6078 |
NOTE: \f(CW\*(C`pad_tidy\*(C'\fR is \fBexperimental\fR and may change or be |
| 6079 |
removed without notice. |
| 6080 |
.Sp |
| 6081 |
Tidy up a pad at the end of compilation of the code to which it belongs. |
| 6082 |
Jobs performed here are: remove most stuff from the pads of anonsub |
| 6083 |
prototypes; give it a \f(CW@_\fR; mark temporaries as such. \f(CW\*(C`type\*(C'\fR indicates |
| 6084 |
the kind of subroutine: |
| 6085 |
.Sp |
| 6086 |
.Vb 3 |
| 6087 |
\& padtidy_SUB ordinary subroutine |
| 6088 |
\& padtidy_SUBCLONE prototype for lexical closure |
| 6089 |
\& padtidy_FORMAT format |
| 6090 |
.Ve |
| 6091 |
.RS 4 |
| 6092 |
.Sp |
| 6093 |
.Vb 1 |
| 6094 |
\& void pad_tidy(padtidy_type type) |
| 6095 |
.Ve |
| 6096 |
.RE |
| 6097 |
.RS 4 |
| 6098 |
.RE |
| 6099 |
.ie n .IP """perl_alloc""" 4 |
| 6100 |
.el .IP \f(CWperl_alloc\fR 4 |
| 6101 |
.IX Xref "perl_alloc" |
| 6102 |
.IX Item "perl_alloc" |
| 6103 |
Allocates a new Perl interpreter. See perlembed. |
| 6104 |
.RS 4 |
| 6105 |
.Sp |
| 6106 |
.Vb 1 |
| 6107 |
\& PerlInterpreter * perl_alloc() |
| 6108 |
.Ve |
| 6109 |
.RE |
| 6110 |
.RS 4 |
| 6111 |
.RE |
| 6112 |
.ie n .IP """PERL_ASYNC_CHECK""" 4 |
| 6113 |
.el .IP \f(CWPERL_ASYNC_CHECK\fR 4 |
| 6114 |
.IX Item "PERL_ASYNC_CHECK" |
| 6115 |
Described in perlinterp. |
| 6116 |
.RS 4 |
| 6117 |
.Sp |
| 6118 |
.Vb 1 |
| 6119 |
\& void PERL_ASYNC_CHECK() |
| 6120 |
.Ve |
| 6121 |
.RE |
| 6122 |
.RS 4 |
| 6123 |
.RE |
| 6124 |
.ie n .IP """perl_clone""" 4 |
| 6125 |
.el .IP \f(CWperl_clone\fR 4 |
| 6126 |
.IX Xref "perl_clone" |
| 6127 |
.IX Item "perl_clone" |
| 6128 |
Create and return a new interpreter by cloning the current one. |
| 6129 |
.Sp |
| 6130 |
\&\f(CW\*(C`perl_clone\*(C'\fR takes these flags as parameters: |
| 6131 |
.Sp |
| 6132 |
\&\f(CW\*(C`CLONEf_COPY_STACKS\*(C'\fR \- is used to, well, copy the stacks also, |
| 6133 |
without it we only clone the data and zero the stacks, |
| 6134 |
with it we copy the stacks and the new perl interpreter is |
| 6135 |
ready to run at the exact same point as the previous one. |
| 6136 |
The pseudo-fork code uses \f(CW\*(C`COPY_STACKS\*(C'\fR while the |
| 6137 |
threads\->create doesn't. |
| 6138 |
.Sp |
| 6139 |
\&\f(CW\*(C`CLONEf_KEEP_PTR_TABLE\*(C'\fR \- |
| 6140 |
\&\f(CW\*(C`perl_clone\*(C'\fR keeps a ptr_table with the pointer of the old |
| 6141 |
variable as a key and the new variable as a value, |
| 6142 |
this allows it to check if something has been cloned and not |
| 6143 |
clone it again, but rather just use the value and increase the |
| 6144 |
refcount. |
| 6145 |
If \f(CW\*(C`KEEP_PTR_TABLE\*(C'\fR is not set then \f(CW\*(C`perl_clone\*(C'\fR will kill the ptr_table |
| 6146 |
using the function \f(CW\*(C`ptr_table_free(PL_ptr_table);\ PL_ptr_table\ =\ NULL;\*(C'\fR. |
| 6147 |
A reason to keep it around is if you want to dup some of your own |
| 6148 |
variables which are outside the graph that perl scans. |
| 6149 |
.Sp |
| 6150 |
\&\f(CW\*(C`CLONEf_CLONE_HOST\*(C'\fR \- |
| 6151 |
This is a win32 thing, it is ignored on unix, it tells perl's |
| 6152 |
win32host code (which is c++) to clone itself, this is needed on |
| 6153 |
win32 if you want to run two threads at the same time, |
| 6154 |
if you just want to do some stuff in a separate perl interpreter |
| 6155 |
and then throw it away and return to the original one, |
| 6156 |
you don't need to do anything. |
| 6157 |
.RS 4 |
| 6158 |
.Sp |
| 6159 |
.Vb 2 |
| 6160 |
\& PerlInterpreter * perl_clone(PerlInterpreter *proto_perl, |
| 6161 |
\& UV flags) |
| 6162 |
.Ve |
| 6163 |
.RE |
| 6164 |
.RS 4 |
| 6165 |
.RE |
| 6166 |
.ie n .IP """perl_construct""" 4 |
| 6167 |
.el .IP \f(CWperl_construct\fR 4 |
| 6168 |
.IX Xref "perl_construct" |
| 6169 |
.IX Item "perl_construct" |
| 6170 |
Initializes a new Perl interpreter. See perlembed. |
| 6171 |
.RS 4 |
| 6172 |
.Sp |
| 6173 |
.Vb 1 |
| 6174 |
\& void perl_construct(PerlInterpreter *my_perl) |
| 6175 |
.Ve |
| 6176 |
.RE |
| 6177 |
.RS 4 |
| 6178 |
.RE |
| 6179 |
.ie n .IP """perl_destruct""" 4 |
| 6180 |
.el .IP \f(CWperl_destruct\fR 4 |
| 6181 |
.IX Xref "perl_destruct" |
| 6182 |
.IX Item "perl_destruct" |
| 6183 |
Shuts down a Perl interpreter. See perlembed for a tutorial. |
| 6184 |
.Sp |
| 6185 |
\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously |
| 6186 |
created through the use of "perl_alloc" and "perl_construct". It may |
| 6187 |
have been initialised through "perl_parse", and may have been used |
| 6188 |
through "perl_run" and other means. This function should be called for |
| 6189 |
any Perl interpreter that has been constructed with "perl_construct", |
| 6190 |
even if subsequent operations on it failed, for example if "perl_parse" |
| 6191 |
returned a non-zero value. |
| 6192 |
.Sp |
| 6193 |
If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word has the |
| 6194 |
\&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function will execute code |
| 6195 |
in \f(CW\*(C`END\*(C'\fR blocks before performing the rest of destruction. If it is |
| 6196 |
desired to make any use of the interpreter between "perl_parse" and |
| 6197 |
"perl_destruct" other than just calling "perl_run", then this flag |
| 6198 |
should be set early on. This matters if "perl_run" will not be called, |
| 6199 |
or if anything else will be done in addition to calling "perl_run". |
| 6200 |
.Sp |
| 6201 |
Returns a value be a suitable value to pass to the C library function |
| 6202 |
\&\f(CW\*(C`exit\*(C'\fR (or to return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating |
| 6203 |
the nature of the way the interpreter terminated. This takes into account |
| 6204 |
any failure of "perl_parse" and any early exit from "perl_run". |
| 6205 |
The exit code is of the type required by the host operating system, |
| 6206 |
so because of differing exit code conventions it is not portable to |
| 6207 |
interpret specific numeric values as having specific meanings. |
| 6208 |
.RS 4 |
| 6209 |
.Sp |
| 6210 |
.Vb 1 |
| 6211 |
\& int perl_destruct(PerlInterpreter *my_perl) |
| 6212 |
.Ve |
| 6213 |
.RE |
| 6214 |
.RS 4 |
| 6215 |
.RE |
| 6216 |
.ie n .IP """perl_free""" 4 |
| 6217 |
.el .IP \f(CWperl_free\fR 4 |
| 6218 |
.IX Xref "perl_free" |
| 6219 |
.IX Item "perl_free" |
| 6220 |
Releases a Perl interpreter. See perlembed. |
| 6221 |
.RS 4 |
| 6222 |
.Sp |
| 6223 |
.Vb 1 |
| 6224 |
\& void perl_free(PerlInterpreter *my_perl) |
| 6225 |
.Ve |
| 6226 |
.RE |
| 6227 |
.RS 4 |
| 6228 |
.RE |
| 6229 |
.ie n .IP """PERL_GET_CONTEXT""" 4 |
| 6230 |
.el .IP \f(CWPERL_GET_CONTEXT\fR 4 |
| 6231 |
.IX Item "PERL_GET_CONTEXT" |
| 6232 |
Described in perlguts. |
| 6233 |
.ie n .IP """PerlInterpreter""" 4 |
| 6234 |
.el .IP \f(CWPerlInterpreter\fR 4 |
| 6235 |
.IX Item "PerlInterpreter" |
| 6236 |
Described in perlembed. |
| 6237 |
.ie n .IP """perl_parse""" 4 |
| 6238 |
.el .IP \f(CWperl_parse\fR 4 |
| 6239 |
.IX Xref "perl_parse" |
| 6240 |
.IX Item "perl_parse" |
| 6241 |
Tells a Perl interpreter to parse a Perl script. This performs most |
| 6242 |
of the initialisation of a Perl interpreter. See perlembed for |
| 6243 |
a tutorial. |
| 6244 |
.Sp |
| 6245 |
\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter that is to parse the script. |
| 6246 |
It must have been previously created through the use of "perl_alloc" |
| 6247 |
and "perl_construct". \f(CW\*(C`xsinit\*(C'\fR points to a callback function that |
| 6248 |
will be called to set up the ability for this Perl interpreter to load |
| 6249 |
XS extensions, or may be null to perform no such setup. |
| 6250 |
.Sp |
| 6251 |
\&\f(CW\*(C`argc\*(C'\fR and \f(CW\*(C`argv\*(C'\fR supply a set of command-line arguments to the Perl |
| 6252 |
interpreter, as would normally be passed to the \f(CW\*(C`main\*(C'\fR function of |
| 6253 |
a C program. \f(CW\*(C`argv[argc]\*(C'\fR must be null. These arguments are where |
| 6254 |
the script to parse is specified, either by naming a script file or by |
| 6255 |
providing a script in a \f(CW\*(C`\-e\*(C'\fR option. |
| 6256 |
If \f(CW$0\fR will be written to in the Perl interpreter, then |
| 6257 |
the argument strings must be in writable memory, and so mustn't just be |
| 6258 |
string constants. |
| 6259 |
.Sp |
| 6260 |
\&\f(CW\*(C`env\*(C'\fR specifies a set of environment variables that will be used by |
| 6261 |
this Perl interpreter. If non-null, it must point to a null-terminated |
| 6262 |
array of environment strings. If null, the Perl interpreter will use |
| 6263 |
the environment supplied by the \f(CW\*(C`environ\*(C'\fR global variable. |
| 6264 |
.Sp |
| 6265 |
This function initialises the interpreter, and parses and compiles the |
| 6266 |
script specified by the command-line arguments. This includes executing |
| 6267 |
code in \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, and \f(CW\*(C`CHECK\*(C'\fR blocks. It does not execute |
| 6268 |
\&\f(CW\*(C`INIT\*(C'\fR blocks or the main program. |
| 6269 |
.Sp |
| 6270 |
Returns an integer of slightly tricky interpretation. The correct |
| 6271 |
use of the return value is as a truth value indicating whether there |
| 6272 |
was a failure in initialisation. If zero is returned, this indicates |
| 6273 |
that initialisation was successful, and it is safe to proceed to call |
| 6274 |
"perl_run" and make other use of it. If a non-zero value is returned, |
| 6275 |
this indicates some problem that means the interpreter wants to terminate. |
| 6276 |
The interpreter should not be just abandoned upon such failure; the caller |
| 6277 |
should proceed to shut the interpreter down cleanly with "perl_destruct" |
| 6278 |
and free it with "perl_free". |
| 6279 |
.Sp |
| 6280 |
For historical reasons, the non-zero return value also attempts to |
| 6281 |
be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to |
| 6282 |
return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature |
| 6283 |
of the way initialisation terminated. However, this isn't portable, |
| 6284 |
due to differing exit code conventions. An attempt is made to return |
| 6285 |
an exit code of the type required by the host operating system, but |
| 6286 |
because it is constrained to be non-zero, it is not necessarily possible |
| 6287 |
to indicate every type of exit. It is only reliable on Unix, where a |
| 6288 |
zero exit code can be augmented with a set bit that will be ignored. |
| 6289 |
In any case, this function is not the correct place to acquire an exit |
| 6290 |
code: one should get that from "perl_destruct". |
| 6291 |
.RS 4 |
| 6292 |
.Sp |
| 6293 |
.Vb 2 |
| 6294 |
\& int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, |
| 6295 |
\& int argc, char **argv, char **env) |
| 6296 |
.Ve |
| 6297 |
.RE |
| 6298 |
.RS 4 |
| 6299 |
.RE |
| 6300 |
.ie n .IP """perl_run""" 4 |
| 6301 |
.el .IP \f(CWperl_run\fR 4 |
| 6302 |
.IX Xref "perl_run" |
| 6303 |
.IX Item "perl_run" |
| 6304 |
Tells a Perl interpreter to run its main program. See perlembed |
| 6305 |
for a tutorial. |
| 6306 |
.Sp |
| 6307 |
\&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously |
| 6308 |
created through the use of "perl_alloc" and "perl_construct", and |
| 6309 |
initialised through "perl_parse". This function should not be called |
| 6310 |
if "perl_parse" returned a non-zero value, indicating a failure in |
| 6311 |
initialisation or compilation. |
| 6312 |
.Sp |
| 6313 |
This function executes code in \f(CW\*(C`INIT\*(C'\fR blocks, and then executes the |
| 6314 |
main program. The code to be executed is that established by the prior |
| 6315 |
call to "perl_parse". If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word |
| 6316 |
does not have the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function |
| 6317 |
will also execute code in \f(CW\*(C`END\*(C'\fR blocks. If it is desired to make any |
| 6318 |
further use of the interpreter after calling this function, then \f(CW\*(C`END\*(C'\fR |
| 6319 |
blocks should be postponed to "perl_destruct" time by setting that flag. |
| 6320 |
.Sp |
| 6321 |
Returns an integer of slightly tricky interpretation. The correct use |
| 6322 |
of the return value is as a truth value indicating whether the program |
| 6323 |
terminated non-locally. If zero is returned, this indicates that |
| 6324 |
the program ran to completion, and it is safe to make other use of the |
| 6325 |
interpreter (provided that the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag was set as |
| 6326 |
described above). If a non-zero value is returned, this indicates that |
| 6327 |
the interpreter wants to terminate early. The interpreter should not be |
| 6328 |
just abandoned because of this desire to terminate; the caller should |
| 6329 |
proceed to shut the interpreter down cleanly with "perl_destruct" |
| 6330 |
and free it with "perl_free". |
| 6331 |
.Sp |
| 6332 |
For historical reasons, the non-zero return value also attempts to |
| 6333 |
be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to |
| 6334 |
return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature of |
| 6335 |
the way the program terminated. However, this isn't portable, due to |
| 6336 |
differing exit code conventions. An attempt is made to return an exit |
| 6337 |
code of the type required by the host operating system, but because |
| 6338 |
it is constrained to be non-zero, it is not necessarily possible to |
| 6339 |
indicate every type of exit. It is only reliable on Unix, where a zero |
| 6340 |
exit code can be augmented with a set bit that will be ignored. In any |
| 6341 |
case, this function is not the correct place to acquire an exit code: |
| 6342 |
one should get that from "perl_destruct". |
| 6343 |
.RS 4 |
| 6344 |
.Sp |
| 6345 |
.Vb 1 |
| 6346 |
\& int perl_run(PerlInterpreter *my_perl) |
| 6347 |
.Ve |
| 6348 |
.RE |
| 6349 |
.RS 4 |
| 6350 |
.RE |
| 6351 |
.ie n .IP """PERL_SET_CONTEXT""" 4 |
| 6352 |
.el .IP \f(CWPERL_SET_CONTEXT\fR 4 |
| 6353 |
.IX Item "PERL_SET_CONTEXT" |
| 6354 |
Described in perlguts. |
| 6355 |
.RS 4 |
| 6356 |
.Sp |
| 6357 |
.Vb 1 |
| 6358 |
\& void PERL_SET_CONTEXT(PerlInterpreter* i) |
| 6359 |
.Ve |
| 6360 |
.RE |
| 6361 |
.RS 4 |
| 6362 |
.RE |
| 6363 |
.ie n .IP """PERL_SYS_INIT""" 4 |
| 6364 |
.el .IP \f(CWPERL_SYS_INIT\fR 4 |
| 6365 |
.IX Item "PERL_SYS_INIT" |
| 6366 |
.PD 0 |
| 6367 |
.ie n .IP """PERL_SYS_INIT3""" 4 |
| 6368 |
.el .IP \f(CWPERL_SYS_INIT3\fR 4 |
| 6369 |
.IX Xref "PERL_SYS_INIT PERL_SYS_INIT3" |
| 6370 |
.IX Item "PERL_SYS_INIT3" |
| 6371 |
.PD |
| 6372 |
These provide system-specific tune up of the C runtime environment necessary to |
| 6373 |
run Perl interpreters. Only one should be used, and it should be called only |
| 6374 |
once, before creating any Perl interpreters. |
| 6375 |
.Sp |
| 6376 |
They differ in that \f(CW\*(C`PERL_SYS_INIT3\*(C'\fR also initializes \f(CW\*(C`env\*(C'\fR. |
| 6377 |
.RS 4 |
| 6378 |
.Sp |
| 6379 |
.Vb 2 |
| 6380 |
\& void PERL_SYS_INIT (int *argc, char*** argv) |
| 6381 |
\& void PERL_SYS_INIT3(int *argc, char*** argv, char*** env) |
| 6382 |
.Ve |
| 6383 |
.RE |
| 6384 |
.RS 4 |
| 6385 |
.RE |
| 6386 |
.ie n .IP """PERL_SYS_TERM""" 4 |
| 6387 |
.el .IP \f(CWPERL_SYS_TERM\fR 4 |
| 6388 |
.IX Xref "PERL_SYS_TERM" |
| 6389 |
.IX Item "PERL_SYS_TERM" |
| 6390 |
Provides system-specific clean up of the C runtime environment after |
| 6391 |
running Perl interpreters. This should be called only once, after |
| 6392 |
freeing any remaining Perl interpreters. |
| 6393 |
.RS 4 |
| 6394 |
.Sp |
| 6395 |
.Vb 1 |
| 6396 |
\& void PERL_SYS_TERM() |
| 6397 |
.Ve |
| 6398 |
.RE |
| 6399 |
.RS 4 |
| 6400 |
.RE |
| 6401 |
.ie n .IP """PL_exit_flags""" 4 |
| 6402 |
.el .IP \f(CWPL_exit_flags\fR 4 |
| 6403 |
.IX Xref "PL_exit_flags" |
| 6404 |
.IX Item "PL_exit_flags" |
| 6405 |
Contains flags controlling perl's behaviour on \fBexit()\fR: |
| 6406 |
.RS 4 |
| 6407 |
.IP \(bu 4 |
| 6408 |
\&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR |
| 6409 |
.Sp |
| 6410 |
If set, END blocks are executed when the interpreter is destroyed. |
| 6411 |
This is normally set by perl itself after the interpreter is |
| 6412 |
constructed. |
| 6413 |
.IP \(bu 4 |
| 6414 |
\&\f(CW\*(C`PERL_EXIT_ABORT\*(C'\fR |
| 6415 |
.Sp |
| 6416 |
Call \f(CWabort()\fR on exit. This is used internally by perl itself to |
| 6417 |
abort if exit is called while processing exit. |
| 6418 |
.IP \(bu 4 |
| 6419 |
\&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR |
| 6420 |
.Sp |
| 6421 |
Warn on exit. |
| 6422 |
.IP \(bu 4 |
| 6423 |
\&\f(CW\*(C`PERL_EXIT_EXPECTED\*(C'\fR |
| 6424 |
.Sp |
| 6425 |
Set by the "exit" in perlfunc operator. |
| 6426 |
.RE |
| 6427 |
.RS 4 |
| 6428 |
.Sp |
| 6429 |
.Vb 1 |
| 6430 |
\& U8 PL_exit_flags |
| 6431 |
.Ve |
| 6432 |
.RE |
| 6433 |
.RS 4 |
| 6434 |
.RE |
| 6435 |
.ie n .IP """PL_origalen""" 4 |
| 6436 |
.el .IP \f(CWPL_origalen\fR 4 |
| 6437 |
.IX Item "PL_origalen" |
| 6438 |
Described in perlembed. |
| 6439 |
.ie n .IP """PL_perl_destruct_level""" 4 |
| 6440 |
.el .IP \f(CWPL_perl_destruct_level\fR 4 |
| 6441 |
.IX Xref "PL_perl_destruct_level" |
| 6442 |
.IX Item "PL_perl_destruct_level" |
| 6443 |
This value may be set when embedding for full cleanup. |
| 6444 |
.Sp |
| 6445 |
Possible values: |
| 6446 |
.RS 4 |
| 6447 |
.IP \(bu 4 |
| 6448 |
0 \- none |
| 6449 |
.IP \(bu 4 |
| 6450 |
1 \- full |
| 6451 |
.IP \(bu 4 |
| 6452 |
2 or greater \- full with checks. |
| 6453 |
.RE |
| 6454 |
.RS 4 |
| 6455 |
.Sp |
| 6456 |
If \f(CW$ENV{PERL_DESTRUCT_LEVEL}\fR is set to an integer greater than the |
| 6457 |
value of \f(CW\*(C`PL_perl_destruct_level\*(C'\fR its value is used instead. |
| 6458 |
.Sp |
| 6459 |
On threaded perls, each thread has an independent copy of this variable; |
| 6460 |
each initialized at creation time with the current value of the creating |
| 6461 |
thread's copy. |
| 6462 |
.Sp |
| 6463 |
.Vb 1 |
| 6464 |
\& signed char PL_perl_destruct_level |
| 6465 |
.Ve |
| 6466 |
.RE |
| 6467 |
.RS 4 |
| 6468 |
.RE |
| 6469 |
.ie n .IP """ptr_table_fetch""" 4 |
| 6470 |
.el .IP \f(CWptr_table_fetch\fR 4 |
| 6471 |
.IX Xref "ptr_table_fetch" |
| 6472 |
.IX Item "ptr_table_fetch" |
| 6473 |
Look for \f(CW\*(C`sv\*(C'\fR in the pointer-mapping table \f(CW\*(C`tbl\*(C'\fR, returning its value, or |
| 6474 |
NULL if not found. |
| 6475 |
.RS 4 |
| 6476 |
.Sp |
| 6477 |
.Vb 2 |
| 6478 |
\& void * ptr_table_fetch(PTR_TBL_t * const tbl, |
| 6479 |
\& const void * const sv) |
| 6480 |
.Ve |
| 6481 |
.RE |
| 6482 |
.RS 4 |
| 6483 |
.RE |
| 6484 |
.ie n .IP """ptr_table_free""" 4 |
| 6485 |
.el .IP \f(CWptr_table_free\fR 4 |
| 6486 |
.IX Xref "ptr_table_free" |
| 6487 |
.IX Item "ptr_table_free" |
| 6488 |
Clear and free a ptr table |
| 6489 |
.RS 4 |
| 6490 |
.Sp |
| 6491 |
.Vb 1 |
| 6492 |
\& void ptr_table_free(PTR_TBL_t * const tbl) |
| 6493 |
.Ve |
| 6494 |
.RE |
| 6495 |
.RS 4 |
| 6496 |
.RE |
| 6497 |
.ie n .IP """ptr_table_new""" 4 |
| 6498 |
.el .IP \f(CWptr_table_new\fR 4 |
| 6499 |
.IX Xref "ptr_table_new" |
| 6500 |
.IX Item "ptr_table_new" |
| 6501 |
Create a new pointer-mapping table |
| 6502 |
.RS 4 |
| 6503 |
.Sp |
| 6504 |
.Vb 1 |
| 6505 |
\& PTR_TBL_t * ptr_table_new() |
| 6506 |
.Ve |
| 6507 |
.RE |
| 6508 |
.RS 4 |
| 6509 |
.RE |
| 6510 |
.ie n .IP """ptr_table_split""" 4 |
| 6511 |
.el .IP \f(CWptr_table_split\fR 4 |
| 6512 |
.IX Xref "ptr_table_split" |
| 6513 |
.IX Item "ptr_table_split" |
| 6514 |
Double the hash bucket size of an existing ptr table |
| 6515 |
.RS 4 |
| 6516 |
.Sp |
| 6517 |
.Vb 1 |
| 6518 |
\& void ptr_table_split(PTR_TBL_t * const tbl) |
| 6519 |
.Ve |
| 6520 |
.RE |
| 6521 |
.RS 4 |
| 6522 |
.RE |
| 6523 |
.ie n .IP """ptr_table_store""" 4 |
| 6524 |
.el .IP \f(CWptr_table_store\fR 4 |
| 6525 |
.IX Xref "ptr_table_store" |
| 6526 |
.IX Item "ptr_table_store" |
| 6527 |
Add a new entry to a pointer-mapping table \f(CW\*(C`tbl\*(C'\fR. |
| 6528 |
In hash terms, \f(CW\*(C`oldsv\*(C'\fR is the key; Cnewsv> is the value. |
| 6529 |
.Sp |
| 6530 |
The names "old" and "new" are specific to the core's typical use of ptr_tables |
| 6531 |
in thread cloning. |
| 6532 |
.RS 4 |
| 6533 |
.Sp |
| 6534 |
.Vb 3 |
| 6535 |
\& void ptr_table_store(PTR_TBL_t * const tbl, |
| 6536 |
\& const void * const oldsv, |
| 6537 |
\& void * const newsv) |
| 6538 |
.Ve |
| 6539 |
.RE |
| 6540 |
.RS 4 |
| 6541 |
.RE |
| 6542 |
.ie n .IP """require_pv""" 4 |
| 6543 |
.el .IP \f(CWrequire_pv\fR 4 |
| 6544 |
.IX Xref "require_pv" |
| 6545 |
.IX Item "require_pv" |
| 6546 |
Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument. It is |
| 6547 |
analogous to the Perl code \f(CW\*(C`eval "require \*(Aq$file\*(Aq"\*(C'\fR. It's even |
| 6548 |
implemented that way; consider using load_module instead. |
| 6549 |
.Sp |
| 6550 |
NOTE: the \f(CWperl_require_pv()\fR form is \fBdeprecated\fR. |
| 6551 |
.RS 4 |
| 6552 |
.Sp |
| 6553 |
.Vb 1 |
| 6554 |
\& void require_pv(const char *pv) |
| 6555 |
.Ve |
| 6556 |
.RE |
| 6557 |
.RS 4 |
| 6558 |
.RE |
| 6559 |
.ie n .IP """vload_module""" 4 |
| 6560 |
.el .IP \f(CWvload_module\fR 4 |
| 6561 |
.IX Xref "vload_module" |
| 6562 |
.IX Item "vload_module" |
| 6563 |
Like \f(CW"load_module"\fR but the arguments are an encapsulated argument list. |
| 6564 |
.RS 4 |
| 6565 |
.Sp |
| 6566 |
.Vb 1 |
| 6567 |
\& void vload_module(U32 flags, SV *name, SV *ver, va_list *args) |
| 6568 |
.Ve |
| 6569 |
.RE |
| 6570 |
.RS 4 |
| 6571 |
.RE |
| 6572 |
.SH Errno |
| 6573 |
.IX Header "Errno" |
| 6574 |
.ie n .IP """sv_string_from_errnum""" 4 |
| 6575 |
.el .IP \f(CWsv_string_from_errnum\fR 4 |
| 6576 |
.IX Xref "sv_string_from_errnum" |
| 6577 |
.IX Item "sv_string_from_errnum" |
| 6578 |
Generates the message string describing an OS error and returns it as |
| 6579 |
an SV. \f(CW\*(C`errnum\*(C'\fR must be a value that \f(CW\*(C`errno\*(C'\fR could take, identifying |
| 6580 |
the type of error. |
| 6581 |
.Sp |
| 6582 |
If \f(CW\*(C`tgtsv\*(C'\fR is non-null then the string will be written into that SV |
| 6583 |
(overwriting existing content) and it will be returned. If \f(CW\*(C`tgtsv\*(C'\fR |
| 6584 |
is a null pointer then the string will be written into a new mortal SV |
| 6585 |
which will be returned. |
| 6586 |
.Sp |
| 6587 |
The message will be taken from whatever locale would be used by \f(CW$!\fR, |
| 6588 |
and will be encoded in the SV in whatever manner would be used by \f(CW$!\fR. |
| 6589 |
The details of this process are subject to future change. Currently, |
| 6590 |
the message is taken from the C locale by default (usually producing an |
| 6591 |
English message), and from the currently selected locale when in the scope |
| 6592 |
of the \f(CW\*(C`use locale\*(C'\fR pragma. A heuristic attempt is made to decode the |
| 6593 |
message from the locale's character encoding, but it will only be decoded |
| 6594 |
as either UTF\-8 or ISO\-8859\-1. It is always correctly decoded in a UTF\-8 |
| 6595 |
locale, usually in an ISO\-8859\-1 locale, and never in any other locale. |
| 6596 |
.Sp |
| 6597 |
The SV is always returned containing an actual string, and with no other |
| 6598 |
OK bits set. Unlike \f(CW$!\fR, a message is even yielded for \f(CW\*(C`errnum\*(C'\fR zero |
| 6599 |
(meaning success), and if no useful message is available then a useless |
| 6600 |
string (currently empty) is returned. |
| 6601 |
.RS 4 |
| 6602 |
.Sp |
| 6603 |
.Vb 1 |
| 6604 |
\& SV * sv_string_from_errnum(int errnum, SV *tgtsv) |
| 6605 |
.Ve |
| 6606 |
.RE |
| 6607 |
.RS 4 |
| 6608 |
.RE |
| 6609 |
.SH "Exception Handling (simple) Macros" |
| 6610 |
.IX Header "Exception Handling (simple) Macros" |
| 6611 |
.ie n .IP """dXCPT""" 4 |
| 6612 |
.el .IP \f(CWdXCPT\fR 4 |
| 6613 |
.IX Xref "dXCPT" |
| 6614 |
.IX Item "dXCPT" |
| 6615 |
Set up necessary local variables for exception handling. |
| 6616 |
See "Exception Handling" in perlguts. |
| 6617 |
.RS 4 |
| 6618 |
.Sp |
| 6619 |
.Vb 1 |
| 6620 |
\& dXCPT; |
| 6621 |
.Ve |
| 6622 |
.RE |
| 6623 |
.RS 4 |
| 6624 |
.RE |
| 6625 |
.ie n .IP """JMPENV_JUMP""" 4 |
| 6626 |
.el .IP \f(CWJMPENV_JUMP\fR 4 |
| 6627 |
.IX Item "JMPENV_JUMP" |
| 6628 |
Described in perlinterp. |
| 6629 |
.RS 4 |
| 6630 |
.Sp |
| 6631 |
.Vb 1 |
| 6632 |
\& void JMPENV_JUMP(int v) |
| 6633 |
.Ve |
| 6634 |
.RE |
| 6635 |
.RS 4 |
| 6636 |
.RE |
| 6637 |
.ie n .IP """JMPENV_PUSH""" 4 |
| 6638 |
.el .IP \f(CWJMPENV_PUSH\fR 4 |
| 6639 |
.IX Item "JMPENV_PUSH" |
| 6640 |
Described in perlinterp. |
| 6641 |
.RS 4 |
| 6642 |
.Sp |
| 6643 |
.Vb 1 |
| 6644 |
\& void JMPENV_PUSH(int v) |
| 6645 |
.Ve |
| 6646 |
.RE |
| 6647 |
.RS 4 |
| 6648 |
.RE |
| 6649 |
.ie n .IP """PL_restartop""" 4 |
| 6650 |
.el .IP \f(CWPL_restartop\fR 4 |
| 6651 |
.IX Item "PL_restartop" |
| 6652 |
Described in perlinterp. |
| 6653 |
.ie n .IP """XCPT_CATCH""" 4 |
| 6654 |
.el .IP \f(CWXCPT_CATCH\fR 4 |
| 6655 |
.IX Xref "XCPT_CATCH" |
| 6656 |
.IX Item "XCPT_CATCH" |
| 6657 |
Introduces a catch block. See "Exception Handling" in perlguts. |
| 6658 |
.ie n .IP """XCPT_RETHROW""" 4 |
| 6659 |
.el .IP \f(CWXCPT_RETHROW\fR 4 |
| 6660 |
.IX Xref "XCPT_RETHROW" |
| 6661 |
.IX Item "XCPT_RETHROW" |
| 6662 |
Rethrows a previously caught exception. See "Exception Handling" in perlguts. |
| 6663 |
.RS 4 |
| 6664 |
.Sp |
| 6665 |
.Vb 1 |
| 6666 |
\& XCPT_RETHROW; |
| 6667 |
.Ve |
| 6668 |
.RE |
| 6669 |
.RS 4 |
| 6670 |
.RE |
| 6671 |
.ie n .IP """XCPT_TRY_END""" 4 |
| 6672 |
.el .IP \f(CWXCPT_TRY_END\fR 4 |
| 6673 |
.IX Xref "XCPT_TRY_END" |
| 6674 |
.IX Item "XCPT_TRY_END" |
| 6675 |
Ends a try block. See "Exception Handling" in perlguts. |
| 6676 |
.ie n .IP """XCPT_TRY_START""" 4 |
| 6677 |
.el .IP \f(CWXCPT_TRY_START\fR 4 |
| 6678 |
.IX Xref "XCPT_TRY_START" |
| 6679 |
.IX Item "XCPT_TRY_START" |
| 6680 |
Starts a try block. See "Exception Handling" in perlguts. |
| 6681 |
.SH "Filesystem configuration values" |
| 6682 |
.IX Header "Filesystem configuration values" |
| 6683 |
Also see "List of capability HAS_foo symbols". |
| 6684 |
.ie n .IP """DIRNAMLEN""" 4 |
| 6685 |
.el .IP \f(CWDIRNAMLEN\fR 4 |
| 6686 |
.IX Xref "DIRNAMLEN" |
| 6687 |
.IX Item "DIRNAMLEN" |
| 6688 |
This symbol, if defined, indicates to the C program that the length |
| 6689 |
of directory entry names is provided by a \f(CW\*(C`d_namlen\*(C'\fR field. Otherwise |
| 6690 |
you need to do \f(CWstrlen()\fR on the \f(CW\*(C`d_name\*(C'\fR field. |
| 6691 |
.ie n .IP """DOSUID""" 4 |
| 6692 |
.el .IP \f(CWDOSUID\fR 4 |
| 6693 |
.IX Xref "DOSUID" |
| 6694 |
.IX Item "DOSUID" |
| 6695 |
This symbol, if defined, indicates that the C program should |
| 6696 |
check the script that it is executing for setuid/setgid bits, and |
| 6697 |
attempt to emulate setuid/setgid on systems that have disabled |
| 6698 |
setuid #! scripts because the kernel can't do it securely. |
| 6699 |
It is up to the package designer to make sure that this emulation |
| 6700 |
is done securely. Among other things, it should do an fstat on |
| 6701 |
the script it just opened to make sure it really is a setuid/setgid |
| 6702 |
script, it should make sure the arguments passed correspond exactly |
| 6703 |
to the argument on the #! line, and it should not trust any |
| 6704 |
subprocesses to which it must pass the filename rather than the |
| 6705 |
file descriptor of the script to be executed. |
| 6706 |
.ie n .IP """EOF_NONBLOCK""" 4 |
| 6707 |
.el .IP \f(CWEOF_NONBLOCK\fR 4 |
| 6708 |
.IX Xref "EOF_NONBLOCK" |
| 6709 |
.IX Item "EOF_NONBLOCK" |
| 6710 |
This symbol, if defined, indicates to the C program that a \f(CWread()\fR on |
| 6711 |
a non-blocking file descriptor will return 0 on \f(CW\*(C`EOF\*(C'\fR, and not the value |
| 6712 |
held in \f(CW\*(C`RD_NODATA\*(C'\fR (\-1 usually, in that case!). |
| 6713 |
.ie n .IP """FCNTL_CAN_LOCK""" 4 |
| 6714 |
.el .IP \f(CWFCNTL_CAN_LOCK\fR 4 |
| 6715 |
.IX Xref "FCNTL_CAN_LOCK" |
| 6716 |
.IX Item "FCNTL_CAN_LOCK" |
| 6717 |
This symbol, if defined, indicates that \f(CWfcntl()\fR can be used |
| 6718 |
for file locking. Normally on Unix systems this is defined. |
| 6719 |
It may be undefined on \f(CW\*(C`VMS\*(C'\fR. |
| 6720 |
.ie n .IP """FFLUSH_ALL""" 4 |
| 6721 |
.el .IP \f(CWFFLUSH_ALL\fR 4 |
| 6722 |
.IX Xref "FFLUSH_ALL" |
| 6723 |
.IX Item "FFLUSH_ALL" |
| 6724 |
This symbol, if defined, tells that to flush |
| 6725 |
all pending stdio output one must loop through all |
| 6726 |
the stdio file handles stored in an array and fflush them. |
| 6727 |
Note that if \f(CW\*(C`fflushNULL\*(C'\fR is defined, fflushall will not |
| 6728 |
even be probed for and will be left undefined. |
| 6729 |
.ie n .IP """FFLUSH_NULL""" 4 |
| 6730 |
.el .IP \f(CWFFLUSH_NULL\fR 4 |
| 6731 |
.IX Xref "FFLUSH_NULL" |
| 6732 |
.IX Item "FFLUSH_NULL" |
| 6733 |
This symbol, if defined, tells that \f(CWfflush(NULL)\fR correctly |
| 6734 |
flushes all pending stdio output without side effects. In |
| 6735 |
particular, on some platforms calling \f(CWfflush(NULL)\fR *still* |
| 6736 |
corrupts \f(CW\*(C`STDIN\*(C'\fR if it is a pipe. |
| 6737 |
.ie n .IP """FILE_base""" 4 |
| 6738 |
.el .IP \f(CWFILE_base\fR 4 |
| 6739 |
.IX Xref "FILE_base" |
| 6740 |
.IX Item "FILE_base" |
| 6741 |
This macro is used to access the \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the |
| 6742 |
\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be |
| 6743 |
defined if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined. |
| 6744 |
.RS 4 |
| 6745 |
.Sp |
| 6746 |
.Vb 1 |
| 6747 |
\& void * FILE_base(FILE * f) |
| 6748 |
.Ve |
| 6749 |
.RE |
| 6750 |
.RS 4 |
| 6751 |
.RE |
| 6752 |
.ie n .IP """FILE_bufsiz""" 4 |
| 6753 |
.el .IP \f(CWFILE_bufsiz\fR 4 |
| 6754 |
.IX Xref "FILE_bufsiz" |
| 6755 |
.IX Item "FILE_bufsiz" |
| 6756 |
This macro is used to determine the number of bytes in the I/O |
| 6757 |
buffer pointed to by \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the \f(CW\*(C`FILE\*(C'\fR |
| 6758 |
structure pointed to its argument. This macro will always be defined |
| 6759 |
if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined. |
| 6760 |
.RS 4 |
| 6761 |
.Sp |
| 6762 |
.Vb 1 |
| 6763 |
\& Size_t FILE_bufsiz(FILE *f) |
| 6764 |
.Ve |
| 6765 |
.RE |
| 6766 |
.RS 4 |
| 6767 |
.RE |
| 6768 |
.ie n .IP """FILE_cnt""" 4 |
| 6769 |
.el .IP \f(CWFILE_cnt\fR 4 |
| 6770 |
.IX Xref "FILE_cnt" |
| 6771 |
.IX Item "FILE_cnt" |
| 6772 |
This macro is used to access the \f(CW\*(C`_cnt\*(C'\fR field (or equivalent) of the |
| 6773 |
\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be |
| 6774 |
defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined. |
| 6775 |
.RS 4 |
| 6776 |
.Sp |
| 6777 |
.Vb 1 |
| 6778 |
\& Size_t FILE_cnt(FILE * f) |
| 6779 |
.Ve |
| 6780 |
.RE |
| 6781 |
.RS 4 |
| 6782 |
.RE |
| 6783 |
.ie n .IP """FILE_ptr""" 4 |
| 6784 |
.el .IP \f(CWFILE_ptr\fR 4 |
| 6785 |
.IX Xref "FILE_ptr" |
| 6786 |
.IX Item "FILE_ptr" |
| 6787 |
This macro is used to access the \f(CW\*(C`_ptr\*(C'\fR field (or equivalent) of the |
| 6788 |
\&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be |
| 6789 |
defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined. |
| 6790 |
.RS 4 |
| 6791 |
.Sp |
| 6792 |
.Vb 1 |
| 6793 |
\& void * FILE_ptr(FILE * f) |
| 6794 |
.Ve |
| 6795 |
.RE |
| 6796 |
.RS 4 |
| 6797 |
.RE |
| 6798 |
.ie n .IP """FLEXFILENAMES""" 4 |
| 6799 |
.el .IP \f(CWFLEXFILENAMES\fR 4 |
| 6800 |
.IX Xref "FLEXFILENAMES" |
| 6801 |
.IX Item "FLEXFILENAMES" |
| 6802 |
This symbol, if defined, indicates that the system supports filenames |
| 6803 |
longer than 14 characters. |
| 6804 |
.ie n .IP """HAS_DIR_DD_FD""" 4 |
| 6805 |
.el .IP \f(CWHAS_DIR_DD_FD\fR 4 |
| 6806 |
.IX Xref "HAS_DIR_DD_FD" |
| 6807 |
.IX Item "HAS_DIR_DD_FD" |
| 6808 |
This symbol, if defined, indicates that the \f(CW\*(C`DIR\*(C'\fR* dirstream |
| 6809 |
structure contains a member variable named \f(CW\*(C`dd_fd\*(C'\fR. |
| 6810 |
.ie n .IP """HAS_DUP2""" 4 |
| 6811 |
.el .IP \f(CWHAS_DUP2\fR 4 |
| 6812 |
.IX Xref "HAS_DUP2" |
| 6813 |
.IX Item "HAS_DUP2" |
| 6814 |
This symbol, if defined, indicates that the \f(CW\*(C`dup2\*(C'\fR routine is |
| 6815 |
available to duplicate file descriptors. |
| 6816 |
.ie n .IP """HAS_DUP3""" 4 |
| 6817 |
.el .IP \f(CWHAS_DUP3\fR 4 |
| 6818 |
.IX Xref "HAS_DUP3" |
| 6819 |
.IX Item "HAS_DUP3" |
| 6820 |
This symbol, if defined, indicates that the \f(CW\*(C`dup3\*(C'\fR routine is |
| 6821 |
available to duplicate file descriptors. |
| 6822 |
.ie n .IP """HAS_FAST_STDIO""" 4 |
| 6823 |
.el .IP \f(CWHAS_FAST_STDIO\fR 4 |
| 6824 |
.IX Xref "HAS_FAST_STDIO" |
| 6825 |
.IX Item "HAS_FAST_STDIO" |
| 6826 |
This symbol, if defined, indicates that the "fast stdio" |
| 6827 |
is available to manipulate the stdio buffers directly. |
| 6828 |
.ie n .IP """HAS_FCHDIR""" 4 |
| 6829 |
.el .IP \f(CWHAS_FCHDIR\fR 4 |
| 6830 |
.IX Xref "HAS_FCHDIR" |
| 6831 |
.IX Item "HAS_FCHDIR" |
| 6832 |
This symbol, if defined, indicates that the \f(CW\*(C`fchdir\*(C'\fR routine is |
| 6833 |
available to change directory using a file descriptor. |
| 6834 |
.ie n .IP """HAS_FCNTL""" 4 |
| 6835 |
.el .IP \f(CWHAS_FCNTL\fR 4 |
| 6836 |
.IX Xref "HAS_FCNTL" |
| 6837 |
.IX Item "HAS_FCNTL" |
| 6838 |
This symbol, if defined, indicates to the C program that |
| 6839 |
the \f(CWfcntl()\fR function exists. |
| 6840 |
.ie n .IP """HAS_FDCLOSE""" 4 |
| 6841 |
.el .IP \f(CWHAS_FDCLOSE\fR 4 |
| 6842 |
.IX Xref "HAS_FDCLOSE" |
| 6843 |
.IX Item "HAS_FDCLOSE" |
| 6844 |
This symbol, if defined, indicates that the \f(CW\*(C`fdclose\*(C'\fR routine is |
| 6845 |
available to free a \f(CW\*(C`FILE\*(C'\fR structure without closing the underlying |
| 6846 |
file descriptor. This function appeared in \f(CW\*(C`FreeBSD\*(C'\fR 10.2. |
| 6847 |
.ie n .IP """HAS_FDOPENDIR""" 4 |
| 6848 |
.el .IP \f(CWHAS_FDOPENDIR\fR 4 |
| 6849 |
.IX Xref "HAS_FDOPENDIR" |
| 6850 |
.IX Item "HAS_FDOPENDIR" |
| 6851 |
This symbol, if defined, indicates that the \f(CWfdopendir()\fR routine is |
| 6852 |
available to open directories using an opened file descriptor already |
| 6853 |
referring to that directory. |
| 6854 |
.ie n .IP """HAS_FPATHCONF""" 4 |
| 6855 |
.el .IP \f(CWHAS_FPATHCONF\fR 4 |
| 6856 |
.IX Xref "HAS_FPATHCONF" |
| 6857 |
.IX Item "HAS_FPATHCONF" |
| 6858 |
This symbol, if defined, indicates that \f(CWpathconf()\fR is available |
| 6859 |
to determine file-system related limits and options associated |
| 6860 |
with a given open file descriptor. |
| 6861 |
.ie n .IP """HAS_FPOS64_T""" 4 |
| 6862 |
.el .IP \f(CWHAS_FPOS64_T\fR 4 |
| 6863 |
.IX Xref "HAS_FPOS64_T" |
| 6864 |
.IX Item "HAS_FPOS64_T" |
| 6865 |
This symbol will be defined if the C compiler supports \f(CW\*(C`fpos64_t\*(C'\fR. |
| 6866 |
.ie n .IP """HAS_FSTATFS""" 4 |
| 6867 |
.el .IP \f(CWHAS_FSTATFS\fR 4 |
| 6868 |
.IX Xref "HAS_FSTATFS" |
| 6869 |
.IX Item "HAS_FSTATFS" |
| 6870 |
This symbol, if defined, indicates that the \f(CW\*(C`fstatfs\*(C'\fR routine is |
| 6871 |
available to stat filesystems by file descriptors. |
| 6872 |
.ie n .IP """HAS_FSTATVFS""" 4 |
| 6873 |
.el .IP \f(CWHAS_FSTATVFS\fR 4 |
| 6874 |
.IX Xref "HAS_FSTATVFS" |
| 6875 |
.IX Item "HAS_FSTATVFS" |
| 6876 |
This symbol, if defined, indicates that the \f(CW\*(C`fstatvfs\*(C'\fR routine is |
| 6877 |
available to stat filesystems by file descriptors. |
| 6878 |
.ie n .IP """HAS_GETFSSTAT""" 4 |
| 6879 |
.el .IP \f(CWHAS_GETFSSTAT\fR 4 |
| 6880 |
.IX Xref "HAS_GETFSSTAT" |
| 6881 |
.IX Item "HAS_GETFSSTAT" |
| 6882 |
This symbol, if defined, indicates that the \f(CW\*(C`getfsstat\*(C'\fR routine is |
| 6883 |
available to stat filesystems in bulk. |
| 6884 |
.ie n .IP """HAS_GETMNT""" 4 |
| 6885 |
.el .IP \f(CWHAS_GETMNT\fR 4 |
| 6886 |
.IX Xref "HAS_GETMNT" |
| 6887 |
.IX Item "HAS_GETMNT" |
| 6888 |
This symbol, if defined, indicates that the \f(CW\*(C`getmnt\*(C'\fR routine is |
| 6889 |
available to get filesystem mount info by filename. |
| 6890 |
.ie n .IP """HAS_GETMNTENT""" 4 |
| 6891 |
.el .IP \f(CWHAS_GETMNTENT\fR 4 |
| 6892 |
.IX Xref "HAS_GETMNTENT" |
| 6893 |
.IX Item "HAS_GETMNTENT" |
| 6894 |
This symbol, if defined, indicates that the \f(CW\*(C`getmntent\*(C'\fR routine is |
| 6895 |
available to iterate through mounted file systems to get their info. |
| 6896 |
.ie n .IP """HAS_HASMNTOPT""" 4 |
| 6897 |
.el .IP \f(CWHAS_HASMNTOPT\fR 4 |
| 6898 |
.IX Xref "HAS_HASMNTOPT" |
| 6899 |
.IX Item "HAS_HASMNTOPT" |
| 6900 |
This symbol, if defined, indicates that the \f(CW\*(C`hasmntopt\*(C'\fR routine is |
| 6901 |
available to query the mount options of file systems. |
| 6902 |
.ie n .IP """HAS_LSEEK_PROTO""" 4 |
| 6903 |
.el .IP \f(CWHAS_LSEEK_PROTO\fR 4 |
| 6904 |
.IX Xref "HAS_LSEEK_PROTO" |
| 6905 |
.IX Item "HAS_LSEEK_PROTO" |
| 6906 |
This symbol, if defined, indicates that the system provides |
| 6907 |
a prototype for the \f(CWlseek()\fR function. Otherwise, it is up |
| 6908 |
to the program to supply one. A good guess is |
| 6909 |
.Sp |
| 6910 |
.Vb 1 |
| 6911 |
\& extern off_t lseek(int, off_t, int); |
| 6912 |
.Ve |
| 6913 |
.ie n .IP """HAS_MKDIR""" 4 |
| 6914 |
.el .IP \f(CWHAS_MKDIR\fR 4 |
| 6915 |
.IX Xref "HAS_MKDIR" |
| 6916 |
.IX Item "HAS_MKDIR" |
| 6917 |
This symbol, if defined, indicates that the \f(CW\*(C`mkdir\*(C'\fR routine is available |
| 6918 |
to create directories. Otherwise you should fork off a new process to |
| 6919 |
exec \fI/bin/mkdir\fR. |
| 6920 |
.ie n .IP """HAS_OFF64_T""" 4 |
| 6921 |
.el .IP \f(CWHAS_OFF64_T\fR 4 |
| 6922 |
.IX Xref "HAS_OFF64_T" |
| 6923 |
.IX Item "HAS_OFF64_T" |
| 6924 |
This symbol will be defined if the C compiler supports \f(CW\*(C`off64_t\*(C'\fR. |
| 6925 |
.ie n .IP """HAS_OPENAT""" 4 |
| 6926 |
.el .IP \f(CWHAS_OPENAT\fR 4 |
| 6927 |
.IX Xref "HAS_OPENAT" |
| 6928 |
.IX Item "HAS_OPENAT" |
| 6929 |
This symbol is defined if the \f(CWopenat()\fR routine is available. |
| 6930 |
.ie n .IP """HAS_OPEN3""" 4 |
| 6931 |
.el .IP \f(CWHAS_OPEN3\fR 4 |
| 6932 |
.IX Xref "HAS_OPEN3" |
| 6933 |
.IX Item "HAS_OPEN3" |
| 6934 |
This manifest constant lets the C program know that the three |
| 6935 |
argument form of \f(CWopen(2)\fR is available. |
| 6936 |
.ie n .IP """HAS_POLL""" 4 |
| 6937 |
.el .IP \f(CWHAS_POLL\fR 4 |
| 6938 |
.IX Xref "HAS_POLL" |
| 6939 |
.IX Item "HAS_POLL" |
| 6940 |
This symbol, if defined, indicates that the \f(CW\*(C`poll\*(C'\fR routine is |
| 6941 |
available to \f(CW\*(C`poll\*(C'\fR active file descriptors. Please check \f(CW\*(C`I_POLL\*(C'\fR and |
| 6942 |
\&\f(CW\*(C`I_SYS_POLL\*(C'\fR to know which header should be included as well. |
| 6943 |
.ie n .IP """HAS_READDIR""" 4 |
| 6944 |
.el .IP \f(CWHAS_READDIR\fR 4 |
| 6945 |
.IX Xref "HAS_READDIR" |
| 6946 |
.IX Item "HAS_READDIR" |
| 6947 |
This symbol, if defined, indicates that the \f(CW\*(C`readdir\*(C'\fR routine is |
| 6948 |
available to read directory entries. You may have to include |
| 6949 |
\&\fIdirent.h\fR. See \f(CW"I_DIRENT"\fR. |
| 6950 |
.ie n .IP """HAS_READDIR64_R""" 4 |
| 6951 |
.el .IP \f(CWHAS_READDIR64_R\fR 4 |
| 6952 |
.IX Xref "HAS_READDIR64_R" |
| 6953 |
.IX Item "HAS_READDIR64_R" |
| 6954 |
This symbol, if defined, indicates that the \f(CW\*(C`readdir64_r\*(C'\fR routine |
| 6955 |
is available to readdir64 re-entrantly. |
| 6956 |
.ie n .IP """HAS_REWINDDIR""" 4 |
| 6957 |
.el .IP \f(CWHAS_REWINDDIR\fR 4 |
| 6958 |
.IX Xref "HAS_REWINDDIR" |
| 6959 |
.IX Item "HAS_REWINDDIR" |
| 6960 |
This symbol, if defined, indicates that the \f(CW\*(C`rewinddir\*(C'\fR routine is |
| 6961 |
available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR. |
| 6962 |
.ie n .IP """HAS_RMDIR""" 4 |
| 6963 |
.el .IP \f(CWHAS_RMDIR\fR 4 |
| 6964 |
.IX Xref "HAS_RMDIR" |
| 6965 |
.IX Item "HAS_RMDIR" |
| 6966 |
This symbol, if defined, indicates that the \f(CW\*(C`rmdir\*(C'\fR routine is |
| 6967 |
available to remove directories. Otherwise you should fork off a |
| 6968 |
new process to exec \fI/bin/rmdir\fR. |
| 6969 |
.ie n .IP """HAS_SEEKDIR""" 4 |
| 6970 |
.el .IP \f(CWHAS_SEEKDIR\fR 4 |
| 6971 |
.IX Xref "HAS_SEEKDIR" |
| 6972 |
.IX Item "HAS_SEEKDIR" |
| 6973 |
This symbol, if defined, indicates that the \f(CW\*(C`seekdir\*(C'\fR routine is |
| 6974 |
available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR. |
| 6975 |
.ie n .IP """HAS_SELECT""" 4 |
| 6976 |
.el .IP \f(CWHAS_SELECT\fR 4 |
| 6977 |
.IX Xref "HAS_SELECT" |
| 6978 |
.IX Item "HAS_SELECT" |
| 6979 |
This symbol, if defined, indicates that the \f(CW\*(C`select\*(C'\fR routine is |
| 6980 |
available to \f(CW\*(C`select\*(C'\fR active file descriptors. If the timeout field |
| 6981 |
is used, \fIsys/time.h\fR may need to be included. |
| 6982 |
.ie n .IP """HAS_SETVBUF""" 4 |
| 6983 |
.el .IP \f(CWHAS_SETVBUF\fR 4 |
| 6984 |
.IX Xref "HAS_SETVBUF" |
| 6985 |
.IX Item "HAS_SETVBUF" |
| 6986 |
This symbol, if defined, indicates that the \f(CW\*(C`setvbuf\*(C'\fR routine is |
| 6987 |
available to change buffering on an open stdio stream. |
| 6988 |
to a line-buffered mode. |
| 6989 |
.ie n .IP """HAS_STDIO_STREAM_ARRAY""" 4 |
| 6990 |
.el .IP \f(CWHAS_STDIO_STREAM_ARRAY\fR 4 |
| 6991 |
.IX Xref "HAS_STDIO_STREAM_ARRAY" |
| 6992 |
.IX Item "HAS_STDIO_STREAM_ARRAY" |
| 6993 |
This symbol, if defined, tells that there is an array |
| 6994 |
holding the stdio streams. |
| 6995 |
.ie n .IP """HAS_STRUCT_FS_DATA""" 4 |
| 6996 |
.el .IP \f(CWHAS_STRUCT_FS_DATA\fR 4 |
| 6997 |
.IX Xref "HAS_STRUCT_FS_DATA" |
| 6998 |
.IX Item "HAS_STRUCT_FS_DATA" |
| 6999 |
This symbol, if defined, indicates that the \f(CW\*(C`struct fs_data\*(C'\fR |
| 7000 |
to do \f(CWstatfs()\fR is supported. |
| 7001 |
.ie n .IP """HAS_STRUCT_STATFS""" 4 |
| 7002 |
.el .IP \f(CWHAS_STRUCT_STATFS\fR 4 |
| 7003 |
.IX Xref "HAS_STRUCT_STATFS" |
| 7004 |
.IX Item "HAS_STRUCT_STATFS" |
| 7005 |
This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR |
| 7006 |
to do \f(CWstatfs()\fR is supported. |
| 7007 |
.ie n .IP """HAS_STRUCT_STATFS_F_FLAGS""" 4 |
| 7008 |
.el .IP \f(CWHAS_STRUCT_STATFS_F_FLAGS\fR 4 |
| 7009 |
.IX Xref "HAS_STRUCT_STATFS_F_FLAGS" |
| 7010 |
.IX Item "HAS_STRUCT_STATFS_F_FLAGS" |
| 7011 |
This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR |
| 7012 |
does have the \f(CW\*(C`f_flags\*(C'\fR member containing the mount flags of |
| 7013 |
the filesystem containing the file. |
| 7014 |
This kind of \f(CW\*(C`struct statfs\*(C'\fR is coming from \fIsys/mount.h\fR (\f(CW\*(C`BSD\*(C'\fR 4.3), |
| 7015 |
not from \fIsys/statfs.h\fR (\f(CW\*(C`SYSV\*(C'\fR). Older \f(CW\*(C`BSDs\*(C'\fR (like Ultrix) do not |
| 7016 |
have \f(CWstatfs()\fR and \f(CW\*(C`struct statfs\*(C'\fR, they have \f(CWustat()\fR and \f(CWgetmnt()\fR |
| 7017 |
with \f(CW\*(C`struct ustat\*(C'\fR and \f(CW\*(C`struct fs_data\*(C'\fR. |
| 7018 |
.ie n .IP """HAS_TELLDIR""" 4 |
| 7019 |
.el .IP \f(CWHAS_TELLDIR\fR 4 |
| 7020 |
.IX Xref "HAS_TELLDIR" |
| 7021 |
.IX Item "HAS_TELLDIR" |
| 7022 |
This symbol, if defined, indicates that the \f(CW\*(C`telldir\*(C'\fR routine is |
| 7023 |
available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR. |
| 7024 |
.ie n .IP """HAS_USTAT""" 4 |
| 7025 |
.el .IP \f(CWHAS_USTAT\fR 4 |
| 7026 |
.IX Xref "HAS_USTAT" |
| 7027 |
.IX Item "HAS_USTAT" |
| 7028 |
This symbol, if defined, indicates that the \f(CW\*(C`ustat\*(C'\fR system call is |
| 7029 |
available to query file system statistics by \f(CW\*(C`dev_t\*(C'\fR. |
| 7030 |
.ie n .IP """I_FCNTL""" 4 |
| 7031 |
.el .IP \f(CWI_FCNTL\fR 4 |
| 7032 |
.IX Xref "I_FCNTL" |
| 7033 |
.IX Item "I_FCNTL" |
| 7034 |
This manifest constant tells the C program to include \fIfcntl.h\fR. |
| 7035 |
.RS 4 |
| 7036 |
.Sp |
| 7037 |
.Vb 3 |
| 7038 |
\& #ifdef I_FCNTL |
| 7039 |
\& #include <fcntl.h> |
| 7040 |
\& #endif |
| 7041 |
.Ve |
| 7042 |
.RE |
| 7043 |
.RS 4 |
| 7044 |
.RE |
| 7045 |
.ie n .IP """I_SYS_DIR""" 4 |
| 7046 |
.el .IP \f(CWI_SYS_DIR\fR 4 |
| 7047 |
.IX Xref "I_SYS_DIR" |
| 7048 |
.IX Item "I_SYS_DIR" |
| 7049 |
This symbol, if defined, indicates to the C program that it should |
| 7050 |
include \fIsys/dir.h\fR. |
| 7051 |
.RS 4 |
| 7052 |
.Sp |
| 7053 |
.Vb 3 |
| 7054 |
\& #ifdef I_SYS_DIR |
| 7055 |
\& #include <sys_dir.h> |
| 7056 |
\& #endif |
| 7057 |
.Ve |
| 7058 |
.RE |
| 7059 |
.RS 4 |
| 7060 |
.RE |
| 7061 |
.ie n .IP """I_SYS_FILE""" 4 |
| 7062 |
.el .IP \f(CWI_SYS_FILE\fR 4 |
| 7063 |
.IX Xref "I_SYS_FILE" |
| 7064 |
.IX Item "I_SYS_FILE" |
| 7065 |
This symbol, if defined, indicates to the C program that it should |
| 7066 |
include \fIsys/file.h\fR to get definition of \f(CW\*(C`R_OK\*(C'\fR and friends. |
| 7067 |
.RS 4 |
| 7068 |
.Sp |
| 7069 |
.Vb 3 |
| 7070 |
\& #ifdef I_SYS_FILE |
| 7071 |
\& #include <sys_file.h> |
| 7072 |
\& #endif |
| 7073 |
.Ve |
| 7074 |
.RE |
| 7075 |
.RS 4 |
| 7076 |
.RE |
| 7077 |
.ie n .IP """I_SYS_NDIR""" 4 |
| 7078 |
.el .IP \f(CWI_SYS_NDIR\fR 4 |
| 7079 |
.IX Xref "I_SYS_NDIR" |
| 7080 |
.IX Item "I_SYS_NDIR" |
| 7081 |
This symbol, if defined, indicates to the C program that it should |
| 7082 |
include \fIsys/ndir.h\fR. |
| 7083 |
.RS 4 |
| 7084 |
.Sp |
| 7085 |
.Vb 3 |
| 7086 |
\& #ifdef I_SYS_NDIR |
| 7087 |
\& #include <sys_ndir.h> |
| 7088 |
\& #endif |
| 7089 |
.Ve |
| 7090 |
.RE |
| 7091 |
.RS 4 |
| 7092 |
.RE |
| 7093 |
.ie n .IP """I_SYS_STATFS""" 4 |
| 7094 |
.el .IP \f(CWI_SYS_STATFS\fR 4 |
| 7095 |
.IX Xref "I_SYS_STATFS" |
| 7096 |
.IX Item "I_SYS_STATFS" |
| 7097 |
This symbol, if defined, indicates that \fIsys/statfs.h\fR exists. |
| 7098 |
.RS 4 |
| 7099 |
.Sp |
| 7100 |
.Vb 3 |
| 7101 |
\& #ifdef I_SYS_STATFS |
| 7102 |
\& #include <sys_statfs.h> |
| 7103 |
\& #endif |
| 7104 |
.Ve |
| 7105 |
.RE |
| 7106 |
.RS 4 |
| 7107 |
.RE |
| 7108 |
.ie n .IP """LSEEKSIZE""" 4 |
| 7109 |
.el .IP \f(CWLSEEKSIZE\fR 4 |
| 7110 |
.IX Xref "LSEEKSIZE" |
| 7111 |
.IX Item "LSEEKSIZE" |
| 7112 |
This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR. |
| 7113 |
.ie n .IP """RD_NODATA""" 4 |
| 7114 |
.el .IP \f(CWRD_NODATA\fR 4 |
| 7115 |
.IX Xref "RD_NODATA" |
| 7116 |
.IX Item "RD_NODATA" |
| 7117 |
This symbol holds the return code from \f(CWread()\fR when no data is present |
| 7118 |
on the non-blocking file descriptor. Be careful! If \f(CW\*(C`EOF_NONBLOCK\*(C'\fR is |
| 7119 |
not defined, then you can't distinguish between no data and \f(CW\*(C`EOF\*(C'\fR by |
| 7120 |
issuing a \f(CWread()\fR. You'll have to find another way to tell for sure! |
| 7121 |
.ie n .IP """READDIR64_R_PROTO""" 4 |
| 7122 |
.el .IP \f(CWREADDIR64_R_PROTO\fR 4 |
| 7123 |
.IX Xref "READDIR64_R_PROTO" |
| 7124 |
.IX Item "READDIR64_R_PROTO" |
| 7125 |
This symbol encodes the prototype of \f(CW\*(C`readdir64_r\*(C'\fR. |
| 7126 |
It is zero if \f(CW\*(C`d_readdir64_r\*(C'\fR is undef, and one of the |
| 7127 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir64_r\*(C'\fR |
| 7128 |
is defined. |
| 7129 |
.ie n .IP """STDCHAR""" 4 |
| 7130 |
.el .IP \f(CWSTDCHAR\fR 4 |
| 7131 |
.IX Xref "STDCHAR" |
| 7132 |
.IX Item "STDCHAR" |
| 7133 |
This symbol is defined to be the type of char used in \fIstdio.h\fR. |
| 7134 |
It has the values "unsigned char" or "char". |
| 7135 |
.ie n .IP """STDIO_CNT_LVALUE""" 4 |
| 7136 |
.el .IP \f(CWSTDIO_CNT_LVALUE\fR 4 |
| 7137 |
.IX Xref "STDIO_CNT_LVALUE" |
| 7138 |
.IX Item "STDIO_CNT_LVALUE" |
| 7139 |
This symbol is defined if the \f(CW\*(C`FILE_cnt\*(C'\fR macro can be used as an |
| 7140 |
lvalue. |
| 7141 |
.ie n .IP """STDIO_PTR_LVAL_NOCHANGE_CNT""" 4 |
| 7142 |
.el .IP \f(CWSTDIO_PTR_LVAL_NOCHANGE_CNT\fR 4 |
| 7143 |
.IX Xref "STDIO_PTR_LVAL_NOCHANGE_CNT" |
| 7144 |
.IX Item "STDIO_PTR_LVAL_NOCHANGE_CNT" |
| 7145 |
This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue |
| 7146 |
to increase the pointer by n leaves \f(CWFile_cnt(fp)\fR unchanged. |
| 7147 |
.ie n .IP """STDIO_PTR_LVAL_SETS_CNT""" 4 |
| 7148 |
.el .IP \f(CWSTDIO_PTR_LVAL_SETS_CNT\fR 4 |
| 7149 |
.IX Xref "STDIO_PTR_LVAL_SETS_CNT" |
| 7150 |
.IX Item "STDIO_PTR_LVAL_SETS_CNT" |
| 7151 |
This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue |
| 7152 |
to increase the pointer by n has the side effect of decreasing the |
| 7153 |
value of \f(CWFile_cnt(fp)\fR by n. |
| 7154 |
.ie n .IP """STDIO_PTR_LVALUE""" 4 |
| 7155 |
.el .IP \f(CWSTDIO_PTR_LVALUE\fR 4 |
| 7156 |
.IX Xref "STDIO_PTR_LVALUE" |
| 7157 |
.IX Item "STDIO_PTR_LVALUE" |
| 7158 |
This symbol is defined if the \f(CW\*(C`FILE_ptr\*(C'\fR macro can be used as an |
| 7159 |
lvalue. |
| 7160 |
.ie n .IP """STDIO_STREAM_ARRAY""" 4 |
| 7161 |
.el .IP \f(CWSTDIO_STREAM_ARRAY\fR 4 |
| 7162 |
.IX Xref "STDIO_STREAM_ARRAY" |
| 7163 |
.IX Item "STDIO_STREAM_ARRAY" |
| 7164 |
This symbol tells the name of the array holding the stdio streams. |
| 7165 |
Usual values include \f(CW\*(C`_iob\*(C'\fR, \f(CW\*(C`_\|_iob\*(C'\fR, and \f(CW\*(C`_\|_sF\*(C'\fR. |
| 7166 |
.ie n .IP """ST_INO_SIGN""" 4 |
| 7167 |
.el .IP \f(CWST_INO_SIGN\fR 4 |
| 7168 |
.IX Xref "ST_INO_SIGN" |
| 7169 |
.IX Item "ST_INO_SIGN" |
| 7170 |
This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR. |
| 7171 |
1 for unsigned, \-1 for signed. |
| 7172 |
.ie n .IP """ST_INO_SIZE""" 4 |
| 7173 |
.el .IP \f(CWST_INO_SIZE\fR 4 |
| 7174 |
.IX Xref "ST_INO_SIZE" |
| 7175 |
.IX Item "ST_INO_SIZE" |
| 7176 |
This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR in bytes. |
| 7177 |
.ie n .IP """VAL_EAGAIN""" 4 |
| 7178 |
.el .IP \f(CWVAL_EAGAIN\fR 4 |
| 7179 |
.IX Xref "VAL_EAGAIN" |
| 7180 |
.IX Item "VAL_EAGAIN" |
| 7181 |
This symbol holds the errno error code set by \f(CWread()\fR when no data was |
| 7182 |
present on the non-blocking file descriptor. |
| 7183 |
.ie n .IP """VAL_O_NONBLOCK""" 4 |
| 7184 |
.el .IP \f(CWVAL_O_NONBLOCK\fR 4 |
| 7185 |
.IX Xref "VAL_O_NONBLOCK" |
| 7186 |
.IX Item "VAL_O_NONBLOCK" |
| 7187 |
This symbol is to be used during \f(CWopen()\fR or \f(CWfcntl(F_SETFL)\fR to turn on |
| 7188 |
non-blocking I/O for the file descriptor. Note that there is no way |
| 7189 |
back, i.e. you cannot turn it blocking again this way. If you wish to |
| 7190 |
alternatively switch between blocking and non-blocking, use the |
| 7191 |
\&\f(CWioctl(FIOSNBIO)\fR call instead, but that is not supported by all devices. |
| 7192 |
.ie n .IP """VOID_CLOSEDIR""" 4 |
| 7193 |
.el .IP \f(CWVOID_CLOSEDIR\fR 4 |
| 7194 |
.IX Xref "VOID_CLOSEDIR" |
| 7195 |
.IX Item "VOID_CLOSEDIR" |
| 7196 |
This symbol, if defined, indicates that the \f(CWclosedir()\fR routine |
| 7197 |
does not return a value. |
| 7198 |
.SH "Floating point" |
| 7199 |
.IX Header "Floating point" |
| 7200 |
Also "List of capability HAS_foo symbols" lists capabilities |
| 7201 |
that arent in this section. For example \f(CW\*(C`HAS_ASINH\*(C'\fR, for the |
| 7202 |
hyperbolic sine function. |
| 7203 |
.ie n .IP """CASTFLAGS""" 4 |
| 7204 |
.el .IP \f(CWCASTFLAGS\fR 4 |
| 7205 |
.IX Xref "CASTFLAGS" |
| 7206 |
.IX Item "CASTFLAGS" |
| 7207 |
This symbol contains flags that say what difficulties the compiler |
| 7208 |
has casting odd floating values to unsigned long: |
| 7209 |
.Sp |
| 7210 |
.Vb 4 |
| 7211 |
\& 0 = ok |
| 7212 |
\& 1 = couldn\*(Aqt cast < 0 |
| 7213 |
\& 2 = couldn\*(Aqt cast >= 0x80000000 |
| 7214 |
\& 4 = couldn\*(Aqt cast in argument expression list |
| 7215 |
.Ve |
| 7216 |
.ie n .IP """CASTNEGFLOAT""" 4 |
| 7217 |
.el .IP \f(CWCASTNEGFLOAT\fR 4 |
| 7218 |
.IX Xref "CASTNEGFLOAT" |
| 7219 |
.IX Item "CASTNEGFLOAT" |
| 7220 |
This symbol is defined if the C compiler can cast negative |
| 7221 |
numbers to unsigned longs, ints and shorts. |
| 7222 |
.ie n .IP """DOUBLE_HAS_INF""" 4 |
| 7223 |
.el .IP \f(CWDOUBLE_HAS_INF\fR 4 |
| 7224 |
.IX Xref "DOUBLE_HAS_INF" |
| 7225 |
.IX Item "DOUBLE_HAS_INF" |
| 7226 |
This symbol, if defined, indicates that the double has |
| 7227 |
the infinity. |
| 7228 |
.ie n .IP """DOUBLE_HAS_NAN""" 4 |
| 7229 |
.el .IP \f(CWDOUBLE_HAS_NAN\fR 4 |
| 7230 |
.IX Xref "DOUBLE_HAS_NAN" |
| 7231 |
.IX Item "DOUBLE_HAS_NAN" |
| 7232 |
This symbol, if defined, indicates that the double has |
| 7233 |
the not-a-number. |
| 7234 |
.ie n .IP """DOUBLE_HAS_NEGATIVE_ZERO""" 4 |
| 7235 |
.el .IP \f(CWDOUBLE_HAS_NEGATIVE_ZERO\fR 4 |
| 7236 |
.IX Xref "DOUBLE_HAS_NEGATIVE_ZERO" |
| 7237 |
.IX Item "DOUBLE_HAS_NEGATIVE_ZERO" |
| 7238 |
This symbol, if defined, indicates that the double has |
| 7239 |
the \f(CW\*(C`negative_zero\*(C'\fR. |
| 7240 |
.ie n .IP """DOUBLE_HAS_SUBNORMALS""" 4 |
| 7241 |
.el .IP \f(CWDOUBLE_HAS_SUBNORMALS\fR 4 |
| 7242 |
.IX Xref "DOUBLE_HAS_SUBNORMALS" |
| 7243 |
.IX Item "DOUBLE_HAS_SUBNORMALS" |
| 7244 |
This symbol, if defined, indicates that the double has |
| 7245 |
the subnormals (denormals). |
| 7246 |
.ie n .IP """DOUBLEINFBYTES""" 4 |
| 7247 |
.el .IP \f(CWDOUBLEINFBYTES\fR 4 |
| 7248 |
.IX Xref "DOUBLEINFBYTES" |
| 7249 |
.IX Item "DOUBLEINFBYTES" |
| 7250 |
This symbol, if defined, is a comma-separated list of |
| 7251 |
hexadecimal bytes for the double precision infinity. |
| 7252 |
.ie n .IP """DOUBLEKIND""" 4 |
| 7253 |
.el .IP \f(CWDOUBLEKIND\fR 4 |
| 7254 |
.IX Xref "DOUBLEKIND" |
| 7255 |
.IX Item "DOUBLEKIND" |
| 7256 |
\&\f(CW\*(C`DOUBLEKIND\*(C'\fR will be one of |
| 7257 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7258 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN\*(C'\fR |
| 7259 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7260 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN\*(C'\fR |
| 7261 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7262 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR |
| 7263 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE\*(C'\fR |
| 7264 |
\&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE\*(C'\fR |
| 7265 |
\&\f(CW\*(C`DOUBLE_IS_VAX_F_FLOAT\*(C'\fR |
| 7266 |
\&\f(CW\*(C`DOUBLE_IS_VAX_D_FLOAT\*(C'\fR |
| 7267 |
\&\f(CW\*(C`DOUBLE_IS_VAX_G_FLOAT\*(C'\fR |
| 7268 |
\&\f(CW\*(C`DOUBLE_IS_IBM_SINGLE_32_BIT\*(C'\fR |
| 7269 |
\&\f(CW\*(C`DOUBLE_IS_IBM_DOUBLE_64_BIT\*(C'\fR |
| 7270 |
\&\f(CW\*(C`DOUBLE_IS_CRAY_SINGLE_64_BIT\*(C'\fR |
| 7271 |
\&\f(CW\*(C`DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR |
| 7272 |
.ie n .IP """DOUBLEMANTBITS""" 4 |
| 7273 |
.el .IP \f(CWDOUBLEMANTBITS\fR 4 |
| 7274 |
.IX Xref "DOUBLEMANTBITS" |
| 7275 |
.IX Item "DOUBLEMANTBITS" |
| 7276 |
This symbol, if defined, tells how many mantissa bits |
| 7277 |
there are in double precision floating point format. |
| 7278 |
Note that this is usually \f(CW\*(C`DBL_MANT_DIG\*(C'\fR minus one, since |
| 7279 |
with the standard \f(CW\*(C`IEEE\*(C'\fR 754 formats \f(CW\*(C`DBL_MANT_DIG\*(C'\fR includes |
| 7280 |
the implicit bit, which doesn't really exist. |
| 7281 |
.ie n .IP """DOUBLENANBYTES""" 4 |
| 7282 |
.el .IP \f(CWDOUBLENANBYTES\fR 4 |
| 7283 |
.IX Xref "DOUBLENANBYTES" |
| 7284 |
.IX Item "DOUBLENANBYTES" |
| 7285 |
This symbol, if defined, is a comma-separated list of |
| 7286 |
hexadecimal bytes (0xHH) for the double precision not-a-number. |
| 7287 |
.ie n .IP """DOUBLESIZE""" 4 |
| 7288 |
.el .IP \f(CWDOUBLESIZE\fR 4 |
| 7289 |
.IX Xref "DOUBLESIZE" |
| 7290 |
.IX Item "DOUBLESIZE" |
| 7291 |
This symbol contains the size of a double, so that the C preprocessor |
| 7292 |
can make decisions based on it. |
| 7293 |
.ie n .IP """DOUBLE_STYLE_CRAY""" 4 |
| 7294 |
.el .IP \f(CWDOUBLE_STYLE_CRAY\fR 4 |
| 7295 |
.IX Xref "DOUBLE_STYLE_CRAY" |
| 7296 |
.IX Item "DOUBLE_STYLE_CRAY" |
| 7297 |
This symbol, if defined, indicates that the double is |
| 7298 |
the 64\-bit \f(CW\*(C`CRAY\*(C'\fR mainframe format. |
| 7299 |
.ie n .IP """DOUBLE_STYLE_IBM""" 4 |
| 7300 |
.el .IP \f(CWDOUBLE_STYLE_IBM\fR 4 |
| 7301 |
.IX Xref "DOUBLE_STYLE_IBM" |
| 7302 |
.IX Item "DOUBLE_STYLE_IBM" |
| 7303 |
This symbol, if defined, indicates that the double is |
| 7304 |
the 64\-bit \f(CW\*(C`IBM\*(C'\fR mainframe format. |
| 7305 |
.ie n .IP """DOUBLE_STYLE_IEEE""" 4 |
| 7306 |
.el .IP \f(CWDOUBLE_STYLE_IEEE\fR 4 |
| 7307 |
.IX Xref "DOUBLE_STYLE_IEEE" |
| 7308 |
.IX Item "DOUBLE_STYLE_IEEE" |
| 7309 |
This symbol, if defined, indicates that the double is |
| 7310 |
the 64\-bit \f(CW\*(C`IEEE\*(C'\fR 754. |
| 7311 |
.ie n .IP """DOUBLE_STYLE_VAX""" 4 |
| 7312 |
.el .IP \f(CWDOUBLE_STYLE_VAX\fR 4 |
| 7313 |
.IX Xref "DOUBLE_STYLE_VAX" |
| 7314 |
.IX Item "DOUBLE_STYLE_VAX" |
| 7315 |
This symbol, if defined, indicates that the double is |
| 7316 |
the 64\-bit \f(CW\*(C`VAX\*(C'\fR format D or G. |
| 7317 |
.ie n .IP """HAS_ATOLF""" 4 |
| 7318 |
.el .IP \f(CWHAS_ATOLF\fR 4 |
| 7319 |
.IX Xref "HAS_ATOLF" |
| 7320 |
.IX Item "HAS_ATOLF" |
| 7321 |
This symbol, if defined, indicates that the \f(CW\*(C`atolf\*(C'\fR routine is |
| 7322 |
available to convert strings into long doubles. |
| 7323 |
.ie n .IP """HAS_CLASS""" 4 |
| 7324 |
.el .IP \f(CWHAS_CLASS\fR 4 |
| 7325 |
.IX Xref "HAS_CLASS" |
| 7326 |
.IX Item "HAS_CLASS" |
| 7327 |
This symbol, if defined, indicates that the \f(CW\*(C`class\*(C'\fR routine is |
| 7328 |
available to classify doubles. Available for example in \f(CW\*(C`AIX\*(C'\fR. |
| 7329 |
The returned values are defined in \fIfloat.h\fR and are: |
| 7330 |
.Sp |
| 7331 |
.Vb 10 |
| 7332 |
\& FP_PLUS_NORM Positive normalized, nonzero |
| 7333 |
\& FP_MINUS_NORM Negative normalized, nonzero |
| 7334 |
\& FP_PLUS_DENORM Positive denormalized, nonzero |
| 7335 |
\& FP_MINUS_DENORM Negative denormalized, nonzero |
| 7336 |
\& FP_PLUS_ZERO +0.0 |
| 7337 |
\& FP_MINUS_ZERO \-0.0 |
| 7338 |
\& FP_PLUS_INF +INF |
| 7339 |
\& FP_MINUS_INF \-INF |
| 7340 |
\& FP_NANS Signaling Not a Number (NaNS) |
| 7341 |
\& FP_NANQ Quiet Not a Number (NaNQ) |
| 7342 |
.Ve |
| 7343 |
.ie n .IP """HAS_FINITE""" 4 |
| 7344 |
.el .IP \f(CWHAS_FINITE\fR 4 |
| 7345 |
.IX Xref "HAS_FINITE" |
| 7346 |
.IX Item "HAS_FINITE" |
| 7347 |
This symbol, if defined, indicates that the \f(CW\*(C`finite\*(C'\fR routine is |
| 7348 |
available to check whether a double is \f(CW\*(C`finite\*(C'\fR (non-infinity non-NaN). |
| 7349 |
.ie n .IP """HAS_FINITEL""" 4 |
| 7350 |
.el .IP \f(CWHAS_FINITEL\fR 4 |
| 7351 |
.IX Xref "HAS_FINITEL" |
| 7352 |
.IX Item "HAS_FINITEL" |
| 7353 |
This symbol, if defined, indicates that the \f(CW\*(C`finitel\*(C'\fR routine is |
| 7354 |
available to check whether a long double is finite |
| 7355 |
(non-infinity non-NaN). |
| 7356 |
.ie n .IP """HAS_FPCLASS""" 4 |
| 7357 |
.el .IP \f(CWHAS_FPCLASS\fR 4 |
| 7358 |
.IX Xref "HAS_FPCLASS" |
| 7359 |
.IX Item "HAS_FPCLASS" |
| 7360 |
This symbol, if defined, indicates that the \f(CW\*(C`fpclass\*(C'\fR routine is |
| 7361 |
available to classify doubles. Available for example in Solaris/\f(CW\*(C`SVR4\*(C'\fR. |
| 7362 |
The returned values are defined in \fIieeefp.h\fR and are: |
| 7363 |
.Sp |
| 7364 |
.Vb 10 |
| 7365 |
\& FP_SNAN signaling NaN |
| 7366 |
\& FP_QNAN quiet NaN |
| 7367 |
\& FP_NINF negative infinity |
| 7368 |
\& FP_PINF positive infinity |
| 7369 |
\& FP_NDENORM negative denormalized non\-zero |
| 7370 |
\& FP_PDENORM positive denormalized non\-zero |
| 7371 |
\& FP_NZERO negative zero |
| 7372 |
\& FP_PZERO positive zero |
| 7373 |
\& FP_NNORM negative normalized non\-zero |
| 7374 |
\& FP_PNORM positive normalized non\-zero |
| 7375 |
.Ve |
| 7376 |
.ie n .IP """HAS_FP_CLASS""" 4 |
| 7377 |
.el .IP \f(CWHAS_FP_CLASS\fR 4 |
| 7378 |
.IX Xref "HAS_FP_CLASS" |
| 7379 |
.IX Item "HAS_FP_CLASS" |
| 7380 |
This symbol, if defined, indicates that the \f(CW\*(C`fp_class\*(C'\fR routine is |
| 7381 |
available to classify doubles. Available for example in Digital \f(CW\*(C`UNIX\*(C'\fR. |
| 7382 |
The returned values are defined in \fImath.h\fR and are: |
| 7383 |
.Sp |
| 7384 |
.Vb 10 |
| 7385 |
\& FP_SNAN Signaling NaN (Not\-a\-Number) |
| 7386 |
\& FP_QNAN Quiet NaN (Not\-a\-Number) |
| 7387 |
\& FP_POS_INF +infinity |
| 7388 |
\& FP_NEG_INF \-infinity |
| 7389 |
\& FP_POS_NORM Positive normalized |
| 7390 |
\& FP_NEG_NORM Negative normalized |
| 7391 |
\& FP_POS_DENORM Positive denormalized |
| 7392 |
\& FP_NEG_DENORM Negative denormalized |
| 7393 |
\& FP_POS_ZERO +0.0 (positive zero) |
| 7394 |
\& FP_NEG_ZERO \-0.0 (negative zero) |
| 7395 |
.Ve |
| 7396 |
.ie n .IP """HAS_FPCLASSIFY""" 4 |
| 7397 |
.el .IP \f(CWHAS_FPCLASSIFY\fR 4 |
| 7398 |
.IX Xref "HAS_FPCLASSIFY" |
| 7399 |
.IX Item "HAS_FPCLASSIFY" |
| 7400 |
This symbol, if defined, indicates that the \f(CW\*(C`fpclassify\*(C'\fR routine is |
| 7401 |
available to classify doubles. Available for example in HP-UX. |
| 7402 |
The returned values are defined in \fImath.h\fR and are |
| 7403 |
.Sp |
| 7404 |
.Vb 5 |
| 7405 |
\& FP_NORMAL Normalized |
| 7406 |
\& FP_ZERO Zero |
| 7407 |
\& FP_INFINITE Infinity |
| 7408 |
\& FP_SUBNORMAL Denormalized |
| 7409 |
\& FP_NAN NaN |
| 7410 |
.Ve |
| 7411 |
.ie n .IP """HAS_FP_CLASSIFY""" 4 |
| 7412 |
.el .IP \f(CWHAS_FP_CLASSIFY\fR 4 |
| 7413 |
.IX Xref "HAS_FP_CLASSIFY" |
| 7414 |
.IX Item "HAS_FP_CLASSIFY" |
| 7415 |
This symbol, if defined, indicates that the \f(CW\*(C`fp_classify\*(C'\fR routine is |
| 7416 |
available to classify doubles. The values are defined in \fImath.h\fR |
| 7417 |
.Sp |
| 7418 |
.Vb 5 |
| 7419 |
\& FP_NORMAL Normalized |
| 7420 |
\& FP_ZERO Zero |
| 7421 |
\& FP_INFINITE Infinity |
| 7422 |
\& FP_SUBNORMAL Denormalized |
| 7423 |
\& FP_NAN NaN |
| 7424 |
.Ve |
| 7425 |
.ie n .IP """HAS_FPCLASSL""" 4 |
| 7426 |
.el .IP \f(CWHAS_FPCLASSL\fR 4 |
| 7427 |
.IX Xref "HAS_FPCLASSL" |
| 7428 |
.IX Item "HAS_FPCLASSL" |
| 7429 |
This symbol, if defined, indicates that the \f(CW\*(C`fpclassl\*(C'\fR routine is |
| 7430 |
available to classify long doubles. Available for example in \f(CW\*(C`IRIX\*(C'\fR. |
| 7431 |
The returned values are defined in \fIieeefp.h\fR and are: |
| 7432 |
.Sp |
| 7433 |
.Vb 10 |
| 7434 |
\& FP_SNAN signaling NaN |
| 7435 |
\& FP_QNAN quiet NaN |
| 7436 |
\& FP_NINF negative infinity |
| 7437 |
\& FP_PINF positive infinity |
| 7438 |
\& FP_NDENORM negative denormalized non\-zero |
| 7439 |
\& FP_PDENORM positive denormalized non\-zero |
| 7440 |
\& FP_NZERO negative zero |
| 7441 |
\& FP_PZERO positive zero |
| 7442 |
\& FP_NNORM negative normalized non\-zero |
| 7443 |
\& FP_PNORM positive normalized non\-zero |
| 7444 |
.Ve |
| 7445 |
.ie n .IP """HAS_FP_CLASSL""" 4 |
| 7446 |
.el .IP \f(CWHAS_FP_CLASSL\fR 4 |
| 7447 |
.IX Xref "HAS_FP_CLASSL" |
| 7448 |
.IX Item "HAS_FP_CLASSL" |
| 7449 |
This symbol, if defined, indicates that the \f(CW\*(C`fp_classl\*(C'\fR routine is |
| 7450 |
available to classify long doubles. Available for example in |
| 7451 |
Digital \f(CW\*(C`UNIX\*(C'\fR. See for possible values \f(CW\*(C`HAS_FP_CLASS\*(C'\fR. |
| 7452 |
.ie n .IP """HAS_FPGETROUND""" 4 |
| 7453 |
.el .IP \f(CWHAS_FPGETROUND\fR 4 |
| 7454 |
.IX Xref "HAS_FPGETROUND" |
| 7455 |
.IX Item "HAS_FPGETROUND" |
| 7456 |
This symbol, if defined, indicates that the \f(CW\*(C`fpgetround\*(C'\fR routine is |
| 7457 |
available to get the floating point rounding mode. |
| 7458 |
.ie n .IP """HAS_FREXPL""" 4 |
| 7459 |
.el .IP \f(CWHAS_FREXPL\fR 4 |
| 7460 |
.IX Xref "HAS_FREXPL" |
| 7461 |
.IX Item "HAS_FREXPL" |
| 7462 |
This symbol, if defined, indicates that the \f(CW\*(C`frexpl\*(C'\fR routine is |
| 7463 |
available to break a long double floating-point number into |
| 7464 |
a normalized fraction and an integral power of 2. |
| 7465 |
.ie n .IP """HAS_ILOGB""" 4 |
| 7466 |
.el .IP \f(CWHAS_ILOGB\fR 4 |
| 7467 |
.IX Xref "HAS_ILOGB" |
| 7468 |
.IX Item "HAS_ILOGB" |
| 7469 |
This symbol, if defined, indicates that the \f(CW\*(C`ilogb\*(C'\fR routine is |
| 7470 |
available to get integer exponent of a floating-point value. |
| 7471 |
.ie n .IP """HAS_ISFINITE""" 4 |
| 7472 |
.el .IP \f(CWHAS_ISFINITE\fR 4 |
| 7473 |
.IX Xref "HAS_ISFINITE" |
| 7474 |
.IX Item "HAS_ISFINITE" |
| 7475 |
This symbol, if defined, indicates that the \f(CW\*(C`isfinite\*(C'\fR routine is |
| 7476 |
available to check whether a double is finite (non-infinity non-NaN). |
| 7477 |
.ie n .IP """HAS_ISFINITEL""" 4 |
| 7478 |
.el .IP \f(CWHAS_ISFINITEL\fR 4 |
| 7479 |
.IX Xref "HAS_ISFINITEL" |
| 7480 |
.IX Item "HAS_ISFINITEL" |
| 7481 |
This symbol, if defined, indicates that the \f(CW\*(C`isfinitel\*(C'\fR routine is |
| 7482 |
available to check whether a long double is finite. |
| 7483 |
(non-infinity non-NaN). |
| 7484 |
.ie n .IP """HAS_ISINF""" 4 |
| 7485 |
.el .IP \f(CWHAS_ISINF\fR 4 |
| 7486 |
.IX Xref "HAS_ISINF" |
| 7487 |
.IX Item "HAS_ISINF" |
| 7488 |
This symbol, if defined, indicates that the \f(CW\*(C`isinf\*(C'\fR routine is |
| 7489 |
available to check whether a double is an infinity. |
| 7490 |
.ie n .IP """HAS_ISINFL""" 4 |
| 7491 |
.el .IP \f(CWHAS_ISINFL\fR 4 |
| 7492 |
.IX Xref "HAS_ISINFL" |
| 7493 |
.IX Item "HAS_ISINFL" |
| 7494 |
This symbol, if defined, indicates that the \f(CW\*(C`isinfl\*(C'\fR routine is |
| 7495 |
available to check whether a long double is an infinity. |
| 7496 |
.ie n .IP """HAS_ISNAN""" 4 |
| 7497 |
.el .IP \f(CWHAS_ISNAN\fR 4 |
| 7498 |
.IX Xref "HAS_ISNAN" |
| 7499 |
.IX Item "HAS_ISNAN" |
| 7500 |
This symbol, if defined, indicates that the \f(CW\*(C`isnan\*(C'\fR routine is |
| 7501 |
available to check whether a double is a NaN. |
| 7502 |
.ie n .IP """HAS_ISNANL""" 4 |
| 7503 |
.el .IP \f(CWHAS_ISNANL\fR 4 |
| 7504 |
.IX Xref "HAS_ISNANL" |
| 7505 |
.IX Item "HAS_ISNANL" |
| 7506 |
This symbol, if defined, indicates that the \f(CW\*(C`isnanl\*(C'\fR routine is |
| 7507 |
available to check whether a long double is a NaN. |
| 7508 |
.ie n .IP """HAS_ISNORMAL""" 4 |
| 7509 |
.el .IP \f(CWHAS_ISNORMAL\fR 4 |
| 7510 |
.IX Xref "HAS_ISNORMAL" |
| 7511 |
.IX Item "HAS_ISNORMAL" |
| 7512 |
This symbol, if defined, indicates that the \f(CW\*(C`isnormal\*(C'\fR routine is |
| 7513 |
available to check whether a double is normal (non-zero normalized). |
| 7514 |
.ie n .IP """HAS_J0L""" 4 |
| 7515 |
.el .IP \f(CWHAS_J0L\fR 4 |
| 7516 |
.IX Xref "HAS_J0L" |
| 7517 |
.IX Item "HAS_J0L" |
| 7518 |
This symbol, if defined, indicates to the C program that the |
| 7519 |
\&\f(CWj0l()\fR function is available for Bessel functions of the first |
| 7520 |
kind of the order zero, for long doubles. |
| 7521 |
.ie n .IP """HAS_J0""" 4 |
| 7522 |
.el .IP \f(CWHAS_J0\fR 4 |
| 7523 |
.IX Xref "HAS_J0" |
| 7524 |
.IX Item "HAS_J0" |
| 7525 |
This symbol, if defined, indicates to the C program that the |
| 7526 |
\&\f(CWj0()\fR function is available for Bessel functions of the first |
| 7527 |
kind of the order zero, for doubles. |
| 7528 |
.ie n .IP """HAS_LDBL_DIG""" 4 |
| 7529 |
.el .IP \f(CWHAS_LDBL_DIG\fR 4 |
| 7530 |
.IX Xref "HAS_LDBL_DIG" |
| 7531 |
.IX Item "HAS_LDBL_DIG" |
| 7532 |
This symbol, if defined, indicates that this system's \fIfloat.h\fR |
| 7533 |
or \fIlimits.h\fR defines the symbol \f(CW\*(C`LDBL_DIG\*(C'\fR, which is the number |
| 7534 |
of significant digits in a long double precision number. Unlike |
| 7535 |
for \f(CW\*(C`DBL_DIG\*(C'\fR, there's no good guess for \f(CW\*(C`LDBL_DIG\*(C'\fR if it is undefined. |
| 7536 |
.ie n .IP """HAS_LDEXPL""" 4 |
| 7537 |
.el .IP \f(CWHAS_LDEXPL\fR 4 |
| 7538 |
.IX Xref "HAS_LDEXPL" |
| 7539 |
.IX Item "HAS_LDEXPL" |
| 7540 |
This symbol, if defined, indicates that the \f(CW\*(C`ldexpl\*(C'\fR routine is |
| 7541 |
available to shift a long double floating-point number |
| 7542 |
by an integral power of 2. |
| 7543 |
.ie n .IP """HAS_LLRINT""" 4 |
| 7544 |
.el .IP \f(CWHAS_LLRINT\fR 4 |
| 7545 |
.IX Xref "HAS_LLRINT" |
| 7546 |
.IX Item "HAS_LLRINT" |
| 7547 |
This symbol, if defined, indicates that the \f(CW\*(C`llrint\*(C'\fR routine is |
| 7548 |
available to return the long long value closest to a double |
| 7549 |
(according to the current rounding mode). |
| 7550 |
.ie n .IP """HAS_LLRINTL""" 4 |
| 7551 |
.el .IP \f(CWHAS_LLRINTL\fR 4 |
| 7552 |
.IX Xref "HAS_LLRINTL" |
| 7553 |
.IX Item "HAS_LLRINTL" |
| 7554 |
This symbol, if defined, indicates that the \f(CW\*(C`llrintl\*(C'\fR routine is |
| 7555 |
available to return the long long value closest to a long double |
| 7556 |
(according to the current rounding mode). |
| 7557 |
.ie n .IP """HAS_LLROUNDL""" 4 |
| 7558 |
.el .IP \f(CWHAS_LLROUNDL\fR 4 |
| 7559 |
.IX Xref "HAS_LLROUNDL" |
| 7560 |
.IX Item "HAS_LLROUNDL" |
| 7561 |
This symbol, if defined, indicates that the \f(CW\*(C`llroundl\*(C'\fR routine is |
| 7562 |
available to return the nearest long long value away from zero of |
| 7563 |
the long double argument value. |
| 7564 |
.ie n .IP """HAS_LONG_DOUBLE""" 4 |
| 7565 |
.el .IP \f(CWHAS_LONG_DOUBLE\fR 4 |
| 7566 |
.IX Xref "HAS_LONG_DOUBLE" |
| 7567 |
.IX Item "HAS_LONG_DOUBLE" |
| 7568 |
This symbol will be defined if the C compiler supports long |
| 7569 |
doubles. |
| 7570 |
.ie n .IP """HAS_LRINT""" 4 |
| 7571 |
.el .IP \f(CWHAS_LRINT\fR 4 |
| 7572 |
.IX Xref "HAS_LRINT" |
| 7573 |
.IX Item "HAS_LRINT" |
| 7574 |
This symbol, if defined, indicates that the \f(CW\*(C`lrint\*(C'\fR routine is |
| 7575 |
available to return the integral value closest to a double |
| 7576 |
(according to the current rounding mode). |
| 7577 |
.ie n .IP """HAS_LRINTL""" 4 |
| 7578 |
.el .IP \f(CWHAS_LRINTL\fR 4 |
| 7579 |
.IX Xref "HAS_LRINTL" |
| 7580 |
.IX Item "HAS_LRINTL" |
| 7581 |
This symbol, if defined, indicates that the \f(CW\*(C`lrintl\*(C'\fR routine is |
| 7582 |
available to return the integral value closest to a long double |
| 7583 |
(according to the current rounding mode). |
| 7584 |
.ie n .IP """HAS_LROUNDL""" 4 |
| 7585 |
.el .IP \f(CWHAS_LROUNDL\fR 4 |
| 7586 |
.IX Xref "HAS_LROUNDL" |
| 7587 |
.IX Item "HAS_LROUNDL" |
| 7588 |
This symbol, if defined, indicates that the \f(CW\*(C`lroundl\*(C'\fR routine is |
| 7589 |
available to return the nearest integral value away from zero of |
| 7590 |
the long double argument value. |
| 7591 |
.ie n .IP """HAS_MODFL""" 4 |
| 7592 |
.el .IP \f(CWHAS_MODFL\fR 4 |
| 7593 |
.IX Xref "HAS_MODFL" |
| 7594 |
.IX Item "HAS_MODFL" |
| 7595 |
This symbol, if defined, indicates that the \f(CW\*(C`modfl\*(C'\fR routine is |
| 7596 |
available to split a long double x into a fractional part f and |
| 7597 |
an integer part i such that |f| < 1.0 and (f + i) = x. |
| 7598 |
.ie n .IP """HAS_NAN""" 4 |
| 7599 |
.el .IP \f(CWHAS_NAN\fR 4 |
| 7600 |
.IX Xref "HAS_NAN" |
| 7601 |
.IX Item "HAS_NAN" |
| 7602 |
This symbol, if defined, indicates that the \f(CW\*(C`nan\*(C'\fR routine is |
| 7603 |
available to generate NaN. |
| 7604 |
.ie n .IP """HAS_NEXTTOWARD""" 4 |
| 7605 |
.el .IP \f(CWHAS_NEXTTOWARD\fR 4 |
| 7606 |
.IX Xref "HAS_NEXTTOWARD" |
| 7607 |
.IX Item "HAS_NEXTTOWARD" |
| 7608 |
This symbol, if defined, indicates that the \f(CW\*(C`nexttoward\*(C'\fR routine is |
| 7609 |
available to return the next machine representable long double from |
| 7610 |
x in direction y. |
| 7611 |
.ie n .IP """HAS_REMAINDER""" 4 |
| 7612 |
.el .IP \f(CWHAS_REMAINDER\fR 4 |
| 7613 |
.IX Xref "HAS_REMAINDER" |
| 7614 |
.IX Item "HAS_REMAINDER" |
| 7615 |
This symbol, if defined, indicates that the \f(CW\*(C`remainder\*(C'\fR routine is |
| 7616 |
available to return the floating-point \f(CW\*(C`remainder\*(C'\fR. |
| 7617 |
.ie n .IP """HAS_SCALBN""" 4 |
| 7618 |
.el .IP \f(CWHAS_SCALBN\fR 4 |
| 7619 |
.IX Xref "HAS_SCALBN" |
| 7620 |
.IX Item "HAS_SCALBN" |
| 7621 |
This symbol, if defined, indicates that the \f(CW\*(C`scalbn\*(C'\fR routine is |
| 7622 |
available to multiply floating-point number by integral power |
| 7623 |
of radix. |
| 7624 |
.ie n .IP """HAS_SIGNBIT""" 4 |
| 7625 |
.el .IP \f(CWHAS_SIGNBIT\fR 4 |
| 7626 |
.IX Xref "HAS_SIGNBIT" |
| 7627 |
.IX Item "HAS_SIGNBIT" |
| 7628 |
This symbol, if defined, indicates that the \f(CW\*(C`signbit\*(C'\fR routine is |
| 7629 |
available to check if the given number has the sign bit set. |
| 7630 |
This should include correct testing of \-0.0. This will only be set |
| 7631 |
if the \f(CWsignbit()\fR routine is safe to use with the NV type used internally |
| 7632 |
in perl. Users should call \f(CWPerl_signbit()\fR, which will be #defined to |
| 7633 |
the system's \f(CWsignbit()\fR function or macro if this symbol is defined. |
| 7634 |
.ie n .IP """HAS_SQRTL""" 4 |
| 7635 |
.el .IP \f(CWHAS_SQRTL\fR 4 |
| 7636 |
.IX Xref "HAS_SQRTL" |
| 7637 |
.IX Item "HAS_SQRTL" |
| 7638 |
This symbol, if defined, indicates that the \f(CW\*(C`sqrtl\*(C'\fR routine is |
| 7639 |
available to do long double square roots. |
| 7640 |
.ie n .IP """HAS_STRTOD_L""" 4 |
| 7641 |
.el .IP \f(CWHAS_STRTOD_L\fR 4 |
| 7642 |
.IX Xref "HAS_STRTOD_L" |
| 7643 |
.IX Item "HAS_STRTOD_L" |
| 7644 |
This symbol, if defined, indicates that the \f(CW\*(C`strtod_l\*(C'\fR routine is |
| 7645 |
available to convert strings to long doubles. |
| 7646 |
.ie n .IP """HAS_STRTOLD""" 4 |
| 7647 |
.el .IP \f(CWHAS_STRTOLD\fR 4 |
| 7648 |
.IX Xref "HAS_STRTOLD" |
| 7649 |
.IX Item "HAS_STRTOLD" |
| 7650 |
This symbol, if defined, indicates that the \f(CW\*(C`strtold\*(C'\fR routine is |
| 7651 |
available to convert strings to long doubles. |
| 7652 |
.ie n .IP """HAS_STRTOLD_L""" 4 |
| 7653 |
.el .IP \f(CWHAS_STRTOLD_L\fR 4 |
| 7654 |
.IX Xref "HAS_STRTOLD_L" |
| 7655 |
.IX Item "HAS_STRTOLD_L" |
| 7656 |
This symbol, if defined, indicates that the \f(CW\*(C`strtold_l\*(C'\fR routine is |
| 7657 |
available to convert strings to long doubles. |
| 7658 |
.ie n .IP """HAS_TRUNC""" 4 |
| 7659 |
.el .IP \f(CWHAS_TRUNC\fR 4 |
| 7660 |
.IX Xref "HAS_TRUNC" |
| 7661 |
.IX Item "HAS_TRUNC" |
| 7662 |
This symbol, if defined, indicates that the \f(CW\*(C`trunc\*(C'\fR routine is |
| 7663 |
available to round doubles towards zero. |
| 7664 |
.ie n .IP """HAS_UNORDERED""" 4 |
| 7665 |
.el .IP \f(CWHAS_UNORDERED\fR 4 |
| 7666 |
.IX Xref "HAS_UNORDERED" |
| 7667 |
.IX Item "HAS_UNORDERED" |
| 7668 |
This symbol, if defined, indicates that the \f(CW\*(C`unordered\*(C'\fR routine is |
| 7669 |
available to check whether two doubles are \f(CW\*(C`unordered\*(C'\fR |
| 7670 |
(effectively: whether either of them is NaN) |
| 7671 |
.ie n .IP """I_FENV""" 4 |
| 7672 |
.el .IP \f(CWI_FENV\fR 4 |
| 7673 |
.IX Xref "I_FENV" |
| 7674 |
.IX Item "I_FENV" |
| 7675 |
This symbol, if defined, indicates to the C program that it should |
| 7676 |
include \fIfenv.h\fR to get the floating point environment definitions. |
| 7677 |
.RS 4 |
| 7678 |
.Sp |
| 7679 |
.Vb 3 |
| 7680 |
\& #ifdef I_FENV |
| 7681 |
\& #include <fenv.h> |
| 7682 |
\& #endif |
| 7683 |
.Ve |
| 7684 |
.RE |
| 7685 |
.RS 4 |
| 7686 |
.RE |
| 7687 |
.ie n .IP """I_QUADMATH""" 4 |
| 7688 |
.el .IP \f(CWI_QUADMATH\fR 4 |
| 7689 |
.IX Xref "I_QUADMATH" |
| 7690 |
.IX Item "I_QUADMATH" |
| 7691 |
This symbol, if defined, indicates that \fIquadmath.h\fR exists and |
| 7692 |
should be included. |
| 7693 |
.RS 4 |
| 7694 |
.Sp |
| 7695 |
.Vb 3 |
| 7696 |
\& #ifdef I_QUADMATH |
| 7697 |
\& #include <quadmath.h> |
| 7698 |
\& #endif |
| 7699 |
.Ve |
| 7700 |
.RE |
| 7701 |
.RS 4 |
| 7702 |
.RE |
| 7703 |
.ie n .IP """LONGDBLINFBYTES""" 4 |
| 7704 |
.el .IP \f(CWLONGDBLINFBYTES\fR 4 |
| 7705 |
.IX Xref "LONGDBLINFBYTES" |
| 7706 |
.IX Item "LONGDBLINFBYTES" |
| 7707 |
This symbol, if defined, is a comma-separated list of |
| 7708 |
hexadecimal bytes for the long double precision infinity. |
| 7709 |
.ie n .IP """LONGDBLMANTBITS""" 4 |
| 7710 |
.el .IP \f(CWLONGDBLMANTBITS\fR 4 |
| 7711 |
.IX Xref "LONGDBLMANTBITS" |
| 7712 |
.IX Item "LONGDBLMANTBITS" |
| 7713 |
This symbol, if defined, tells how many mantissa bits |
| 7714 |
there are in long double precision floating point format. |
| 7715 |
Note that this can be \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR minus one, |
| 7716 |
since \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR can include the \f(CW\*(C`IEEE\*(C'\fR 754 implicit bit. |
| 7717 |
The common x86\-style 80\-bit long double does not have |
| 7718 |
an implicit bit. |
| 7719 |
.ie n .IP """LONGDBLNANBYTES""" 4 |
| 7720 |
.el .IP \f(CWLONGDBLNANBYTES\fR 4 |
| 7721 |
.IX Xref "LONGDBLNANBYTES" |
| 7722 |
.IX Item "LONGDBLNANBYTES" |
| 7723 |
This symbol, if defined, is a comma-separated list of |
| 7724 |
hexadecimal bytes (0xHH) for the long double precision not-a-number. |
| 7725 |
.ie n .IP """LONG_DOUBLEKIND""" 4 |
| 7726 |
.el .IP \f(CWLONG_DOUBLEKIND\fR 4 |
| 7727 |
.IX Xref "LONG_DOUBLEKIND" |
| 7728 |
.IX Item "LONG_DOUBLEKIND" |
| 7729 |
\&\f(CW\*(C`LONG_DOUBLEKIND\*(C'\fR will be one of |
| 7730 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLE\*(C'\fR |
| 7731 |
\&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7732 |
\&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR |
| 7733 |
\&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7734 |
\&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN\*(C'\fR |
| 7735 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE\*(C'\fR |
| 7736 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE\*(C'\fR |
| 7737 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE\*(C'\fR |
| 7738 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE\*(C'\fR |
| 7739 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN\*(C'\fR |
| 7740 |
\&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN\*(C'\fR |
| 7741 |
\&\f(CW\*(C`LONG_DOUBLE_IS_VAX_H_FLOAT\*(C'\fR |
| 7742 |
\&\f(CW\*(C`LONG_DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR |
| 7743 |
It is only defined if the system supports long doubles. |
| 7744 |
.ie n .IP """LONG_DOUBLESIZE""" 4 |
| 7745 |
.el .IP \f(CWLONG_DOUBLESIZE\fR 4 |
| 7746 |
.IX Xref "LONG_DOUBLESIZE" |
| 7747 |
.IX Item "LONG_DOUBLESIZE" |
| 7748 |
This symbol contains the size of a long double, so that the |
| 7749 |
C preprocessor can make decisions based on it. It is only |
| 7750 |
defined if the system supports long doubles. Note that this |
| 7751 |
is \f(CW\*(C`sizeof(long double)\*(C'\fR, which may include unused bytes. |
| 7752 |
.ie n .IP """LONG_DOUBLE_STYLE_IEEE""" 4 |
| 7753 |
.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE\fR 4 |
| 7754 |
.IX Xref "LONG_DOUBLE_STYLE_IEEE" |
| 7755 |
.IX Item "LONG_DOUBLE_STYLE_IEEE" |
| 7756 |
This symbol, if defined, indicates that the long double |
| 7757 |
is any of the \f(CW\*(C`IEEE\*(C'\fR 754 style long doubles: |
| 7758 |
\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_STD\*(C'\fR, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_EXTENDED\*(C'\fR, |
| 7759 |
\&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\*(C'\fR. |
| 7760 |
.ie n .IP """LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE""" 4 |
| 7761 |
.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\fR 4 |
| 7762 |
.IX Xref "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE" |
| 7763 |
.IX Item "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE" |
| 7764 |
This symbol, if defined, indicates that the long double is |
| 7765 |
the 128\-bit double-double. |
| 7766 |
.ie n .IP """LONG_DOUBLE_STYLE_IEEE_EXTENDED""" 4 |
| 7767 |
.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_EXTENDED\fR 4 |
| 7768 |
.IX Xref "LONG_DOUBLE_STYLE_IEEE_EXTENDED" |
| 7769 |
.IX Item "LONG_DOUBLE_STYLE_IEEE_EXTENDED" |
| 7770 |
This symbol, if defined, indicates that the long double is |
| 7771 |
the 80\-bit \f(CW\*(C`IEEE\*(C'\fR 754. Note that despite the 'extended' this |
| 7772 |
is less than the 'std', since this is an extension of |
| 7773 |
the double precision. |
| 7774 |
.ie n .IP """LONG_DOUBLE_STYLE_IEEE_STD""" 4 |
| 7775 |
.el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_STD\fR 4 |
| 7776 |
.IX Xref "LONG_DOUBLE_STYLE_IEEE_STD" |
| 7777 |
.IX Item "LONG_DOUBLE_STYLE_IEEE_STD" |
| 7778 |
This symbol, if defined, indicates that the long double is |
| 7779 |
the 128\-bit \f(CW\*(C`IEEE\*(C'\fR 754. |
| 7780 |
.ie n .IP """LONG_DOUBLE_STYLE_VAX""" 4 |
| 7781 |
.el .IP \f(CWLONG_DOUBLE_STYLE_VAX\fR 4 |
| 7782 |
.IX Xref "LONG_DOUBLE_STYLE_VAX" |
| 7783 |
.IX Item "LONG_DOUBLE_STYLE_VAX" |
| 7784 |
This symbol, if defined, indicates that the long double is |
| 7785 |
the 128\-bit \f(CW\*(C`VAX\*(C'\fR format H. |
| 7786 |
.ie n .IP """NV""" 4 |
| 7787 |
.el .IP \f(CWNV\fR 4 |
| 7788 |
.IX Item "NV" |
| 7789 |
Described in perlguts. |
| 7790 |
.ie n .IP """NVMANTBITS""" 4 |
| 7791 |
.el .IP \f(CWNVMANTBITS\fR 4 |
| 7792 |
.IX Xref "NVMANTBITS" |
| 7793 |
.IX Item "NVMANTBITS" |
| 7794 |
This symbol, if defined, tells how many mantissa bits |
| 7795 |
(not including implicit bit) there are in a Perl NV. |
| 7796 |
This depends on which floating point type was chosen. |
| 7797 |
.ie n .IP """NV_OVERFLOWS_INTEGERS_AT""" 4 |
| 7798 |
.el .IP \f(CWNV_OVERFLOWS_INTEGERS_AT\fR 4 |
| 7799 |
.IX Xref "NV_OVERFLOWS_INTEGERS_AT" |
| 7800 |
.IX Item "NV_OVERFLOWS_INTEGERS_AT" |
| 7801 |
This symbol gives the largest integer value that NVs can hold. This |
| 7802 |
value + 1.0 cannot be stored accurately. It is expressed as constant |
| 7803 |
floating point expression to reduce the chance of decimal/binary |
| 7804 |
conversion issues. If it can not be determined, the value 0 is given. |
| 7805 |
.ie n .IP """NV_PRESERVES_UV""" 4 |
| 7806 |
.el .IP \f(CWNV_PRESERVES_UV\fR 4 |
| 7807 |
.IX Xref "NV_PRESERVES_UV" |
| 7808 |
.IX Item "NV_PRESERVES_UV" |
| 7809 |
This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR |
| 7810 |
can preserve all the bits of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR. |
| 7811 |
.ie n .IP """NV_PRESERVES_UV_BITS""" 4 |
| 7812 |
.el .IP \f(CWNV_PRESERVES_UV_BITS\fR 4 |
| 7813 |
.IX Xref "NV_PRESERVES_UV_BITS" |
| 7814 |
.IX Item "NV_PRESERVES_UV_BITS" |
| 7815 |
This symbol contains the number of bits a variable of type \f(CW\*(C`NVTYPE\*(C'\fR |
| 7816 |
can preserve of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR. |
| 7817 |
.ie n .IP """NVSIZE""" 4 |
| 7818 |
.el .IP \f(CWNVSIZE\fR 4 |
| 7819 |
.IX Xref "NVSIZE" |
| 7820 |
.IX Item "NVSIZE" |
| 7821 |
This symbol contains the \f(CWsizeof(NV)\fR. |
| 7822 |
Note that some floating point formats have unused bytes. |
| 7823 |
The most notable example is the x86* 80\-bit extended precision |
| 7824 |
which comes in byte sizes of 12 and 16 (for 32 and 64 bit |
| 7825 |
platforms, respectively), but which only uses 10 bytes. |
| 7826 |
Perl compiled with \f(CW\*(C`\-Duselongdouble\*(C'\fR on x86* is like this. |
| 7827 |
.ie n .IP """NVTYPE""" 4 |
| 7828 |
.el .IP \f(CWNVTYPE\fR 4 |
| 7829 |
.IX Xref "NVTYPE" |
| 7830 |
.IX Item "NVTYPE" |
| 7831 |
This symbol defines the C type used for Perl's NV. |
| 7832 |
.ie n .IP """NV_ZERO_IS_ALLBITS_ZERO""" 4 |
| 7833 |
.el .IP \f(CWNV_ZERO_IS_ALLBITS_ZERO\fR 4 |
| 7834 |
.IX Xref "NV_ZERO_IS_ALLBITS_ZERO" |
| 7835 |
.IX Item "NV_ZERO_IS_ALLBITS_ZERO" |
| 7836 |
This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR |
| 7837 |
stores 0.0 in memory as all bits zero. |
| 7838 |
.SH "General Configuration" |
| 7839 |
.IX Xref "PERL_GCC_BRACE_GROUPS_FORBIDDEN" |
| 7840 |
.IX Header "General Configuration" |
| 7841 |
This section contains configuration information not otherwise |
| 7842 |
found in the more specialized sections of this document. At the |
| 7843 |
end is a list of \f(CW\*(C`#defines\*(C'\fR whose name should be enough to tell |
| 7844 |
you what they do, and a list of #defines which tell you if you |
| 7845 |
need to \f(CW\*(C`#include\*(C'\fR files to get the corresponding functionality. |
| 7846 |
.ie n .IP """ASCIIish""" 4 |
| 7847 |
.el .IP \f(CWASCIIish\fR 4 |
| 7848 |
.IX Xref "ASCIIish" |
| 7849 |
.IX Item "ASCIIish" |
| 7850 |
A preprocessor symbol that is defined iff the system is an ASCII platform; this |
| 7851 |
symbol would not be defined on \f(CW"EBCDIC"\fR platforms. |
| 7852 |
.RS 4 |
| 7853 |
.Sp |
| 7854 |
.Vb 1 |
| 7855 |
\& #ifdef ASCIIish |
| 7856 |
.Ve |
| 7857 |
.RE |
| 7858 |
.RS 4 |
| 7859 |
.RE |
| 7860 |
.ie n .IP """BYTEORDER""" 4 |
| 7861 |
.el .IP \f(CWBYTEORDER\fR 4 |
| 7862 |
.IX Xref "BYTEORDER" |
| 7863 |
.IX Item "BYTEORDER" |
| 7864 |
This symbol holds the hexadecimal constant defined in byteorder, |
| 7865 |
in a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc... |
| 7866 |
If the compiler supports cross-compiling or multiple-architecture |
| 7867 |
binaries, use compiler-defined macros to |
| 7868 |
determine the byte order. |
| 7869 |
.ie n .IP """CHARBITS""" 4 |
| 7870 |
.el .IP \f(CWCHARBITS\fR 4 |
| 7871 |
.IX Xref "CHARBITS" |
| 7872 |
.IX Item "CHARBITS" |
| 7873 |
This symbol contains the size of a char, so that the C preprocessor |
| 7874 |
can make decisions based on it. |
| 7875 |
.ie n .IP """DB_VERSION_MAJOR_CFG""" 4 |
| 7876 |
.el .IP \f(CWDB_VERSION_MAJOR_CFG\fR 4 |
| 7877 |
.IX Xref "DB_VERSION_MAJOR_CFG" |
| 7878 |
.IX Item "DB_VERSION_MAJOR_CFG" |
| 7879 |
This symbol, if defined, defines the major version number of |
| 7880 |
Berkeley DB found in the \fIdb.h\fR header when Perl was configured. |
| 7881 |
.ie n .IP """DB_VERSION_MINOR_CFG""" 4 |
| 7882 |
.el .IP \f(CWDB_VERSION_MINOR_CFG\fR 4 |
| 7883 |
.IX Xref "DB_VERSION_MINOR_CFG" |
| 7884 |
.IX Item "DB_VERSION_MINOR_CFG" |
| 7885 |
This symbol, if defined, defines the minor version number of |
| 7886 |
Berkeley DB found in the \fIdb.h\fR header when Perl was configured. |
| 7887 |
For DB version 1 this is always 0. |
| 7888 |
.ie n .IP """DB_VERSION_PATCH_CFG""" 4 |
| 7889 |
.el .IP \f(CWDB_VERSION_PATCH_CFG\fR 4 |
| 7890 |
.IX Xref "DB_VERSION_PATCH_CFG" |
| 7891 |
.IX Item "DB_VERSION_PATCH_CFG" |
| 7892 |
This symbol, if defined, defines the patch version number of |
| 7893 |
Berkeley DB found in the \fIdb.h\fR header when Perl was configured. |
| 7894 |
For DB version 1 this is always 0. |
| 7895 |
.ie n .IP """DEFAULT_INC_EXCLUDES_DOT""" 4 |
| 7896 |
.el .IP \f(CWDEFAULT_INC_EXCLUDES_DOT\fR 4 |
| 7897 |
.IX Xref "DEFAULT_INC_EXCLUDES_DOT" |
| 7898 |
.IX Item "DEFAULT_INC_EXCLUDES_DOT" |
| 7899 |
This symbol, if defined, removes the legacy default behavior of |
| 7900 |
including '.' at the end of @\f(CW\*(C`INC\*(C'\fR. |
| 7901 |
.ie n .IP """DLSYM_NEEDS_UNDERSCORE""" 4 |
| 7902 |
.el .IP \f(CWDLSYM_NEEDS_UNDERSCORE\fR 4 |
| 7903 |
.IX Xref "DLSYM_NEEDS_UNDERSCORE" |
| 7904 |
.IX Item "DLSYM_NEEDS_UNDERSCORE" |
| 7905 |
This symbol, if defined, indicates that we need to prepend an |
| 7906 |
underscore to the symbol name before calling \f(CWdlsym()\fR. This only |
| 7907 |
makes sense if you *have* dlsym, which we will presume is the |
| 7908 |
case if you're using \fIdl_dlopen.xs\fR. |
| 7909 |
.ie n .IP """EBCDIC""" 4 |
| 7910 |
.el .IP \f(CWEBCDIC\fR 4 |
| 7911 |
.IX Xref "EBCDIC" |
| 7912 |
.IX Item "EBCDIC" |
| 7913 |
This symbol, if defined, indicates that this system uses |
| 7914 |
\&\f(CW\*(C`EBCDIC\*(C'\fR encoding. |
| 7915 |
.ie n .IP """HAS_CSH""" 4 |
| 7916 |
.el .IP \f(CWHAS_CSH\fR 4 |
| 7917 |
.IX Xref "HAS_CSH" |
| 7918 |
.IX Item "HAS_CSH" |
| 7919 |
This symbol, if defined, indicates that the C\-shell exists. |
| 7920 |
.ie n .IP """HAS_GETHOSTNAME""" 4 |
| 7921 |
.el .IP \f(CWHAS_GETHOSTNAME\fR 4 |
| 7922 |
.IX Xref "HAS_GETHOSTNAME" |
| 7923 |
.IX Item "HAS_GETHOSTNAME" |
| 7924 |
This symbol, if defined, indicates that the C program may use the |
| 7925 |
\&\f(CWgethostname()\fR routine to derive the host name. See also \f(CW"HAS_UNAME"\fR |
| 7926 |
and \f(CW"PHOSTNAME"\fR. |
| 7927 |
.ie n .IP """HAS_GNULIBC""" 4 |
| 7928 |
.el .IP \f(CWHAS_GNULIBC\fR 4 |
| 7929 |
.IX Xref "HAS_GNULIBC" |
| 7930 |
.IX Item "HAS_GNULIBC" |
| 7931 |
This symbol, if defined, indicates to the C program that |
| 7932 |
the \f(CW\*(C`GNU\*(C'\fR C library is being used. A better check is to use |
| 7933 |
the \f(CW\*(C`_\|_GLIBC_\|_\*(C'\fR and \f(CW\*(C`_\|_GLIBC_MINOR_\|_\*(C'\fR symbols supplied with glibc. |
| 7934 |
.ie n .IP """HAS_LGAMMA""" 4 |
| 7935 |
.el .IP \f(CWHAS_LGAMMA\fR 4 |
| 7936 |
.IX Xref "HAS_LGAMMA" |
| 7937 |
.IX Item "HAS_LGAMMA" |
| 7938 |
This symbol, if defined, indicates that the \f(CW\*(C`lgamma\*(C'\fR routine is |
| 7939 |
available to do the log gamma function. See also \f(CW"HAS_TGAMMA"\fR and |
| 7940 |
\&\f(CW"HAS_LGAMMA_R"\fR. |
| 7941 |
.ie n .IP """HAS_LGAMMA_R""" 4 |
| 7942 |
.el .IP \f(CWHAS_LGAMMA_R\fR 4 |
| 7943 |
.IX Xref "HAS_LGAMMA_R" |
| 7944 |
.IX Item "HAS_LGAMMA_R" |
| 7945 |
This symbol, if defined, indicates that the \f(CW\*(C`lgamma_r\*(C'\fR routine is |
| 7946 |
available to do the log gamma function without using the global |
| 7947 |
signgam variable. |
| 7948 |
.ie n .IP """HAS_NON_INT_BITFIELDS""" 4 |
| 7949 |
.el .IP \f(CWHAS_NON_INT_BITFIELDS\fR 4 |
| 7950 |
.IX Xref "HAS_NON_INT_BITFIELDS" |
| 7951 |
.IX Item "HAS_NON_INT_BITFIELDS" |
| 7952 |
This symbol, if defined, indicates that the C compiler accepts, without |
| 7953 |
error or warning, \f(CW\*(C`struct bitfields\*(C'\fR that are declared with sizes other |
| 7954 |
than plain 'int'; for example 'unsigned char' is accepted. |
| 7955 |
.ie n .IP """HAS_PRCTL_SET_NAME""" 4 |
| 7956 |
.el .IP \f(CWHAS_PRCTL_SET_NAME\fR 4 |
| 7957 |
.IX Xref "HAS_PRCTL_SET_NAME" |
| 7958 |
.IX Item "HAS_PRCTL_SET_NAME" |
| 7959 |
This symbol, if defined, indicates that the prctl routine is |
| 7960 |
available to set process title and supports \f(CW\*(C`PR_SET_NAME\*(C'\fR. |
| 7961 |
.ie n .IP """HAS_PROCSELFEXE""" 4 |
| 7962 |
.el .IP \f(CWHAS_PROCSELFEXE\fR 4 |
| 7963 |
.IX Xref "HAS_PROCSELFEXE" |
| 7964 |
.IX Item "HAS_PROCSELFEXE" |
| 7965 |
This symbol is defined if \f(CW\*(C`PROCSELFEXE_PATH\*(C'\fR is a symlink |
| 7966 |
to the absolute pathname of the executing program. |
| 7967 |
.ie n .IP """HAS_PSEUDOFORK""" 4 |
| 7968 |
.el .IP \f(CWHAS_PSEUDOFORK\fR 4 |
| 7969 |
.IX Xref "HAS_PSEUDOFORK" |
| 7970 |
.IX Item "HAS_PSEUDOFORK" |
| 7971 |
This symbol, if defined, indicates that an emulation of the |
| 7972 |
fork routine is available. |
| 7973 |
.ie n .IP """HAS_REGCOMP""" 4 |
| 7974 |
.el .IP \f(CWHAS_REGCOMP\fR 4 |
| 7975 |
.IX Xref "HAS_REGCOMP" |
| 7976 |
.IX Item "HAS_REGCOMP" |
| 7977 |
This symbol, if defined, indicates that the \f(CWregcomp()\fR routine is |
| 7978 |
available to do some regular pattern matching (usually on \f(CW\*(C`POSIX\*(C'\fR.2 |
| 7979 |
conforming systems). |
| 7980 |
.ie n .IP """HAS_SETPGID""" 4 |
| 7981 |
.el .IP \f(CWHAS_SETPGID\fR 4 |
| 7982 |
.IX Xref "HAS_SETPGID" |
| 7983 |
.IX Item "HAS_SETPGID" |
| 7984 |
This symbol, if defined, indicates that the \f(CW\*(C`setpgid(pid, gpid)\*(C'\fR |
| 7985 |
routine is available to set process group ID. |
| 7986 |
.ie n .IP """HAS_SIGSETJMP""" 4 |
| 7987 |
.el .IP \f(CWHAS_SIGSETJMP\fR 4 |
| 7988 |
.IX Xref "HAS_SIGSETJMP" |
| 7989 |
.IX Item "HAS_SIGSETJMP" |
| 7990 |
This variable indicates to the C program that the \f(CWsigsetjmp()\fR |
| 7991 |
routine is available to save the calling process's registers |
| 7992 |
and stack environment for later use by \f(CWsiglongjmp()\fR, and |
| 7993 |
to optionally save the process's signal mask. See |
| 7994 |
\&\f(CW"Sigjmp_buf"\fR, \f(CW"Sigsetjmp"\fR, and \f(CW"Siglongjmp"\fR. |
| 7995 |
.ie n .IP """HAS_STRUCT_CMSGHDR""" 4 |
| 7996 |
.el .IP \f(CWHAS_STRUCT_CMSGHDR\fR 4 |
| 7997 |
.IX Xref "HAS_STRUCT_CMSGHDR" |
| 7998 |
.IX Item "HAS_STRUCT_CMSGHDR" |
| 7999 |
This symbol, if defined, indicates that the \f(CW\*(C`struct cmsghdr\*(C'\fR |
| 8000 |
is supported. |
| 8001 |
.ie n .IP """HAS_STRUCT_MSGHDR""" 4 |
| 8002 |
.el .IP \f(CWHAS_STRUCT_MSGHDR\fR 4 |
| 8003 |
.IX Xref "HAS_STRUCT_MSGHDR" |
| 8004 |
.IX Item "HAS_STRUCT_MSGHDR" |
| 8005 |
This symbol, if defined, indicates that the \f(CW\*(C`struct msghdr\*(C'\fR |
| 8006 |
is supported. |
| 8007 |
.ie n .IP """HAS_TGAMMA""" 4 |
| 8008 |
.el .IP \f(CWHAS_TGAMMA\fR 4 |
| 8009 |
.IX Xref "HAS_TGAMMA" |
| 8010 |
.IX Item "HAS_TGAMMA" |
| 8011 |
This symbol, if defined, indicates that the \f(CW\*(C`tgamma\*(C'\fR routine is |
| 8012 |
available to do the gamma function. See also \f(CW"HAS_LGAMMA"\fR. |
| 8013 |
.ie n .IP """HAS_UNAME""" 4 |
| 8014 |
.el .IP \f(CWHAS_UNAME\fR 4 |
| 8015 |
.IX Xref "HAS_UNAME" |
| 8016 |
.IX Item "HAS_UNAME" |
| 8017 |
This symbol, if defined, indicates that the C program may use the |
| 8018 |
\&\f(CWuname()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR |
| 8019 |
and \f(CW"PHOSTNAME"\fR. |
| 8020 |
.ie n .IP """HAS_UNION_SEMUN""" 4 |
| 8021 |
.el .IP \f(CWHAS_UNION_SEMUN\fR 4 |
| 8022 |
.IX Xref "HAS_UNION_SEMUN" |
| 8023 |
.IX Item "HAS_UNION_SEMUN" |
| 8024 |
This symbol, if defined, indicates that the \f(CW\*(C`union semun\*(C'\fR is |
| 8025 |
defined by including \fIsys/sem.h\fR. If not, the user code |
| 8026 |
probably needs to define it as: |
| 8027 |
.Sp |
| 8028 |
.Vb 5 |
| 8029 |
\& union semun { |
| 8030 |
\& int val; |
| 8031 |
\& struct semid_ds *buf; |
| 8032 |
\& unsigned short *array; |
| 8033 |
\& } |
| 8034 |
.Ve |
| 8035 |
.ie n .IP """I_DIRENT""" 4 |
| 8036 |
.el .IP \f(CWI_DIRENT\fR 4 |
| 8037 |
.IX Xref "I_DIRENT" |
| 8038 |
.IX Item "I_DIRENT" |
| 8039 |
This symbol, if defined, indicates to the C program that it should |
| 8040 |
include \fIdirent.h\fR. Using this symbol also triggers the definition |
| 8041 |
of the \f(CW\*(C`Direntry_t\*(C'\fR define which ends up being '\f(CW\*(C`struct dirent\*(C'\fR' or |
| 8042 |
\&'\f(CW\*(C`struct direct\*(C'\fR' depending on the availability of \fIdirent.h\fR. |
| 8043 |
.RS 4 |
| 8044 |
.Sp |
| 8045 |
.Vb 3 |
| 8046 |
\& #ifdef I_DIRENT |
| 8047 |
\& #include <dirent.h> |
| 8048 |
\& #endif |
| 8049 |
.Ve |
| 8050 |
.RE |
| 8051 |
.RS 4 |
| 8052 |
.RE |
| 8053 |
.ie n .IP """I_POLL""" 4 |
| 8054 |
.el .IP \f(CWI_POLL\fR 4 |
| 8055 |
.IX Xref "I_POLL" |
| 8056 |
.IX Item "I_POLL" |
| 8057 |
This symbol, if defined, indicates that \fIpoll.h\fR exists and |
| 8058 |
should be included. (see also \f(CW"HAS_POLL"\fR) |
| 8059 |
.RS 4 |
| 8060 |
.Sp |
| 8061 |
.Vb 3 |
| 8062 |
\& #ifdef I_POLL |
| 8063 |
\& #include <poll.h> |
| 8064 |
\& #endif |
| 8065 |
.Ve |
| 8066 |
.RE |
| 8067 |
.RS 4 |
| 8068 |
.RE |
| 8069 |
.ie n .IP """I_SYS_RESOURCE""" 4 |
| 8070 |
.el .IP \f(CWI_SYS_RESOURCE\fR 4 |
| 8071 |
.IX Xref "I_SYS_RESOURCE" |
| 8072 |
.IX Item "I_SYS_RESOURCE" |
| 8073 |
This symbol, if defined, indicates to the C program that it should |
| 8074 |
include \fIsys/resource.h\fR. |
| 8075 |
.RS 4 |
| 8076 |
.Sp |
| 8077 |
.Vb 3 |
| 8078 |
\& #ifdef I_SYS_RESOURCE |
| 8079 |
\& #include <sys_resource.h> |
| 8080 |
\& #endif |
| 8081 |
.Ve |
| 8082 |
.RE |
| 8083 |
.RS 4 |
| 8084 |
.RE |
| 8085 |
.ie n .IP """LIBM_LIB_VERSION""" 4 |
| 8086 |
.el .IP \f(CWLIBM_LIB_VERSION\fR 4 |
| 8087 |
.IX Xref "LIBM_LIB_VERSION" |
| 8088 |
.IX Item "LIBM_LIB_VERSION" |
| 8089 |
This symbol, if defined, indicates that libm exports \f(CW\*(C`_LIB_VERSION\*(C'\fR |
| 8090 |
and that \fImath.h\fR defines the enum to manipulate it. |
| 8091 |
.ie n .IP """NEED_VA_COPY""" 4 |
| 8092 |
.el .IP \f(CWNEED_VA_COPY\fR 4 |
| 8093 |
.IX Item "NEED_VA_COPY" |
| 8094 |
This symbol, if defined, indicates that the system stores |
| 8095 |
the variable argument list datatype, \f(CW\*(C`va_list\*(C'\fR, in a format |
| 8096 |
that cannot be copied by simple assignment, so that some |
| 8097 |
other means must be used when copying is required. |
| 8098 |
As such systems vary in their provision (or non-provision) |
| 8099 |
of copying mechanisms, \fIhandy.h\fR defines a platform\- |
| 8100 |
independent macro, \f(CW\*(C`Perl_va_copy(src, dst)\*(C'\fR, to do the job. |
| 8101 |
.ie n .IP """OSNAME""" 4 |
| 8102 |
.el .IP \f(CWOSNAME\fR 4 |
| 8103 |
.IX Xref "OSNAME" |
| 8104 |
.IX Item "OSNAME" |
| 8105 |
This symbol contains the name of the operating system, as determined |
| 8106 |
by Configure. You shouldn't rely on it too much; the specific |
| 8107 |
feature tests from Configure are generally more reliable. |
| 8108 |
.ie n .IP """OSVERS""" 4 |
| 8109 |
.el .IP \f(CWOSVERS\fR 4 |
| 8110 |
.IX Xref "OSVERS" |
| 8111 |
.IX Item "OSVERS" |
| 8112 |
This symbol contains the version of the operating system, as determined |
| 8113 |
by Configure. You shouldn't rely on it too much; the specific |
| 8114 |
feature tests from Configure are generally more reliable. |
| 8115 |
.ie n .IP """PERL_USE_GCC_BRACE_GROUPS""" 4 |
| 8116 |
.el .IP \f(CWPERL_USE_GCC_BRACE_GROUPS\fR 4 |
| 8117 |
.IX Xref "PERL_USE_GCC_BRACE_GROUPS" |
| 8118 |
.IX Item "PERL_USE_GCC_BRACE_GROUPS" |
| 8119 |
This C pre-processor value, if defined, indicates that it is permissible to use |
| 8120 |
the GCC brace groups extension. However, use of this extension is DISCOURAGED. |
| 8121 |
Use a \f(CW\*(C`static inline\*(C'\fR function instead. |
| 8122 |
.Sp |
| 8123 |
The extension, of the form |
| 8124 |
.Sp |
| 8125 |
.Vb 1 |
| 8126 |
\& ({ statement ... }) |
| 8127 |
.Ve |
| 8128 |
.Sp |
| 8129 |
turns the block consisting of \fIstatement ...\fR into an expression with a |
| 8130 |
value, unlike plain C language blocks. This can present optimization |
| 8131 |
possibilities, \fBBUT\fR, unless you know for sure that this will never be |
| 8132 |
compiled without this extension being available and not forbidden, you need to |
| 8133 |
specify an alternative. Thus two code paths have to be maintained, which can |
| 8134 |
get out-of-sync. All these issues are solved by using a \f(CW\*(C`static inline\*(C'\fR |
| 8135 |
function instead. |
| 8136 |
.Sp |
| 8137 |
Perl can be configured to not use this feature by passing the parameter |
| 8138 |
\&\f(CW\*(C`\-Accflags=\-DPERL_GCC_BRACE_GROUPS_FORBIDDEN\*(C'\fR to \fIConfigure\fR. |
| 8139 |
.RS 4 |
| 8140 |
.Sp |
| 8141 |
.Vb 1 |
| 8142 |
\& #ifdef PERL_USE_GCC_BRACE_GROUPS |
| 8143 |
.Ve |
| 8144 |
.RE |
| 8145 |
.RS 4 |
| 8146 |
.RE |
| 8147 |
.ie n .IP """PHOSTNAME""" 4 |
| 8148 |
.el .IP \f(CWPHOSTNAME\fR 4 |
| 8149 |
.IX Xref "PHOSTNAME" |
| 8150 |
.IX Item "PHOSTNAME" |
| 8151 |
This symbol, if defined, indicates the command to feed to the |
| 8152 |
\&\f(CWpopen()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR |
| 8153 |
and \f(CW"HAS_UNAME"\fR. Note that the command uses a fully qualified path, |
| 8154 |
so that it is safe even if used by a process with super-user |
| 8155 |
privileges. |
| 8156 |
.ie n .IP """PROCSELFEXE_PATH""" 4 |
| 8157 |
.el .IP \f(CWPROCSELFEXE_PATH\fR 4 |
| 8158 |
.IX Xref "PROCSELFEXE_PATH" |
| 8159 |
.IX Item "PROCSELFEXE_PATH" |
| 8160 |
If \f(CW\*(C`HAS_PROCSELFEXE\*(C'\fR is defined this symbol is the filename |
| 8161 |
of the symbolic link pointing to the absolute pathname of |
| 8162 |
the executing program. |
| 8163 |
.ie n .IP """PTRSIZE""" 4 |
| 8164 |
.el .IP \f(CWPTRSIZE\fR 4 |
| 8165 |
.IX Xref "PTRSIZE" |
| 8166 |
.IX Item "PTRSIZE" |
| 8167 |
This symbol contains the size of a pointer, so that the C preprocessor |
| 8168 |
can make decisions based on it. It will be \f(CW\*(C`sizeof(void *)\*(C'\fR if |
| 8169 |
the compiler supports (void *); otherwise it will be |
| 8170 |
\&\f(CW\*(C`sizeof(char *)\*(C'\fR. |
| 8171 |
.ie n .IP """RANDBITS""" 4 |
| 8172 |
.el .IP \f(CWRANDBITS\fR 4 |
| 8173 |
.IX Xref "RANDBITS" |
| 8174 |
.IX Item "RANDBITS" |
| 8175 |
This symbol indicates how many bits are produced by the |
| 8176 |
function used to generate normalized random numbers. |
| 8177 |
Values include 15, 16, 31, and 48. |
| 8178 |
.ie n .IP """SELECT_MIN_BITS""" 4 |
| 8179 |
.el .IP \f(CWSELECT_MIN_BITS\fR 4 |
| 8180 |
.IX Xref "SELECT_MIN_BITS" |
| 8181 |
.IX Item "SELECT_MIN_BITS" |
| 8182 |
This symbol holds the minimum number of bits operated by select. |
| 8183 |
That is, if you do \f(CW\*(C`select(n, ...)\*(C'\fR, how many bits at least will be |
| 8184 |
cleared in the masks if some activity is detected. Usually this |
| 8185 |
is either n or 32*\f(CWceil(n/32)\fR, especially many little-endians do |
| 8186 |
the latter. This is only useful if you have \f(CWselect()\fR, naturally. |
| 8187 |
.ie n .IP """SETUID_SCRIPTS_ARE_SECURE_NOW""" 4 |
| 8188 |
.el .IP \f(CWSETUID_SCRIPTS_ARE_SECURE_NOW\fR 4 |
| 8189 |
.IX Xref "SETUID_SCRIPTS_ARE_SECURE_NOW" |
| 8190 |
.IX Item "SETUID_SCRIPTS_ARE_SECURE_NOW" |
| 8191 |
This symbol, if defined, indicates that the bug that prevents |
| 8192 |
setuid scripts from being secure is not present in this kernel. |
| 8193 |
.ie n .IP """ST_DEV_SIGN""" 4 |
| 8194 |
.el .IP \f(CWST_DEV_SIGN\fR 4 |
| 8195 |
.IX Xref "ST_DEV_SIGN" |
| 8196 |
.IX Item "ST_DEV_SIGN" |
| 8197 |
This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR. |
| 8198 |
1 for unsigned, \-1 for signed. |
| 8199 |
.ie n .IP """ST_DEV_SIZE""" 4 |
| 8200 |
.el .IP \f(CWST_DEV_SIZE\fR 4 |
| 8201 |
.IX Xref "ST_DEV_SIZE" |
| 8202 |
.IX Item "ST_DEV_SIZE" |
| 8203 |
This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR in bytes. |
| 8204 |
.ie n .SS "List of capability ""HAS_\fIfoo\fP"" symbols" |
| 8205 |
.el .SS "List of capability \f(CWHAS_\fP\f(CIfoo\fP\f(CW\fP symbols" |
| 8206 |
.IX Subsection "List of capability HAS_foo symbols" |
| 8207 |
This is a list of those symbols that dont appear elsewhere in ths |
| 8208 |
document that indicate if the current platform has a certain |
| 8209 |
capability. Their names all begin with \f(CW\*(C`HAS_\*(C'\fR. Only those |
| 8210 |
symbols whose capability is directly derived from the name are |
| 8211 |
listed here. All others have their meaning expanded out elsewhere |
| 8212 |
in this document. This (relatively) compact list is because we |
| 8213 |
think that the expansion would add little or no value and take up |
| 8214 |
a lot of space (because there are so many). If you think certain |
| 8215 |
ones should be expanded, send email to |
| 8216 |
perl5\[email protected] <mailto:[email protected]>. |
| 8217 |
.PP |
| 8218 |
Each symbol here will be \f(CW\*(C`#define\*(C'\fRd if and only if the platform |
| 8219 |
has the capability. If you need more detail, see the |
| 8220 |
corresponding entry in \fIconfig.h\fR. For convenience, the list is |
| 8221 |
split so that the ones that indicate there is a reentrant version |
| 8222 |
of a capability are listed separately |
| 8223 |
.PP |
| 8224 |
\&\f(CW\*(C`HAS_ACCEPT4\*(C'\fR,\ \f(CW\*(C`HAS_ACCESS\*(C'\fR,\ \f(CW\*(C`HAS_ACCESSX\*(C'\fR,\ \f(CW\*(C`HAS_ACOSH\*(C'\fR,\ \f(CW\*(C`HAS_AINTL\*(C'\fR,\ \f(CW\*(C`HAS_ALARM\*(C'\fR,\ \f(CW\*(C`HAS_ASINH\*(C'\fR,\ \f(CW\*(C`HAS_ATANH\*(C'\fR,\ \f(CW\*(C`HAS_ATOLL\*(C'\fR,\ \f(CW\*(C`HAS_CBRT\*(C'\fR,\ \f(CW\*(C`HAS_CHOWN\*(C'\fR,\ \f(CW\*(C`HAS_CHROOT\*(C'\fR,\ \f(CW\*(C`HAS_CHSIZE\*(C'\fR,\ \f(CW\*(C`HAS_CLEARENV\*(C'\fR,\ \f(CW\*(C`HAS_COPYSIGN\*(C'\fR,\ \f(CW\*(C`HAS_COPYSIGNL\*(C'\fR,\ \f(CW\*(C`HAS_CRYPT\*(C'\fR,\ \f(CW\*(C`HAS_CTERMID\*(C'\fR,\ \f(CW\*(C`HAS_CUSERID\*(C'\fR,\ \f(CW\*(C`HAS_DIRFD\*(C'\fR,\ \f(CW\*(C`HAS_DLADDR\*(C'\fR,\ \f(CW\*(C`HAS_DLERROR\*(C'\fR,\ \f(CW\*(C`HAS_EACCESS\*(C'\fR,\ \f(CW\*(C`HAS_ENDHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDNETENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_ERF\*(C'\fR,\ \f(CW\*(C`HAS_ERFC\*(C'\fR,\ \f(CW\*(C`HAS_EXPM1\*(C'\fR,\ \f(CW\*(C`HAS_EXP2\*(C'\fR,\ \f(CW\*(C`HAS_FCHMOD\*(C'\fR,\ \f(CW\*(C`HAS_FCHMODAT\*(C'\fR,\ \f(CW\*(C`HAS_FCHOWN\*(C'\fR,\ \f(CW\*(C`HAS_FDIM\*(C'\fR,\ \f(CW\*(C`HAS_FD_SET\*(C'\fR,\ \f(CW\*(C`HAS_FEGETROUND\*(C'\fR,\ \f(CW\*(C`HAS_FFS\*(C'\fR,\ \f(CW\*(C`HAS_FFSL\*(C'\fR,\ \f(CW\*(C`HAS_FGETPOS\*(C'\fR,\ \f(CW\*(C`HAS_FLOCK\*(C'\fR,\ \f(CW\*(C`HAS_FMA\*(C'\fR,\ \f(CW\*(C`HAS_FMAX\*(C'\fR,\ \f(CW\*(C`HAS_FMIN\*(C'\fR,\ \f(CW\*(C`HAS_FORK\*(C'\fR,\ \f(CW\*(C`HAS_FSEEKO\*(C'\fR,\ \f(CW\*(C`HAS_FSETPOS\*(C'\fR,\ \f(CW\*(C`HAS_FSYNC\*(C'\fR,\ \f(CW\*(C`HAS_FTELLO\*(C'\fR,\ \f(CW\*(C`HAS_\|_FWALK\*(C'\fR,\ \f(CW\*(C`HAS_GAI_STRERROR\*(C'\fR,\ \f(CW\*(C`HAS_GETADDRINFO\*(C'\fR,\ \f(CW\*(C`HAS_GETCWD\*(C'\fR,\ \f(CW\*(C`HAS_GETESPWNAM\*(C'\fR,\ \f(CW\*(C`HAS_GETGROUPS\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYADDR\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_GETLOGIN\*(C'\fR,\ \f(CW\*(C`HAS_GETNAMEINFO\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYADDR\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETNETENT\*(C'\fR,\ \f(CW\*(C`HAS_GETPAGESIZE\*(C'\fR,\ \f(CW\*(C`HAS_GETPGID\*(C'\fR,\ \f(CW\*(C`HAS_GETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_GETPGRP2\*(C'\fR,\ \f(CW\*(C`HAS_GETPPID\*(C'\fR,\ \f(CW\*(C`HAS_GETPRIORITY\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNUMBER\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_GETPRPWNAM\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYPORT\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_GETSPNAM\*(C'\fR,\ \f(CW\*(C`HAS_HTONL\*(C'\fR,\ \f(CW\*(C`HAS_HTONS\*(C'\fR,\ \f(CW\*(C`HAS_HYPOT\*(C'\fR,\ \f(CW\*(C`HAS_ILOGBL\*(C'\fR,\ \f(CW\*(C`HAS_INET_ATON\*(C'\fR,\ \f(CW\*(C`HAS_INETNTOP\*(C'\fR,\ \f(CW\*(C`HAS_INETPTON\*(C'\fR,\ \f(CW\*(C`HAS_IP_MREQ\*(C'\fR,\ \f(CW\*(C`HAS_IP_MREQ_SOURCE\*(C'\fR,\ \f(CW\*(C`HAS_IPV6_MREQ\*(C'\fR,\ \f(CW\*(C`HAS_IPV6_MREQ_SOURCE\*(C'\fR,\ \f(CW\*(C`HAS_ISASCII\*(C'\fR,\ \f(CW\*(C`HAS_ISBLANK\*(C'\fR,\ \f(CW\*(C`HAS_ISLESS\*(C'\fR,\ \f(CW\*(C`HAS_KILLPG\*(C'\fR,\ \f(CW\*(C`HAS_LCHOWN\*(C'\fR,\ \f(CW\*(C`HAS_LINK\*(C'\fR,\ \f(CW\*(C`HAS_LINKAT\*(C'\fR,\ \f(CW\*(C`HAS_LLROUND\*(C'\fR,\ \f(CW\*(C`HAS_LOCKF\*(C'\fR,\ \f(CW\*(C`HAS_LOGB\*(C'\fR,\ \f(CW\*(C`HAS_LOG1P\*(C'\fR,\ \f(CW\*(C`HAS_LOG2\*(C'\fR,\ \f(CW\*(C`HAS_LROUND\*(C'\fR,\ \f(CW\*(C`HAS_LSTAT\*(C'\fR,\ \f(CW\*(C`HAS_MADVISE\*(C'\fR,\ \f(CW\*(C`HAS_MBLEN\*(C'\fR,\ \f(CW\*(C`HAS_MBRLEN\*(C'\fR,\ \f(CW\*(C`HAS_MBRTOWC\*(C'\fR,\ \f(CW\*(C`HAS_MBSTOWCS\*(C'\fR,\ \f(CW\*(C`HAS_MBTOWC\*(C'\fR,\ \f(CW\*(C`HAS_MEMMEM\*(C'\fR,\ \f(CW\*(C`HAS_MEMRCHR\*(C'\fR,\ \f(CW\*(C`HAS_MKDTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKFIFO\*(C'\fR,\ \f(CW\*(C`HAS_MKOSTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKSTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKSTEMPS\*(C'\fR,\ \f(CW\*(C`HAS_MMAP\*(C'\fR,\ \f(CW\*(C`HAS_MPROTECT\*(C'\fR,\ \f(CW\*(C`HAS_MSG\*(C'\fR,\ \f(CW\*(C`HAS_MSYNC\*(C'\fR,\ \f(CW\*(C`HAS_MUNMAP\*(C'\fR,\ \f(CW\*(C`HAS_NEARBYINT\*(C'\fR,\ \f(CW\*(C`HAS_NEXTAFTER\*(C'\fR,\ \f(CW\*(C`HAS_NICE\*(C'\fR,\ \f(CW\*(C`HAS_NTOHL\*(C'\fR,\ \f(CW\*(C`HAS_NTOHS\*(C'\fR,\ \f(CW\*(C`HAS_PATHCONF\*(C'\fR,\ \f(CW\*(C`HAS_PAUSE\*(C'\fR,\ \f(CW\*(C`HAS_PHOSTNAME\*(C'\fR,\ \f(CW\*(C`HAS_PIPE\*(C'\fR,\ \f(CW\*(C`HAS_PIPE2\*(C'\fR,\ \f(CW\*(C`HAS_PRCTL\*(C'\fR,\ \f(CW\*(C`HAS_PTRDIFF_T\*(C'\fR,\ \f(CW\*(C`HAS_READLINK\*(C'\fR,\ \f(CW\*(C`HAS_READV\*(C'\fR,\ \f(CW\*(C`HAS_RECVMSG\*(C'\fR,\ \f(CW\*(C`HAS_REMQUO\*(C'\fR,\ \f(CW\*(C`HAS_RENAME\*(C'\fR,\ \f(CW\*(C`HAS_RENAMEAT\*(C'\fR,\ \f(CW\*(C`HAS_RINT\*(C'\fR,\ \f(CW\*(C`HAS_ROUND\*(C'\fR,\ \f(CW\*(C`HAS_SCALBNL\*(C'\fR,\ \f(CW\*(C`HAS_SEM\*(C'\fR,\ \f(CW\*(C`HAS_SENDMSG\*(C'\fR,\ \f(CW\*(C`HAS_SETEGID\*(C'\fR,\ \f(CW\*(C`HAS_SETENV\*(C'\fR,\ \f(CW\*(C`HAS_SETEUID\*(C'\fR,\ \f(CW\*(C`HAS_SETGROUPS\*(C'\fR,\ \f(CW\*(C`HAS_SETHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_SETLINEBUF\*(C'\fR,\ \f(CW\*(C`HAS_SETNETENT\*(C'\fR,\ \f(CW\*(C`HAS_SETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_SETPGRP2\*(C'\fR,\ \f(CW\*(C`HAS_SETPRIORITY\*(C'\fR,\ \f(CW\*(C`HAS_SETPROCTITLE\*(C'\fR,\ \f(CW\*(C`HAS_SETPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_SETREGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRESGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRESUID\*(C'\fR,\ \f(CW\*(C`HAS_SETREUID\*(C'\fR,\ \f(CW\*(C`HAS_SETRGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRUID\*(C'\fR,\ \f(CW\*(C`HAS_SETSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_SETSID\*(C'\fR,\ \f(CW\*(C`HAS_SHM\*(C'\fR,\ \f(CW\*(C`HAS_SIGACTION\*(C'\fR,\ \f(CW\*(C`HAS_SIGPROCMASK\*(C'\fR,\ \f(CW\*(C`HAS_SIN6_SCOPE_ID\*(C'\fR,\ \f(CW\*(C`HAS_SNPRINTF\*(C'\fR,\ \f(CW\*(C`HAS_STAT\*(C'\fR,\ \f(CW\*(C`HAS_STRCOLL\*(C'\fR,\ \f(CW\*(C`HAS_STRERROR_L\*(C'\fR,\ \f(CW\*(C`HAS_STRLCAT\*(C'\fR,\ \f(CW\*(C`HAS_STRLCPY\*(C'\fR,\ \f(CW\*(C`HAS_STRNLEN\*(C'\fR,\ \f(CW\*(C`HAS_STRTOD\*(C'\fR,\ \f(CW\*(C`HAS_STRTOL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOLL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOQ\*(C'\fR,\ \f(CW\*(C`HAS_STRTOUL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOULL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOUQ\*(C'\fR,\ \f(CW\*(C`HAS_STRXFRM\*(C'\fR,\ \f(CW\*(C`HAS_STRXFRM_L\*(C'\fR,\ \f(CW\*(C`HAS_SYMLINK\*(C'\fR,\ \f(CW\*(C`HAS_SYSCALL\*(C'\fR,\ \f(CW\*(C`HAS_SYSCONF\*(C'\fR,\ \f(CW\*(C`HAS_SYS_ERRLIST\*(C'\fR,\ \f(CW\*(C`HAS_SYSTEM\*(C'\fR,\ \f(CW\*(C`HAS_TCGETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_TCSETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_TOWLOWER\*(C'\fR,\ \f(CW\*(C`HAS_TOWUPPER\*(C'\fR,\ \f(CW\*(C`HAS_TRUNCATE\*(C'\fR,\ \f(CW\*(C`HAS_TRUNCL\*(C'\fR,\ \f(CW\*(C`HAS_UALARM\*(C'\fR,\ \f(CW\*(C`HAS_UMASK\*(C'\fR,\ \f(CW\*(C`HAS_UNLINKAT\*(C'\fR,\ \f(CW\*(C`HAS_UNSETENV\*(C'\fR,\ \f(CW\*(C`HAS_VFORK\*(C'\fR,\ \f(CW\*(C`HAS_VSNPRINTF\*(C'\fR,\ \f(CW\*(C`HAS_WAITPID\*(C'\fR,\ \f(CW\*(C`HAS_WAIT4\*(C'\fR,\ \f(CW\*(C`HAS_WCRTOMB\*(C'\fR,\ \f(CW\*(C`HAS_WCSCMP\*(C'\fR,\ \f(CW\*(C`HAS_WCSTOMBS\*(C'\fR,\ \f(CW\*(C`HAS_WCSXFRM\*(C'\fR,\ \f(CW\*(C`HAS_WCTOMB\*(C'\fR,\ \f(CW\*(C`HAS_WRITEV\*(C'\fR |
| 8225 |
.PP |
| 8226 |
And, the reentrant capabilities: |
| 8227 |
.PP |
| 8228 |
\&\f(CW\*(C`HAS_CRYPT_R\*(C'\fR,\ \f(CW\*(C`HAS_CTERMID_R\*(C'\fR,\ \f(CW\*(C`HAS_DRAND48_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETGRGID_R\*(C'\fR,\ \f(CW\*(C`HAS_GETGRNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYADDR_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETLOGIN_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYADDR_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNUMBER_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPWNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPWUID_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYPORT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSPNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_RANDOM_R\*(C'\fR,\ \f(CW\*(C`HAS_READDIR_R\*(C'\fR,\ \f(CW\*(C`HAS_SETHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SRANDOM_R\*(C'\fR,\ \f(CW\*(C`HAS_SRAND48_R\*(C'\fR,\ \f(CW\*(C`HAS_STRERROR_R\*(C'\fR,\ \f(CW\*(C`HAS_TMPNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_TTYNAME_R\*(C'\fR |
| 8229 |
.PP |
| 8230 |
Example usage: |
| 8231 |
.Sp |
| 8232 |
.Vb 5 |
| 8233 |
\& #ifdef HAS_STRNLEN |
| 8234 |
\& use strnlen() |
| 8235 |
\& #else |
| 8236 |
\& use an alternative implementation |
| 8237 |
\& #endif |
| 8238 |
.Ve |
| 8239 |
.ie n .SS "List of ""#include"" needed symbols" |
| 8240 |
.el .SS "List of \f(CW#include\fP needed symbols" |
| 8241 |
.IX Subsection "List of #include needed symbols" |
| 8242 |
This list contains symbols that indicate if certain \f(CW\*(C`#include\*(C'\fR |
| 8243 |
files are present on the platform. If your code accesses the |
| 8244 |
functionality that one of these is for, you will need to |
| 8245 |
\&\f(CW\*(C`#include\*(C'\fR it if the symbol on this list is \f(CW\*(C`#define\*(C'\fRd. For |
| 8246 |
more detail, see the corresponding entry in \fIconfig.h\fR. |
| 8247 |
.PP |
| 8248 |
\&\f(CW\*(C`I_ARPA_INET\*(C'\fR,\ \f(CW\*(C`I_BFD\*(C'\fR,\ \f(CW\*(C`I_CRYPT\*(C'\fR,\ \f(CW\*(C`I_DBM\*(C'\fR,\ \f(CW\*(C`I_DLFCN\*(C'\fR,\ \f(CW\*(C`I_EXECINFO\*(C'\fR,\ \f(CW\*(C`I_FP\*(C'\fR,\ \f(CW\*(C`I_FP_CLASS\*(C'\fR,\ \f(CW\*(C`I_GDBM\*(C'\fR,\ \f(CW\*(C`I_GDBMNDBM\*(C'\fR,\ \f(CW\*(C`I_GDBM_NDBM\*(C'\fR,\ \f(CW\*(C`I_GRP\*(C'\fR,\ \f(CW\*(C`I_IEEEFP\*(C'\fR,\ \f(CW\*(C`I_INTTYPES\*(C'\fR,\ \f(CW\*(C`I_LIBUTIL\*(C'\fR,\ \f(CW\*(C`I_MNTENT\*(C'\fR,\ \f(CW\*(C`I_NDBM\*(C'\fR,\ \f(CW\*(C`I_NETDB\*(C'\fR,\ \f(CW\*(C`I_NET_ERRNO\*(C'\fR,\ \f(CW\*(C`I_NETINET_IN\*(C'\fR,\ \f(CW\*(C`I_NETINET_TCP\*(C'\fR,\ \f(CW\*(C`I_PROT\*(C'\fR,\ \f(CW\*(C`I_PWD\*(C'\fR,\ \f(CW\*(C`I_RPCSVC_DBM\*(C'\fR,\ \f(CW\*(C`I_SGTTY\*(C'\fR,\ \f(CW\*(C`I_SHADOW\*(C'\fR,\ \f(CW\*(C`I_STDBOOL\*(C'\fR,\ \f(CW\*(C`I_STDINT\*(C'\fR,\ \f(CW\*(C`I_SUNMATH\*(C'\fR,\ \f(CW\*(C`I_SYS_ACCESS\*(C'\fR,\ \f(CW\*(C`I_SYS_IOCTL\*(C'\fR,\ \f(CW\*(C`I_SYSLOG\*(C'\fR,\ \f(CW\*(C`I_SYSMODE\*(C'\fR,\ \f(CW\*(C`I_SYS_MOUNT\*(C'\fR,\ \f(CW\*(C`I_SYS_PARAM\*(C'\fR,\ \f(CW\*(C`I_SYS_POLL\*(C'\fR,\ \f(CW\*(C`I_SYS_SECURITY\*(C'\fR,\ \f(CW\*(C`I_SYS_SELECT\*(C'\fR,\ \f(CW\*(C`I_SYS_STAT\*(C'\fR,\ \f(CW\*(C`I_SYS_STATVFS\*(C'\fR,\ \f(CW\*(C`I_SYS_SYSCALL\*(C'\fR,\ \f(CW\*(C`I_SYS_TIME\*(C'\fR,\ \f(CW\*(C`I_SYS_TIME_KERNEL\*(C'\fR,\ \f(CW\*(C`I_SYS_TIMES\*(C'\fR,\ \f(CW\*(C`I_SYS_TYPES\*(C'\fR,\ \f(CW\*(C`I_SYSUIO\*(C'\fR,\ \f(CW\*(C`I_SYS_UN\*(C'\fR,\ \f(CW\*(C`I_SYSUTSNAME\*(C'\fR,\ \f(CW\*(C`I_SYS_VFS\*(C'\fR,\ \f(CW\*(C`I_SYS_WAIT\*(C'\fR,\ \f(CW\*(C`I_TERMIO\*(C'\fR,\ \f(CW\*(C`I_TERMIOS\*(C'\fR,\ \f(CW\*(C`I_UNISTD\*(C'\fR,\ \f(CW\*(C`I_USTAT\*(C'\fR,\ \f(CW\*(C`I_VFORK\*(C'\fR,\ \f(CW\*(C`I_WCHAR\*(C'\fR,\ \f(CW\*(C`I_WCTYPE\*(C'\fR |
| 8249 |
.PP |
| 8250 |
Example usage: |
| 8251 |
.Sp |
| 8252 |
.Vb 3 |
| 8253 |
\& #ifdef I_WCHAR |
| 8254 |
\& #include <wchar.h> |
| 8255 |
\& #endif |
| 8256 |
.Ve |
| 8257 |
.SH "Global Variables" |
| 8258 |
.IX Header "Global Variables" |
| 8259 |
These variables are global to an entire process. They are shared between |
| 8260 |
all interpreters and all threads in a process. Any variables not documented |
| 8261 |
here may be changed or removed without notice, so don't use them! |
| 8262 |
If you feel you really do need to use an unlisted variable, first send email to |
| 8263 |
perl5\[email protected] <mailto:[email protected]>. It may be that |
| 8264 |
someone there will point out a way to accomplish what you need without using an |
| 8265 |
internal variable. But if not, you should get a go-ahead to document and then |
| 8266 |
use the variable. |
| 8267 |
.ie n .IP """PL_check""" 4 |
| 8268 |
.el .IP \f(CWPL_check\fR 4 |
| 8269 |
.IX Xref "PL_check" |
| 8270 |
.IX Item "PL_check" |
| 8271 |
Array, indexed by opcode, of functions that will be called for the "check" |
| 8272 |
phase of optree building during compilation of Perl code. For most (but |
| 8273 |
not all) types of op, once the op has been initially built and populated |
| 8274 |
with child ops it will be filtered through the check function referenced |
| 8275 |
by the appropriate element of this array. The new op is passed in as the |
| 8276 |
sole argument to the check function, and the check function returns the |
| 8277 |
completed op. The check function may (as the name suggests) check the op |
| 8278 |
for validity and signal errors. It may also initialise or modify parts of |
| 8279 |
the ops, or perform more radical surgery such as adding or removing child |
| 8280 |
ops, or even throw the op away and return a different op in its place. |
| 8281 |
.Sp |
| 8282 |
This array of function pointers is a convenient place to hook into the |
| 8283 |
compilation process. An XS module can put its own custom check function |
| 8284 |
in place of any of the standard ones, to influence the compilation of a |
| 8285 |
particular type of op. However, a custom check function must never fully |
| 8286 |
replace a standard check function (or even a custom check function from |
| 8287 |
another module). A module modifying checking must instead \fBwrap\fR the |
| 8288 |
preexisting check function. A custom check function must be selective |
| 8289 |
about when to apply its custom behaviour. In the usual case where |
| 8290 |
it decides not to do anything special with an op, it must chain the |
| 8291 |
preexisting op function. Check functions are thus linked in a chain, |
| 8292 |
with the core's base checker at the end. |
| 8293 |
.Sp |
| 8294 |
For thread safety, modules should not write directly to this array. |
| 8295 |
Instead, use the function "wrap_op_checker". |
| 8296 |
.ie n .IP """PL_infix_plugin""" 4 |
| 8297 |
.el .IP \f(CWPL_infix_plugin\fR 4 |
| 8298 |
.IX Xref "PL_infix_plugin" |
| 8299 |
.IX Item "PL_infix_plugin" |
| 8300 |
NOTE: \f(CW\*(C`PL_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be |
| 8301 |
removed without notice. |
| 8302 |
.Sp |
| 8303 |
\&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module |
| 8304 |
\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make |
| 8305 |
use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing |
| 8306 |
of new infix operators. |
| 8307 |
.Sp |
| 8308 |
Function pointer, pointing at a function used to handle extended infix |
| 8309 |
operators. The function should be declared as |
| 8310 |
.Sp |
| 8311 |
.Vb 3 |
| 8312 |
\& int infix_plugin_function(pTHX_ |
| 8313 |
\& char *opname, STRLEN oplen, |
| 8314 |
\& struct Perl_custom_infix **infix_ptr) |
| 8315 |
.Ve |
| 8316 |
.Sp |
| 8317 |
The function is called from the tokenizer whenever a possible infix operator |
| 8318 |
is seen. \f(CW\*(C`opname\*(C'\fR points to the operator name in the parser's input buffer, |
| 8319 |
and \f(CW\*(C`oplen\*(C'\fR gives the \fImaximum\fR number of bytes of it that should be |
| 8320 |
consumed; it is not null-terminated. The function is expected to examine the |
| 8321 |
operator name and possibly other state such as %^H, to |
| 8322 |
determine whether it wants to handle the operator name. |
| 8323 |
.Sp |
| 8324 |
As compared to the single stage of \f(CW\*(C`PL_keyword_plugin\*(C'\fR, parsing of additional |
| 8325 |
infix operators occurs in three separate stages. This is because of the more |
| 8326 |
complex interactions it has with the parser, to ensure that operator |
| 8327 |
precedence rules work correctly. These stages are co-ordinated by the use of |
| 8328 |
an additional information structure. |
| 8329 |
.Sp |
| 8330 |
If the function wants to handle the infix operator, it must set the variable |
| 8331 |
pointed to by \f(CW\*(C`infix_ptr\*(C'\fR to the address of a structure that provides this |
| 8332 |
additional information about the subsequent parsing stages. If it does not, |
| 8333 |
it should make a call to the next function in the chain. |
| 8334 |
.Sp |
| 8335 |
This structure has the following definition: |
| 8336 |
.Sp |
| 8337 |
.Vb 7 |
| 8338 |
\& struct Perl_custom_infix { |
| 8339 |
\& enum Perl_custom_infix_precedence prec; |
| 8340 |
\& void (*parse)(pTHX_ SV **opdata, |
| 8341 |
\& struct Perl_custom_infix *); |
| 8342 |
\& OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs, |
| 8343 |
\& struct Perl_custom_infix *); |
| 8344 |
\& }; |
| 8345 |
.Ve |
| 8346 |
.Sp |
| 8347 |
The function must then return an integer giving the number of bytes consumed |
| 8348 |
by the name of this operator. In the case of an operator whose name is |
| 8349 |
composed of identifier characters, this must be equal to \f(CW\*(C`oplen\*(C'\fR. In the case |
| 8350 |
of an operator named by non-identifier characters, this is permitted to be |
| 8351 |
shorter than \f(CW\*(C`oplen\*(C'\fR, and any additional characters after it will not be |
| 8352 |
claimed by the infix operator but instead will be consumed by the tokenizer |
| 8353 |
and parser as normal. |
| 8354 |
.Sp |
| 8355 |
If the optional \f(CW\*(C`parse\*(C'\fR function is provided, it is called immediately by the |
| 8356 |
parser to let the operator's definition consume any additional syntax from the |
| 8357 |
source code. This should \fInot\fR be used for normal operand parsing, but it may |
| 8358 |
be useful when implementing things like parametric operators or meta-operators |
| 8359 |
that consume more syntax themselves. This function may use the variable |
| 8360 |
pointed to by \f(CW\*(C`opdata\*(C'\fR to provide an SV containing additional data to be |
| 8361 |
passed into the \f(CW\*(C`build_op\*(C'\fR function later on. |
| 8362 |
.Sp |
| 8363 |
The information structure gives the operator precedence level in the \f(CW\*(C`prec\*(C'\fR |
| 8364 |
field. This is used to tell the parser how much of the surrounding syntax |
| 8365 |
before and after should be considered as operands to the operator. |
| 8366 |
.Sp |
| 8367 |
The tokenizer and parser will then continue to operate as normal until enough |
| 8368 |
additional input has been parsed to form both the left\- and right-hand side |
| 8369 |
operands to the operator, according to the precedence level. At this point the |
| 8370 |
\&\f(CW\*(C`build_op\*(C'\fR function is called, being passed the left\- and right-hand operands |
| 8371 |
as optree fragments. It is expected to combine them into the resulting optree |
| 8372 |
fragment, which it should return. |
| 8373 |
.Sp |
| 8374 |
After the \f(CW\*(C`build_op\*(C'\fR function has returned, if the variable pointed to by |
| 8375 |
\&\f(CW\*(C`opdata\*(C'\fR was set to a non\-\f(CW\*(C`NULL\*(C'\fR value, it will then be destroyed by calling |
| 8376 |
\&\f(CWSvREFCNT_dec()\fR. |
| 8377 |
.Sp |
| 8378 |
For thread safety, modules should not set this variable directly. |
| 8379 |
Instead, use the function "wrap_infix_plugin". |
| 8380 |
.Sp |
| 8381 |
However, that all said, the introductory note above still applies. This |
| 8382 |
variable is provided in core perl only for the benefit of the |
| 8383 |
\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR module. That module acts as a central registry for infix |
| 8384 |
operators, automatically handling things like deparse support and |
| 8385 |
discovery/reflection, and these abilities only work because it knows all the |
| 8386 |
registered operators. Other modules should not use this interpreter variable |
| 8387 |
directly to implement them because then those central features would no longer |
| 8388 |
work properly. |
| 8389 |
.Sp |
| 8390 |
Furthermore, it is likely that this (experimental) API will be replaced in a |
| 8391 |
future Perl version by a more complete API that fully implements the central |
| 8392 |
registry and other semantics currently provided by \f(CW\*(C`XS::Parse::Infix\*(C'\fR, once |
| 8393 |
the module has had sufficient experimental testing time. This current |
| 8394 |
mechanism exists only as an interim measure to get to that stage. |
| 8395 |
.ie n .IP """PL_keyword_plugin""" 4 |
| 8396 |
.el .IP \f(CWPL_keyword_plugin\fR 4 |
| 8397 |
.IX Xref "PL_keyword_plugin" |
| 8398 |
.IX Item "PL_keyword_plugin" |
| 8399 |
NOTE: \f(CW\*(C`PL_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be |
| 8400 |
removed without notice. |
| 8401 |
.Sp |
| 8402 |
Function pointer, pointing at a function used to handle extended keywords. |
| 8403 |
The function should be declared as |
| 8404 |
.Sp |
| 8405 |
.Vb 3 |
| 8406 |
\& int keyword_plugin_function(pTHX_ |
| 8407 |
\& char *keyword_ptr, STRLEN keyword_len, |
| 8408 |
\& OP **op_ptr) |
| 8409 |
.Ve |
| 8410 |
.Sp |
| 8411 |
The function is called from the tokeniser, whenever a possible keyword |
| 8412 |
is seen. \f(CW\*(C`keyword_ptr\*(C'\fR points at the word in the parser's input |
| 8413 |
buffer, and \f(CW\*(C`keyword_len\*(C'\fR gives its length; it is not null-terminated. |
| 8414 |
The function is expected to examine the word, and possibly other state |
| 8415 |
such as %^H, to decide whether it wants to handle it |
| 8416 |
as an extended keyword. If it does not, the function should return |
| 8417 |
\&\f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR, and the normal parser process will continue. |
| 8418 |
.Sp |
| 8419 |
If the function wants to handle the keyword, it first must |
| 8420 |
parse anything following the keyword that is part of the syntax |
| 8421 |
introduced by the keyword. See "Lexer interface" for details. |
| 8422 |
.Sp |
| 8423 |
When a keyword is being handled, the plugin function must build |
| 8424 |
a tree of \f(CW\*(C`OP\*(C'\fR structures, representing the code that was parsed. |
| 8425 |
The root of the tree must be stored in \f(CW*op_ptr\fR. The function then |
| 8426 |
returns a constant indicating the syntactic role of the construct that |
| 8427 |
it has parsed: \f(CW\*(C`KEYWORD_PLUGIN_STMT\*(C'\fR if it is a complete statement, or |
| 8428 |
\&\f(CW\*(C`KEYWORD_PLUGIN_EXPR\*(C'\fR if it is an expression. Note that a statement |
| 8429 |
construct cannot be used inside an expression (except via \f(CW\*(C`do BLOCK\*(C'\fR |
| 8430 |
and similar), and an expression is not a complete statement (it requires |
| 8431 |
at least a terminating semicolon). |
| 8432 |
.Sp |
| 8433 |
When a keyword is handled, the plugin function may also have |
| 8434 |
(compile-time) side effects. It may modify \f(CW\*(C`%^H\*(C'\fR, define functions, and |
| 8435 |
so on. Typically, if side effects are the main purpose of a handler, |
| 8436 |
it does not wish to generate any ops to be included in the normal |
| 8437 |
compilation. In this case it is still required to supply an op tree, |
| 8438 |
but it suffices to generate a single null op. |
| 8439 |
.Sp |
| 8440 |
That's how the \f(CW*PL_keyword_plugin\fR function needs to behave overall. |
| 8441 |
Conventionally, however, one does not completely replace the existing |
| 8442 |
handler function. Instead, take a copy of \f(CW\*(C`PL_keyword_plugin\*(C'\fR before |
| 8443 |
assigning your own function pointer to it. Your handler function should |
| 8444 |
look for keywords that it is interested in and handle those. Where it |
| 8445 |
is not interested, it should call the saved plugin function, passing on |
| 8446 |
the arguments it received. Thus \f(CW\*(C`PL_keyword_plugin\*(C'\fR actually points |
| 8447 |
at a chain of handler functions, all of which have an opportunity to |
| 8448 |
handle keywords, and only the last function in the chain (built into |
| 8449 |
the Perl core) will normally return \f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR. |
| 8450 |
.Sp |
| 8451 |
For thread safety, modules should not set this variable directly. |
| 8452 |
Instead, use the function "wrap_keyword_plugin". |
| 8453 |
.ie n .IP """PL_phase""" 4 |
| 8454 |
.el .IP \f(CWPL_phase\fR 4 |
| 8455 |
.IX Xref "PL_phase" |
| 8456 |
.IX Item "PL_phase" |
| 8457 |
A value that indicates the current Perl interpreter's phase. Possible values |
| 8458 |
include \f(CW\*(C`PERL_PHASE_CONSTRUCT\*(C'\fR, \f(CW\*(C`PERL_PHASE_START\*(C'\fR, \f(CW\*(C`PERL_PHASE_CHECK\*(C'\fR, |
| 8459 |
\&\f(CW\*(C`PERL_PHASE_INIT\*(C'\fR, \f(CW\*(C`PERL_PHASE_RUN\*(C'\fR, \f(CW\*(C`PERL_PHASE_END\*(C'\fR, and |
| 8460 |
\&\f(CW\*(C`PERL_PHASE_DESTRUCT\*(C'\fR. |
| 8461 |
.Sp |
| 8462 |
For example, the following determines whether the interpreter is in |
| 8463 |
global destruction: |
| 8464 |
.Sp |
| 8465 |
.Vb 3 |
| 8466 |
\& if (PL_phase == PERL_PHASE_DESTRUCT) { |
| 8467 |
\& // we are in global destruction |
| 8468 |
\& } |
| 8469 |
.Ve |
| 8470 |
.Sp |
| 8471 |
\&\f(CW\*(C`PL_phase\*(C'\fR was introduced in Perl 5.14; in prior perls you can use |
| 8472 |
\&\f(CW\*(C`PL_dirty\*(C'\fR (boolean) to determine whether the interpreter is in global |
| 8473 |
destruction. (Use of \f(CW\*(C`PL_dirty\*(C'\fR is discouraged since 5.14.) |
| 8474 |
.RS 4 |
| 8475 |
.Sp |
| 8476 |
.Vb 1 |
| 8477 |
\& enum perl_phase PL_phase |
| 8478 |
.Ve |
| 8479 |
.RE |
| 8480 |
.RS 4 |
| 8481 |
.RE |
| 8482 |
.SH "GV Handling and Stashes" |
| 8483 |
.IX Xref "GV GV_ADD GV_ADDMG GV_ADDMULTI GV_ADDWARN GV_NOADD_NOINIT GV_NOEXPAND GV_NOINIT GV_NOTQUAL GV_NO_SVGMAGIC GV_SUPER SVf_UTF8" |
| 8484 |
.IX Header "GV Handling and Stashes" |
| 8485 |
A GV is a structure which corresponds to a Perl typeglob, ie *foo. |
| 8486 |
It is a structure that holds a pointer to a scalar, an array, a hash etc, |
| 8487 |
corresponding to \f(CW$foo\fR, \f(CW@foo\fR, \f(CW%foo\fR. |
| 8488 |
.PP |
| 8489 |
GVs are usually found as values in stashes (symbol table hashes) where |
| 8490 |
Perl stores its global variables. |
| 8491 |
.PP |
| 8492 |
A \fBstash\fR is a hash that contains all variables that are defined |
| 8493 |
within a package. See "Stashes and Globs" in perlguts |
| 8494 |
.ie n .IP """amagic_call""" 4 |
| 8495 |
.el .IP \f(CWamagic_call\fR 4 |
| 8496 |
.IX Xref "amagic_call" |
| 8497 |
.IX Item "amagic_call" |
| 8498 |
Perform the overloaded (active magic) operation given by \f(CW\*(C`method\*(C'\fR. |
| 8499 |
\&\f(CW\*(C`method\*(C'\fR is one of the values found in \fIoverload.h\fR. |
| 8500 |
.Sp |
| 8501 |
\&\f(CW\*(C`flags\*(C'\fR affects how the operation is performed, as follows: |
| 8502 |
.RS 4 |
| 8503 |
.ie n .IP """AMGf_noleft""" 4 |
| 8504 |
.el .IP \f(CWAMGf_noleft\fR 4 |
| 8505 |
.IX Item "AMGf_noleft" |
| 8506 |
\&\f(CW\*(C`left\*(C'\fR is not to be used in this operation. |
| 8507 |
.ie n .IP """AMGf_noright""" 4 |
| 8508 |
.el .IP \f(CWAMGf_noright\fR 4 |
| 8509 |
.IX Item "AMGf_noright" |
| 8510 |
\&\f(CW\*(C`right\*(C'\fR is not to be used in this operation. |
| 8511 |
.ie n .IP """AMGf_unary""" 4 |
| 8512 |
.el .IP \f(CWAMGf_unary\fR 4 |
| 8513 |
.IX Item "AMGf_unary" |
| 8514 |
The operation is done only on just one operand. |
| 8515 |
.ie n .IP """AMGf_assign""" 4 |
| 8516 |
.el .IP \f(CWAMGf_assign\fR 4 |
| 8517 |
.IX Item "AMGf_assign" |
| 8518 |
The operation changes one of the operands, e.g., \f(CW$x\fR += 1 |
| 8519 |
.RE |
| 8520 |
.RS 4 |
| 8521 |
.Sp |
| 8522 |
.Vb 1 |
| 8523 |
\& SV * amagic_call(SV *left, SV *right, int method, int dir) |
| 8524 |
.Ve |
| 8525 |
.RE |
| 8526 |
.RS 4 |
| 8527 |
.RE |
| 8528 |
.ie n .IP """amagic_deref_call""" 4 |
| 8529 |
.el .IP \f(CWamagic_deref_call\fR 4 |
| 8530 |
.IX Xref "amagic_deref_call" |
| 8531 |
.IX Item "amagic_deref_call" |
| 8532 |
Perform \f(CW\*(C`method\*(C'\fR overloading dereferencing on \f(CW\*(C`ref\*(C'\fR, returning the |
| 8533 |
dereferenced result. \f(CW\*(C`method\*(C'\fR must be one of the dereference operations given |
| 8534 |
in \fIoverload.h\fR. |
| 8535 |
.Sp |
| 8536 |
If overloading is inactive on \f(CW\*(C`ref\*(C'\fR, returns \f(CW\*(C`ref\*(C'\fR itself. |
| 8537 |
.RS 4 |
| 8538 |
.Sp |
| 8539 |
.Vb 1 |
| 8540 |
\& SV * amagic_deref_call(SV *ref, int method) |
| 8541 |
.Ve |
| 8542 |
.RE |
| 8543 |
.RS 4 |
| 8544 |
.RE |
| 8545 |
.ie n .IP """gv_add_by_type""" 4 |
| 8546 |
.el .IP \f(CWgv_add_by_type\fR 4 |
| 8547 |
.IX Xref "gv_add_by_type" |
| 8548 |
.IX Item "gv_add_by_type" |
| 8549 |
Make sure there is a slot of type \f(CW\*(C`type\*(C'\fR in the GV \f(CW\*(C`gv\*(C'\fR. |
| 8550 |
.RS 4 |
| 8551 |
.Sp |
| 8552 |
.Vb 1 |
| 8553 |
\& GV * gv_add_by_type(GV *gv, svtype type) |
| 8554 |
.Ve |
| 8555 |
.RE |
| 8556 |
.RS 4 |
| 8557 |
.RE |
| 8558 |
.ie n .IP """Gv_AMupdate""" 4 |
| 8559 |
.el .IP \f(CWGv_AMupdate\fR 4 |
| 8560 |
.IX Xref "Gv_AMupdate" |
| 8561 |
.IX Item "Gv_AMupdate" |
| 8562 |
Recalculates overload magic in the package given by \f(CW\*(C`stash\*(C'\fR. |
| 8563 |
.Sp |
| 8564 |
Returns: |
| 8565 |
.RS 4 |
| 8566 |
.IP "1 on success and there is some overload" 4 |
| 8567 |
.IX Item "1 on success and there is some overload" |
| 8568 |
.PD 0 |
| 8569 |
.IP "0 if there is no overload" 4 |
| 8570 |
.IX Item "0 if there is no overload" |
| 8571 |
.ie n .IP "\-1 if some error occurred and it couldn't croak (because ""destructing"" is true)." 4 |
| 8572 |
.el .IP "\-1 if some error occurred and it couldn't croak (because \f(CWdestructing\fR is true)." 4 |
| 8573 |
.IX Item "-1 if some error occurred and it couldn't croak (because destructing is true)." |
| 8574 |
.RE |
| 8575 |
.RS 4 |
| 8576 |
.PD |
| 8577 |
.Sp |
| 8578 |
.Vb 1 |
| 8579 |
\& int Gv_AMupdate(HV *stash, bool destructing) |
| 8580 |
.Ve |
| 8581 |
.RE |
| 8582 |
.RS 4 |
| 8583 |
.RE |
| 8584 |
.ie n .IP """gv_autoload_pv""" 4 |
| 8585 |
.el .IP \f(CWgv_autoload_pv\fR 4 |
| 8586 |
.IX Item "gv_autoload_pv" |
| 8587 |
.PD 0 |
| 8588 |
.ie n .IP """gv_autoload_pvn""" 4 |
| 8589 |
.el .IP \f(CWgv_autoload_pvn\fR 4 |
| 8590 |
.IX Item "gv_autoload_pvn" |
| 8591 |
.ie n .IP """gv_autoload_sv""" 4 |
| 8592 |
.el .IP \f(CWgv_autoload_sv\fR 4 |
| 8593 |
.IX Xref "gv_autoload_pv gv_autoload_pvn gv_autoload_sv" |
| 8594 |
.IX Item "gv_autoload_sv" |
| 8595 |
.PD |
| 8596 |
These each search for an \f(CW\*(C`AUTOLOAD\*(C'\fR method, returning NULL if not found, or |
| 8597 |
else returning a pointer to its GV, while setting the package |
| 8598 |
\&\f(CW$AUTOLOAD\fR variable to \f(CW\*(C`name\*(C'\fR (fully qualified). Also, |
| 8599 |
if found and the GV's CV is an XSUB, the CV's PV will be set to \f(CW\*(C`name\*(C'\fR, and |
| 8600 |
its stash will be set to the stash of the GV. |
| 8601 |
.Sp |
| 8602 |
Searching is done in \f(CW\*(C`MRO\*(C'\fR order, as specified in |
| 8603 |
"\f(CW\*(C`gv_fetchmeth\*(C'\fR", beginning with \f(CW\*(C`stash\*(C'\fR if it isn't NULL. |
| 8604 |
.Sp |
| 8605 |
The forms differ only in how \f(CW\*(C`name\*(C'\fR is specified. |
| 8606 |
.Sp |
| 8607 |
In \f(CW\*(C`gv_autoload_pv\*(C'\fR, \f(CW\*(C`namepv\*(C'\fR is a C language NUL-terminated string. |
| 8608 |
.Sp |
| 8609 |
In \f(CW\*(C`gv_autoload_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an |
| 8610 |
additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, \f(CW*name\fR |
| 8611 |
may contain embedded-NUL characters. |
| 8612 |
.Sp |
| 8613 |
In \f(CW\*(C`gv_autoload_sv\*(C'\fR, \f(CW*namesv\fR is an SV, and the name is the PV extracted |
| 8614 |
from that using "\f(CW\*(C`SvPV\*(C'\fR". If the SV is marked as being in UTF\-8, the |
| 8615 |
extracted PV will also be. |
| 8616 |
.RS 4 |
| 8617 |
.Sp |
| 8618 |
.Vb 4 |
| 8619 |
\& GV * gv_autoload_pv (HV *stash, const char *namepv, U32 flags) |
| 8620 |
\& GV * gv_autoload_pvn(HV *stash, const char *name, STRLEN len, |
| 8621 |
\& U32 flags) |
| 8622 |
\& GV * gv_autoload_sv (HV *stash, SV *namesv, U32 flags) |
| 8623 |
.Ve |
| 8624 |
.RE |
| 8625 |
.RS 4 |
| 8626 |
.RE |
| 8627 |
.ie n .IP """gv_autoload4""" 4 |
| 8628 |
.el .IP \f(CWgv_autoload4\fR 4 |
| 8629 |
.IX Xref "gv_autoload4" |
| 8630 |
.IX Item "gv_autoload4" |
| 8631 |
Equivalent to \f(CW"gv_autoload_pvn"\fR. |
| 8632 |
.RS 4 |
| 8633 |
.Sp |
| 8634 |
.Vb 2 |
| 8635 |
\& GV * gv_autoload4(HV *stash, const char *name, STRLEN len, |
| 8636 |
\& I32 method) |
| 8637 |
.Ve |
| 8638 |
.RE |
| 8639 |
.RS 4 |
| 8640 |
.RE |
| 8641 |
.ie n .IP """GvAV""" 4 |
| 8642 |
.el .IP \f(CWGvAV\fR 4 |
| 8643 |
.IX Xref "GvAV" |
| 8644 |
.IX Item "GvAV" |
| 8645 |
Return the AV from the GV. |
| 8646 |
.RS 4 |
| 8647 |
.Sp |
| 8648 |
.Vb 1 |
| 8649 |
\& AV* GvAV(GV* gv) |
| 8650 |
.Ve |
| 8651 |
.RE |
| 8652 |
.RS 4 |
| 8653 |
.RE |
| 8654 |
.ie n .IP """gv_AVadd""" 4 |
| 8655 |
.el .IP \f(CWgv_AVadd\fR 4 |
| 8656 |
.IX Item "gv_AVadd" |
| 8657 |
.PD 0 |
| 8658 |
.ie n .IP """gv_HVadd""" 4 |
| 8659 |
.el .IP \f(CWgv_HVadd\fR 4 |
| 8660 |
.IX Item "gv_HVadd" |
| 8661 |
.ie n .IP """gv_IOadd""" 4 |
| 8662 |
.el .IP \f(CWgv_IOadd\fR 4 |
| 8663 |
.IX Item "gv_IOadd" |
| 8664 |
.ie n .IP """gv_SVadd""" 4 |
| 8665 |
.el .IP \f(CWgv_SVadd\fR 4 |
| 8666 |
.IX Xref "gv_AVadd gv_HVadd gv_IOadd gv_SVadd" |
| 8667 |
.IX Item "gv_SVadd" |
| 8668 |
.PD |
| 8669 |
Make sure there is a slot of the given type (AV, HV, IO, SV) in the GV \f(CW\*(C`gv\*(C'\fR. |
| 8670 |
.RS 4 |
| 8671 |
.Sp |
| 8672 |
.Vb 1 |
| 8673 |
\& GV * gv_AVadd(GV *gv) |
| 8674 |
.Ve |
| 8675 |
.RE |
| 8676 |
.RS 4 |
| 8677 |
.RE |
| 8678 |
.ie n .IP """gv_const_sv""" 4 |
| 8679 |
.el .IP \f(CWgv_const_sv\fR 4 |
| 8680 |
.IX Xref "gv_const_sv" |
| 8681 |
.IX Item "gv_const_sv" |
| 8682 |
If \f(CW\*(C`gv\*(C'\fR is a typeglob whose subroutine entry is a constant sub eligible for |
| 8683 |
inlining, or \f(CW\*(C`gv\*(C'\fR is a placeholder reference that would be promoted to such |
| 8684 |
a typeglob, then returns the value returned by the sub. Otherwise, returns |
| 8685 |
\&\f(CW\*(C`NULL\*(C'\fR. |
| 8686 |
.RS 4 |
| 8687 |
.Sp |
| 8688 |
.Vb 1 |
| 8689 |
\& SV * gv_const_sv(GV *gv) |
| 8690 |
.Ve |
| 8691 |
.RE |
| 8692 |
.RS 4 |
| 8693 |
.RE |
| 8694 |
.ie n .IP """GvCV""" 4 |
| 8695 |
.el .IP \f(CWGvCV\fR 4 |
| 8696 |
.IX Xref "GvCV" |
| 8697 |
.IX Item "GvCV" |
| 8698 |
Return the CV from the GV. |
| 8699 |
.RS 4 |
| 8700 |
.Sp |
| 8701 |
.Vb 1 |
| 8702 |
\& CV* GvCV(GV* gv) |
| 8703 |
.Ve |
| 8704 |
.RE |
| 8705 |
.RS 4 |
| 8706 |
.RE |
| 8707 |
.ie n .IP """gv_efullname3""" 4 |
| 8708 |
.el .IP \f(CWgv_efullname3\fR 4 |
| 8709 |
.IX Item "gv_efullname3" |
| 8710 |
.PD 0 |
| 8711 |
.ie n .IP """gv_efullname4""" 4 |
| 8712 |
.el .IP \f(CWgv_efullname4\fR 4 |
| 8713 |
.IX Item "gv_efullname4" |
| 8714 |
.ie n .IP """gv_fullname3""" 4 |
| 8715 |
.el .IP \f(CWgv_fullname3\fR 4 |
| 8716 |
.IX Item "gv_fullname3" |
| 8717 |
.ie n .IP """gv_fullname4""" 4 |
| 8718 |
.el .IP \f(CWgv_fullname4\fR 4 |
| 8719 |
.IX Xref "gv_efullname3 gv_efullname4 gv_fullname3 gv_fullname4" |
| 8720 |
.IX Item "gv_fullname4" |
| 8721 |
.PD |
| 8722 |
Place the full package name of \f(CW\*(C`gv\*(C'\fR into \f(CW\*(C`sv\*(C'\fR. The \f(CW\*(C`gv_e*\*(C'\fR forms return |
| 8723 |
instead the effective package name (see "HvENAME"). |
| 8724 |
.Sp |
| 8725 |
If \f(CW\*(C`prefix\*(C'\fR is non-NULL, it is considered to be a C language NUL-terminated |
| 8726 |
string, and the stored name will be prefaced with it. |
| 8727 |
.Sp |
| 8728 |
The other difference between the functions is that the \f(CW*4\fR forms have an |
| 8729 |
extra parameter, \f(CW\*(C`keepmain\*(C'\fR. If \f(CW\*(C`true\*(C'\fR an initial \f(CW\*(C`main::\*(C'\fR in the name is |
| 8730 |
kept; if \f(CW\*(C`false\*(C'\fR it is stripped. With the \f(CW*3\fR forms, it is always kept. |
| 8731 |
.RS 4 |
| 8732 |
.Sp |
| 8733 |
.Vb 6 |
| 8734 |
\& void gv_efullname3(SV *sv, const GV *gv, const char *prefix) |
| 8735 |
\& void gv_efullname4(SV *sv, const GV *gv, const char *prefix, |
| 8736 |
\& bool keepmain) |
| 8737 |
\& void gv_fullname3 (SV *sv, const GV *gv, const char *prefix) |
| 8738 |
\& void gv_fullname4 (SV *sv, const GV *gv, const char *prefix, |
| 8739 |
\& bool keepmain) |
| 8740 |
.Ve |
| 8741 |
.RE |
| 8742 |
.RS 4 |
| 8743 |
.RE |
| 8744 |
.ie n .IP """gv_fetchfile""" 4 |
| 8745 |
.el .IP \f(CWgv_fetchfile\fR 4 |
| 8746 |
.IX Item "gv_fetchfile" |
| 8747 |
.PD 0 |
| 8748 |
.ie n .IP """gv_fetchfile_flags""" 4 |
| 8749 |
.el .IP \f(CWgv_fetchfile_flags\fR 4 |
| 8750 |
.IX Xref "gv_fetchfile gv_fetchfile_flags" |
| 8751 |
.IX Item "gv_fetchfile_flags" |
| 8752 |
.PD |
| 8753 |
These return the debugger glob for the file (compiled by Perl) whose name is |
| 8754 |
given by the \f(CW\*(C`name\*(C'\fR parameter. |
| 8755 |
.Sp |
| 8756 |
There are currently exactly two differences between these functions. |
| 8757 |
.Sp |
| 8758 |
The \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile\*(C'\fR is a C string, meaning it is |
| 8759 |
\&\f(CW\*(C`NUL\*(C'\fR\-terminated; whereas the \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile_flags\*(C'\fR is a |
| 8760 |
Perl string, whose length (in bytes) is passed in via the \f(CW\*(C`namelen\*(C'\fR parameter |
| 8761 |
This means the name may contain embedded \f(CW\*(C`NUL\*(C'\fR characters. |
| 8762 |
\&\f(CW\*(C`namelen\*(C'\fR doesn't exist in plain \f(CW\*(C`gv_fetchfile\*(C'\fR). |
| 8763 |
.Sp |
| 8764 |
The other difference is that \f(CW\*(C`gv_fetchfile_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR |
| 8765 |
parameter, which is currently completely ignored, but allows for possible |
| 8766 |
future extensions. |
| 8767 |
.RS 4 |
| 8768 |
.Sp |
| 8769 |
.Vb 3 |
| 8770 |
\& GV * gv_fetchfile (const char *name) |
| 8771 |
\& GV * gv_fetchfile_flags(const char * const name, |
| 8772 |
\& const STRLEN len, const U32 flags) |
| 8773 |
.Ve |
| 8774 |
.RE |
| 8775 |
.RS 4 |
| 8776 |
.RE |
| 8777 |
.ie n .IP """gv_fetchmeth""" 4 |
| 8778 |
.el .IP \f(CWgv_fetchmeth\fR 4 |
| 8779 |
.IX Item "gv_fetchmeth" |
| 8780 |
.PD 0 |
| 8781 |
.ie n .IP """gv_fetchmeth_pv""" 4 |
| 8782 |
.el .IP \f(CWgv_fetchmeth_pv\fR 4 |
| 8783 |
.IX Item "gv_fetchmeth_pv" |
| 8784 |
.ie n .IP """gv_fetchmeth_pvn""" 4 |
| 8785 |
.el .IP \f(CWgv_fetchmeth_pvn\fR 4 |
| 8786 |
.IX Item "gv_fetchmeth_pvn" |
| 8787 |
.ie n .IP """gv_fetchmeth_sv""" 4 |
| 8788 |
.el .IP \f(CWgv_fetchmeth_sv\fR 4 |
| 8789 |
.IX Xref "gv_fetchmeth gv_fetchmeth_pv gv_fetchmeth_pvn gv_fetchmeth_sv" |
| 8790 |
.IX Item "gv_fetchmeth_sv" |
| 8791 |
.PD |
| 8792 |
These each look for a glob with name \f(CW\*(C`name\*(C'\fR, containing a defined subroutine, |
| 8793 |
returning the GV of that glob if found, or \f(CW\*(C`NULL\*(C'\fR if not. |
| 8794 |
.Sp |
| 8795 |
\&\f(CW\*(C`stash\*(C'\fR is always searched (first), unless it is \f(CW\*(C`NULL\*(C'\fR. |
| 8796 |
.Sp |
| 8797 |
If \f(CW\*(C`stash\*(C'\fR is NULL, or was searched but nothing was found in it, and the |
| 8798 |
\&\f(CW\*(C`GV_SUPER\*(C'\fR bit is set in \f(CW\*(C`flags\*(C'\fR, stashes accessible via \f(CW@ISA\fR are searched |
| 8799 |
next. Searching is conducted according to \f(CW\*(C`MRO\*(C'\fR order. |
| 8800 |
.Sp |
| 8801 |
Finally, if no matches were found so far, and the \f(CW\*(C`GV_NOUNIVERSAL\*(C'\fR flag in |
| 8802 |
\&\f(CW\*(C`flags\*(C'\fR is not set, \f(CW\*(C`UNIVERSAL::\*(C'\fR is searched. |
| 8803 |
.Sp |
| 8804 |
The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1. If \-1, the function will |
| 8805 |
return without any side effects or caching. If 0, the function makes sure |
| 8806 |
there is a glob named \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`stash\*(C'\fR, creating one if necessary. |
| 8807 |
The subroutine slot in the glob will be set to any subroutine found in the |
| 8808 |
\&\f(CW\*(C`stash\*(C'\fR and \f(CW\*(C`SUPER::\*(C'\fR search, hence caching any \f(CW\*(C`SUPER::\*(C'\fR result. Note that |
| 8809 |
subroutines found in \f(CW\*(C`UNIVERSAL::\*(C'\fR are not cached. |
| 8810 |
.Sp |
| 8811 |
The GV returned from these may be a method cache entry, which is not visible to |
| 8812 |
Perl code. So when calling \f(CW\*(C`call_sv\*(C'\fR, you should not use the GV directly; |
| 8813 |
instead, you should use the method's CV, which can be obtained from the GV with |
| 8814 |
the \f(CW\*(C`GvCV\*(C'\fR macro. |
| 8815 |
.Sp |
| 8816 |
The only other significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR, indicating that |
| 8817 |
\&\f(CW\*(C`name\*(C'\fR is to be treated as being encoded in UTF\-8. |
| 8818 |
.Sp |
| 8819 |
Plain \f(CW\*(C`gv_fetchmeth\*(C'\fR lacks a \f(CW\*(C`flags\*(C'\fR parameter, hence always searches in |
| 8820 |
\&\f(CW\*(C`stash\*(C'\fR, then \f(CW\*(C`UNIVERSAL::\*(C'\fR, and \f(CW\*(C`name\*(C'\fR is never UTF\-8. Otherwise it is |
| 8821 |
exactly like \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR. |
| 8822 |
.Sp |
| 8823 |
The other forms do have a \f(CW\*(C`flags\*(C'\fR parameter, and differ only in how the glob |
| 8824 |
name is specified. |
| 8825 |
.Sp |
| 8826 |
In \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a C language NUL-terminated string. |
| 8827 |
.Sp |
| 8828 |
In \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an |
| 8829 |
additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the name |
| 8830 |
may contain embedded-NUL characters. |
| 8831 |
.Sp |
| 8832 |
In \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR, \f(CW*name\fR is an SV, and the name is the PV extracted from |
| 8833 |
that, using "\f(CW\*(C`SvPV\*(C'\fR". If the SV is marked as being in UTF\-8, the extracted |
| 8834 |
PV will also be. |
| 8835 |
.RS 4 |
| 8836 |
.Sp |
| 8837 |
.Vb 8 |
| 8838 |
\& GV * gv_fetchmeth (HV *stash, const char *name, STRLEN len, |
| 8839 |
\& I32 level) |
| 8840 |
\& GV * gv_fetchmeth_pv (HV *stash, const char *name, I32 level, |
| 8841 |
\& U32 flags) |
| 8842 |
\& GV * gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len, |
| 8843 |
\& I32 level, U32 flags) |
| 8844 |
\& GV * gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level, |
| 8845 |
\& U32 flags) |
| 8846 |
.Ve |
| 8847 |
.RE |
| 8848 |
.RS 4 |
| 8849 |
.RE |
| 8850 |
.ie n .IP """gv_fetchmeth_autoload""" 4 |
| 8851 |
.el .IP \f(CWgv_fetchmeth_autoload\fR 4 |
| 8852 |
.IX Xref "gv_fetchmeth_autoload" |
| 8853 |
.IX Item "gv_fetchmeth_autoload" |
| 8854 |
This is the old form of "gv_fetchmeth_pvn_autoload", which has no flags |
| 8855 |
parameter. |
| 8856 |
.RS 4 |
| 8857 |
.Sp |
| 8858 |
.Vb 2 |
| 8859 |
\& GV * gv_fetchmeth_autoload(HV *stash, const char *name, |
| 8860 |
\& STRLEN len, I32 level) |
| 8861 |
.Ve |
| 8862 |
.RE |
| 8863 |
.RS 4 |
| 8864 |
.RE |
| 8865 |
.ie n .IP """gv_fetchmethod""" 4 |
| 8866 |
.el .IP \f(CWgv_fetchmethod\fR 4 |
| 8867 |
.IX Xref "gv_fetchmethod" |
| 8868 |
.IX Item "gv_fetchmethod" |
| 8869 |
See "gv_fetchmethod_autoload". |
| 8870 |
.RS 4 |
| 8871 |
.Sp |
| 8872 |
.Vb 1 |
| 8873 |
\& GV * gv_fetchmethod(HV *stash, const char *name) |
| 8874 |
.Ve |
| 8875 |
.RE |
| 8876 |
.RS 4 |
| 8877 |
.RE |
| 8878 |
.ie n .IP """gv_fetchmethod_autoload""" 4 |
| 8879 |
.el .IP \f(CWgv_fetchmethod_autoload\fR 4 |
| 8880 |
.IX Xref "gv_fetchmethod_autoload" |
| 8881 |
.IX Item "gv_fetchmethod_autoload" |
| 8882 |
Returns the glob which contains the subroutine to call to invoke the method |
| 8883 |
on the \f(CW\*(C`stash\*(C'\fR. In fact in the presence of autoloading this may be the |
| 8884 |
glob for "AUTOLOAD". In this case the corresponding variable \f(CW$AUTOLOAD\fR is |
| 8885 |
already setup. |
| 8886 |
.Sp |
| 8887 |
The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether |
| 8888 |
AUTOLOAD lookup is performed if the given method is not present: non-zero |
| 8889 |
means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. |
| 8890 |
Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR |
| 8891 |
with a non-zero \f(CW\*(C`autoload\*(C'\fR parameter. |
| 8892 |
.Sp |
| 8893 |
These functions grant \f(CW"SUPER"\fR token |
| 8894 |
as a prefix of the method name. Note |
| 8895 |
that if you want to keep the returned glob for a long time, you need to |
| 8896 |
check for it being "AUTOLOAD", since at the later time the call may load a |
| 8897 |
different subroutine due to \f(CW$AUTOLOAD\fR changing its value. Use the glob |
| 8898 |
created as a side effect to do this. |
| 8899 |
.Sp |
| 8900 |
These functions have the same side-effects as \f(CW\*(C`gv_fetchmeth\*(C'\fR with |
| 8901 |
\&\f(CW\*(C`level==0\*(C'\fR. The warning against passing the GV returned by |
| 8902 |
\&\f(CW\*(C`gv_fetchmeth\*(C'\fR to \f(CW\*(C`call_sv\*(C'\fR applies equally to these functions. |
| 8903 |
.RS 4 |
| 8904 |
.Sp |
| 8905 |
.Vb 2 |
| 8906 |
\& GV * gv_fetchmethod_autoload(HV *stash, const char *name, |
| 8907 |
\& I32 autoload) |
| 8908 |
.Ve |
| 8909 |
.RE |
| 8910 |
.RS 4 |
| 8911 |
.RE |
| 8912 |
.ie n .IP """gv_fetchmeth_pv_autoload""" 4 |
| 8913 |
.el .IP \f(CWgv_fetchmeth_pv_autoload\fR 4 |
| 8914 |
.IX Xref "gv_fetchmeth_pv_autoload" |
| 8915 |
.IX Item "gv_fetchmeth_pv_autoload" |
| 8916 |
Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-terminated string |
| 8917 |
instead of a string/length pair. |
| 8918 |
.RS 4 |
| 8919 |
.Sp |
| 8920 |
.Vb 2 |
| 8921 |
\& GV * gv_fetchmeth_pv_autoload(HV *stash, const char *name, |
| 8922 |
\& I32 level, U32 flags) |
| 8923 |
.Ve |
| 8924 |
.RE |
| 8925 |
.RS 4 |
| 8926 |
.RE |
| 8927 |
.ie n .IP """gv_fetchmeth_pvn_autoload""" 4 |
| 8928 |
.el .IP \f(CWgv_fetchmeth_pvn_autoload\fR 4 |
| 8929 |
.IX Xref "gv_fetchmeth_pvn_autoload" |
| 8930 |
.IX Item "gv_fetchmeth_pvn_autoload" |
| 8931 |
Same as \f(CWgv_fetchmeth_pvn()\fR, but looks for autoloaded subroutines too. |
| 8932 |
Returns a glob for the subroutine. |
| 8933 |
.Sp |
| 8934 |
For an autoloaded subroutine without a GV, will create a GV even |
| 8935 |
if \f(CW\*(C`level < 0\*(C'\fR. For an autoloaded subroutine without a stub, \f(CWGvCV()\fR |
| 8936 |
of the result may be zero. |
| 8937 |
.Sp |
| 8938 |
Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR. |
| 8939 |
.RS 4 |
| 8940 |
.Sp |
| 8941 |
.Vb 2 |
| 8942 |
\& GV * gv_fetchmeth_pvn_autoload(HV *stash, const char *name, |
| 8943 |
\& STRLEN len, I32 level, U32 flags) |
| 8944 |
.Ve |
| 8945 |
.RE |
| 8946 |
.RS 4 |
| 8947 |
.RE |
| 8948 |
.ie n .IP """gv_fetchmeth_sv_autoload""" 4 |
| 8949 |
.el .IP \f(CWgv_fetchmeth_sv_autoload\fR 4 |
| 8950 |
.IX Xref "gv_fetchmeth_sv_autoload" |
| 8951 |
.IX Item "gv_fetchmeth_sv_autoload" |
| 8952 |
Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string in the form |
| 8953 |
of an SV instead of a string/length pair. |
| 8954 |
.RS 4 |
| 8955 |
.Sp |
| 8956 |
.Vb 2 |
| 8957 |
\& GV * gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level, |
| 8958 |
\& U32 flags) |
| 8959 |
.Ve |
| 8960 |
.RE |
| 8961 |
.RS 4 |
| 8962 |
.RE |
| 8963 |
.ie n .IP """gv_fetchpv""" 4 |
| 8964 |
.el .IP \f(CWgv_fetchpv\fR 4 |
| 8965 |
.IX Item "gv_fetchpv" |
| 8966 |
.PD 0 |
| 8967 |
.ie n .IP """gv_fetchpvn""" 4 |
| 8968 |
.el .IP \f(CWgv_fetchpvn\fR 4 |
| 8969 |
.IX Item "gv_fetchpvn" |
| 8970 |
.ie n .IP """gv_fetchpvn_flags""" 4 |
| 8971 |
.el .IP \f(CWgv_fetchpvn_flags\fR 4 |
| 8972 |
.IX Item "gv_fetchpvn_flags" |
| 8973 |
.ie n .IP """gv_fetchpvs""" 4 |
| 8974 |
.el .IP \f(CWgv_fetchpvs\fR 4 |
| 8975 |
.IX Item "gv_fetchpvs" |
| 8976 |
.ie n .IP """gv_fetchsv""" 4 |
| 8977 |
.el .IP \f(CWgv_fetchsv\fR 4 |
| 8978 |
.IX Item "gv_fetchsv" |
| 8979 |
.ie n .IP """gv_fetchsv_nomg""" 4 |
| 8980 |
.el .IP \f(CWgv_fetchsv_nomg\fR 4 |
| 8981 |
.IX Xref "gv_fetchpv gv_fetchpvn gv_fetchpvn_flags gv_fetchpvs gv_fetchsv gv_fetchsv_nomg" |
| 8982 |
.IX Item "gv_fetchsv_nomg" |
| 8983 |
.PD |
| 8984 |
These all return the GV of type \f(CW\*(C`sv_type\*(C'\fR whose name is given by the inputs, |
| 8985 |
or NULL if no GV of that name and type could be found. See "Stashes |
| 8986 |
and Globs" in perlguts. |
| 8987 |
.Sp |
| 8988 |
The only differences are how the input name is specified, and if 'get' magic is |
| 8989 |
normally used in getting that name. |
| 8990 |
.Sp |
| 8991 |
Don't be fooled by the fact that only one form has \f(CW\*(C`flags\*(C'\fR in its name. They |
| 8992 |
all have a \f(CW\*(C`flags\*(C'\fR parameter in fact, and all the flag bits have the same |
| 8993 |
meanings for all |
| 8994 |
.Sp |
| 8995 |
If any of the flags \f(CW\*(C`GV_ADD\*(C'\fR, \f(CW\*(C`GV_ADDMG\*(C'\fR, \f(CW\*(C`GV_ADDWARN\*(C'\fR, \f(CW\*(C`GV_ADDMULTI\*(C'\fR, or |
| 8996 |
\&\f(CW\*(C`GV_NOINIT\*(C'\fR is set, a GV is created if none already exists for the input name |
| 8997 |
and type. However, \f(CW\*(C`GV_ADDMG\*(C'\fR will only do the creation for magical GV's. |
| 8998 |
For all of these flags except \f(CW\*(C`GV_NOINIT\*(C'\fR, \f(CW"gv_init_pvn"\fR is called after |
| 8999 |
the addition. \f(CW\*(C`GV_ADDWARN\*(C'\fR is used when the caller expects that adding won't |
| 9000 |
be necessary because the symbol should already exist; but if not, add it |
| 9001 |
anyway, with a warning that it was unexpectedly absent. The \f(CW\*(C`GV_ADDMULTI\*(C'\fR |
| 9002 |
flag means to pretend that the GV has been seen before (\fIi.e.\fR, suppress "Used |
| 9003 |
once" warnings). |
| 9004 |
.Sp |
| 9005 |
The flag \f(CW\*(C`GV_NOADD_NOINIT\*(C'\fR causes \f(CW"gv_init_pvn"\fR not be to called if the |
| 9006 |
GV existed but isn't PVGV. |
| 9007 |
.Sp |
| 9008 |
If the \f(CW\*(C`SVf_UTF8\*(C'\fR bit is set, the name is treated as being encoded in UTF\-8; |
| 9009 |
otherwise the name won't be considered to be UTF\-8 in the \f(CW\*(C`pv\*(C'\fR\-named forms, |
| 9010 |
and the UTF\-8ness of the underlying SVs will be used in the \f(CW\*(C`sv\*(C'\fR forms. |
| 9011 |
.Sp |
| 9012 |
If the flag \f(CW\*(C`GV_NOTQUAL\*(C'\fR is set, the caller warrants that the input name is a |
| 9013 |
plain symbol name, not qualified with a package, otherwise the name is checked |
| 9014 |
for being a qualified one. |
| 9015 |
.Sp |
| 9016 |
In \f(CW\*(C`gv_fetchpv\*(C'\fR, \f(CW\*(C`nambeg\*(C'\fR is a C string, NUL-terminated with no intermediate |
| 9017 |
NULs. |
| 9018 |
.Sp |
| 9019 |
In \f(CW\*(C`gv_fetchpvs\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a literal C string, hence is enclosed in |
| 9020 |
double quotes. |
| 9021 |
.Sp |
| 9022 |
\&\f(CW\*(C`gv_fetchpvn\*(C'\fR and \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR are identical. In these, <nambeg> is |
| 9023 |
a Perl string whose byte length is given by \f(CW\*(C`full_len\*(C'\fR, and may contain |
| 9024 |
embedded NULs. |
| 9025 |
.Sp |
| 9026 |
In \f(CW\*(C`gv_fetchsv\*(C'\fR and \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR, the name is extracted from the PV of |
| 9027 |
the input \f(CW\*(C`name\*(C'\fR SV. The only difference between these two forms is that |
| 9028 |
\&'get' magic is normally done on \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`gv_fetchsv\*(C'\fR, and always skipped |
| 9029 |
with \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR. Including \f(CW\*(C`GV_NO_SVGMAGIC\*(C'\fR in the \f(CW\*(C`flags\*(C'\fR parameter |
| 9030 |
to \f(CW\*(C`gv_fetchsv\*(C'\fR makes it behave identically to \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR. |
| 9031 |
.RS 4 |
| 9032 |
.Sp |
| 9033 |
.Vb 9 |
| 9034 |
\& GV * gv_fetchpv (const char *nambeg, I32 flags, |
| 9035 |
\& const svtype sv_type) |
| 9036 |
\& GV * gv_fetchpvn (const char * nambeg, STRLEN full_len, |
| 9037 |
\& I32 flags, const svtype sv_type) |
| 9038 |
\& GV * gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags, |
| 9039 |
\& const svtype sv_type) |
| 9040 |
\& GV * gv_fetchpvs ("name", I32 flags, const svtype sv_type) |
| 9041 |
\& GV * gv_fetchsv (SV *name, I32 flags, const svtype sv_type) |
| 9042 |
\& GV * gv_fetchsv_nomg (SV *name, I32 flags, const svtype sv_type) |
| 9043 |
.Ve |
| 9044 |
.RE |
| 9045 |
.RS 4 |
| 9046 |
.RE |
| 9047 |
.ie n .IP """GvHV""" 4 |
| 9048 |
.el .IP \f(CWGvHV\fR 4 |
| 9049 |
.IX Xref "GvHV" |
| 9050 |
.IX Item "GvHV" |
| 9051 |
Return the HV from the GV. |
| 9052 |
.RS 4 |
| 9053 |
.Sp |
| 9054 |
.Vb 1 |
| 9055 |
\& HV* GvHV(GV* gv) |
| 9056 |
.Ve |
| 9057 |
.RE |
| 9058 |
.RS 4 |
| 9059 |
.RE |
| 9060 |
.ie n .IP """gv_init""" 4 |
| 9061 |
.el .IP \f(CWgv_init\fR 4 |
| 9062 |
.IX Xref "gv_init" |
| 9063 |
.IX Item "gv_init" |
| 9064 |
The old form of \f(CWgv_init_pvn()\fR. It does not work with UTF\-8 strings, as it |
| 9065 |
has no flags parameter. If the \f(CW\*(C`multi\*(C'\fR parameter is set, the |
| 9066 |
\&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag will be passed to \f(CWgv_init_pvn()\fR. |
| 9067 |
.RS 4 |
| 9068 |
.Sp |
| 9069 |
.Vb 2 |
| 9070 |
\& void gv_init(GV *gv, HV *stash, const char *name, STRLEN len, |
| 9071 |
\& int multi) |
| 9072 |
.Ve |
| 9073 |
.RE |
| 9074 |
.RS 4 |
| 9075 |
.RE |
| 9076 |
.ie n .IP """gv_init_pv""" 4 |
| 9077 |
.el .IP \f(CWgv_init_pv\fR 4 |
| 9078 |
.IX Xref "gv_init_pv" |
| 9079 |
.IX Item "gv_init_pv" |
| 9080 |
Same as \f(CWgv_init_pvn()\fR, but takes a nul-terminated string for the name |
| 9081 |
instead of separate char * and length parameters. |
| 9082 |
.RS 4 |
| 9083 |
.Sp |
| 9084 |
.Vb 1 |
| 9085 |
\& void gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags) |
| 9086 |
.Ve |
| 9087 |
.RE |
| 9088 |
.RS 4 |
| 9089 |
.RE |
| 9090 |
.ie n .IP """gv_init_pvn""" 4 |
| 9091 |
.el .IP \f(CWgv_init_pvn\fR 4 |
| 9092 |
.IX Xref "gv_init_pvn" |
| 9093 |
.IX Item "gv_init_pvn" |
| 9094 |
Converts a scalar into a typeglob. This is an incoercible typeglob; |
| 9095 |
assigning a reference to it will assign to one of its slots, instead of |
| 9096 |
overwriting it as happens with typeglobs created by \f(CW\*(C`SvSetSV\*(C'\fR. Converting |
| 9097 |
any scalar that is \f(CWSvOK()\fR may produce unpredictable results and is reserved |
| 9098 |
for perl's internal use. |
| 9099 |
.Sp |
| 9100 |
\&\f(CW\*(C`gv\*(C'\fR is the scalar to be converted. |
| 9101 |
.Sp |
| 9102 |
\&\f(CW\*(C`stash\*(C'\fR is the parent stash/package, if any. |
| 9103 |
.Sp |
| 9104 |
\&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`len\*(C'\fR give the name. The name must be unqualified; |
| 9105 |
that is, it must not include the package name. If \f(CW\*(C`gv\*(C'\fR is a |
| 9106 |
stash element, it is the caller's responsibility to ensure that the name |
| 9107 |
passed to this function matches the name of the element. If it does not |
| 9108 |
match, perl's internal bookkeeping will get out of sync. |
| 9109 |
.Sp |
| 9110 |
\&\f(CW\*(C`flags\*(C'\fR can be set to \f(CW\*(C`SVf_UTF8\*(C'\fR if \f(CW\*(C`name\*(C'\fR is a UTF\-8 string, or |
| 9111 |
the return value of SvUTF8(sv). It can also take the |
| 9112 |
\&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag, which means to pretend that the GV has been |
| 9113 |
seen before (i.e., suppress "Used once" warnings). |
| 9114 |
.RS 4 |
| 9115 |
.Sp |
| 9116 |
.Vb 2 |
| 9117 |
\& void gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len, |
| 9118 |
\& U32 flags) |
| 9119 |
.Ve |
| 9120 |
.RE |
| 9121 |
.RS 4 |
| 9122 |
.RE |
| 9123 |
.ie n .IP """gv_init_sv""" 4 |
| 9124 |
.el .IP \f(CWgv_init_sv\fR 4 |
| 9125 |
.IX Xref "gv_init_sv" |
| 9126 |
.IX Item "gv_init_sv" |
| 9127 |
Same as \f(CWgv_init_pvn()\fR, but takes an SV * for the name instead of separate |
| 9128 |
char * and length parameters. \f(CW\*(C`flags\*(C'\fR is currently unused. |
| 9129 |
.RS 4 |
| 9130 |
.Sp |
| 9131 |
.Vb 1 |
| 9132 |
\& void gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags) |
| 9133 |
.Ve |
| 9134 |
.RE |
| 9135 |
.RS 4 |
| 9136 |
.RE |
| 9137 |
.ie n .IP """gv_name_set""" 4 |
| 9138 |
.el .IP \f(CWgv_name_set\fR 4 |
| 9139 |
.IX Xref "gv_name_set" |
| 9140 |
.IX Item "gv_name_set" |
| 9141 |
Set the name for GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`name\*(C'\fR which is \f(CW\*(C`len\*(C'\fR bytes long. Thus it may |
| 9142 |
contain embedded NUL characters. |
| 9143 |
.Sp |
| 9144 |
If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SVf_UTF8\*(C'\fR, the name is treated as being encoded in |
| 9145 |
UTF\-8; otherwise not. |
| 9146 |
.RS 4 |
| 9147 |
.Sp |
| 9148 |
.Vb 1 |
| 9149 |
\& void gv_name_set(GV *gv, const char *name, U32 len, U32 flags) |
| 9150 |
.Ve |
| 9151 |
.RE |
| 9152 |
.RS 4 |
| 9153 |
.RE |
| 9154 |
.ie n .IP """gv_stashpv""" 4 |
| 9155 |
.el .IP \f(CWgv_stashpv\fR 4 |
| 9156 |
.IX Xref "gv_stashpv" |
| 9157 |
.IX Item "gv_stashpv" |
| 9158 |
Returns a pointer to the stash for a specified package. Uses \f(CW\*(C`strlen\*(C'\fR to |
| 9159 |
determine the length of \f(CW\*(C`name\*(C'\fR, then calls \f(CWgv_stashpvn()\fR. |
| 9160 |
.RS 4 |
| 9161 |
.Sp |
| 9162 |
.Vb 1 |
| 9163 |
\& HV * gv_stashpv(const char *name, I32 flags) |
| 9164 |
.Ve |
| 9165 |
.RE |
| 9166 |
.RS 4 |
| 9167 |
.RE |
| 9168 |
.ie n .IP """gv_stashpvn""" 4 |
| 9169 |
.el .IP \f(CWgv_stashpvn\fR 4 |
| 9170 |
.IX Xref "gv_stashpvn" |
| 9171 |
.IX Item "gv_stashpvn" |
| 9172 |
Returns a pointer to the stash for a specified package. The \f(CW\*(C`namelen\*(C'\fR |
| 9173 |
parameter indicates the length of the \f(CW\*(C`name\*(C'\fR, in bytes. \f(CW\*(C`flags\*(C'\fR is passed |
| 9174 |
to \f(CWgv_fetchpvn_flags()\fR, so if set to \f(CW\*(C`GV_ADD\*(C'\fR then the package will be |
| 9175 |
created if it does not already exist. If the package does not exist and |
| 9176 |
\&\f(CW\*(C`flags\*(C'\fR is 0 (or any other setting that does not create packages) then \f(CW\*(C`NULL\*(C'\fR |
| 9177 |
is returned. |
| 9178 |
.Sp |
| 9179 |
Flags may be one of: |
| 9180 |
.Sp |
| 9181 |
.Vb 7 |
| 9182 |
\& GV_ADD Create and initialize the package if doesn\*(Aqt |
| 9183 |
\& already exist |
| 9184 |
\& GV_NOADD_NOINIT Don\*(Aqt create the package, |
| 9185 |
\& GV_ADDMG GV_ADD iff the GV is magical |
| 9186 |
\& GV_NOINIT GV_ADD, but don\*(Aqt initialize |
| 9187 |
\& GV_NOEXPAND Don\*(Aqt expand SvOK() entries to PVGV |
| 9188 |
\& SVf_UTF8 The name is in UTF\-8 |
| 9189 |
.Ve |
| 9190 |
.Sp |
| 9191 |
The most important of which are probably \f(CW\*(C`GV_ADD\*(C'\fR and \f(CW\*(C`SVf_UTF8\*(C'\fR. |
| 9192 |
.Sp |
| 9193 |
Note, use of \f(CW\*(C`gv_stashsv\*(C'\fR instead of \f(CW\*(C`gv_stashpvn\*(C'\fR where possible is strongly |
| 9194 |
recommended for performance reasons. |
| 9195 |
.RS 4 |
| 9196 |
.Sp |
| 9197 |
.Vb 1 |
| 9198 |
\& HV * gv_stashpvn(const char *name, U32 namelen, I32 flags) |
| 9199 |
.Ve |
| 9200 |
.RE |
| 9201 |
.RS 4 |
| 9202 |
.RE |
| 9203 |
.ie n .IP """gv_stashpvs""" 4 |
| 9204 |
.el .IP \f(CWgv_stashpvs\fR 4 |
| 9205 |
.IX Xref "gv_stashpvs" |
| 9206 |
.IX Item "gv_stashpvs" |
| 9207 |
Like \f(CW\*(C`gv_stashpvn\*(C'\fR, but takes a literal string instead of a |
| 9208 |
string/length pair. |
| 9209 |
.RS 4 |
| 9210 |
.Sp |
| 9211 |
.Vb 1 |
| 9212 |
\& HV* gv_stashpvs("name", I32 create) |
| 9213 |
.Ve |
| 9214 |
.RE |
| 9215 |
.RS 4 |
| 9216 |
.RE |
| 9217 |
.ie n .IP """gv_stashsv""" 4 |
| 9218 |
.el .IP \f(CWgv_stashsv\fR 4 |
| 9219 |
.IX Xref "gv_stashsv" |
| 9220 |
.IX Item "gv_stashsv" |
| 9221 |
Returns a pointer to the stash for a specified package. See |
| 9222 |
\&\f(CW"gv_stashpvn"\fR. |
| 9223 |
.Sp |
| 9224 |
Note this interface is strongly preferred over \f(CW\*(C`gv_stashpvn\*(C'\fR for performance |
| 9225 |
reasons. |
| 9226 |
.RS 4 |
| 9227 |
.Sp |
| 9228 |
.Vb 1 |
| 9229 |
\& HV * gv_stashsv(SV *sv, I32 flags) |
| 9230 |
.Ve |
| 9231 |
.RE |
| 9232 |
.RS 4 |
| 9233 |
.RE |
| 9234 |
.ie n .IP """GvSV""" 4 |
| 9235 |
.el .IP \f(CWGvSV\fR 4 |
| 9236 |
.IX Xref "GvSV" |
| 9237 |
.IX Item "GvSV" |
| 9238 |
Return the SV from the GV. |
| 9239 |
.Sp |
| 9240 |
Prior to Perl v5.9.3, this would add a scalar if none existed. Nowadays, use |
| 9241 |
\&\f(CW"GvSVn"\fR for that, or compile perl with \f(CW\*(C`\-DPERL_CREATE_GVSV\*(C'\fR. See |
| 9242 |
perl5100delta. |
| 9243 |
.RS 4 |
| 9244 |
.Sp |
| 9245 |
.Vb 1 |
| 9246 |
\& SV* GvSV(GV* gv) |
| 9247 |
.Ve |
| 9248 |
.RE |
| 9249 |
.RS 4 |
| 9250 |
.RE |
| 9251 |
.ie n .IP """GvSVn""" 4 |
| 9252 |
.el .IP \f(CWGvSVn\fR 4 |
| 9253 |
.IX Xref "GvSVn" |
| 9254 |
.IX Item "GvSVn" |
| 9255 |
Like \f(CW"GvSV"\fR, but creates an empty scalar if none already exists. |
| 9256 |
.RS 4 |
| 9257 |
.Sp |
| 9258 |
.Vb 1 |
| 9259 |
\& SV* GvSVn(GV* gv) |
| 9260 |
.Ve |
| 9261 |
.RE |
| 9262 |
.RS 4 |
| 9263 |
.RE |
| 9264 |
.ie n .IP """newGVgen""" 4 |
| 9265 |
.el .IP \f(CWnewGVgen\fR 4 |
| 9266 |
.IX Item "newGVgen" |
| 9267 |
.PD 0 |
| 9268 |
.ie n .IP """newGVgen_flags""" 4 |
| 9269 |
.el .IP \f(CWnewGVgen_flags\fR 4 |
| 9270 |
.IX Xref "newGVgen newGVgen_flags" |
| 9271 |
.IX Item "newGVgen_flags" |
| 9272 |
.PD |
| 9273 |
Create a new, guaranteed to be unique, GV in the package given by the |
| 9274 |
NUL-terminated C language string \f(CW\*(C`pack\*(C'\fR, and return a pointer to it. |
| 9275 |
.Sp |
| 9276 |
For \f(CW\*(C`newGVgen\*(C'\fR or if \f(CW\*(C`flags\*(C'\fR in \f(CW\*(C`newGVgen_flags\*(C'\fR is 0, \f(CW\*(C`pack\*(C'\fR is to be |
| 9277 |
considered to be encoded in Latin\-1. The only other legal \f(CW\*(C`flags\*(C'\fR value is |
| 9278 |
\&\f(CW\*(C`SVf_UTF8\*(C'\fR, which indicates \f(CW\*(C`pack\*(C'\fR is to be considered to be encoded in |
| 9279 |
UTF\-8. |
| 9280 |
.RS 4 |
| 9281 |
.Sp |
| 9282 |
.Vb 2 |
| 9283 |
\& GV * newGVgen (const char *pack) |
| 9284 |
\& GV * newGVgen_flags(const char *pack, U32 flags) |
| 9285 |
.Ve |
| 9286 |
.RE |
| 9287 |
.RS 4 |
| 9288 |
.RE |
| 9289 |
.ie n .IP """PL_curstash""" 4 |
| 9290 |
.el .IP \f(CWPL_curstash\fR 4 |
| 9291 |
.IX Xref "PL_curstash" |
| 9292 |
.IX Item "PL_curstash" |
| 9293 |
The stash for the package code will be compiled into. |
| 9294 |
.Sp |
| 9295 |
On threaded perls, each thread has an independent copy of this variable; |
| 9296 |
each initialized at creation time with the current value of the creating |
| 9297 |
thread's copy. |
| 9298 |
.RS 4 |
| 9299 |
.Sp |
| 9300 |
.Vb 1 |
| 9301 |
\& HV* PL_curstash |
| 9302 |
.Ve |
| 9303 |
.RE |
| 9304 |
.RS 4 |
| 9305 |
.RE |
| 9306 |
.ie n .IP """PL_defgv""" 4 |
| 9307 |
.el .IP \f(CWPL_defgv\fR 4 |
| 9308 |
.IX Xref "PL_defgv" |
| 9309 |
.IX Item "PL_defgv" |
| 9310 |
The GV representing \f(CW*_\fR. Useful for access to \f(CW$_\fR. |
| 9311 |
.Sp |
| 9312 |
On threaded perls, each thread has an independent copy of this variable; |
| 9313 |
each initialized at creation time with the current value of the creating |
| 9314 |
thread's copy. |
| 9315 |
.RS 4 |
| 9316 |
.Sp |
| 9317 |
.Vb 1 |
| 9318 |
\& GV * PL_defgv |
| 9319 |
.Ve |
| 9320 |
.RE |
| 9321 |
.RS 4 |
| 9322 |
.RE |
| 9323 |
.ie n .IP """PL_defoutgv""" 4 |
| 9324 |
.el .IP \f(CWPL_defoutgv\fR 4 |
| 9325 |
.IX Xref "PL_defoutgv" |
| 9326 |
.IX Item "PL_defoutgv" |
| 9327 |
See \f(CW"setdefout"\fR. |
| 9328 |
.ie n .IP """PL_defstash""" 4 |
| 9329 |
.el .IP \f(CWPL_defstash\fR 4 |
| 9330 |
.IX Item "PL_defstash" |
| 9331 |
Described in perlguts. |
| 9332 |
.ie n .IP """save_gp""" 4 |
| 9333 |
.el .IP \f(CWsave_gp\fR 4 |
| 9334 |
.IX Xref "save_gp" |
| 9335 |
.IX Item "save_gp" |
| 9336 |
Saves the current GP of gv on the save stack to be restored on scope exit. |
| 9337 |
.Sp |
| 9338 |
If \f(CW\*(C`empty\*(C'\fR is true, replace the GP with a new GP. |
| 9339 |
.Sp |
| 9340 |
If \f(CW\*(C`empty\*(C'\fR is false, mark \f(CW\*(C`gv\*(C'\fR with \f(CW\*(C`GVf_INTRO\*(C'\fR so the next reference |
| 9341 |
assigned is localized, which is how \f(CW\*(C`\ local\ *foo\ =\ $someref;\ \*(C'\fR works. |
| 9342 |
.RS 4 |
| 9343 |
.Sp |
| 9344 |
.Vb 1 |
| 9345 |
\& void save_gp(GV *gv, I32 empty) |
| 9346 |
.Ve |
| 9347 |
.RE |
| 9348 |
.RS 4 |
| 9349 |
.RE |
| 9350 |
.ie n .IP """setdefout""" 4 |
| 9351 |
.el .IP \f(CWsetdefout\fR 4 |
| 9352 |
.IX Xref "setdefout" |
| 9353 |
.IX Item "setdefout" |
| 9354 |
Sets \f(CW\*(C`PL_defoutgv\*(C'\fR, the default file handle for output, to the passed in |
| 9355 |
typeglob. As \f(CW\*(C`PL_defoutgv\*(C'\fR "owns" a reference on its typeglob, the reference |
| 9356 |
count of the passed in typeglob is increased by one, and the reference count |
| 9357 |
of the typeglob that \f(CW\*(C`PL_defoutgv\*(C'\fR points to is decreased by one. |
| 9358 |
.RS 4 |
| 9359 |
.Sp |
| 9360 |
.Vb 1 |
| 9361 |
\& void setdefout(GV *gv) |
| 9362 |
.Ve |
| 9363 |
.RE |
| 9364 |
.RS 4 |
| 9365 |
.RE |
| 9366 |
.SH "Hook manipulation" |
| 9367 |
.IX Header "Hook manipulation" |
| 9368 |
These functions provide convenient and thread-safe means of manipulating |
| 9369 |
hook variables. |
| 9370 |
.ie n .IP """rcpv_copy""" 4 |
| 9371 |
.el .IP \f(CWrcpv_copy\fR 4 |
| 9372 |
.IX Xref "rcpv_copy" |
| 9373 |
.IX Item "rcpv_copy" |
| 9374 |
refcount increment a shared memory refcounted string, and when |
| 9375 |
the refcount goes to 0 free it using \fBPerlMemShared_free()\fR. |
| 9376 |
.Sp |
| 9377 |
It is the callers responsibility to ensure that the pv is the |
| 9378 |
result of a \fBrcpv_new()\fR call. |
| 9379 |
.Sp |
| 9380 |
Returns the same pointer that was passed in. |
| 9381 |
.Sp |
| 9382 |
.Vb 1 |
| 9383 |
\& new = rcpv_copy(pv); |
| 9384 |
.Ve |
| 9385 |
.RS 4 |
| 9386 |
.Sp |
| 9387 |
.Vb 1 |
| 9388 |
\& char * rcpv_copy(char * const pv) |
| 9389 |
.Ve |
| 9390 |
.RE |
| 9391 |
.RS 4 |
| 9392 |
.RE |
| 9393 |
.ie n .IP """rcpv_free""" 4 |
| 9394 |
.el .IP \f(CWrcpv_free\fR 4 |
| 9395 |
.IX Xref "rcpv_free" |
| 9396 |
.IX Item "rcpv_free" |
| 9397 |
refcount decrement a shared memory refcounted string, and when |
| 9398 |
the refcount goes to 0 free it using \fBperlmemshared_free()\fR. |
| 9399 |
.Sp |
| 9400 |
it is the callers responsibility to ensure that the pv is the |
| 9401 |
result of a \fBrcpv_new()\fR call. |
| 9402 |
.Sp |
| 9403 |
Always returns NULL so it can be used like this: |
| 9404 |
.Sp |
| 9405 |
.Vb 1 |
| 9406 |
\& thing = rcpv_free(thing); |
| 9407 |
.Ve |
| 9408 |
.RS 4 |
| 9409 |
.Sp |
| 9410 |
.Vb 1 |
| 9411 |
\& char * rcpv_free(char * const pv) |
| 9412 |
.Ve |
| 9413 |
.RE |
| 9414 |
.RS 4 |
| 9415 |
.RE |
| 9416 |
.ie n .IP """rcpv_new""" 4 |
| 9417 |
.el .IP \f(CWrcpv_new\fR 4 |
| 9418 |
.IX Xref "rcpv_new" |
| 9419 |
.IX Item "rcpv_new" |
| 9420 |
Create a new shared memory refcounted string with the requested size, and |
| 9421 |
with the requested initialization and a refcount of 1. The actual space |
| 9422 |
allocated will be 1 byte more than requested and \fBrcpv_new()\fR will ensure that |
| 9423 |
the extra byte is a null regardless of any flags settings. |
| 9424 |
.Sp |
| 9425 |
If the RCPVf_NO_COPY flag is set then the pv argument will be |
| 9426 |
ignored, otherwise the contents of the pv pointer will be copied into |
| 9427 |
the new buffer or if it is NULL the function will do nothing and return NULL. |
| 9428 |
.Sp |
| 9429 |
If the RCPVf_USE_STRLEN flag is set then the len argument is ignored and |
| 9430 |
recomputed using \f(CWstrlen(pv)\fR. It is an error to combine RCPVf_USE_STRLEN |
| 9431 |
and RCPVf_NO_COPY at the same time. |
| 9432 |
.Sp |
| 9433 |
Under DEBUGGING \fBrcpv_new()\fR will \fBassert()\fR if it is asked to create a 0 length |
| 9434 |
shared string unless the RCPVf_ALLOW_EMPTY flag is set. |
| 9435 |
.Sp |
| 9436 |
The return value from the function is suitable for passing into \fBrcpv_copy()\fR and |
| 9437 |
\&\fBrcpv_free()\fR. To access the RCPV * from the returned value use the \fBRCPVx()\fR macro. |
| 9438 |
The 'len' member of the RCPV struct stores the allocated length (including the |
| 9439 |
extra byte), but the \fBRCPV_LEN()\fR macro returns the requested length (not |
| 9440 |
including the extra byte). |
| 9441 |
.Sp |
| 9442 |
Note that \fBrcpv_new()\fR does NOT use a hash table or anything like that to |
| 9443 |
dedupe inputs given the same text content. Each call with a non-null pv |
| 9444 |
parameter will produce a distinct pointer with its own refcount regardless of |
| 9445 |
the input content. |
| 9446 |
.RS 4 |
| 9447 |
.Sp |
| 9448 |
.Vb 1 |
| 9449 |
\& char * rcpv_new(const char * const pv, STRLEN len, U32 flags) |
| 9450 |
.Ve |
| 9451 |
.RE |
| 9452 |
.RS 4 |
| 9453 |
.RE |
| 9454 |
.ie n .IP """wrap_op_checker""" 4 |
| 9455 |
.el .IP \f(CWwrap_op_checker\fR 4 |
| 9456 |
.IX Xref "wrap_op_checker" |
| 9457 |
.IX Item "wrap_op_checker" |
| 9458 |
Puts a C function into the chain of check functions for a specified op |
| 9459 |
type. This is the preferred way to manipulate the "PL_check" array. |
| 9460 |
\&\f(CW\*(C`opcode\*(C'\fR specifies which type of op is to be affected. \f(CW\*(C`new_checker\*(C'\fR |
| 9461 |
is a pointer to the C function that is to be added to that opcode's |
| 9462 |
check chain, and \f(CW\*(C`old_checker_p\*(C'\fR points to the storage location where a |
| 9463 |
pointer to the next function in the chain will be stored. The value of |
| 9464 |
\&\f(CW\*(C`new_checker\*(C'\fR is written into the "PL_check" array, while the value |
| 9465 |
previously stored there is written to \f(CW*old_checker_p\fR. |
| 9466 |
.Sp |
| 9467 |
"PL_check" is global to an entire process, and a module wishing to |
| 9468 |
hook op checking may find itself invoked more than once per process, |
| 9469 |
typically in different threads. To handle that situation, this function |
| 9470 |
is idempotent. The location \f(CW*old_checker_p\fR must initially (once |
| 9471 |
per process) contain a null pointer. A C variable of static duration |
| 9472 |
(declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give |
| 9473 |
it internal linkage) will be implicitly initialised appropriately, |
| 9474 |
if it does not have an explicit initialiser. This function will only |
| 9475 |
actually modify the check chain if it finds \f(CW*old_checker_p\fR to be null. |
| 9476 |
This function is also thread safe on the small scale. It uses appropriate |
| 9477 |
locking to avoid race conditions in accessing "PL_check". |
| 9478 |
.Sp |
| 9479 |
When this function is called, the function referenced by \f(CW\*(C`new_checker\*(C'\fR |
| 9480 |
must be ready to be called, except for \f(CW*old_checker_p\fR being unfilled. |
| 9481 |
In a threading situation, \f(CW\*(C`new_checker\*(C'\fR may be called immediately, |
| 9482 |
even before this function has returned. \f(CW*old_checker_p\fR will always |
| 9483 |
be appropriately set before \f(CW\*(C`new_checker\*(C'\fR is called. If \f(CW\*(C`new_checker\*(C'\fR |
| 9484 |
decides not to do anything special with an op that it is given (which |
| 9485 |
is the usual case for most uses of op check hooking), it must chain the |
| 9486 |
check function referenced by \f(CW*old_checker_p\fR. |
| 9487 |
.Sp |
| 9488 |
Taken all together, XS code to hook an op checker should typically look |
| 9489 |
something like this: |
| 9490 |
.Sp |
| 9491 |
.Vb 9 |
| 9492 |
\& static Perl_check_t nxck_frob; |
| 9493 |
\& static OP *myck_frob(pTHX_ OP *op) { |
| 9494 |
\& ... |
| 9495 |
\& op = nxck_frob(aTHX_ op); |
| 9496 |
\& ... |
| 9497 |
\& return op; |
| 9498 |
\& } |
| 9499 |
\& BOOT: |
| 9500 |
\& wrap_op_checker(OP_FROB, myck_frob, &nxck_frob); |
| 9501 |
.Ve |
| 9502 |
.Sp |
| 9503 |
If you want to influence compilation of calls to a specific subroutine, |
| 9504 |
then use "cv_set_call_checker_flags" rather than hooking checking of |
| 9505 |
all \f(CW\*(C`entersub\*(C'\fR ops. |
| 9506 |
.RS 4 |
| 9507 |
.Sp |
| 9508 |
.Vb 2 |
| 9509 |
\& void wrap_op_checker(Optype opcode, Perl_check_t new_checker, |
| 9510 |
\& Perl_check_t *old_checker_p) |
| 9511 |
.Ve |
| 9512 |
.RE |
| 9513 |
.RS 4 |
| 9514 |
.RE |
| 9515 |
.SH "HV Handling" |
| 9516 |
.IX Xref "HV_ITERNEXT_WANTPLACEHOLDERS HV_NAME_SETALL HvNAMELEN_get" |
| 9517 |
.IX Header "HV Handling" |
| 9518 |
A HV structure represents a Perl hash. It consists mainly of an array |
| 9519 |
of pointers, each of which points to a linked list of HE structures. The |
| 9520 |
array is indexed by the hash function of the key, so each linked list |
| 9521 |
represents all the hash entries with the same hash value. Each HE contains |
| 9522 |
a pointer to the actual value, plus a pointer to a HEK structure which |
| 9523 |
holds the key and hash value. |
| 9524 |
.ie n .IP """get_hv""" 4 |
| 9525 |
.el .IP \f(CWget_hv\fR 4 |
| 9526 |
.IX Xref "get_hv" |
| 9527 |
.IX Item "get_hv" |
| 9528 |
Returns the HV of the specified Perl hash. \f(CW\*(C`flags\*(C'\fR are passed to |
| 9529 |
\&\f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the |
| 9530 |
Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero |
| 9531 |
(ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is |
| 9532 |
returned. |
| 9533 |
.Sp |
| 9534 |
NOTE: the \f(CWperl_get_hv()\fR form is \fBdeprecated\fR. |
| 9535 |
.RS 4 |
| 9536 |
.Sp |
| 9537 |
.Vb 1 |
| 9538 |
\& HV * get_hv(const char *name, I32 flags) |
| 9539 |
.Ve |
| 9540 |
.RE |
| 9541 |
.RS 4 |
| 9542 |
.RE |
| 9543 |
.ie n .IP """HE""" 4 |
| 9544 |
.el .IP \f(CWHE\fR 4 |
| 9545 |
.IX Item "HE" |
| 9546 |
Described in perlguts. |
| 9547 |
.ie n .IP """HEf_SVKEY""" 4 |
| 9548 |
.el .IP \f(CWHEf_SVKEY\fR 4 |
| 9549 |
.IX Xref "HEf_SVKEY" |
| 9550 |
.IX Item "HEf_SVKEY" |
| 9551 |
This flag, used in the length slot of hash entries and magic structures, |
| 9552 |
specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer |
| 9553 |
is to be expected. (For information only\-\-not to be used). |
| 9554 |
.ie n .IP """HeHASH""" 4 |
| 9555 |
.el .IP \f(CWHeHASH\fR 4 |
| 9556 |
.IX Xref "HeHASH" |
| 9557 |
.IX Item "HeHASH" |
| 9558 |
Returns the computed hash stored in the hash entry. |
| 9559 |
.RS 4 |
| 9560 |
.Sp |
| 9561 |
.Vb 1 |
| 9562 |
\& U32 HeHASH(HE* he) |
| 9563 |
.Ve |
| 9564 |
.RE |
| 9565 |
.RS 4 |
| 9566 |
.RE |
| 9567 |
.ie n .IP """HeKEY""" 4 |
| 9568 |
.el .IP \f(CWHeKEY\fR 4 |
| 9569 |
.IX Xref "HeKEY" |
| 9570 |
.IX Item "HeKEY" |
| 9571 |
Returns the actual pointer stored in the key slot of the hash entry. The |
| 9572 |
pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of |
| 9573 |
\&\f(CWHeKLEN()\fR. Can be assigned to. The \f(CWHePV()\fR or \f(CWHeSVKEY()\fR macros are |
| 9574 |
usually preferable for finding the value of a key. |
| 9575 |
.RS 4 |
| 9576 |
.Sp |
| 9577 |
.Vb 1 |
| 9578 |
\& void* HeKEY(HE* he) |
| 9579 |
.Ve |
| 9580 |
.RE |
| 9581 |
.RS 4 |
| 9582 |
.RE |
| 9583 |
.ie n .IP """HeKLEN""" 4 |
| 9584 |
.el .IP \f(CWHeKLEN\fR 4 |
| 9585 |
.IX Xref "HeKLEN" |
| 9586 |
.IX Item "HeKLEN" |
| 9587 |
If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry |
| 9588 |
holds an \f(CW\*(C`SV*\*(C'\fR key. Otherwise, holds the actual length of the key. Can |
| 9589 |
be assigned to. The \f(CWHePV()\fR macro is usually preferable for finding key |
| 9590 |
lengths. |
| 9591 |
.RS 4 |
| 9592 |
.Sp |
| 9593 |
.Vb 1 |
| 9594 |
\& STRLEN HeKLEN(HE* he) |
| 9595 |
.Ve |
| 9596 |
.RE |
| 9597 |
.RS 4 |
| 9598 |
.RE |
| 9599 |
.ie n .IP """HePV""" 4 |
| 9600 |
.el .IP \f(CWHePV\fR 4 |
| 9601 |
.IX Xref "HePV" |
| 9602 |
.IX Item "HePV" |
| 9603 |
Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any |
| 9604 |
necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The length of the string |
| 9605 |
is placed in \f(CW\*(C`len\*(C'\fR (this is a macro, so do \fInot\fR use \f(CW&len\fR). If you do |
| 9606 |
not care about what the length of the key is, you may use the global |
| 9607 |
variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local |
| 9608 |
variable. Remember though, that hash keys in perl are free to contain |
| 9609 |
embedded nulls, so using \f(CWstrlen()\fR or similar is not a good way to find |
| 9610 |
the length of hash keys. This is very similar to the \f(CWSvPV()\fR macro |
| 9611 |
described elsewhere in this document. See also \f(CW"HeUTF8"\fR. |
| 9612 |
.Sp |
| 9613 |
If you are using \f(CW\*(C`HePV\*(C'\fR to get values to pass to \f(CWnewSVpvn()\fR to create a |
| 9614 |
new SV, you should consider using \f(CW\*(C`newSVhek(HeKEY_hek(he))\*(C'\fR as it is more |
| 9615 |
efficient. |
| 9616 |
.RS 4 |
| 9617 |
.Sp |
| 9618 |
.Vb 1 |
| 9619 |
\& char* HePV(HE* he, STRLEN len) |
| 9620 |
.Ve |
| 9621 |
.RE |
| 9622 |
.RS 4 |
| 9623 |
.RE |
| 9624 |
.ie n .IP """HeSVKEY""" 4 |
| 9625 |
.el .IP \f(CWHeSVKEY\fR 4 |
| 9626 |
.IX Xref "HeSVKEY" |
| 9627 |
.IX Item "HeSVKEY" |
| 9628 |
Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if the hash entry does not |
| 9629 |
contain an \f(CW\*(C`SV*\*(C'\fR key. |
| 9630 |
.RS 4 |
| 9631 |
.Sp |
| 9632 |
.Vb 1 |
| 9633 |
\& SV* HeSVKEY(HE* he) |
| 9634 |
.Ve |
| 9635 |
.RE |
| 9636 |
.RS 4 |
| 9637 |
.RE |
| 9638 |
.ie n .IP """HeSVKEY_force""" 4 |
| 9639 |
.el .IP \f(CWHeSVKEY_force\fR 4 |
| 9640 |
.IX Xref "HeSVKEY_force" |
| 9641 |
.IX Item "HeSVKEY_force" |
| 9642 |
Returns the key as an \f(CW\*(C`SV*\*(C'\fR. Will create and return a temporary mortal |
| 9643 |
\&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key. |
| 9644 |
.RS 4 |
| 9645 |
.Sp |
| 9646 |
.Vb 1 |
| 9647 |
\& SV* HeSVKEY_force(HE* he) |
| 9648 |
.Ve |
| 9649 |
.RE |
| 9650 |
.RS 4 |
| 9651 |
.RE |
| 9652 |
.ie n .IP """HeSVKEY_set""" 4 |
| 9653 |
.el .IP \f(CWHeSVKEY_set\fR 4 |
| 9654 |
.IX Xref "HeSVKEY_set" |
| 9655 |
.IX Item "HeSVKEY_set" |
| 9656 |
Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to |
| 9657 |
indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same |
| 9658 |
\&\f(CW\*(C`SV*\*(C'\fR. |
| 9659 |
.RS 4 |
| 9660 |
.Sp |
| 9661 |
.Vb 1 |
| 9662 |
\& SV* HeSVKEY_set(HE* he, SV* sv) |
| 9663 |
.Ve |
| 9664 |
.RE |
| 9665 |
.RS 4 |
| 9666 |
.RE |
| 9667 |
.ie n .IP """HeUTF8""" 4 |
| 9668 |
.el .IP \f(CWHeUTF8\fR 4 |
| 9669 |
.IX Xref "HeUTF8" |
| 9670 |
.IX Item "HeUTF8" |
| 9671 |
Returns whether the \f(CW\*(C`char *\*(C'\fR value returned by \f(CW\*(C`HePV\*(C'\fR is encoded in UTF\-8, |
| 9672 |
doing any necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The value returned |
| 9673 |
will be 0 or non\-0, not necessarily 1 (or even a value with any low bits set), |
| 9674 |
so \fBdo not\fR blindly assign this to a \f(CW\*(C`bool\*(C'\fR variable, as \f(CW\*(C`bool\*(C'\fR may be a |
| 9675 |
typedef for \f(CW\*(C`char\*(C'\fR. |
| 9676 |
.RS 4 |
| 9677 |
.Sp |
| 9678 |
.Vb 1 |
| 9679 |
\& U32 HeUTF8(HE* he) |
| 9680 |
.Ve |
| 9681 |
.RE |
| 9682 |
.RS 4 |
| 9683 |
.RE |
| 9684 |
.ie n .IP """HeVAL""" 4 |
| 9685 |
.el .IP \f(CWHeVAL\fR 4 |
| 9686 |
.IX Xref "HeVAL" |
| 9687 |
.IX Item "HeVAL" |
| 9688 |
Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR) |
| 9689 |
stored in the hash entry. Can be assigned |
| 9690 |
to. |
| 9691 |
.Sp |
| 9692 |
.Vb 2 |
| 9693 |
\& SV *foo= HeVAL(hv); |
| 9694 |
\& HeVAL(hv)= sv; |
| 9695 |
.Ve |
| 9696 |
.RS 4 |
| 9697 |
.Sp |
| 9698 |
.Vb 1 |
| 9699 |
\& SV* HeVAL(HE* he) |
| 9700 |
.Ve |
| 9701 |
.RE |
| 9702 |
.RS 4 |
| 9703 |
.RE |
| 9704 |
.ie n .IP """HV""" 4 |
| 9705 |
.el .IP \f(CWHV\fR 4 |
| 9706 |
.IX Item "HV" |
| 9707 |
Described in perlguts. |
| 9708 |
.ie n .IP """hv_assert""" 4 |
| 9709 |
.el .IP \f(CWhv_assert\fR 4 |
| 9710 |
.IX Xref "hv_assert" |
| 9711 |
.IX Item "hv_assert" |
| 9712 |
Check that a hash is in an internally consistent state. |
| 9713 |
.Sp |
| 9714 |
NOTE: \f(CW\*(C`hv_assert\*(C'\fR must be explicitly called as |
| 9715 |
\&\f(CW\*(C`Perl_hv_assert\*(C'\fR |
| 9716 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 9717 |
.RS 4 |
| 9718 |
.Sp |
| 9719 |
.Vb 1 |
| 9720 |
\& void Perl_hv_assert(pTHX_ HV *hv) |
| 9721 |
.Ve |
| 9722 |
.RE |
| 9723 |
.RS 4 |
| 9724 |
.RE |
| 9725 |
.ie n .IP """hv_bucket_ratio""" 4 |
| 9726 |
.el .IP \f(CWhv_bucket_ratio\fR 4 |
| 9727 |
.IX Xref "hv_bucket_ratio" |
| 9728 |
.IX Item "hv_bucket_ratio" |
| 9729 |
NOTE: \f(CW\*(C`hv_bucket_ratio\*(C'\fR is \fBexperimental\fR and may change or be |
| 9730 |
removed without notice. |
| 9731 |
.Sp |
| 9732 |
If the hash is tied dispatches through to the SCALAR tied method, |
| 9733 |
otherwise if the hash contains no keys returns 0, otherwise returns |
| 9734 |
a mortal sv containing a string specifying the number of used buckets, |
| 9735 |
followed by a slash, followed by the number of available buckets. |
| 9736 |
.Sp |
| 9737 |
This function is expensive, it must scan all of the buckets |
| 9738 |
to determine which are used, and the count is NOT cached. |
| 9739 |
In a large hash this could be a lot of buckets. |
| 9740 |
.RS 4 |
| 9741 |
.Sp |
| 9742 |
.Vb 1 |
| 9743 |
\& SV * hv_bucket_ratio(HV *hv) |
| 9744 |
.Ve |
| 9745 |
.RE |
| 9746 |
.RS 4 |
| 9747 |
.RE |
| 9748 |
.ie n .IP """hv_clear""" 4 |
| 9749 |
.el .IP \f(CWhv_clear\fR 4 |
| 9750 |
.IX Xref "hv_clear" |
| 9751 |
.IX Item "hv_clear" |
| 9752 |
Frees all the elements of a hash, leaving it empty. |
| 9753 |
The XS equivalent of \f(CW\*(C`%hash = ()\*(C'\fR. See also "hv_undef". |
| 9754 |
.Sp |
| 9755 |
See "av_clear" for a note about the hash possibly being invalid on |
| 9756 |
return. |
| 9757 |
.RS 4 |
| 9758 |
.Sp |
| 9759 |
.Vb 1 |
| 9760 |
\& void hv_clear(HV *hv) |
| 9761 |
.Ve |
| 9762 |
.RE |
| 9763 |
.RS 4 |
| 9764 |
.RE |
| 9765 |
.ie n .IP """hv_clear_placeholders""" 4 |
| 9766 |
.el .IP \f(CWhv_clear_placeholders\fR 4 |
| 9767 |
.IX Xref "hv_clear_placeholders" |
| 9768 |
.IX Item "hv_clear_placeholders" |
| 9769 |
Clears any placeholders from a hash. If a restricted hash has any of its keys |
| 9770 |
marked as readonly and the key is subsequently deleted, the key is not actually |
| 9771 |
deleted but is marked by assigning it a value of \f(CW&PL_sv_placeholder\fR. This tags |
| 9772 |
it so it will be ignored by future operations such as iterating over the hash, |
| 9773 |
but will still allow the hash to have a value reassigned to the key at some |
| 9774 |
future point. This function clears any such placeholder keys from the hash. |
| 9775 |
See \f(CWHash::Util::lock_keys()\fR for an example of its |
| 9776 |
use. |
| 9777 |
.RS 4 |
| 9778 |
.Sp |
| 9779 |
.Vb 1 |
| 9780 |
\& void hv_clear_placeholders(HV *hv) |
| 9781 |
.Ve |
| 9782 |
.RE |
| 9783 |
.RS 4 |
| 9784 |
.RE |
| 9785 |
.ie n .IP """hv_copy_hints_hv""" 4 |
| 9786 |
.el .IP \f(CWhv_copy_hints_hv\fR 4 |
| 9787 |
.IX Xref "hv_copy_hints_hv" |
| 9788 |
.IX Item "hv_copy_hints_hv" |
| 9789 |
A specialised version of "newHVhv" for copying \f(CW\*(C`%^H\*(C'\fR. \f(CW\*(C`ohv\*(C'\fR must be |
| 9790 |
a pointer to a hash (which may have \f(CW\*(C`%^H\*(C'\fR magic, but should be generally |
| 9791 |
non-magical), or \f(CW\*(C`NULL\*(C'\fR (interpreted as an empty hash). The content |
| 9792 |
of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash, which has the \f(CW\*(C`%^H\*(C'\fR\-specific magic |
| 9793 |
added to it. A pointer to the new hash is returned. |
| 9794 |
.RS 4 |
| 9795 |
.Sp |
| 9796 |
.Vb 1 |
| 9797 |
\& HV * hv_copy_hints_hv(HV * const ohv) |
| 9798 |
.Ve |
| 9799 |
.RE |
| 9800 |
.RS 4 |
| 9801 |
.RE |
| 9802 |
.ie n .IP """hv_delete""" 4 |
| 9803 |
.el .IP \f(CWhv_delete\fR 4 |
| 9804 |
.IX Item "hv_delete" |
| 9805 |
.PD 0 |
| 9806 |
.ie n .IP """hv_deletes""" 4 |
| 9807 |
.el .IP \f(CWhv_deletes\fR 4 |
| 9808 |
.IX Xref "hv_delete hv_deletes" |
| 9809 |
.IX Item "hv_deletes" |
| 9810 |
.PD |
| 9811 |
These delete a key/value pair in the hash. The value's SV is removed from |
| 9812 |
the hash, made mortal, and returned to the caller. |
| 9813 |
.Sp |
| 9814 |
In \f(CW\*(C`hv_deletes\*(C'\fR, the key must be a C language string literal, enclosed in |
| 9815 |
double quotes. It is never treated as being in UTF\-8. There is no |
| 9816 |
length_parameter. |
| 9817 |
.Sp |
| 9818 |
In \f(CW\*(C`hv_delete\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If |
| 9819 |
\&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode. |
| 9820 |
.Sp |
| 9821 |
In both, the \f(CW\*(C`flags\*(C'\fR value will normally be zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then |
| 9822 |
\&\f(CW\*(C`NULL\*(C'\fR will be returned. \f(CW\*(C`NULL\*(C'\fR will also be returned if the key is not |
| 9823 |
found. |
| 9824 |
.RS 4 |
| 9825 |
.Sp |
| 9826 |
.Vb 2 |
| 9827 |
\& SV * hv_delete (HV *hv, const char *key, I32 klen, I32 flags) |
| 9828 |
\& SV * hv_deletes(HV *hv, "key", U32 flags) |
| 9829 |
.Ve |
| 9830 |
.RE |
| 9831 |
.RS 4 |
| 9832 |
.RE |
| 9833 |
.ie n .IP """hv_delete_ent""" 4 |
| 9834 |
.el .IP \f(CWhv_delete_ent\fR 4 |
| 9835 |
.IX Xref "hv_delete_ent" |
| 9836 |
.IX Item "hv_delete_ent" |
| 9837 |
Deletes a key/value pair in the hash. The value SV is removed from the hash, |
| 9838 |
made mortal, and returned to the caller. The \f(CW\*(C`flags\*(C'\fR value will normally be |
| 9839 |
zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then \f(CW\*(C`NULL\*(C'\fR will be returned. \f(CW\*(C`NULL\*(C'\fR will also |
| 9840 |
be returned if the key is not found. \f(CW\*(C`hash\*(C'\fR can be a valid precomputed hash |
| 9841 |
value, or 0 to ask for it to be computed. |
| 9842 |
.RS 4 |
| 9843 |
.Sp |
| 9844 |
.Vb 1 |
| 9845 |
\& SV * hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash) |
| 9846 |
.Ve |
| 9847 |
.RE |
| 9848 |
.RS 4 |
| 9849 |
.RE |
| 9850 |
.ie n .IP """HvENAME""" 4 |
| 9851 |
.el .IP \f(CWHvENAME\fR 4 |
| 9852 |
.IX Xref "HvENAME" |
| 9853 |
.IX Item "HvENAME" |
| 9854 |
Returns the effective name of a stash, or NULL if there is none. The |
| 9855 |
effective name represents a location in the symbol table where this stash |
| 9856 |
resides. It is updated automatically when packages are aliased or deleted. |
| 9857 |
A stash that is no longer in the symbol table has no effective name. This |
| 9858 |
name is preferable to \f(CW\*(C`HvNAME\*(C'\fR for use in MRO linearisations and isa |
| 9859 |
caches. |
| 9860 |
.RS 4 |
| 9861 |
.Sp |
| 9862 |
.Vb 1 |
| 9863 |
\& char* HvENAME(HV* stash) |
| 9864 |
.Ve |
| 9865 |
.RE |
| 9866 |
.RS 4 |
| 9867 |
.RE |
| 9868 |
.ie n .IP """HvENAMELEN""" 4 |
| 9869 |
.el .IP \f(CWHvENAMELEN\fR 4 |
| 9870 |
.IX Xref "HvENAMELEN" |
| 9871 |
.IX Item "HvENAMELEN" |
| 9872 |
Returns the length of the stash's effective name. |
| 9873 |
.RS 4 |
| 9874 |
.Sp |
| 9875 |
.Vb 1 |
| 9876 |
\& STRLEN HvENAMELEN(HV *stash) |
| 9877 |
.Ve |
| 9878 |
.RE |
| 9879 |
.RS 4 |
| 9880 |
.RE |
| 9881 |
.ie n .IP """HvENAMEUTF8""" 4 |
| 9882 |
.el .IP \f(CWHvENAMEUTF8\fR 4 |
| 9883 |
.IX Xref "HvENAMEUTF8" |
| 9884 |
.IX Item "HvENAMEUTF8" |
| 9885 |
Returns true if the effective name is in UTF\-8 encoding. |
| 9886 |
.RS 4 |
| 9887 |
.Sp |
| 9888 |
.Vb 1 |
| 9889 |
\& unsigned char HvENAMEUTF8(HV *stash) |
| 9890 |
.Ve |
| 9891 |
.RE |
| 9892 |
.RS 4 |
| 9893 |
.RE |
| 9894 |
.ie n .IP """hv_exists""" 4 |
| 9895 |
.el .IP \f(CWhv_exists\fR 4 |
| 9896 |
.IX Item "hv_exists" |
| 9897 |
.PD 0 |
| 9898 |
.ie n .IP """hv_existss""" 4 |
| 9899 |
.el .IP \f(CWhv_existss\fR 4 |
| 9900 |
.IX Xref "hv_exists hv_existss" |
| 9901 |
.IX Item "hv_existss" |
| 9902 |
.PD |
| 9903 |
These return a boolean indicating whether the specified hash key exists. |
| 9904 |
.Sp |
| 9905 |
In \f(CW\*(C`hv_existss\*(C'\fR, the key must be a C language string literal, enclosed in |
| 9906 |
double quotes. It is never treated as being in UTF\-8. There is no |
| 9907 |
length_parameter. |
| 9908 |
.Sp |
| 9909 |
In \f(CW\*(C`hv_exists\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If |
| 9910 |
\&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode. |
| 9911 |
.RS 4 |
| 9912 |
.Sp |
| 9913 |
.Vb 2 |
| 9914 |
\& bool hv_exists (HV *hv, const char *key, I32 klen) |
| 9915 |
\& bool hv_existss(HV *hv, "key") |
| 9916 |
.Ve |
| 9917 |
.RE |
| 9918 |
.RS 4 |
| 9919 |
.RE |
| 9920 |
.ie n .IP """hv_exists_ent""" 4 |
| 9921 |
.el .IP \f(CWhv_exists_ent\fR 4 |
| 9922 |
.IX Xref "hv_exists_ent" |
| 9923 |
.IX Item "hv_exists_ent" |
| 9924 |
Returns a boolean indicating whether |
| 9925 |
the specified hash key exists. \f(CW\*(C`hash\*(C'\fR |
| 9926 |
can be a valid precomputed hash value, or 0 to ask for it to be |
| 9927 |
computed. |
| 9928 |
.RS 4 |
| 9929 |
.Sp |
| 9930 |
.Vb 1 |
| 9931 |
\& bool hv_exists_ent(HV *hv, SV *keysv, U32 hash) |
| 9932 |
.Ve |
| 9933 |
.RE |
| 9934 |
.RS 4 |
| 9935 |
.RE |
| 9936 |
.ie n .IP """hv_fetch""" 4 |
| 9937 |
.el .IP \f(CWhv_fetch\fR 4 |
| 9938 |
.IX Item "hv_fetch" |
| 9939 |
.PD 0 |
| 9940 |
.ie n .IP """hv_fetchs""" 4 |
| 9941 |
.el .IP \f(CWhv_fetchs\fR 4 |
| 9942 |
.IX Xref "hv_fetch hv_fetchs" |
| 9943 |
.IX Item "hv_fetchs" |
| 9944 |
.PD |
| 9945 |
These return the SV which corresponds to the specified key in the hash. |
| 9946 |
.Sp |
| 9947 |
In \f(CW\*(C`hv_fetchs\*(C'\fR, the key must be a C language string literal, enclosed in |
| 9948 |
double quotes. It is never treated as being in UTF\-8. There is no |
| 9949 |
length_parameter. |
| 9950 |
.Sp |
| 9951 |
In \f(CW\*(C`hv_fetch\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If |
| 9952 |
\&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode. |
| 9953 |
.Sp |
| 9954 |
In both, if \f(CW\*(C`lval\*(C'\fR is set, then the fetch will be part of a store. This means |
| 9955 |
that if there is no value in the hash associated with the given key, then one |
| 9956 |
is created and a pointer to it is returned. The \f(CW\*(C`SV*\*(C'\fR it points to can be |
| 9957 |
assigned to. But always check that the return value is non-null before |
| 9958 |
dereferencing it to an \f(CW\*(C`SV*\*(C'\fR. |
| 9959 |
.Sp |
| 9960 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more |
| 9961 |
information on how to use this function on tied hashes. |
| 9962 |
.RS 4 |
| 9963 |
.Sp |
| 9964 |
.Vb 2 |
| 9965 |
\& SV ** hv_fetch (HV *hv, const char *key, I32 klen, I32 lval) |
| 9966 |
\& SV ** hv_fetchs(HV *hv, "key", I32 lval) |
| 9967 |
.Ve |
| 9968 |
.RE |
| 9969 |
.RS 4 |
| 9970 |
.RE |
| 9971 |
.ie n .IP """hv_fetch_ent""" 4 |
| 9972 |
.el .IP \f(CWhv_fetch_ent\fR 4 |
| 9973 |
.IX Xref "hv_fetch_ent" |
| 9974 |
.IX Item "hv_fetch_ent" |
| 9975 |
Returns the hash entry which corresponds to the specified key in the hash. |
| 9976 |
\&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0 |
| 9977 |
if you want the function to compute it. IF \f(CW\*(C`lval\*(C'\fR is set then the fetch |
| 9978 |
will be part of a store. Make sure the return value is non-null before |
| 9979 |
accessing it. The return value when \f(CW\*(C`hv\*(C'\fR is a tied hash is a pointer to a |
| 9980 |
static location, so be sure to make a copy of the structure if you need to |
| 9981 |
store it somewhere. |
| 9982 |
.Sp |
| 9983 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more |
| 9984 |
information on how to use this function on tied hashes. |
| 9985 |
.RS 4 |
| 9986 |
.Sp |
| 9987 |
.Vb 1 |
| 9988 |
\& HE * hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash) |
| 9989 |
.Ve |
| 9990 |
.RE |
| 9991 |
.RS 4 |
| 9992 |
.RE |
| 9993 |
.ie n .IP """hv_fetchs""" 4 |
| 9994 |
.el .IP \f(CWhv_fetchs\fR 4 |
| 9995 |
.IX Xref "hv_fetchs" |
| 9996 |
.IX Item "hv_fetchs" |
| 9997 |
Like \f(CW\*(C`hv_fetch\*(C'\fR, but takes a literal string instead of a |
| 9998 |
string/length pair. |
| 9999 |
.RS 4 |
| 10000 |
.Sp |
| 10001 |
.Vb 1 |
| 10002 |
\& SV** hv_fetchs(HV* tb, "key", I32 lval) |
| 10003 |
.Ve |
| 10004 |
.RE |
| 10005 |
.RS 4 |
| 10006 |
.RE |
| 10007 |
.ie n .IP """HvFILL""" 4 |
| 10008 |
.el .IP \f(CWHvFILL\fR 4 |
| 10009 |
.IX Xref "HvFILL" |
| 10010 |
.IX Item "HvFILL" |
| 10011 |
Returns the number of hash buckets that happen to be in use. |
| 10012 |
.Sp |
| 10013 |
As of perl 5.25 this function is used only for debugging |
| 10014 |
purposes, and the number of used hash buckets is not |
| 10015 |
in any way cached, thus this function can be costly |
| 10016 |
to execute as it must iterate over all the buckets in the |
| 10017 |
hash. |
| 10018 |
.RS 4 |
| 10019 |
.Sp |
| 10020 |
.Vb 1 |
| 10021 |
\& STRLEN HvFILL(HV *const hv) |
| 10022 |
.Ve |
| 10023 |
.RE |
| 10024 |
.RS 4 |
| 10025 |
.RE |
| 10026 |
.ie n .IP """HvHasAUX""" 4 |
| 10027 |
.el .IP \f(CWHvHasAUX\fR 4 |
| 10028 |
.IX Xref "HvHasAUX" |
| 10029 |
.IX Item "HvHasAUX" |
| 10030 |
Returns true if the HV has a \f(CW\*(C`struct xpvhv_aux\*(C'\fR extension. Use this to check |
| 10031 |
whether it is valid to call \f(CWHvAUX()\fR. |
| 10032 |
.RS 4 |
| 10033 |
.Sp |
| 10034 |
.Vb 1 |
| 10035 |
\& bool HvHasAUX(HV *const hv) |
| 10036 |
.Ve |
| 10037 |
.RE |
| 10038 |
.RS 4 |
| 10039 |
.RE |
| 10040 |
.ie n .IP """hv_iterinit""" 4 |
| 10041 |
.el .IP \f(CWhv_iterinit\fR 4 |
| 10042 |
.IX Xref "hv_iterinit" |
| 10043 |
.IX Item "hv_iterinit" |
| 10044 |
Prepares a starting point to traverse a hash table. Returns the number of |
| 10045 |
keys in the hash, including placeholders (i.e. the same as \f(CWHvTOTALKEYS(hv)\fR). |
| 10046 |
The return value is currently only meaningful for hashes without tie magic. |
| 10047 |
.Sp |
| 10048 |
NOTE: Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of |
| 10049 |
hash buckets that happen to be in use. If you still need that esoteric |
| 10050 |
value, you can get it through the macro \f(CWHvFILL(hv)\fR. |
| 10051 |
.RS 4 |
| 10052 |
.Sp |
| 10053 |
.Vb 1 |
| 10054 |
\& I32 hv_iterinit(HV *hv) |
| 10055 |
.Ve |
| 10056 |
.RE |
| 10057 |
.RS 4 |
| 10058 |
.RE |
| 10059 |
.ie n .IP """hv_iterkey""" 4 |
| 10060 |
.el .IP \f(CWhv_iterkey\fR 4 |
| 10061 |
.IX Xref "hv_iterkey" |
| 10062 |
.IX Item "hv_iterkey" |
| 10063 |
Returns the key from the current position of the hash iterator. See |
| 10064 |
\&\f(CW"hv_iterinit"\fR. |
| 10065 |
.RS 4 |
| 10066 |
.Sp |
| 10067 |
.Vb 1 |
| 10068 |
\& char * hv_iterkey(HE *entry, I32 *retlen) |
| 10069 |
.Ve |
| 10070 |
.RE |
| 10071 |
.RS 4 |
| 10072 |
.RE |
| 10073 |
.ie n .IP """hv_iterkeysv""" 4 |
| 10074 |
.el .IP \f(CWhv_iterkeysv\fR 4 |
| 10075 |
.IX Xref "hv_iterkeysv" |
| 10076 |
.IX Item "hv_iterkeysv" |
| 10077 |
Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash |
| 10078 |
iterator. The return value will always be a mortal copy of the key. Also |
| 10079 |
see \f(CW"hv_iterinit"\fR. |
| 10080 |
.RS 4 |
| 10081 |
.Sp |
| 10082 |
.Vb 1 |
| 10083 |
\& SV * hv_iterkeysv(HE *entry) |
| 10084 |
.Ve |
| 10085 |
.RE |
| 10086 |
.RS 4 |
| 10087 |
.RE |
| 10088 |
.ie n .IP """hv_iternext""" 4 |
| 10089 |
.el .IP \f(CWhv_iternext\fR 4 |
| 10090 |
.IX Xref "hv_iternext" |
| 10091 |
.IX Item "hv_iternext" |
| 10092 |
Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR. |
| 10093 |
.Sp |
| 10094 |
You may call \f(CW\*(C`hv_delete\*(C'\fR or \f(CW\*(C`hv_delete_ent\*(C'\fR on the hash entry that the |
| 10095 |
iterator currently points to, without losing your place or invalidating your |
| 10096 |
iterator. Note that in this case the current entry is deleted from the hash |
| 10097 |
with your iterator holding the last reference to it. Your iterator is flagged |
| 10098 |
to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard |
| 10099 |
your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to |
| 10100 |
trigger the resource deallocation. |
| 10101 |
.RS 4 |
| 10102 |
.Sp |
| 10103 |
.Vb 1 |
| 10104 |
\& HE * hv_iternext(HV *hv) |
| 10105 |
.Ve |
| 10106 |
.RE |
| 10107 |
.RS 4 |
| 10108 |
.RE |
| 10109 |
.ie n .IP """hv_iternext_flags""" 4 |
| 10110 |
.el .IP \f(CWhv_iternext_flags\fR 4 |
| 10111 |
.IX Xref "hv_iternext_flags" |
| 10112 |
.IX Item "hv_iternext_flags" |
| 10113 |
NOTE: \f(CW\*(C`hv_iternext_flags\*(C'\fR is \fBexperimental\fR and may change or be |
| 10114 |
removed without notice. |
| 10115 |
.Sp |
| 10116 |
Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR and |
| 10117 |
\&\f(CW"hv_iternext"\fR. |
| 10118 |
The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \f(CW\*(C`HV_ITERNEXT_WANTPLACEHOLDERS\*(C'\fR is |
| 10119 |
set the placeholders keys (for restricted hashes) will be returned in addition |
| 10120 |
to normal keys. By default placeholders are automatically skipped over. |
| 10121 |
Currently a placeholder is implemented with a value that is |
| 10122 |
\&\f(CW&PL_sv_placeholder\fR. Note that the implementation of placeholders and |
| 10123 |
restricted hashes may change, and the implementation currently is |
| 10124 |
insufficiently abstracted for any change to be tidy. |
| 10125 |
.RS 4 |
| 10126 |
.Sp |
| 10127 |
.Vb 1 |
| 10128 |
\& HE * hv_iternext_flags(HV *hv, I32 flags) |
| 10129 |
.Ve |
| 10130 |
.RE |
| 10131 |
.RS 4 |
| 10132 |
.RE |
| 10133 |
.ie n .IP """hv_iternextsv""" 4 |
| 10134 |
.el .IP \f(CWhv_iternextsv\fR 4 |
| 10135 |
.IX Xref "hv_iternextsv" |
| 10136 |
.IX Item "hv_iternextsv" |
| 10137 |
Performs an \f(CW\*(C`hv_iternext\*(C'\fR, \f(CW\*(C`hv_iterkey\*(C'\fR, and \f(CW\*(C`hv_iterval\*(C'\fR in one |
| 10138 |
operation. |
| 10139 |
.RS 4 |
| 10140 |
.Sp |
| 10141 |
.Vb 1 |
| 10142 |
\& SV * hv_iternextsv(HV *hv, char **key, I32 *retlen) |
| 10143 |
.Ve |
| 10144 |
.RE |
| 10145 |
.RS 4 |
| 10146 |
.RE |
| 10147 |
.ie n .IP """hv_iterval""" 4 |
| 10148 |
.el .IP \f(CWhv_iterval\fR 4 |
| 10149 |
.IX Xref "hv_iterval" |
| 10150 |
.IX Item "hv_iterval" |
| 10151 |
Returns the value from the current position of the hash iterator. See |
| 10152 |
\&\f(CW"hv_iterkey"\fR. |
| 10153 |
.RS 4 |
| 10154 |
.Sp |
| 10155 |
.Vb 1 |
| 10156 |
\& SV * hv_iterval(HV *hv, HE *entry) |
| 10157 |
.Ve |
| 10158 |
.RE |
| 10159 |
.RS 4 |
| 10160 |
.RE |
| 10161 |
.ie n .IP """hv_ksplit""" 4 |
| 10162 |
.el .IP \f(CWhv_ksplit\fR 4 |
| 10163 |
.IX Xref "hv_ksplit" |
| 10164 |
.IX Item "hv_ksplit" |
| 10165 |
Attempt to grow the hash \f(CW\*(C`hv\*(C'\fR so it has at least \f(CW\*(C`newmax\*(C'\fR buckets available. |
| 10166 |
Perl chooses the actual number for its convenience. |
| 10167 |
.Sp |
| 10168 |
This is the same as doing the following in Perl code: |
| 10169 |
.Sp |
| 10170 |
.Vb 1 |
| 10171 |
\& keys %hv = newmax; |
| 10172 |
.Ve |
| 10173 |
.RS 4 |
| 10174 |
.Sp |
| 10175 |
.Vb 1 |
| 10176 |
\& void hv_ksplit(HV *hv, IV newmax) |
| 10177 |
.Ve |
| 10178 |
.RE |
| 10179 |
.RS 4 |
| 10180 |
.RE |
| 10181 |
.ie n .IP """hv_magic""" 4 |
| 10182 |
.el .IP \f(CWhv_magic\fR 4 |
| 10183 |
.IX Xref "hv_magic" |
| 10184 |
.IX Item "hv_magic" |
| 10185 |
Adds magic to a hash. See \f(CW"sv_magic"\fR. |
| 10186 |
.RS 4 |
| 10187 |
.Sp |
| 10188 |
.Vb 1 |
| 10189 |
\& void hv_magic(HV *hv, GV *gv, int how) |
| 10190 |
.Ve |
| 10191 |
.RE |
| 10192 |
.RS 4 |
| 10193 |
.RE |
| 10194 |
.ie n .IP """HvNAME""" 4 |
| 10195 |
.el .IP \f(CWHvNAME\fR 4 |
| 10196 |
.IX Xref "HvNAME" |
| 10197 |
.IX Item "HvNAME" |
| 10198 |
Returns the package name of a stash, or \f(CW\*(C`NULL\*(C'\fR if \f(CW\*(C`stash\*(C'\fR isn't a stash. |
| 10199 |
See \f(CW"SvSTASH"\fR, \f(CW"CvSTASH"\fR. |
| 10200 |
.RS 4 |
| 10201 |
.Sp |
| 10202 |
.Vb 1 |
| 10203 |
\& char* HvNAME(HV* stash) |
| 10204 |
.Ve |
| 10205 |
.RE |
| 10206 |
.RS 4 |
| 10207 |
.RE |
| 10208 |
.ie n .IP """HvNAMELEN""" 4 |
| 10209 |
.el .IP \f(CWHvNAMELEN\fR 4 |
| 10210 |
.IX Xref "HvNAMELEN" |
| 10211 |
.IX Item "HvNAMELEN" |
| 10212 |
Returns the length of the stash's name. |
| 10213 |
.Sp |
| 10214 |
Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them |
| 10215 |
.RS 4 |
| 10216 |
.Sp |
| 10217 |
.Vb 1 |
| 10218 |
\& STRLEN HvNAMELEN(HV *stash) |
| 10219 |
.Ve |
| 10220 |
.RE |
| 10221 |
.RS 4 |
| 10222 |
.RE |
| 10223 |
.ie n .IP """hv_name_set""" 4 |
| 10224 |
.el .IP \f(CWhv_name_set\fR 4 |
| 10225 |
.IX Item "hv_name_set" |
| 10226 |
.PD 0 |
| 10227 |
.ie n .IP """hv_name_sets""" 4 |
| 10228 |
.el .IP \f(CWhv_name_sets\fR 4 |
| 10229 |
.IX Xref "hv_name_set hv_name_sets" |
| 10230 |
.IX Item "hv_name_sets" |
| 10231 |
.PD |
| 10232 |
These each set the name of stash \f(CW\*(C`hv\*(C'\fR to the specified name. |
| 10233 |
.Sp |
| 10234 |
They differ only in how the name is specified. |
| 10235 |
.Sp |
| 10236 |
In \f(CW\*(C`hv_name_sets\*(C'\fR, the name is a literal C string, enclosed in double quotes. |
| 10237 |
.Sp |
| 10238 |
In \f(CW\*(C`hv_name_set\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an |
| 10239 |
additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the name |
| 10240 |
may contain embedded-NUL characters. |
| 10241 |
.Sp |
| 10242 |
If \f(CW\*(C`SVf_UTF8\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, the name is treated as being in UTF\-8; |
| 10243 |
otherwise not. |
| 10244 |
.Sp |
| 10245 |
If \f(CW\*(C`HV_NAME_SETALL\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, both the name and the effective name |
| 10246 |
are set. |
| 10247 |
.RS 4 |
| 10248 |
.Sp |
| 10249 |
.Vb 2 |
| 10250 |
\& void hv_name_set (HV *hv, const char *name, U32 len, U32 flags) |
| 10251 |
\& void hv_name_sets(HV *hv, "name", U32 flags) |
| 10252 |
.Ve |
| 10253 |
.RE |
| 10254 |
.RS 4 |
| 10255 |
.RE |
| 10256 |
.ie n .IP """HvNAMEUTF8""" 4 |
| 10257 |
.el .IP \f(CWHvNAMEUTF8\fR 4 |
| 10258 |
.IX Xref "HvNAMEUTF8" |
| 10259 |
.IX Item "HvNAMEUTF8" |
| 10260 |
Returns true if the name is in UTF\-8 encoding. |
| 10261 |
.RS 4 |
| 10262 |
.Sp |
| 10263 |
.Vb 1 |
| 10264 |
\& unsigned char HvNAMEUTF8(HV *stash) |
| 10265 |
.Ve |
| 10266 |
.RE |
| 10267 |
.RS 4 |
| 10268 |
.RE |
| 10269 |
.ie n .IP """hv_scalar""" 4 |
| 10270 |
.el .IP \f(CWhv_scalar\fR 4 |
| 10271 |
.IX Xref "hv_scalar" |
| 10272 |
.IX Item "hv_scalar" |
| 10273 |
Evaluates the hash in scalar context and returns the result. |
| 10274 |
.Sp |
| 10275 |
When the hash is tied dispatches through to the SCALAR method, |
| 10276 |
otherwise returns a mortal SV containing the number of keys |
| 10277 |
in the hash. |
| 10278 |
.Sp |
| 10279 |
Note, prior to 5.25 this function returned what is now |
| 10280 |
returned by the \fBhv_bucket_ratio()\fR function. |
| 10281 |
.RS 4 |
| 10282 |
.Sp |
| 10283 |
.Vb 1 |
| 10284 |
\& SV * hv_scalar(HV *hv) |
| 10285 |
.Ve |
| 10286 |
.RE |
| 10287 |
.RS 4 |
| 10288 |
.RE |
| 10289 |
.ie n .IP """hv_store""" 4 |
| 10290 |
.el .IP \f(CWhv_store\fR 4 |
| 10291 |
.IX Item "hv_store" |
| 10292 |
.PD 0 |
| 10293 |
.ie n .IP """hv_stores""" 4 |
| 10294 |
.el .IP \f(CWhv_stores\fR 4 |
| 10295 |
.IX Xref "hv_store hv_stores" |
| 10296 |
.IX Item "hv_stores" |
| 10297 |
.PD |
| 10298 |
These each store SV \f(CW\*(C`val\*(C'\fR with the specified key in hash \f(CW\*(C`hv\*(C'\fR, returning NULL |
| 10299 |
if the operation failed or if the value did not need to be actually stored |
| 10300 |
within the hash (as in the case of tied hashes). Otherwise it can be |
| 10301 |
dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR. |
| 10302 |
.Sp |
| 10303 |
They differ only in how the hash key is specified. |
| 10304 |
.Sp |
| 10305 |
In \f(CW\*(C`hv_stores\*(C'\fR, the key must be a C language string literal, enclosed in |
| 10306 |
double quotes. It is never treated as being in UTF\-8. There is no |
| 10307 |
length_parameter. |
| 10308 |
.Sp |
| 10309 |
In \f(CW\*(C`hv_store\*(C'\fR, \f(CW\*(C`key\*(C'\fR is either NULL or points to the first byte of the string |
| 10310 |
specifying the key, and its length in bytes is given by the absolute value of |
| 10311 |
an additional parameter, \f(CW\*(C`klen\*(C'\fR. A NULL key indicates the key is to be |
| 10312 |
treated as \f(CW\*(C`undef\*(C'\fR, and \f(CW\*(C`klen\*(C'\fR is ignored; otherwise the key string may |
| 10313 |
contain embedded-NUL bytes. If \f(CW\*(C`klen\*(C'\fR is negative, the string is treated as |
| 10314 |
being encoded in UTF\-8; otherwise not. |
| 10315 |
.Sp |
| 10316 |
\&\f(CW\*(C`hv_store\*(C'\fR has another extra parameter, \f(CW\*(C`hash\*(C'\fR, a precomputed hash of the key |
| 10317 |
string, or zero if it has not been precomputed. This parameter is omitted from |
| 10318 |
\&\f(CW\*(C`hv_stores\*(C'\fR, as it is computed automatically at compile time. |
| 10319 |
.Sp |
| 10320 |
If <hv> is NULL, NULL is returned and no action is taken. |
| 10321 |
.Sp |
| 10322 |
If \f(CW\*(C`val\*(C'\fR is NULL, it is treated as being \f(CW\*(C`undef\*(C'\fR; otherwise the caller is |
| 10323 |
responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before |
| 10324 |
the call, and decrementing it if the function returned \f(CW\*(C`NULL\*(C'\fR. Effectively |
| 10325 |
a successful \f(CW\*(C`hv_store\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is |
| 10326 |
usually what you want; a newly created SV has a reference count of one, so |
| 10327 |
if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR |
| 10328 |
will own the only reference to the new SV, and your code doesn't need to do |
| 10329 |
anything further to tidy up. |
| 10330 |
.Sp |
| 10331 |
\&\f(CW\*(C`hv_store\*(C'\fR is not implemented as a call to "\f(CW\*(C`hv_store_ent\*(C'\fR", and does not |
| 10332 |
create a temporary SV for the key, so if your key data is not already in SV |
| 10333 |
form then use \f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR. |
| 10334 |
.Sp |
| 10335 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more |
| 10336 |
information on how to use this function on tied hashes. |
| 10337 |
.RS 4 |
| 10338 |
.Sp |
| 10339 |
.Vb 3 |
| 10340 |
\& SV ** hv_store (HV *hv, const char *key, I32 klen, SV *val, |
| 10341 |
\& U32 hash) |
| 10342 |
\& SV ** hv_stores(HV *hv, "key", SV *val) |
| 10343 |
.Ve |
| 10344 |
.RE |
| 10345 |
.RS 4 |
| 10346 |
.RE |
| 10347 |
.ie n .IP """hv_store_ent""" 4 |
| 10348 |
.el .IP \f(CWhv_store_ent\fR 4 |
| 10349 |
.IX Xref "hv_store_ent" |
| 10350 |
.IX Item "hv_store_ent" |
| 10351 |
Stores \f(CW\*(C`val\*(C'\fR in a hash. The hash key is specified as \f(CW\*(C`key\*(C'\fR. The \f(CW\*(C`hash\*(C'\fR |
| 10352 |
parameter is the precomputed hash value; if it is zero then Perl will |
| 10353 |
compute it. The return value is the new hash entry so created. It will be |
| 10354 |
\&\f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not need to be actually |
| 10355 |
stored within the hash (as in the case of tied hashes). Otherwise the |
| 10356 |
contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros |
| 10357 |
described here. Note that the caller is responsible for suitably |
| 10358 |
incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and |
| 10359 |
decrementing it if the function returned NULL. Effectively a successful |
| 10360 |
\&\f(CW\*(C`hv_store_ent\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is |
| 10361 |
usually what you want; a newly created SV has a reference count of one, so |
| 10362 |
if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR |
| 10363 |
will own the only reference to the new SV, and your code doesn't need to do |
| 10364 |
anything further to tidy up. Note that \f(CW\*(C`hv_store_ent\*(C'\fR only reads the \f(CW\*(C`key\*(C'\fR; |
| 10365 |
unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct |
| 10366 |
reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller's responsibility. The reason |
| 10367 |
it does not take ownership, is that \f(CW\*(C`key\*(C'\fR is not used after this function |
| 10368 |
returns, and so can be freed immediately. \f(CW\*(C`hv_store\*(C'\fR |
| 10369 |
is not implemented as a call to \f(CW\*(C`hv_store_ent\*(C'\fR, and does not create a temporary |
| 10370 |
SV for the key, so if your key data is not already in SV form then use |
| 10371 |
\&\f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR. |
| 10372 |
.Sp |
| 10373 |
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more |
| 10374 |
information on how to use this function on tied hashes. |
| 10375 |
.RS 4 |
| 10376 |
.Sp |
| 10377 |
.Vb 1 |
| 10378 |
\& HE * hv_store_ent(HV *hv, SV *key, SV *val, U32 hash) |
| 10379 |
.Ve |
| 10380 |
.RE |
| 10381 |
.RS 4 |
| 10382 |
.RE |
| 10383 |
.ie n .IP """hv_undef""" 4 |
| 10384 |
.el .IP \f(CWhv_undef\fR 4 |
| 10385 |
.IX Xref "hv_undef" |
| 10386 |
.IX Item "hv_undef" |
| 10387 |
Undefines the hash. The XS equivalent of \f(CWundef(%hash)\fR. |
| 10388 |
.Sp |
| 10389 |
As well as freeing all the elements of the hash (like \f(CWhv_clear()\fR), this |
| 10390 |
also frees any auxiliary data and storage associated with the hash. |
| 10391 |
.Sp |
| 10392 |
See "av_clear" for a note about the hash possibly being invalid on |
| 10393 |
return. |
| 10394 |
.RS 4 |
| 10395 |
.Sp |
| 10396 |
.Vb 1 |
| 10397 |
\& void hv_undef(HV *hv) |
| 10398 |
.Ve |
| 10399 |
.RE |
| 10400 |
.RS 4 |
| 10401 |
.RE |
| 10402 |
.ie n .IP """newHV""" 4 |
| 10403 |
.el .IP \f(CWnewHV\fR 4 |
| 10404 |
.IX Xref "newHV" |
| 10405 |
.IX Item "newHV" |
| 10406 |
Creates a new HV. The reference count is set to 1. |
| 10407 |
.RS 4 |
| 10408 |
.Sp |
| 10409 |
.Vb 1 |
| 10410 |
\& HV * newHV() |
| 10411 |
.Ve |
| 10412 |
.RE |
| 10413 |
.RS 4 |
| 10414 |
.RE |
| 10415 |
.ie n .IP """newHVhv""" 4 |
| 10416 |
.el .IP \f(CWnewHVhv\fR 4 |
| 10417 |
.IX Xref "newHVhv" |
| 10418 |
.IX Item "newHVhv" |
| 10419 |
The content of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash. A pointer to the new hash is |
| 10420 |
returned. |
| 10421 |
.RS 4 |
| 10422 |
.Sp |
| 10423 |
.Vb 1 |
| 10424 |
\& HV * newHVhv(HV *hv) |
| 10425 |
.Ve |
| 10426 |
.RE |
| 10427 |
.RS 4 |
| 10428 |
.RE |
| 10429 |
.ie n .IP """Nullhv""" 4 |
| 10430 |
.el .IP \f(CWNullhv\fR 4 |
| 10431 |
.IX Xref "Nullhv" |
| 10432 |
.IX Item "Nullhv" |
| 10433 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullhv\*(C'\fR |
| 10434 |
from a future release of Perl. Do not use it for |
| 10435 |
new code; remove it from existing code. |
| 10436 |
.Sp |
| 10437 |
Null HV pointer. |
| 10438 |
.Sp |
| 10439 |
(deprecated \- use \f(CW\*(C`(HV *)NULL\*(C'\fR instead) |
| 10440 |
.ie n .IP """PERL_HASH""" 4 |
| 10441 |
.el .IP \f(CWPERL_HASH\fR 4 |
| 10442 |
.IX Item "PERL_HASH" |
| 10443 |
Described in perlguts. |
| 10444 |
.RS 4 |
| 10445 |
.Sp |
| 10446 |
.Vb 1 |
| 10447 |
\& void PERL_HASH(U32 hash, char *key, STRLEN klen) |
| 10448 |
.Ve |
| 10449 |
.RE |
| 10450 |
.RS 4 |
| 10451 |
.RE |
| 10452 |
.ie n .IP """PL_modglobal""" 4 |
| 10453 |
.el .IP \f(CWPL_modglobal\fR 4 |
| 10454 |
.IX Xref "PL_modglobal" |
| 10455 |
.IX Item "PL_modglobal" |
| 10456 |
\&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global HV for use by |
| 10457 |
extensions that need to keep information on a per-interpreter basis. |
| 10458 |
In a pinch, it can also be used as a symbol table for extensions |
| 10459 |
to share data among each other. It is a good idea to use keys |
| 10460 |
prefixed by the package name of the extension that owns the data. |
| 10461 |
.Sp |
| 10462 |
On threaded perls, each thread has an independent copy of this variable; |
| 10463 |
each initialized at creation time with the current value of the creating |
| 10464 |
thread's copy. |
| 10465 |
.RS 4 |
| 10466 |
.Sp |
| 10467 |
.Vb 1 |
| 10468 |
\& HV* PL_modglobal |
| 10469 |
.Ve |
| 10470 |
.RE |
| 10471 |
.RS 4 |
| 10472 |
.RE |
| 10473 |
.SH Input/Output |
| 10474 |
.IX Header "Input/Output" |
| 10475 |
.ie n .IP """do_close""" 4 |
| 10476 |
.el .IP \f(CWdo_close\fR 4 |
| 10477 |
.IX Xref "do_close" |
| 10478 |
.IX Item "do_close" |
| 10479 |
Close an I/O stream. This implements Perl "\f(CW\*(C`close\*(C'\fR" in perlfunc. |
| 10480 |
.Sp |
| 10481 |
\&\f(CW\*(C`gv\*(C'\fR is the glob associated with the stream. |
| 10482 |
.Sp |
| 10483 |
\&\f(CW\*(C`is_explict\*(C'\fR is \f(CW\*(C`true\*(C'\fR if this is an explicit close of the stream; \f(CW\*(C`false\*(C'\fR |
| 10484 |
if it is part of another operation, such as closing a pipe (which involves |
| 10485 |
implicitly closing both ends). |
| 10486 |
.Sp |
| 10487 |
Returns \f(CW\*(C`true\*(C'\fR if successful; otherwise returns \f(CW\*(C`false\*(C'\fR and sets \f(CW\*(C`errno\*(C'\fR to |
| 10488 |
indicate the cause. |
| 10489 |
.RS 4 |
| 10490 |
.Sp |
| 10491 |
.Vb 1 |
| 10492 |
\& bool do_close(GV *gv, bool is_explicit) |
| 10493 |
.Ve |
| 10494 |
.RE |
| 10495 |
.RS 4 |
| 10496 |
.RE |
| 10497 |
.ie n .IP """IoDIRP""" 4 |
| 10498 |
.el .IP \f(CWIoDIRP\fR 4 |
| 10499 |
.IX Item "IoDIRP" |
| 10500 |
Described in perlguts. |
| 10501 |
.RS 4 |
| 10502 |
.Sp |
| 10503 |
.Vb 1 |
| 10504 |
\& DIR * IoDIRP(IO *io) |
| 10505 |
.Ve |
| 10506 |
.RE |
| 10507 |
.RS 4 |
| 10508 |
.RE |
| 10509 |
.ie n .IP """IOf_FLUSH""" 4 |
| 10510 |
.el .IP \f(CWIOf_FLUSH\fR 4 |
| 10511 |
.IX Item "IOf_FLUSH" |
| 10512 |
Described in perlguts. |
| 10513 |
.ie n .IP """IoFLAGS""" 4 |
| 10514 |
.el .IP \f(CWIoFLAGS\fR 4 |
| 10515 |
.IX Item "IoFLAGS" |
| 10516 |
Described in perlguts. |
| 10517 |
.RS 4 |
| 10518 |
.Sp |
| 10519 |
.Vb 1 |
| 10520 |
\& U8 IoFLAGS(IO *io) |
| 10521 |
.Ve |
| 10522 |
.RE |
| 10523 |
.RS 4 |
| 10524 |
.RE |
| 10525 |
.ie n .IP """IOf_UNTAINT""" 4 |
| 10526 |
.el .IP \f(CWIOf_UNTAINT\fR 4 |
| 10527 |
.IX Item "IOf_UNTAINT" |
| 10528 |
Described in perlguts. |
| 10529 |
.ie n .IP """IoIFP""" 4 |
| 10530 |
.el .IP \f(CWIoIFP\fR 4 |
| 10531 |
.IX Item "IoIFP" |
| 10532 |
Described in perlguts. |
| 10533 |
.RS 4 |
| 10534 |
.Sp |
| 10535 |
.Vb 1 |
| 10536 |
\& PerlIO * IoIFP(IO *io) |
| 10537 |
.Ve |
| 10538 |
.RE |
| 10539 |
.RS 4 |
| 10540 |
.RE |
| 10541 |
.ie n .IP """IoOFP""" 4 |
| 10542 |
.el .IP \f(CWIoOFP\fR 4 |
| 10543 |
.IX Item "IoOFP" |
| 10544 |
Described in perlguts. |
| 10545 |
.RS 4 |
| 10546 |
.Sp |
| 10547 |
.Vb 1 |
| 10548 |
\& PerlIO * IoOFP(IO *io) |
| 10549 |
.Ve |
| 10550 |
.RE |
| 10551 |
.RS 4 |
| 10552 |
.RE |
| 10553 |
.ie n .IP """IoTYPE""" 4 |
| 10554 |
.el .IP \f(CWIoTYPE\fR 4 |
| 10555 |
.IX Item "IoTYPE" |
| 10556 |
Described in perlguts. |
| 10557 |
.RS 4 |
| 10558 |
.Sp |
| 10559 |
.Vb 1 |
| 10560 |
\& char IoTYPE(IO *io) |
| 10561 |
.Ve |
| 10562 |
.RE |
| 10563 |
.RS 4 |
| 10564 |
.RE |
| 10565 |
.ie n .IP """my_chsize""" 4 |
| 10566 |
.el .IP \f(CWmy_chsize\fR 4 |
| 10567 |
.IX Xref "my_chsize" |
| 10568 |
.IX Item "my_chsize" |
| 10569 |
The C library \fBchsize\fR\|(3) if available, or a Perl implementation of it. |
| 10570 |
.RS 4 |
| 10571 |
.Sp |
| 10572 |
.Vb 1 |
| 10573 |
\& I32 my_chsize(int fd, Off_t length) |
| 10574 |
.Ve |
| 10575 |
.RE |
| 10576 |
.RS 4 |
| 10577 |
.RE |
| 10578 |
.ie n .IP """my_dirfd""" 4 |
| 10579 |
.el .IP \f(CWmy_dirfd\fR 4 |
| 10580 |
.IX Xref "my_dirfd" |
| 10581 |
.IX Item "my_dirfd" |
| 10582 |
The C library \f(CWdirfd(3)\fR if available, or a Perl implementation of it, or die |
| 10583 |
if not easily emulatable. |
| 10584 |
.RS 4 |
| 10585 |
.Sp |
| 10586 |
.Vb 1 |
| 10587 |
\& int my_dirfd(DIR *dir) |
| 10588 |
.Ve |
| 10589 |
.RE |
| 10590 |
.RS 4 |
| 10591 |
.RE |
| 10592 |
.ie n .IP """my_pclose""" 4 |
| 10593 |
.el .IP \f(CWmy_pclose\fR 4 |
| 10594 |
.IX Xref "my_pclose" |
| 10595 |
.IX Item "my_pclose" |
| 10596 |
A wrapper for the C library \fBpclose\fR\|(3). Don't use the latter, as the Perl |
| 10597 |
version knows things that interact with the rest of the perl interpreter. |
| 10598 |
.RS 4 |
| 10599 |
.Sp |
| 10600 |
.Vb 1 |
| 10601 |
\& I32 my_pclose(PerlIO *ptr) |
| 10602 |
.Ve |
| 10603 |
.RE |
| 10604 |
.RS 4 |
| 10605 |
.RE |
| 10606 |
.ie n .IP """my_popen""" 4 |
| 10607 |
.el .IP \f(CWmy_popen\fR 4 |
| 10608 |
.IX Xref "my_popen" |
| 10609 |
.IX Item "my_popen" |
| 10610 |
A wrapper for the C library \fBpopen\fR\|(3). Don't use the latter, as the Perl |
| 10611 |
version knows things that interact with the rest of the perl interpreter. |
| 10612 |
.RS 4 |
| 10613 |
.Sp |
| 10614 |
.Vb 1 |
| 10615 |
\& PerlIO * my_popen(const char *cmd, const char *mode) |
| 10616 |
.Ve |
| 10617 |
.RE |
| 10618 |
.RS 4 |
| 10619 |
.RE |
| 10620 |
.ie n .IP """newIO""" 4 |
| 10621 |
.el .IP \f(CWnewIO\fR 4 |
| 10622 |
.IX Xref "newIO" |
| 10623 |
.IX Item "newIO" |
| 10624 |
Create a new IO, setting the reference count to 1. |
| 10625 |
.RS 4 |
| 10626 |
.Sp |
| 10627 |
.Vb 1 |
| 10628 |
\& IO * newIO() |
| 10629 |
.Ve |
| 10630 |
.RE |
| 10631 |
.RS 4 |
| 10632 |
.RE |
| 10633 |
.ie n .IP """PERL_FLUSHALL_FOR_CHILD""" 4 |
| 10634 |
.el .IP \f(CWPERL_FLUSHALL_FOR_CHILD\fR 4 |
| 10635 |
.IX Xref "PERL_FLUSHALL_FOR_CHILD" |
| 10636 |
.IX Item "PERL_FLUSHALL_FOR_CHILD" |
| 10637 |
This defines a way to flush all output buffers. This may be a |
| 10638 |
performance issue, so we allow people to disable it. Also, if |
| 10639 |
we are using stdio, there are broken implementations of fflush(NULL) |
| 10640 |
out there, Solaris being the most prominent. |
| 10641 |
.RS 4 |
| 10642 |
.Sp |
| 10643 |
.Vb 1 |
| 10644 |
\& void PERL_FLUSHALL_FOR_CHILD |
| 10645 |
.Ve |
| 10646 |
.RE |
| 10647 |
.RS 4 |
| 10648 |
.RE |
| 10649 |
.ie n .IP """PerlIO_apply_layers""" 4 |
| 10650 |
.el .IP \f(CWPerlIO_apply_layers\fR 4 |
| 10651 |
.IX Item "PerlIO_apply_layers" |
| 10652 |
.PD 0 |
| 10653 |
.ie n .IP """PerlIO_binmode""" 4 |
| 10654 |
.el .IP \f(CWPerlIO_binmode\fR 4 |
| 10655 |
.IX Item "PerlIO_binmode" |
| 10656 |
.ie n .IP """PerlIO_canset_cnt""" 4 |
| 10657 |
.el .IP \f(CWPerlIO_canset_cnt\fR 4 |
| 10658 |
.IX Item "PerlIO_canset_cnt" |
| 10659 |
.ie n .IP """PerlIO_clearerr""" 4 |
| 10660 |
.el .IP \f(CWPerlIO_clearerr\fR 4 |
| 10661 |
.IX Item "PerlIO_clearerr" |
| 10662 |
.ie n .IP """PerlIO_close""" 4 |
| 10663 |
.el .IP \f(CWPerlIO_close\fR 4 |
| 10664 |
.IX Item "PerlIO_close" |
| 10665 |
.ie n .IP """PerlIO_debug""" 4 |
| 10666 |
.el .IP \f(CWPerlIO_debug\fR 4 |
| 10667 |
.IX Item "PerlIO_debug" |
| 10668 |
.ie n .IP """PerlIO_eof""" 4 |
| 10669 |
.el .IP \f(CWPerlIO_eof\fR 4 |
| 10670 |
.IX Item "PerlIO_eof" |
| 10671 |
.ie n .IP """PerlIO_error""" 4 |
| 10672 |
.el .IP \f(CWPerlIO_error\fR 4 |
| 10673 |
.IX Item "PerlIO_error" |
| 10674 |
.ie n .IP """PerlIO_exportFILE""" 4 |
| 10675 |
.el .IP \f(CWPerlIO_exportFILE\fR 4 |
| 10676 |
.IX Item "PerlIO_exportFILE" |
| 10677 |
.ie n .IP """PerlIO_fast_gets""" 4 |
| 10678 |
.el .IP \f(CWPerlIO_fast_gets\fR 4 |
| 10679 |
.IX Item "PerlIO_fast_gets" |
| 10680 |
.ie n .IP """PerlIO_fdopen""" 4 |
| 10681 |
.el .IP \f(CWPerlIO_fdopen\fR 4 |
| 10682 |
.IX Item "PerlIO_fdopen" |
| 10683 |
.ie n .IP """PerlIO_fileno""" 4 |
| 10684 |
.el .IP \f(CWPerlIO_fileno\fR 4 |
| 10685 |
.IX Item "PerlIO_fileno" |
| 10686 |
.ie n .IP """PerlIO_fill""" 4 |
| 10687 |
.el .IP \f(CWPerlIO_fill\fR 4 |
| 10688 |
.IX Item "PerlIO_fill" |
| 10689 |
.ie n .IP """PerlIO_findFILE""" 4 |
| 10690 |
.el .IP \f(CWPerlIO_findFILE\fR 4 |
| 10691 |
.IX Item "PerlIO_findFILE" |
| 10692 |
.ie n .IP """PerlIO_flush""" 4 |
| 10693 |
.el .IP \f(CWPerlIO_flush\fR 4 |
| 10694 |
.IX Item "PerlIO_flush" |
| 10695 |
.ie n .IP """PerlIO_get_base""" 4 |
| 10696 |
.el .IP \f(CWPerlIO_get_base\fR 4 |
| 10697 |
.IX Item "PerlIO_get_base" |
| 10698 |
.ie n .IP """PerlIO_get_bufsiz""" 4 |
| 10699 |
.el .IP \f(CWPerlIO_get_bufsiz\fR 4 |
| 10700 |
.IX Item "PerlIO_get_bufsiz" |
| 10701 |
.ie n .IP """PerlIO_get_cnt""" 4 |
| 10702 |
.el .IP \f(CWPerlIO_get_cnt\fR 4 |
| 10703 |
.IX Item "PerlIO_get_cnt" |
| 10704 |
.ie n .IP """PerlIO_get_ptr""" 4 |
| 10705 |
.el .IP \f(CWPerlIO_get_ptr\fR 4 |
| 10706 |
.IX Item "PerlIO_get_ptr" |
| 10707 |
.ie n .IP """PerlIO_getc""" 4 |
| 10708 |
.el .IP \f(CWPerlIO_getc\fR 4 |
| 10709 |
.IX Item "PerlIO_getc" |
| 10710 |
.ie n .IP """PerlIO_getpos""" 4 |
| 10711 |
.el .IP \f(CWPerlIO_getpos\fR 4 |
| 10712 |
.IX Item "PerlIO_getpos" |
| 10713 |
.ie n .IP """PerlIO_has_base""" 4 |
| 10714 |
.el .IP \f(CWPerlIO_has_base\fR 4 |
| 10715 |
.IX Item "PerlIO_has_base" |
| 10716 |
.ie n .IP """PerlIO_has_cntptr""" 4 |
| 10717 |
.el .IP \f(CWPerlIO_has_cntptr\fR 4 |
| 10718 |
.IX Item "PerlIO_has_cntptr" |
| 10719 |
.ie n .IP """PerlIO_importFILE""" 4 |
| 10720 |
.el .IP \f(CWPerlIO_importFILE\fR 4 |
| 10721 |
.IX Item "PerlIO_importFILE" |
| 10722 |
.ie n .IP """PerlIO_open""" 4 |
| 10723 |
.el .IP \f(CWPerlIO_open\fR 4 |
| 10724 |
.IX Item "PerlIO_open" |
| 10725 |
.ie n .IP """PerlIO_printf""" 4 |
| 10726 |
.el .IP \f(CWPerlIO_printf\fR 4 |
| 10727 |
.IX Item "PerlIO_printf" |
| 10728 |
.ie n .IP """PerlIO_putc""" 4 |
| 10729 |
.el .IP \f(CWPerlIO_putc\fR 4 |
| 10730 |
.IX Item "PerlIO_putc" |
| 10731 |
.ie n .IP """PerlIO_puts""" 4 |
| 10732 |
.el .IP \f(CWPerlIO_puts\fR 4 |
| 10733 |
.IX Item "PerlIO_puts" |
| 10734 |
.ie n .IP """PerlIO_read""" 4 |
| 10735 |
.el .IP \f(CWPerlIO_read\fR 4 |
| 10736 |
.IX Item "PerlIO_read" |
| 10737 |
.ie n .IP """PerlIO_releaseFILE""" 4 |
| 10738 |
.el .IP \f(CWPerlIO_releaseFILE\fR 4 |
| 10739 |
.IX Item "PerlIO_releaseFILE" |
| 10740 |
.ie n .IP """PerlIO_reopen""" 4 |
| 10741 |
.el .IP \f(CWPerlIO_reopen\fR 4 |
| 10742 |
.IX Item "PerlIO_reopen" |
| 10743 |
.ie n .IP """PerlIO_rewind""" 4 |
| 10744 |
.el .IP \f(CWPerlIO_rewind\fR 4 |
| 10745 |
.IX Item "PerlIO_rewind" |
| 10746 |
.ie n .IP """PerlIO_seek""" 4 |
| 10747 |
.el .IP \f(CWPerlIO_seek\fR 4 |
| 10748 |
.IX Item "PerlIO_seek" |
| 10749 |
.ie n .IP """PerlIO_set_cnt""" 4 |
| 10750 |
.el .IP \f(CWPerlIO_set_cnt\fR 4 |
| 10751 |
.IX Item "PerlIO_set_cnt" |
| 10752 |
.ie n .IP """PerlIO_set_ptrcnt""" 4 |
| 10753 |
.el .IP \f(CWPerlIO_set_ptrcnt\fR 4 |
| 10754 |
.IX Item "PerlIO_set_ptrcnt" |
| 10755 |
.ie n .IP """PerlIO_setlinebuf""" 4 |
| 10756 |
.el .IP \f(CWPerlIO_setlinebuf\fR 4 |
| 10757 |
.IX Item "PerlIO_setlinebuf" |
| 10758 |
.ie n .IP """PerlIO_setpos""" 4 |
| 10759 |
.el .IP \f(CWPerlIO_setpos\fR 4 |
| 10760 |
.IX Item "PerlIO_setpos" |
| 10761 |
.ie n .IP """PerlIO_stderr""" 4 |
| 10762 |
.el .IP \f(CWPerlIO_stderr\fR 4 |
| 10763 |
.IX Item "PerlIO_stderr" |
| 10764 |
.ie n .IP """PerlIO_stdin""" 4 |
| 10765 |
.el .IP \f(CWPerlIO_stdin\fR 4 |
| 10766 |
.IX Item "PerlIO_stdin" |
| 10767 |
.ie n .IP """PerlIO_stdout""" 4 |
| 10768 |
.el .IP \f(CWPerlIO_stdout\fR 4 |
| 10769 |
.IX Item "PerlIO_stdout" |
| 10770 |
.ie n .IP """PerlIO_stdoutf""" 4 |
| 10771 |
.el .IP \f(CWPerlIO_stdoutf\fR 4 |
| 10772 |
.IX Item "PerlIO_stdoutf" |
| 10773 |
.ie n .IP """PerlIO_tell""" 4 |
| 10774 |
.el .IP \f(CWPerlIO_tell\fR 4 |
| 10775 |
.IX Item "PerlIO_tell" |
| 10776 |
.ie n .IP """PerlIO_ungetc""" 4 |
| 10777 |
.el .IP \f(CWPerlIO_ungetc\fR 4 |
| 10778 |
.IX Item "PerlIO_ungetc" |
| 10779 |
.ie n .IP """PerlIO_unread""" 4 |
| 10780 |
.el .IP \f(CWPerlIO_unread\fR 4 |
| 10781 |
.IX Item "PerlIO_unread" |
| 10782 |
.ie n .IP """PerlIO_vprintf""" 4 |
| 10783 |
.el .IP \f(CWPerlIO_vprintf\fR 4 |
| 10784 |
.IX Item "PerlIO_vprintf" |
| 10785 |
.ie n .IP """PerlIO_write""" 4 |
| 10786 |
.el .IP \f(CWPerlIO_write\fR 4 |
| 10787 |
.IX Item "PerlIO_write" |
| 10788 |
.PD |
| 10789 |
Described in perlapio. |
| 10790 |
.RS 4 |
| 10791 |
.Sp |
| 10792 |
.Vb 10 |
| 10793 |
\& int PerlIO_apply_layers(PerlIO *f, const char *mode, |
| 10794 |
\& const char *layers) |
| 10795 |
\& int PerlIO_binmode (PerlIO *f, int ptype, int imode, |
| 10796 |
\& const char *layers) |
| 10797 |
\& int PerlIO_canset_cnt (PerlIO *f) |
| 10798 |
\& void PerlIO_clearerr (PerlIO *f) |
| 10799 |
\& int PerlIO_close (PerlIO *f) |
| 10800 |
\& void PerlIO_debug (const char *fmt, ...) |
| 10801 |
\& int PerlIO_eof (PerlIO *f) |
| 10802 |
\& int PerlIO_error (PerlIO *f) |
| 10803 |
\& FILE * PerlIO_exportFILE (PerlIO *f, const char *mode) |
| 10804 |
\& int PerlIO_fast_gets (PerlIO *f) |
| 10805 |
\& PerlIO * PerlIO_fdopen (int fd, const char *mode) |
| 10806 |
\& int PerlIO_fileno (PerlIO *f) |
| 10807 |
\& int PerlIO_fill (PerlIO *f) |
| 10808 |
\& FILE * PerlIO_findFILE (PerlIO *f) |
| 10809 |
\& int PerlIO_flush (PerlIO *f) |
| 10810 |
\& STDCHAR * PerlIO_get_base (PerlIO *f) |
| 10811 |
\& SSize_t PerlIO_get_bufsiz (PerlIO *f) |
| 10812 |
\& SSize_t PerlIO_get_cnt (PerlIO *f) |
| 10813 |
\& STDCHAR * PerlIO_get_ptr (PerlIO *f) |
| 10814 |
\& int PerlIO_getc (PerlIO *d) |
| 10815 |
\& int PerlIO_getpos (PerlIO *f, SV *save) |
| 10816 |
\& int PerlIO_has_base (PerlIO *f) |
| 10817 |
\& int PerlIO_has_cntptr (PerlIO *f) |
| 10818 |
\& PerlIO * PerlIO_importFILE (FILE *stdio, const char *mode) |
| 10819 |
\& PerlIO * PerlIO_open (const char *path, const char *mode) |
| 10820 |
\& int PerlIO_printf (PerlIO *f, const char *fmt, ...) |
| 10821 |
\& int PerlIO_putc (PerlIO *f, int ch) |
| 10822 |
\& int PerlIO_puts (PerlIO *f, const char *string) |
| 10823 |
\& SSize_t PerlIO_read (PerlIO *f, void *vbuf, |
| 10824 |
\& Size_t count) |
| 10825 |
\& void PerlIO_releaseFILE (PerlIO *f, FILE *stdio) |
| 10826 |
\& PerlIO * PerlIO_reopen (const char *path, const char *mode, |
| 10827 |
\& PerlIO *old) |
| 10828 |
\& void PerlIO_rewind (PerlIO *f) |
| 10829 |
\& int PerlIO_seek (PerlIO *f, Off_t offset, |
| 10830 |
\& int whence) |
| 10831 |
\& void PerlIO_set_cnt (PerlIO *f, SSize_t cnt) |
| 10832 |
\& void PerlIO_set_ptrcnt (PerlIO *f, STDCHAR *ptr, |
| 10833 |
\& SSize_t cnt) |
| 10834 |
\& void PerlIO_setlinebuf (PerlIO *f) |
| 10835 |
\& int PerlIO_setpos (PerlIO *f, SV *saved) |
| 10836 |
\& PerlIO * PerlIO_stderr (PerlIO *f, const char *mode, |
| 10837 |
\& const char *layers) |
| 10838 |
\& PerlIO * PerlIO_stdin (PerlIO *f, const char *mode, |
| 10839 |
\& const char *layers) |
| 10840 |
\& PerlIO * PerlIO_stdout (PerlIO *f, const char *mode, |
| 10841 |
\& const char *layers) |
| 10842 |
\& int PerlIO_stdoutf (const char *fmt, ...) |
| 10843 |
\& Off_t PerlIO_tell (PerlIO *f) |
| 10844 |
\& int PerlIO_ungetc (PerlIO *f, int ch) |
| 10845 |
\& SSize_t PerlIO_unread (PerlIO *f, const void *vbuf, |
| 10846 |
\& Size_t count) |
| 10847 |
\& int PerlIO_vprintf (PerlIO *f, const char *fmt, |
| 10848 |
\& va_list args) |
| 10849 |
\& SSize_t PerlIO_write (PerlIO *f, const void *vbuf, |
| 10850 |
\& Size_t count) |
| 10851 |
.Ve |
| 10852 |
.RE |
| 10853 |
.RS 4 |
| 10854 |
.RE |
| 10855 |
.ie n .IP """PERLIO_F_APPEND""" 4 |
| 10856 |
.el .IP \f(CWPERLIO_F_APPEND\fR 4 |
| 10857 |
.IX Item "PERLIO_F_APPEND" |
| 10858 |
.PD 0 |
| 10859 |
.ie n .IP """PERLIO_F_CANREAD""" 4 |
| 10860 |
.el .IP \f(CWPERLIO_F_CANREAD\fR 4 |
| 10861 |
.IX Item "PERLIO_F_CANREAD" |
| 10862 |
.ie n .IP """PERLIO_F_CANWRITE""" 4 |
| 10863 |
.el .IP \f(CWPERLIO_F_CANWRITE\fR 4 |
| 10864 |
.IX Item "PERLIO_F_CANWRITE" |
| 10865 |
.ie n .IP """PERLIO_F_CRLF""" 4 |
| 10866 |
.el .IP \f(CWPERLIO_F_CRLF\fR 4 |
| 10867 |
.IX Item "PERLIO_F_CRLF" |
| 10868 |
.ie n .IP """PERLIO_F_EOF""" 4 |
| 10869 |
.el .IP \f(CWPERLIO_F_EOF\fR 4 |
| 10870 |
.IX Item "PERLIO_F_EOF" |
| 10871 |
.ie n .IP """PERLIO_F_ERROR""" 4 |
| 10872 |
.el .IP \f(CWPERLIO_F_ERROR\fR 4 |
| 10873 |
.IX Item "PERLIO_F_ERROR" |
| 10874 |
.ie n .IP """PERLIO_F_FASTGETS""" 4 |
| 10875 |
.el .IP \f(CWPERLIO_F_FASTGETS\fR 4 |
| 10876 |
.IX Item "PERLIO_F_FASTGETS" |
| 10877 |
.ie n .IP """PERLIO_F_LINEBUF""" 4 |
| 10878 |
.el .IP \f(CWPERLIO_F_LINEBUF\fR 4 |
| 10879 |
.IX Item "PERLIO_F_LINEBUF" |
| 10880 |
.ie n .IP """PERLIO_F_OPEN""" 4 |
| 10881 |
.el .IP \f(CWPERLIO_F_OPEN\fR 4 |
| 10882 |
.IX Item "PERLIO_F_OPEN" |
| 10883 |
.ie n .IP """PERLIO_F_RDBUF""" 4 |
| 10884 |
.el .IP \f(CWPERLIO_F_RDBUF\fR 4 |
| 10885 |
.IX Item "PERLIO_F_RDBUF" |
| 10886 |
.ie n .IP """PERLIO_F_TEMP""" 4 |
| 10887 |
.el .IP \f(CWPERLIO_F_TEMP\fR 4 |
| 10888 |
.IX Item "PERLIO_F_TEMP" |
| 10889 |
.ie n .IP """PERLIO_F_TRUNCATE""" 4 |
| 10890 |
.el .IP \f(CWPERLIO_F_TRUNCATE\fR 4 |
| 10891 |
.IX Item "PERLIO_F_TRUNCATE" |
| 10892 |
.ie n .IP """PERLIO_F_UNBUF""" 4 |
| 10893 |
.el .IP \f(CWPERLIO_F_UNBUF\fR 4 |
| 10894 |
.IX Item "PERLIO_F_UNBUF" |
| 10895 |
.ie n .IP """PERLIO_F_UTF8""" 4 |
| 10896 |
.el .IP \f(CWPERLIO_F_UTF8\fR 4 |
| 10897 |
.IX Item "PERLIO_F_UTF8" |
| 10898 |
.ie n .IP """PERLIO_F_WRBUF""" 4 |
| 10899 |
.el .IP \f(CWPERLIO_F_WRBUF\fR 4 |
| 10900 |
.IX Item "PERLIO_F_WRBUF" |
| 10901 |
.PD |
| 10902 |
Described in perliol. |
| 10903 |
.ie n .IP """PERLIO_FUNCS_CAST""" 4 |
| 10904 |
.el .IP \f(CWPERLIO_FUNCS_CAST\fR 4 |
| 10905 |
.IX Xref "PERLIO_FUNCS_CAST" |
| 10906 |
.IX Item "PERLIO_FUNCS_CAST" |
| 10907 |
Cast the pointer \f(CW\*(C`func\*(C'\fR to be of type \f(CW\*(C`PerlIO_funcs\ *\*(C'\fR. |
| 10908 |
.ie n .IP """PERLIO_FUNCS_DECL""" 4 |
| 10909 |
.el .IP \f(CWPERLIO_FUNCS_DECL\fR 4 |
| 10910 |
.IX Xref "PERLIO_FUNCS_DECL" |
| 10911 |
.IX Item "PERLIO_FUNCS_DECL" |
| 10912 |
Declare \f(CW\*(C`ftab\*(C'\fR to be a PerlIO function table, that is, of type |
| 10913 |
\&\f(CW\*(C`PerlIO_funcs\*(C'\fR. |
| 10914 |
.RS 4 |
| 10915 |
.Sp |
| 10916 |
.Vb 1 |
| 10917 |
\& PERLIO_FUNCS_DECL(PerlIO * ftab) |
| 10918 |
.Ve |
| 10919 |
.RE |
| 10920 |
.RS 4 |
| 10921 |
.RE |
| 10922 |
.ie n .IP """PERLIO_K_BUFFERED""" 4 |
| 10923 |
.el .IP \f(CWPERLIO_K_BUFFERED\fR 4 |
| 10924 |
.IX Item "PERLIO_K_BUFFERED" |
| 10925 |
.PD 0 |
| 10926 |
.ie n .IP """PERLIO_K_CANCRLF""" 4 |
| 10927 |
.el .IP \f(CWPERLIO_K_CANCRLF\fR 4 |
| 10928 |
.IX Item "PERLIO_K_CANCRLF" |
| 10929 |
.ie n .IP """PERLIO_K_FASTGETS""" 4 |
| 10930 |
.el .IP \f(CWPERLIO_K_FASTGETS\fR 4 |
| 10931 |
.IX Item "PERLIO_K_FASTGETS" |
| 10932 |
.ie n .IP """PERLIO_K_MULTIARG""" 4 |
| 10933 |
.el .IP \f(CWPERLIO_K_MULTIARG\fR 4 |
| 10934 |
.IX Item "PERLIO_K_MULTIARG" |
| 10935 |
.ie n .IP """PERLIO_K_RAW""" 4 |
| 10936 |
.el .IP \f(CWPERLIO_K_RAW\fR 4 |
| 10937 |
.IX Item "PERLIO_K_RAW" |
| 10938 |
.PD |
| 10939 |
Described in perliol. |
| 10940 |
.ie n .IP """PERLIO_NOT_STDIO""" 4 |
| 10941 |
.el .IP \f(CWPERLIO_NOT_STDIO\fR 4 |
| 10942 |
.IX Item "PERLIO_NOT_STDIO" |
| 10943 |
Described in perlapio. |
| 10944 |
.ie n .IP """PL_maxsysfd""" 4 |
| 10945 |
.el .IP \f(CWPL_maxsysfd\fR 4 |
| 10946 |
.IX Item "PL_maxsysfd" |
| 10947 |
Described in perliol. |
| 10948 |
.ie n .IP """repeatcpy""" 4 |
| 10949 |
.el .IP \f(CWrepeatcpy\fR 4 |
| 10950 |
.IX Xref "repeatcpy" |
| 10951 |
.IX Item "repeatcpy" |
| 10952 |
Make \f(CW\*(C`count\*(C'\fR copies of the \f(CW\*(C`len\*(C'\fR bytes beginning at \f(CW\*(C`from\*(C'\fR, placing them |
| 10953 |
into memory beginning at \f(CW\*(C`to\*(C'\fR, which must be big enough to accommodate them |
| 10954 |
all. |
| 10955 |
.RS 4 |
| 10956 |
.Sp |
| 10957 |
.Vb 1 |
| 10958 |
\& void repeatcpy(char *to, const char *from, SSize_t len, IV count) |
| 10959 |
.Ve |
| 10960 |
.RE |
| 10961 |
.RS 4 |
| 10962 |
.RE |
| 10963 |
.ie n .IP """USE_STDIO""" 4 |
| 10964 |
.el .IP \f(CWUSE_STDIO\fR 4 |
| 10965 |
.IX Item "USE_STDIO" |
| 10966 |
Described in perlapio. |
| 10967 |
.SH Integer |
| 10968 |
.IX Header "Integer" |
| 10969 |
.ie n .IP """CASTI32""" 4 |
| 10970 |
.el .IP \f(CWCASTI32\fR 4 |
| 10971 |
.IX Xref "CASTI32" |
| 10972 |
.IX Item "CASTI32" |
| 10973 |
This symbol is defined if the C compiler can cast negative |
| 10974 |
or large floating point numbers to 32\-bit ints. |
| 10975 |
.ie n .IP """HAS_INT64_T""" 4 |
| 10976 |
.el .IP \f(CWHAS_INT64_T\fR 4 |
| 10977 |
.IX Xref "HAS_INT64_T" |
| 10978 |
.IX Item "HAS_INT64_T" |
| 10979 |
This symbol will defined if the C compiler supports \f(CW\*(C`int64_t\*(C'\fR. |
| 10980 |
Usually the \fIinttypes.h\fR needs to be included, but sometimes |
| 10981 |
\&\fIsys/types.h\fR is enough. |
| 10982 |
.ie n .IP """HAS_LONG_LONG""" 4 |
| 10983 |
.el .IP \f(CWHAS_LONG_LONG\fR 4 |
| 10984 |
.IX Xref "HAS_LONG_LONG" |
| 10985 |
.IX Item "HAS_LONG_LONG" |
| 10986 |
This symbol will be defined if the C compiler supports long long. |
| 10987 |
.ie n .IP """HAS_QUAD""" 4 |
| 10988 |
.el .IP \f(CWHAS_QUAD\fR 4 |
| 10989 |
.IX Xref "HAS_QUAD" |
| 10990 |
.IX Item "HAS_QUAD" |
| 10991 |
This symbol, if defined, tells that there's a 64\-bit integer type, |
| 10992 |
\&\f(CW\*(C`Quad_t\*(C'\fR, and its unsigned counterpart, \f(CW\*(C`Uquad_t\*(C'\fR. \f(CW\*(C`QUADKIND\*(C'\fR will be one |
| 10993 |
of \f(CW\*(C`QUAD_IS_INT\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_INT64_T\*(C'\fR, |
| 10994 |
or \f(CW\*(C`QUAD_IS_\|_\|_INT64\*(C'\fR. |
| 10995 |
.ie n .IP """I32df""" 4 |
| 10996 |
.el .IP \f(CWI32df\fR 4 |
| 10997 |
.IX Xref "I32df" |
| 10998 |
.IX Item "I32df" |
| 10999 |
This symbol defines the format string used for printing a Perl I32 |
| 11000 |
as a signed decimal integer. |
| 11001 |
.ie n .IP """INT16_C""" 4 |
| 11002 |
.el .IP \f(CWINT16_C\fR 4 |
| 11003 |
.IX Item "INT16_C" |
| 11004 |
.PD 0 |
| 11005 |
.ie n .IP """INT32_C""" 4 |
| 11006 |
.el .IP \f(CWINT32_C\fR 4 |
| 11007 |
.IX Item "INT32_C" |
| 11008 |
.ie n .IP """INT64_C""" 4 |
| 11009 |
.el .IP \f(CWINT64_C\fR 4 |
| 11010 |
.IX Xref "INT16_C INT32_C INT64_C" |
| 11011 |
.IX Item "INT64_C" |
| 11012 |
.PD |
| 11013 |
Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the |
| 11014 |
corresponding integer type on the machine. |
| 11015 |
.Sp |
| 11016 |
If the machine does not have a 64\-bit type, \f(CW\*(C`INT64_C\*(C'\fR is undefined. |
| 11017 |
Use \f(CW"INTMAX_C"\fR to get the largest type available on the platform. |
| 11018 |
.RS 4 |
| 11019 |
.Sp |
| 11020 |
.Vb 3 |
| 11021 |
\& I16 INT16_C(number) |
| 11022 |
\& I32 INT32_C(number) |
| 11023 |
\& I64 INT64_C(number) |
| 11024 |
.Ve |
| 11025 |
.RE |
| 11026 |
.RS 4 |
| 11027 |
.RE |
| 11028 |
.ie n .IP """INTMAX_C""" 4 |
| 11029 |
.el .IP \f(CWINTMAX_C\fR 4 |
| 11030 |
.IX Xref "INTMAX_C" |
| 11031 |
.IX Item "INTMAX_C" |
| 11032 |
Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the |
| 11033 |
widest integer type on the machine. For example, if the machine has \f(CW\*(C`long |
| 11034 |
long\*(C'\fRs, \f(CWINTMAX_C(\-1)\fR would yield |
| 11035 |
.Sp |
| 11036 |
.Vb 1 |
| 11037 |
\& \-1LL |
| 11038 |
.Ve |
| 11039 |
.Sp |
| 11040 |
See also, for example, \f(CW"INT32_C"\fR. |
| 11041 |
.Sp |
| 11042 |
Use "IV" to declare variables of the maximum usable size on this platform. |
| 11043 |
.RS 4 |
| 11044 |
.Sp |
| 11045 |
.Vb 1 |
| 11046 |
\& INTMAX_C(number) |
| 11047 |
.Ve |
| 11048 |
.RE |
| 11049 |
.RS 4 |
| 11050 |
.RE |
| 11051 |
.ie n .IP """INTSIZE""" 4 |
| 11052 |
.el .IP \f(CWINTSIZE\fR 4 |
| 11053 |
.IX Xref "INTSIZE" |
| 11054 |
.IX Item "INTSIZE" |
| 11055 |
This symbol contains the value of \f(CWsizeof(int)\fR so that the C |
| 11056 |
preprocessor can make decisions based on it. |
| 11057 |
.ie n .IP """I8SIZE""" 4 |
| 11058 |
.el .IP \f(CWI8SIZE\fR 4 |
| 11059 |
.IX Xref "I8SIZE" |
| 11060 |
.IX Item "I8SIZE" |
| 11061 |
This symbol contains the \f(CWsizeof(I8)\fR. |
| 11062 |
.ie n .IP """I16SIZE""" 4 |
| 11063 |
.el .IP \f(CWI16SIZE\fR 4 |
| 11064 |
.IX Xref "I16SIZE" |
| 11065 |
.IX Item "I16SIZE" |
| 11066 |
This symbol contains the \f(CWsizeof(I16)\fR. |
| 11067 |
.ie n .IP """I32SIZE""" 4 |
| 11068 |
.el .IP \f(CWI32SIZE\fR 4 |
| 11069 |
.IX Xref "I32SIZE" |
| 11070 |
.IX Item "I32SIZE" |
| 11071 |
This symbol contains the \f(CWsizeof(I32)\fR. |
| 11072 |
.ie n .IP """I64SIZE""" 4 |
| 11073 |
.el .IP \f(CWI64SIZE\fR 4 |
| 11074 |
.IX Xref "I64SIZE" |
| 11075 |
.IX Item "I64SIZE" |
| 11076 |
This symbol contains the \f(CWsizeof(I64)\fR. |
| 11077 |
.ie n .IP """I8TYPE""" 4 |
| 11078 |
.el .IP \f(CWI8TYPE\fR 4 |
| 11079 |
.IX Xref "I8TYPE" |
| 11080 |
.IX Item "I8TYPE" |
| 11081 |
This symbol defines the C type used for Perl's I8. |
| 11082 |
.ie n .IP """I16TYPE""" 4 |
| 11083 |
.el .IP \f(CWI16TYPE\fR 4 |
| 11084 |
.IX Xref "I16TYPE" |
| 11085 |
.IX Item "I16TYPE" |
| 11086 |
This symbol defines the C type used for Perl's I16. |
| 11087 |
.ie n .IP """I32TYPE""" 4 |
| 11088 |
.el .IP \f(CWI32TYPE\fR 4 |
| 11089 |
.IX Xref "I32TYPE" |
| 11090 |
.IX Item "I32TYPE" |
| 11091 |
This symbol defines the C type used for Perl's I32. |
| 11092 |
.ie n .IP """I64TYPE""" 4 |
| 11093 |
.el .IP \f(CWI64TYPE\fR 4 |
| 11094 |
.IX Xref "I64TYPE" |
| 11095 |
.IX Item "I64TYPE" |
| 11096 |
This symbol defines the C type used for Perl's I64. |
| 11097 |
.ie n .IP """IV""" 4 |
| 11098 |
.el .IP \f(CWIV\fR 4 |
| 11099 |
.IX Item "IV" |
| 11100 |
.PD 0 |
| 11101 |
.ie n .IP """I8""" 4 |
| 11102 |
.el .IP \f(CWI8\fR 4 |
| 11103 |
.IX Item "I8" |
| 11104 |
.ie n .IP """I16""" 4 |
| 11105 |
.el .IP \f(CWI16\fR 4 |
| 11106 |
.IX Item "I16" |
| 11107 |
.ie n .IP """I32""" 4 |
| 11108 |
.el .IP \f(CWI32\fR 4 |
| 11109 |
.IX Item "I32" |
| 11110 |
.ie n .IP """I64""" 4 |
| 11111 |
.el .IP \f(CWI64\fR 4 |
| 11112 |
.IX Item "I64" |
| 11113 |
.PD |
| 11114 |
Described in perlguts. |
| 11115 |
.ie n .IP """IV_MAX""" 4 |
| 11116 |
.el .IP \f(CWIV_MAX\fR 4 |
| 11117 |
.IX Xref "IV_MAX" |
| 11118 |
.IX Item "IV_MAX" |
| 11119 |
The largest signed integer that fits in an IV on this platform. |
| 11120 |
.RS 4 |
| 11121 |
.Sp |
| 11122 |
.Vb 1 |
| 11123 |
\& IV IV_MAX |
| 11124 |
.Ve |
| 11125 |
.RE |
| 11126 |
.RS 4 |
| 11127 |
.RE |
| 11128 |
.ie n .IP """IV_MIN""" 4 |
| 11129 |
.el .IP \f(CWIV_MIN\fR 4 |
| 11130 |
.IX Xref "IV_MIN" |
| 11131 |
.IX Item "IV_MIN" |
| 11132 |
The negative signed integer furthest away from 0 that fits in an IV on this |
| 11133 |
platform. |
| 11134 |
.RS 4 |
| 11135 |
.Sp |
| 11136 |
.Vb 1 |
| 11137 |
\& IV IV_MIN |
| 11138 |
.Ve |
| 11139 |
.RE |
| 11140 |
.RS 4 |
| 11141 |
.RE |
| 11142 |
.ie n .IP """IVSIZE""" 4 |
| 11143 |
.el .IP \f(CWIVSIZE\fR 4 |
| 11144 |
.IX Xref "IVSIZE" |
| 11145 |
.IX Item "IVSIZE" |
| 11146 |
This symbol contains the \f(CWsizeof(IV)\fR. |
| 11147 |
.ie n .IP """IVTYPE""" 4 |
| 11148 |
.el .IP \f(CWIVTYPE\fR 4 |
| 11149 |
.IX Xref "IVTYPE" |
| 11150 |
.IX Item "IVTYPE" |
| 11151 |
This symbol defines the C type used for Perl's IV. |
| 11152 |
.ie n .IP """line_t""" 4 |
| 11153 |
.el .IP \f(CWline_t\fR 4 |
| 11154 |
.IX Xref "line_t" |
| 11155 |
.IX Item "line_t" |
| 11156 |
The typedef to use to declare variables that are to hold line numbers. |
| 11157 |
.ie n .IP """LONGLONGSIZE""" 4 |
| 11158 |
.el .IP \f(CWLONGLONGSIZE\fR 4 |
| 11159 |
.IX Xref "LONGLONGSIZE" |
| 11160 |
.IX Item "LONGLONGSIZE" |
| 11161 |
This symbol contains the size of a long long, so that the |
| 11162 |
C preprocessor can make decisions based on it. It is only |
| 11163 |
defined if the system supports long long. |
| 11164 |
.ie n .IP """LONGSIZE""" 4 |
| 11165 |
.el .IP \f(CWLONGSIZE\fR 4 |
| 11166 |
.IX Xref "LONGSIZE" |
| 11167 |
.IX Item "LONGSIZE" |
| 11168 |
This symbol contains the value of \f(CWsizeof(long)\fR so that the C |
| 11169 |
preprocessor can make decisions based on it. |
| 11170 |
.ie n .IP """memzero""" 4 |
| 11171 |
.el .IP \f(CWmemzero\fR 4 |
| 11172 |
.IX Xref "memzero" |
| 11173 |
.IX Item "memzero" |
| 11174 |
Set the \f(CW\*(C`l\*(C'\fR bytes starting at \f(CW*d\fR to all zeroes. |
| 11175 |
.RS 4 |
| 11176 |
.Sp |
| 11177 |
.Vb 1 |
| 11178 |
\& void memzero(void * d, Size_t l) |
| 11179 |
.Ve |
| 11180 |
.RE |
| 11181 |
.RS 4 |
| 11182 |
.RE |
| 11183 |
.ie n .IP """PERL_INT_FAST8_T""" 4 |
| 11184 |
.el .IP \f(CWPERL_INT_FAST8_T\fR 4 |
| 11185 |
.IX Item "PERL_INT_FAST8_T" |
| 11186 |
.PD 0 |
| 11187 |
.ie n .IP """PERL_INT_FAST16_T""" 4 |
| 11188 |
.el .IP \f(CWPERL_INT_FAST16_T\fR 4 |
| 11189 |
.IX Item "PERL_INT_FAST16_T" |
| 11190 |
.ie n .IP """PERL_UINT_FAST8_T""" 4 |
| 11191 |
.el .IP \f(CWPERL_UINT_FAST8_T\fR 4 |
| 11192 |
.IX Item "PERL_UINT_FAST8_T" |
| 11193 |
.ie n .IP """PERL_UINT_FAST16_T""" 4 |
| 11194 |
.el .IP \f(CWPERL_UINT_FAST16_T\fR 4 |
| 11195 |
.IX Xref "PERL_INT_FAST8_T PERL_INT_FAST16_T PERL_UINT_FAST8_T PERL_UINT_FAST16_T" |
| 11196 |
.IX Item "PERL_UINT_FAST16_T" |
| 11197 |
.PD |
| 11198 |
These are equivalent to the correspondingly-named C99 typedefs on platforms |
| 11199 |
that have those; they evaluate to \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`unsigned int\*(C'\fR on platforms that |
| 11200 |
don't, so that you can portably take advantage of this C99 feature. |
| 11201 |
.ie n .IP """PERL_INT_MAX""" 4 |
| 11202 |
.el .IP \f(CWPERL_INT_MAX\fR 4 |
| 11203 |
.IX Item "PERL_INT_MAX" |
| 11204 |
.PD 0 |
| 11205 |
.ie n .IP """PERL_INT_MIN""" 4 |
| 11206 |
.el .IP \f(CWPERL_INT_MIN\fR 4 |
| 11207 |
.IX Item "PERL_INT_MIN" |
| 11208 |
.ie n .IP """PERL_LONG_MAX""" 4 |
| 11209 |
.el .IP \f(CWPERL_LONG_MAX\fR 4 |
| 11210 |
.IX Item "PERL_LONG_MAX" |
| 11211 |
.ie n .IP """PERL_LONG_MIN""" 4 |
| 11212 |
.el .IP \f(CWPERL_LONG_MIN\fR 4 |
| 11213 |
.IX Item "PERL_LONG_MIN" |
| 11214 |
.ie n .IP """PERL_QUAD_MAX""" 4 |
| 11215 |
.el .IP \f(CWPERL_QUAD_MAX\fR 4 |
| 11216 |
.IX Item "PERL_QUAD_MAX" |
| 11217 |
.ie n .IP """PERL_QUAD_MIN""" 4 |
| 11218 |
.el .IP \f(CWPERL_QUAD_MIN\fR 4 |
| 11219 |
.IX Item "PERL_QUAD_MIN" |
| 11220 |
.ie n .IP """PERL_SHORT_MAX""" 4 |
| 11221 |
.el .IP \f(CWPERL_SHORT_MAX\fR 4 |
| 11222 |
.IX Item "PERL_SHORT_MAX" |
| 11223 |
.ie n .IP """PERL_SHORT_MIN""" 4 |
| 11224 |
.el .IP \f(CWPERL_SHORT_MIN\fR 4 |
| 11225 |
.IX Item "PERL_SHORT_MIN" |
| 11226 |
.ie n .IP """PERL_UCHAR_MAX""" 4 |
| 11227 |
.el .IP \f(CWPERL_UCHAR_MAX\fR 4 |
| 11228 |
.IX Item "PERL_UCHAR_MAX" |
| 11229 |
.ie n .IP """PERL_UCHAR_MIN""" 4 |
| 11230 |
.el .IP \f(CWPERL_UCHAR_MIN\fR 4 |
| 11231 |
.IX Item "PERL_UCHAR_MIN" |
| 11232 |
.ie n .IP """PERL_UINT_MAX""" 4 |
| 11233 |
.el .IP \f(CWPERL_UINT_MAX\fR 4 |
| 11234 |
.IX Item "PERL_UINT_MAX" |
| 11235 |
.ie n .IP """PERL_UINT_MIN""" 4 |
| 11236 |
.el .IP \f(CWPERL_UINT_MIN\fR 4 |
| 11237 |
.IX Item "PERL_UINT_MIN" |
| 11238 |
.ie n .IP """PERL_ULONG_MAX""" 4 |
| 11239 |
.el .IP \f(CWPERL_ULONG_MAX\fR 4 |
| 11240 |
.IX Item "PERL_ULONG_MAX" |
| 11241 |
.ie n .IP """PERL_ULONG_MIN""" 4 |
| 11242 |
.el .IP \f(CWPERL_ULONG_MIN\fR 4 |
| 11243 |
.IX Item "PERL_ULONG_MIN" |
| 11244 |
.ie n .IP """PERL_UQUAD_MAX""" 4 |
| 11245 |
.el .IP \f(CWPERL_UQUAD_MAX\fR 4 |
| 11246 |
.IX Item "PERL_UQUAD_MAX" |
| 11247 |
.ie n .IP """PERL_UQUAD_MIN""" 4 |
| 11248 |
.el .IP \f(CWPERL_UQUAD_MIN\fR 4 |
| 11249 |
.IX Item "PERL_UQUAD_MIN" |
| 11250 |
.ie n .IP """PERL_USHORT_MAX""" 4 |
| 11251 |
.el .IP \f(CWPERL_USHORT_MAX\fR 4 |
| 11252 |
.IX Item "PERL_USHORT_MAX" |
| 11253 |
.ie n .IP """PERL_USHORT_MIN""" 4 |
| 11254 |
.el .IP \f(CWPERL_USHORT_MIN\fR 4 |
| 11255 |
.IX Xref "PERL_INT_MAX PERL_INT_MIN PERL_LONG_MAX PERL_LONG_MIN PERL_QUAD_MAX PERL_QUAD_MIN PERL_SHORT_MAX PERL_SHORT_MIN PERL_UCHAR_MAX PERL_UCHAR_MIN PERL_UINT_MAX PERL_UINT_MIN PERL_ULONG_MAX PERL_ULONG_MIN PERL_UQUAD_MAX PERL_UQUAD_MIN PERL_USHORT_MAX PERL_USHORT_MIN" |
| 11256 |
.IX Item "PERL_USHORT_MIN" |
| 11257 |
.PD |
| 11258 |
These give the largest and smallest number representable in the current |
| 11259 |
platform in variables of the corresponding types. |
| 11260 |
.Sp |
| 11261 |
For signed types, the smallest representable number is the most negative |
| 11262 |
number, the one furthest away from zero. |
| 11263 |
.Sp |
| 11264 |
For C99 and later compilers, these correspond to things like \f(CW\*(C`INT_MAX\*(C'\fR, which |
| 11265 |
are available to the C code. But these constants, furnished by Perl, |
| 11266 |
allow code compiled on earlier compilers to portably have access to the same |
| 11267 |
constants. |
| 11268 |
.RS 4 |
| 11269 |
.Sp |
| 11270 |
.Vb 10 |
| 11271 |
\& int PERL_INT_MAX |
| 11272 |
\& int PERL_INT_MIN |
| 11273 |
\& long PERL_LONG_MAX |
| 11274 |
\& long PERL_LONG_MIN |
| 11275 |
\& IV PERL_QUAD_MAX |
| 11276 |
\& IV PERL_QUAD_MIN |
| 11277 |
\& short PERL_SHORT_MAX |
| 11278 |
\& short PERL_SHORT_MIN |
| 11279 |
\& U8 PERL_UCHAR_MAX |
| 11280 |
\& U8 PERL_UCHAR_MIN |
| 11281 |
\& unsigned int PERL_UINT_MAX |
| 11282 |
\& unsigned int PERL_UINT_MIN |
| 11283 |
\& unsigned long PERL_ULONG_MAX |
| 11284 |
\& unsigned long PERL_ULONG_MIN |
| 11285 |
\& UV PERL_UQUAD_MAX |
| 11286 |
\& UV PERL_UQUAD_MIN |
| 11287 |
\& unsigned short PERL_USHORT_MAX |
| 11288 |
\& unsigned short PERL_USHORT_MIN |
| 11289 |
.Ve |
| 11290 |
.RE |
| 11291 |
.RS 4 |
| 11292 |
.RE |
| 11293 |
.ie n .IP """SHORTSIZE""" 4 |
| 11294 |
.el .IP \f(CWSHORTSIZE\fR 4 |
| 11295 |
.IX Xref "SHORTSIZE" |
| 11296 |
.IX Item "SHORTSIZE" |
| 11297 |
This symbol contains the value of \f(CWsizeof(short)\fR so that the C |
| 11298 |
preprocessor can make decisions based on it. |
| 11299 |
.ie n .IP """UINT16_C""" 4 |
| 11300 |
.el .IP \f(CWUINT16_C\fR 4 |
| 11301 |
.IX Item "UINT16_C" |
| 11302 |
.PD 0 |
| 11303 |
.ie n .IP """UINT32_C""" 4 |
| 11304 |
.el .IP \f(CWUINT32_C\fR 4 |
| 11305 |
.IX Item "UINT32_C" |
| 11306 |
.ie n .IP """UINT64_C""" 4 |
| 11307 |
.el .IP \f(CWUINT64_C\fR 4 |
| 11308 |
.IX Xref "UINT16_C UINT32_C UINT64_C" |
| 11309 |
.IX Item "UINT64_C" |
| 11310 |
.PD |
| 11311 |
Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the |
| 11312 |
corresponding unsigned integer type on the machine. |
| 11313 |
.Sp |
| 11314 |
If the machine does not have a 64\-bit type, \f(CW\*(C`UINT64_C\*(C'\fR is undefined. |
| 11315 |
Use \f(CW"UINTMAX_C"\fR to get the largest type available on the platform. |
| 11316 |
.RS 4 |
| 11317 |
.Sp |
| 11318 |
.Vb 3 |
| 11319 |
\& U16 UINT16_C(number) |
| 11320 |
\& U32 UINT32_C(number) |
| 11321 |
\& U64 UINT64_C(number) |
| 11322 |
.Ve |
| 11323 |
.RE |
| 11324 |
.RS 4 |
| 11325 |
.RE |
| 11326 |
.ie n .IP """UINTMAX_C""" 4 |
| 11327 |
.el .IP \f(CWUINTMAX_C\fR 4 |
| 11328 |
.IX Xref "UINTMAX_C" |
| 11329 |
.IX Item "UINTMAX_C" |
| 11330 |
Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the |
| 11331 |
widest unsigned integer type on the machine. For example, if the machine has |
| 11332 |
\&\f(CW\*(C`long\*(C'\fRs, \f(CWUINTMAX_C(1)\fR would yield |
| 11333 |
.Sp |
| 11334 |
.Vb 1 |
| 11335 |
\& 1UL |
| 11336 |
.Ve |
| 11337 |
.Sp |
| 11338 |
See also, for example, \f(CW"UINT32_C"\fR. |
| 11339 |
.Sp |
| 11340 |
Use "UV" to declare variables of the maximum usable size on this platform. |
| 11341 |
.RS 4 |
| 11342 |
.Sp |
| 11343 |
.Vb 1 |
| 11344 |
\& UINTMAX_C(number) |
| 11345 |
.Ve |
| 11346 |
.RE |
| 11347 |
.RS 4 |
| 11348 |
.RE |
| 11349 |
.ie n .IP """U32of""" 4 |
| 11350 |
.el .IP \f(CWU32of\fR 4 |
| 11351 |
.IX Xref "U32of" |
| 11352 |
.IX Item "U32of" |
| 11353 |
This symbol defines the format string used for printing a Perl U32 |
| 11354 |
as an unsigned octal integer. |
| 11355 |
.ie n .IP """U8SIZE""" 4 |
| 11356 |
.el .IP \f(CWU8SIZE\fR 4 |
| 11357 |
.IX Xref "U8SIZE" |
| 11358 |
.IX Item "U8SIZE" |
| 11359 |
This symbol contains the \f(CWsizeof(U8)\fR. |
| 11360 |
.ie n .IP """U16SIZE""" 4 |
| 11361 |
.el .IP \f(CWU16SIZE\fR 4 |
| 11362 |
.IX Xref "U16SIZE" |
| 11363 |
.IX Item "U16SIZE" |
| 11364 |
This symbol contains the \f(CWsizeof(U16)\fR. |
| 11365 |
.ie n .IP """U32SIZE""" 4 |
| 11366 |
.el .IP \f(CWU32SIZE\fR 4 |
| 11367 |
.IX Xref "U32SIZE" |
| 11368 |
.IX Item "U32SIZE" |
| 11369 |
This symbol contains the \f(CWsizeof(U32)\fR. |
| 11370 |
.ie n .IP """U64SIZE""" 4 |
| 11371 |
.el .IP \f(CWU64SIZE\fR 4 |
| 11372 |
.IX Xref "U64SIZE" |
| 11373 |
.IX Item "U64SIZE" |
| 11374 |
This symbol contains the \f(CWsizeof(U64)\fR. |
| 11375 |
.ie n .IP """U8TYPE""" 4 |
| 11376 |
.el .IP \f(CWU8TYPE\fR 4 |
| 11377 |
.IX Xref "U8TYPE" |
| 11378 |
.IX Item "U8TYPE" |
| 11379 |
This symbol defines the C type used for Perl's U8. |
| 11380 |
.ie n .IP """U16TYPE""" 4 |
| 11381 |
.el .IP \f(CWU16TYPE\fR 4 |
| 11382 |
.IX Xref "U16TYPE" |
| 11383 |
.IX Item "U16TYPE" |
| 11384 |
This symbol defines the C type used for Perl's U16. |
| 11385 |
.ie n .IP """U32TYPE""" 4 |
| 11386 |
.el .IP \f(CWU32TYPE\fR 4 |
| 11387 |
.IX Xref "U32TYPE" |
| 11388 |
.IX Item "U32TYPE" |
| 11389 |
This symbol defines the C type used for Perl's U32. |
| 11390 |
.ie n .IP """U64TYPE""" 4 |
| 11391 |
.el .IP \f(CWU64TYPE\fR 4 |
| 11392 |
.IX Xref "U64TYPE" |
| 11393 |
.IX Item "U64TYPE" |
| 11394 |
This symbol defines the C type used for Perl's U64. |
| 11395 |
.ie n .IP """U32uf""" 4 |
| 11396 |
.el .IP \f(CWU32uf\fR 4 |
| 11397 |
.IX Xref "U32uf" |
| 11398 |
.IX Item "U32uf" |
| 11399 |
This symbol defines the format string used for printing a Perl U32 |
| 11400 |
as an unsigned decimal integer. |
| 11401 |
.ie n .IP """UV""" 4 |
| 11402 |
.el .IP \f(CWUV\fR 4 |
| 11403 |
.IX Item "UV" |
| 11404 |
.PD 0 |
| 11405 |
.ie n .IP """U8""" 4 |
| 11406 |
.el .IP \f(CWU8\fR 4 |
| 11407 |
.IX Item "U8" |
| 11408 |
.ie n .IP """U16""" 4 |
| 11409 |
.el .IP \f(CWU16\fR 4 |
| 11410 |
.IX Item "U16" |
| 11411 |
.ie n .IP """U32""" 4 |
| 11412 |
.el .IP \f(CWU32\fR 4 |
| 11413 |
.IX Item "U32" |
| 11414 |
.ie n .IP """U64""" 4 |
| 11415 |
.el .IP \f(CWU64\fR 4 |
| 11416 |
.IX Item "U64" |
| 11417 |
.PD |
| 11418 |
Described in perlguts. |
| 11419 |
.ie n .IP """UV_MAX""" 4 |
| 11420 |
.el .IP \f(CWUV_MAX\fR 4 |
| 11421 |
.IX Xref "UV_MAX" |
| 11422 |
.IX Item "UV_MAX" |
| 11423 |
The largest unsigned integer that fits in a UV on this platform. |
| 11424 |
.RS 4 |
| 11425 |
.Sp |
| 11426 |
.Vb 1 |
| 11427 |
\& UV UV_MAX |
| 11428 |
.Ve |
| 11429 |
.RE |
| 11430 |
.RS 4 |
| 11431 |
.RE |
| 11432 |
.ie n .IP """UV_MIN""" 4 |
| 11433 |
.el .IP \f(CWUV_MIN\fR 4 |
| 11434 |
.IX Xref "UV_MIN" |
| 11435 |
.IX Item "UV_MIN" |
| 11436 |
The smallest unsigned integer that fits in a UV on this platform. It should |
| 11437 |
equal zero. |
| 11438 |
.RS 4 |
| 11439 |
.Sp |
| 11440 |
.Vb 1 |
| 11441 |
\& UV UV_MIN |
| 11442 |
.Ve |
| 11443 |
.RE |
| 11444 |
.RS 4 |
| 11445 |
.RE |
| 11446 |
.ie n .IP """UVSIZE""" 4 |
| 11447 |
.el .IP \f(CWUVSIZE\fR 4 |
| 11448 |
.IX Xref "UVSIZE" |
| 11449 |
.IX Item "UVSIZE" |
| 11450 |
This symbol contains the \f(CWsizeof(UV)\fR. |
| 11451 |
.ie n .IP """UVTYPE""" 4 |
| 11452 |
.el .IP \f(CWUVTYPE\fR 4 |
| 11453 |
.IX Xref "UVTYPE" |
| 11454 |
.IX Item "UVTYPE" |
| 11455 |
This symbol defines the C type used for Perl's UV. |
| 11456 |
.ie n .IP """U32Xf""" 4 |
| 11457 |
.el .IP \f(CWU32Xf\fR 4 |
| 11458 |
.IX Xref "U32Xf" |
| 11459 |
.IX Item "U32Xf" |
| 11460 |
This symbol defines the format string used for printing a Perl U32 |
| 11461 |
as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR. |
| 11462 |
.ie n .IP """U32xf""" 4 |
| 11463 |
.el .IP \f(CWU32xf\fR 4 |
| 11464 |
.IX Xref "U32xf" |
| 11465 |
.IX Item "U32xf" |
| 11466 |
This symbol defines the format string used for printing a Perl U32 |
| 11467 |
as an unsigned hexadecimal integer in lowercase abcdef. |
| 11468 |
.ie n .IP """WIDEST_UTYPE""" 4 |
| 11469 |
.el .IP \f(CWWIDEST_UTYPE\fR 4 |
| 11470 |
.IX Xref "WIDEST_UTYPE" |
| 11471 |
.IX Item "WIDEST_UTYPE" |
| 11472 |
Yields the widest unsigned integer type on the platform, currently either |
| 11473 |
\&\f(CW\*(C`U32\*(C'\fR or \f(CW\*(C`U64\*(C'\fR. This can be used in declarations such as |
| 11474 |
.Sp |
| 11475 |
.Vb 1 |
| 11476 |
\& WIDEST_UTYPE my_uv; |
| 11477 |
.Ve |
| 11478 |
.Sp |
| 11479 |
or casts |
| 11480 |
.Sp |
| 11481 |
.Vb 1 |
| 11482 |
\& my_uv = (WIDEST_UTYPE) val; |
| 11483 |
.Ve |
| 11484 |
.SH "I/O Formats" |
| 11485 |
.IX Header "I/O Formats" |
| 11486 |
These are used for formatting the corresponding type For example, |
| 11487 |
instead of saying |
| 11488 |
.PP |
| 11489 |
.Vb 1 |
| 11490 |
\& Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\en", iv); |
| 11491 |
.Ve |
| 11492 |
.PP |
| 11493 |
use |
| 11494 |
.PP |
| 11495 |
.Vb 1 |
| 11496 |
\& Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\en", iv); |
| 11497 |
.Ve |
| 11498 |
.PP |
| 11499 |
This keeps you from having to know if, say an IV, needs to be |
| 11500 |
printed as \f(CW%d\fR, \f(CW%ld\fR, or something else. |
| 11501 |
.ie n .IP """HvNAMEf""" 4 |
| 11502 |
.el .IP \f(CWHvNAMEf\fR 4 |
| 11503 |
.IX Item "HvNAMEf" |
| 11504 |
Described in perlguts. |
| 11505 |
.ie n .IP """HvNAMEf_QUOTEDPREFIX""" 4 |
| 11506 |
.el .IP \f(CWHvNAMEf_QUOTEDPREFIX\fR 4 |
| 11507 |
.IX Item "HvNAMEf_QUOTEDPREFIX" |
| 11508 |
Described in perlguts. |
| 11509 |
.ie n .IP """IVdf""" 4 |
| 11510 |
.el .IP \f(CWIVdf\fR 4 |
| 11511 |
.IX Xref "IVdf" |
| 11512 |
.IX Item "IVdf" |
| 11513 |
This symbol defines the format string used for printing a Perl IV |
| 11514 |
as a signed decimal integer. |
| 11515 |
.ie n .IP """NVef""" 4 |
| 11516 |
.el .IP \f(CWNVef\fR 4 |
| 11517 |
.IX Xref "NVef" |
| 11518 |
.IX Item "NVef" |
| 11519 |
This symbol defines the format string used for printing a Perl NV |
| 11520 |
using \f(CW%e\fR\-ish floating point format. |
| 11521 |
.ie n .IP """NVff""" 4 |
| 11522 |
.el .IP \f(CWNVff\fR 4 |
| 11523 |
.IX Xref "NVff" |
| 11524 |
.IX Item "NVff" |
| 11525 |
This symbol defines the format string used for printing a Perl NV |
| 11526 |
using \f(CW%f\fR\-ish floating point format. |
| 11527 |
.ie n .IP """NVgf""" 4 |
| 11528 |
.el .IP \f(CWNVgf\fR 4 |
| 11529 |
.IX Xref "NVgf" |
| 11530 |
.IX Item "NVgf" |
| 11531 |
This symbol defines the format string used for printing a Perl NV |
| 11532 |
using \f(CW%g\fR\-ish floating point format. |
| 11533 |
.ie n .IP """PERL_PRIeldbl""" 4 |
| 11534 |
.el .IP \f(CWPERL_PRIeldbl\fR 4 |
| 11535 |
.IX Xref "PERL_PRIeldbl" |
| 11536 |
.IX Item "PERL_PRIeldbl" |
| 11537 |
This symbol, if defined, contains the string used by stdio to |
| 11538 |
format long doubles (format 'e') for output. |
| 11539 |
.ie n .IP """PERL_PRIfldbl""" 4 |
| 11540 |
.el .IP \f(CWPERL_PRIfldbl\fR 4 |
| 11541 |
.IX Xref "PERL_PRIfldbl" |
| 11542 |
.IX Item "PERL_PRIfldbl" |
| 11543 |
This symbol, if defined, contains the string used by stdio to |
| 11544 |
format long doubles (format 'f') for output. |
| 11545 |
.ie n .IP """PERL_PRIgldbl""" 4 |
| 11546 |
.el .IP \f(CWPERL_PRIgldbl\fR 4 |
| 11547 |
.IX Xref "PERL_PRIgldbl" |
| 11548 |
.IX Item "PERL_PRIgldbl" |
| 11549 |
This symbol, if defined, contains the string used by stdio to |
| 11550 |
format long doubles (format 'g') for output. |
| 11551 |
.ie n .IP """PERL_SCNfldbl""" 4 |
| 11552 |
.el .IP \f(CWPERL_SCNfldbl\fR 4 |
| 11553 |
.IX Xref "PERL_SCNfldbl" |
| 11554 |
.IX Item "PERL_SCNfldbl" |
| 11555 |
This symbol, if defined, contains the string used by stdio to |
| 11556 |
format long doubles (format 'f') for input. |
| 11557 |
.ie n .IP """PRINTF_FORMAT_NULL_OK""" 4 |
| 11558 |
.el .IP \f(CWPRINTF_FORMAT_NULL_OK\fR 4 |
| 11559 |
.IX Xref "PRINTF_FORMAT_NULL_OK" |
| 11560 |
.IX Item "PRINTF_FORMAT_NULL_OK" |
| 11561 |
Allows \f(CW\*(C`_\|_printf_\|_\*(C'\fR format to be null when checking printf-style |
| 11562 |
.ie n .IP """SVf""" 4 |
| 11563 |
.el .IP \f(CWSVf\fR 4 |
| 11564 |
.IX Item "SVf" |
| 11565 |
Described in perlguts. |
| 11566 |
.ie n .IP """SVfARG""" 4 |
| 11567 |
.el .IP \f(CWSVfARG\fR 4 |
| 11568 |
.IX Item "SVfARG" |
| 11569 |
Described in perlguts. |
| 11570 |
.RS 4 |
| 11571 |
.Sp |
| 11572 |
.Vb 1 |
| 11573 |
\& SVfARG(SV *sv) |
| 11574 |
.Ve |
| 11575 |
.RE |
| 11576 |
.RS 4 |
| 11577 |
.RE |
| 11578 |
.ie n .IP """SVf_QUOTEDPREFIX""" 4 |
| 11579 |
.el .IP \f(CWSVf_QUOTEDPREFIX\fR 4 |
| 11580 |
.IX Item "SVf_QUOTEDPREFIX" |
| 11581 |
Described in perlguts. |
| 11582 |
.ie n .IP """UTF8f""" 4 |
| 11583 |
.el .IP \f(CWUTF8f\fR 4 |
| 11584 |
.IX Item "UTF8f" |
| 11585 |
Described in perlguts. |
| 11586 |
.ie n .IP """UTF8fARG""" 4 |
| 11587 |
.el .IP \f(CWUTF8fARG\fR 4 |
| 11588 |
.IX Item "UTF8fARG" |
| 11589 |
Described in perlguts. |
| 11590 |
.RS 4 |
| 11591 |
.Sp |
| 11592 |
.Vb 1 |
| 11593 |
\& UTF8fARG(bool is_utf8, Size_t byte_len, char *str) |
| 11594 |
.Ve |
| 11595 |
.RE |
| 11596 |
.RS 4 |
| 11597 |
.RE |
| 11598 |
.ie n .IP """UTF8f_QUOTEDPREFIX""" 4 |
| 11599 |
.el .IP \f(CWUTF8f_QUOTEDPREFIX\fR 4 |
| 11600 |
.IX Item "UTF8f_QUOTEDPREFIX" |
| 11601 |
Described in perlguts. |
| 11602 |
.ie n .IP """UVf""" 4 |
| 11603 |
.el .IP \f(CWUVf\fR 4 |
| 11604 |
.IX Xref "UVf" |
| 11605 |
.IX Item "UVf" |
| 11606 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`UVf\*(C'\fR |
| 11607 |
from a future release of Perl. Do not use it for |
| 11608 |
new code; remove it from existing code. |
| 11609 |
.Sp |
| 11610 |
Obsolete form of \f(CW\*(C`UVuf\*(C'\fR, which you should convert to instead use |
| 11611 |
.RS 4 |
| 11612 |
.Sp |
| 11613 |
.Vb 1 |
| 11614 |
\& const char * UVf |
| 11615 |
.Ve |
| 11616 |
.RE |
| 11617 |
.RS 4 |
| 11618 |
.RE |
| 11619 |
.ie n .IP """UVof""" 4 |
| 11620 |
.el .IP \f(CWUVof\fR 4 |
| 11621 |
.IX Xref "UVof" |
| 11622 |
.IX Item "UVof" |
| 11623 |
This symbol defines the format string used for printing a Perl UV |
| 11624 |
as an unsigned octal integer. |
| 11625 |
.ie n .IP """UVuf""" 4 |
| 11626 |
.el .IP \f(CWUVuf\fR 4 |
| 11627 |
.IX Xref "UVuf" |
| 11628 |
.IX Item "UVuf" |
| 11629 |
This symbol defines the format string used for printing a Perl UV |
| 11630 |
as an unsigned decimal integer. |
| 11631 |
.ie n .IP """UVXf""" 4 |
| 11632 |
.el .IP \f(CWUVXf\fR 4 |
| 11633 |
.IX Xref "UVXf" |
| 11634 |
.IX Item "UVXf" |
| 11635 |
This symbol defines the format string used for printing a Perl UV |
| 11636 |
as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR. |
| 11637 |
.ie n .IP """UVxf""" 4 |
| 11638 |
.el .IP \f(CWUVxf\fR 4 |
| 11639 |
.IX Xref "UVxf" |
| 11640 |
.IX Item "UVxf" |
| 11641 |
This symbol defines the format string used for printing a Perl UV |
| 11642 |
as an unsigned hexadecimal integer in lowercase abcdef. |
| 11643 |
.SH "Lexer interface" |
| 11644 |
.IX Xref "LEX_KEEP_PREVIOUS LEX_STUFF_UTF8 PARSE_OPTIONAL" |
| 11645 |
.IX Header "Lexer interface" |
| 11646 |
This is the lower layer of the Perl parser, managing characters and tokens. |
| 11647 |
.ie n .IP """BHK""" 4 |
| 11648 |
.el .IP \f(CWBHK\fR 4 |
| 11649 |
.IX Item "BHK" |
| 11650 |
Described in perlguts. |
| 11651 |
.ie n .IP """lex_bufutf8""" 4 |
| 11652 |
.el .IP \f(CWlex_bufutf8\fR 4 |
| 11653 |
.IX Xref "lex_bufutf8" |
| 11654 |
.IX Item "lex_bufutf8" |
| 11655 |
NOTE: \f(CW\*(C`lex_bufutf8\*(C'\fR is \fBexperimental\fR and may change or be |
| 11656 |
removed without notice. |
| 11657 |
.Sp |
| 11658 |
Indicates whether the octets in the lexer buffer |
| 11659 |
("PL_parser\->linestr") should be interpreted as the UTF\-8 encoding |
| 11660 |
of Unicode characters. If not, they should be interpreted as Latin\-1 |
| 11661 |
characters. This is analogous to the \f(CW\*(C`SvUTF8\*(C'\fR flag for scalars. |
| 11662 |
.Sp |
| 11663 |
In UTF\-8 mode, it is not guaranteed that the lexer buffer actually |
| 11664 |
contains valid UTF\-8. Lexing code must be robust in the face of invalid |
| 11665 |
encoding. |
| 11666 |
.Sp |
| 11667 |
The actual \f(CW\*(C`SvUTF8\*(C'\fR flag of the "PL_parser\->linestr" scalar |
| 11668 |
is significant, but not the whole story regarding the input character |
| 11669 |
encoding. Normally, when a file is being read, the scalar contains octets |
| 11670 |
and its \f(CW\*(C`SvUTF8\*(C'\fR flag is off, but the octets should be interpreted as |
| 11671 |
UTF\-8 if the \f(CW\*(C`use utf8\*(C'\fR pragma is in effect. During a string eval, |
| 11672 |
however, the scalar may have the \f(CW\*(C`SvUTF8\*(C'\fR flag on, and in this case its |
| 11673 |
octets should be interpreted as UTF\-8 unless the \f(CW\*(C`use bytes\*(C'\fR pragma |
| 11674 |
is in effect. This logic may change in the future; use this function |
| 11675 |
instead of implementing the logic yourself. |
| 11676 |
.RS 4 |
| 11677 |
.Sp |
| 11678 |
.Vb 1 |
| 11679 |
\& bool lex_bufutf8() |
| 11680 |
.Ve |
| 11681 |
.RE |
| 11682 |
.RS 4 |
| 11683 |
.RE |
| 11684 |
.ie n .IP """lex_discard_to""" 4 |
| 11685 |
.el .IP \f(CWlex_discard_to\fR 4 |
| 11686 |
.IX Xref "lex_discard_to" |
| 11687 |
.IX Item "lex_discard_to" |
| 11688 |
NOTE: \f(CW\*(C`lex_discard_to\*(C'\fR is \fBexperimental\fR and may change or be |
| 11689 |
removed without notice. |
| 11690 |
.Sp |
| 11691 |
Discards the first part of the "PL_parser\->linestr" buffer, |
| 11692 |
up to \f(CW\*(C`ptr\*(C'\fR. The remaining content of the buffer will be moved, and |
| 11693 |
all pointers into the buffer updated appropriately. \f(CW\*(C`ptr\*(C'\fR must not |
| 11694 |
be later in the buffer than the position of "PL_parser\->bufptr": |
| 11695 |
it is not permitted to discard text that has yet to be lexed. |
| 11696 |
.Sp |
| 11697 |
Normally it is not necessarily to do this directly, because it suffices to |
| 11698 |
use the implicit discarding behaviour of "lex_next_chunk" and things |
| 11699 |
based on it. However, if a token stretches across multiple lines, |
| 11700 |
and the lexing code has kept multiple lines of text in the buffer for |
| 11701 |
that purpose, then after completion of the token it would be wise to |
| 11702 |
explicitly discard the now-unneeded earlier lines, to avoid future |
| 11703 |
multi-line tokens growing the buffer without bound. |
| 11704 |
.RS 4 |
| 11705 |
.Sp |
| 11706 |
.Vb 1 |
| 11707 |
\& void lex_discard_to(char *ptr) |
| 11708 |
.Ve |
| 11709 |
.RE |
| 11710 |
.RS 4 |
| 11711 |
.RE |
| 11712 |
.ie n .IP """lex_grow_linestr""" 4 |
| 11713 |
.el .IP \f(CWlex_grow_linestr\fR 4 |
| 11714 |
.IX Xref "lex_grow_linestr" |
| 11715 |
.IX Item "lex_grow_linestr" |
| 11716 |
NOTE: \f(CW\*(C`lex_grow_linestr\*(C'\fR is \fBexperimental\fR and may change or be |
| 11717 |
removed without notice. |
| 11718 |
.Sp |
| 11719 |
Reallocates the lexer buffer ("PL_parser\->linestr") to accommodate |
| 11720 |
at least \f(CW\*(C`len\*(C'\fR octets (including terminating \f(CW\*(C`NUL\*(C'\fR). Returns a |
| 11721 |
pointer to the reallocated buffer. This is necessary before making |
| 11722 |
any direct modification of the buffer that would increase its length. |
| 11723 |
"lex_stuff_pvn" provides a more convenient way to insert text into |
| 11724 |
the buffer. |
| 11725 |
.Sp |
| 11726 |
Do not use \f(CW\*(C`SvGROW\*(C'\fR or \f(CW\*(C`sv_grow\*(C'\fR directly on \f(CW\*(C`PL_parser\->linestr\*(C'\fR; |
| 11727 |
this function updates all of the lexer's variables that point directly |
| 11728 |
into the buffer. |
| 11729 |
.RS 4 |
| 11730 |
.Sp |
| 11731 |
.Vb 1 |
| 11732 |
\& char * lex_grow_linestr(STRLEN len) |
| 11733 |
.Ve |
| 11734 |
.RE |
| 11735 |
.RS 4 |
| 11736 |
.RE |
| 11737 |
.ie n .IP """lex_next_chunk""" 4 |
| 11738 |
.el .IP \f(CWlex_next_chunk\fR 4 |
| 11739 |
.IX Xref "lex_next_chunk" |
| 11740 |
.IX Item "lex_next_chunk" |
| 11741 |
NOTE: \f(CW\*(C`lex_next_chunk\*(C'\fR is \fBexperimental\fR and may change or be |
| 11742 |
removed without notice. |
| 11743 |
.Sp |
| 11744 |
Reads in the next chunk of text to be lexed, appending it to |
| 11745 |
"PL_parser\->linestr". This should be called when lexing code has |
| 11746 |
looked to the end of the current chunk and wants to know more. It is |
| 11747 |
usual, but not necessary, for lexing to have consumed the entirety of |
| 11748 |
the current chunk at this time. |
| 11749 |
.Sp |
| 11750 |
If "PL_parser\->bufptr" is pointing to the very end of the current |
| 11751 |
chunk (i.e., the current chunk has been entirely consumed), normally the |
| 11752 |
current chunk will be discarded at the same time that the new chunk is |
| 11753 |
read in. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, the current chunk |
| 11754 |
will not be discarded. If the current chunk has not been entirely |
| 11755 |
consumed, then it will not be discarded regardless of the flag. |
| 11756 |
.Sp |
| 11757 |
Returns true if some new text was added to the buffer, or false if the |
| 11758 |
buffer has reached the end of the input text. |
| 11759 |
.RS 4 |
| 11760 |
.Sp |
| 11761 |
.Vb 1 |
| 11762 |
\& bool lex_next_chunk(U32 flags) |
| 11763 |
.Ve |
| 11764 |
.RE |
| 11765 |
.RS 4 |
| 11766 |
.RE |
| 11767 |
.ie n .IP """lex_peek_unichar""" 4 |
| 11768 |
.el .IP \f(CWlex_peek_unichar\fR 4 |
| 11769 |
.IX Xref "lex_peek_unichar" |
| 11770 |
.IX Item "lex_peek_unichar" |
| 11771 |
NOTE: \f(CW\*(C`lex_peek_unichar\*(C'\fR is \fBexperimental\fR and may change or be |
| 11772 |
removed without notice. |
| 11773 |
.Sp |
| 11774 |
Looks ahead one (Unicode) character in the text currently being lexed. |
| 11775 |
Returns the codepoint (unsigned integer value) of the next character, |
| 11776 |
or \-1 if lexing has reached the end of the input text. To consume the |
| 11777 |
peeked character, use "lex_read_unichar". |
| 11778 |
.Sp |
| 11779 |
If the next character is in (or extends into) the next chunk of input |
| 11780 |
text, the next chunk will be read in. Normally the current chunk will be |
| 11781 |
discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR |
| 11782 |
bit set, then the current chunk will not be discarded. |
| 11783 |
.Sp |
| 11784 |
If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error |
| 11785 |
is encountered, an exception is generated. |
| 11786 |
.RS 4 |
| 11787 |
.Sp |
| 11788 |
.Vb 1 |
| 11789 |
\& I32 lex_peek_unichar(U32 flags) |
| 11790 |
.Ve |
| 11791 |
.RE |
| 11792 |
.RS 4 |
| 11793 |
.RE |
| 11794 |
.ie n .IP """lex_read_space""" 4 |
| 11795 |
.el .IP \f(CWlex_read_space\fR 4 |
| 11796 |
.IX Xref "lex_read_space" |
| 11797 |
.IX Item "lex_read_space" |
| 11798 |
NOTE: \f(CW\*(C`lex_read_space\*(C'\fR is \fBexperimental\fR and may change or be |
| 11799 |
removed without notice. |
| 11800 |
.Sp |
| 11801 |
Reads optional spaces, in Perl style, in the text currently being |
| 11802 |
lexed. The spaces may include ordinary whitespace characters and |
| 11803 |
Perl-style comments. \f(CW\*(C`#line\*(C'\fR directives are processed if encountered. |
| 11804 |
"PL_parser\->bufptr" is moved past the spaces, so that it points |
| 11805 |
at a non-space character (or the end of the input text). |
| 11806 |
.Sp |
| 11807 |
If spaces extend into the next chunk of input text, the next chunk will |
| 11808 |
be read in. Normally the current chunk will be discarded at the same |
| 11809 |
time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, then the current |
| 11810 |
chunk will not be discarded. |
| 11811 |
.RS 4 |
| 11812 |
.Sp |
| 11813 |
.Vb 1 |
| 11814 |
\& void lex_read_space(U32 flags) |
| 11815 |
.Ve |
| 11816 |
.RE |
| 11817 |
.RS 4 |
| 11818 |
.RE |
| 11819 |
.ie n .IP """lex_read_to""" 4 |
| 11820 |
.el .IP \f(CWlex_read_to\fR 4 |
| 11821 |
.IX Xref "lex_read_to" |
| 11822 |
.IX Item "lex_read_to" |
| 11823 |
NOTE: \f(CW\*(C`lex_read_to\*(C'\fR is \fBexperimental\fR and may change or be |
| 11824 |
removed without notice. |
| 11825 |
.Sp |
| 11826 |
Consume text in the lexer buffer, from "PL_parser\->bufptr" up |
| 11827 |
to \f(CW\*(C`ptr\*(C'\fR. This advances "PL_parser\->bufptr" to match \f(CW\*(C`ptr\*(C'\fR, |
| 11828 |
performing the correct bookkeeping whenever a newline character is passed. |
| 11829 |
This is the normal way to consume lexed text. |
| 11830 |
.Sp |
| 11831 |
Interpretation of the buffer's octets can be abstracted out by |
| 11832 |
using the slightly higher-level functions "lex_peek_unichar" and |
| 11833 |
"lex_read_unichar". |
| 11834 |
.RS 4 |
| 11835 |
.Sp |
| 11836 |
.Vb 1 |
| 11837 |
\& void lex_read_to(char *ptr) |
| 11838 |
.Ve |
| 11839 |
.RE |
| 11840 |
.RS 4 |
| 11841 |
.RE |
| 11842 |
.ie n .IP """lex_read_unichar""" 4 |
| 11843 |
.el .IP \f(CWlex_read_unichar\fR 4 |
| 11844 |
.IX Xref "lex_read_unichar" |
| 11845 |
.IX Item "lex_read_unichar" |
| 11846 |
NOTE: \f(CW\*(C`lex_read_unichar\*(C'\fR is \fBexperimental\fR and may change or be |
| 11847 |
removed without notice. |
| 11848 |
.Sp |
| 11849 |
Reads the next (Unicode) character in the text currently being lexed. |
| 11850 |
Returns the codepoint (unsigned integer value) of the character read, |
| 11851 |
and moves "PL_parser\->bufptr" past the character, or returns \-1 |
| 11852 |
if lexing has reached the end of the input text. To non-destructively |
| 11853 |
examine the next character, use "lex_peek_unichar" instead. |
| 11854 |
.Sp |
| 11855 |
If the next character is in (or extends into) the next chunk of input |
| 11856 |
text, the next chunk will be read in. Normally the current chunk will be |
| 11857 |
discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR |
| 11858 |
bit set, then the current chunk will not be discarded. |
| 11859 |
.Sp |
| 11860 |
If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error |
| 11861 |
is encountered, an exception is generated. |
| 11862 |
.RS 4 |
| 11863 |
.Sp |
| 11864 |
.Vb 1 |
| 11865 |
\& I32 lex_read_unichar(U32 flags) |
| 11866 |
.Ve |
| 11867 |
.RE |
| 11868 |
.RS 4 |
| 11869 |
.RE |
| 11870 |
.ie n .IP """lex_start""" 4 |
| 11871 |
.el .IP \f(CWlex_start\fR 4 |
| 11872 |
.IX Xref "lex_start" |
| 11873 |
.IX Item "lex_start" |
| 11874 |
NOTE: \f(CW\*(C`lex_start\*(C'\fR is \fBexperimental\fR and may change or be |
| 11875 |
removed without notice. |
| 11876 |
.Sp |
| 11877 |
Creates and initialises a new lexer/parser state object, supplying |
| 11878 |
a context in which to lex and parse from a new source of Perl code. |
| 11879 |
A pointer to the new state object is placed in "PL_parser". An entry |
| 11880 |
is made on the save stack so that upon unwinding, the new state object |
| 11881 |
will be destroyed and the former value of "PL_parser" will be restored. |
| 11882 |
Nothing else need be done to clean up the parsing context. |
| 11883 |
.Sp |
| 11884 |
The code to be parsed comes from \f(CW\*(C`line\*(C'\fR and \f(CW\*(C`rsfp\*(C'\fR. \f(CW\*(C`line\*(C'\fR, if |
| 11885 |
non-null, provides a string (in SV form) containing code to be parsed. |
| 11886 |
A copy of the string is made, so subsequent modification of \f(CW\*(C`line\*(C'\fR |
| 11887 |
does not affect parsing. \f(CW\*(C`rsfp\*(C'\fR, if non-null, provides an input stream |
| 11888 |
from which code will be read to be parsed. If both are non-null, the |
| 11889 |
code in \f(CW\*(C`line\*(C'\fR comes first and must consist of complete lines of input, |
| 11890 |
and \f(CW\*(C`rsfp\*(C'\fR supplies the remainder of the source. |
| 11891 |
.Sp |
| 11892 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use. Currently it is only |
| 11893 |
used by perl internally, so extensions should always pass zero. |
| 11894 |
.RS 4 |
| 11895 |
.Sp |
| 11896 |
.Vb 1 |
| 11897 |
\& void lex_start(SV *line, PerlIO *rsfp, U32 flags) |
| 11898 |
.Ve |
| 11899 |
.RE |
| 11900 |
.RS 4 |
| 11901 |
.RE |
| 11902 |
.ie n .IP """lex_stuff_pv""" 4 |
| 11903 |
.el .IP \f(CWlex_stuff_pv\fR 4 |
| 11904 |
.IX Xref "lex_stuff_pv" |
| 11905 |
.IX Item "lex_stuff_pv" |
| 11906 |
NOTE: \f(CW\*(C`lex_stuff_pv\*(C'\fR is \fBexperimental\fR and may change or be |
| 11907 |
removed without notice. |
| 11908 |
.Sp |
| 11909 |
Insert characters into the lexer buffer ("PL_parser\->linestr"), |
| 11910 |
immediately after the current lexing point ("PL_parser\->bufptr"), |
| 11911 |
reallocating the buffer if necessary. This means that lexing code that |
| 11912 |
runs later will see the characters as if they had appeared in the input. |
| 11913 |
It is not recommended to do this as part of normal parsing, and most |
| 11914 |
uses of this facility run the risk of the inserted characters being |
| 11915 |
interpreted in an unintended manner. |
| 11916 |
.Sp |
| 11917 |
The string to be inserted is represented by octets starting at \f(CW\*(C`pv\*(C'\fR |
| 11918 |
and continuing to the first nul. These octets are interpreted as either |
| 11919 |
UTF\-8 or Latin\-1, according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set |
| 11920 |
in \f(CW\*(C`flags\*(C'\fR. The characters are recoded for the lexer buffer, according |
| 11921 |
to how the buffer is currently being interpreted ("lex_bufutf8"). |
| 11922 |
If it is not convenient to nul-terminate a string to be inserted, the |
| 11923 |
"lex_stuff_pvn" function is more appropriate. |
| 11924 |
.RS 4 |
| 11925 |
.Sp |
| 11926 |
.Vb 1 |
| 11927 |
\& void lex_stuff_pv(const char *pv, U32 flags) |
| 11928 |
.Ve |
| 11929 |
.RE |
| 11930 |
.RS 4 |
| 11931 |
.RE |
| 11932 |
.ie n .IP """lex_stuff_pvn""" 4 |
| 11933 |
.el .IP \f(CWlex_stuff_pvn\fR 4 |
| 11934 |
.IX Xref "lex_stuff_pvn" |
| 11935 |
.IX Item "lex_stuff_pvn" |
| 11936 |
NOTE: \f(CW\*(C`lex_stuff_pvn\*(C'\fR is \fBexperimental\fR and may change or be |
| 11937 |
removed without notice. |
| 11938 |
.Sp |
| 11939 |
Insert characters into the lexer buffer ("PL_parser\->linestr"), |
| 11940 |
immediately after the current lexing point ("PL_parser\->bufptr"), |
| 11941 |
reallocating the buffer if necessary. This means that lexing code that |
| 11942 |
runs later will see the characters as if they had appeared in the input. |
| 11943 |
It is not recommended to do this as part of normal parsing, and most |
| 11944 |
uses of this facility run the risk of the inserted characters being |
| 11945 |
interpreted in an unintended manner. |
| 11946 |
.Sp |
| 11947 |
The string to be inserted is represented by \f(CW\*(C`len\*(C'\fR octets starting |
| 11948 |
at \f(CW\*(C`pv\*(C'\fR. These octets are interpreted as either UTF\-8 or Latin\-1, |
| 11949 |
according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set in \f(CW\*(C`flags\*(C'\fR. |
| 11950 |
The characters are recoded for the lexer buffer, according to how the |
| 11951 |
buffer is currently being interpreted ("lex_bufutf8"). If a string |
| 11952 |
to be inserted is available as a Perl scalar, the "lex_stuff_sv" |
| 11953 |
function is more convenient. |
| 11954 |
.RS 4 |
| 11955 |
.Sp |
| 11956 |
.Vb 1 |
| 11957 |
\& void lex_stuff_pvn(const char *pv, STRLEN len, U32 flags) |
| 11958 |
.Ve |
| 11959 |
.RE |
| 11960 |
.RS 4 |
| 11961 |
.RE |
| 11962 |
.ie n .IP """lex_stuff_pvs""" 4 |
| 11963 |
.el .IP \f(CWlex_stuff_pvs\fR 4 |
| 11964 |
.IX Xref "lex_stuff_pvs" |
| 11965 |
.IX Item "lex_stuff_pvs" |
| 11966 |
NOTE: \f(CW\*(C`lex_stuff_pvs\*(C'\fR is \fBexperimental\fR and may change or be |
| 11967 |
removed without notice. |
| 11968 |
.Sp |
| 11969 |
Like "lex_stuff_pvn", but takes a literal string instead of |
| 11970 |
a string/length pair. |
| 11971 |
.RS 4 |
| 11972 |
.Sp |
| 11973 |
.Vb 1 |
| 11974 |
\& void lex_stuff_pvs("pv", U32 flags) |
| 11975 |
.Ve |
| 11976 |
.RE |
| 11977 |
.RS 4 |
| 11978 |
.RE |
| 11979 |
.ie n .IP """lex_stuff_sv""" 4 |
| 11980 |
.el .IP \f(CWlex_stuff_sv\fR 4 |
| 11981 |
.IX Xref "lex_stuff_sv" |
| 11982 |
.IX Item "lex_stuff_sv" |
| 11983 |
NOTE: \f(CW\*(C`lex_stuff_sv\*(C'\fR is \fBexperimental\fR and may change or be |
| 11984 |
removed without notice. |
| 11985 |
.Sp |
| 11986 |
Insert characters into the lexer buffer ("PL_parser\->linestr"), |
| 11987 |
immediately after the current lexing point ("PL_parser\->bufptr"), |
| 11988 |
reallocating the buffer if necessary. This means that lexing code that |
| 11989 |
runs later will see the characters as if they had appeared in the input. |
| 11990 |
It is not recommended to do this as part of normal parsing, and most |
| 11991 |
uses of this facility run the risk of the inserted characters being |
| 11992 |
interpreted in an unintended manner. |
| 11993 |
.Sp |
| 11994 |
The string to be inserted is the string value of \f(CW\*(C`sv\*(C'\fR. The characters |
| 11995 |
are recoded for the lexer buffer, according to how the buffer is currently |
| 11996 |
being interpreted ("lex_bufutf8"). If a string to be inserted is |
| 11997 |
not already a Perl scalar, the "lex_stuff_pvn" function avoids the |
| 11998 |
need to construct a scalar. |
| 11999 |
.RS 4 |
| 12000 |
.Sp |
| 12001 |
.Vb 1 |
| 12002 |
\& void lex_stuff_sv(SV *sv, U32 flags) |
| 12003 |
.Ve |
| 12004 |
.RE |
| 12005 |
.RS 4 |
| 12006 |
.RE |
| 12007 |
.ie n .IP """lex_unstuff""" 4 |
| 12008 |
.el .IP \f(CWlex_unstuff\fR 4 |
| 12009 |
.IX Xref "lex_unstuff" |
| 12010 |
.IX Item "lex_unstuff" |
| 12011 |
NOTE: \f(CW\*(C`lex_unstuff\*(C'\fR is \fBexperimental\fR and may change or be |
| 12012 |
removed without notice. |
| 12013 |
.Sp |
| 12014 |
Discards text about to be lexed, from "PL_parser\->bufptr" up to |
| 12015 |
\&\f(CW\*(C`ptr\*(C'\fR. Text following \f(CW\*(C`ptr\*(C'\fR will be moved, and the buffer shortened. |
| 12016 |
This hides the discarded text from any lexing code that runs later, |
| 12017 |
as if the text had never appeared. |
| 12018 |
.Sp |
| 12019 |
This is not the normal way to consume lexed text. For that, use |
| 12020 |
"lex_read_to". |
| 12021 |
.RS 4 |
| 12022 |
.Sp |
| 12023 |
.Vb 1 |
| 12024 |
\& void lex_unstuff(char *ptr) |
| 12025 |
.Ve |
| 12026 |
.RE |
| 12027 |
.RS 4 |
| 12028 |
.RE |
| 12029 |
.ie n .IP """parse_arithexpr""" 4 |
| 12030 |
.el .IP \f(CWparse_arithexpr\fR 4 |
| 12031 |
.IX Xref "parse_arithexpr" |
| 12032 |
.IX Item "parse_arithexpr" |
| 12033 |
NOTE: \f(CW\*(C`parse_arithexpr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12034 |
removed without notice. |
| 12035 |
.Sp |
| 12036 |
Parse a Perl arithmetic expression. This may contain operators of precedence |
| 12037 |
down to the bit shift operators. The expression must be followed (and thus |
| 12038 |
terminated) either by a comparison or lower-precedence operator or by |
| 12039 |
something that would normally terminate an expression such as semicolon. |
| 12040 |
If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, |
| 12041 |
otherwise it is mandatory. It is up to the caller to ensure that the |
| 12042 |
dynamic parser state ("PL_parser" et al) is correctly set to reflect |
| 12043 |
the source of the code to be parsed and the lexical context for the |
| 12044 |
expression. |
| 12045 |
.Sp |
| 12046 |
The op tree representing the expression is returned. If an optional |
| 12047 |
expression is absent, a null pointer is returned, otherwise the pointer |
| 12048 |
will be non-null. |
| 12049 |
.Sp |
| 12050 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12051 |
tree is returned anyway. The error is reflected in the parser state, |
| 12052 |
normally resulting in a single exception at the top level of parsing |
| 12053 |
which covers all the compilation errors that occurred. Some compilation |
| 12054 |
errors, however, will throw an exception immediately. |
| 12055 |
.RS 4 |
| 12056 |
.Sp |
| 12057 |
.Vb 1 |
| 12058 |
\& OP * parse_arithexpr(U32 flags) |
| 12059 |
.Ve |
| 12060 |
.RE |
| 12061 |
.RS 4 |
| 12062 |
.RE |
| 12063 |
.ie n .IP """parse_barestmt""" 4 |
| 12064 |
.el .IP \f(CWparse_barestmt\fR 4 |
| 12065 |
.IX Xref "parse_barestmt" |
| 12066 |
.IX Item "parse_barestmt" |
| 12067 |
NOTE: \f(CW\*(C`parse_barestmt\*(C'\fR is \fBexperimental\fR and may change or be |
| 12068 |
removed without notice. |
| 12069 |
.Sp |
| 12070 |
Parse a single unadorned Perl statement. This may be a normal imperative |
| 12071 |
statement or a declaration that has compile-time effect. It does not |
| 12072 |
include any label or other affixture. It is up to the caller to ensure |
| 12073 |
that the dynamic parser state ("PL_parser" et al) is correctly set to |
| 12074 |
reflect the source of the code to be parsed and the lexical context for |
| 12075 |
the statement. |
| 12076 |
.Sp |
| 12077 |
The op tree representing the statement is returned. This may be a |
| 12078 |
null pointer if the statement is null, for example if it was actually |
| 12079 |
a subroutine definition (which has compile-time side effects). If not |
| 12080 |
null, it will be ops directly implementing the statement, suitable to |
| 12081 |
pass to "newSTATEOP". It will not normally include a \f(CW\*(C`nextstate\*(C'\fR or |
| 12082 |
equivalent op (except for those embedded in a scope contained entirely |
| 12083 |
within the statement). |
| 12084 |
.Sp |
| 12085 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12086 |
tree (most likely null) is returned anyway. The error is reflected in |
| 12087 |
the parser state, normally resulting in a single exception at the top |
| 12088 |
level of parsing which covers all the compilation errors that occurred. |
| 12089 |
Some compilation errors, however, will throw an exception immediately. |
| 12090 |
.Sp |
| 12091 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always |
| 12092 |
be zero. |
| 12093 |
.RS 4 |
| 12094 |
.Sp |
| 12095 |
.Vb 1 |
| 12096 |
\& OP * parse_barestmt(U32 flags) |
| 12097 |
.Ve |
| 12098 |
.RE |
| 12099 |
.RS 4 |
| 12100 |
.RE |
| 12101 |
.ie n .IP """parse_block""" 4 |
| 12102 |
.el .IP \f(CWparse_block\fR 4 |
| 12103 |
.IX Xref "parse_block" |
| 12104 |
.IX Item "parse_block" |
| 12105 |
NOTE: \f(CW\*(C`parse_block\*(C'\fR is \fBexperimental\fR and may change or be |
| 12106 |
removed without notice. |
| 12107 |
.Sp |
| 12108 |
Parse a single complete Perl code block. This consists of an opening |
| 12109 |
brace, a sequence of statements, and a closing brace. The block |
| 12110 |
constitutes a lexical scope, so \f(CW\*(C`my\*(C'\fR variables and various compile-time |
| 12111 |
effects can be contained within it. It is up to the caller to ensure |
| 12112 |
that the dynamic parser state ("PL_parser" et al) is correctly set to |
| 12113 |
reflect the source of the code to be parsed and the lexical context for |
| 12114 |
the statement. |
| 12115 |
.Sp |
| 12116 |
The op tree representing the code block is returned. This is always a |
| 12117 |
real op, never a null pointer. It will normally be a \f(CW\*(C`lineseq\*(C'\fR list, |
| 12118 |
including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops. No ops to construct any kind |
| 12119 |
of runtime scope are included by virtue of it being a block. |
| 12120 |
.Sp |
| 12121 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12122 |
tree (most likely null) is returned anyway. The error is reflected in |
| 12123 |
the parser state, normally resulting in a single exception at the top |
| 12124 |
level of parsing which covers all the compilation errors that occurred. |
| 12125 |
Some compilation errors, however, will throw an exception immediately. |
| 12126 |
.Sp |
| 12127 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always |
| 12128 |
be zero. |
| 12129 |
.RS 4 |
| 12130 |
.Sp |
| 12131 |
.Vb 1 |
| 12132 |
\& OP * parse_block(U32 flags) |
| 12133 |
.Ve |
| 12134 |
.RE |
| 12135 |
.RS 4 |
| 12136 |
.RE |
| 12137 |
.ie n .IP """parse_fullexpr""" 4 |
| 12138 |
.el .IP \f(CWparse_fullexpr\fR 4 |
| 12139 |
.IX Xref "parse_fullexpr" |
| 12140 |
.IX Item "parse_fullexpr" |
| 12141 |
NOTE: \f(CW\*(C`parse_fullexpr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12142 |
removed without notice. |
| 12143 |
.Sp |
| 12144 |
Parse a single complete Perl expression. This allows the full |
| 12145 |
expression grammar, including the lowest-precedence operators such |
| 12146 |
as \f(CW\*(C`or\*(C'\fR. The expression must be followed (and thus terminated) by a |
| 12147 |
token that an expression would normally be terminated by: end-of-file, |
| 12148 |
closing bracketing punctuation, semicolon, or one of the keywords that |
| 12149 |
signals a postfix expression-statement modifier. If \f(CW\*(C`flags\*(C'\fR has the |
| 12150 |
\&\f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, otherwise it is |
| 12151 |
mandatory. It is up to the caller to ensure that the dynamic parser |
| 12152 |
state ("PL_parser" et al) is correctly set to reflect the source of |
| 12153 |
the code to be parsed and the lexical context for the expression. |
| 12154 |
.Sp |
| 12155 |
The op tree representing the expression is returned. If an optional |
| 12156 |
expression is absent, a null pointer is returned, otherwise the pointer |
| 12157 |
will be non-null. |
| 12158 |
.Sp |
| 12159 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12160 |
tree is returned anyway. The error is reflected in the parser state, |
| 12161 |
normally resulting in a single exception at the top level of parsing |
| 12162 |
which covers all the compilation errors that occurred. Some compilation |
| 12163 |
errors, however, will throw an exception immediately. |
| 12164 |
.RS 4 |
| 12165 |
.Sp |
| 12166 |
.Vb 1 |
| 12167 |
\& OP * parse_fullexpr(U32 flags) |
| 12168 |
.Ve |
| 12169 |
.RE |
| 12170 |
.RS 4 |
| 12171 |
.RE |
| 12172 |
.ie n .IP """parse_fullstmt""" 4 |
| 12173 |
.el .IP \f(CWparse_fullstmt\fR 4 |
| 12174 |
.IX Xref "parse_fullstmt" |
| 12175 |
.IX Item "parse_fullstmt" |
| 12176 |
NOTE: \f(CW\*(C`parse_fullstmt\*(C'\fR is \fBexperimental\fR and may change or be |
| 12177 |
removed without notice. |
| 12178 |
.Sp |
| 12179 |
Parse a single complete Perl statement. This may be a normal imperative |
| 12180 |
statement or a declaration that has compile-time effect, and may include |
| 12181 |
optional labels. It is up to the caller to ensure that the dynamic |
| 12182 |
parser state ("PL_parser" et al) is correctly set to reflect the source |
| 12183 |
of the code to be parsed and the lexical context for the statement. |
| 12184 |
.Sp |
| 12185 |
The op tree representing the statement is returned. This may be a |
| 12186 |
null pointer if the statement is null, for example if it was actually |
| 12187 |
a subroutine definition (which has compile-time side effects). If not |
| 12188 |
null, it will be the result of a "newSTATEOP" call, normally including |
| 12189 |
a \f(CW\*(C`nextstate\*(C'\fR or equivalent op. |
| 12190 |
.Sp |
| 12191 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12192 |
tree (most likely null) is returned anyway. The error is reflected in |
| 12193 |
the parser state, normally resulting in a single exception at the top |
| 12194 |
level of parsing which covers all the compilation errors that occurred. |
| 12195 |
Some compilation errors, however, will throw an exception immediately. |
| 12196 |
.Sp |
| 12197 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always |
| 12198 |
be zero. |
| 12199 |
.RS 4 |
| 12200 |
.Sp |
| 12201 |
.Vb 1 |
| 12202 |
\& OP * parse_fullstmt(U32 flags) |
| 12203 |
.Ve |
| 12204 |
.RE |
| 12205 |
.RS 4 |
| 12206 |
.RE |
| 12207 |
.ie n .IP """parse_label""" 4 |
| 12208 |
.el .IP \f(CWparse_label\fR 4 |
| 12209 |
.IX Xref "parse_label" |
| 12210 |
.IX Item "parse_label" |
| 12211 |
NOTE: \f(CW\*(C`parse_label\*(C'\fR is \fBexperimental\fR and may change or be |
| 12212 |
removed without notice. |
| 12213 |
.Sp |
| 12214 |
Parse a single label, possibly optional, of the type that may prefix a |
| 12215 |
Perl statement. It is up to the caller to ensure that the dynamic parser |
| 12216 |
state ("PL_parser" et al) is correctly set to reflect the source of |
| 12217 |
the code to be parsed. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the |
| 12218 |
label is optional, otherwise it is mandatory. |
| 12219 |
.Sp |
| 12220 |
The name of the label is returned in the form of a fresh scalar. If an |
| 12221 |
optional label is absent, a null pointer is returned. |
| 12222 |
.Sp |
| 12223 |
If an error occurs in parsing, which can only occur if the label is |
| 12224 |
mandatory, a valid label is returned anyway. The error is reflected in |
| 12225 |
the parser state, normally resulting in a single exception at the top |
| 12226 |
level of parsing which covers all the compilation errors that occurred. |
| 12227 |
.RS 4 |
| 12228 |
.Sp |
| 12229 |
.Vb 1 |
| 12230 |
\& SV * parse_label(U32 flags) |
| 12231 |
.Ve |
| 12232 |
.RE |
| 12233 |
.RS 4 |
| 12234 |
.RE |
| 12235 |
.ie n .IP """parse_listexpr""" 4 |
| 12236 |
.el .IP \f(CWparse_listexpr\fR 4 |
| 12237 |
.IX Xref "parse_listexpr" |
| 12238 |
.IX Item "parse_listexpr" |
| 12239 |
NOTE: \f(CW\*(C`parse_listexpr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12240 |
removed without notice. |
| 12241 |
.Sp |
| 12242 |
Parse a Perl list expression. This may contain operators of precedence |
| 12243 |
down to the comma operator. The expression must be followed (and thus |
| 12244 |
terminated) either by a low-precedence logic operator such as \f(CW\*(C`or\*(C'\fR or by |
| 12245 |
something that would normally terminate an expression such as semicolon. |
| 12246 |
If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, |
| 12247 |
otherwise it is mandatory. It is up to the caller to ensure that the |
| 12248 |
dynamic parser state ("PL_parser" et al) is correctly set to reflect |
| 12249 |
the source of the code to be parsed and the lexical context for the |
| 12250 |
expression. |
| 12251 |
.Sp |
| 12252 |
The op tree representing the expression is returned. If an optional |
| 12253 |
expression is absent, a null pointer is returned, otherwise the pointer |
| 12254 |
will be non-null. |
| 12255 |
.Sp |
| 12256 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12257 |
tree is returned anyway. The error is reflected in the parser state, |
| 12258 |
normally resulting in a single exception at the top level of parsing |
| 12259 |
which covers all the compilation errors that occurred. Some compilation |
| 12260 |
errors, however, will throw an exception immediately. |
| 12261 |
.RS 4 |
| 12262 |
.Sp |
| 12263 |
.Vb 1 |
| 12264 |
\& OP * parse_listexpr(U32 flags) |
| 12265 |
.Ve |
| 12266 |
.RE |
| 12267 |
.RS 4 |
| 12268 |
.RE |
| 12269 |
.ie n .IP """parse_stmtseq""" 4 |
| 12270 |
.el .IP \f(CWparse_stmtseq\fR 4 |
| 12271 |
.IX Xref "parse_stmtseq" |
| 12272 |
.IX Item "parse_stmtseq" |
| 12273 |
NOTE: \f(CW\*(C`parse_stmtseq\*(C'\fR is \fBexperimental\fR and may change or be |
| 12274 |
removed without notice. |
| 12275 |
.Sp |
| 12276 |
Parse a sequence of zero or more Perl statements. These may be normal |
| 12277 |
imperative statements, including optional labels, or declarations |
| 12278 |
that have compile-time effect, or any mixture thereof. The statement |
| 12279 |
sequence ends when a closing brace or end-of-file is encountered in a |
| 12280 |
place where a new statement could have validly started. It is up to |
| 12281 |
the caller to ensure that the dynamic parser state ("PL_parser" et al) |
| 12282 |
is correctly set to reflect the source of the code to be parsed and the |
| 12283 |
lexical context for the statements. |
| 12284 |
.Sp |
| 12285 |
The op tree representing the statement sequence is returned. This may |
| 12286 |
be a null pointer if the statements were all null, for example if there |
| 12287 |
were no statements or if there were only subroutine definitions (which |
| 12288 |
have compile-time side effects). If not null, it will be a \f(CW\*(C`lineseq\*(C'\fR |
| 12289 |
list, normally including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops. |
| 12290 |
.Sp |
| 12291 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12292 |
tree is returned anyway. The error is reflected in the parser state, |
| 12293 |
normally resulting in a single exception at the top level of parsing |
| 12294 |
which covers all the compilation errors that occurred. Some compilation |
| 12295 |
errors, however, will throw an exception immediately. |
| 12296 |
.Sp |
| 12297 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always |
| 12298 |
be zero. |
| 12299 |
.RS 4 |
| 12300 |
.Sp |
| 12301 |
.Vb 1 |
| 12302 |
\& OP * parse_stmtseq(U32 flags) |
| 12303 |
.Ve |
| 12304 |
.RE |
| 12305 |
.RS 4 |
| 12306 |
.RE |
| 12307 |
.ie n .IP """parse_subsignature""" 4 |
| 12308 |
.el .IP \f(CWparse_subsignature\fR 4 |
| 12309 |
.IX Xref "parse_subsignature" |
| 12310 |
.IX Item "parse_subsignature" |
| 12311 |
NOTE: \f(CW\*(C`parse_subsignature\*(C'\fR is \fBexperimental\fR and may change or be |
| 12312 |
removed without notice. |
| 12313 |
.Sp |
| 12314 |
Parse a subroutine signature declaration. This is the contents of the |
| 12315 |
parentheses following a named or anonymous subroutine declaration when the |
| 12316 |
\&\f(CW\*(C`signatures\*(C'\fR feature is enabled. Note that this function neither expects |
| 12317 |
nor consumes the opening and closing parentheses around the signature; it |
| 12318 |
is the caller's job to handle these. |
| 12319 |
.Sp |
| 12320 |
This function must only be called during parsing of a subroutine; after |
| 12321 |
"start_subparse" has been called. It might allocate lexical variables on |
| 12322 |
the pad for the current subroutine. |
| 12323 |
.Sp |
| 12324 |
The op tree to unpack the arguments from the stack at runtime is returned. |
| 12325 |
This op tree should appear at the beginning of the compiled function. The |
| 12326 |
caller may wish to use "op_append_list" to build their function body |
| 12327 |
after it, or splice it together with the body before calling "newATTRSUB". |
| 12328 |
.Sp |
| 12329 |
The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always |
| 12330 |
be zero. |
| 12331 |
.RS 4 |
| 12332 |
.Sp |
| 12333 |
.Vb 1 |
| 12334 |
\& OP * parse_subsignature(U32 flags) |
| 12335 |
.Ve |
| 12336 |
.RE |
| 12337 |
.RS 4 |
| 12338 |
.RE |
| 12339 |
.ie n .IP """parse_termexpr""" 4 |
| 12340 |
.el .IP \f(CWparse_termexpr\fR 4 |
| 12341 |
.IX Xref "parse_termexpr" |
| 12342 |
.IX Item "parse_termexpr" |
| 12343 |
NOTE: \f(CW\*(C`parse_termexpr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12344 |
removed without notice. |
| 12345 |
.Sp |
| 12346 |
Parse a Perl term expression. This may contain operators of precedence |
| 12347 |
down to the assignment operators. The expression must be followed (and thus |
| 12348 |
terminated) either by a comma or lower-precedence operator or by |
| 12349 |
something that would normally terminate an expression such as semicolon. |
| 12350 |
If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, |
| 12351 |
otherwise it is mandatory. It is up to the caller to ensure that the |
| 12352 |
dynamic parser state ("PL_parser" et al) is correctly set to reflect |
| 12353 |
the source of the code to be parsed and the lexical context for the |
| 12354 |
expression. |
| 12355 |
.Sp |
| 12356 |
The op tree representing the expression is returned. If an optional |
| 12357 |
expression is absent, a null pointer is returned, otherwise the pointer |
| 12358 |
will be non-null. |
| 12359 |
.Sp |
| 12360 |
If an error occurs in parsing or compilation, in most cases a valid op |
| 12361 |
tree is returned anyway. The error is reflected in the parser state, |
| 12362 |
normally resulting in a single exception at the top level of parsing |
| 12363 |
which covers all the compilation errors that occurred. Some compilation |
| 12364 |
errors, however, will throw an exception immediately. |
| 12365 |
.RS 4 |
| 12366 |
.Sp |
| 12367 |
.Vb 1 |
| 12368 |
\& OP * parse_termexpr(U32 flags) |
| 12369 |
.Ve |
| 12370 |
.RE |
| 12371 |
.RS 4 |
| 12372 |
.RE |
| 12373 |
.ie n .IP """PL_parser""" 4 |
| 12374 |
.el .IP \f(CWPL_parser\fR 4 |
| 12375 |
.IX Xref "PL_parser" |
| 12376 |
.IX Item "PL_parser" |
| 12377 |
Pointer to a structure encapsulating the state of the parsing operation |
| 12378 |
currently in progress. The pointer can be locally changed to perform |
| 12379 |
a nested parse without interfering with the state of an outer parse. |
| 12380 |
Individual members of \f(CW\*(C`PL_parser\*(C'\fR have their own documentation. |
| 12381 |
.ie n .IP """PL_parser\->bufend""" 4 |
| 12382 |
.el .IP \f(CWPL_parser\->bufend\fR 4 |
| 12383 |
.IX Xref "PL_parser->bufend" |
| 12384 |
.IX Item "PL_parser->bufend" |
| 12385 |
NOTE: \f(CW\*(C`PL_parser\->bufend\*(C'\fR is \fBexperimental\fR and may change or be |
| 12386 |
removed without notice. |
| 12387 |
.Sp |
| 12388 |
Direct pointer to the end of the chunk of text currently being lexed, the |
| 12389 |
end of the lexer buffer. This is equal to \f(CW\*(C`SvPVX(PL_parser\->linestr) |
| 12390 |
+ SvCUR(PL_parser\->linestr)\*(C'\fR. A \f(CW\*(C`NUL\*(C'\fR character (zero octet) is |
| 12391 |
always located at the end of the buffer, and does not count as part of |
| 12392 |
the buffer's contents. |
| 12393 |
.ie n .IP """PL_parser\->bufptr""" 4 |
| 12394 |
.el .IP \f(CWPL_parser\->bufptr\fR 4 |
| 12395 |
.IX Xref "PL_parser->bufptr" |
| 12396 |
.IX Item "PL_parser->bufptr" |
| 12397 |
NOTE: \f(CW\*(C`PL_parser\->bufptr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12398 |
removed without notice. |
| 12399 |
.Sp |
| 12400 |
Points to the current position of lexing inside the lexer buffer. |
| 12401 |
Characters around this point may be freely examined, within |
| 12402 |
the range delimited by \f(CWSvPVX("PL_parser\->linestr")\fR and |
| 12403 |
"PL_parser\->bufend". The octets of the buffer may be intended to be |
| 12404 |
interpreted as either UTF\-8 or Latin\-1, as indicated by "lex_bufutf8". |
| 12405 |
.Sp |
| 12406 |
Lexing code (whether in the Perl core or not) moves this pointer past |
| 12407 |
the characters that it consumes. It is also expected to perform some |
| 12408 |
bookkeeping whenever a newline character is consumed. This movement |
| 12409 |
can be more conveniently performed by the function "lex_read_to", |
| 12410 |
which handles newlines appropriately. |
| 12411 |
.Sp |
| 12412 |
Interpretation of the buffer's octets can be abstracted out by |
| 12413 |
using the slightly higher-level functions "lex_peek_unichar" and |
| 12414 |
"lex_read_unichar". |
| 12415 |
.ie n .IP """PL_parser\->linestart""" 4 |
| 12416 |
.el .IP \f(CWPL_parser\->linestart\fR 4 |
| 12417 |
.IX Xref "PL_parser->linestart" |
| 12418 |
.IX Item "PL_parser->linestart" |
| 12419 |
NOTE: \f(CW\*(C`PL_parser\->linestart\*(C'\fR is \fBexperimental\fR and may change or be |
| 12420 |
removed without notice. |
| 12421 |
.Sp |
| 12422 |
Points to the start of the current line inside the lexer buffer. |
| 12423 |
This is useful for indicating at which column an error occurred, and |
| 12424 |
not much else. This must be updated by any lexing code that consumes |
| 12425 |
a newline; the function "lex_read_to" handles this detail. |
| 12426 |
.ie n .IP """PL_parser\->linestr""" 4 |
| 12427 |
.el .IP \f(CWPL_parser\->linestr\fR 4 |
| 12428 |
.IX Xref "PL_parser->linestr" |
| 12429 |
.IX Item "PL_parser->linestr" |
| 12430 |
NOTE: \f(CW\*(C`PL_parser\->linestr\*(C'\fR is \fBexperimental\fR and may change or be |
| 12431 |
removed without notice. |
| 12432 |
.Sp |
| 12433 |
Buffer scalar containing the chunk currently under consideration of the |
| 12434 |
text currently being lexed. This is always a plain string scalar (for |
| 12435 |
which \f(CW\*(C`SvPOK\*(C'\fR is true). It is not intended to be used as a scalar by |
| 12436 |
normal scalar means; instead refer to the buffer directly by the pointer |
| 12437 |
variables described below. |
| 12438 |
.Sp |
| 12439 |
The lexer maintains various \f(CW\*(C`char*\*(C'\fR pointers to things in the |
| 12440 |
\&\f(CW\*(C`PL_parser\->linestr\*(C'\fR buffer. If \f(CW\*(C`PL_parser\->linestr\*(C'\fR is ever |
| 12441 |
reallocated, all of these pointers must be updated. Don't attempt to |
| 12442 |
do this manually, but rather use "lex_grow_linestr" if you need to |
| 12443 |
reallocate the buffer. |
| 12444 |
.Sp |
| 12445 |
The content of the text chunk in the buffer is commonly exactly one |
| 12446 |
complete line of input, up to and including a newline terminator, |
| 12447 |
but there are situations where it is otherwise. The octets of the |
| 12448 |
buffer may be intended to be interpreted as either UTF\-8 or Latin\-1. |
| 12449 |
The function "lex_bufutf8" tells you which. Do not use the \f(CW\*(C`SvUTF8\*(C'\fR |
| 12450 |
flag on this scalar, which may disagree with it. |
| 12451 |
.Sp |
| 12452 |
For direct examination of the buffer, the variable |
| 12453 |
"PL_parser\->bufend" points to the end of the buffer. The current |
| 12454 |
lexing position is pointed to by "PL_parser\->bufptr". Direct use |
| 12455 |
of these pointers is usually preferable to examination of the scalar |
| 12456 |
through normal scalar means. |
| 12457 |
.ie n .IP """suspend_compcv""" 4 |
| 12458 |
.el .IP \f(CWsuspend_compcv\fR 4 |
| 12459 |
.IX Xref "suspend_compcv" |
| 12460 |
.IX Item "suspend_compcv" |
| 12461 |
Implements part of the concept of a "suspended compilation CV", which can be |
| 12462 |
used to pause the parser and compiler during parsing a CV in order to come |
| 12463 |
back to it later on. |
| 12464 |
.Sp |
| 12465 |
This function saves the current state of the subroutine under compilation |
| 12466 |
(\f(CW\*(C`PL_compcv\*(C'\fR) into the supplied buffer. This should be used initially to |
| 12467 |
create the state in the buffer, as the final thing before a \f(CW\*(C`LEAVE\*(C'\fR within a |
| 12468 |
block. |
| 12469 |
.Sp |
| 12470 |
.Vb 3 |
| 12471 |
\& ENTER; |
| 12472 |
\& start_subparse(0); |
| 12473 |
\& ... |
| 12474 |
\& |
| 12475 |
\& suspend_compcv(&buffer); |
| 12476 |
\& LEAVE; |
| 12477 |
.Ve |
| 12478 |
.Sp |
| 12479 |
Once suspended, the \f(CW\*(C`resume_compcv_final\*(C'\fR or \f(CW\*(C`resume_compcv_and_save\*(C'\fR |
| 12480 |
function can later be used to continue the parsing from the point this stopped. |
| 12481 |
.RS 4 |
| 12482 |
.Sp |
| 12483 |
.Vb 1 |
| 12484 |
\& void suspend_compcv(struct suspended_compcv *buffer) |
| 12485 |
.Ve |
| 12486 |
.RE |
| 12487 |
.RS 4 |
| 12488 |
.RE |
| 12489 |
.ie n .IP """wrap_infix_plugin""" 4 |
| 12490 |
.el .IP \f(CWwrap_infix_plugin\fR 4 |
| 12491 |
.IX Xref "wrap_infix_plugin" |
| 12492 |
.IX Item "wrap_infix_plugin" |
| 12493 |
NOTE: \f(CW\*(C`wrap_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be |
| 12494 |
removed without notice. |
| 12495 |
.Sp |
| 12496 |
\&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module |
| 12497 |
\&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make |
| 12498 |
use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing |
| 12499 |
of new infix operators. |
| 12500 |
.Sp |
| 12501 |
Puts a C function into the chain of infix plugins. This is the preferred |
| 12502 |
way to manipulate the "PL_infix_plugin" variable. \f(CW\*(C`new_plugin\*(C'\fR is a |
| 12503 |
pointer to the C function that is to be added to the infix plugin chain, and |
| 12504 |
\&\f(CW\*(C`old_plugin_p\*(C'\fR points to a storage location where a pointer to the next |
| 12505 |
function in the chain will be stored. The value of \f(CW\*(C`new_plugin\*(C'\fR is written |
| 12506 |
into the "PL_infix_plugin" variable, while the value previously stored there |
| 12507 |
is written to \f(CW*old_plugin_p\fR. |
| 12508 |
.Sp |
| 12509 |
Direct access to "PL_infix_plugin" should be avoided. |
| 12510 |
.RS 4 |
| 12511 |
.Sp |
| 12512 |
.Vb 2 |
| 12513 |
\& void wrap_infix_plugin(Perl_infix_plugin_t new_plugin, |
| 12514 |
\& Perl_infix_plugin_t *old_plugin_p) |
| 12515 |
.Ve |
| 12516 |
.RE |
| 12517 |
.RS 4 |
| 12518 |
.RE |
| 12519 |
.ie n .IP """wrap_keyword_plugin""" 4 |
| 12520 |
.el .IP \f(CWwrap_keyword_plugin\fR 4 |
| 12521 |
.IX Xref "wrap_keyword_plugin" |
| 12522 |
.IX Item "wrap_keyword_plugin" |
| 12523 |
NOTE: \f(CW\*(C`wrap_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be |
| 12524 |
removed without notice. |
| 12525 |
.Sp |
| 12526 |
Puts a C function into the chain of keyword plugins. This is the |
| 12527 |
preferred way to manipulate the "PL_keyword_plugin" variable. |
| 12528 |
\&\f(CW\*(C`new_plugin\*(C'\fR is a pointer to the C function that is to be added to the |
| 12529 |
keyword plugin chain, and \f(CW\*(C`old_plugin_p\*(C'\fR points to the storage location |
| 12530 |
where a pointer to the next function in the chain will be stored. The |
| 12531 |
value of \f(CW\*(C`new_plugin\*(C'\fR is written into the "PL_keyword_plugin" variable, |
| 12532 |
while the value previously stored there is written to \f(CW*old_plugin_p\fR. |
| 12533 |
.Sp |
| 12534 |
"PL_keyword_plugin" is global to an entire process, and a module wishing |
| 12535 |
to hook keyword parsing may find itself invoked more than once per |
| 12536 |
process, typically in different threads. To handle that situation, this |
| 12537 |
function is idempotent. The location \f(CW*old_plugin_p\fR must initially |
| 12538 |
(once per process) contain a null pointer. A C variable of static |
| 12539 |
duration (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give |
| 12540 |
it internal linkage) will be implicitly initialised appropriately, if it |
| 12541 |
does not have an explicit initialiser. This function will only actually |
| 12542 |
modify the plugin chain if it finds \f(CW*old_plugin_p\fR to be null. This |
| 12543 |
function is also thread safe on the small scale. It uses appropriate |
| 12544 |
locking to avoid race conditions in accessing "PL_keyword_plugin". |
| 12545 |
.Sp |
| 12546 |
When this function is called, the function referenced by \f(CW\*(C`new_plugin\*(C'\fR |
| 12547 |
must be ready to be called, except for \f(CW*old_plugin_p\fR being unfilled. |
| 12548 |
In a threading situation, \f(CW\*(C`new_plugin\*(C'\fR may be called immediately, even |
| 12549 |
before this function has returned. \f(CW*old_plugin_p\fR will always be |
| 12550 |
appropriately set before \f(CW\*(C`new_plugin\*(C'\fR is called. If \f(CW\*(C`new_plugin\*(C'\fR |
| 12551 |
decides not to do anything special with the identifier that it is given |
| 12552 |
(which is the usual case for most calls to a keyword plugin), it must |
| 12553 |
chain the plugin function referenced by \f(CW*old_plugin_p\fR. |
| 12554 |
.Sp |
| 12555 |
Taken all together, XS code to install a keyword plugin should typically |
| 12556 |
look something like this: |
| 12557 |
.Sp |
| 12558 |
.Vb 10 |
| 12559 |
\& static Perl_keyword_plugin_t next_keyword_plugin; |
| 12560 |
\& static OP *my_keyword_plugin(pTHX_ |
| 12561 |
\& char *keyword_ptr, STRLEN keyword_len, OP **op_ptr) |
| 12562 |
\& { |
| 12563 |
\& if (memEQs(keyword_ptr, keyword_len, |
| 12564 |
\& "my_new_keyword")) { |
| 12565 |
\& ... |
| 12566 |
\& } else { |
| 12567 |
\& return next_keyword_plugin(aTHX_ |
| 12568 |
\& keyword_ptr, keyword_len, op_ptr); |
| 12569 |
\& } |
| 12570 |
\& } |
| 12571 |
\& BOOT: |
| 12572 |
\& wrap_keyword_plugin(my_keyword_plugin, |
| 12573 |
\& &next_keyword_plugin); |
| 12574 |
.Ve |
| 12575 |
.Sp |
| 12576 |
Direct access to "PL_keyword_plugin" should be avoided. |
| 12577 |
.RS 4 |
| 12578 |
.Sp |
| 12579 |
.Vb 2 |
| 12580 |
\& void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin, |
| 12581 |
\& Perl_keyword_plugin_t *old_plugin_p) |
| 12582 |
.Ve |
| 12583 |
.RE |
| 12584 |
.RS 4 |
| 12585 |
.RE |
| 12586 |
.SH Locales |
| 12587 |
.IX Header "Locales" |
| 12588 |
.ie n .IP """DECLARATION_FOR_LC_NUMERIC_MANIPULATION""" 4 |
| 12589 |
.el .IP \f(CWDECLARATION_FOR_LC_NUMERIC_MANIPULATION\fR 4 |
| 12590 |
.IX Xref "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" |
| 12591 |
.IX Item "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" |
| 12592 |
This macro should be used as a statement. It declares a private variable |
| 12593 |
(whose name begins with an underscore) that is needed by the other macros in |
| 12594 |
this section. Failing to include this correctly should lead to a syntax error. |
| 12595 |
For compatibility with C89 C compilers it should be placed in a block before |
| 12596 |
any executable statements. |
| 12597 |
.RS 4 |
| 12598 |
.Sp |
| 12599 |
.Vb 1 |
| 12600 |
\& void DECLARATION_FOR_LC_NUMERIC_MANIPULATION |
| 12601 |
.Ve |
| 12602 |
.RE |
| 12603 |
.RS 4 |
| 12604 |
.RE |
| 12605 |
.ie n .IP """foldEQ_locale""" 4 |
| 12606 |
.el .IP \f(CWfoldEQ_locale\fR 4 |
| 12607 |
.IX Xref "foldEQ_locale" |
| 12608 |
.IX Item "foldEQ_locale" |
| 12609 |
Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the |
| 12610 |
same case-insensitively in the current locale; false otherwise. |
| 12611 |
.RS 4 |
| 12612 |
.Sp |
| 12613 |
.Vb 1 |
| 12614 |
\& I32 foldEQ_locale(const char *a, const char *b, I32 len) |
| 12615 |
.Ve |
| 12616 |
.RE |
| 12617 |
.RS 4 |
| 12618 |
.RE |
| 12619 |
.ie n .IP """HAS_DUPLOCALE""" 4 |
| 12620 |
.el .IP \f(CWHAS_DUPLOCALE\fR 4 |
| 12621 |
.IX Xref "HAS_DUPLOCALE" |
| 12622 |
.IX Item "HAS_DUPLOCALE" |
| 12623 |
This symbol, if defined, indicates that the \f(CW\*(C`duplocale\*(C'\fR routine is |
| 12624 |
available to duplicate a locale object. |
| 12625 |
.ie n .IP """HAS_FREELOCALE""" 4 |
| 12626 |
.el .IP \f(CWHAS_FREELOCALE\fR 4 |
| 12627 |
.IX Xref "HAS_FREELOCALE" |
| 12628 |
.IX Item "HAS_FREELOCALE" |
| 12629 |
This symbol, if defined, indicates that the \f(CW\*(C`freelocale\*(C'\fR routine is |
| 12630 |
available to deallocates the resources associated with a locale object. |
| 12631 |
.ie n .IP """HAS_LC_MONETARY_2008""" 4 |
| 12632 |
.el .IP \f(CWHAS_LC_MONETARY_2008\fR 4 |
| 12633 |
.IX Xref "HAS_LC_MONETARY_2008" |
| 12634 |
.IX Item "HAS_LC_MONETARY_2008" |
| 12635 |
This symbol, if defined, indicates that the localeconv routine is |
| 12636 |
available and has the additional members added in \f(CW\*(C`POSIX\*(C'\fR 1003.1\-2008. |
| 12637 |
.ie n .IP """HAS_LOCALECONV""" 4 |
| 12638 |
.el .IP \f(CWHAS_LOCALECONV\fR 4 |
| 12639 |
.IX Xref "HAS_LOCALECONV" |
| 12640 |
.IX Item "HAS_LOCALECONV" |
| 12641 |
This symbol, if defined, indicates that the \f(CW\*(C`localeconv\*(C'\fR routine is |
| 12642 |
available for numeric and monetary formatting conventions. |
| 12643 |
.ie n .IP """HAS_LOCALECONV_L""" 4 |
| 12644 |
.el .IP \f(CWHAS_LOCALECONV_L\fR 4 |
| 12645 |
.IX Xref "HAS_LOCALECONV_L" |
| 12646 |
.IX Item "HAS_LOCALECONV_L" |
| 12647 |
This symbol, if defined, indicates that the \f(CW\*(C`localeconv_l\*(C'\fR routine is |
| 12648 |
available to query certain information about a locale. |
| 12649 |
.ie n .IP """HAS_NEWLOCALE""" 4 |
| 12650 |
.el .IP \f(CWHAS_NEWLOCALE\fR 4 |
| 12651 |
.IX Xref "HAS_NEWLOCALE" |
| 12652 |
.IX Item "HAS_NEWLOCALE" |
| 12653 |
This symbol, if defined, indicates that the \f(CW\*(C`newlocale\*(C'\fR routine is |
| 12654 |
available to return a new locale object or modify an existing |
| 12655 |
locale object. |
| 12656 |
.ie n .IP """HAS_NL_LANGINFO""" 4 |
| 12657 |
.el .IP \f(CWHAS_NL_LANGINFO\fR 4 |
| 12658 |
.IX Xref "HAS_NL_LANGINFO" |
| 12659 |
.IX Item "HAS_NL_LANGINFO" |
| 12660 |
This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo\*(C'\fR routine is |
| 12661 |
available to return locale data. You will also need \fIlanginfo.h\fR |
| 12662 |
and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR. |
| 12663 |
.ie n .IP """HAS_NL_LANGINFO_L""" 4 |
| 12664 |
.el .IP \f(CWHAS_NL_LANGINFO_L\fR 4 |
| 12665 |
.IX Xref "HAS_NL_LANGINFO_L" |
| 12666 |
.IX Item "HAS_NL_LANGINFO_L" |
| 12667 |
This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo_l\*(C'\fR routine is |
| 12668 |
available to return locale data. You will also need \fIlanginfo.h\fR |
| 12669 |
and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR. |
| 12670 |
.ie n .IP """HAS_QUERYLOCALE""" 4 |
| 12671 |
.el .IP \f(CWHAS_QUERYLOCALE\fR 4 |
| 12672 |
.IX Xref "HAS_QUERYLOCALE" |
| 12673 |
.IX Item "HAS_QUERYLOCALE" |
| 12674 |
This symbol, if defined, indicates that the \f(CW\*(C`querylocale\*(C'\fR routine is |
| 12675 |
available to return the name of the locale for a category mask. |
| 12676 |
.ie n .IP """HAS_SETLOCALE""" 4 |
| 12677 |
.el .IP \f(CWHAS_SETLOCALE\fR 4 |
| 12678 |
.IX Xref "HAS_SETLOCALE" |
| 12679 |
.IX Item "HAS_SETLOCALE" |
| 12680 |
This symbol, if defined, indicates that the \f(CW\*(C`setlocale\*(C'\fR routine is |
| 12681 |
available to handle locale-specific ctype implementations. |
| 12682 |
.ie n .IP """HAS_SETLOCALE_R""" 4 |
| 12683 |
.el .IP \f(CWHAS_SETLOCALE_R\fR 4 |
| 12684 |
.IX Xref "HAS_SETLOCALE_R" |
| 12685 |
.IX Item "HAS_SETLOCALE_R" |
| 12686 |
This symbol, if defined, indicates that the \f(CW\*(C`setlocale_r\*(C'\fR routine |
| 12687 |
is available to setlocale re-entrantly. |
| 12688 |
.ie n .IP """HAS_USELOCALE""" 4 |
| 12689 |
.el .IP \f(CWHAS_USELOCALE\fR 4 |
| 12690 |
.IX Xref "HAS_USELOCALE" |
| 12691 |
.IX Item "HAS_USELOCALE" |
| 12692 |
This symbol, if defined, indicates that the \f(CW\*(C`uselocale\*(C'\fR routine is |
| 12693 |
available to set the current locale for the calling thread. |
| 12694 |
.ie n .IP """I_LANGINFO""" 4 |
| 12695 |
.el .IP \f(CWI_LANGINFO\fR 4 |
| 12696 |
.IX Xref "I_LANGINFO" |
| 12697 |
.IX Item "I_LANGINFO" |
| 12698 |
This symbol, if defined, indicates that \fIlanginfo.h\fR exists and |
| 12699 |
should be included. |
| 12700 |
.RS 4 |
| 12701 |
.Sp |
| 12702 |
.Vb 3 |
| 12703 |
\& #ifdef I_LANGINFO |
| 12704 |
\& #include <langinfo.h> |
| 12705 |
\& #endif |
| 12706 |
.Ve |
| 12707 |
.RE |
| 12708 |
.RS 4 |
| 12709 |
.RE |
| 12710 |
.ie n .IP """I_LOCALE""" 4 |
| 12711 |
.el .IP \f(CWI_LOCALE\fR 4 |
| 12712 |
.IX Xref "I_LOCALE" |
| 12713 |
.IX Item "I_LOCALE" |
| 12714 |
This symbol, if defined, indicates to the C program that it should |
| 12715 |
include \fIlocale.h\fR. |
| 12716 |
.RS 4 |
| 12717 |
.Sp |
| 12718 |
.Vb 3 |
| 12719 |
\& #ifdef I_LOCALE |
| 12720 |
\& #include <locale.h> |
| 12721 |
\& #endif |
| 12722 |
.Ve |
| 12723 |
.RE |
| 12724 |
.RS 4 |
| 12725 |
.RE |
| 12726 |
.ie n .IP """IN_LOCALE""" 4 |
| 12727 |
.el .IP \f(CWIN_LOCALE\fR 4 |
| 12728 |
.IX Xref "IN_LOCALE" |
| 12729 |
.IX Item "IN_LOCALE" |
| 12730 |
Evaluates to TRUE if the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect. |
| 12731 |
.RS 4 |
| 12732 |
.Sp |
| 12733 |
.Vb 1 |
| 12734 |
\& bool IN_LOCALE |
| 12735 |
.Ve |
| 12736 |
.RE |
| 12737 |
.RS 4 |
| 12738 |
.RE |
| 12739 |
.ie n .IP """IN_LOCALE_COMPILETIME""" 4 |
| 12740 |
.el .IP \f(CWIN_LOCALE_COMPILETIME\fR 4 |
| 12741 |
.IX Xref "IN_LOCALE_COMPILETIME" |
| 12742 |
.IX Item "IN_LOCALE_COMPILETIME" |
| 12743 |
Evaluates to TRUE if, when compiling a perl program (including an \f(CW\*(C`eval\*(C'\fR) if |
| 12744 |
the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect. |
| 12745 |
.RS 4 |
| 12746 |
.Sp |
| 12747 |
.Vb 1 |
| 12748 |
\& bool IN_LOCALE_COMPILETIME |
| 12749 |
.Ve |
| 12750 |
.RE |
| 12751 |
.RS 4 |
| 12752 |
.RE |
| 12753 |
.ie n .IP """IN_LOCALE_RUNTIME""" 4 |
| 12754 |
.el .IP \f(CWIN_LOCALE_RUNTIME\fR 4 |
| 12755 |
.IX Xref "IN_LOCALE_RUNTIME" |
| 12756 |
.IX Item "IN_LOCALE_RUNTIME" |
| 12757 |
Evaluates to TRUE if, when executing a perl program (including an \f(CW\*(C`eval\*(C'\fR) if |
| 12758 |
the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect. |
| 12759 |
.RS 4 |
| 12760 |
.Sp |
| 12761 |
.Vb 1 |
| 12762 |
\& bool IN_LOCALE_RUNTIME |
| 12763 |
.Ve |
| 12764 |
.RE |
| 12765 |
.RS 4 |
| 12766 |
.RE |
| 12767 |
.ie n .IP """I_XLOCALE""" 4 |
| 12768 |
.el .IP \f(CWI_XLOCALE\fR 4 |
| 12769 |
.IX Xref "I_XLOCALE" |
| 12770 |
.IX Item "I_XLOCALE" |
| 12771 |
This symbol, if defined, indicates to the C program that the |
| 12772 |
header \fIxlocale.h\fR is available. See also \f(CW"NEED_XLOCALE_H"\fR |
| 12773 |
.RS 4 |
| 12774 |
.Sp |
| 12775 |
.Vb 3 |
| 12776 |
\& #ifdef I_XLOCALE |
| 12777 |
\& #include <xlocale.h> |
| 12778 |
\& #endif |
| 12779 |
.Ve |
| 12780 |
.RE |
| 12781 |
.RS 4 |
| 12782 |
.RE |
| 12783 |
.ie n .IP """NEED_XLOCALE_H""" 4 |
| 12784 |
.el .IP \f(CWNEED_XLOCALE_H\fR 4 |
| 12785 |
.IX Xref "NEED_XLOCALE_H" |
| 12786 |
.IX Item "NEED_XLOCALE_H" |
| 12787 |
This symbol, if defined, indicates that the C program should |
| 12788 |
include \fIxlocale.h\fR to get \f(CWnewlocale()\fR and its friends. |
| 12789 |
.ie n .IP """Perl_langinfo""" 4 |
| 12790 |
.el .IP \f(CWPerl_langinfo\fR 4 |
| 12791 |
.IX Item "Perl_langinfo" |
| 12792 |
.PD 0 |
| 12793 |
.ie n .IP """Perl_langinfo8""" 4 |
| 12794 |
.el .IP \f(CWPerl_langinfo8\fR 4 |
| 12795 |
.IX Xref "Perl_langinfo Perl_langinfo8" |
| 12796 |
.IX Item "Perl_langinfo8" |
| 12797 |
.PD |
| 12798 |
\&\f(CW\*(C`Perl_langinfo\*(C'\fR is an (almost) drop-in replacement for the system |
| 12799 |
\&\f(CWnl_langinfo(3)\fR, taking the same \f(CW\*(C`item\*(C'\fR parameter values, and returning |
| 12800 |
the same information. But it is more thread-safe than regular |
| 12801 |
\&\f(CWnl_langinfo()\fR, and hides the quirks of Perl's locale handling from your |
| 12802 |
code, and can be used on systems that lack a native \f(CW\*(C`nl_langinfo\*(C'\fR. |
| 12803 |
.Sp |
| 12804 |
However, you should instead use either the improved version of this, |
| 12805 |
"Perl_langinfo8", or even better, "sv_langinfo". The latter returns an SV, |
| 12806 |
handling all the possible non-standard returns of \f(CWnl_langinfo()\fR, including |
| 12807 |
the UTF8ness of any returned string. |
| 12808 |
.Sp |
| 12809 |
\&\f(CW\*(C`Perl_langinfo8\*(C'\fR is identical to \f(CW\*(C`Perl_langinfo\*(C'\fR except for an additional |
| 12810 |
parameter, a pointer to a variable declared as "\f(CW\*(C`utf8ness_t\*(C'\fR", into which it |
| 12811 |
returns to you how you should treat the returned string with regards to it |
| 12812 |
being encoded in UTF\-8 or not. |
| 12813 |
.Sp |
| 12814 |
These two functions share private per-thread memory that will be changed the |
| 12815 |
next time either one of them is called with any input, but not before. |
| 12816 |
.Sp |
| 12817 |
Concerning the differences between these and plain \f(CWnl_langinfo()\fR: |
| 12818 |
.RS 4 |
| 12819 |
.IP a. 4 |
| 12820 |
.IX Item "a." |
| 12821 |
\&\f(CW\*(C`Perl_langinfo8\*(C'\fR has an extra parameter, described above. Besides this, the |
| 12822 |
other reason they aren't quite a drop-in replacement is actually an advantage. |
| 12823 |
The \f(CW\*(C`const\*(C'\fRness of the return allows the compiler to catch attempts to write |
| 12824 |
into the returned buffer, which is illegal and could cause run-time crashes. |
| 12825 |
.IP b. 4 |
| 12826 |
.IX Item "b." |
| 12827 |
They deliver the correct results for the \f(CW\*(C`RADIXCHAR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR items, |
| 12828 |
without you having to write extra code. The reason for the extra code would be |
| 12829 |
because these are from the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale category, which is normally |
| 12830 |
kept set by Perl so that the radix is a dot, and the separator is the empty |
| 12831 |
string, no matter what the underlying locale is supposed to be, and so to get |
| 12832 |
the expected results, you have to temporarily toggle into the underlying |
| 12833 |
locale, and later toggle back. (You could use plain \f(CW\*(C`nl_langinfo\*(C'\fR and |
| 12834 |
\&\f(CW"STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"\fR for this but then you wouldn't get |
| 12835 |
the other advantages of \f(CWPerl_langinfo()\fR; not keeping \f(CW\*(C`LC_NUMERIC\*(C'\fR in the C |
| 12836 |
(or equivalent) locale would break a lot of CPAN, which is expecting the radix |
| 12837 |
(decimal point) character to be a dot.) |
| 12838 |
.IP c. 4 |
| 12839 |
.IX Item "c." |
| 12840 |
The system function they replace can have its static return buffer trashed, |
| 12841 |
not only by a subsequent call to that function, but by a \f(CW\*(C`freelocale\*(C'\fR, |
| 12842 |
\&\f(CW\*(C`setlocale\*(C'\fR, or other locale change. The returned buffer of these functions |
| 12843 |
is not changed until the next call to one or the other, so the buffer is never |
| 12844 |
in a trashed state. |
| 12845 |
.IP d. 4 |
| 12846 |
.IX Item "d." |
| 12847 |
The return buffer is per-thread, so it also is never overwritten by a call to |
| 12848 |
these functions from another thread; unlike the function it replaces. |
| 12849 |
.IP e. 4 |
| 12850 |
.IX Item "e." |
| 12851 |
But most importantly, they work on systems that don't have \f(CW\*(C`nl_langinfo\*(C'\fR, such |
| 12852 |
as Windows, hence making your code more portable. Of the fifty-some possible |
| 12853 |
items specified by the POSIX 2008 standard, |
| 12854 |
<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>, |
| 12855 |
only one is completely unimplemented, though on non-Windows platforms, another |
| 12856 |
significant one is not fully implemented). They use various techniques to |
| 12857 |
recover the other items, including calling \f(CWlocaleconv(3)\fR, and |
| 12858 |
\&\f(CWstrftime(3)\fR, both of which are specified in C89, so should be always be |
| 12859 |
available. Later \f(CWstrftime()\fR versions have additional capabilities. |
| 12860 |
If an item is not available on your system, this returns either the value |
| 12861 |
associated with the C locale, or simply \f(CW""\fR, whichever is more appropriate. |
| 12862 |
.Sp |
| 12863 |
It is important to note that, when called with an item that is recovered by |
| 12864 |
using \f(CW\*(C`localeconv\*(C'\fR, the buffer from any previous explicit call to |
| 12865 |
\&\f(CWlocaleconv(3)\fR will be overwritten. But you shouldn't be using |
| 12866 |
\&\f(CW\*(C`localeconv\*(C'\fR anyway because it is is very much not thread-safe, and suffers |
| 12867 |
from the same problems outlined in item 'b.' above for the fields it returns |
| 12868 |
that are controlled by the LC_NUMERIC locale category. Instead, avoid all of |
| 12869 |
those problems by calling "Perl_localeconv", which is thread-safe; or by |
| 12870 |
using the methods given in perlcall to call |
| 12871 |
\&\f(CWPOSIX::localeconv()\fR, which is also thread-safe. |
| 12872 |
.RE |
| 12873 |
.RS 4 |
| 12874 |
.Sp |
| 12875 |
The details for those items which may deviate from what this emulation returns |
| 12876 |
and what a native \f(CWnl_langinfo()\fR would return are specified in |
| 12877 |
I18N::Langinfo. |
| 12878 |
.Sp |
| 12879 |
.Vb 3 |
| 12880 |
\& const char * Perl_langinfo (const nl_item item) |
| 12881 |
\& const char * Perl_langinfo8(const nl_item item, |
| 12882 |
\& utf8ness_t *utf8ness) |
| 12883 |
.Ve |
| 12884 |
.RE |
| 12885 |
.RS 4 |
| 12886 |
.RE |
| 12887 |
.ie n .IP """PERL_LC_ALL_CATEGORY_POSITIONS_INIT""" 4 |
| 12888 |
.el .IP \f(CWPERL_LC_ALL_CATEGORY_POSITIONS_INIT\fR 4 |
| 12889 |
.IX Xref "PERL_LC_ALL_CATEGORY_POSITIONS_INIT" |
| 12890 |
.IX Item "PERL_LC_ALL_CATEGORY_POSITIONS_INIT" |
| 12891 |
This symbol, when defined, gives the C initializer for an array whose |
| 12892 |
element [0] is the first category in the string returned by |
| 12893 |
\&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR when not all categories are the same, on |
| 12894 |
systems that use a positional notation. After element [0] is |
| 12895 |
\&\f(CW\*(C`LC_ALL_SEPARATOR\*(C'\fR, then the category given by element [1] and so on. |
| 12896 |
.ie n .IP """PERL_LC_ALL_SEPARATOR""" 4 |
| 12897 |
.el .IP \f(CWPERL_LC_ALL_SEPARATOR\fR 4 |
| 12898 |
.IX Xref "PERL_LC_ALL_SEPARATOR" |
| 12899 |
.IX Item "PERL_LC_ALL_SEPARATOR" |
| 12900 |
This symbol, if defined, gives the string returned by |
| 12901 |
\&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR to separate categories that are in different |
| 12902 |
locales on systems that use a positional notation as opposed to |
| 12903 |
\&'name=value' pairs. An example on some platforms could be the '/' in |
| 12904 |
"C/\f(CW\*(C`de_DE\*(C'\fR/C/\f(CW\*(C`en_UK\*(C'\fR/C/C" |
| 12905 |
.ie n .IP """PERL_LC_ALL_USES_NAME_VALUE_PAIRS""" 4 |
| 12906 |
.el .IP \f(CWPERL_LC_ALL_USES_NAME_VALUE_PAIRS\fR 4 |
| 12907 |
.IX Xref "PERL_LC_ALL_USES_NAME_VALUE_PAIRS" |
| 12908 |
.IX Item "PERL_LC_ALL_USES_NAME_VALUE_PAIRS" |
| 12909 |
This symbol, if defined, indicates to the C program that the string |
| 12910 |
returned by \f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR uses 'name=value;' pairs to |
| 12911 |
indicate what each category's locale is when they aren't all set to the |
| 12912 |
same locale. For example, "\f(CW\*(C`LC_NUMERIC\*(C'\fR=C;\f(CW\*(C`LC_CTYPE\*(C'\fR=\f(CW\*(C`de_DE\*(C'\fR;..." |
| 12913 |
When not defined, the system uses positional notation. |
| 12914 |
.ie n .IP """Perl_localeconv""" 4 |
| 12915 |
.el .IP \f(CWPerl_localeconv\fR 4 |
| 12916 |
.IX Xref "Perl_localeconv" |
| 12917 |
.IX Item "Perl_localeconv" |
| 12918 |
This is a thread-safe version of the libc \fBlocaleconv\fR\|(3). It is the same as |
| 12919 |
POSIX::localeconv (returning a hash of the \f(CWlocaleconv()\fR |
| 12920 |
fields), but directly callable from XS code. The hash is mortalized, so must |
| 12921 |
be dealt with immediately. |
| 12922 |
.RS 4 |
| 12923 |
.Sp |
| 12924 |
.Vb 1 |
| 12925 |
\& HV * Perl_localeconv(pTHX) |
| 12926 |
.Ve |
| 12927 |
.RE |
| 12928 |
.RS 4 |
| 12929 |
.RE |
| 12930 |
.ie n .IP """Perl_setlocale""" 4 |
| 12931 |
.el .IP \f(CWPerl_setlocale\fR 4 |
| 12932 |
.IX Xref "Perl_setlocale" |
| 12933 |
.IX Item "Perl_setlocale" |
| 12934 |
This is an (almost) drop-in replacement for the system \f(CWsetlocale(3)\fR, |
| 12935 |
taking the same parameters, and returning the same information, except that it |
| 12936 |
returns the correct underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR locale. Regular \f(CW\*(C`setlocale\*(C'\fR will |
| 12937 |
instead return \f(CW\*(C`C\*(C'\fR if the underlying locale has a non-dot decimal point |
| 12938 |
character, or a non-empty thousands separator for displaying floating point |
| 12939 |
numbers. This is because perl keeps that locale category such that it has a |
| 12940 |
dot and empty separator, changing the locale briefly during the operations |
| 12941 |
where the underlying one is required. \f(CW\*(C`Perl_setlocale\*(C'\fR knows about this, and |
| 12942 |
compensates; regular \f(CW\*(C`setlocale\*(C'\fR doesn't. |
| 12943 |
.Sp |
| 12944 |
Another reason it isn't completely a drop-in replacement is that it is |
| 12945 |
declared to return \f(CW\*(C`const\ char\ *\*(C'\fR, whereas the system setlocale omits the |
| 12946 |
\&\f(CW\*(C`const\*(C'\fR (presumably because its API was specified long ago, and can't be |
| 12947 |
updated; it is illegal to change the information \f(CW\*(C`setlocale\*(C'\fR returns; doing |
| 12948 |
so leads to segfaults.) |
| 12949 |
.Sp |
| 12950 |
Finally, \f(CW\*(C`Perl_setlocale\*(C'\fR works under all circumstances, whereas plain |
| 12951 |
\&\f(CW\*(C`setlocale\*(C'\fR can be completely ineffective on some platforms under some |
| 12952 |
configurations. |
| 12953 |
.Sp |
| 12954 |
Changing the locale is not a good idea when more than one thread is running, |
| 12955 |
except on systems where the predefined variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is |
| 12956 |
non-zero. This is because on such systems the locale is global to the whole |
| 12957 |
process and not local to just the thread calling the function. So changing it |
| 12958 |
in one thread instantaneously changes it in all. On some such systems, the |
| 12959 |
system \f(CWsetlocale()\fR is ineffective, returning the wrong information, and |
| 12960 |
failing to actually change the locale. z/OS refuses to try to change the |
| 12961 |
locale once a second thread is created. \f(CW\*(C`Perl_setlocale\*(C'\fR, should give you |
| 12962 |
accurate results of what actually happened on these problematic platforms, |
| 12963 |
returning NULL if the system forbade the locale change. |
| 12964 |
.Sp |
| 12965 |
The return points to a per-thread static buffer, which is overwritten the next |
| 12966 |
time \f(CW\*(C`Perl_setlocale\*(C'\fR is called from the same thread. |
| 12967 |
.RS 4 |
| 12968 |
.Sp |
| 12969 |
.Vb 2 |
| 12970 |
\& const char * Perl_setlocale(const int category, |
| 12971 |
\& const char *locale) |
| 12972 |
.Ve |
| 12973 |
.RE |
| 12974 |
.RS 4 |
| 12975 |
.RE |
| 12976 |
.ie n .IP """RESTORE_LC_NUMERIC""" 4 |
| 12977 |
.el .IP \f(CWRESTORE_LC_NUMERIC\fR 4 |
| 12978 |
.IX Xref "RESTORE_LC_NUMERIC" |
| 12979 |
.IX Item "RESTORE_LC_NUMERIC" |
| 12980 |
This is used in conjunction with one of the macros |
| 12981 |
"STORE_LC_NUMERIC_SET_TO_NEEDED" |
| 12982 |
and "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the |
| 12983 |
\&\f(CW\*(C`LC_NUMERIC\*(C'\fR state. |
| 12984 |
.Sp |
| 12985 |
A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to |
| 12986 |
declare at compile time a private variable used by this macro and the two |
| 12987 |
\&\f(CW\*(C`STORE\*(C'\fR ones. This macro should be called as a single statement, not an |
| 12988 |
expression, but with an empty argument list, like this: |
| 12989 |
.Sp |
| 12990 |
.Vb 6 |
| 12991 |
\& { |
| 12992 |
\& DECLARATION_FOR_LC_NUMERIC_MANIPULATION; |
| 12993 |
\& ... |
| 12994 |
\& RESTORE_LC_NUMERIC(); |
| 12995 |
\& ... |
| 12996 |
\& } |
| 12997 |
.Ve |
| 12998 |
.RS 4 |
| 12999 |
.Sp |
| 13000 |
.Vb 1 |
| 13001 |
\& void RESTORE_LC_NUMERIC() |
| 13002 |
.Ve |
| 13003 |
.RE |
| 13004 |
.RS 4 |
| 13005 |
.RE |
| 13006 |
.ie n .IP """SETLOCALE_ACCEPTS_ANY_LOCALE_NAME""" 4 |
| 13007 |
.el .IP \f(CWSETLOCALE_ACCEPTS_ANY_LOCALE_NAME\fR 4 |
| 13008 |
.IX Xref "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME" |
| 13009 |
.IX Item "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME" |
| 13010 |
This symbol, if defined, indicates that the setlocale routine is |
| 13011 |
available and it accepts any input locale name as valid. |
| 13012 |
.ie n .IP """STORE_LC_NUMERIC_FORCE_TO_UNDERLYING""" 4 |
| 13013 |
.el .IP \f(CWSTORE_LC_NUMERIC_FORCE_TO_UNDERLYING\fR 4 |
| 13014 |
.IX Xref "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" |
| 13015 |
.IX Item "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" |
| 13016 |
This is used by XS code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware to force the |
| 13017 |
locale for category \f(CW\*(C`LC_NUMERIC\*(C'\fR to be what perl thinks is the current |
| 13018 |
underlying locale. (The perl interpreter could be wrong about what the |
| 13019 |
underlying locale actually is if some C or XS code has called the C library |
| 13020 |
function \fBsetlocale\fR\|(3) behind its back; calling "sync_locale" before calling |
| 13021 |
this macro will update perl's records.) |
| 13022 |
.Sp |
| 13023 |
A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to |
| 13024 |
declare at compile time a private variable used by this macro. This macro |
| 13025 |
should be called as a single statement, not an expression, but with an empty |
| 13026 |
argument list, like this: |
| 13027 |
.Sp |
| 13028 |
.Vb 8 |
| 13029 |
\& { |
| 13030 |
\& DECLARATION_FOR_LC_NUMERIC_MANIPULATION; |
| 13031 |
\& ... |
| 13032 |
\& STORE_LC_NUMERIC_FORCE_TO_UNDERLYING(); |
| 13033 |
\& ... |
| 13034 |
\& RESTORE_LC_NUMERIC(); |
| 13035 |
\& ... |
| 13036 |
\& } |
| 13037 |
.Ve |
| 13038 |
.Sp |
| 13039 |
The private variable is used to save the current locale state, so |
| 13040 |
that the requisite matching call to "RESTORE_LC_NUMERIC" can restore it. |
| 13041 |
.Sp |
| 13042 |
On threaded perls not operating with thread-safe functionality, this macro uses |
| 13043 |
a mutex to force a critical section. Therefore the matching RESTORE should be |
| 13044 |
close by, and guaranteed to be called. |
| 13045 |
.RS 4 |
| 13046 |
.Sp |
| 13047 |
.Vb 1 |
| 13048 |
\& void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING() |
| 13049 |
.Ve |
| 13050 |
.RE |
| 13051 |
.RS 4 |
| 13052 |
.RE |
| 13053 |
.ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED""" 4 |
| 13054 |
.el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED\fR 4 |
| 13055 |
.IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED" |
| 13056 |
.IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED" |
| 13057 |
This is used to help wrap XS or C code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware. |
| 13058 |
This locale category is generally kept set to a locale where the decimal radix |
| 13059 |
character is a dot, and the separator between groups of digits is empty. This |
| 13060 |
is because most XS code that reads floating point numbers is expecting them to |
| 13061 |
have this syntax. |
| 13062 |
.Sp |
| 13063 |
This macro makes sure the current \f(CW\*(C`LC_NUMERIC\*(C'\fR state is set properly, to be |
| 13064 |
aware of locale if the call to the XS or C code from the Perl program is |
| 13065 |
from within the scope of a \f(CW\*(C`use\ locale\*(C'\fR; or to ignore locale if the call is |
| 13066 |
instead from outside such scope. |
| 13067 |
.Sp |
| 13068 |
This macro is the start of wrapping the C or XS code; the wrap ending is done |
| 13069 |
by calling the "RESTORE_LC_NUMERIC" macro after the operation. Otherwise |
| 13070 |
the state can be changed that will adversely affect other XS code. |
| 13071 |
.Sp |
| 13072 |
A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to |
| 13073 |
declare at compile time a private variable used by this macro. This macro |
| 13074 |
should be called as a single statement, not an expression, but with an empty |
| 13075 |
argument list, like this: |
| 13076 |
.Sp |
| 13077 |
.Vb 8 |
| 13078 |
\& { |
| 13079 |
\& DECLARATION_FOR_LC_NUMERIC_MANIPULATION; |
| 13080 |
\& ... |
| 13081 |
\& STORE_LC_NUMERIC_SET_TO_NEEDED(); |
| 13082 |
\& ... |
| 13083 |
\& RESTORE_LC_NUMERIC(); |
| 13084 |
\& ... |
| 13085 |
\& } |
| 13086 |
.Ve |
| 13087 |
.Sp |
| 13088 |
On threaded perls not operating with thread-safe functionality, this macro uses |
| 13089 |
a mutex to force a critical section. Therefore the matching RESTORE should be |
| 13090 |
close by, and guaranteed to be called; see "WITH_LC_NUMERIC_SET_TO_NEEDED" |
| 13091 |
for a more contained way to ensure that. |
| 13092 |
.RS 4 |
| 13093 |
.Sp |
| 13094 |
.Vb 1 |
| 13095 |
\& void STORE_LC_NUMERIC_SET_TO_NEEDED() |
| 13096 |
.Ve |
| 13097 |
.RE |
| 13098 |
.RS 4 |
| 13099 |
.RE |
| 13100 |
.ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED_IN""" 4 |
| 13101 |
.el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4 |
| 13102 |
.IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED_IN" |
| 13103 |
.IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED_IN" |
| 13104 |
Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided |
| 13105 |
as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's |
| 13106 |
responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR |
| 13107 |
cannot have changed since the precalculation. |
| 13108 |
.RS 4 |
| 13109 |
.Sp |
| 13110 |
.Vb 1 |
| 13111 |
\& void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric) |
| 13112 |
.Ve |
| 13113 |
.RE |
| 13114 |
.RS 4 |
| 13115 |
.RE |
| 13116 |
.ie n .IP """sv_langinfo""" 4 |
| 13117 |
.el .IP \f(CWsv_langinfo\fR 4 |
| 13118 |
.IX Xref "sv_langinfo" |
| 13119 |
.IX Item "sv_langinfo" |
| 13120 |
This is the preferred interface for accessing the data that \fBnl_langinfo\fR\|(3) |
| 13121 |
provides (or Perl's emulation of it on platforms lacking it), returning an SV. |
| 13122 |
Unlike, the earlier-defined interfaces to this ("Perl_langinfo" and |
| 13123 |
"Perl_langinfo8"), which return strings, the UTF8ness of the result is |
| 13124 |
automatically handled for you. And like them, it is thread-safe and |
| 13125 |
automatically handles getting the proper values for the \f(CW\*(C`RADIXCHAR\*(C'\fR and |
| 13126 |
\&\f(CW\*(C`THOUSEP\*(C'\fR items (that calling the plain libc \f(CWnl_langinfo()\fR could give the |
| 13127 |
wrong results for). Like them, this also doesn't play well with the libc |
| 13128 |
\&\f(CWlocaleconv()\fR; use \f(CWPOSIX::localeconv()\fR instead. |
| 13129 |
.Sp |
| 13130 |
There are a few deviations from what a native \f(CWnl_langinfo()\fR would return and |
| 13131 |
what this returns on platforms that don't implement that function. These are |
| 13132 |
detailed in I18N::Langinfo. |
| 13133 |
.RS 4 |
| 13134 |
.Sp |
| 13135 |
.Vb 1 |
| 13136 |
\& SV * sv_langinfo(const nl_item item) |
| 13137 |
.Ve |
| 13138 |
.RE |
| 13139 |
.RS 4 |
| 13140 |
.RE |
| 13141 |
.ie n .IP """switch_to_global_locale""" 4 |
| 13142 |
.el .IP \f(CWswitch_to_global_locale\fR 4 |
| 13143 |
.IX Xref "switch_to_global_locale" |
| 13144 |
.IX Item "switch_to_global_locale" |
| 13145 |
This function copies the locale state of the calling thread into the program's |
| 13146 |
global locale, and converts the thread to use that global locale. |
| 13147 |
.Sp |
| 13148 |
It is intended so that Perl can safely be used with C libraries that access the |
| 13149 |
global locale and which can't be converted to not access it. Effectively, this |
| 13150 |
means libraries that call \f(CWsetlocale(3)\fR on non-Windows systems. (For |
| 13151 |
portability, it is a good idea to use it on Windows as well.) |
| 13152 |
.Sp |
| 13153 |
A downside of using it is that it disables the services that Perl provides to |
| 13154 |
hide locale gotchas from your code. The service you most likely will miss |
| 13155 |
regards the radix character (decimal point) in floating point numbers. Code |
| 13156 |
executed after this function is called can no longer just assume that this |
| 13157 |
character is correct for the current circumstances. |
| 13158 |
.Sp |
| 13159 |
To return to Perl control, and restart the gotcha prevention services, call |
| 13160 |
\&\f(CW"sync_locale"\fR. Behavior is undefined for any pure Perl code that executes |
| 13161 |
while the switch is in effect. |
| 13162 |
.Sp |
| 13163 |
The global locale and the per-thread locales are independent. As long as just |
| 13164 |
one thread converts to the global locale, everything works smoothly. But if |
| 13165 |
more than one does, they can easily interfere with each other, and races are |
| 13166 |
likely. On Windows systems prior to Visual Studio 15 (at which point Microsoft |
| 13167 |
fixed a bug), races can occur (even if only one thread has been converted to |
| 13168 |
the global locale), but only if you use the following operations: |
| 13169 |
.RS 4 |
| 13170 |
.IP POSIX::localeconv 4 |
| 13171 |
.IX Item "POSIX::localeconv" |
| 13172 |
.PD 0 |
| 13173 |
.ie n .IP "I18N::Langinfo, items ""CRNCYSTR"" and ""THOUSEP""" 4 |
| 13174 |
.el .IP "I18N::Langinfo, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4 |
| 13175 |
.IX Item "I18N::Langinfo, items CRNCYSTR and THOUSEP" |
| 13176 |
.ie n .IP """sv_langinfo"" in perlapi, items ""CRNCYSTR"" and ""THOUSEP""" 4 |
| 13177 |
.el .IP """sv_langinfo"" in perlapi, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4 |
| 13178 |
.IX Item """sv_langinfo"" in perlapi, items CRNCYSTR and THOUSEP" |
| 13179 |
.RE |
| 13180 |
.RS 4 |
| 13181 |
.PD |
| 13182 |
.Sp |
| 13183 |
The first item is not fixable (except by upgrading to a later Visual Studio |
| 13184 |
release), but it would be possible to work around the latter two items by |
| 13185 |
having Perl change its algorithm for calculating these to use Windows API |
| 13186 |
functions (likely \f(CW\*(C`GetNumberFormat\*(C'\fR and \f(CW\*(C`GetCurrencyFormat\*(C'\fR); patches |
| 13187 |
welcome. |
| 13188 |
.Sp |
| 13189 |
XS code should never call plain \f(CW\*(C`setlocale\*(C'\fR, but should instead be converted |
| 13190 |
to either call \f(CW\*(C`Perl_setlocale\*(C'\fR (which is a drop-in |
| 13191 |
for the system \f(CW\*(C`setlocale\*(C'\fR) or use the methods given in perlcall to call |
| 13192 |
\&\f(CW\*(C`POSIX::setlocale\*(C'\fR. Either one will transparently properly |
| 13193 |
handle all cases of single\- vs multi-thread, POSIX 2008\-supported or not. |
| 13194 |
.Sp |
| 13195 |
.Vb 1 |
| 13196 |
\& void switch_to_global_locale() |
| 13197 |
.Ve |
| 13198 |
.RE |
| 13199 |
.RS 4 |
| 13200 |
.RE |
| 13201 |
.ie n .IP """sync_locale""" 4 |
| 13202 |
.el .IP \f(CWsync_locale\fR 4 |
| 13203 |
.IX Xref "sync_locale" |
| 13204 |
.IX Item "sync_locale" |
| 13205 |
This function copies the state of the program global locale into the calling |
| 13206 |
thread, and converts that thread to using per-thread locales, if it wasn't |
| 13207 |
already, and the platform supports them. The LC_NUMERIC locale is toggled into |
| 13208 |
the standard state (using the C locale's conventions), if not within the |
| 13209 |
lexical scope of \f(CW\*(C`use\ locale\*(C'\fR. |
| 13210 |
.Sp |
| 13211 |
Perl will now consider itself to have control of the locale. |
| 13212 |
.Sp |
| 13213 |
Since unthreaded perls have only a global locale, this function is a no-op |
| 13214 |
without threads. |
| 13215 |
.Sp |
| 13216 |
This function is intended for use with C libraries that do locale manipulation. |
| 13217 |
It allows Perl to accommodate the use of them. Call this function before |
| 13218 |
transferring back to Perl space so that it knows what state the C code has left |
| 13219 |
things in. |
| 13220 |
.Sp |
| 13221 |
XS code should not manipulate the locale on its own. Instead, |
| 13222 |
\&\f(CW\*(C`Perl_setlocale\*(C'\fR can be used at any time to query or |
| 13223 |
change the locale (though changing the locale is antisocial and dangerous on |
| 13224 |
multi-threaded systems that don't have multi-thread safe locale operations. |
| 13225 |
(See "Multi-threaded operation" in perllocale). |
| 13226 |
.Sp |
| 13227 |
Using the libc \f(CWsetlocale(3)\fR function should be avoided. Nevertheless, |
| 13228 |
certain non-Perl libraries called from XS, do call it, and their behavior may |
| 13229 |
not be able to be changed. This function, along with |
| 13230 |
\&\f(CW"switch_to_global_locale"\fR, can be used to get seamless behavior in these |
| 13231 |
circumstances, as long as only one thread is involved. |
| 13232 |
.Sp |
| 13233 |
If the library has an option to turn off its locale manipulation, doing that is |
| 13234 |
preferable to using this mechanism. \f(CW\*(C`Gtk\*(C'\fR is such a library. |
| 13235 |
.Sp |
| 13236 |
The return value is a boolean: TRUE if the global locale at the time of call |
| 13237 |
was in effect for the caller; and FALSE if a per-thread locale was in effect. |
| 13238 |
.RS 4 |
| 13239 |
.Sp |
| 13240 |
.Vb 1 |
| 13241 |
\& bool sync_locale() |
| 13242 |
.Ve |
| 13243 |
.RE |
| 13244 |
.RS 4 |
| 13245 |
.RE |
| 13246 |
.ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED""" 4 |
| 13247 |
.el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED\fR 4 |
| 13248 |
.IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED" |
| 13249 |
.IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED" |
| 13250 |
This macro invokes the supplied statement or block within the context |
| 13251 |
of a "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC" pair |
| 13252 |
if required, so eg: |
| 13253 |
.Sp |
| 13254 |
.Vb 3 |
| 13255 |
\& WITH_LC_NUMERIC_SET_TO_NEEDED( |
| 13256 |
\& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis) |
| 13257 |
\& ); |
| 13258 |
.Ve |
| 13259 |
.Sp |
| 13260 |
is equivalent to: |
| 13261 |
.Sp |
| 13262 |
.Vb 10 |
| 13263 |
\& { |
| 13264 |
\&#ifdef USE_LOCALE_NUMERIC |
| 13265 |
\& DECLARATION_FOR_LC_NUMERIC_MANIPULATION; |
| 13266 |
\& STORE_LC_NUMERIC_SET_TO_NEEDED(); |
| 13267 |
\&#endif |
| 13268 |
\& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis); |
| 13269 |
\&#ifdef USE_LOCALE_NUMERIC |
| 13270 |
\& RESTORE_LC_NUMERIC(); |
| 13271 |
\&#endif |
| 13272 |
\& } |
| 13273 |
.Ve |
| 13274 |
.RS 4 |
| 13275 |
.Sp |
| 13276 |
.Vb 1 |
| 13277 |
\& void WITH_LC_NUMERIC_SET_TO_NEEDED(block) |
| 13278 |
.Ve |
| 13279 |
.RE |
| 13280 |
.RS 4 |
| 13281 |
.RE |
| 13282 |
.ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED_IN""" 4 |
| 13283 |
.el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4 |
| 13284 |
.IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED_IN" |
| 13285 |
.IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED_IN" |
| 13286 |
Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided |
| 13287 |
as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's |
| 13288 |
responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR |
| 13289 |
cannot have changed since the precalculation. |
| 13290 |
.RS 4 |
| 13291 |
.Sp |
| 13292 |
.Vb 1 |
| 13293 |
\& void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block) |
| 13294 |
.Ve |
| 13295 |
.RE |
| 13296 |
.RS 4 |
| 13297 |
.RE |
| 13298 |
.SH Magic |
| 13299 |
.IX Xref "MAGIC" |
| 13300 |
.IX Header "Magic" |
| 13301 |
"Magic" is special data attached to SV structures in order to give them |
| 13302 |
"magical" properties. When any Perl code tries to read from, or assign to, |
| 13303 |
an SV marked as magical, it calls the 'get' or 'set' function associated |
| 13304 |
with that SV's magic. A get is called prior to reading an SV, in order to |
| 13305 |
give it a chance to update its internal value (get on $. writes the line |
| 13306 |
number of the last read filehandle into the SV's IV slot), while |
| 13307 |
set is called after an SV has been written to, in order to allow it to make |
| 13308 |
use of its changed value (set on $/ copies the SV's new value to the |
| 13309 |
PL_rs global variable). |
| 13310 |
.PP |
| 13311 |
Magic is implemented as a linked list of MAGIC structures attached to the |
| 13312 |
SV. Each MAGIC struct holds the type of the magic, a pointer to an array |
| 13313 |
of functions that implement the \fBget()\fR, \fBset()\fR, \fBlength()\fR etc functions, |
| 13314 |
plus space for some flags and pointers. For example, a tied variable has |
| 13315 |
a MAGIC structure that contains a pointer to the object associated with the |
| 13316 |
tie. |
| 13317 |
.ie n .IP """mg_clear""" 4 |
| 13318 |
.el .IP \f(CWmg_clear\fR 4 |
| 13319 |
.IX Xref "mg_clear" |
| 13320 |
.IX Item "mg_clear" |
| 13321 |
Clear something magical that the SV represents. See \f(CW"sv_magic"\fR. |
| 13322 |
.RS 4 |
| 13323 |
.Sp |
| 13324 |
.Vb 1 |
| 13325 |
\& int mg_clear(SV *sv) |
| 13326 |
.Ve |
| 13327 |
.RE |
| 13328 |
.RS 4 |
| 13329 |
.RE |
| 13330 |
.ie n .IP """mg_copy""" 4 |
| 13331 |
.el .IP \f(CWmg_copy\fR 4 |
| 13332 |
.IX Xref "mg_copy" |
| 13333 |
.IX Item "mg_copy" |
| 13334 |
Copies the magic from one SV to another. See \f(CW"sv_magic"\fR. |
| 13335 |
.RS 4 |
| 13336 |
.Sp |
| 13337 |
.Vb 1 |
| 13338 |
\& int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen) |
| 13339 |
.Ve |
| 13340 |
.RE |
| 13341 |
.RS 4 |
| 13342 |
.RE |
| 13343 |
.ie n .IP """MGf_COPY""" 4 |
| 13344 |
.el .IP \f(CWMGf_COPY\fR 4 |
| 13345 |
.IX Item "MGf_COPY" |
| 13346 |
.PD 0 |
| 13347 |
.ie n .IP """MGf_DUP""" 4 |
| 13348 |
.el .IP \f(CWMGf_DUP\fR 4 |
| 13349 |
.IX Item "MGf_DUP" |
| 13350 |
.ie n .IP """MGf_LOCAL""" 4 |
| 13351 |
.el .IP \f(CWMGf_LOCAL\fR 4 |
| 13352 |
.IX Item "MGf_LOCAL" |
| 13353 |
.PD |
| 13354 |
Described in perlguts. |
| 13355 |
.ie n .IP """mg_find""" 4 |
| 13356 |
.el .IP \f(CWmg_find\fR 4 |
| 13357 |
.IX Xref "mg_find" |
| 13358 |
.IX Item "mg_find" |
| 13359 |
Finds the magic pointer for \f(CW\*(C`type\*(C'\fR matching the SV. See \f(CW"sv_magic"\fR. |
| 13360 |
.RS 4 |
| 13361 |
.Sp |
| 13362 |
.Vb 1 |
| 13363 |
\& MAGIC * mg_find(const SV *sv, int type) |
| 13364 |
.Ve |
| 13365 |
.RE |
| 13366 |
.RS 4 |
| 13367 |
.RE |
| 13368 |
.ie n .IP """mg_findext""" 4 |
| 13369 |
.el .IP \f(CWmg_findext\fR 4 |
| 13370 |
.IX Xref "mg_findext" |
| 13371 |
.IX Item "mg_findext" |
| 13372 |
Finds the magic pointer of \f(CW\*(C`type\*(C'\fR with the given \f(CW\*(C`vtbl\*(C'\fR for the \f(CW\*(C`SV\*(C'\fR. See |
| 13373 |
\&\f(CW"sv_magicext"\fR. |
| 13374 |
.RS 4 |
| 13375 |
.Sp |
| 13376 |
.Vb 1 |
| 13377 |
\& MAGIC * mg_findext(const SV *sv, int type, const MGVTBL *vtbl) |
| 13378 |
.Ve |
| 13379 |
.RE |
| 13380 |
.RS 4 |
| 13381 |
.RE |
| 13382 |
.ie n .IP """mg_free""" 4 |
| 13383 |
.el .IP \f(CWmg_free\fR 4 |
| 13384 |
.IX Xref "mg_free" |
| 13385 |
.IX Item "mg_free" |
| 13386 |
Free any magic storage used by the SV. See \f(CW"sv_magic"\fR. |
| 13387 |
.RS 4 |
| 13388 |
.Sp |
| 13389 |
.Vb 1 |
| 13390 |
\& int mg_free(SV *sv) |
| 13391 |
.Ve |
| 13392 |
.RE |
| 13393 |
.RS 4 |
| 13394 |
.RE |
| 13395 |
.ie n .IP """mg_freeext""" 4 |
| 13396 |
.el .IP \f(CWmg_freeext\fR 4 |
| 13397 |
.IX Xref "mg_freeext" |
| 13398 |
.IX Item "mg_freeext" |
| 13399 |
Remove any magic of type \f(CW\*(C`how\*(C'\fR using virtual table \f(CW\*(C`vtbl\*(C'\fR from the |
| 13400 |
SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic". |
| 13401 |
.Sp |
| 13402 |
\&\f(CW\*(C`mg_freeext(sv, how, NULL)\*(C'\fR is equivalent to \f(CW\*(C`mg_free_type(sv, how)\*(C'\fR. |
| 13403 |
.RS 4 |
| 13404 |
.Sp |
| 13405 |
.Vb 1 |
| 13406 |
\& void mg_freeext(SV *sv, int how, const MGVTBL *vtbl) |
| 13407 |
.Ve |
| 13408 |
.RE |
| 13409 |
.RS 4 |
| 13410 |
.RE |
| 13411 |
.ie n .IP """mg_free_type""" 4 |
| 13412 |
.el .IP \f(CWmg_free_type\fR 4 |
| 13413 |
.IX Xref "mg_free_type" |
| 13414 |
.IX Item "mg_free_type" |
| 13415 |
Remove any magic of type \f(CW\*(C`how\*(C'\fR from the SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic". |
| 13416 |
.RS 4 |
| 13417 |
.Sp |
| 13418 |
.Vb 1 |
| 13419 |
\& void mg_free_type(SV *sv, int how) |
| 13420 |
.Ve |
| 13421 |
.RE |
| 13422 |
.RS 4 |
| 13423 |
.RE |
| 13424 |
.ie n .IP """mg_get""" 4 |
| 13425 |
.el .IP \f(CWmg_get\fR 4 |
| 13426 |
.IX Xref "mg_get" |
| 13427 |
.IX Item "mg_get" |
| 13428 |
Do magic before a value is retrieved from the SV. The type of SV must |
| 13429 |
be >= \f(CW\*(C`SVt_PVMG\*(C'\fR. See \f(CW"sv_magic"\fR. |
| 13430 |
.RS 4 |
| 13431 |
.Sp |
| 13432 |
.Vb 1 |
| 13433 |
\& int mg_get(SV *sv) |
| 13434 |
.Ve |
| 13435 |
.RE |
| 13436 |
.RS 4 |
| 13437 |
.RE |
| 13438 |
.ie n .IP """mg_magical""" 4 |
| 13439 |
.el .IP \f(CWmg_magical\fR 4 |
| 13440 |
.IX Xref "mg_magical" |
| 13441 |
.IX Item "mg_magical" |
| 13442 |
Turns on the magical status of an SV. See \f(CW"sv_magic"\fR. |
| 13443 |
.RS 4 |
| 13444 |
.Sp |
| 13445 |
.Vb 1 |
| 13446 |
\& void mg_magical(SV *sv) |
| 13447 |
.Ve |
| 13448 |
.RE |
| 13449 |
.RS 4 |
| 13450 |
.RE |
| 13451 |
.ie n .IP """mg_set""" 4 |
| 13452 |
.el .IP \f(CWmg_set\fR 4 |
| 13453 |
.IX Xref "mg_set" |
| 13454 |
.IX Item "mg_set" |
| 13455 |
Do magic after a value is assigned to the SV. See \f(CW"sv_magic"\fR. |
| 13456 |
.RS 4 |
| 13457 |
.Sp |
| 13458 |
.Vb 1 |
| 13459 |
\& int mg_set(SV *sv) |
| 13460 |
.Ve |
| 13461 |
.RE |
| 13462 |
.RS 4 |
| 13463 |
.RE |
| 13464 |
.ie n .IP """MGVTBL""" 4 |
| 13465 |
.el .IP \f(CWMGVTBL\fR 4 |
| 13466 |
.IX Item "MGVTBL" |
| 13467 |
Described in perlguts. |
| 13468 |
.ie n .IP """PERL_MAGIC_arylen""" 4 |
| 13469 |
.el .IP \f(CWPERL_MAGIC_arylen\fR 4 |
| 13470 |
.IX Item "PERL_MAGIC_arylen" |
| 13471 |
.PD 0 |
| 13472 |
.ie n .IP """PERL_MAGIC_arylen_p""" 4 |
| 13473 |
.el .IP \f(CWPERL_MAGIC_arylen_p\fR 4 |
| 13474 |
.IX Item "PERL_MAGIC_arylen_p" |
| 13475 |
.ie n .IP """PERL_MAGIC_backref""" 4 |
| 13476 |
.el .IP \f(CWPERL_MAGIC_backref\fR 4 |
| 13477 |
.IX Item "PERL_MAGIC_backref" |
| 13478 |
.ie n .IP """PERL_MAGIC_bm""" 4 |
| 13479 |
.el .IP \f(CWPERL_MAGIC_bm\fR 4 |
| 13480 |
.IX Item "PERL_MAGIC_bm" |
| 13481 |
.ie n .IP """PERL_MAGIC_checkcall""" 4 |
| 13482 |
.el .IP \f(CWPERL_MAGIC_checkcall\fR 4 |
| 13483 |
.IX Item "PERL_MAGIC_checkcall" |
| 13484 |
.ie n .IP """PERL_MAGIC_collxfrm""" 4 |
| 13485 |
.el .IP \f(CWPERL_MAGIC_collxfrm\fR 4 |
| 13486 |
.IX Item "PERL_MAGIC_collxfrm" |
| 13487 |
.ie n .IP """PERL_MAGIC_dbfile""" 4 |
| 13488 |
.el .IP \f(CWPERL_MAGIC_dbfile\fR 4 |
| 13489 |
.IX Item "PERL_MAGIC_dbfile" |
| 13490 |
.ie n .IP """PERL_MAGIC_dbline""" 4 |
| 13491 |
.el .IP \f(CWPERL_MAGIC_dbline\fR 4 |
| 13492 |
.IX Item "PERL_MAGIC_dbline" |
| 13493 |
.ie n .IP """PERL_MAGIC_debugvar""" 4 |
| 13494 |
.el .IP \f(CWPERL_MAGIC_debugvar\fR 4 |
| 13495 |
.IX Item "PERL_MAGIC_debugvar" |
| 13496 |
.ie n .IP """PERL_MAGIC_defelem""" 4 |
| 13497 |
.el .IP \f(CWPERL_MAGIC_defelem\fR 4 |
| 13498 |
.IX Item "PERL_MAGIC_defelem" |
| 13499 |
.ie n .IP """PERL_MAGIC_destruct""" 4 |
| 13500 |
.el .IP \f(CWPERL_MAGIC_destruct\fR 4 |
| 13501 |
.IX Item "PERL_MAGIC_destruct" |
| 13502 |
.ie n .IP """PERL_MAGIC_env""" 4 |
| 13503 |
.el .IP \f(CWPERL_MAGIC_env\fR 4 |
| 13504 |
.IX Item "PERL_MAGIC_env" |
| 13505 |
.ie n .IP """PERL_MAGIC_envelem""" 4 |
| 13506 |
.el .IP \f(CWPERL_MAGIC_envelem\fR 4 |
| 13507 |
.IX Item "PERL_MAGIC_envelem" |
| 13508 |
.ie n .IP """PERL_MAGIC_ext""" 4 |
| 13509 |
.el .IP \f(CWPERL_MAGIC_ext\fR 4 |
| 13510 |
.IX Item "PERL_MAGIC_ext" |
| 13511 |
.ie n .IP """PERL_MAGIC_extvalue""" 4 |
| 13512 |
.el .IP \f(CWPERL_MAGIC_extvalue\fR 4 |
| 13513 |
.IX Item "PERL_MAGIC_extvalue" |
| 13514 |
.ie n .IP """PERL_MAGIC_fm""" 4 |
| 13515 |
.el .IP \f(CWPERL_MAGIC_fm\fR 4 |
| 13516 |
.IX Item "PERL_MAGIC_fm" |
| 13517 |
.ie n .IP """PERL_MAGIC_hints""" 4 |
| 13518 |
.el .IP \f(CWPERL_MAGIC_hints\fR 4 |
| 13519 |
.IX Item "PERL_MAGIC_hints" |
| 13520 |
.ie n .IP """PERL_MAGIC_hintselem""" 4 |
| 13521 |
.el .IP \f(CWPERL_MAGIC_hintselem\fR 4 |
| 13522 |
.IX Item "PERL_MAGIC_hintselem" |
| 13523 |
.ie n .IP """PERL_MAGIC_hook""" 4 |
| 13524 |
.el .IP \f(CWPERL_MAGIC_hook\fR 4 |
| 13525 |
.IX Item "PERL_MAGIC_hook" |
| 13526 |
.ie n .IP """PERL_MAGIC_hookelem""" 4 |
| 13527 |
.el .IP \f(CWPERL_MAGIC_hookelem\fR 4 |
| 13528 |
.IX Item "PERL_MAGIC_hookelem" |
| 13529 |
.ie n .IP """PERL_MAGIC_isa""" 4 |
| 13530 |
.el .IP \f(CWPERL_MAGIC_isa\fR 4 |
| 13531 |
.IX Item "PERL_MAGIC_isa" |
| 13532 |
.ie n .IP """PERL_MAGIC_isaelem""" 4 |
| 13533 |
.el .IP \f(CWPERL_MAGIC_isaelem\fR 4 |
| 13534 |
.IX Item "PERL_MAGIC_isaelem" |
| 13535 |
.ie n .IP """PERL_MAGIC_lvref""" 4 |
| 13536 |
.el .IP \f(CWPERL_MAGIC_lvref\fR 4 |
| 13537 |
.IX Item "PERL_MAGIC_lvref" |
| 13538 |
.ie n .IP """PERL_MAGIC_nkeys""" 4 |
| 13539 |
.el .IP \f(CWPERL_MAGIC_nkeys\fR 4 |
| 13540 |
.IX Item "PERL_MAGIC_nkeys" |
| 13541 |
.ie n .IP """PERL_MAGIC_nonelem""" 4 |
| 13542 |
.el .IP \f(CWPERL_MAGIC_nonelem\fR 4 |
| 13543 |
.IX Item "PERL_MAGIC_nonelem" |
| 13544 |
.ie n .IP """PERL_MAGIC_overload_table""" 4 |
| 13545 |
.el .IP \f(CWPERL_MAGIC_overload_table\fR 4 |
| 13546 |
.IX Item "PERL_MAGIC_overload_table" |
| 13547 |
.ie n .IP """PERL_MAGIC_pos""" 4 |
| 13548 |
.el .IP \f(CWPERL_MAGIC_pos\fR 4 |
| 13549 |
.IX Item "PERL_MAGIC_pos" |
| 13550 |
.ie n .IP """PERL_MAGIC_qr""" 4 |
| 13551 |
.el .IP \f(CWPERL_MAGIC_qr\fR 4 |
| 13552 |
.IX Item "PERL_MAGIC_qr" |
| 13553 |
.ie n .IP """PERL_MAGIC_regdata""" 4 |
| 13554 |
.el .IP \f(CWPERL_MAGIC_regdata\fR 4 |
| 13555 |
.IX Item "PERL_MAGIC_regdata" |
| 13556 |
.ie n .IP """PERL_MAGIC_regdatum""" 4 |
| 13557 |
.el .IP \f(CWPERL_MAGIC_regdatum\fR 4 |
| 13558 |
.IX Item "PERL_MAGIC_regdatum" |
| 13559 |
.ie n .IP """PERL_MAGIC_regex_global""" 4 |
| 13560 |
.el .IP \f(CWPERL_MAGIC_regex_global\fR 4 |
| 13561 |
.IX Item "PERL_MAGIC_regex_global" |
| 13562 |
.ie n .IP """PERL_MAGIC_rhash""" 4 |
| 13563 |
.el .IP \f(CWPERL_MAGIC_rhash\fR 4 |
| 13564 |
.IX Item "PERL_MAGIC_rhash" |
| 13565 |
.ie n .IP """PERL_MAGIC_shared""" 4 |
| 13566 |
.el .IP \f(CWPERL_MAGIC_shared\fR 4 |
| 13567 |
.IX Item "PERL_MAGIC_shared" |
| 13568 |
.ie n .IP """PERL_MAGIC_shared_scalar""" 4 |
| 13569 |
.el .IP \f(CWPERL_MAGIC_shared_scalar\fR 4 |
| 13570 |
.IX Item "PERL_MAGIC_shared_scalar" |
| 13571 |
.ie n .IP """PERL_MAGIC_sig""" 4 |
| 13572 |
.el .IP \f(CWPERL_MAGIC_sig\fR 4 |
| 13573 |
.IX Item "PERL_MAGIC_sig" |
| 13574 |
.ie n .IP """PERL_MAGIC_sigelem""" 4 |
| 13575 |
.el .IP \f(CWPERL_MAGIC_sigelem\fR 4 |
| 13576 |
.IX Item "PERL_MAGIC_sigelem" |
| 13577 |
.ie n .IP """PERL_MAGIC_substr""" 4 |
| 13578 |
.el .IP \f(CWPERL_MAGIC_substr\fR 4 |
| 13579 |
.IX Item "PERL_MAGIC_substr" |
| 13580 |
.ie n .IP """PERL_MAGIC_sv""" 4 |
| 13581 |
.el .IP \f(CWPERL_MAGIC_sv\fR 4 |
| 13582 |
.IX Item "PERL_MAGIC_sv" |
| 13583 |
.ie n .IP """PERL_MAGIC_symtab""" 4 |
| 13584 |
.el .IP \f(CWPERL_MAGIC_symtab\fR 4 |
| 13585 |
.IX Item "PERL_MAGIC_symtab" |
| 13586 |
.ie n .IP """PERL_MAGIC_taint""" 4 |
| 13587 |
.el .IP \f(CWPERL_MAGIC_taint\fR 4 |
| 13588 |
.IX Item "PERL_MAGIC_taint" |
| 13589 |
.ie n .IP """PERL_MAGIC_tied""" 4 |
| 13590 |
.el .IP \f(CWPERL_MAGIC_tied\fR 4 |
| 13591 |
.IX Item "PERL_MAGIC_tied" |
| 13592 |
.ie n .IP """PERL_MAGIC_tiedelem""" 4 |
| 13593 |
.el .IP \f(CWPERL_MAGIC_tiedelem\fR 4 |
| 13594 |
.IX Item "PERL_MAGIC_tiedelem" |
| 13595 |
.ie n .IP """PERL_MAGIC_tiedscalar""" 4 |
| 13596 |
.el .IP \f(CWPERL_MAGIC_tiedscalar\fR 4 |
| 13597 |
.IX Item "PERL_MAGIC_tiedscalar" |
| 13598 |
.ie n .IP """PERL_MAGIC_utf8""" 4 |
| 13599 |
.el .IP \f(CWPERL_MAGIC_utf8\fR 4 |
| 13600 |
.IX Item "PERL_MAGIC_utf8" |
| 13601 |
.ie n .IP """PERL_MAGIC_uvar""" 4 |
| 13602 |
.el .IP \f(CWPERL_MAGIC_uvar\fR 4 |
| 13603 |
.IX Item "PERL_MAGIC_uvar" |
| 13604 |
.ie n .IP """PERL_MAGIC_uvar_elem""" 4 |
| 13605 |
.el .IP \f(CWPERL_MAGIC_uvar_elem\fR 4 |
| 13606 |
.IX Item "PERL_MAGIC_uvar_elem" |
| 13607 |
.ie n .IP """PERL_MAGIC_vec""" 4 |
| 13608 |
.el .IP \f(CWPERL_MAGIC_vec\fR 4 |
| 13609 |
.IX Item "PERL_MAGIC_vec" |
| 13610 |
.ie n .IP """PERL_MAGIC_vstring""" 4 |
| 13611 |
.el .IP \f(CWPERL_MAGIC_vstring\fR 4 |
| 13612 |
.IX Item "PERL_MAGIC_vstring" |
| 13613 |
.PD |
| 13614 |
Described in perlguts. |
| 13615 |
.ie n .IP """SvTIED_obj""" 4 |
| 13616 |
.el .IP \f(CWSvTIED_obj\fR 4 |
| 13617 |
.IX Item "SvTIED_obj" |
| 13618 |
Described in perlinterp. |
| 13619 |
.RS 4 |
| 13620 |
.Sp |
| 13621 |
.Vb 1 |
| 13622 |
\& SvTIED_obj(SV *sv, MAGIC *mg) |
| 13623 |
.Ve |
| 13624 |
.RE |
| 13625 |
.RS 4 |
| 13626 |
.RE |
| 13627 |
.SH "Memory Management" |
| 13628 |
.IX Header "Memory Management" |
| 13629 |
.ie n .IP """dump_mstats""" 4 |
| 13630 |
.el .IP \f(CWdump_mstats\fR 4 |
| 13631 |
.IX Xref "dump_mstats" |
| 13632 |
.IX Item "dump_mstats" |
| 13633 |
When enabled by compiling with \f(CW\*(C`\-DDEBUGGING_MSTATS\*(C'\fR, print out statistics |
| 13634 |
about malloc as two lines of numbers, one showing the length of the free list |
| 13635 |
for each size category, the second showing the number of mallocs\ \-\ frees for |
| 13636 |
each size category. |
| 13637 |
.Sp |
| 13638 |
\&\f(CW\*(C`s\*(C'\fR, if not NULL, is used as a phrase to include in the output, such as |
| 13639 |
"after\ compilation". |
| 13640 |
.RS 4 |
| 13641 |
.Sp |
| 13642 |
.Vb 1 |
| 13643 |
\& void dump_mstats(const char *s) |
| 13644 |
.Ve |
| 13645 |
.RE |
| 13646 |
.RS 4 |
| 13647 |
.RE |
| 13648 |
.ie n .IP """HASATTRIBUTE_MALLOC""" 4 |
| 13649 |
.el .IP \f(CWHASATTRIBUTE_MALLOC\fR 4 |
| 13650 |
.IX Xref "HASATTRIBUTE_MALLOC" |
| 13651 |
.IX Item "HASATTRIBUTE_MALLOC" |
| 13652 |
Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for malloc-style functions. |
| 13653 |
.ie n .IP """HAS_MALLOC_GOOD_SIZE""" 4 |
| 13654 |
.el .IP \f(CWHAS_MALLOC_GOOD_SIZE\fR 4 |
| 13655 |
.IX Xref "HAS_MALLOC_GOOD_SIZE" |
| 13656 |
.IX Item "HAS_MALLOC_GOOD_SIZE" |
| 13657 |
This symbol, if defined, indicates that the \f(CW\*(C`malloc_good_size\*(C'\fR |
| 13658 |
routine is available for use. |
| 13659 |
.ie n .IP """HAS_MALLOC_SIZE""" 4 |
| 13660 |
.el .IP \f(CWHAS_MALLOC_SIZE\fR 4 |
| 13661 |
.IX Xref "HAS_MALLOC_SIZE" |
| 13662 |
.IX Item "HAS_MALLOC_SIZE" |
| 13663 |
This symbol, if defined, indicates that the \f(CW\*(C`malloc_size\*(C'\fR |
| 13664 |
routine is available for use. |
| 13665 |
.ie n .IP """I_MALLOCMALLOC""" 4 |
| 13666 |
.el .IP \f(CWI_MALLOCMALLOC\fR 4 |
| 13667 |
.IX Xref "I_MALLOCMALLOC" |
| 13668 |
.IX Item "I_MALLOCMALLOC" |
| 13669 |
This symbol, if defined, indicates to the C program that it should |
| 13670 |
include \fImalloc/malloc.h\fR. |
| 13671 |
.RS 4 |
| 13672 |
.Sp |
| 13673 |
.Vb 3 |
| 13674 |
\& #ifdef I_MALLOCMALLOC |
| 13675 |
\& #include <mallocmalloc.h> |
| 13676 |
\& #endif |
| 13677 |
.Ve |
| 13678 |
.RE |
| 13679 |
.RS 4 |
| 13680 |
.RE |
| 13681 |
.ie n .IP """MYMALLOC""" 4 |
| 13682 |
.el .IP \f(CWMYMALLOC\fR 4 |
| 13683 |
.IX Xref "MYMALLOC" |
| 13684 |
.IX Item "MYMALLOC" |
| 13685 |
This symbol, if defined, indicates that we're using our own malloc. |
| 13686 |
.ie n .IP """Newx""" 4 |
| 13687 |
.el .IP \f(CWNewx\fR 4 |
| 13688 |
.IX Item "Newx" |
| 13689 |
.PD 0 |
| 13690 |
.ie n .IP """safemalloc""" 4 |
| 13691 |
.el .IP \f(CWsafemalloc\fR 4 |
| 13692 |
.IX Xref "Newx safemalloc" |
| 13693 |
.IX Item "safemalloc" |
| 13694 |
.PD |
| 13695 |
The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function. |
| 13696 |
.Sp |
| 13697 |
Memory obtained by this should \fBONLY\fR be freed with "Safefree". |
| 13698 |
.Sp |
| 13699 |
In 5.9.3, \fBNewx()\fR and friends replace the older \fBNew()\fR API, and drops |
| 13700 |
the first parameter, \fIx\fR, a debug aid which allowed callers to identify |
| 13701 |
themselves. This aid has been superseded by a new build option, |
| 13702 |
PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The older API is still |
| 13703 |
there for use in XS modules supporting older perls. |
| 13704 |
.RS 4 |
| 13705 |
.Sp |
| 13706 |
.Vb 2 |
| 13707 |
\& void Newx (void* ptr, int nitems, type) |
| 13708 |
\& void* safemalloc(size_t size) |
| 13709 |
.Ve |
| 13710 |
.RE |
| 13711 |
.RS 4 |
| 13712 |
.RE |
| 13713 |
.ie n .IP """Newxc""" 4 |
| 13714 |
.el .IP \f(CWNewxc\fR 4 |
| 13715 |
.IX Xref "Newxc" |
| 13716 |
.IX Item "Newxc" |
| 13717 |
The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with |
| 13718 |
cast. See also \f(CW"Newx"\fR. |
| 13719 |
.Sp |
| 13720 |
Memory obtained by this should \fBONLY\fR be freed with "Safefree". |
| 13721 |
.RS 4 |
| 13722 |
.Sp |
| 13723 |
.Vb 1 |
| 13724 |
\& void Newxc(void* ptr, int nitems, type, cast) |
| 13725 |
.Ve |
| 13726 |
.RE |
| 13727 |
.RS 4 |
| 13728 |
.RE |
| 13729 |
.ie n .IP """Newxz""" 4 |
| 13730 |
.el .IP \f(CWNewxz\fR 4 |
| 13731 |
.IX Item "Newxz" |
| 13732 |
.PD 0 |
| 13733 |
.ie n .IP """safecalloc""" 4 |
| 13734 |
.el .IP \f(CWsafecalloc\fR 4 |
| 13735 |
.IX Xref "Newxz safecalloc" |
| 13736 |
.IX Item "safecalloc" |
| 13737 |
.PD |
| 13738 |
The XSUB-writer's interface to the C \f(CW\*(C`calloc\*(C'\fR function. The allocated |
| 13739 |
memory is zeroed with \f(CW\*(C`memzero\*(C'\fR. See also \f(CW"Newx"\fR. |
| 13740 |
.Sp |
| 13741 |
Memory obtained by this should \fBONLY\fR be freed with "Safefree". |
| 13742 |
.RS 4 |
| 13743 |
.Sp |
| 13744 |
.Vb 2 |
| 13745 |
\& void Newxz (void* ptr, int nitems, type) |
| 13746 |
\& void* safecalloc(size_t nitems, size_t item_size) |
| 13747 |
.Ve |
| 13748 |
.RE |
| 13749 |
.RS 4 |
| 13750 |
.RE |
| 13751 |
.ie n .IP """PERL_MALLOC_WRAP""" 4 |
| 13752 |
.el .IP \f(CWPERL_MALLOC_WRAP\fR 4 |
| 13753 |
.IX Xref "PERL_MALLOC_WRAP" |
| 13754 |
.IX Item "PERL_MALLOC_WRAP" |
| 13755 |
This symbol, if defined, indicates that we'd like malloc wrap checks. |
| 13756 |
.ie n .IP """Renew""" 4 |
| 13757 |
.el .IP \f(CWRenew\fR 4 |
| 13758 |
.IX Item "Renew" |
| 13759 |
.PD 0 |
| 13760 |
.ie n .IP """saferealloc""" 4 |
| 13761 |
.el .IP \f(CWsaferealloc\fR 4 |
| 13762 |
.IX Xref "Renew saferealloc" |
| 13763 |
.IX Item "saferealloc" |
| 13764 |
.PD |
| 13765 |
The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function. |
| 13766 |
.Sp |
| 13767 |
Memory obtained by this should \fBONLY\fR be freed with "Safefree". |
| 13768 |
.RS 4 |
| 13769 |
.Sp |
| 13770 |
.Vb 2 |
| 13771 |
\& void Renew (void* ptr, int nitems, type) |
| 13772 |
\& void* saferealloc(void *ptr, size_t size) |
| 13773 |
.Ve |
| 13774 |
.RE |
| 13775 |
.RS 4 |
| 13776 |
.RE |
| 13777 |
.ie n .IP """Renewc""" 4 |
| 13778 |
.el .IP \f(CWRenewc\fR 4 |
| 13779 |
.IX Xref "Renewc" |
| 13780 |
.IX Item "Renewc" |
| 13781 |
The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with |
| 13782 |
cast. |
| 13783 |
.Sp |
| 13784 |
Memory obtained by this should \fBONLY\fR be freed with "Safefree". |
| 13785 |
.RS 4 |
| 13786 |
.Sp |
| 13787 |
.Vb 1 |
| 13788 |
\& void Renewc(void* ptr, int nitems, type, cast) |
| 13789 |
.Ve |
| 13790 |
.RE |
| 13791 |
.RS 4 |
| 13792 |
.RE |
| 13793 |
.ie n .IP """Safefree""" 4 |
| 13794 |
.el .IP \f(CWSafefree\fR 4 |
| 13795 |
.IX Xref "Safefree" |
| 13796 |
.IX Item "Safefree" |
| 13797 |
The XSUB-writer's interface to the C \f(CW\*(C`free\*(C'\fR function. |
| 13798 |
.Sp |
| 13799 |
This should \fBONLY\fR be used on memory obtained using "Newx" and friends. |
| 13800 |
.RS 4 |
| 13801 |
.Sp |
| 13802 |
.Vb 1 |
| 13803 |
\& void Safefree(void* ptr) |
| 13804 |
.Ve |
| 13805 |
.RE |
| 13806 |
.RS 4 |
| 13807 |
.RE |
| 13808 |
.ie n .IP """safesyscalloc""" 4 |
| 13809 |
.el .IP \f(CWsafesyscalloc\fR 4 |
| 13810 |
.IX Xref "safesyscalloc" |
| 13811 |
.IX Item "safesyscalloc" |
| 13812 |
Safe version of system's \fBcalloc()\fR |
| 13813 |
.RS 4 |
| 13814 |
.Sp |
| 13815 |
.Vb 1 |
| 13816 |
\& Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size) |
| 13817 |
.Ve |
| 13818 |
.RE |
| 13819 |
.RS 4 |
| 13820 |
.RE |
| 13821 |
.ie n .IP """safesysfree""" 4 |
| 13822 |
.el .IP \f(CWsafesysfree\fR 4 |
| 13823 |
.IX Xref "safesysfree" |
| 13824 |
.IX Item "safesysfree" |
| 13825 |
Safe version of system's \fBfree()\fR |
| 13826 |
.RS 4 |
| 13827 |
.Sp |
| 13828 |
.Vb 1 |
| 13829 |
\& Free_t safesysfree(Malloc_t where) |
| 13830 |
.Ve |
| 13831 |
.RE |
| 13832 |
.RS 4 |
| 13833 |
.RE |
| 13834 |
.ie n .IP """safesysmalloc""" 4 |
| 13835 |
.el .IP \f(CWsafesysmalloc\fR 4 |
| 13836 |
.IX Xref "safesysmalloc" |
| 13837 |
.IX Item "safesysmalloc" |
| 13838 |
Paranoid version of system's \fBmalloc()\fR |
| 13839 |
.RS 4 |
| 13840 |
.Sp |
| 13841 |
.Vb 1 |
| 13842 |
\& Malloc_t safesysmalloc(MEM_SIZE nbytes) |
| 13843 |
.Ve |
| 13844 |
.RE |
| 13845 |
.RS 4 |
| 13846 |
.RE |
| 13847 |
.ie n .IP """safesysrealloc""" 4 |
| 13848 |
.el .IP \f(CWsafesysrealloc\fR 4 |
| 13849 |
.IX Xref "safesysrealloc" |
| 13850 |
.IX Item "safesysrealloc" |
| 13851 |
Paranoid version of system's \fBrealloc()\fR |
| 13852 |
.RS 4 |
| 13853 |
.Sp |
| 13854 |
.Vb 1 |
| 13855 |
\& Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes) |
| 13856 |
.Ve |
| 13857 |
.RE |
| 13858 |
.RS 4 |
| 13859 |
.RE |
| 13860 |
.SH MRO |
| 13861 |
.IX Header "MRO" |
| 13862 |
These functions are related to the method resolution order of perl classes |
| 13863 |
Also see perlmroapi. |
| 13864 |
.ie n .IP """HvMROMETA""" 4 |
| 13865 |
.el .IP \f(CWHvMROMETA\fR 4 |
| 13866 |
.IX Item "HvMROMETA" |
| 13867 |
Described in perlmroapi. |
| 13868 |
.RS 4 |
| 13869 |
.Sp |
| 13870 |
.Vb 1 |
| 13871 |
\& struct mro_meta * HvMROMETA(HV *hv) |
| 13872 |
.Ve |
| 13873 |
.RE |
| 13874 |
.RS 4 |
| 13875 |
.RE |
| 13876 |
.ie n .IP """mro_get_from_name""" 4 |
| 13877 |
.el .IP \f(CWmro_get_from_name\fR 4 |
| 13878 |
.IX Xref "mro_get_from_name" |
| 13879 |
.IX Item "mro_get_from_name" |
| 13880 |
Returns the previously registered mro with the given \f(CW\*(C`name\*(C'\fR, or NULL if not |
| 13881 |
registered. See "\f(CW\*(C`mro_register\*(C'\fR". |
| 13882 |
.Sp |
| 13883 |
NOTE: \f(CW\*(C`mro_get_from_name\*(C'\fR must be explicitly called as |
| 13884 |
\&\f(CW\*(C`Perl_mro_get_from_name\*(C'\fR |
| 13885 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 13886 |
.RS 4 |
| 13887 |
.Sp |
| 13888 |
.Vb 1 |
| 13889 |
\& const struct mro_alg * Perl_mro_get_from_name(pTHX_ SV *name) |
| 13890 |
.Ve |
| 13891 |
.RE |
| 13892 |
.RS 4 |
| 13893 |
.RE |
| 13894 |
.ie n .IP """mro_get_linear_isa""" 4 |
| 13895 |
.el .IP \f(CWmro_get_linear_isa\fR 4 |
| 13896 |
.IX Xref "mro_get_linear_isa" |
| 13897 |
.IX Item "mro_get_linear_isa" |
| 13898 |
Returns the mro linearisation for the given stash. By default, this |
| 13899 |
will be whatever \f(CW\*(C`mro_get_linear_isa_dfs\*(C'\fR returns unless some |
| 13900 |
other MRO is in effect for the stash. The return value is a |
| 13901 |
read-only AV* whose values are string SVs giving class names. |
| 13902 |
.Sp |
| 13903 |
You are responsible for \f(CWSvREFCNT_inc()\fR on the |
| 13904 |
return value if you plan to store it anywhere |
| 13905 |
semi-permanently (otherwise it might be deleted |
| 13906 |
out from under you the next time the cache is |
| 13907 |
invalidated). |
| 13908 |
.RS 4 |
| 13909 |
.Sp |
| 13910 |
.Vb 1 |
| 13911 |
\& AV * mro_get_linear_isa(HV *stash) |
| 13912 |
.Ve |
| 13913 |
.RE |
| 13914 |
.RS 4 |
| 13915 |
.RE |
| 13916 |
.ie n .IP """MRO_GET_PRIVATE_DATA""" 4 |
| 13917 |
.el .IP \f(CWMRO_GET_PRIVATE_DATA\fR 4 |
| 13918 |
.IX Item "MRO_GET_PRIVATE_DATA" |
| 13919 |
Described in perlmroapi. |
| 13920 |
.RS 4 |
| 13921 |
.Sp |
| 13922 |
.Vb 2 |
| 13923 |
\& SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta, |
| 13924 |
\& const struct mro_alg *const which) |
| 13925 |
.Ve |
| 13926 |
.RE |
| 13927 |
.RS 4 |
| 13928 |
.RE |
| 13929 |
.ie n .IP """mro_method_changed_in""" 4 |
| 13930 |
.el .IP \f(CWmro_method_changed_in\fR 4 |
| 13931 |
.IX Xref "mro_method_changed_in" |
| 13932 |
.IX Item "mro_method_changed_in" |
| 13933 |
Invalidates method caching on any child classes |
| 13934 |
of the given stash, so that they might notice |
| 13935 |
the changes in this one. |
| 13936 |
.Sp |
| 13937 |
Ideally, all instances of \f(CW\*(C`PL_sub_generation++\*(C'\fR in |
| 13938 |
perl source outside of \fImro.c\fR should be |
| 13939 |
replaced by calls to this. |
| 13940 |
.Sp |
| 13941 |
Perl automatically handles most of the common |
| 13942 |
ways a method might be redefined. However, there |
| 13943 |
are a few ways you could change a method in a stash |
| 13944 |
without the cache code noticing, in which case you |
| 13945 |
need to call this method afterwards: |
| 13946 |
.Sp |
| 13947 |
1) Directly manipulating the stash HV entries from |
| 13948 |
XS code. |
| 13949 |
.Sp |
| 13950 |
2) Assigning a reference to a readonly scalar |
| 13951 |
constant into a stash entry in order to create |
| 13952 |
a constant subroutine (like \fIconstant.pm\fR |
| 13953 |
does). |
| 13954 |
.Sp |
| 13955 |
This same method is available from pure perl |
| 13956 |
via, \f(CWmro::method_changed_in(classname)\fR. |
| 13957 |
.RS 4 |
| 13958 |
.Sp |
| 13959 |
.Vb 1 |
| 13960 |
\& void mro_method_changed_in(HV *stash) |
| 13961 |
.Ve |
| 13962 |
.RE |
| 13963 |
.RS 4 |
| 13964 |
.RE |
| 13965 |
.ie n .IP """mro_register""" 4 |
| 13966 |
.el .IP \f(CWmro_register\fR 4 |
| 13967 |
.IX Xref "mro_register" |
| 13968 |
.IX Item "mro_register" |
| 13969 |
Registers a custom mro plugin. See perlmroapi for details on this and other |
| 13970 |
mro functions. |
| 13971 |
.Sp |
| 13972 |
NOTE: \f(CW\*(C`mro_register\*(C'\fR must be explicitly called as |
| 13973 |
\&\f(CW\*(C`Perl_mro_register\*(C'\fR |
| 13974 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 13975 |
.RS 4 |
| 13976 |
.Sp |
| 13977 |
.Vb 1 |
| 13978 |
\& void Perl_mro_register(pTHX_ const struct mro_alg *mro) |
| 13979 |
.Ve |
| 13980 |
.RE |
| 13981 |
.RS 4 |
| 13982 |
.RE |
| 13983 |
.ie n .IP """mro_set_mro""" 4 |
| 13984 |
.el .IP \f(CWmro_set_mro\fR 4 |
| 13985 |
.IX Xref "mro_set_mro" |
| 13986 |
.IX Item "mro_set_mro" |
| 13987 |
Set \f(CW\*(C`meta\*(C'\fR to the value contained in the registered mro plugin whose name is |
| 13988 |
\&\f(CW\*(C`name\*(C'\fR. |
| 13989 |
.Sp |
| 13990 |
Croaks if \f(CW\*(C`name\*(C'\fR hasn't been registered |
| 13991 |
.Sp |
| 13992 |
NOTE: \f(CW\*(C`mro_set_mro\*(C'\fR must be explicitly called as |
| 13993 |
\&\f(CW\*(C`Perl_mro_set_mro\*(C'\fR |
| 13994 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 13995 |
.RS 4 |
| 13996 |
.Sp |
| 13997 |
.Vb 2 |
| 13998 |
\& void Perl_mro_set_mro(pTHX_ struct mro_meta * const meta, |
| 13999 |
\& SV * const name) |
| 14000 |
.Ve |
| 14001 |
.RE |
| 14002 |
.RS 4 |
| 14003 |
.RE |
| 14004 |
.ie n .IP """mro_set_private_data""" 4 |
| 14005 |
.el .IP \f(CWmro_set_private_data\fR 4 |
| 14006 |
.IX Item "mro_set_private_data" |
| 14007 |
Described in perlmroapi. |
| 14008 |
.Sp |
| 14009 |
NOTE: \f(CW\*(C`mro_set_private_data\*(C'\fR must be explicitly called as |
| 14010 |
\&\f(CW\*(C`Perl_mro_set_private_data\*(C'\fR |
| 14011 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 14012 |
.RS 4 |
| 14013 |
.Sp |
| 14014 |
.Vb 4 |
| 14015 |
\& SV * Perl_mro_set_private_data(pTHX_ |
| 14016 |
\& struct mro_meta * const smeta, |
| 14017 |
\& const struct mro_alg * const which, |
| 14018 |
\& SV * const data) |
| 14019 |
.Ve |
| 14020 |
.RE |
| 14021 |
.RS 4 |
| 14022 |
.RE |
| 14023 |
.SH "Multicall Functions" |
| 14024 |
.IX Header "Multicall Functions" |
| 14025 |
.ie n .IP """dMULTICALL""" 4 |
| 14026 |
.el .IP \f(CWdMULTICALL\fR 4 |
| 14027 |
.IX Xref "dMULTICALL" |
| 14028 |
.IX Item "dMULTICALL" |
| 14029 |
Declare local variables for a multicall. See "LIGHTWEIGHT CALLBACKS" in perlcall. |
| 14030 |
.RS 4 |
| 14031 |
.Sp |
| 14032 |
.Vb 1 |
| 14033 |
\& dMULTICALL; |
| 14034 |
.Ve |
| 14035 |
.RE |
| 14036 |
.RS 4 |
| 14037 |
.RE |
| 14038 |
.ie n .IP """MULTICALL""" 4 |
| 14039 |
.el .IP \f(CWMULTICALL\fR 4 |
| 14040 |
.IX Xref "MULTICALL" |
| 14041 |
.IX Item "MULTICALL" |
| 14042 |
Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in perlcall. |
| 14043 |
.RS 4 |
| 14044 |
.Sp |
| 14045 |
.Vb 1 |
| 14046 |
\& MULTICALL; |
| 14047 |
.Ve |
| 14048 |
.RE |
| 14049 |
.RS 4 |
| 14050 |
.RE |
| 14051 |
.ie n .IP """POP_MULTICALL""" 4 |
| 14052 |
.el .IP \f(CWPOP_MULTICALL\fR 4 |
| 14053 |
.IX Xref "POP_MULTICALL" |
| 14054 |
.IX Item "POP_MULTICALL" |
| 14055 |
Closing bracket for a lightweight callback. |
| 14056 |
See "LIGHTWEIGHT CALLBACKS" in perlcall. |
| 14057 |
.RS 4 |
| 14058 |
.Sp |
| 14059 |
.Vb 1 |
| 14060 |
\& POP_MULTICALL; |
| 14061 |
.Ve |
| 14062 |
.RE |
| 14063 |
.RS 4 |
| 14064 |
.RE |
| 14065 |
.ie n .IP """PUSH_MULTICALL""" 4 |
| 14066 |
.el .IP \f(CWPUSH_MULTICALL\fR 4 |
| 14067 |
.IX Xref "PUSH_MULTICALL" |
| 14068 |
.IX Item "PUSH_MULTICALL" |
| 14069 |
Opening bracket for a lightweight callback. |
| 14070 |
See "LIGHTWEIGHT CALLBACKS" in perlcall. |
| 14071 |
.RS 4 |
| 14072 |
.Sp |
| 14073 |
.Vb 1 |
| 14074 |
\& PUSH_MULTICALL(CV* the_cv); |
| 14075 |
.Ve |
| 14076 |
.RE |
| 14077 |
.RS 4 |
| 14078 |
.RE |
| 14079 |
.SH "Numeric Functions" |
| 14080 |
.IX Xref "IS_NUMBER_GREATER_THAN_UV_MAX IS_NUMBER_INFINITY IS_NUMBER_IN_UV IS_NUMBER_NAN IS_NUMBER_NEG IS_NUMBER_NOT_INT PERL_SCAN_ALLOW_UNDERSCORES PERL_SCAN_DISALLOW_PREFIX PERL_SCAN_GREATER_THAN_UV_MAX PERL_SCAN_SILENT_ILLDIGIT PERL_SCAN_TRAILING" |
| 14081 |
.IX Header "Numeric Functions" |
| 14082 |
.ie n .IP """Atol""" 4 |
| 14083 |
.el .IP \f(CWAtol\fR 4 |
| 14084 |
.IX Item "Atol" |
| 14085 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Atol\*(C'\fR |
| 14086 |
from a future release of Perl. Do not use it for |
| 14087 |
new code; remove it from existing code. |
| 14088 |
.Sp |
| 14089 |
Described in perlhacktips. |
| 14090 |
.RS 4 |
| 14091 |
.Sp |
| 14092 |
.Vb 1 |
| 14093 |
\& Atol(const char * nptr) |
| 14094 |
.Ve |
| 14095 |
.RE |
| 14096 |
.RS 4 |
| 14097 |
.RE |
| 14098 |
.ie n .IP """Atoul""" 4 |
| 14099 |
.el .IP \f(CWAtoul\fR 4 |
| 14100 |
.IX Item "Atoul" |
| 14101 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Atoul\*(C'\fR |
| 14102 |
from a future release of Perl. Do not use it for |
| 14103 |
new code; remove it from existing code. |
| 14104 |
.Sp |
| 14105 |
Described in perlhacktips. |
| 14106 |
.RS 4 |
| 14107 |
.Sp |
| 14108 |
.Vb 1 |
| 14109 |
\& Atoul(const char * nptr) |
| 14110 |
.Ve |
| 14111 |
.RE |
| 14112 |
.RS 4 |
| 14113 |
.RE |
| 14114 |
.ie n .IP """Drand01""" 4 |
| 14115 |
.el .IP \f(CWDrand01\fR 4 |
| 14116 |
.IX Xref "Drand01" |
| 14117 |
.IX Item "Drand01" |
| 14118 |
This macro is to be used to generate uniformly distributed |
| 14119 |
random numbers over the range [0., 1.[. You may have to supply |
| 14120 |
an 'extern double \f(CWdrand48()\fR;' in your program since SunOS 4.1.3 |
| 14121 |
doesn't provide you with anything relevant in its headers. |
| 14122 |
See \f(CW"HAS_DRAND48_PROTO"\fR. |
| 14123 |
.RS 4 |
| 14124 |
.Sp |
| 14125 |
.Vb 1 |
| 14126 |
\& double Drand01() |
| 14127 |
.Ve |
| 14128 |
.RE |
| 14129 |
.RS 4 |
| 14130 |
.RE |
| 14131 |
.ie n .IP """Gconvert""" 4 |
| 14132 |
.el .IP \f(CWGconvert\fR 4 |
| 14133 |
.IX Xref "Gconvert" |
| 14134 |
.IX Item "Gconvert" |
| 14135 |
This preprocessor macro is defined to convert a floating point |
| 14136 |
number to a string without a trailing decimal point. This |
| 14137 |
emulates the behavior of \f(CWsprintf("%g")\fR, but is sometimes much more |
| 14138 |
efficient. If \f(CWgconvert()\fR is not available, but \f(CWgcvt()\fR drops the |
| 14139 |
trailing decimal point, then \f(CWgcvt()\fR is used. If all else fails, |
| 14140 |
a macro using \f(CWsprintf("%g")\fR is used. Arguments for the Gconvert |
| 14141 |
macro are: value, number of digits, whether trailing zeros should |
| 14142 |
be retained, and the output buffer. |
| 14143 |
The usual values are: |
| 14144 |
.Sp |
| 14145 |
.Vb 3 |
| 14146 |
\& d_Gconvert=\*(Aqgconvert((x),(n),(t),(b))\*(Aq |
| 14147 |
\& d_Gconvert=\*(Aqgcvt((x),(n),(b))\*(Aq |
| 14148 |
\& d_Gconvert=\*(Aqsprintf((b),"%.*g",(n),(x))\*(Aq |
| 14149 |
.Ve |
| 14150 |
.Sp |
| 14151 |
The last two assume trailing zeros should not be kept. |
| 14152 |
.RS 4 |
| 14153 |
.Sp |
| 14154 |
.Vb 1 |
| 14155 |
\& char * Gconvert(double x, Size_t n, bool t, char * b) |
| 14156 |
.Ve |
| 14157 |
.RE |
| 14158 |
.RS 4 |
| 14159 |
.RE |
| 14160 |
.ie n .IP """grok_atoUV""" 4 |
| 14161 |
.el .IP \f(CWgrok_atoUV\fR 4 |
| 14162 |
.IX Xref "grok_atoUV" |
| 14163 |
.IX Item "grok_atoUV" |
| 14164 |
parse a string, looking for a decimal unsigned integer. |
| 14165 |
.Sp |
| 14166 |
On entry, \f(CW\*(C`pv\*(C'\fR points to the beginning of the string; |
| 14167 |
\&\f(CW\*(C`valptr\*(C'\fR points to a UV that will receive the converted value, if found; |
| 14168 |
\&\f(CW\*(C`endptr\*(C'\fR is either NULL or points to a variable that points to one byte |
| 14169 |
beyond the point in \f(CW\*(C`pv\*(C'\fR that this routine should examine. |
| 14170 |
If \f(CW\*(C`endptr\*(C'\fR is NULL, \f(CW\*(C`pv\*(C'\fR is assumed to be NUL-terminated. |
| 14171 |
.Sp |
| 14172 |
Returns FALSE if \f(CW\*(C`pv\*(C'\fR doesn't represent a valid unsigned integer value (with |
| 14173 |
no leading zeros). Otherwise it returns TRUE, and sets \f(CW*valptr\fR to that |
| 14174 |
value. |
| 14175 |
.Sp |
| 14176 |
If you constrain the portion of \f(CW\*(C`pv\*(C'\fR that is looked at by this function (by |
| 14177 |
passing a non-NULL \f(CW\*(C`endptr\*(C'\fR), and if the initial bytes of that portion form a |
| 14178 |
valid value, it will return TRUE, setting \f(CW*endptr\fR to the byte following the |
| 14179 |
final digit of the value. But if there is no constraint at what's looked at, |
| 14180 |
all of \f(CW\*(C`pv\*(C'\fR must be valid in order for TRUE to be returned. \f(CW*endptr\fR is |
| 14181 |
unchanged from its value on input if FALSE is returned; |
| 14182 |
.Sp |
| 14183 |
The only characters this accepts are the decimal digits '0'..'9'. |
| 14184 |
.Sp |
| 14185 |
As opposed to \fBatoi\fR\|(3) or \fBstrtol\fR\|(3), \f(CW\*(C`grok_atoUV\*(C'\fR does NOT allow optional |
| 14186 |
leading whitespace, nor negative inputs. If such features are required, the |
| 14187 |
calling code needs to explicitly implement those. |
| 14188 |
.Sp |
| 14189 |
Note that this function returns FALSE for inputs that would overflow a UV, |
| 14190 |
or have leading zeros. Thus a single \f(CW0\fR is accepted, but not \f(CW00\fR nor |
| 14191 |
\&\f(CW01\fR, \f(CW002\fR, \fIetc\fR. |
| 14192 |
.Sp |
| 14193 |
Background: \f(CW\*(C`atoi\*(C'\fR has severe problems with illegal inputs, it cannot be |
| 14194 |
used for incremental parsing, and therefore should be avoided |
| 14195 |
\&\f(CW\*(C`atoi\*(C'\fR and \f(CW\*(C`strtol\*(C'\fR are also affected by locale settings, which can also be |
| 14196 |
seen as a bug (global state controlled by user environment). |
| 14197 |
.RS 4 |
| 14198 |
.Sp |
| 14199 |
.Vb 1 |
| 14200 |
\& bool grok_atoUV(const char *pv, UV *valptr, const char **endptr) |
| 14201 |
.Ve |
| 14202 |
.RE |
| 14203 |
.RS 4 |
| 14204 |
.RE |
| 14205 |
.ie n .IP """grok_bin""" 4 |
| 14206 |
.el .IP \f(CWgrok_bin\fR 4 |
| 14207 |
.IX Xref "grok_bin" |
| 14208 |
.IX Item "grok_bin" |
| 14209 |
converts a string representing a binary number to numeric form. |
| 14210 |
.Sp |
| 14211 |
On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives |
| 14212 |
conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The |
| 14213 |
scan stops at the end of the string, or at just before the first invalid |
| 14214 |
character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR, |
| 14215 |
encountering an invalid character (except NUL) will also trigger a warning. On |
| 14216 |
return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR |
| 14217 |
gives output flags. |
| 14218 |
.Sp |
| 14219 |
If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear, |
| 14220 |
and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_bin\*(C'\fR |
| 14221 |
returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, |
| 14222 |
and writes an approximation of the correct value into \f(CW*result\fR (which is an |
| 14223 |
NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL). |
| 14224 |
.Sp |
| 14225 |
The binary number may optionally be prefixed with \f(CW"0b"\fR or \f(CW"b"\fR unless |
| 14226 |
\&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry. |
| 14227 |
.Sp |
| 14228 |
If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of |
| 14229 |
digits may be separated from each other by a single underscore; also a single |
| 14230 |
leading underscore is accepted. |
| 14231 |
.RS 4 |
| 14232 |
.Sp |
| 14233 |
.Vb 2 |
| 14234 |
\& UV grok_bin(const char *start, STRLEN *len_p, I32 *flags, |
| 14235 |
\& NV *result) |
| 14236 |
.Ve |
| 14237 |
.RE |
| 14238 |
.RS 4 |
| 14239 |
.RE |
| 14240 |
.ie n .IP """grok_hex""" 4 |
| 14241 |
.el .IP \f(CWgrok_hex\fR 4 |
| 14242 |
.IX Xref "grok_hex" |
| 14243 |
.IX Item "grok_hex" |
| 14244 |
converts a string representing a hex number to numeric form. |
| 14245 |
.Sp |
| 14246 |
On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives |
| 14247 |
conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The |
| 14248 |
scan stops at the end of the string, or at just before the first invalid |
| 14249 |
character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR, |
| 14250 |
encountering an invalid character (except NUL) will also trigger a warning. On |
| 14251 |
return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR |
| 14252 |
gives output flags. |
| 14253 |
.Sp |
| 14254 |
If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear, |
| 14255 |
and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR |
| 14256 |
returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, |
| 14257 |
and writes an approximation of the correct value into \f(CW*result\fR (which is an |
| 14258 |
NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL). |
| 14259 |
.Sp |
| 14260 |
The hex number may optionally be prefixed with \f(CW"0x"\fR or \f(CW"x"\fR unless |
| 14261 |
\&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry. |
| 14262 |
.Sp |
| 14263 |
If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of |
| 14264 |
digits may be separated from each other by a single underscore; also a single |
| 14265 |
leading underscore is accepted. |
| 14266 |
.RS 4 |
| 14267 |
.Sp |
| 14268 |
.Vb 2 |
| 14269 |
\& UV grok_hex(const char *start, STRLEN *len_p, I32 *flags, |
| 14270 |
\& NV *result) |
| 14271 |
.Ve |
| 14272 |
.RE |
| 14273 |
.RS 4 |
| 14274 |
.RE |
| 14275 |
.ie n .IP """grok_infnan""" 4 |
| 14276 |
.el .IP \f(CWgrok_infnan\fR 4 |
| 14277 |
.IX Xref "grok_infnan" |
| 14278 |
.IX Item "grok_infnan" |
| 14279 |
Helper for \f(CWgrok_number()\fR, accepts various ways of spelling "infinity" |
| 14280 |
or "not a number", and returns one of the following flag combinations: |
| 14281 |
.Sp |
| 14282 |
.Vb 5 |
| 14283 |
\& IS_NUMBER_INFINITY |
| 14284 |
\& IS_NUMBER_NAN |
| 14285 |
\& IS_NUMBER_INFINITY | IS_NUMBER_NEG |
| 14286 |
\& IS_NUMBER_NAN | IS_NUMBER_NEG |
| 14287 |
\& 0 |
| 14288 |
.Ve |
| 14289 |
.Sp |
| 14290 |
possibly |\-ed with \f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR. |
| 14291 |
.Sp |
| 14292 |
If an infinity or a not-a-number is recognized, \f(CW*sp\fR will point to |
| 14293 |
one byte past the end of the recognized string. If the recognition fails, |
| 14294 |
zero is returned, and \f(CW*sp\fR will not move. |
| 14295 |
.RS 4 |
| 14296 |
.Sp |
| 14297 |
.Vb 1 |
| 14298 |
\& int grok_infnan(const char **sp, const char *send) |
| 14299 |
.Ve |
| 14300 |
.RE |
| 14301 |
.RS 4 |
| 14302 |
.RE |
| 14303 |
.ie n .IP """grok_number""" 4 |
| 14304 |
.el .IP \f(CWgrok_number\fR 4 |
| 14305 |
.IX Xref "grok_number" |
| 14306 |
.IX Item "grok_number" |
| 14307 |
Identical to \f(CWgrok_number_flags()\fR with \f(CW\*(C`flags\*(C'\fR set to zero. |
| 14308 |
.RS 4 |
| 14309 |
.Sp |
| 14310 |
.Vb 1 |
| 14311 |
\& int grok_number(const char *pv, STRLEN len, UV *valuep) |
| 14312 |
.Ve |
| 14313 |
.RE |
| 14314 |
.RS 4 |
| 14315 |
.RE |
| 14316 |
.ie n .IP """grok_number_flags""" 4 |
| 14317 |
.el .IP \f(CWgrok_number_flags\fR 4 |
| 14318 |
.IX Xref "grok_number_flags" |
| 14319 |
.IX Item "grok_number_flags" |
| 14320 |
Recognise (or not) a number. The type of the number is returned |
| 14321 |
(0 if unrecognised), otherwise it is a bit-ORed combination of |
| 14322 |
\&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR, \f(CW\*(C`IS_NUMBER_GREATER_THAN_UV_MAX\*(C'\fR, \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR, |
| 14323 |
\&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR, \f(CW\*(C`IS_NUMBER_INFINITY\*(C'\fR, \f(CW\*(C`IS_NUMBER_NAN\*(C'\fR (defined in perl.h). |
| 14324 |
.Sp |
| 14325 |
If the value of the number can fit in a UV, it is returned in \f(CW*valuep\fR. |
| 14326 |
\&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set to indicate that \f(CW*valuep\fR is valid, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR |
| 14327 |
will never be set unless \f(CW*valuep\fR is valid, but \f(CW*valuep\fR may have been assigned |
| 14328 |
to during processing even though \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set on return. |
| 14329 |
If \f(CW\*(C`valuep\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set for the same cases as when |
| 14330 |
\&\f(CW\*(C`valuep\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR, but no actual assignment (or SEGV) will occur. |
| 14331 |
.Sp |
| 14332 |
\&\f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR will be set with \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR if trailing decimals were |
| 14333 |
seen (in which case \f(CW*valuep\fR gives the true value truncated to an integer), and |
| 14334 |
\&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR if the number is negative (in which case \f(CW*valuep\fR holds the |
| 14335 |
absolute value). \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set if \f(CW\*(C`e\*(C'\fR notation was used or the |
| 14336 |
number is larger than a UV. |
| 14337 |
.Sp |
| 14338 |
\&\f(CW\*(C`flags\*(C'\fR allows only \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR, which allows for trailing |
| 14339 |
non-numeric text on an otherwise successful \fIgrok\fR, setting |
| 14340 |
\&\f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR on the result. |
| 14341 |
.RS 4 |
| 14342 |
.Sp |
| 14343 |
.Vb 2 |
| 14344 |
\& int grok_number_flags(const char *pv, STRLEN len, UV *valuep, |
| 14345 |
\& U32 flags) |
| 14346 |
.Ve |
| 14347 |
.RE |
| 14348 |
.RS 4 |
| 14349 |
.RE |
| 14350 |
.ie n .IP """GROK_NUMERIC_RADIX""" 4 |
| 14351 |
.el .IP \f(CWGROK_NUMERIC_RADIX\fR 4 |
| 14352 |
.IX Xref "GROK_NUMERIC_RADIX" |
| 14353 |
.IX Item "GROK_NUMERIC_RADIX" |
| 14354 |
A synonym for "grok_numeric_radix" |
| 14355 |
.RS 4 |
| 14356 |
.Sp |
| 14357 |
.Vb 1 |
| 14358 |
\& bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send) |
| 14359 |
.Ve |
| 14360 |
.RE |
| 14361 |
.RS 4 |
| 14362 |
.RE |
| 14363 |
.ie n .IP """grok_numeric_radix""" 4 |
| 14364 |
.el .IP \f(CWgrok_numeric_radix\fR 4 |
| 14365 |
.IX Xref "grok_numeric_radix" |
| 14366 |
.IX Item "grok_numeric_radix" |
| 14367 |
Scan and skip for a numeric decimal separator (radix). |
| 14368 |
.RS 4 |
| 14369 |
.Sp |
| 14370 |
.Vb 1 |
| 14371 |
\& bool grok_numeric_radix(const char **sp, const char *send) |
| 14372 |
.Ve |
| 14373 |
.RE |
| 14374 |
.RS 4 |
| 14375 |
.RE |
| 14376 |
.ie n .IP """grok_oct""" 4 |
| 14377 |
.el .IP \f(CWgrok_oct\fR 4 |
| 14378 |
.IX Xref "grok_oct" |
| 14379 |
.IX Item "grok_oct" |
| 14380 |
converts a string representing an octal number to numeric form. |
| 14381 |
.Sp |
| 14382 |
On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives |
| 14383 |
conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The |
| 14384 |
scan stops at the end of the string, or at just before the first invalid |
| 14385 |
character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR, |
| 14386 |
encountering an invalid character (except NUL) will also trigger a warning. On |
| 14387 |
return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR |
| 14388 |
gives output flags. |
| 14389 |
.Sp |
| 14390 |
If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear, |
| 14391 |
and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_oct\*(C'\fR |
| 14392 |
returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, |
| 14393 |
and writes an approximation of the correct value into \f(CW*result\fR (which is an |
| 14394 |
NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL). |
| 14395 |
.Sp |
| 14396 |
If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of |
| 14397 |
digits may be separated from each other by a single underscore; also a single |
| 14398 |
leading underscore is accepted. |
| 14399 |
.Sp |
| 14400 |
The \f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR flag is always treated as being set for |
| 14401 |
this function. |
| 14402 |
.RS 4 |
| 14403 |
.Sp |
| 14404 |
.Vb 2 |
| 14405 |
\& UV grok_oct(const char *start, STRLEN *len_p, I32 *flags, |
| 14406 |
\& NV *result) |
| 14407 |
.Ve |
| 14408 |
.RE |
| 14409 |
.RS 4 |
| 14410 |
.RE |
| 14411 |
.ie n .IP """isinfnan""" 4 |
| 14412 |
.el .IP \f(CWisinfnan\fR 4 |
| 14413 |
.IX Xref "isinfnan" |
| 14414 |
.IX Item "isinfnan" |
| 14415 |
\&\f(CWPerl_isinfnan()\fR is a utility function that returns true if the NV |
| 14416 |
argument is either an infinity or a \f(CW\*(C`NaN\*(C'\fR, false otherwise. To test |
| 14417 |
in more detail, use \f(CWPerl_isinf()\fR and \f(CWPerl_isnan()\fR. |
| 14418 |
.Sp |
| 14419 |
This is also the logical inverse of \fBPerl_isfinite()\fR. |
| 14420 |
.RS 4 |
| 14421 |
.Sp |
| 14422 |
.Vb 1 |
| 14423 |
\& bool isinfnan(NV nv) |
| 14424 |
.Ve |
| 14425 |
.RE |
| 14426 |
.RS 4 |
| 14427 |
.RE |
| 14428 |
.ie n .IP """my_atof""" 4 |
| 14429 |
.el .IP \f(CWmy_atof\fR 4 |
| 14430 |
.IX Xref "my_atof" |
| 14431 |
.IX Item "my_atof" |
| 14432 |
\&\f(CW\*(C`atof\*(C'\fR(3), but properly works with Perl locale handling, accepting a dot |
| 14433 |
radix character always, but also the current locale's radix character if and |
| 14434 |
only if called from within the lexical scope of a Perl \f(CW\*(C`use locale\*(C'\fR statement. |
| 14435 |
.Sp |
| 14436 |
N.B. \f(CW\*(C`s\*(C'\fR must be NUL terminated. |
| 14437 |
.RS 4 |
| 14438 |
.Sp |
| 14439 |
.Vb 1 |
| 14440 |
\& NV my_atof(const char *s) |
| 14441 |
.Ve |
| 14442 |
.RE |
| 14443 |
.RS 4 |
| 14444 |
.RE |
| 14445 |
.ie n .IP """my_strtod""" 4 |
| 14446 |
.el .IP \f(CWmy_strtod\fR 4 |
| 14447 |
.IX Xref "my_strtod" |
| 14448 |
.IX Item "my_strtod" |
| 14449 |
This function is equivalent to the libc \fBstrtod()\fR function, and is available |
| 14450 |
even on platforms that lack plain \fBstrtod()\fR. Its return value is the best |
| 14451 |
available precision depending on platform capabilities and \fIConfigure\fR |
| 14452 |
options. |
| 14453 |
.Sp |
| 14454 |
It properly handles the locale radix character, meaning it expects a dot except |
| 14455 |
when called from within the scope of \f(CW\*(C`use\ locale\*(C'\fR, in which case the radix |
| 14456 |
character should be that specified by the current locale. |
| 14457 |
.Sp |
| 14458 |
The synonym \fBStrtod()\fR may be used instead. |
| 14459 |
.RS 4 |
| 14460 |
.Sp |
| 14461 |
.Vb 1 |
| 14462 |
\& NV my_strtod(const char * const s, char **e) |
| 14463 |
.Ve |
| 14464 |
.RE |
| 14465 |
.RS 4 |
| 14466 |
.RE |
| 14467 |
.ie n .IP """PERL_ABS""" 4 |
| 14468 |
.el .IP \f(CWPERL_ABS\fR 4 |
| 14469 |
.IX Xref "PERL_ABS" |
| 14470 |
.IX Item "PERL_ABS" |
| 14471 |
Typeless \f(CW\*(C`abs\*(C'\fR or \f(CW\*(C`fabs\*(C'\fR, \fIetc\fR. (The usage below indicates it is for |
| 14472 |
integers, but it works for any type.) Use instead of these, since the C |
| 14473 |
library ones force their argument to be what it is expecting, potentially |
| 14474 |
leading to disaster. But also beware that this evaluates its argument twice, |
| 14475 |
so no \f(CW\*(C`x++\*(C'\fR. |
| 14476 |
.RS 4 |
| 14477 |
.Sp |
| 14478 |
.Vb 1 |
| 14479 |
\& int PERL_ABS(int x) |
| 14480 |
.Ve |
| 14481 |
.RE |
| 14482 |
.RS 4 |
| 14483 |
.RE |
| 14484 |
.ie n .IP """Perl_acos""" 4 |
| 14485 |
.el .IP \f(CWPerl_acos\fR 4 |
| 14486 |
.IX Item "Perl_acos" |
| 14487 |
.PD 0 |
| 14488 |
.ie n .IP """Perl_asin""" 4 |
| 14489 |
.el .IP \f(CWPerl_asin\fR 4 |
| 14490 |
.IX Item "Perl_asin" |
| 14491 |
.ie n .IP """Perl_atan""" 4 |
| 14492 |
.el .IP \f(CWPerl_atan\fR 4 |
| 14493 |
.IX Item "Perl_atan" |
| 14494 |
.ie n .IP """Perl_atan2""" 4 |
| 14495 |
.el .IP \f(CWPerl_atan2\fR 4 |
| 14496 |
.IX Item "Perl_atan2" |
| 14497 |
.ie n .IP """Perl_ceil""" 4 |
| 14498 |
.el .IP \f(CWPerl_ceil\fR 4 |
| 14499 |
.IX Item "Perl_ceil" |
| 14500 |
.ie n .IP """Perl_cos""" 4 |
| 14501 |
.el .IP \f(CWPerl_cos\fR 4 |
| 14502 |
.IX Item "Perl_cos" |
| 14503 |
.ie n .IP """Perl_cosh""" 4 |
| 14504 |
.el .IP \f(CWPerl_cosh\fR 4 |
| 14505 |
.IX Item "Perl_cosh" |
| 14506 |
.ie n .IP """Perl_exp""" 4 |
| 14507 |
.el .IP \f(CWPerl_exp\fR 4 |
| 14508 |
.IX Item "Perl_exp" |
| 14509 |
.ie n .IP """Perl_floor""" 4 |
| 14510 |
.el .IP \f(CWPerl_floor\fR 4 |
| 14511 |
.IX Item "Perl_floor" |
| 14512 |
.ie n .IP """Perl_fmod""" 4 |
| 14513 |
.el .IP \f(CWPerl_fmod\fR 4 |
| 14514 |
.IX Item "Perl_fmod" |
| 14515 |
.ie n .IP """Perl_frexp""" 4 |
| 14516 |
.el .IP \f(CWPerl_frexp\fR 4 |
| 14517 |
.IX Item "Perl_frexp" |
| 14518 |
.ie n .IP """Perl_isfinite""" 4 |
| 14519 |
.el .IP \f(CWPerl_isfinite\fR 4 |
| 14520 |
.IX Item "Perl_isfinite" |
| 14521 |
.ie n .IP """Perl_isinf""" 4 |
| 14522 |
.el .IP \f(CWPerl_isinf\fR 4 |
| 14523 |
.IX Item "Perl_isinf" |
| 14524 |
.ie n .IP """Perl_isnan""" 4 |
| 14525 |
.el .IP \f(CWPerl_isnan\fR 4 |
| 14526 |
.IX Item "Perl_isnan" |
| 14527 |
.ie n .IP """Perl_ldexp""" 4 |
| 14528 |
.el .IP \f(CWPerl_ldexp\fR 4 |
| 14529 |
.IX Item "Perl_ldexp" |
| 14530 |
.ie n .IP """Perl_log""" 4 |
| 14531 |
.el .IP \f(CWPerl_log\fR 4 |
| 14532 |
.IX Item "Perl_log" |
| 14533 |
.ie n .IP """Perl_log10""" 4 |
| 14534 |
.el .IP \f(CWPerl_log10\fR 4 |
| 14535 |
.IX Item "Perl_log10" |
| 14536 |
.ie n .IP """Perl_modf""" 4 |
| 14537 |
.el .IP \f(CWPerl_modf\fR 4 |
| 14538 |
.IX Item "Perl_modf" |
| 14539 |
.ie n .IP """Perl_pow""" 4 |
| 14540 |
.el .IP \f(CWPerl_pow\fR 4 |
| 14541 |
.IX Item "Perl_pow" |
| 14542 |
.ie n .IP """Perl_sin""" 4 |
| 14543 |
.el .IP \f(CWPerl_sin\fR 4 |
| 14544 |
.IX Item "Perl_sin" |
| 14545 |
.ie n .IP """Perl_sinh""" 4 |
| 14546 |
.el .IP \f(CWPerl_sinh\fR 4 |
| 14547 |
.IX Item "Perl_sinh" |
| 14548 |
.ie n .IP """Perl_sqrt""" 4 |
| 14549 |
.el .IP \f(CWPerl_sqrt\fR 4 |
| 14550 |
.IX Item "Perl_sqrt" |
| 14551 |
.ie n .IP """Perl_tan""" 4 |
| 14552 |
.el .IP \f(CWPerl_tan\fR 4 |
| 14553 |
.IX Item "Perl_tan" |
| 14554 |
.ie n .IP """Perl_tanh""" 4 |
| 14555 |
.el .IP \f(CWPerl_tanh\fR 4 |
| 14556 |
.IX Xref "Perl_acos Perl_asin Perl_atan Perl_atan2 Perl_ceil Perl_cos Perl_cosh Perl_exp Perl_floor Perl_fmod Perl_frexp Perl_isfinite Perl_isinf Perl_isnan Perl_ldexp Perl_log Perl_log10 Perl_modf Perl_pow Perl_sin Perl_sinh Perl_sqrt Perl_tan Perl_tanh" |
| 14557 |
.IX Item "Perl_tanh" |
| 14558 |
.PD |
| 14559 |
These perform the corresponding mathematical operation on the operand(s), using |
| 14560 |
the libc function designed for the task that has just enough precision for an |
| 14561 |
NV on this platform. If no such function with sufficient precision exists, |
| 14562 |
the highest precision one available is used. |
| 14563 |
.RS 4 |
| 14564 |
.Sp |
| 14565 |
.Vb 10 |
| 14566 |
\& NV Perl_acos (NV x) |
| 14567 |
\& NV Perl_asin (NV x) |
| 14568 |
\& NV Perl_atan (NV x) |
| 14569 |
\& NV Perl_atan2 (NV x, NV y) |
| 14570 |
\& NV Perl_ceil (NV x) |
| 14571 |
\& NV Perl_cos (NV x) |
| 14572 |
\& NV Perl_cosh (NV x) |
| 14573 |
\& NV Perl_exp (NV x) |
| 14574 |
\& NV Perl_floor (NV x) |
| 14575 |
\& NV Perl_fmod (NV x, NV y) |
| 14576 |
\& NV Perl_frexp (NV x, int *exp) |
| 14577 |
\& IV Perl_isfinite(NV x) |
| 14578 |
\& IV Perl_isinf (NV x) |
| 14579 |
\& IV Perl_isnan (NV x) |
| 14580 |
\& NV Perl_ldexp (NV x, int exp) |
| 14581 |
\& NV Perl_log (NV x) |
| 14582 |
\& NV Perl_log10 (NV x) |
| 14583 |
\& NV Perl_modf (NV x, NV *iptr) |
| 14584 |
\& NV Perl_pow (NV x, NV y) |
| 14585 |
\& NV Perl_sin (NV x) |
| 14586 |
\& NV Perl_sinh (NV x) |
| 14587 |
\& NV Perl_sqrt (NV x) |
| 14588 |
\& NV Perl_tan (NV x) |
| 14589 |
\& NV Perl_tanh (NV x) |
| 14590 |
.Ve |
| 14591 |
.RE |
| 14592 |
.RS 4 |
| 14593 |
.RE |
| 14594 |
.ie n .IP """Perl_signbit""" 4 |
| 14595 |
.el .IP \f(CWPerl_signbit\fR 4 |
| 14596 |
.IX Xref "Perl_signbit" |
| 14597 |
.IX Item "Perl_signbit" |
| 14598 |
NOTE: \f(CW\*(C`Perl_signbit\*(C'\fR is \fBexperimental\fR and may change or be |
| 14599 |
removed without notice. |
| 14600 |
.Sp |
| 14601 |
Return a non-zero integer if the sign bit on an NV is set, and 0 if |
| 14602 |
it is not. |
| 14603 |
.Sp |
| 14604 |
If \fIConfigure\fR detects this system has a \f(CWsignbit()\fR that will work with |
| 14605 |
our NVs, then we just use it via the \f(CW\*(C`#define\*(C'\fR in \fIperl.h\fR. Otherwise, |
| 14606 |
fall back on this implementation. The main use of this function |
| 14607 |
is catching \f(CW\-0.0\fR. |
| 14608 |
.Sp |
| 14609 |
\&\f(CW\*(C`Configure\*(C'\fR notes: This function is called \f(CW\*(AqPerl_signbit\*(Aq\fR instead of a |
| 14610 |
plain \f(CW\*(Aqsignbit\*(Aq\fR because it is easy to imagine a system having a \f(CWsignbit()\fR |
| 14611 |
function or macro that doesn't happen to work with our particular choice |
| 14612 |
of NVs. We shouldn't just re\-\f(CW\*(C`#define\*(C'\fR \f(CW\*(C`signbit\*(C'\fR as \f(CW\*(C`Perl_signbit\*(C'\fR and expect |
| 14613 |
the standard system headers to be happy. Also, this is a no-context |
| 14614 |
function (no \f(CW\*(C`pTHX_\*(C'\fR) because \f(CWPerl_signbit()\fR is usually re\-\f(CW\*(C`#defined\*(C'\fR in |
| 14615 |
\&\fIperl.h\fR as a simple macro call to the system's \f(CWsignbit()\fR. |
| 14616 |
Users should just always call \f(CWPerl_signbit()\fR. |
| 14617 |
.RS 4 |
| 14618 |
.Sp |
| 14619 |
.Vb 1 |
| 14620 |
\& int Perl_signbit(NV f) |
| 14621 |
.Ve |
| 14622 |
.RE |
| 14623 |
.RS 4 |
| 14624 |
.RE |
| 14625 |
.ie n .IP """PL_hexdigit""" 4 |
| 14626 |
.el .IP \f(CWPL_hexdigit\fR 4 |
| 14627 |
.IX Xref "PL_hexdigit" |
| 14628 |
.IX Item "PL_hexdigit" |
| 14629 |
This array, indexed by an integer, converts that value into the character that |
| 14630 |
represents it. For example, if the input is 8, the return will be a string |
| 14631 |
whose first character is '8'. What is actually returned is a pointer into a |
| 14632 |
string. All you are interested in is the first character of that string. To |
| 14633 |
get uppercase letters (for the values 10..15), add 16 to the index. Hence, |
| 14634 |
\&\f(CW\*(C`PL_hexdigit[11]\*(C'\fR is \f(CW\*(Aqb\*(Aq\fR, and \f(CW\*(C`PL_hexdigit[11+16]\*(C'\fR is \f(CW\*(AqB\*(Aq\fR. Adding 16 |
| 14635 |
to an index whose representation is '0'..'9' yields the same as not adding 16. |
| 14636 |
Indices outside the range 0..31 result in (bad) undedefined behavior. |
| 14637 |
.ie n .IP """READ_XDIGIT""" 4 |
| 14638 |
.el .IP \f(CWREAD_XDIGIT\fR 4 |
| 14639 |
.IX Xref "READ_XDIGIT" |
| 14640 |
.IX Item "READ_XDIGIT" |
| 14641 |
Returns the value of an ASCII-range hex digit and advances the string pointer. |
| 14642 |
Behaviour is only well defined when isXDIGIT(*str) is true. |
| 14643 |
.RS 4 |
| 14644 |
.Sp |
| 14645 |
.Vb 1 |
| 14646 |
\& U8 READ_XDIGIT(char str*) |
| 14647 |
.Ve |
| 14648 |
.RE |
| 14649 |
.RS 4 |
| 14650 |
.RE |
| 14651 |
.ie n .IP """scan_bin""" 4 |
| 14652 |
.el .IP \f(CWscan_bin\fR 4 |
| 14653 |
.IX Xref "scan_bin" |
| 14654 |
.IX Item "scan_bin" |
| 14655 |
For backwards compatibility. Use \f(CW\*(C`grok_bin\*(C'\fR instead. |
| 14656 |
.RS 4 |
| 14657 |
.Sp |
| 14658 |
.Vb 1 |
| 14659 |
\& NV scan_bin(const char *start, STRLEN len, STRLEN *retlen) |
| 14660 |
.Ve |
| 14661 |
.RE |
| 14662 |
.RS 4 |
| 14663 |
.RE |
| 14664 |
.ie n .IP """scan_hex""" 4 |
| 14665 |
.el .IP \f(CWscan_hex\fR 4 |
| 14666 |
.IX Xref "scan_hex" |
| 14667 |
.IX Item "scan_hex" |
| 14668 |
For backwards compatibility. Use \f(CW\*(C`grok_hex\*(C'\fR instead. |
| 14669 |
.RS 4 |
| 14670 |
.Sp |
| 14671 |
.Vb 1 |
| 14672 |
\& NV scan_hex(const char *start, STRLEN len, STRLEN *retlen) |
| 14673 |
.Ve |
| 14674 |
.RE |
| 14675 |
.RS 4 |
| 14676 |
.RE |
| 14677 |
.ie n .IP """scan_oct""" 4 |
| 14678 |
.el .IP \f(CWscan_oct\fR 4 |
| 14679 |
.IX Xref "scan_oct" |
| 14680 |
.IX Item "scan_oct" |
| 14681 |
For backwards compatibility. Use \f(CW\*(C`grok_oct\*(C'\fR instead. |
| 14682 |
.RS 4 |
| 14683 |
.Sp |
| 14684 |
.Vb 1 |
| 14685 |
\& NV scan_oct(const char *start, STRLEN len, STRLEN *retlen) |
| 14686 |
.Ve |
| 14687 |
.RE |
| 14688 |
.RS 4 |
| 14689 |
.RE |
| 14690 |
.ie n .IP """seedDrand01""" 4 |
| 14691 |
.el .IP \f(CWseedDrand01\fR 4 |
| 14692 |
.IX Xref "seedDrand01" |
| 14693 |
.IX Item "seedDrand01" |
| 14694 |
This symbol defines the macro to be used in seeding the |
| 14695 |
random number generator (see \f(CW"Drand01"\fR). |
| 14696 |
.RS 4 |
| 14697 |
.Sp |
| 14698 |
.Vb 1 |
| 14699 |
\& void seedDrand01(Rand_seed_t x) |
| 14700 |
.Ve |
| 14701 |
.RE |
| 14702 |
.RS 4 |
| 14703 |
.RE |
| 14704 |
.ie n .IP """Strtod""" 4 |
| 14705 |
.el .IP \f(CWStrtod\fR 4 |
| 14706 |
.IX Xref "Strtod" |
| 14707 |
.IX Item "Strtod" |
| 14708 |
This is a synonym for "my_strtod". |
| 14709 |
.RS 4 |
| 14710 |
.Sp |
| 14711 |
.Vb 1 |
| 14712 |
\& NV Strtod(NN const char * const s, NULLOK char ** e) |
| 14713 |
.Ve |
| 14714 |
.RE |
| 14715 |
.RS 4 |
| 14716 |
.RE |
| 14717 |
.ie n .IP """Strtol""" 4 |
| 14718 |
.el .IP \f(CWStrtol\fR 4 |
| 14719 |
.IX Xref "Strtol" |
| 14720 |
.IX Item "Strtol" |
| 14721 |
Platform and configuration independent \f(CW\*(C`strtol\*(C'\fR. This expands to the |
| 14722 |
appropriate \f(CW\*(C`strotol\*(C'\fR\-like function based on the platform and \fIConfigure\fR |
| 14723 |
options>. For example it could expand to \f(CW\*(C`strtoll\*(C'\fR or \f(CW\*(C`strtoq\*(C'\fR instead of |
| 14724 |
\&\f(CW\*(C`strtol\*(C'\fR. |
| 14725 |
.RS 4 |
| 14726 |
.Sp |
| 14727 |
.Vb 1 |
| 14728 |
\& NV Strtol(NN const char * const s, NULLOK char ** e, int base) |
| 14729 |
.Ve |
| 14730 |
.RE |
| 14731 |
.RS 4 |
| 14732 |
.RE |
| 14733 |
.ie n .IP """Strtoul""" 4 |
| 14734 |
.el .IP \f(CWStrtoul\fR 4 |
| 14735 |
.IX Xref "Strtoul" |
| 14736 |
.IX Item "Strtoul" |
| 14737 |
Platform and configuration independent \f(CW\*(C`strtoul\*(C'\fR. This expands to the |
| 14738 |
appropriate \f(CW\*(C`strotoul\*(C'\fR\-like function based on the platform and \fIConfigure\fR |
| 14739 |
options>. For example it could expand to \f(CW\*(C`strtoull\*(C'\fR or \f(CW\*(C`strtouq\*(C'\fR instead of |
| 14740 |
\&\f(CW\*(C`strtoul\*(C'\fR. |
| 14741 |
.RS 4 |
| 14742 |
.Sp |
| 14743 |
.Vb 1 |
| 14744 |
\& NV Strtoul(NN const char * const s, NULLOK char ** e, int base) |
| 14745 |
.Ve |
| 14746 |
.RE |
| 14747 |
.RS 4 |
| 14748 |
.RE |
| 14749 |
.SH Optrees |
| 14750 |
.IX Xref "CALL_CHECKER_REQUIRE_GV OPf_KIDS OPpEARLY_CV OPpENTERSUB_AMPER RV2CVOPCV_MARK_EARLY RV2CVOPCV_RETURN_NAME_GV" |
| 14751 |
.IX Header "Optrees" |
| 14752 |
.ie n .IP """alloccopstash""" 4 |
| 14753 |
.el .IP \f(CWalloccopstash\fR 4 |
| 14754 |
.IX Xref "alloccopstash" |
| 14755 |
.IX Item "alloccopstash" |
| 14756 |
NOTE: \f(CW\*(C`alloccopstash\*(C'\fR is \fBexperimental\fR and may change or be |
| 14757 |
removed without notice. |
| 14758 |
.Sp |
| 14759 |
Available only under threaded builds, this function allocates an entry in |
| 14760 |
\&\f(CW\*(C`PL_stashpad\*(C'\fR for the stash passed to it. |
| 14761 |
.RS 4 |
| 14762 |
.Sp |
| 14763 |
.Vb 1 |
| 14764 |
\& PADOFFSET alloccopstash(HV *hv) |
| 14765 |
.Ve |
| 14766 |
.RE |
| 14767 |
.RS 4 |
| 14768 |
.RE |
| 14769 |
.ie n .IP """BINOP""" 4 |
| 14770 |
.el .IP \f(CWBINOP\fR 4 |
| 14771 |
.IX Item "BINOP" |
| 14772 |
Described in perlguts. |
| 14773 |
.ie n .IP """block_end""" 4 |
| 14774 |
.el .IP \f(CWblock_end\fR 4 |
| 14775 |
.IX Xref "block_end" |
| 14776 |
.IX Item "block_end" |
| 14777 |
Handles compile-time scope exit. \f(CW\*(C`floor\*(C'\fR |
| 14778 |
is the savestack index returned by |
| 14779 |
\&\f(CW\*(C`block_start\*(C'\fR, and \f(CW\*(C`seq\*(C'\fR is the body of the block. Returns the block, |
| 14780 |
possibly modified. |
| 14781 |
.RS 4 |
| 14782 |
.Sp |
| 14783 |
.Vb 1 |
| 14784 |
\& OP * block_end(I32 floor, OP *seq) |
| 14785 |
.Ve |
| 14786 |
.RE |
| 14787 |
.RS 4 |
| 14788 |
.RE |
| 14789 |
.ie n .IP """block_start""" 4 |
| 14790 |
.el .IP \f(CWblock_start\fR 4 |
| 14791 |
.IX Xref "block_start" |
| 14792 |
.IX Item "block_start" |
| 14793 |
Handles compile-time scope entry. |
| 14794 |
Arranges for hints to be restored on block |
| 14795 |
exit and also handles pad sequence numbers to make lexical variables scope |
| 14796 |
right. Returns a savestack index for use with \f(CW\*(C`block_end\*(C'\fR. |
| 14797 |
.RS 4 |
| 14798 |
.Sp |
| 14799 |
.Vb 1 |
| 14800 |
\& int block_start(int full) |
| 14801 |
.Ve |
| 14802 |
.RE |
| 14803 |
.RS 4 |
| 14804 |
.RE |
| 14805 |
.ie n .IP """ck_entersub_args_list""" 4 |
| 14806 |
.el .IP \f(CWck_entersub_args_list\fR 4 |
| 14807 |
.IX Xref "ck_entersub_args_list" |
| 14808 |
.IX Item "ck_entersub_args_list" |
| 14809 |
Performs the default fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR |
| 14810 |
op tree. This consists of applying list context to each of the |
| 14811 |
argument ops. This is the standard treatment used on a call marked |
| 14812 |
with \f(CW\*(C`&\*(C'\fR, or a method call, or a call through a subroutine reference, |
| 14813 |
or any other call where the callee can't be identified at compile time, |
| 14814 |
or a call where the callee has no prototype. |
| 14815 |
.RS 4 |
| 14816 |
.Sp |
| 14817 |
.Vb 1 |
| 14818 |
\& OP * ck_entersub_args_list(OP *entersubop) |
| 14819 |
.Ve |
| 14820 |
.RE |
| 14821 |
.RS 4 |
| 14822 |
.RE |
| 14823 |
.ie n .IP """ck_entersub_args_proto""" 4 |
| 14824 |
.el .IP \f(CWck_entersub_args_proto\fR 4 |
| 14825 |
.IX Xref "ck_entersub_args_proto" |
| 14826 |
.IX Item "ck_entersub_args_proto" |
| 14827 |
Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree |
| 14828 |
based on a subroutine prototype. This makes various modifications to |
| 14829 |
the argument ops, from applying context up to inserting \f(CW\*(C`refgen\*(C'\fR ops, |
| 14830 |
and checking the number and syntactic types of arguments, as directed by |
| 14831 |
the prototype. This is the standard treatment used on a subroutine call, |
| 14832 |
not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time |
| 14833 |
and has a prototype. |
| 14834 |
.Sp |
| 14835 |
\&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call. |
| 14836 |
It may be a normal defined scalar, of which the string value will be used. |
| 14837 |
Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR |
| 14838 |
that has been cast to \f(CW\*(C`SV*\*(C'\fR) which has a prototype. The prototype |
| 14839 |
supplied, in whichever form, does not need to match the actual callee |
| 14840 |
referenced by the op tree. |
| 14841 |
.Sp |
| 14842 |
If the argument ops disagree with the prototype, for example by having |
| 14843 |
an unacceptable number of arguments, a valid op tree is returned anyway. |
| 14844 |
The error is reflected in the parser state, normally resulting in a single |
| 14845 |
exception at the top level of parsing which covers all the compilation |
| 14846 |
errors that occurred. In the error message, the callee is referred to |
| 14847 |
by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter. |
| 14848 |
.RS 4 |
| 14849 |
.Sp |
| 14850 |
.Vb 2 |
| 14851 |
\& OP * ck_entersub_args_proto(OP *entersubop, GV *namegv, |
| 14852 |
\& SV *protosv) |
| 14853 |
.Ve |
| 14854 |
.RE |
| 14855 |
.RS 4 |
| 14856 |
.RE |
| 14857 |
.ie n .IP """ck_entersub_args_proto_or_list""" 4 |
| 14858 |
.el .IP \f(CWck_entersub_args_proto_or_list\fR 4 |
| 14859 |
.IX Xref "ck_entersub_args_proto_or_list" |
| 14860 |
.IX Item "ck_entersub_args_proto_or_list" |
| 14861 |
Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree either |
| 14862 |
based on a subroutine prototype or using default list-context processing. |
| 14863 |
This is the standard treatment used on a subroutine call, not marked |
| 14864 |
with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time. |
| 14865 |
.Sp |
| 14866 |
\&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call, |
| 14867 |
or indicates that there is no prototype. It may be a normal scalar, |
| 14868 |
in which case if it is defined then the string value will be used |
| 14869 |
as a prototype, and if it is undefined then there is no prototype. |
| 14870 |
Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR |
| 14871 |
that has been cast to \f(CW\*(C`SV*\*(C'\fR), of which the prototype will be used if it |
| 14872 |
has one. The prototype (or lack thereof) supplied, in whichever form, |
| 14873 |
does not need to match the actual callee referenced by the op tree. |
| 14874 |
.Sp |
| 14875 |
If the argument ops disagree with the prototype, for example by having |
| 14876 |
an unacceptable number of arguments, a valid op tree is returned anyway. |
| 14877 |
The error is reflected in the parser state, normally resulting in a single |
| 14878 |
exception at the top level of parsing which covers all the compilation |
| 14879 |
errors that occurred. In the error message, the callee is referred to |
| 14880 |
by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter. |
| 14881 |
.RS 4 |
| 14882 |
.Sp |
| 14883 |
.Vb 2 |
| 14884 |
\& OP * ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv, |
| 14885 |
\& SV *protosv) |
| 14886 |
.Ve |
| 14887 |
.RE |
| 14888 |
.RS 4 |
| 14889 |
.RE |
| 14890 |
.ie n .IP """cv_const_sv""" 4 |
| 14891 |
.el .IP \f(CWcv_const_sv\fR 4 |
| 14892 |
.IX Xref "cv_const_sv" |
| 14893 |
.IX Item "cv_const_sv" |
| 14894 |
If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining, returns the constant |
| 14895 |
value returned by the sub. Otherwise, returns \f(CW\*(C`NULL\*(C'\fR. |
| 14896 |
.Sp |
| 14897 |
Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in |
| 14898 |
"Constant Functions" in perlsub. |
| 14899 |
.RS 4 |
| 14900 |
.Sp |
| 14901 |
.Vb 1 |
| 14902 |
\& SV * cv_const_sv(const CV * const cv) |
| 14903 |
.Ve |
| 14904 |
.RE |
| 14905 |
.RS 4 |
| 14906 |
.RE |
| 14907 |
.ie n .IP """cv_get_call_checker""" 4 |
| 14908 |
.el .IP \f(CWcv_get_call_checker\fR 4 |
| 14909 |
.IX Xref "cv_get_call_checker" |
| 14910 |
.IX Item "cv_get_call_checker" |
| 14911 |
The original form of "cv_get_call_checker_flags", which does not return |
| 14912 |
checker flags. When using a checker function returned by this function, |
| 14913 |
it is only safe to call it with a genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument. |
| 14914 |
.RS 4 |
| 14915 |
.Sp |
| 14916 |
.Vb 2 |
| 14917 |
\& void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p, |
| 14918 |
\& SV **ckobj_p) |
| 14919 |
.Ve |
| 14920 |
.RE |
| 14921 |
.RS 4 |
| 14922 |
.RE |
| 14923 |
.ie n .IP """cv_get_call_checker_flags""" 4 |
| 14924 |
.el .IP \f(CWcv_get_call_checker_flags\fR 4 |
| 14925 |
.IX Xref "cv_get_call_checker_flags" |
| 14926 |
.IX Item "cv_get_call_checker_flags" |
| 14927 |
Retrieves the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR. |
| 14928 |
Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a |
| 14929 |
subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified |
| 14930 |
at compile time as \f(CW\*(C`cv\*(C'\fR. |
| 14931 |
.Sp |
| 14932 |
The C\-level function pointer is returned in \f(CW*ckfun_p\fR, an SV argument |
| 14933 |
for it is returned in \f(CW*ckobj_p\fR, and control flags are returned in |
| 14934 |
\&\f(CW*ckflags_p\fR. The function is intended to be called in this manner: |
| 14935 |
.Sp |
| 14936 |
.Vb 1 |
| 14937 |
\& entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p)); |
| 14938 |
.Ve |
| 14939 |
.Sp |
| 14940 |
In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op, |
| 14941 |
which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies |
| 14942 |
the name that should be used by the check function to refer |
| 14943 |
to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics. |
| 14944 |
It is permitted to apply the check function in non-standard situations, |
| 14945 |
such as to a call to a different subroutine or to a method call. |
| 14946 |
.Sp |
| 14947 |
\&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR |
| 14948 |
bit is clear in \f(CW*ckflags_p\fR, it is permitted to pass a CV or other SV |
| 14949 |
instead, anything that can be used as the first argument to "cv_name". |
| 14950 |
If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW*ckflags_p\fR then the |
| 14951 |
check function requires \f(CW\*(C`namegv\*(C'\fR to be a genuine GV. |
| 14952 |
.Sp |
| 14953 |
By default, the check function is |
| 14954 |
Perl_ck_entersub_args_proto_or_list, |
| 14955 |
the SV parameter is \f(CW\*(C`cv\*(C'\fR itself, and the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR |
| 14956 |
flag is clear. This implements standard prototype processing. It can |
| 14957 |
be changed, for a particular subroutine, by "cv_set_call_checker_flags". |
| 14958 |
.Sp |
| 14959 |
If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW\*(C`gflags\*(C'\fR then it |
| 14960 |
indicates that the caller only knows about the genuine GV version of |
| 14961 |
\&\f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit will always be set in |
| 14962 |
\&\f(CW*ckflags_p\fR, regardless of the check function's recorded requirements. |
| 14963 |
If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is clear in \f(CW\*(C`gflags\*(C'\fR then it |
| 14964 |
indicates the caller knows about the possibility of passing something |
| 14965 |
other than a GV as \f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit may |
| 14966 |
be either set or clear in \f(CW*ckflags_p\fR, indicating the check function's |
| 14967 |
recorded requirements. |
| 14968 |
.Sp |
| 14969 |
\&\f(CW\*(C`gflags\*(C'\fR is a bitset passed into \f(CW\*(C`cv_get_call_checker_flags\*(C'\fR, in which |
| 14970 |
only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit currently has a defined meaning |
| 14971 |
(for which see above). All other bits should be clear. |
| 14972 |
.RS 4 |
| 14973 |
.Sp |
| 14974 |
.Vb 3 |
| 14975 |
\& void cv_get_call_checker_flags(CV *cv, U32 gflags, |
| 14976 |
\& Perl_call_checker *ckfun_p, |
| 14977 |
\& SV **ckobj_p, U32 *ckflags_p) |
| 14978 |
.Ve |
| 14979 |
.RE |
| 14980 |
.RS 4 |
| 14981 |
.RE |
| 14982 |
.ie n .IP """cv_set_call_checker""" 4 |
| 14983 |
.el .IP \f(CWcv_set_call_checker\fR 4 |
| 14984 |
.IX Xref "cv_set_call_checker" |
| 14985 |
.IX Item "cv_set_call_checker" |
| 14986 |
The original form of "cv_set_call_checker_flags", which passes it the |
| 14987 |
\&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR flag for backward-compatibility. The effect |
| 14988 |
of that flag setting is that the check function is guaranteed to get a |
| 14989 |
genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument. |
| 14990 |
.RS 4 |
| 14991 |
.Sp |
| 14992 |
.Vb 2 |
| 14993 |
\& void cv_set_call_checker(CV *cv, Perl_call_checker ckfun, |
| 14994 |
\& SV *ckobj) |
| 14995 |
.Ve |
| 14996 |
.RE |
| 14997 |
.RS 4 |
| 14998 |
.RE |
| 14999 |
.ie n .IP """cv_set_call_checker_flags""" 4 |
| 15000 |
.el .IP \f(CWcv_set_call_checker_flags\fR 4 |
| 15001 |
.IX Xref "cv_set_call_checker_flags" |
| 15002 |
.IX Item "cv_set_call_checker_flags" |
| 15003 |
Sets the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR. |
| 15004 |
Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a |
| 15005 |
subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified |
| 15006 |
at compile time as \f(CW\*(C`cv\*(C'\fR. |
| 15007 |
.Sp |
| 15008 |
The C\-level function pointer is supplied in \f(CW\*(C`ckfun\*(C'\fR, an SV argument for |
| 15009 |
it is supplied in \f(CW\*(C`ckobj\*(C'\fR, and control flags are supplied in \f(CW\*(C`ckflags\*(C'\fR. |
| 15010 |
The function should be defined like this: |
| 15011 |
.Sp |
| 15012 |
.Vb 1 |
| 15013 |
\& STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj) |
| 15014 |
.Ve |
| 15015 |
.Sp |
| 15016 |
It is intended to be called in this manner: |
| 15017 |
.Sp |
| 15018 |
.Vb 1 |
| 15019 |
\& entersubop = ckfun(aTHX_ entersubop, namegv, ckobj); |
| 15020 |
.Ve |
| 15021 |
.Sp |
| 15022 |
In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op, |
| 15023 |
which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies |
| 15024 |
the name that should be used by the check function to refer |
| 15025 |
to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics. |
| 15026 |
It is permitted to apply the check function in non-standard situations, |
| 15027 |
such as to a call to a different subroutine or to a method call. |
| 15028 |
.Sp |
| 15029 |
\&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. For efficiency, perl may pass a |
| 15030 |
CV or other SV instead. Whatever is passed can be used as the first |
| 15031 |
argument to "cv_name". You can force perl to pass a GV by including |
| 15032 |
\&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR in the \f(CW\*(C`ckflags\*(C'\fR. |
| 15033 |
.Sp |
| 15034 |
\&\f(CW\*(C`ckflags\*(C'\fR is a bitset, in which only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR |
| 15035 |
bit currently has a defined meaning (for which see above). All other |
| 15036 |
bits should be clear. |
| 15037 |
.Sp |
| 15038 |
The current setting for a particular CV can be retrieved by |
| 15039 |
"cv_get_call_checker_flags". |
| 15040 |
.RS 4 |
| 15041 |
.Sp |
| 15042 |
.Vb 2 |
| 15043 |
\& void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun, |
| 15044 |
\& SV *ckobj, U32 ckflags) |
| 15045 |
.Ve |
| 15046 |
.RE |
| 15047 |
.RS 4 |
| 15048 |
.RE |
| 15049 |
.ie n .IP """finalize_optree""" 4 |
| 15050 |
.el .IP \f(CWfinalize_optree\fR 4 |
| 15051 |
.IX Xref "finalize_optree" |
| 15052 |
.IX Item "finalize_optree" |
| 15053 |
This function finalizes the optree. Should be called directly after |
| 15054 |
the complete optree is built. It does some additional |
| 15055 |
checking which can't be done in the normal \f(CW\*(C`ck_\*(C'\fRxxx functions and makes |
| 15056 |
the tree thread-safe. |
| 15057 |
.RS 4 |
| 15058 |
.Sp |
| 15059 |
.Vb 1 |
| 15060 |
\& void finalize_optree(OP *o) |
| 15061 |
.Ve |
| 15062 |
.RE |
| 15063 |
.RS 4 |
| 15064 |
.RE |
| 15065 |
.ie n .IP """forbid_outofblock_ops""" 4 |
| 15066 |
.el .IP \f(CWforbid_outofblock_ops\fR 4 |
| 15067 |
.IX Xref "forbid_outofblock_ops" |
| 15068 |
.IX Item "forbid_outofblock_ops" |
| 15069 |
NOTE: \f(CW\*(C`forbid_outofblock_ops\*(C'\fR is \fBexperimental\fR and may change or be |
| 15070 |
removed without notice. |
| 15071 |
.Sp |
| 15072 |
Checks an optree that implements a block, to ensure there are no control-flow |
| 15073 |
ops that attempt to leave the block. Any \f(CW\*(C`OP_RETURN\*(C'\fR is forbidden, as is any |
| 15074 |
\&\f(CW\*(C`OP_GOTO\*(C'\fR. Loops are analysed, so any LOOPEX op (\f(CW\*(C`OP_NEXT\*(C'\fR, \f(CW\*(C`OP_LAST\*(C'\fR or |
| 15075 |
\&\f(CW\*(C`OP_REDO\*(C'\fR) that affects a loop that contains it within the block are |
| 15076 |
permitted, but those that do not are forbidden. |
| 15077 |
.Sp |
| 15078 |
If any of these forbidden constructions are detected, an exception is thrown |
| 15079 |
by using the op name and the blockname argument to construct a suitable |
| 15080 |
message. |
| 15081 |
.Sp |
| 15082 |
This function alone is not sufficient to ensure the optree does not perform |
| 15083 |
any of these forbidden activities during runtime, as it might call a different |
| 15084 |
function that performs a non-local LOOPEX, or a string\-\fBeval()\fR that performs a |
| 15085 |
\&\f(CW\*(C`goto\*(C'\fR, or various other things. It is intended purely as a compile-time |
| 15086 |
check for those that could be detected statically. Additional runtime checks |
| 15087 |
may be required depending on the circumstance it is used for. |
| 15088 |
.Sp |
| 15089 |
Note currently that \fIall\fR \f(CW\*(C`OP_GOTO\*(C'\fR ops are forbidden, even in cases where |
| 15090 |
they might otherwise be safe to execute. This may be permitted in a later |
| 15091 |
version. |
| 15092 |
.RS 4 |
| 15093 |
.Sp |
| 15094 |
.Vb 1 |
| 15095 |
\& void forbid_outofblock_ops(OP *o, const char *blockname) |
| 15096 |
.Ve |
| 15097 |
.RE |
| 15098 |
.RS 4 |
| 15099 |
.RE |
| 15100 |
.ie n .IP """LINKLIST""" 4 |
| 15101 |
.el .IP \f(CWLINKLIST\fR 4 |
| 15102 |
.IX Xref "LINKLIST" |
| 15103 |
.IX Item "LINKLIST" |
| 15104 |
Given the root of an optree, link the tree in execution order using the |
| 15105 |
\&\f(CW\*(C`op_next\*(C'\fR pointers and return the first op executed. If this has |
| 15106 |
already been done, it will not be redone, and \f(CW\*(C`o\->op_next\*(C'\fR will be |
| 15107 |
returned. If \f(CW\*(C`o\->op_next\*(C'\fR is not already set, \f(CW\*(C`o\*(C'\fR should be at |
| 15108 |
least an \f(CW\*(C`UNOP\*(C'\fR. |
| 15109 |
.RS 4 |
| 15110 |
.Sp |
| 15111 |
.Vb 1 |
| 15112 |
\& OP* LINKLIST(OP *o) |
| 15113 |
.Ve |
| 15114 |
.RE |
| 15115 |
.RS 4 |
| 15116 |
.RE |
| 15117 |
.ie n .IP """LISTOP""" 4 |
| 15118 |
.el .IP \f(CWLISTOP\fR 4 |
| 15119 |
.IX Item "LISTOP" |
| 15120 |
Described in perlguts. |
| 15121 |
.ie n .IP """LOGOP""" 4 |
| 15122 |
.el .IP \f(CWLOGOP\fR 4 |
| 15123 |
.IX Item "LOGOP" |
| 15124 |
Described in perlguts. |
| 15125 |
.ie n .IP """LOOP""" 4 |
| 15126 |
.el .IP \f(CWLOOP\fR 4 |
| 15127 |
.IX Item "LOOP" |
| 15128 |
Described in perlguts. |
| 15129 |
.ie n .IP """newANONATTRSUB""" 4 |
| 15130 |
.el .IP \f(CWnewANONATTRSUB\fR 4 |
| 15131 |
.IX Xref "newANONATTRSUB" |
| 15132 |
.IX Item "newANONATTRSUB" |
| 15133 |
Construct a nameless (anonymous) Perl subroutine, also performing some |
| 15134 |
surrounding jobs. |
| 15135 |
.Sp |
| 15136 |
This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter |
| 15137 |
set to FALSE, and its \f(CW\*(C`o\*(C'\fR parameter to NULL. |
| 15138 |
For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern. |
| 15139 |
.RS 4 |
| 15140 |
.Sp |
| 15141 |
.Vb 1 |
| 15142 |
\& OP * newANONATTRSUB(I32 floor, OP *proto, OP *attrs, OP *block) |
| 15143 |
.Ve |
| 15144 |
.RE |
| 15145 |
.RS 4 |
| 15146 |
.RE |
| 15147 |
.ie n .IP """newANONHASH""" 4 |
| 15148 |
.el .IP \f(CWnewANONHASH\fR 4 |
| 15149 |
.IX Xref "newANONHASH" |
| 15150 |
.IX Item "newANONHASH" |
| 15151 |
Constructs, checks, and returns an anonymous hash op. |
| 15152 |
.RS 4 |
| 15153 |
.Sp |
| 15154 |
.Vb 1 |
| 15155 |
\& OP * newANONHASH(OP *o) |
| 15156 |
.Ve |
| 15157 |
.RE |
| 15158 |
.RS 4 |
| 15159 |
.RE |
| 15160 |
.ie n .IP """newANONLIST""" 4 |
| 15161 |
.el .IP \f(CWnewANONLIST\fR 4 |
| 15162 |
.IX Xref "newANONLIST" |
| 15163 |
.IX Item "newANONLIST" |
| 15164 |
Constructs, checks, and returns an anonymous list op. |
| 15165 |
.RS 4 |
| 15166 |
.Sp |
| 15167 |
.Vb 1 |
| 15168 |
\& OP * newANONLIST(OP *o) |
| 15169 |
.Ve |
| 15170 |
.RE |
| 15171 |
.RS 4 |
| 15172 |
.RE |
| 15173 |
.ie n .IP """newANONSUB""" 4 |
| 15174 |
.el .IP \f(CWnewANONSUB\fR 4 |
| 15175 |
.IX Xref "newANONSUB" |
| 15176 |
.IX Item "newANONSUB" |
| 15177 |
Construct a nameless (anonymous) Perl subroutine without attributes, also |
| 15178 |
performing some surrounding jobs. |
| 15179 |
.Sp |
| 15180 |
This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter |
| 15181 |
set to FALSE, and its \f(CW\*(C`o\*(C'\fR and \f(CW\*(C`attrs\*(C'\fR parameters to NULL. |
| 15182 |
For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern. |
| 15183 |
.RS 4 |
| 15184 |
.Sp |
| 15185 |
.Vb 1 |
| 15186 |
\& OP * newANONSUB(I32 floor, OP *proto, OP *block) |
| 15187 |
.Ve |
| 15188 |
.RE |
| 15189 |
.RS 4 |
| 15190 |
.RE |
| 15191 |
.ie n .IP """newARGDEFELEMOP""" 4 |
| 15192 |
.el .IP \f(CWnewARGDEFELEMOP\fR 4 |
| 15193 |
.IX Xref "newARGDEFELEMOP" |
| 15194 |
.IX Item "newARGDEFELEMOP" |
| 15195 |
Constructs and returns a new \f(CW\*(C`OP_ARGDEFELEM\*(C'\fR op which provides a defaulting |
| 15196 |
expression given by \f(CW\*(C`expr\*(C'\fR for the signature parameter at the index given |
| 15197 |
by \f(CW\*(C`argindex\*(C'\fR. The expression optree is consumed by this function and |
| 15198 |
becomes part of the returned optree. |
| 15199 |
.RS 4 |
| 15200 |
.Sp |
| 15201 |
.Vb 1 |
| 15202 |
\& OP * newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex) |
| 15203 |
.Ve |
| 15204 |
.RE |
| 15205 |
.RS 4 |
| 15206 |
.RE |
| 15207 |
.ie n .IP """newASSIGNOP""" 4 |
| 15208 |
.el .IP \f(CWnewASSIGNOP\fR 4 |
| 15209 |
.IX Xref "newASSIGNOP" |
| 15210 |
.IX Item "newASSIGNOP" |
| 15211 |
Constructs, checks, and returns an assignment op. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR |
| 15212 |
supply the parameters of the assignment; they are consumed by this |
| 15213 |
function and become part of the constructed op tree. |
| 15214 |
.Sp |
| 15215 |
If \f(CW\*(C`optype\*(C'\fR is \f(CW\*(C`OP_ANDASSIGN\*(C'\fR, \f(CW\*(C`OP_ORASSIGN\*(C'\fR, or \f(CW\*(C`OP_DORASSIGN\*(C'\fR, then |
| 15216 |
a suitable conditional optree is constructed. If \f(CW\*(C`optype\*(C'\fR is the opcode |
| 15217 |
of a binary operator, such as \f(CW\*(C`OP_BIT_OR\*(C'\fR, then an op is constructed that |
| 15218 |
performs the binary operation and assigns the result to the left argument. |
| 15219 |
Either way, if \f(CW\*(C`optype\*(C'\fR is non-zero then \f(CW\*(C`flags\*(C'\fR has no effect. |
| 15220 |
.Sp |
| 15221 |
If \f(CW\*(C`optype\*(C'\fR is zero, then a plain scalar or list assignment is |
| 15222 |
constructed. Which type of assignment it is is automatically determined. |
| 15223 |
\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR |
| 15224 |
will be set automatically, and, shifted up eight bits, the eight bits |
| 15225 |
of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically |
| 15226 |
set as required. |
| 15227 |
.RS 4 |
| 15228 |
.Sp |
| 15229 |
.Vb 1 |
| 15230 |
\& OP * newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right) |
| 15231 |
.Ve |
| 15232 |
.RE |
| 15233 |
.RS 4 |
| 15234 |
.RE |
| 15235 |
.ie n .IP """newATTRSUB""" 4 |
| 15236 |
.el .IP \f(CWnewATTRSUB\fR 4 |
| 15237 |
.IX Xref "newATTRSUB" |
| 15238 |
.IX Item "newATTRSUB" |
| 15239 |
Construct a Perl subroutine, also performing some surrounding jobs, |
| 15240 |
returning a pointer to the constructed subroutine. |
| 15241 |
.Sp |
| 15242 |
This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter |
| 15243 |
set to FALSE. This means that if \f(CW\*(C`o\*(C'\fR is null, the new sub will be anonymous; |
| 15244 |
otherwise the name will be derived from \f(CW\*(C`o\*(C'\fR in the way described (as with all |
| 15245 |
other details) in "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern. |
| 15246 |
.RS 4 |
| 15247 |
.Sp |
| 15248 |
.Vb 2 |
| 15249 |
\& CV * newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs, |
| 15250 |
\& OP *block) |
| 15251 |
.Ve |
| 15252 |
.RE |
| 15253 |
.RS 4 |
| 15254 |
.RE |
| 15255 |
.ie n .IP """newAVREF""" 4 |
| 15256 |
.el .IP \f(CWnewAVREF\fR 4 |
| 15257 |
.IX Xref "newAVREF" |
| 15258 |
.IX Item "newAVREF" |
| 15259 |
Constructs, checks, and returns an arrary reference op. |
| 15260 |
.RS 4 |
| 15261 |
.Sp |
| 15262 |
.Vb 1 |
| 15263 |
\& OP * newAVREF(OP *o) |
| 15264 |
.Ve |
| 15265 |
.RE |
| 15266 |
.RS 4 |
| 15267 |
.RE |
| 15268 |
.ie n .IP """newBINOP""" 4 |
| 15269 |
.el .IP \f(CWnewBINOP\fR 4 |
| 15270 |
.IX Xref "newBINOP" |
| 15271 |
.IX Item "newBINOP" |
| 15272 |
Constructs, checks, and returns an op of any binary type. \f(CW\*(C`type\*(C'\fR |
| 15273 |
is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except |
| 15274 |
that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits, |
| 15275 |
the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or |
| 15276 |
2 is automatically set as required. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR supply up to |
| 15277 |
two ops to be the direct children of the binary op; they are consumed |
| 15278 |
by this function and become part of the constructed op tree. |
| 15279 |
.RS 4 |
| 15280 |
.Sp |
| 15281 |
.Vb 1 |
| 15282 |
\& OP * newBINOP(I32 type, I32 flags, OP *first, OP *last) |
| 15283 |
.Ve |
| 15284 |
.RE |
| 15285 |
.RS 4 |
| 15286 |
.RE |
| 15287 |
.ie n .IP """newCONDOP""" 4 |
| 15288 |
.el .IP \f(CWnewCONDOP\fR 4 |
| 15289 |
.IX Xref "newCONDOP" |
| 15290 |
.IX Item "newCONDOP" |
| 15291 |
Constructs, checks, and returns a conditional-expression (\f(CW\*(C`cond_expr\*(C'\fR) |
| 15292 |
op. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR |
| 15293 |
will be set automatically, and, shifted up eight bits, the eight bits of |
| 15294 |
\&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is automatically set. |
| 15295 |
\&\f(CW\*(C`first\*(C'\fR supplies the expression selecting between the two branches, |
| 15296 |
and \f(CW\*(C`trueop\*(C'\fR and \f(CW\*(C`falseop\*(C'\fR supply the branches; they are consumed by |
| 15297 |
this function and become part of the constructed op tree. |
| 15298 |
.RS 4 |
| 15299 |
.Sp |
| 15300 |
.Vb 1 |
| 15301 |
\& OP * newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop) |
| 15302 |
.Ve |
| 15303 |
.RE |
| 15304 |
.RS 4 |
| 15305 |
.RE |
| 15306 |
.ie n .IP """newCONSTSUB""" 4 |
| 15307 |
.el .IP \f(CWnewCONSTSUB\fR 4 |
| 15308 |
.IX Item "newCONSTSUB" |
| 15309 |
.PD 0 |
| 15310 |
.ie n .IP """newCONSTSUB_flags""" 4 |
| 15311 |
.el .IP \f(CWnewCONSTSUB_flags\fR 4 |
| 15312 |
.IX Xref "newCONSTSUB newCONSTSUB_flags" |
| 15313 |
.IX Item "newCONSTSUB_flags" |
| 15314 |
.PD |
| 15315 |
Construct a constant subroutine, also performing some surrounding |
| 15316 |
jobs. A scalar constant-valued subroutine is eligible for inlining |
| 15317 |
at compile-time, and in Perl code can be created by \f(CW\*(C`sub\ FOO\ ()\ {\ 123\ }\*(C'\fR. Other kinds of constant subroutine have other treatment. |
| 15318 |
.Sp |
| 15319 |
The subroutine will have an empty prototype and will ignore any arguments |
| 15320 |
when called. Its constant behaviour is determined by \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`sv\*(C'\fR |
| 15321 |
is null, the subroutine will yield an empty list. If \f(CW\*(C`sv\*(C'\fR points to a |
| 15322 |
scalar, the subroutine will always yield that scalar. If \f(CW\*(C`sv\*(C'\fR points |
| 15323 |
to an array, the subroutine will always yield a list of the elements of |
| 15324 |
that array in list context, or the number of elements in the array in |
| 15325 |
scalar context. This function takes ownership of one counted reference |
| 15326 |
to the scalar or array, and will arrange for the object to live as long |
| 15327 |
as the subroutine does. If \f(CW\*(C`sv\*(C'\fR points to a scalar then the inlining |
| 15328 |
assumes that the value of the scalar will never change, so the caller |
| 15329 |
must ensure that the scalar is not subsequently written to. If \f(CW\*(C`sv\*(C'\fR |
| 15330 |
points to an array then no such assumption is made, so it is ostensibly |
| 15331 |
safe to mutate the array or its elements, but whether this is really |
| 15332 |
supported has not been determined. |
| 15333 |
.Sp |
| 15334 |
The subroutine will have \f(CW\*(C`CvFILE\*(C'\fR set according to \f(CW\*(C`PL_curcop\*(C'\fR. |
| 15335 |
Other aspects of the subroutine will be left in their default state. |
| 15336 |
The caller is free to mutate the subroutine beyond its initial state |
| 15337 |
after this function has returned. |
| 15338 |
.Sp |
| 15339 |
If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its |
| 15340 |
\&\f(CW\*(C`CvGV\*(C'\fR referring to an \f(CW\*(C`_\|_ANON_\|_\*(C'\fR glob. If \f(CW\*(C`name\*(C'\fR is non-null then the |
| 15341 |
subroutine will be named accordingly, referenced by the appropriate glob. |
| 15342 |
.Sp |
| 15343 |
\&\f(CW\*(C`name\*(C'\fR is a string, giving a sigilless symbol name. |
| 15344 |
For \f(CW\*(C`/newCONSTSUB\*(C'\fR, \f(CW\*(C`name\*(C'\fR is NUL-terminated, interpreted as Latin\-1. |
| 15345 |
.Sp |
| 15346 |
For \f(CW\*(C`/newCONSTSUB_flags\*(C'\fR, \f(CW\*(C`name\*(C'\fR has length \f(CW\*(C`len\*(C'\fR bytes, hence may contain |
| 15347 |
embedded NULs. It is interpreted as UTF\-8 if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SVf_UTF8\*(C'\fR bit |
| 15348 |
set, and Latin\-1 otherwise. \f(CW\*(C`flags\*(C'\fR should not have bits set other than |
| 15349 |
\&\f(CW\*(C`SVf_UTF8\*(C'\fR. |
| 15350 |
.Sp |
| 15351 |
The name may be either qualified or unqualified. If the |
| 15352 |
name is unqualified then it defaults to being in the stash specified by |
| 15353 |
\&\f(CW\*(C`stash\*(C'\fR if that is non-null, or to \f(CW\*(C`PL_curstash\*(C'\fR if \f(CW\*(C`stash\*(C'\fR is null. |
| 15354 |
The symbol is always added to the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR |
| 15355 |
semantics. |
| 15356 |
.Sp |
| 15357 |
If there is already a subroutine of the specified name, then the new sub |
| 15358 |
will replace the existing one in the glob. A warning may be generated |
| 15359 |
about the redefinition. |
| 15360 |
.Sp |
| 15361 |
If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or |
| 15362 |
\&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic |
| 15363 |
running of phase-related subroutines. In this case the relevant glob will |
| 15364 |
be left not containing any subroutine, even if it did contain one before. |
| 15365 |
Execution of the subroutine will likely be a no-op, unless \f(CW\*(C`sv\*(C'\fR was |
| 15366 |
a tied array or the caller modified the subroutine in some interesting |
| 15367 |
way before it was executed. In the case of \f(CW\*(C`BEGIN\*(C'\fR, the treatment is |
| 15368 |
buggy: the sub will be executed when only half built, and may be deleted |
| 15369 |
prematurely, possibly causing a crash. |
| 15370 |
.Sp |
| 15371 |
The function returns a pointer to the constructed subroutine. If the sub |
| 15372 |
is anonymous then ownership of one counted reference to the subroutine |
| 15373 |
is transferred to the caller. If the sub is named then the caller does |
| 15374 |
not get ownership of a reference. In most such cases, where the sub |
| 15375 |
has a non-phase name, the sub will be alive at the point it is returned |
| 15376 |
by virtue of being contained in the glob that names it. A phase-named |
| 15377 |
subroutine will usually be alive by virtue of the reference owned by |
| 15378 |
the phase's automatic run queue. A \f(CW\*(C`BEGIN\*(C'\fR subroutine may have been |
| 15379 |
destroyed already by the time this function returns, but currently bugs |
| 15380 |
occur in that case before the caller gets control. It is the caller's |
| 15381 |
responsibility to ensure that it knows which of these situations applies. |
| 15382 |
.RS 4 |
| 15383 |
.Sp |
| 15384 |
.Vb 3 |
| 15385 |
\& CV * newCONSTSUB (HV *stash, const char *name, SV *sv) |
| 15386 |
\& CV * newCONSTSUB_flags(HV *stash, const char *name, STRLEN len, |
| 15387 |
\& U32 flags, SV *sv) |
| 15388 |
.Ve |
| 15389 |
.RE |
| 15390 |
.RS 4 |
| 15391 |
.RE |
| 15392 |
.ie n .IP """newCVREF""" 4 |
| 15393 |
.el .IP \f(CWnewCVREF\fR 4 |
| 15394 |
.IX Xref "newCVREF" |
| 15395 |
.IX Item "newCVREF" |
| 15396 |
Constructs, checks, and returns a code reference op. |
| 15397 |
.RS 4 |
| 15398 |
.Sp |
| 15399 |
.Vb 1 |
| 15400 |
\& OP * newCVREF(I32 flags, OP *o) |
| 15401 |
.Ve |
| 15402 |
.RE |
| 15403 |
.RS 4 |
| 15404 |
.RE |
| 15405 |
.ie n .IP """newDEFEROP""" 4 |
| 15406 |
.el .IP \f(CWnewDEFEROP\fR 4 |
| 15407 |
.IX Xref "newDEFEROP" |
| 15408 |
.IX Item "newDEFEROP" |
| 15409 |
NOTE: \f(CW\*(C`newDEFEROP\*(C'\fR is \fBexperimental\fR and may change or be |
| 15410 |
removed without notice. |
| 15411 |
.Sp |
| 15412 |
Constructs and returns a deferred-block statement that implements the |
| 15413 |
\&\f(CW\*(C`defer\*(C'\fR semantics. The \f(CW\*(C`block\*(C'\fR optree is consumed by this function and |
| 15414 |
becomes part of the returned optree. |
| 15415 |
.Sp |
| 15416 |
The \f(CW\*(C`flags\*(C'\fR argument carries additional flags to set on the returned op, |
| 15417 |
including the \f(CW\*(C`op_private\*(C'\fR field. |
| 15418 |
.RS 4 |
| 15419 |
.Sp |
| 15420 |
.Vb 1 |
| 15421 |
\& OP * newDEFEROP(I32 flags, OP *block) |
| 15422 |
.Ve |
| 15423 |
.RE |
| 15424 |
.RS 4 |
| 15425 |
.RE |
| 15426 |
.ie n .IP """newDEFSVOP""" 4 |
| 15427 |
.el .IP \f(CWnewDEFSVOP\fR 4 |
| 15428 |
.IX Xref "newDEFSVOP" |
| 15429 |
.IX Item "newDEFSVOP" |
| 15430 |
Constructs and returns an op to access \f(CW$_\fR. |
| 15431 |
.RS 4 |
| 15432 |
.Sp |
| 15433 |
.Vb 1 |
| 15434 |
\& OP * newDEFSVOP() |
| 15435 |
.Ve |
| 15436 |
.RE |
| 15437 |
.RS 4 |
| 15438 |
.RE |
| 15439 |
.ie n .IP """newFOROP""" 4 |
| 15440 |
.el .IP \f(CWnewFOROP\fR 4 |
| 15441 |
.IX Xref "newFOROP" |
| 15442 |
.IX Item "newFOROP" |
| 15443 |
Constructs, checks, and returns an op tree expressing a \f(CW\*(C`foreach\*(C'\fR |
| 15444 |
loop (iteration through a list of values). This is a heavyweight loop, |
| 15445 |
with structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR and suchlike. |
| 15446 |
.Sp |
| 15447 |
\&\f(CW\*(C`sv\*(C'\fR optionally supplies the variable(s) that will be aliased to each |
| 15448 |
item in turn; if null, it defaults to \f(CW$_\fR. |
| 15449 |
\&\f(CW\*(C`expr\*(C'\fR supplies the list of values to iterate over. \f(CW\*(C`block\*(C'\fR supplies |
| 15450 |
the main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR |
| 15451 |
block that operates as a second half of the body. All of these optree |
| 15452 |
inputs are consumed by this function and become part of the constructed |
| 15453 |
op tree. |
| 15454 |
.Sp |
| 15455 |
\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR |
| 15456 |
op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for |
| 15457 |
the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set |
| 15458 |
automatically. |
| 15459 |
.RS 4 |
| 15460 |
.Sp |
| 15461 |
.Vb 1 |
| 15462 |
\& OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont) |
| 15463 |
.Ve |
| 15464 |
.RE |
| 15465 |
.RS 4 |
| 15466 |
.RE |
| 15467 |
.ie n .IP """newGIVENOP""" 4 |
| 15468 |
.el .IP \f(CWnewGIVENOP\fR 4 |
| 15469 |
.IX Xref "newGIVENOP" |
| 15470 |
.IX Item "newGIVENOP" |
| 15471 |
Constructs, checks, and returns an op tree expressing a \f(CW\*(C`given\*(C'\fR block. |
| 15472 |
\&\f(CW\*(C`cond\*(C'\fR supplies the expression to whose value \f(CW$_\fR will be locally |
| 15473 |
aliased, and \f(CW\*(C`block\*(C'\fR supplies the body of the \f(CW\*(C`given\*(C'\fR construct; they |
| 15474 |
are consumed by this function and become part of the constructed op tree. |
| 15475 |
\&\f(CW\*(C`defsv_off\*(C'\fR must be zero (it used to identity the pad slot of lexical \f(CW$_\fR). |
| 15476 |
.RS 4 |
| 15477 |
.Sp |
| 15478 |
.Vb 1 |
| 15479 |
\& OP * newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off) |
| 15480 |
.Ve |
| 15481 |
.RE |
| 15482 |
.RS 4 |
| 15483 |
.RE |
| 15484 |
.ie n .IP """newGVOP""" 4 |
| 15485 |
.el .IP \f(CWnewGVOP\fR 4 |
| 15486 |
.IX Xref "newGVOP" |
| 15487 |
.IX Item "newGVOP" |
| 15488 |
Constructs, checks, and returns an op of any type that involves an |
| 15489 |
embedded reference to a GV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the |
| 15490 |
eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`gv\*(C'\fR identifies the GV that the op should |
| 15491 |
reference; calling this function does not transfer ownership of any |
| 15492 |
reference to it. |
| 15493 |
.RS 4 |
| 15494 |
.Sp |
| 15495 |
.Vb 1 |
| 15496 |
\& OP * newGVOP(I32 type, I32 flags, GV *gv) |
| 15497 |
.Ve |
| 15498 |
.RE |
| 15499 |
.RS 4 |
| 15500 |
.RE |
| 15501 |
.ie n .IP """newGVREF""" 4 |
| 15502 |
.el .IP \f(CWnewGVREF\fR 4 |
| 15503 |
.IX Xref "newGVREF" |
| 15504 |
.IX Item "newGVREF" |
| 15505 |
Constructs, checks, and returns a glob reference op. |
| 15506 |
.RS 4 |
| 15507 |
.Sp |
| 15508 |
.Vb 1 |
| 15509 |
\& OP * newGVREF(I32 type, OP *o) |
| 15510 |
.Ve |
| 15511 |
.RE |
| 15512 |
.RS 4 |
| 15513 |
.RE |
| 15514 |
.ie n .IP """newHVREF""" 4 |
| 15515 |
.el .IP \f(CWnewHVREF\fR 4 |
| 15516 |
.IX Xref "newHVREF" |
| 15517 |
.IX Item "newHVREF" |
| 15518 |
Constructs, checks, and returns a hash reference op. |
| 15519 |
.RS 4 |
| 15520 |
.Sp |
| 15521 |
.Vb 1 |
| 15522 |
\& OP * newHVREF(OP *o) |
| 15523 |
.Ve |
| 15524 |
.RE |
| 15525 |
.RS 4 |
| 15526 |
.RE |
| 15527 |
.ie n .IP """newLISTOP""" 4 |
| 15528 |
.el .IP \f(CWnewLISTOP\fR 4 |
| 15529 |
.IX Xref "newLISTOP" |
| 15530 |
.IX Item "newLISTOP" |
| 15531 |
Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is |
| 15532 |
the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that |
| 15533 |
\&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR |
| 15534 |
supply up to two ops to be direct children of the list op; they are |
| 15535 |
consumed by this function and become part of the constructed op tree. |
| 15536 |
.Sp |
| 15537 |
For most list operators, the check function expects all the kid ops to be |
| 15538 |
present already, so calling \f(CW\*(C`newLISTOP(OP_JOIN, ...)\*(C'\fR (e.g.) is not |
| 15539 |
appropriate. What you want to do in that case is create an op of type |
| 15540 |
\&\f(CW\*(C`OP_LIST\*(C'\fR, append more children to it, and then call "op_convert_list". |
| 15541 |
See "op_convert_list" for more information. |
| 15542 |
.Sp |
| 15543 |
If a compiletime-known fixed list of child ops is required, the |
| 15544 |
"newLISTOPn" function can be used as a convenient shortcut, avoiding the |
| 15545 |
need to create a temporary plain \f(CW\*(C`OP_LIST\*(C'\fR in a new variable. |
| 15546 |
.RS 4 |
| 15547 |
.Sp |
| 15548 |
.Vb 1 |
| 15549 |
\& OP * newLISTOP(I32 type, I32 flags, OP *first, OP *last) |
| 15550 |
.Ve |
| 15551 |
.RE |
| 15552 |
.RS 4 |
| 15553 |
.RE |
| 15554 |
.ie n .IP """newLISTOPn""" 4 |
| 15555 |
.el .IP \f(CWnewLISTOPn\fR 4 |
| 15556 |
.IX Xref "newLISTOPn" |
| 15557 |
.IX Item "newLISTOPn" |
| 15558 |
Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is |
| 15559 |
the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that |
| 15560 |
\&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required. The variable number of |
| 15561 |
arguments after \f(CW\*(C`flags\*(C'\fR must all be OP pointers, terminated by a final |
| 15562 |
\&\f(CW\*(C`NULL\*(C'\fR pointer. These will all be consumed as direct children of the list |
| 15563 |
op and become part of the constructed op tree. |
| 15564 |
.Sp |
| 15565 |
Do not forget to end the arguments list with a \f(CW\*(C`NULL\*(C'\fR pointer. |
| 15566 |
.Sp |
| 15567 |
This function is useful as a shortcut to performing the sequence of |
| 15568 |
\&\f(CWnewLISTOP()\fR, \f(CWop_append_elem()\fR on each element and final |
| 15569 |
\&\f(CWop_convert_list()\fR in the case where a compiletime-known fixed sequence of |
| 15570 |
child ops is required. If a variable number of elements are required, or for |
| 15571 |
splicing in an entire sub-list of child ops, see instead "newLISTOP" and |
| 15572 |
"op_convert_list". |
| 15573 |
.RS 4 |
| 15574 |
.Sp |
| 15575 |
.Vb 1 |
| 15576 |
\& OP * newLISTOPn(I32 type, I32 flags, ...) |
| 15577 |
.Ve |
| 15578 |
.RE |
| 15579 |
.RS 4 |
| 15580 |
.RE |
| 15581 |
.ie n .IP """newLOGOP""" 4 |
| 15582 |
.el .IP \f(CWnewLOGOP\fR 4 |
| 15583 |
.IX Xref "newLOGOP" |
| 15584 |
.IX Item "newLOGOP" |
| 15585 |
Constructs, checks, and returns a logical (flow control) op. \f(CW\*(C`type\*(C'\fR |
| 15586 |
is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except |
| 15587 |
that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits, |
| 15588 |
the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is |
| 15589 |
automatically set. \f(CW\*(C`first\*(C'\fR supplies the expression controlling the |
| 15590 |
flow, and \f(CW\*(C`other\*(C'\fR supplies the side (alternate) chain of ops; they are |
| 15591 |
consumed by this function and become part of the constructed op tree. |
| 15592 |
.RS 4 |
| 15593 |
.Sp |
| 15594 |
.Vb 1 |
| 15595 |
\& OP * newLOGOP(I32 optype, I32 flags, OP *first, OP *other) |
| 15596 |
.Ve |
| 15597 |
.RE |
| 15598 |
.RS 4 |
| 15599 |
.RE |
| 15600 |
.ie n .IP """newLOOPEX""" 4 |
| 15601 |
.el .IP \f(CWnewLOOPEX\fR 4 |
| 15602 |
.IX Xref "newLOOPEX" |
| 15603 |
.IX Item "newLOOPEX" |
| 15604 |
Constructs, checks, and returns a loop-exiting op (such as \f(CW\*(C`goto\*(C'\fR |
| 15605 |
or \f(CW\*(C`last\*(C'\fR). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`label\*(C'\fR supplies the parameter |
| 15606 |
determining the target of the op; it is consumed by this function and |
| 15607 |
becomes part of the constructed op tree. |
| 15608 |
.RS 4 |
| 15609 |
.Sp |
| 15610 |
.Vb 1 |
| 15611 |
\& OP * newLOOPEX(I32 type, OP *label) |
| 15612 |
.Ve |
| 15613 |
.RE |
| 15614 |
.RS 4 |
| 15615 |
.RE |
| 15616 |
.ie n .IP """newLOOPOP""" 4 |
| 15617 |
.el .IP \f(CWnewLOOPOP\fR 4 |
| 15618 |
.IX Xref "newLOOPOP" |
| 15619 |
.IX Item "newLOOPOP" |
| 15620 |
Constructs, checks, and returns an op tree expressing a loop. This is |
| 15621 |
only a loop in the control flow through the op tree; it does not have |
| 15622 |
the heavyweight loop structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR |
| 15623 |
and suchlike. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the |
| 15624 |
top-level op, except that some bits will be set automatically as required. |
| 15625 |
\&\f(CW\*(C`expr\*(C'\fR supplies the expression controlling loop iteration, and \f(CW\*(C`block\*(C'\fR |
| 15626 |
supplies the body of the loop; they are consumed by this function and |
| 15627 |
become part of the constructed op tree. \f(CW\*(C`debuggable\*(C'\fR is currently |
| 15628 |
unused and should always be 1. |
| 15629 |
.RS 4 |
| 15630 |
.Sp |
| 15631 |
.Vb 1 |
| 15632 |
\& OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block) |
| 15633 |
.Ve |
| 15634 |
.RE |
| 15635 |
.RS 4 |
| 15636 |
.RE |
| 15637 |
.ie n .IP """newMETHOP""" 4 |
| 15638 |
.el .IP \f(CWnewMETHOP\fR 4 |
| 15639 |
.IX Xref "newMETHOP" |
| 15640 |
.IX Item "newMETHOP" |
| 15641 |
Constructs, checks, and returns an op of method type with a method name |
| 15642 |
evaluated at runtime. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight |
| 15643 |
bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, |
| 15644 |
and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that |
| 15645 |
the bit with value 1 is automatically set. \f(CW\*(C`dynamic_meth\*(C'\fR supplies an |
| 15646 |
op which evaluates method name; it is consumed by this function and |
| 15647 |
become part of the constructed op tree. |
| 15648 |
Supported optypes: \f(CW\*(C`OP_METHOD\*(C'\fR. |
| 15649 |
.RS 4 |
| 15650 |
.Sp |
| 15651 |
.Vb 1 |
| 15652 |
\& OP * newMETHOP(I32 type, I32 flags, OP *dynamic_meth) |
| 15653 |
.Ve |
| 15654 |
.RE |
| 15655 |
.RS 4 |
| 15656 |
.RE |
| 15657 |
.ie n .IP """newMETHOP_named""" 4 |
| 15658 |
.el .IP \f(CWnewMETHOP_named\fR 4 |
| 15659 |
.IX Xref "newMETHOP_named" |
| 15660 |
.IX Item "newMETHOP_named" |
| 15661 |
Constructs, checks, and returns an op of method type with a constant |
| 15662 |
method name. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of |
| 15663 |
\&\f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits of |
| 15664 |
\&\f(CW\*(C`op_private\*(C'\fR. \f(CW\*(C`const_meth\*(C'\fR supplies a constant method name; |
| 15665 |
it must be a shared COW string. |
| 15666 |
Supported optypes: \f(CW\*(C`OP_METHOD_NAMED\*(C'\fR. |
| 15667 |
.RS 4 |
| 15668 |
.Sp |
| 15669 |
.Vb 1 |
| 15670 |
\& OP * newMETHOP_named(I32 type, I32 flags, SV * const_meth) |
| 15671 |
.Ve |
| 15672 |
.RE |
| 15673 |
.RS 4 |
| 15674 |
.RE |
| 15675 |
.ie n .IP """newNULLLIST""" 4 |
| 15676 |
.el .IP \f(CWnewNULLLIST\fR 4 |
| 15677 |
.IX Xref "newNULLLIST" |
| 15678 |
.IX Item "newNULLLIST" |
| 15679 |
Constructs, checks, and returns a new \f(CW\*(C`stub\*(C'\fR op, which represents an |
| 15680 |
empty list expression. |
| 15681 |
.RS 4 |
| 15682 |
.Sp |
| 15683 |
.Vb 1 |
| 15684 |
\& OP * newNULLLIST() |
| 15685 |
.Ve |
| 15686 |
.RE |
| 15687 |
.RS 4 |
| 15688 |
.RE |
| 15689 |
.ie n .IP """newOP""" 4 |
| 15690 |
.el .IP \f(CWnewOP\fR 4 |
| 15691 |
.IX Xref "newOP" |
| 15692 |
.IX Item "newOP" |
| 15693 |
Constructs, checks, and returns an op of any base type (any type that |
| 15694 |
has no extra fields). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the |
| 15695 |
eight bits of \f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits |
| 15696 |
of \f(CW\*(C`op_private\*(C'\fR. |
| 15697 |
.RS 4 |
| 15698 |
.Sp |
| 15699 |
.Vb 1 |
| 15700 |
\& OP * newOP(I32 optype, I32 flags) |
| 15701 |
.Ve |
| 15702 |
.RE |
| 15703 |
.RS 4 |
| 15704 |
.RE |
| 15705 |
.ie n .IP """newPADOP""" 4 |
| 15706 |
.el .IP \f(CWnewPADOP\fR 4 |
| 15707 |
.IX Xref "newPADOP" |
| 15708 |
.IX Item "newPADOP" |
| 15709 |
Constructs, checks, and returns an op of any type that involves a |
| 15710 |
reference to a pad element. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the |
| 15711 |
eight bits of \f(CW\*(C`op_flags\*(C'\fR. A pad slot is automatically allocated, and |
| 15712 |
is populated with \f(CW\*(C`sv\*(C'\fR; this function takes ownership of one reference |
| 15713 |
to it. |
| 15714 |
.Sp |
| 15715 |
This function only exists if Perl has been compiled to use ithreads. |
| 15716 |
.RS 4 |
| 15717 |
.Sp |
| 15718 |
.Vb 1 |
| 15719 |
\& OP * newPADOP(I32 type, I32 flags, SV *sv) |
| 15720 |
.Ve |
| 15721 |
.RE |
| 15722 |
.RS 4 |
| 15723 |
.RE |
| 15724 |
.ie n .IP """newPMOP""" 4 |
| 15725 |
.el .IP \f(CWnewPMOP\fR 4 |
| 15726 |
.IX Xref "newPMOP" |
| 15727 |
.IX Item "newPMOP" |
| 15728 |
Constructs, checks, and returns an op of any pattern matching type. |
| 15729 |
\&\f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR |
| 15730 |
and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR. |
| 15731 |
.RS 4 |
| 15732 |
.Sp |
| 15733 |
.Vb 1 |
| 15734 |
\& OP * newPMOP(I32 type, I32 flags) |
| 15735 |
.Ve |
| 15736 |
.RE |
| 15737 |
.RS 4 |
| 15738 |
.RE |
| 15739 |
.ie n .IP """newPVOP""" 4 |
| 15740 |
.el .IP \f(CWnewPVOP\fR 4 |
| 15741 |
.IX Xref "newPVOP" |
| 15742 |
.IX Item "newPVOP" |
| 15743 |
Constructs, checks, and returns an op of any type that involves an |
| 15744 |
embedded C\-level pointer (PV). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives |
| 15745 |
the eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`pv\*(C'\fR supplies the C\-level pointer. |
| 15746 |
Depending on the op type, the memory referenced by \f(CW\*(C`pv\*(C'\fR may be freed |
| 15747 |
when the op is destroyed. If the op is of a freeing type, \f(CW\*(C`pv\*(C'\fR must |
| 15748 |
have been allocated using \f(CW\*(C`PerlMemShared_malloc\*(C'\fR. |
| 15749 |
.RS 4 |
| 15750 |
.Sp |
| 15751 |
.Vb 1 |
| 15752 |
\& OP * newPVOP(I32 type, I32 flags, char *pv) |
| 15753 |
.Ve |
| 15754 |
.RE |
| 15755 |
.RS 4 |
| 15756 |
.RE |
| 15757 |
.ie n .IP """newRANGE""" 4 |
| 15758 |
.el .IP \f(CWnewRANGE\fR 4 |
| 15759 |
.IX Xref "newRANGE" |
| 15760 |
.IX Item "newRANGE" |
| 15761 |
Constructs and returns a \f(CW\*(C`range\*(C'\fR op, with subordinate \f(CW\*(C`flip\*(C'\fR and |
| 15762 |
\&\f(CW\*(C`flop\*(C'\fR ops. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the |
| 15763 |
\&\f(CW\*(C`flip\*(C'\fR op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR |
| 15764 |
for both the \f(CW\*(C`flip\*(C'\fR and \f(CW\*(C`range\*(C'\fR ops, except that the bit with value |
| 15765 |
1 is automatically set. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR supply the expressions |
| 15766 |
controlling the endpoints of the range; they are consumed by this function |
| 15767 |
and become part of the constructed op tree. |
| 15768 |
.RS 4 |
| 15769 |
.Sp |
| 15770 |
.Vb 1 |
| 15771 |
\& OP * newRANGE(I32 flags, OP *left, OP *right) |
| 15772 |
.Ve |
| 15773 |
.RE |
| 15774 |
.RS 4 |
| 15775 |
.RE |
| 15776 |
.ie n .IP """newSLICEOP""" 4 |
| 15777 |
.el .IP \f(CWnewSLICEOP\fR 4 |
| 15778 |
.IX Xref "newSLICEOP" |
| 15779 |
.IX Item "newSLICEOP" |
| 15780 |
Constructs, checks, and returns an \f(CW\*(C`lslice\*(C'\fR (list slice) op. \f(CW\*(C`flags\*(C'\fR |
| 15781 |
gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will |
| 15782 |
be set automatically, and, shifted up eight bits, the eight bits of |
| 15783 |
\&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically |
| 15784 |
set as required. \f(CW\*(C`listval\*(C'\fR and \f(CW\*(C`subscript\*(C'\fR supply the parameters of |
| 15785 |
the slice; they are consumed by this function and become part of the |
| 15786 |
constructed op tree. |
| 15787 |
.RS 4 |
| 15788 |
.Sp |
| 15789 |
.Vb 1 |
| 15790 |
\& OP * newSLICEOP(I32 flags, OP *subscript, OP *listop) |
| 15791 |
.Ve |
| 15792 |
.RE |
| 15793 |
.RS 4 |
| 15794 |
.RE |
| 15795 |
.ie n .IP """newSTATEOP""" 4 |
| 15796 |
.el .IP \f(CWnewSTATEOP\fR 4 |
| 15797 |
.IX Xref "newSTATEOP" |
| 15798 |
.IX Item "newSTATEOP" |
| 15799 |
Constructs a state op (COP). The state op is normally a \f(CW\*(C`nextstate\*(C'\fR op, |
| 15800 |
but will be a \f(CW\*(C`dbstate\*(C'\fR op if debugging is enabled for currently-compiled |
| 15801 |
code. The state op is populated from \f(CW\*(C`PL_curcop\*(C'\fR (or \f(CW\*(C`PL_compiling\*(C'\fR). |
| 15802 |
If \f(CW\*(C`label\*(C'\fR is non-null, it supplies the name of a label to attach to |
| 15803 |
the state op; this function takes ownership of the memory pointed at by |
| 15804 |
\&\f(CW\*(C`label\*(C'\fR, and will free it. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR |
| 15805 |
for the state op. |
| 15806 |
.Sp |
| 15807 |
If \f(CW\*(C`o\*(C'\fR is null, the state op is returned. Otherwise the state op is |
| 15808 |
combined with \f(CW\*(C`o\*(C'\fR into a \f(CW\*(C`lineseq\*(C'\fR list op, which is returned. \f(CW\*(C`o\*(C'\fR |
| 15809 |
is consumed by this function and becomes part of the returned op tree. |
| 15810 |
.RS 4 |
| 15811 |
.Sp |
| 15812 |
.Vb 1 |
| 15813 |
\& OP * newSTATEOP(I32 flags, char *label, OP *o) |
| 15814 |
.Ve |
| 15815 |
.RE |
| 15816 |
.RS 4 |
| 15817 |
.RE |
| 15818 |
.ie n .IP """newSUB""" 4 |
| 15819 |
.el .IP \f(CWnewSUB\fR 4 |
| 15820 |
.IX Xref "newSUB" |
| 15821 |
.IX Item "newSUB" |
| 15822 |
Construct a Perl subroutine without attributes, and also performing some |
| 15823 |
surrounding jobs, returning a pointer to the constructed subroutine. |
| 15824 |
.Sp |
| 15825 |
This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter |
| 15826 |
set to FALSE, and its \f(CW\*(C`attrs\*(C'\fR parameter to NULL. This means that if \f(CW\*(C`o\*(C'\fR is |
| 15827 |
null, the new sub will be anonymous; otherwise the name will be derived from |
| 15828 |
\&\f(CW\*(C`o\*(C'\fR in the way described (as with all other details) in |
| 15829 |
"\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern. |
| 15830 |
.RS 4 |
| 15831 |
.Sp |
| 15832 |
.Vb 1 |
| 15833 |
\& CV * newSUB(I32 floor, OP *o, OP *proto, OP *block) |
| 15834 |
.Ve |
| 15835 |
.RE |
| 15836 |
.RS 4 |
| 15837 |
.RE |
| 15838 |
.ie n .IP """newSVOP""" 4 |
| 15839 |
.el .IP \f(CWnewSVOP\fR 4 |
| 15840 |
.IX Xref "newSVOP" |
| 15841 |
.IX Item "newSVOP" |
| 15842 |
Constructs, checks, and returns an op of any type that involves an |
| 15843 |
embedded SV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits |
| 15844 |
of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`sv\*(C'\fR gives the SV to embed in the op; this function |
| 15845 |
takes ownership of one reference to it. |
| 15846 |
.RS 4 |
| 15847 |
.Sp |
| 15848 |
.Vb 1 |
| 15849 |
\& OP * newSVOP(I32 type, I32 flags, SV *sv) |
| 15850 |
.Ve |
| 15851 |
.RE |
| 15852 |
.RS 4 |
| 15853 |
.RE |
| 15854 |
.ie n .IP """newSVREF""" 4 |
| 15855 |
.el .IP \f(CWnewSVREF\fR 4 |
| 15856 |
.IX Xref "newSVREF" |
| 15857 |
.IX Item "newSVREF" |
| 15858 |
Constructs, checks, and returns a scalar reference op. |
| 15859 |
.RS 4 |
| 15860 |
.Sp |
| 15861 |
.Vb 1 |
| 15862 |
\& OP * newSVREF(OP *o) |
| 15863 |
.Ve |
| 15864 |
.RE |
| 15865 |
.RS 4 |
| 15866 |
.RE |
| 15867 |
.ie n .IP """newTRYCATCHOP""" 4 |
| 15868 |
.el .IP \f(CWnewTRYCATCHOP\fR 4 |
| 15869 |
.IX Xref "newTRYCATCHOP" |
| 15870 |
.IX Item "newTRYCATCHOP" |
| 15871 |
NOTE: \f(CW\*(C`newTRYCATCHOP\*(C'\fR is \fBexperimental\fR and may change or be |
| 15872 |
removed without notice. |
| 15873 |
.Sp |
| 15874 |
Constructs and returns a conditional execution statement that implements |
| 15875 |
the \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR semantics. First the op tree in \f(CW\*(C`tryblock\*(C'\fR is executed, |
| 15876 |
inside a context that traps exceptions. If an exception occurs then the |
| 15877 |
optree in \f(CW\*(C`catchblock\*(C'\fR is executed, with the trapped exception set into the |
| 15878 |
lexical variable given by \f(CW\*(C`catchvar\*(C'\fR (which must be an op of type |
| 15879 |
\&\f(CW\*(C`OP_PADSV\*(C'\fR). All the optrees are consumed by this function and become part |
| 15880 |
of the returned op tree. |
| 15881 |
.Sp |
| 15882 |
The \f(CW\*(C`flags\*(C'\fR argument is currently ignored. |
| 15883 |
.RS 4 |
| 15884 |
.Sp |
| 15885 |
.Vb 2 |
| 15886 |
\& OP * newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar, |
| 15887 |
\& OP *catchblock) |
| 15888 |
.Ve |
| 15889 |
.RE |
| 15890 |
.RS 4 |
| 15891 |
.RE |
| 15892 |
.ie n .IP """newUNOP""" 4 |
| 15893 |
.el .IP \f(CWnewUNOP\fR 4 |
| 15894 |
.IX Xref "newUNOP" |
| 15895 |
.IX Item "newUNOP" |
| 15896 |
Constructs, checks, and returns an op of any unary type. \f(CW\*(C`type\*(C'\fR is |
| 15897 |
the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that |
| 15898 |
\&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required, and, shifted up eight |
| 15899 |
bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 |
| 15900 |
is automatically set. \f(CW\*(C`first\*(C'\fR supplies an optional op to be the direct |
| 15901 |
child of the unary op; it is consumed by this function and become part |
| 15902 |
of the constructed op tree. |
| 15903 |
.RS 4 |
| 15904 |
.Sp |
| 15905 |
.Vb 1 |
| 15906 |
\& OP * newUNOP(I32 type, I32 flags, OP *first) |
| 15907 |
.Ve |
| 15908 |
.RE |
| 15909 |
.RS 4 |
| 15910 |
.RE |
| 15911 |
.ie n .IP """newUNOP_AUX""" 4 |
| 15912 |
.el .IP \f(CWnewUNOP_AUX\fR 4 |
| 15913 |
.IX Xref "newUNOP_AUX" |
| 15914 |
.IX Item "newUNOP_AUX" |
| 15915 |
Similar to \f(CW\*(C`newUNOP\*(C'\fR, but creates an \f(CW\*(C`UNOP_AUX\*(C'\fR struct instead, with \f(CW\*(C`op_aux\*(C'\fR |
| 15916 |
initialised to \f(CW\*(C`aux\*(C'\fR |
| 15917 |
.RS 4 |
| 15918 |
.Sp |
| 15919 |
.Vb 2 |
| 15920 |
\& OP * newUNOP_AUX(I32 type, I32 flags, OP *first, |
| 15921 |
\& UNOP_AUX_item *aux) |
| 15922 |
.Ve |
| 15923 |
.RE |
| 15924 |
.RS 4 |
| 15925 |
.RE |
| 15926 |
.ie n .IP """newWHENOP""" 4 |
| 15927 |
.el .IP \f(CWnewWHENOP\fR 4 |
| 15928 |
.IX Xref "newWHENOP" |
| 15929 |
.IX Item "newWHENOP" |
| 15930 |
Constructs, checks, and returns an op tree expressing a \f(CW\*(C`when\*(C'\fR block. |
| 15931 |
\&\f(CW\*(C`cond\*(C'\fR supplies the test expression, and \f(CW\*(C`block\*(C'\fR supplies the block |
| 15932 |
that will be executed if the test evaluates to true; they are consumed |
| 15933 |
by this function and become part of the constructed op tree. \f(CW\*(C`cond\*(C'\fR |
| 15934 |
will be interpreted DWIMically, often as a comparison against \f(CW$_\fR, |
| 15935 |
and may be null to generate a \f(CW\*(C`default\*(C'\fR block. |
| 15936 |
.RS 4 |
| 15937 |
.Sp |
| 15938 |
.Vb 1 |
| 15939 |
\& OP * newWHENOP(OP *cond, OP *block) |
| 15940 |
.Ve |
| 15941 |
.RE |
| 15942 |
.RS 4 |
| 15943 |
.RE |
| 15944 |
.ie n .IP """newWHILEOP""" 4 |
| 15945 |
.el .IP \f(CWnewWHILEOP\fR 4 |
| 15946 |
.IX Xref "newWHILEOP" |
| 15947 |
.IX Item "newWHILEOP" |
| 15948 |
Constructs, checks, and returns an op tree expressing a \f(CW\*(C`while\*(C'\fR loop. |
| 15949 |
This is a heavyweight loop, with structure that allows exiting the loop |
| 15950 |
by \f(CW\*(C`last\*(C'\fR and suchlike. |
| 15951 |
.Sp |
| 15952 |
\&\f(CW\*(C`loop\*(C'\fR is an optional preconstructed \f(CW\*(C`enterloop\*(C'\fR op to use in the |
| 15953 |
loop; if it is null then a suitable op will be constructed automatically. |
| 15954 |
\&\f(CW\*(C`expr\*(C'\fR supplies the loop's controlling expression. \f(CW\*(C`block\*(C'\fR supplies the |
| 15955 |
main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR block |
| 15956 |
that operates as a second half of the body. All of these optree inputs |
| 15957 |
are consumed by this function and become part of the constructed op tree. |
| 15958 |
.Sp |
| 15959 |
\&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR |
| 15960 |
op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for |
| 15961 |
the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set |
| 15962 |
automatically. \f(CW\*(C`debuggable\*(C'\fR is currently unused and should always be 1. |
| 15963 |
\&\f(CW\*(C`has_my\*(C'\fR can be supplied as true to force the |
| 15964 |
loop body to be enclosed in its own scope. |
| 15965 |
.RS 4 |
| 15966 |
.Sp |
| 15967 |
.Vb 2 |
| 15968 |
\& OP * newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr, |
| 15969 |
\& OP *block, OP *cont, I32 has_my) |
| 15970 |
.Ve |
| 15971 |
.RE |
| 15972 |
.RS 4 |
| 15973 |
.RE |
| 15974 |
.ie n .IP """newXS""" 4 |
| 15975 |
.el .IP \f(CWnewXS\fR 4 |
| 15976 |
.IX Xref "newXS" |
| 15977 |
.IX Item "newXS" |
| 15978 |
Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. \f(CW\*(C`filename\*(C'\fR needs to be |
| 15979 |
static storage, as it is used directly as \fBCvFILE()\fR, without a copy being made. |
| 15980 |
.ie n .IP """OA_BASEOP""" 4 |
| 15981 |
.el .IP \f(CWOA_BASEOP\fR 4 |
| 15982 |
.IX Item "OA_BASEOP" |
| 15983 |
.PD 0 |
| 15984 |
.ie n .IP """OA_BINOP""" 4 |
| 15985 |
.el .IP \f(CWOA_BINOP\fR 4 |
| 15986 |
.IX Item "OA_BINOP" |
| 15987 |
.ie n .IP """OA_COP""" 4 |
| 15988 |
.el .IP \f(CWOA_COP\fR 4 |
| 15989 |
.IX Item "OA_COP" |
| 15990 |
.ie n .IP """OA_LISTOP""" 4 |
| 15991 |
.el .IP \f(CWOA_LISTOP\fR 4 |
| 15992 |
.IX Item "OA_LISTOP" |
| 15993 |
.ie n .IP """OA_LOGOP""" 4 |
| 15994 |
.el .IP \f(CWOA_LOGOP\fR 4 |
| 15995 |
.IX Item "OA_LOGOP" |
| 15996 |
.ie n .IP """OA_LOOP""" 4 |
| 15997 |
.el .IP \f(CWOA_LOOP\fR 4 |
| 15998 |
.IX Item "OA_LOOP" |
| 15999 |
.ie n .IP """OA_PADOP""" 4 |
| 16000 |
.el .IP \f(CWOA_PADOP\fR 4 |
| 16001 |
.IX Item "OA_PADOP" |
| 16002 |
.ie n .IP """OA_PMOP""" 4 |
| 16003 |
.el .IP \f(CWOA_PMOP\fR 4 |
| 16004 |
.IX Item "OA_PMOP" |
| 16005 |
.ie n .IP """OA_PVOP_OR_SVOP""" 4 |
| 16006 |
.el .IP \f(CWOA_PVOP_OR_SVOP\fR 4 |
| 16007 |
.IX Item "OA_PVOP_OR_SVOP" |
| 16008 |
.ie n .IP """OA_SVOP""" 4 |
| 16009 |
.el .IP \f(CWOA_SVOP\fR 4 |
| 16010 |
.IX Item "OA_SVOP" |
| 16011 |
.ie n .IP """OA_UNOP""" 4 |
| 16012 |
.el .IP \f(CWOA_UNOP\fR 4 |
| 16013 |
.IX Item "OA_UNOP" |
| 16014 |
.PD |
| 16015 |
Described in perlguts. |
| 16016 |
.ie n .IP """OP""" 4 |
| 16017 |
.el .IP \f(CWOP\fR 4 |
| 16018 |
.IX Item "OP" |
| 16019 |
Described in perlguts. |
| 16020 |
.ie n .IP """op_append_elem""" 4 |
| 16021 |
.el .IP \f(CWop_append_elem\fR 4 |
| 16022 |
.IX Xref "op_append_elem" |
| 16023 |
.IX Item "op_append_elem" |
| 16024 |
Append an item to the list of ops contained directly within a list-type |
| 16025 |
op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the list-type op, |
| 16026 |
and \f(CW\*(C`last\*(C'\fR is the op to append to the list. \f(CW\*(C`optype\*(C'\fR specifies the |
| 16027 |
intended opcode for the list. If \f(CW\*(C`first\*(C'\fR is not already a list of the |
| 16028 |
right type, it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR |
| 16029 |
is null, the other is returned unchanged. |
| 16030 |
.RS 4 |
| 16031 |
.Sp |
| 16032 |
.Vb 1 |
| 16033 |
\& OP * op_append_elem(I32 optype, OP *first, OP *last) |
| 16034 |
.Ve |
| 16035 |
.RE |
| 16036 |
.RS 4 |
| 16037 |
.RE |
| 16038 |
.ie n .IP """op_append_list""" 4 |
| 16039 |
.el .IP \f(CWop_append_list\fR 4 |
| 16040 |
.IX Xref "op_append_list" |
| 16041 |
.IX Item "op_append_list" |
| 16042 |
Concatenate the lists of ops contained directly within two list-type ops, |
| 16043 |
returning the combined list. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR are the list-type ops |
| 16044 |
to concatenate. \f(CW\*(C`optype\*(C'\fR specifies the intended opcode for the list. |
| 16045 |
If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is not already a list of the right type, |
| 16046 |
it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null, |
| 16047 |
the other is returned unchanged. |
| 16048 |
.RS 4 |
| 16049 |
.Sp |
| 16050 |
.Vb 1 |
| 16051 |
\& OP * op_append_list(I32 optype, OP *first, OP *last) |
| 16052 |
.Ve |
| 16053 |
.RE |
| 16054 |
.RS 4 |
| 16055 |
.RE |
| 16056 |
.ie n .IP """OP_CLASS""" 4 |
| 16057 |
.el .IP \f(CWOP_CLASS\fR 4 |
| 16058 |
.IX Xref "OP_CLASS" |
| 16059 |
.IX Item "OP_CLASS" |
| 16060 |
Return the class of the provided OP: that is, which of the *OP |
| 16061 |
structures it uses. For core ops this currently gets the information out |
| 16062 |
of \f(CW\*(C`PL_opargs\*(C'\fR, which does not always accurately reflect the type used; |
| 16063 |
in v5.26 onwards, see also the function \f(CW"op_class"\fR which can do a better |
| 16064 |
job of determining the used type. |
| 16065 |
.Sp |
| 16066 |
For custom ops the type is returned from the registration, and it is up |
| 16067 |
to the registree to ensure it is accurate. The value returned will be |
| 16068 |
one of the \f(CW\*(C`OA_\*(C'\fR* constants from \fIop.h\fR. |
| 16069 |
.RS 4 |
| 16070 |
.Sp |
| 16071 |
.Vb 1 |
| 16072 |
\& U32 OP_CLASS(OP *o) |
| 16073 |
.Ve |
| 16074 |
.RE |
| 16075 |
.RS 4 |
| 16076 |
.RE |
| 16077 |
.ie n .IP """op_contextualize""" 4 |
| 16078 |
.el .IP \f(CWop_contextualize\fR 4 |
| 16079 |
.IX Xref "op_contextualize" |
| 16080 |
.IX Item "op_contextualize" |
| 16081 |
Applies a syntactic context to an op tree representing an expression. |
| 16082 |
\&\f(CW\*(C`o\*(C'\fR is the op tree, and \f(CW\*(C`context\*(C'\fR must be \f(CW\*(C`G_SCALAR\*(C'\fR, \f(CW\*(C`G_LIST\*(C'\fR, |
| 16083 |
or \f(CW\*(C`G_VOID\*(C'\fR to specify the context to apply. The modified op tree |
| 16084 |
is returned. |
| 16085 |
.RS 4 |
| 16086 |
.Sp |
| 16087 |
.Vb 1 |
| 16088 |
\& OP * op_contextualize(OP *o, I32 context) |
| 16089 |
.Ve |
| 16090 |
.RE |
| 16091 |
.RS 4 |
| 16092 |
.RE |
| 16093 |
.ie n .IP """op_convert_list""" 4 |
| 16094 |
.el .IP \f(CWop_convert_list\fR 4 |
| 16095 |
.IX Xref "op_convert_list" |
| 16096 |
.IX Item "op_convert_list" |
| 16097 |
Converts \f(CW\*(C`o\*(C'\fR into a list op if it is not one already, and then converts it |
| 16098 |
into the specified \f(CW\*(C`type\*(C'\fR, calling its check function, allocating a target if |
| 16099 |
it needs one, and folding constants. |
| 16100 |
.Sp |
| 16101 |
A list-type op is usually constructed one kid at a time via \f(CW\*(C`newLISTOP\*(C'\fR, |
| 16102 |
\&\f(CW\*(C`op_prepend_elem\*(C'\fR and \f(CW\*(C`op_append_elem\*(C'\fR. Then finally it is passed to |
| 16103 |
\&\f(CW\*(C`op_convert_list\*(C'\fR to make it the right type. |
| 16104 |
.RS 4 |
| 16105 |
.Sp |
| 16106 |
.Vb 1 |
| 16107 |
\& OP * op_convert_list(I32 optype, I32 flags, OP *o) |
| 16108 |
.Ve |
| 16109 |
.RE |
| 16110 |
.RS 4 |
| 16111 |
.RE |
| 16112 |
.ie n .IP """OP_DESC""" 4 |
| 16113 |
.el .IP \f(CWOP_DESC\fR 4 |
| 16114 |
.IX Xref "OP_DESC" |
| 16115 |
.IX Item "OP_DESC" |
| 16116 |
Return a short description of the provided OP. |
| 16117 |
.RS 4 |
| 16118 |
.Sp |
| 16119 |
.Vb 1 |
| 16120 |
\& const char * OP_DESC(OP *o) |
| 16121 |
.Ve |
| 16122 |
.RE |
| 16123 |
.RS 4 |
| 16124 |
.RE |
| 16125 |
.ie n .IP """op_force_list""" 4 |
| 16126 |
.el .IP \f(CWop_force_list\fR 4 |
| 16127 |
.IX Xref "op_force_list" |
| 16128 |
.IX Item "op_force_list" |
| 16129 |
Promotes o and any siblings to be an \f(CW\*(C`OP_LIST\*(C'\fR if it is not already. If |
| 16130 |
a new \f(CW\*(C`OP_LIST\*(C'\fR op was created, its first child will be \f(CW\*(C`OP_PUSHMARK\*(C'\fR. |
| 16131 |
The returned node itself will be nulled, leaving only its children. |
| 16132 |
.Sp |
| 16133 |
This is often what you want to do before putting the optree into list |
| 16134 |
context; as |
| 16135 |
.Sp |
| 16136 |
.Vb 1 |
| 16137 |
\& o = op_contextualize(op_force_list(o), G_LIST); |
| 16138 |
.Ve |
| 16139 |
.RS 4 |
| 16140 |
.Sp |
| 16141 |
.Vb 1 |
| 16142 |
\& OP * op_force_list(OP *o) |
| 16143 |
.Ve |
| 16144 |
.RE |
| 16145 |
.RS 4 |
| 16146 |
.RE |
| 16147 |
.ie n .IP """op_free""" 4 |
| 16148 |
.el .IP \f(CWop_free\fR 4 |
| 16149 |
.IX Xref "op_free" |
| 16150 |
.IX Item "op_free" |
| 16151 |
Free an op and its children. Only use this when an op is no longer linked |
| 16152 |
to from any optree. |
| 16153 |
.Sp |
| 16154 |
Remember that any op with \f(CW\*(C`OPf_KIDS\*(C'\fR set is expected to have a valid |
| 16155 |
\&\f(CW\*(C`op_first\*(C'\fR pointer. If you are attempting to free an op but preserve its |
| 16156 |
child op, make sure to clear that flag before calling \f(CWop_free()\fR. For |
| 16157 |
example: |
| 16158 |
.Sp |
| 16159 |
.Vb 3 |
| 16160 |
\& OP *kid = o\->op_first; o\->op_first = NULL; |
| 16161 |
\& o\->op_flags &= ~OPf_KIDS; |
| 16162 |
\& op_free(o); |
| 16163 |
.Ve |
| 16164 |
.RS 4 |
| 16165 |
.Sp |
| 16166 |
.Vb 1 |
| 16167 |
\& void op_free(OP *arg) |
| 16168 |
.Ve |
| 16169 |
.RE |
| 16170 |
.RS 4 |
| 16171 |
.RE |
| 16172 |
.ie n .IP """OpHAS_SIBLING""" 4 |
| 16173 |
.el .IP \f(CWOpHAS_SIBLING\fR 4 |
| 16174 |
.IX Xref "OpHAS_SIBLING" |
| 16175 |
.IX Item "OpHAS_SIBLING" |
| 16176 |
Returns true if \f(CW\*(C`o\*(C'\fR has a sibling |
| 16177 |
.RS 4 |
| 16178 |
.Sp |
| 16179 |
.Vb 1 |
| 16180 |
\& bool OpHAS_SIBLING(OP *o) |
| 16181 |
.Ve |
| 16182 |
.RE |
| 16183 |
.RS 4 |
| 16184 |
.RE |
| 16185 |
.ie n .IP """OpLASTSIB_set""" 4 |
| 16186 |
.el .IP \f(CWOpLASTSIB_set\fR 4 |
| 16187 |
.IX Xref "OpLASTSIB_set" |
| 16188 |
.IX Item "OpLASTSIB_set" |
| 16189 |
Marks \f(CW\*(C`o\*(C'\fR as having no further siblings and marks |
| 16190 |
o as having the specified parent. See also \f(CW"OpMORESIB_set"\fR and |
| 16191 |
\&\f(CW\*(C`OpMAYBESIB_set\*(C'\fR. For a higher-level interface, see |
| 16192 |
\&\f(CW"op_sibling_splice"\fR. |
| 16193 |
.RS 4 |
| 16194 |
.Sp |
| 16195 |
.Vb 1 |
| 16196 |
\& void OpLASTSIB_set(OP *o, OP *parent) |
| 16197 |
.Ve |
| 16198 |
.RE |
| 16199 |
.RS 4 |
| 16200 |
.RE |
| 16201 |
.ie n .IP """op_linklist""" 4 |
| 16202 |
.el .IP \f(CWop_linklist\fR 4 |
| 16203 |
.IX Xref "op_linklist" |
| 16204 |
.IX Item "op_linklist" |
| 16205 |
This function is the implementation of the "LINKLIST" macro. It should |
| 16206 |
not be called directly. |
| 16207 |
.RS 4 |
| 16208 |
.Sp |
| 16209 |
.Vb 1 |
| 16210 |
\& OP * op_linklist(OP *o) |
| 16211 |
.Ve |
| 16212 |
.RE |
| 16213 |
.RS 4 |
| 16214 |
.RE |
| 16215 |
.ie n .IP """op_lvalue""" 4 |
| 16216 |
.el .IP \f(CWop_lvalue\fR 4 |
| 16217 |
.IX Xref "op_lvalue" |
| 16218 |
.IX Item "op_lvalue" |
| 16219 |
NOTE: \f(CW\*(C`op_lvalue\*(C'\fR is \fBexperimental\fR and may change or be |
| 16220 |
removed without notice. |
| 16221 |
.Sp |
| 16222 |
Propagate lvalue ("modifiable") context to an op and its children. |
| 16223 |
\&\f(CW\*(C`type\*(C'\fR represents the context type, roughly based on the type of op that |
| 16224 |
would do the modifying, although \f(CWlocal()\fR is represented by \f(CW\*(C`OP_NULL\*(C'\fR, |
| 16225 |
because it has no op type of its own (it is signalled by a flag on |
| 16226 |
the lvalue op). |
| 16227 |
.Sp |
| 16228 |
This function detects things that can't be modified, such as \f(CW\*(C`$x+1\*(C'\fR, and |
| 16229 |
generates errors for them. For example, \f(CW\*(C`$x+1 = 2\*(C'\fR would cause it to be |
| 16230 |
called with an op of type \f(CW\*(C`OP_ADD\*(C'\fR and a \f(CW\*(C`type\*(C'\fR argument of \f(CW\*(C`OP_SASSIGN\*(C'\fR. |
| 16231 |
.Sp |
| 16232 |
It also flags things that need to behave specially in an lvalue context, |
| 16233 |
such as \f(CW\*(C`$$x = 5\*(C'\fR which might have to vivify a reference in \f(CW$x\fR. |
| 16234 |
.RS 4 |
| 16235 |
.Sp |
| 16236 |
.Vb 1 |
| 16237 |
\& OP * op_lvalue(OP *o, I32 type) |
| 16238 |
.Ve |
| 16239 |
.RE |
| 16240 |
.RS 4 |
| 16241 |
.RE |
| 16242 |
.ie n .IP """OpMAYBESIB_set""" 4 |
| 16243 |
.el .IP \f(CWOpMAYBESIB_set\fR 4 |
| 16244 |
.IX Xref "OpMAYBESIB_set" |
| 16245 |
.IX Item "OpMAYBESIB_set" |
| 16246 |
Conditionally does \f(CW\*(C`OpMORESIB_set\*(C'\fR or \f(CW\*(C`OpLASTSIB_set\*(C'\fR depending on whether |
| 16247 |
\&\f(CW\*(C`sib\*(C'\fR is non-null. For a higher-level interface, see \f(CW"op_sibling_splice"\fR. |
| 16248 |
.RS 4 |
| 16249 |
.Sp |
| 16250 |
.Vb 1 |
| 16251 |
\& void OpMAYBESIB_set(OP *o, OP *sib, OP *parent) |
| 16252 |
.Ve |
| 16253 |
.RE |
| 16254 |
.RS 4 |
| 16255 |
.RE |
| 16256 |
.ie n .IP """OpMORESIB_set""" 4 |
| 16257 |
.el .IP \f(CWOpMORESIB_set\fR 4 |
| 16258 |
.IX Xref "OpMORESIB_set" |
| 16259 |
.IX Item "OpMORESIB_set" |
| 16260 |
Sets the sibling of \f(CW\*(C`o\*(C'\fR to the non-zero value \f(CW\*(C`sib\*(C'\fR. See also \f(CW"OpLASTSIB_set"\fR |
| 16261 |
and \f(CW"OpMAYBESIB_set"\fR. For a higher-level interface, see |
| 16262 |
\&\f(CW"op_sibling_splice"\fR. |
| 16263 |
.RS 4 |
| 16264 |
.Sp |
| 16265 |
.Vb 1 |
| 16266 |
\& void OpMORESIB_set(OP *o, OP *sib) |
| 16267 |
.Ve |
| 16268 |
.RE |
| 16269 |
.RS 4 |
| 16270 |
.RE |
| 16271 |
.ie n .IP """OP_NAME""" 4 |
| 16272 |
.el .IP \f(CWOP_NAME\fR 4 |
| 16273 |
.IX Xref "OP_NAME" |
| 16274 |
.IX Item "OP_NAME" |
| 16275 |
Return the name of the provided OP. For core ops this looks up the name |
| 16276 |
from the op_type; for custom ops from the op_ppaddr. |
| 16277 |
.RS 4 |
| 16278 |
.Sp |
| 16279 |
.Vb 1 |
| 16280 |
\& const char * OP_NAME(OP *o) |
| 16281 |
.Ve |
| 16282 |
.RE |
| 16283 |
.RS 4 |
| 16284 |
.RE |
| 16285 |
.ie n .IP """op_null""" 4 |
| 16286 |
.el .IP \f(CWop_null\fR 4 |
| 16287 |
.IX Xref "op_null" |
| 16288 |
.IX Item "op_null" |
| 16289 |
Neutralizes an op when it is no longer needed, but is still linked to from |
| 16290 |
other ops. |
| 16291 |
.RS 4 |
| 16292 |
.Sp |
| 16293 |
.Vb 1 |
| 16294 |
\& void op_null(OP *o) |
| 16295 |
.Ve |
| 16296 |
.RE |
| 16297 |
.RS 4 |
| 16298 |
.RE |
| 16299 |
.ie n .IP """op_parent""" 4 |
| 16300 |
.el .IP \f(CWop_parent\fR 4 |
| 16301 |
.IX Xref "op_parent" |
| 16302 |
.IX Item "op_parent" |
| 16303 |
Returns the parent OP of \f(CW\*(C`o\*(C'\fR, if it has a parent. Returns \f(CW\*(C`NULL\*(C'\fR otherwise. |
| 16304 |
.RS 4 |
| 16305 |
.Sp |
| 16306 |
.Vb 1 |
| 16307 |
\& OP * op_parent(OP *o) |
| 16308 |
.Ve |
| 16309 |
.RE |
| 16310 |
.RS 4 |
| 16311 |
.RE |
| 16312 |
.ie n .IP """op_prepend_elem""" 4 |
| 16313 |
.el .IP \f(CWop_prepend_elem\fR 4 |
| 16314 |
.IX Xref "op_prepend_elem" |
| 16315 |
.IX Item "op_prepend_elem" |
| 16316 |
Prepend an item to the list of ops contained directly within a list-type |
| 16317 |
op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the op to prepend to the |
| 16318 |
list, and \f(CW\*(C`last\*(C'\fR is the list-type op. \f(CW\*(C`optype\*(C'\fR specifies the intended |
| 16319 |
opcode for the list. If \f(CW\*(C`last\*(C'\fR is not already a list of the right type, |
| 16320 |
it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null, |
| 16321 |
the other is returned unchanged. |
| 16322 |
.RS 4 |
| 16323 |
.Sp |
| 16324 |
.Vb 1 |
| 16325 |
\& OP * op_prepend_elem(I32 optype, OP *first, OP *last) |
| 16326 |
.Ve |
| 16327 |
.RE |
| 16328 |
.RS 4 |
| 16329 |
.RE |
| 16330 |
.ie n .IP """op_scope""" 4 |
| 16331 |
.el .IP \f(CWop_scope\fR 4 |
| 16332 |
.IX Xref "op_scope" |
| 16333 |
.IX Item "op_scope" |
| 16334 |
NOTE: \f(CW\*(C`op_scope\*(C'\fR is \fBexperimental\fR and may change or be |
| 16335 |
removed without notice. |
| 16336 |
.Sp |
| 16337 |
Wraps up an op tree with some additional ops so that at runtime a dynamic |
| 16338 |
scope will be created. The original ops run in the new dynamic scope, |
| 16339 |
and then, provided that they exit normally, the scope will be unwound. |
| 16340 |
The additional ops used to create and unwind the dynamic scope will |
| 16341 |
normally be an \f(CW\*(C`enter\*(C'\fR/\f(CW\*(C`leave\*(C'\fR pair, but a \f(CW\*(C`scope\*(C'\fR op may be used |
| 16342 |
instead if the ops are simple enough to not need the full dynamic scope |
| 16343 |
structure. |
| 16344 |
.RS 4 |
| 16345 |
.Sp |
| 16346 |
.Vb 1 |
| 16347 |
\& OP * op_scope(OP *o) |
| 16348 |
.Ve |
| 16349 |
.RE |
| 16350 |
.RS 4 |
| 16351 |
.RE |
| 16352 |
.ie n .IP """OpSIBLING""" 4 |
| 16353 |
.el .IP \f(CWOpSIBLING\fR 4 |
| 16354 |
.IX Xref "OpSIBLING" |
| 16355 |
.IX Item "OpSIBLING" |
| 16356 |
Returns the sibling of \f(CW\*(C`o\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if there is no sibling |
| 16357 |
.RS 4 |
| 16358 |
.Sp |
| 16359 |
.Vb 1 |
| 16360 |
\& OP* OpSIBLING(OP *o) |
| 16361 |
.Ve |
| 16362 |
.RE |
| 16363 |
.RS 4 |
| 16364 |
.RE |
| 16365 |
.ie n .IP """op_sibling_splice""" 4 |
| 16366 |
.el .IP \f(CWop_sibling_splice\fR 4 |
| 16367 |
.IX Xref "op_sibling_splice" |
| 16368 |
.IX Item "op_sibling_splice" |
| 16369 |
A general function for editing the structure of an existing chain of |
| 16370 |
op_sibling nodes. By analogy with the perl-level \f(CWsplice()\fR function, allows |
| 16371 |
you to delete zero or more sequential nodes, replacing them with zero or |
| 16372 |
more different nodes. Performs the necessary op_first/op_last |
| 16373 |
housekeeping on the parent node and op_sibling manipulation on the |
| 16374 |
children. The last deleted node will be marked as the last node by |
| 16375 |
updating the op_sibling/op_sibparent or op_moresib field as appropriate. |
| 16376 |
.Sp |
| 16377 |
Note that op_next is not manipulated, and nodes are not freed; that is the |
| 16378 |
responsibility of the caller. It also won't create a new list op for an |
| 16379 |
empty list etc; use higher-level functions like \fBop_append_elem()\fR for that. |
| 16380 |
.Sp |
| 16381 |
\&\f(CW\*(C`parent\*(C'\fR is the parent node of the sibling chain. It may passed as \f(CW\*(C`NULL\*(C'\fR if |
| 16382 |
the splicing doesn't affect the first or last op in the chain. |
| 16383 |
.Sp |
| 16384 |
\&\f(CW\*(C`start\*(C'\fR is the node preceding the first node to be spliced. Node(s) |
| 16385 |
following it will be deleted, and ops will be inserted after it. If it is |
| 16386 |
\&\f(CW\*(C`NULL\*(C'\fR, the first node onwards is deleted, and nodes are inserted at the |
| 16387 |
beginning. |
| 16388 |
.Sp |
| 16389 |
\&\f(CW\*(C`del_count\*(C'\fR is the number of nodes to delete. If zero, no nodes are deleted. |
| 16390 |
If \-1 or greater than or equal to the number of remaining kids, all |
| 16391 |
remaining kids are deleted. |
| 16392 |
.Sp |
| 16393 |
\&\f(CW\*(C`insert\*(C'\fR is the first of a chain of nodes to be inserted in place of the nodes. |
| 16394 |
If \f(CW\*(C`NULL\*(C'\fR, no nodes are inserted. |
| 16395 |
.Sp |
| 16396 |
The head of the chain of deleted ops is returned, or \f(CW\*(C`NULL\*(C'\fR if no ops were |
| 16397 |
deleted. |
| 16398 |
.Sp |
| 16399 |
For example: |
| 16400 |
.Sp |
| 16401 |
.Vb 2 |
| 16402 |
\& action before after returns |
| 16403 |
\& \-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\- |
| 16404 |
\& |
| 16405 |
\& P P |
| 16406 |
\& splice(P, A, 2, X\-Y\-Z) | | B\-C |
| 16407 |
\& A\-B\-C\-D A\-X\-Y\-Z\-D |
| 16408 |
\& |
| 16409 |
\& P P |
| 16410 |
\& splice(P, NULL, 1, X\-Y) | | A |
| 16411 |
\& A\-B\-C\-D X\-Y\-B\-C\-D |
| 16412 |
\& |
| 16413 |
\& P P |
| 16414 |
\& splice(P, NULL, 3, NULL) | | A\-B\-C |
| 16415 |
\& A\-B\-C\-D D |
| 16416 |
\& |
| 16417 |
\& P P |
| 16418 |
\& splice(P, B, 0, X\-Y) | | NULL |
| 16419 |
\& A\-B\-C\-D A\-B\-X\-Y\-C\-D |
| 16420 |
.Ve |
| 16421 |
.Sp |
| 16422 |
For lower-level direct manipulation of \f(CW\*(C`op_sibparent\*(C'\fR and \f(CW\*(C`op_moresib\*(C'\fR, |
| 16423 |
see \f(CW"OpMORESIB_set"\fR, \f(CW"OpLASTSIB_set"\fR, \f(CW"OpMAYBESIB_set"\fR. |
| 16424 |
.RS 4 |
| 16425 |
.Sp |
| 16426 |
.Vb 2 |
| 16427 |
\& OP * op_sibling_splice(OP *parent, OP *start, int del_count, |
| 16428 |
\& OP *insert) |
| 16429 |
.Ve |
| 16430 |
.RE |
| 16431 |
.RS 4 |
| 16432 |
.RE |
| 16433 |
.ie n .IP """optimize_optree""" 4 |
| 16434 |
.el .IP \f(CWoptimize_optree\fR 4 |
| 16435 |
.IX Xref "optimize_optree" |
| 16436 |
.IX Item "optimize_optree" |
| 16437 |
This function applies some optimisations to the optree in top-down order. |
| 16438 |
It is called before the peephole optimizer, which processes ops in |
| 16439 |
execution order. Note that \fBfinalize_optree()\fR also does a top-down scan, |
| 16440 |
but is called *after* the peephole optimizer. |
| 16441 |
.RS 4 |
| 16442 |
.Sp |
| 16443 |
.Vb 1 |
| 16444 |
\& void optimize_optree(OP *o) |
| 16445 |
.Ve |
| 16446 |
.RE |
| 16447 |
.RS 4 |
| 16448 |
.RE |
| 16449 |
.ie n .IP """OP_TYPE_IS""" 4 |
| 16450 |
.el .IP \f(CWOP_TYPE_IS\fR 4 |
| 16451 |
.IX Xref "OP_TYPE_IS" |
| 16452 |
.IX Item "OP_TYPE_IS" |
| 16453 |
Returns true if the given OP is not a \f(CW\*(C`NULL\*(C'\fR pointer |
| 16454 |
and if it is of the given type. |
| 16455 |
.Sp |
| 16456 |
The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT\*(C'\fR is also available |
| 16457 |
as well as \f(CW\*(C`OP_TYPE_IS_NN\*(C'\fR and \f(CW\*(C`OP_TYPE_ISNT_NN\*(C'\fR which elide |
| 16458 |
the NULL pointer check. |
| 16459 |
.RS 4 |
| 16460 |
.Sp |
| 16461 |
.Vb 1 |
| 16462 |
\& bool OP_TYPE_IS(OP *o, Optype type) |
| 16463 |
.Ve |
| 16464 |
.RE |
| 16465 |
.RS 4 |
| 16466 |
.RE |
| 16467 |
.ie n .IP """OP_TYPE_IS_OR_WAS""" 4 |
| 16468 |
.el .IP \f(CWOP_TYPE_IS_OR_WAS\fR 4 |
| 16469 |
.IX Xref "OP_TYPE_IS_OR_WAS" |
| 16470 |
.IX Item "OP_TYPE_IS_OR_WAS" |
| 16471 |
Returns true if the given OP is not a NULL pointer and |
| 16472 |
if it is of the given type or used to be before being |
| 16473 |
replaced by an OP of type OP_NULL. |
| 16474 |
.Sp |
| 16475 |
The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT\*(C'\fR |
| 16476 |
is also available as well as \f(CW\*(C`OP_TYPE_IS_OR_WAS_NN\*(C'\fR |
| 16477 |
and \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT_NN\*(C'\fR which elide |
| 16478 |
the \f(CW\*(C`NULL\*(C'\fR pointer check. |
| 16479 |
.RS 4 |
| 16480 |
.Sp |
| 16481 |
.Vb 1 |
| 16482 |
\& bool OP_TYPE_IS_OR_WAS(OP *o, Optype type) |
| 16483 |
.Ve |
| 16484 |
.RE |
| 16485 |
.RS 4 |
| 16486 |
.RE |
| 16487 |
.ie n .IP """op_wrap_finally""" 4 |
| 16488 |
.el .IP \f(CWop_wrap_finally\fR 4 |
| 16489 |
.IX Xref "op_wrap_finally" |
| 16490 |
.IX Item "op_wrap_finally" |
| 16491 |
NOTE: \f(CW\*(C`op_wrap_finally\*(C'\fR is \fBexperimental\fR and may change or be |
| 16492 |
removed without notice. |
| 16493 |
.Sp |
| 16494 |
Wraps the given \f(CW\*(C`block\*(C'\fR optree fragment in its own scoped block, arranging |
| 16495 |
for the \f(CW\*(C`finally\*(C'\fR optree fragment to be invoked when leaving that block for |
| 16496 |
any reason. Both optree fragments are consumed and the combined result is |
| 16497 |
returned. |
| 16498 |
.RS 4 |
| 16499 |
.Sp |
| 16500 |
.Vb 1 |
| 16501 |
\& OP * op_wrap_finally(OP *block, OP *finally) |
| 16502 |
.Ve |
| 16503 |
.RE |
| 16504 |
.RS 4 |
| 16505 |
.RE |
| 16506 |
.ie n .IP """peep_t""" 4 |
| 16507 |
.el .IP \f(CWpeep_t\fR 4 |
| 16508 |
.IX Item "peep_t" |
| 16509 |
Described in perlguts. |
| 16510 |
.ie n .IP """Perl_cpeep_t""" 4 |
| 16511 |
.el .IP \f(CWPerl_cpeep_t\fR 4 |
| 16512 |
.IX Item "Perl_cpeep_t" |
| 16513 |
Described in perlguts. |
| 16514 |
.ie n .IP """PL_opfreehook""" 4 |
| 16515 |
.el .IP \f(CWPL_opfreehook\fR 4 |
| 16516 |
.IX Xref "PL_opfreehook" |
| 16517 |
.IX Item "PL_opfreehook" |
| 16518 |
When non\-\f(CW\*(C`NULL\*(C'\fR, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument. |
| 16519 |
This allows extensions to free any extra attribute they have locally attached to an OP. |
| 16520 |
It is also assured to first fire for the parent OP and then for its kids. |
| 16521 |
.Sp |
| 16522 |
When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own. |
| 16523 |
.Sp |
| 16524 |
On threaded perls, each thread has an independent copy of this variable; |
| 16525 |
each initialized at creation time with the current value of the creating |
| 16526 |
thread's copy. |
| 16527 |
.RS 4 |
| 16528 |
.Sp |
| 16529 |
.Vb 1 |
| 16530 |
\& Perl_ophook_t PL_opfreehook |
| 16531 |
.Ve |
| 16532 |
.RE |
| 16533 |
.RS 4 |
| 16534 |
.RE |
| 16535 |
.ie n .IP """PL_peepp""" 4 |
| 16536 |
.el .IP \f(CWPL_peepp\fR 4 |
| 16537 |
.IX Xref "PL_peepp" |
| 16538 |
.IX Item "PL_peepp" |
| 16539 |
Pointer to the per-subroutine peephole optimiser. This is a function |
| 16540 |
that gets called at the end of compilation of a Perl subroutine (or |
| 16541 |
equivalently independent piece of Perl code) to perform fixups of |
| 16542 |
some ops and to perform small-scale optimisations. The function is |
| 16543 |
called once for each subroutine that is compiled, and is passed, as sole |
| 16544 |
parameter, a pointer to the op that is the entry point to the subroutine. |
| 16545 |
It modifies the op tree in place. |
| 16546 |
.Sp |
| 16547 |
The peephole optimiser should never be completely replaced. Rather, |
| 16548 |
add code to it by wrapping the existing optimiser. The basic way to do |
| 16549 |
this can be seen in "Compile pass 3: peephole optimization" in perlguts. |
| 16550 |
If the new code wishes to operate on ops throughout the subroutine's |
| 16551 |
structure, rather than just at the top level, it is likely to be more |
| 16552 |
convenient to wrap the "PL_rpeepp" hook. |
| 16553 |
.Sp |
| 16554 |
On threaded perls, each thread has an independent copy of this variable; |
| 16555 |
each initialized at creation time with the current value of the creating |
| 16556 |
thread's copy. |
| 16557 |
.RS 4 |
| 16558 |
.Sp |
| 16559 |
.Vb 1 |
| 16560 |
\& peep_t PL_peepp |
| 16561 |
.Ve |
| 16562 |
.RE |
| 16563 |
.RS 4 |
| 16564 |
.RE |
| 16565 |
.ie n .IP """PL_rpeepp""" 4 |
| 16566 |
.el .IP \f(CWPL_rpeepp\fR 4 |
| 16567 |
.IX Xref "PL_rpeepp" |
| 16568 |
.IX Item "PL_rpeepp" |
| 16569 |
Pointer to the recursive peephole optimiser. This is a function |
| 16570 |
that gets called at the end of compilation of a Perl subroutine (or |
| 16571 |
equivalently independent piece of Perl code) to perform fixups of some |
| 16572 |
ops and to perform small-scale optimisations. The function is called |
| 16573 |
once for each chain of ops linked through their \f(CW\*(C`op_next\*(C'\fR fields; |
| 16574 |
it is recursively called to handle each side chain. It is passed, as |
| 16575 |
sole parameter, a pointer to the op that is at the head of the chain. |
| 16576 |
It modifies the op tree in place. |
| 16577 |
.Sp |
| 16578 |
The peephole optimiser should never be completely replaced. Rather, |
| 16579 |
add code to it by wrapping the existing optimiser. The basic way to do |
| 16580 |
this can be seen in "Compile pass 3: peephole optimization" in perlguts. |
| 16581 |
If the new code wishes to operate only on ops at a subroutine's top level, |
| 16582 |
rather than throughout the structure, it is likely to be more convenient |
| 16583 |
to wrap the "PL_peepp" hook. |
| 16584 |
.Sp |
| 16585 |
On threaded perls, each thread has an independent copy of this variable; |
| 16586 |
each initialized at creation time with the current value of the creating |
| 16587 |
thread's copy. |
| 16588 |
.RS 4 |
| 16589 |
.Sp |
| 16590 |
.Vb 1 |
| 16591 |
\& peep_t PL_rpeepp |
| 16592 |
.Ve |
| 16593 |
.RE |
| 16594 |
.RS 4 |
| 16595 |
.RE |
| 16596 |
.ie n .IP """PMOP""" 4 |
| 16597 |
.el .IP \f(CWPMOP\fR 4 |
| 16598 |
.IX Item "PMOP" |
| 16599 |
Described in perlguts. |
| 16600 |
.ie n .IP """rv2cv_op_cv""" 4 |
| 16601 |
.el .IP \f(CWrv2cv_op_cv\fR 4 |
| 16602 |
.IX Xref "rv2cv_op_cv" |
| 16603 |
.IX Item "rv2cv_op_cv" |
| 16604 |
Examines an op, which is expected to identify a subroutine at runtime, |
| 16605 |
and attempts to determine at compile time which subroutine it identifies. |
| 16606 |
This is normally used during Perl compilation to determine whether |
| 16607 |
a prototype can be applied to a function call. \f(CW\*(C`cvop\*(C'\fR is the op |
| 16608 |
being considered, normally an \f(CW\*(C`rv2cv\*(C'\fR op. A pointer to the identified |
| 16609 |
subroutine is returned, if it could be determined statically, and a null |
| 16610 |
pointer is returned if it was not possible to determine statically. |
| 16611 |
.Sp |
| 16612 |
Currently, the subroutine can be identified statically if the RV that the |
| 16613 |
\&\f(CW\*(C`rv2cv\*(C'\fR is to operate on is provided by a suitable \f(CW\*(C`gv\*(C'\fR or \f(CW\*(C`const\*(C'\fR op. |
| 16614 |
A \f(CW\*(C`gv\*(C'\fR op is suitable if the GV's CV slot is populated. A \f(CW\*(C`const\*(C'\fR op is |
| 16615 |
suitable if the constant value must be an RV pointing to a CV. Details of |
| 16616 |
this process may change in future versions of Perl. If the \f(CW\*(C`rv2cv\*(C'\fR op |
| 16617 |
has the \f(CW\*(C`OPpENTERSUB_AMPER\*(C'\fR flag set then no attempt is made to identify |
| 16618 |
the subroutine statically: this flag is used to suppress compile-time |
| 16619 |
magic on a subroutine call, forcing it to use default runtime behaviour. |
| 16620 |
.Sp |
| 16621 |
If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_MARK_EARLY\*(C'\fR set, then the handling |
| 16622 |
of a GV reference is modified. If a GV was examined and its CV slot was |
| 16623 |
found to be empty, then the \f(CW\*(C`gv\*(C'\fR op has the \f(CW\*(C`OPpEARLY_CV\*(C'\fR flag set. |
| 16624 |
If the op is not optimised away, and the CV slot is later populated with |
| 16625 |
a subroutine having a prototype, that flag eventually triggers the warning |
| 16626 |
"called too early to check prototype". |
| 16627 |
.Sp |
| 16628 |
If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_RETURN_NAME_GV\*(C'\fR set, then instead |
| 16629 |
of returning a pointer to the subroutine it returns a pointer to the |
| 16630 |
GV giving the most appropriate name for the subroutine in this context. |
| 16631 |
Normally this is just the \f(CW\*(C`CvGV\*(C'\fR of the subroutine, but for an anonymous |
| 16632 |
(\f(CW\*(C`CvANON\*(C'\fR) subroutine that is referenced through a GV it will be the |
| 16633 |
referencing GV. The resulting \f(CW\*(C`GV*\*(C'\fR is cast to \f(CW\*(C`CV*\*(C'\fR to be returned. |
| 16634 |
A null pointer is returned as usual if there is no statically-determinable |
| 16635 |
subroutine. |
| 16636 |
.RS 4 |
| 16637 |
.Sp |
| 16638 |
.Vb 1 |
| 16639 |
\& CV * rv2cv_op_cv(OP *cvop, U32 flags) |
| 16640 |
.Ve |
| 16641 |
.RE |
| 16642 |
.RS 4 |
| 16643 |
.RE |
| 16644 |
.ie n .IP """UNOP""" 4 |
| 16645 |
.el .IP \f(CWUNOP\fR 4 |
| 16646 |
.IX Item "UNOP" |
| 16647 |
Described in perlguts. |
| 16648 |
.ie n .IP """XOP""" 4 |
| 16649 |
.el .IP \f(CWXOP\fR 4 |
| 16650 |
.IX Item "XOP" |
| 16651 |
Described in perlguts. |
| 16652 |
.SH "Pack and Unpack" |
| 16653 |
.IX Header "Pack and Unpack" |
| 16654 |
.ie n .IP """packlist""" 4 |
| 16655 |
.el .IP \f(CWpacklist\fR 4 |
| 16656 |
.IX Xref "packlist" |
| 16657 |
.IX Item "packlist" |
| 16658 |
The engine implementing \f(CWpack()\fR Perl function. |
| 16659 |
.RS 4 |
| 16660 |
.Sp |
| 16661 |
.Vb 2 |
| 16662 |
\& void packlist(SV *cat, const char *pat, const char *patend, |
| 16663 |
\& SV **beglist, SV **endlist) |
| 16664 |
.Ve |
| 16665 |
.RE |
| 16666 |
.RS 4 |
| 16667 |
.RE |
| 16668 |
.ie n .IP """unpackstring""" 4 |
| 16669 |
.el .IP \f(CWunpackstring\fR 4 |
| 16670 |
.IX Xref "unpackstring" |
| 16671 |
.IX Item "unpackstring" |
| 16672 |
The engine implementing the \f(CWunpack()\fR Perl function. |
| 16673 |
.Sp |
| 16674 |
Using the template \f(CW\*(C`pat..patend\*(C'\fR, this function unpacks the string |
| 16675 |
\&\f(CW\*(C`s..strend\*(C'\fR into a number of mortal SVs, which it pushes onto the perl |
| 16676 |
argument (\f(CW@_\fR) stack (so you will need to issue a \f(CW\*(C`PUTBACK\*(C'\fR before and |
| 16677 |
\&\f(CW\*(C`SPAGAIN\*(C'\fR after the call to this function). It returns the number of |
| 16678 |
pushed elements. |
| 16679 |
.Sp |
| 16680 |
The \f(CW\*(C`strend\*(C'\fR and \f(CW\*(C`patend\*(C'\fR pointers should point to the byte following the |
| 16681 |
last character of each string. |
| 16682 |
.Sp |
| 16683 |
Although this function returns its values on the perl argument stack, it |
| 16684 |
doesn't take any parameters from that stack (and thus in particular |
| 16685 |
there's no need to do a \f(CW\*(C`PUSHMARK\*(C'\fR before calling it, unlike "call_pv" for |
| 16686 |
example). |
| 16687 |
.RS 4 |
| 16688 |
.Sp |
| 16689 |
.Vb 3 |
| 16690 |
\& SSize_t unpackstring(const char *pat, const char *patend, |
| 16691 |
\& const char *s, const char *strend, |
| 16692 |
\& U32 flags) |
| 16693 |
.Ve |
| 16694 |
.RE |
| 16695 |
.RS 4 |
| 16696 |
.RE |
| 16697 |
.SH "Pad Data Structures" |
| 16698 |
.IX Xref "SVs_PADSTALE" |
| 16699 |
.IX Header "Pad Data Structures" |
| 16700 |
.ie n .IP """CvPADLIST""" 4 |
| 16701 |
.el .IP \f(CWCvPADLIST\fR 4 |
| 16702 |
.IX Xref "CvPADLIST" |
| 16703 |
.IX Item "CvPADLIST" |
| 16704 |
NOTE: \f(CW\*(C`CvPADLIST\*(C'\fR is \fBexperimental\fR and may change or be |
| 16705 |
removed without notice. |
| 16706 |
.Sp |
| 16707 |
CV's can have CvPADLIST(cv) set to point to a PADLIST. This is the CV's |
| 16708 |
scratchpad, which stores lexical variables and opcode temporary and |
| 16709 |
per-thread values. |
| 16710 |
.Sp |
| 16711 |
For these purposes "formats" are a kind-of CV; eval""s are too (except they're |
| 16712 |
not callable at will and are always thrown away after the eval"" is done |
| 16713 |
executing). Require'd files are simply evals without any outer lexical |
| 16714 |
scope. |
| 16715 |
.Sp |
| 16716 |
XSUBs do not have a \f(CW\*(C`CvPADLIST\*(C'\fR. \f(CW\*(C`dXSTARG\*(C'\fR fetches values from \f(CW\*(C`PL_curpad\*(C'\fR, |
| 16717 |
but that is really the callers pad (a slot of which is allocated by |
| 16718 |
every entersub). Do not get or set \f(CW\*(C`CvPADLIST\*(C'\fR if a CV is an XSUB (as |
| 16719 |
determined by \f(CWCvISXSUB()\fR), \f(CW\*(C`CvPADLIST\*(C'\fR slot is reused for a different |
| 16720 |
internal purpose in XSUBs. |
| 16721 |
.Sp |
| 16722 |
The PADLIST has a C array where pads are stored. |
| 16723 |
.Sp |
| 16724 |
The 0th entry of the PADLIST is a PADNAMELIST |
| 16725 |
which represents the "names" or rather |
| 16726 |
the "static type information" for lexicals. The individual elements of a |
| 16727 |
PADNAMELIST are PADNAMEs. Future |
| 16728 |
refactorings might stop the PADNAMELIST from being stored in the PADLIST's |
| 16729 |
array, so don't rely on it. See "PadlistNAMES". |
| 16730 |
.Sp |
| 16731 |
The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the stack frame |
| 16732 |
at that depth of recursion into the CV. The 0th slot of a frame AV is an |
| 16733 |
AV which is \f(CW@_\fR. Other entries are storage for variables and op targets. |
| 16734 |
.Sp |
| 16735 |
Iterating over the PADNAMELIST iterates over all possible pad |
| 16736 |
items. Pad slots for targets (\f(CW\*(C`SVs_PADTMP\*(C'\fR) |
| 16737 |
and GVs end up having &PL_padname_undef "names", while slots for constants |
| 16738 |
have \f(CW&PL_padname_const\fR "names" (see \f(CW"pad_alloc"\fR). That |
| 16739 |
\&\f(CW&PL_padname_undef\fR |
| 16740 |
and \f(CW&PL_padname_const\fR are used is an implementation detail subject to |
| 16741 |
change. To test for them, use \f(CW\*(C`!PadnamePV(name)\*(C'\fR and |
| 16742 |
\&\f(CW\*(C`PadnamePV(name)\ &&\ !PadnameLEN(name)\*(C'\fR, respectively. |
| 16743 |
.Sp |
| 16744 |
Only \f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variable slots get valid names. |
| 16745 |
The rest are op targets/GVs/constants which are statically allocated |
| 16746 |
or resolved at compile time. These don't have names by which they |
| 16747 |
can be looked up from Perl code at run time through eval"" the way |
| 16748 |
\&\f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variables can be. Since they can't be looked up by "name" |
| 16749 |
but only by their index allocated at compile time (which is usually |
| 16750 |
in \f(CW\*(C`PL_op\->op_targ\*(C'\fR), wasting a name SV for them doesn't make sense. |
| 16751 |
.Sp |
| 16752 |
The pad names in the PADNAMELIST have their PV holding the name of |
| 16753 |
the variable. The \f(CW\*(C`COP_SEQ_RANGE_LOW\*(C'\fR and \f(CW\*(C`_HIGH\*(C'\fR fields form a range |
| 16754 |
(low+1..high inclusive) of cop_seq numbers for which the name is |
| 16755 |
valid. During compilation, these fields may hold the special value |
| 16756 |
PERL_PADSEQ_INTRO to indicate various stages: |
| 16757 |
.Sp |
| 16758 |
.Vb 8 |
| 16759 |
\& COP_SEQ_RANGE_LOW _HIGH |
| 16760 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\- |
| 16761 |
\& PERL_PADSEQ_INTRO 0 variable not yet introduced: |
| 16762 |
\& { my ($x |
| 16763 |
\& valid\-seq# PERL_PADSEQ_INTRO variable in scope: |
| 16764 |
\& { my ($x); |
| 16765 |
\& valid\-seq# valid\-seq# compilation of scope complete: |
| 16766 |
\& { my ($x); .... } |
| 16767 |
.Ve |
| 16768 |
.Sp |
| 16769 |
When a lexical var hasn't yet been introduced, it already exists from the |
| 16770 |
perspective of duplicate declarations, but not for variable lookups, e.g. |
| 16771 |
.Sp |
| 16772 |
.Vb 2 |
| 16773 |
\& my ($x, $x); # \*(Aq"my" variable $x masks earlier declaration\*(Aq |
| 16774 |
\& my $x = $x; # equal to my $x = $::x; |
| 16775 |
.Ve |
| 16776 |
.Sp |
| 16777 |
For typed lexicals \f(CW\*(C`PadnameTYPE\*(C'\fR points at the type stash. For \f(CW\*(C`our\*(C'\fR |
| 16778 |
lexicals, \f(CW\*(C`PadnameOURSTASH\*(C'\fR points at the stash of the associated global (so |
| 16779 |
that duplicate \f(CW\*(C`our\*(C'\fR declarations in the same package can be detected). |
| 16780 |
\&\f(CW\*(C`PadnameGEN\*(C'\fR is sometimes used to store the generation number during |
| 16781 |
compilation. |
| 16782 |
.Sp |
| 16783 |
If \f(CW\*(C`PadnameOUTER\*(C'\fR is set on the pad name, then that slot in the frame AV |
| 16784 |
is a REFCNT'ed reference to a lexical from "outside". Such entries |
| 16785 |
are sometimes referred to as 'fake'. In this case, the name does not |
| 16786 |
use 'low' and 'high' to store a cop_seq range, since it is in scope |
| 16787 |
throughout. Instead 'high' stores some flags containing info about |
| 16788 |
the real lexical (is it declared in an anon, and is it capable of being |
| 16789 |
instantiated multiple times?), and for fake ANONs, 'low' contains the index |
| 16790 |
within the parent's pad where the lexical's value is stored, to make |
| 16791 |
cloning quicker. |
| 16792 |
.Sp |
| 16793 |
If the 'name' is \f(CW\*(C`&\*(C'\fR the corresponding entry in the PAD |
| 16794 |
is a CV representing a possible closure. |
| 16795 |
.Sp |
| 16796 |
Note that formats are treated as anon subs, and are cloned each time |
| 16797 |
write is called (if necessary). |
| 16798 |
.Sp |
| 16799 |
The flag \f(CW\*(C`SVs_PADSTALE\*(C'\fR is cleared on lexicals each time the \f(CWmy()\fR is executed, |
| 16800 |
and set on scope exit. This allows the |
| 16801 |
\&\f(CW"Variable $x is not available"\fR warning |
| 16802 |
to be generated in evals, such as |
| 16803 |
.Sp |
| 16804 |
.Vb 1 |
| 16805 |
\& { my $x = 1; sub f { eval \*(Aq$x\*(Aq} } f(); |
| 16806 |
.Ve |
| 16807 |
.Sp |
| 16808 |
For state vars, \f(CW\*(C`SVs_PADSTALE\*(C'\fR is overloaded to mean 'not yet initialised', |
| 16809 |
but this internal state is stored in a separate pad entry. |
| 16810 |
.RS 4 |
| 16811 |
.Sp |
| 16812 |
.Vb 1 |
| 16813 |
\& PADLIST * CvPADLIST(CV *cv) |
| 16814 |
.Ve |
| 16815 |
.RE |
| 16816 |
.RS 4 |
| 16817 |
.RE |
| 16818 |
.ie n .IP """pad_add_name_pvs""" 4 |
| 16819 |
.el .IP \f(CWpad_add_name_pvs\fR 4 |
| 16820 |
.IX Xref "pad_add_name_pvs" |
| 16821 |
.IX Item "pad_add_name_pvs" |
| 16822 |
Exactly like "pad_add_name_pvn", but takes a literal string |
| 16823 |
instead of a string/length pair. |
| 16824 |
.RS 4 |
| 16825 |
.Sp |
| 16826 |
.Vb 2 |
| 16827 |
\& PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash, |
| 16828 |
\& HV *ourstash) |
| 16829 |
.Ve |
| 16830 |
.RE |
| 16831 |
.RS 4 |
| 16832 |
.RE |
| 16833 |
.ie n .IP """PadARRAY""" 4 |
| 16834 |
.el .IP \f(CWPadARRAY\fR 4 |
| 16835 |
.IX Xref "PadARRAY" |
| 16836 |
.IX Item "PadARRAY" |
| 16837 |
NOTE: \f(CW\*(C`PadARRAY\*(C'\fR is \fBexperimental\fR and may change or be |
| 16838 |
removed without notice. |
| 16839 |
.Sp |
| 16840 |
The C array of pad entries. |
| 16841 |
.RS 4 |
| 16842 |
.Sp |
| 16843 |
.Vb 1 |
| 16844 |
\& SV ** PadARRAY(PAD * pad) |
| 16845 |
.Ve |
| 16846 |
.RE |
| 16847 |
.RS 4 |
| 16848 |
.RE |
| 16849 |
.ie n .IP """pad_findmy_pvs""" 4 |
| 16850 |
.el .IP \f(CWpad_findmy_pvs\fR 4 |
| 16851 |
.IX Xref "pad_findmy_pvs" |
| 16852 |
.IX Item "pad_findmy_pvs" |
| 16853 |
Exactly like "pad_findmy_pvn", but takes a literal string |
| 16854 |
instead of a string/length pair. |
| 16855 |
.RS 4 |
| 16856 |
.Sp |
| 16857 |
.Vb 1 |
| 16858 |
\& PADOFFSET pad_findmy_pvs("name", U32 flags) |
| 16859 |
.Ve |
| 16860 |
.RE |
| 16861 |
.RS 4 |
| 16862 |
.RE |
| 16863 |
.ie n .IP """PadlistARRAY""" 4 |
| 16864 |
.el .IP \f(CWPadlistARRAY\fR 4 |
| 16865 |
.IX Xref "PadlistARRAY" |
| 16866 |
.IX Item "PadlistARRAY" |
| 16867 |
NOTE: \f(CW\*(C`PadlistARRAY\*(C'\fR is \fBexperimental\fR and may change or be |
| 16868 |
removed without notice. |
| 16869 |
.Sp |
| 16870 |
The C array of a padlist, containing the pads. Only subscript it with |
| 16871 |
numbers >= 1, as the 0th entry is not guaranteed to remain usable. |
| 16872 |
.RS 4 |
| 16873 |
.Sp |
| 16874 |
.Vb 1 |
| 16875 |
\& PAD ** PadlistARRAY(PADLIST * padlist) |
| 16876 |
.Ve |
| 16877 |
.RE |
| 16878 |
.RS 4 |
| 16879 |
.RE |
| 16880 |
.ie n .IP """PadlistMAX""" 4 |
| 16881 |
.el .IP \f(CWPadlistMAX\fR 4 |
| 16882 |
.IX Xref "PadlistMAX" |
| 16883 |
.IX Item "PadlistMAX" |
| 16884 |
NOTE: \f(CW\*(C`PadlistMAX\*(C'\fR is \fBexperimental\fR and may change or be |
| 16885 |
removed without notice. |
| 16886 |
.Sp |
| 16887 |
The index of the last allocated space in the padlist. Note that the last |
| 16888 |
pad may be in an earlier slot. Any entries following it will be \f(CW\*(C`NULL\*(C'\fR in |
| 16889 |
that case. |
| 16890 |
.RS 4 |
| 16891 |
.Sp |
| 16892 |
.Vb 1 |
| 16893 |
\& SSize_t PadlistMAX(PADLIST * padlist) |
| 16894 |
.Ve |
| 16895 |
.RE |
| 16896 |
.RS 4 |
| 16897 |
.RE |
| 16898 |
.ie n .IP """PadlistNAMES""" 4 |
| 16899 |
.el .IP \f(CWPadlistNAMES\fR 4 |
| 16900 |
.IX Xref "PadlistNAMES" |
| 16901 |
.IX Item "PadlistNAMES" |
| 16902 |
NOTE: \f(CW\*(C`PadlistNAMES\*(C'\fR is \fBexperimental\fR and may change or be |
| 16903 |
removed without notice. |
| 16904 |
.Sp |
| 16905 |
The names associated with pad entries. |
| 16906 |
.RS 4 |
| 16907 |
.Sp |
| 16908 |
.Vb 1 |
| 16909 |
\& PADNAMELIST * PadlistNAMES(PADLIST * padlist) |
| 16910 |
.Ve |
| 16911 |
.RE |
| 16912 |
.RS 4 |
| 16913 |
.RE |
| 16914 |
.ie n .IP """PadlistNAMESARRAY""" 4 |
| 16915 |
.el .IP \f(CWPadlistNAMESARRAY\fR 4 |
| 16916 |
.IX Xref "PadlistNAMESARRAY" |
| 16917 |
.IX Item "PadlistNAMESARRAY" |
| 16918 |
NOTE: \f(CW\*(C`PadlistNAMESARRAY\*(C'\fR is \fBexperimental\fR and may change or be |
| 16919 |
removed without notice. |
| 16920 |
.Sp |
| 16921 |
The C array of pad names. |
| 16922 |
.RS 4 |
| 16923 |
.Sp |
| 16924 |
.Vb 1 |
| 16925 |
\& PADNAME ** PadlistNAMESARRAY(PADLIST * padlist) |
| 16926 |
.Ve |
| 16927 |
.RE |
| 16928 |
.RS 4 |
| 16929 |
.RE |
| 16930 |
.ie n .IP """PadlistNAMESMAX""" 4 |
| 16931 |
.el .IP \f(CWPadlistNAMESMAX\fR 4 |
| 16932 |
.IX Xref "PadlistNAMESMAX" |
| 16933 |
.IX Item "PadlistNAMESMAX" |
| 16934 |
NOTE: \f(CW\*(C`PadlistNAMESMAX\*(C'\fR is \fBexperimental\fR and may change or be |
| 16935 |
removed without notice. |
| 16936 |
.Sp |
| 16937 |
The index of the last pad name. |
| 16938 |
.RS 4 |
| 16939 |
.Sp |
| 16940 |
.Vb 1 |
| 16941 |
\& SSize_t PadlistNAMESMAX(PADLIST * padlist) |
| 16942 |
.Ve |
| 16943 |
.RE |
| 16944 |
.RS 4 |
| 16945 |
.RE |
| 16946 |
.ie n .IP """PadlistREFCNT""" 4 |
| 16947 |
.el .IP \f(CWPadlistREFCNT\fR 4 |
| 16948 |
.IX Xref "PadlistREFCNT" |
| 16949 |
.IX Item "PadlistREFCNT" |
| 16950 |
NOTE: \f(CW\*(C`PadlistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be |
| 16951 |
removed without notice. |
| 16952 |
.Sp |
| 16953 |
The reference count of the padlist. Currently this is always 1. |
| 16954 |
.RS 4 |
| 16955 |
.Sp |
| 16956 |
.Vb 1 |
| 16957 |
\& U32 PadlistREFCNT(PADLIST * padlist) |
| 16958 |
.Ve |
| 16959 |
.RE |
| 16960 |
.RS 4 |
| 16961 |
.RE |
| 16962 |
.ie n .IP """PadMAX""" 4 |
| 16963 |
.el .IP \f(CWPadMAX\fR 4 |
| 16964 |
.IX Xref "PadMAX" |
| 16965 |
.IX Item "PadMAX" |
| 16966 |
NOTE: \f(CW\*(C`PadMAX\*(C'\fR is \fBexperimental\fR and may change or be |
| 16967 |
removed without notice. |
| 16968 |
.Sp |
| 16969 |
The index of the last pad entry. |
| 16970 |
.RS 4 |
| 16971 |
.Sp |
| 16972 |
.Vb 1 |
| 16973 |
\& SSize_t PadMAX(PAD * pad) |
| 16974 |
.Ve |
| 16975 |
.RE |
| 16976 |
.RS 4 |
| 16977 |
.RE |
| 16978 |
.ie n .IP """PadnameLEN""" 4 |
| 16979 |
.el .IP \f(CWPadnameLEN\fR 4 |
| 16980 |
.IX Xref "PadnameLEN" |
| 16981 |
.IX Item "PadnameLEN" |
| 16982 |
NOTE: \f(CW\*(C`PadnameLEN\*(C'\fR is \fBexperimental\fR and may change or be |
| 16983 |
removed without notice. |
| 16984 |
.Sp |
| 16985 |
The length of the name. |
| 16986 |
.RS 4 |
| 16987 |
.Sp |
| 16988 |
.Vb 1 |
| 16989 |
\& STRLEN PadnameLEN(PADNAME * pn) |
| 16990 |
.Ve |
| 16991 |
.RE |
| 16992 |
.RS 4 |
| 16993 |
.RE |
| 16994 |
.ie n .IP """PadnamelistARRAY""" 4 |
| 16995 |
.el .IP \f(CWPadnamelistARRAY\fR 4 |
| 16996 |
.IX Xref "PadnamelistARRAY" |
| 16997 |
.IX Item "PadnamelistARRAY" |
| 16998 |
NOTE: \f(CW\*(C`PadnamelistARRAY\*(C'\fR is \fBexperimental\fR and may change or be |
| 16999 |
removed without notice. |
| 17000 |
.Sp |
| 17001 |
The C array of pad names. |
| 17002 |
.RS 4 |
| 17003 |
.Sp |
| 17004 |
.Vb 1 |
| 17005 |
\& PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl) |
| 17006 |
.Ve |
| 17007 |
.RE |
| 17008 |
.RS 4 |
| 17009 |
.RE |
| 17010 |
.ie n .IP """PadnamelistMAX""" 4 |
| 17011 |
.el .IP \f(CWPadnamelistMAX\fR 4 |
| 17012 |
.IX Xref "PadnamelistMAX" |
| 17013 |
.IX Item "PadnamelistMAX" |
| 17014 |
NOTE: \f(CW\*(C`PadnamelistMAX\*(C'\fR is \fBexperimental\fR and may change or be |
| 17015 |
removed without notice. |
| 17016 |
.Sp |
| 17017 |
The index of the last pad name. |
| 17018 |
.RS 4 |
| 17019 |
.Sp |
| 17020 |
.Vb 1 |
| 17021 |
\& SSize_t PadnamelistMAX(PADNAMELIST * pnl) |
| 17022 |
.Ve |
| 17023 |
.RE |
| 17024 |
.RS 4 |
| 17025 |
.RE |
| 17026 |
.ie n .IP """PadnamelistREFCNT""" 4 |
| 17027 |
.el .IP \f(CWPadnamelistREFCNT\fR 4 |
| 17028 |
.IX Xref "PadnamelistREFCNT" |
| 17029 |
.IX Item "PadnamelistREFCNT" |
| 17030 |
NOTE: \f(CW\*(C`PadnamelistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be |
| 17031 |
removed without notice. |
| 17032 |
.Sp |
| 17033 |
The reference count of the pad name list. |
| 17034 |
.RS 4 |
| 17035 |
.Sp |
| 17036 |
.Vb 1 |
| 17037 |
\& SSize_t PadnamelistREFCNT(PADNAMELIST * pnl) |
| 17038 |
.Ve |
| 17039 |
.RE |
| 17040 |
.RS 4 |
| 17041 |
.RE |
| 17042 |
.ie n .IP """PadnamelistREFCNT_dec""" 4 |
| 17043 |
.el .IP \f(CWPadnamelistREFCNT_dec\fR 4 |
| 17044 |
.IX Xref "PadnamelistREFCNT_dec" |
| 17045 |
.IX Item "PadnamelistREFCNT_dec" |
| 17046 |
NOTE: \f(CW\*(C`PadnamelistREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be |
| 17047 |
removed without notice. |
| 17048 |
.Sp |
| 17049 |
Lowers the reference count of the pad name list. |
| 17050 |
.RS 4 |
| 17051 |
.Sp |
| 17052 |
.Vb 1 |
| 17053 |
\& void PadnamelistREFCNT_dec(PADNAMELIST * pnl) |
| 17054 |
.Ve |
| 17055 |
.RE |
| 17056 |
.RS 4 |
| 17057 |
.RE |
| 17058 |
.ie n .IP """PadnamePV""" 4 |
| 17059 |
.el .IP \f(CWPadnamePV\fR 4 |
| 17060 |
.IX Xref "PadnamePV" |
| 17061 |
.IX Item "PadnamePV" |
| 17062 |
NOTE: \f(CW\*(C`PadnamePV\*(C'\fR is \fBexperimental\fR and may change or be |
| 17063 |
removed without notice. |
| 17064 |
.Sp |
| 17065 |
The name stored in the pad name struct. This returns \f(CW\*(C`NULL\*(C'\fR for a target |
| 17066 |
slot. |
| 17067 |
.RS 4 |
| 17068 |
.Sp |
| 17069 |
.Vb 1 |
| 17070 |
\& char * PadnamePV(PADNAME * pn) |
| 17071 |
.Ve |
| 17072 |
.RE |
| 17073 |
.RS 4 |
| 17074 |
.RE |
| 17075 |
.ie n .IP """PadnameREFCNT""" 4 |
| 17076 |
.el .IP \f(CWPadnameREFCNT\fR 4 |
| 17077 |
.IX Xref "PadnameREFCNT" |
| 17078 |
.IX Item "PadnameREFCNT" |
| 17079 |
NOTE: \f(CW\*(C`PadnameREFCNT\*(C'\fR is \fBexperimental\fR and may change or be |
| 17080 |
removed without notice. |
| 17081 |
.Sp |
| 17082 |
The reference count of the pad name. |
| 17083 |
.RS 4 |
| 17084 |
.Sp |
| 17085 |
.Vb 1 |
| 17086 |
\& SSize_t PadnameREFCNT(PADNAME * pn) |
| 17087 |
.Ve |
| 17088 |
.RE |
| 17089 |
.RS 4 |
| 17090 |
.RE |
| 17091 |
.ie n .IP """PadnameREFCNT_dec""" 4 |
| 17092 |
.el .IP \f(CWPadnameREFCNT_dec\fR 4 |
| 17093 |
.IX Xref "PadnameREFCNT_dec" |
| 17094 |
.IX Item "PadnameREFCNT_dec" |
| 17095 |
NOTE: \f(CW\*(C`PadnameREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be |
| 17096 |
removed without notice. |
| 17097 |
.Sp |
| 17098 |
Lowers the reference count of the pad name. |
| 17099 |
.RS 4 |
| 17100 |
.Sp |
| 17101 |
.Vb 1 |
| 17102 |
\& void PadnameREFCNT_dec(PADNAME * pn) |
| 17103 |
.Ve |
| 17104 |
.RE |
| 17105 |
.RS 4 |
| 17106 |
.RE |
| 17107 |
.ie n .IP """PadnameREFCNT_inc""" 4 |
| 17108 |
.el .IP \f(CWPadnameREFCNT_inc\fR 4 |
| 17109 |
.IX Xref "PadnameREFCNT_inc" |
| 17110 |
.IX Item "PadnameREFCNT_inc" |
| 17111 |
NOTE: \f(CW\*(C`PadnameREFCNT_inc\*(C'\fR is \fBexperimental\fR and may change or be |
| 17112 |
removed without notice. |
| 17113 |
.Sp |
| 17114 |
Increases the reference count of the pad name. Returns the pad name itself. |
| 17115 |
.RS 4 |
| 17116 |
.Sp |
| 17117 |
.Vb 1 |
| 17118 |
\& PADNAME * PadnameREFCNT_inc(PADNAME * pn) |
| 17119 |
.Ve |
| 17120 |
.RE |
| 17121 |
.RS 4 |
| 17122 |
.RE |
| 17123 |
.ie n .IP """PadnameSV""" 4 |
| 17124 |
.el .IP \f(CWPadnameSV\fR 4 |
| 17125 |
.IX Xref "PadnameSV" |
| 17126 |
.IX Item "PadnameSV" |
| 17127 |
NOTE: \f(CW\*(C`PadnameSV\*(C'\fR is \fBexperimental\fR and may change or be |
| 17128 |
removed without notice. |
| 17129 |
.Sp |
| 17130 |
Returns the pad name as a mortal SV. |
| 17131 |
.RS 4 |
| 17132 |
.Sp |
| 17133 |
.Vb 1 |
| 17134 |
\& SV * PadnameSV(PADNAME * pn) |
| 17135 |
.Ve |
| 17136 |
.RE |
| 17137 |
.RS 4 |
| 17138 |
.RE |
| 17139 |
.ie n .IP """PadnameUTF8""" 4 |
| 17140 |
.el .IP \f(CWPadnameUTF8\fR 4 |
| 17141 |
.IX Xref "PadnameUTF8" |
| 17142 |
.IX Item "PadnameUTF8" |
| 17143 |
NOTE: \f(CW\*(C`PadnameUTF8\*(C'\fR is \fBexperimental\fR and may change or be |
| 17144 |
removed without notice. |
| 17145 |
.Sp |
| 17146 |
Whether PadnamePV is in UTF\-8. Currently, this is always true. |
| 17147 |
.RS 4 |
| 17148 |
.Sp |
| 17149 |
.Vb 1 |
| 17150 |
\& bool PadnameUTF8(PADNAME * pn) |
| 17151 |
.Ve |
| 17152 |
.RE |
| 17153 |
.RS 4 |
| 17154 |
.RE |
| 17155 |
.ie n .IP """pad_new""" 4 |
| 17156 |
.el .IP \f(CWpad_new\fR 4 |
| 17157 |
.IX Xref "pad_new" |
| 17158 |
.IX Item "pad_new" |
| 17159 |
Create a new padlist, updating the global variables for the |
| 17160 |
currently-compiling padlist to point to the new padlist. The following |
| 17161 |
flags can be OR'ed together: |
| 17162 |
.Sp |
| 17163 |
.Vb 3 |
| 17164 |
\& padnew_CLONE this pad is for a cloned CV |
| 17165 |
\& padnew_SAVE save old globals on the save stack |
| 17166 |
\& padnew_SAVESUB also save extra stuff for start of sub |
| 17167 |
.Ve |
| 17168 |
.RS 4 |
| 17169 |
.Sp |
| 17170 |
.Vb 1 |
| 17171 |
\& PADLIST * pad_new(int flags) |
| 17172 |
.Ve |
| 17173 |
.RE |
| 17174 |
.RS 4 |
| 17175 |
.RE |
| 17176 |
.ie n .IP """PL_comppad""" 4 |
| 17177 |
.el .IP \f(CWPL_comppad\fR 4 |
| 17178 |
.IX Xref "PL_comppad" |
| 17179 |
.IX Item "PL_comppad" |
| 17180 |
NOTE: \f(CW\*(C`PL_comppad\*(C'\fR is \fBexperimental\fR and may change or be |
| 17181 |
removed without notice. |
| 17182 |
.Sp |
| 17183 |
During compilation, this points to the array containing the values |
| 17184 |
part of the pad for the currently-compiling code. (At runtime a CV may |
| 17185 |
have many such value arrays; at compile time just one is constructed.) |
| 17186 |
At runtime, this points to the array containing the currently-relevant |
| 17187 |
values for the pad for the currently-executing code. |
| 17188 |
.ie n .IP """PL_comppad_name""" 4 |
| 17189 |
.el .IP \f(CWPL_comppad_name\fR 4 |
| 17190 |
.IX Xref "PL_comppad_name" |
| 17191 |
.IX Item "PL_comppad_name" |
| 17192 |
NOTE: \f(CW\*(C`PL_comppad_name\*(C'\fR is \fBexperimental\fR and may change or be |
| 17193 |
removed without notice. |
| 17194 |
.Sp |
| 17195 |
During compilation, this points to the array containing the names part |
| 17196 |
of the pad for the currently-compiling code. |
| 17197 |
.ie n .IP """PL_curpad""" 4 |
| 17198 |
.el .IP \f(CWPL_curpad\fR 4 |
| 17199 |
.IX Xref "PL_curpad" |
| 17200 |
.IX Item "PL_curpad" |
| 17201 |
NOTE: \f(CW\*(C`PL_curpad\*(C'\fR is \fBexperimental\fR and may change or be |
| 17202 |
removed without notice. |
| 17203 |
.Sp |
| 17204 |
Points directly to the body of the "PL_comppad" array. |
| 17205 |
(I.e., this is \f(CWPadARRAY(PL_comppad)\fR.) |
| 17206 |
.ie n .IP """SVs_PADMY""" 4 |
| 17207 |
.el .IP \f(CWSVs_PADMY\fR 4 |
| 17208 |
.IX Item "SVs_PADMY" |
| 17209 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SVs_PADMY\*(C'\fR |
| 17210 |
from a future release of Perl. Do not use it for |
| 17211 |
new code; remove it from existing code. |
| 17212 |
.Sp |
| 17213 |
Described in perlguts. |
| 17214 |
.ie n .IP """SVs_PADTMP""" 4 |
| 17215 |
.el .IP \f(CWSVs_PADTMP\fR 4 |
| 17216 |
.IX Item "SVs_PADTMP" |
| 17217 |
Described in perlguts. |
| 17218 |
.SH "Password and Group access" |
| 17219 |
.IX Header "Password and Group access" |
| 17220 |
.ie n .IP """GRPASSWD""" 4 |
| 17221 |
.el .IP \f(CWGRPASSWD\fR 4 |
| 17222 |
.IX Xref "GRPASSWD" |
| 17223 |
.IX Item "GRPASSWD" |
| 17224 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct group\*(C'\fR |
| 17225 |
in \fIgrp.h\fR contains \f(CW\*(C`gr_passwd\*(C'\fR. |
| 17226 |
.ie n .IP """HAS_ENDGRENT""" 4 |
| 17227 |
.el .IP \f(CWHAS_ENDGRENT\fR 4 |
| 17228 |
.IX Xref "HAS_ENDGRENT" |
| 17229 |
.IX Item "HAS_ENDGRENT" |
| 17230 |
This symbol, if defined, indicates that the getgrent routine is |
| 17231 |
available for finalizing sequential access of the group database. |
| 17232 |
.ie n .IP """HAS_ENDGRENT_R""" 4 |
| 17233 |
.el .IP \f(CWHAS_ENDGRENT_R\fR 4 |
| 17234 |
.IX Xref "HAS_ENDGRENT_R" |
| 17235 |
.IX Item "HAS_ENDGRENT_R" |
| 17236 |
This symbol, if defined, indicates that the \f(CW\*(C`endgrent_r\*(C'\fR routine |
| 17237 |
is available to endgrent re-entrantly. |
| 17238 |
.ie n .IP """HAS_ENDPWENT""" 4 |
| 17239 |
.el .IP \f(CWHAS_ENDPWENT\fR 4 |
| 17240 |
.IX Xref "HAS_ENDPWENT" |
| 17241 |
.IX Item "HAS_ENDPWENT" |
| 17242 |
This symbol, if defined, indicates that the \f(CW\*(C`endpwent\*(C'\fR routine is |
| 17243 |
available for finalizing sequential access of the passwd database. |
| 17244 |
.ie n .IP """HAS_ENDPWENT_R""" 4 |
| 17245 |
.el .IP \f(CWHAS_ENDPWENT_R\fR 4 |
| 17246 |
.IX Xref "HAS_ENDPWENT_R" |
| 17247 |
.IX Item "HAS_ENDPWENT_R" |
| 17248 |
This symbol, if defined, indicates that the \f(CW\*(C`endpwent_r\*(C'\fR routine |
| 17249 |
is available to endpwent re-entrantly. |
| 17250 |
.ie n .IP """HAS_GETGRENT""" 4 |
| 17251 |
.el .IP \f(CWHAS_GETGRENT\fR 4 |
| 17252 |
.IX Xref "HAS_GETGRENT" |
| 17253 |
.IX Item "HAS_GETGRENT" |
| 17254 |
This symbol, if defined, indicates that the \f(CW\*(C`getgrent\*(C'\fR routine is |
| 17255 |
available for sequential access of the group database. |
| 17256 |
.ie n .IP """HAS_GETGRENT_R""" 4 |
| 17257 |
.el .IP \f(CWHAS_GETGRENT_R\fR 4 |
| 17258 |
.IX Xref "HAS_GETGRENT_R" |
| 17259 |
.IX Item "HAS_GETGRENT_R" |
| 17260 |
This symbol, if defined, indicates that the \f(CW\*(C`getgrent_r\*(C'\fR routine |
| 17261 |
is available to getgrent re-entrantly. |
| 17262 |
.ie n .IP """HAS_GETPWENT""" 4 |
| 17263 |
.el .IP \f(CWHAS_GETPWENT\fR 4 |
| 17264 |
.IX Xref "HAS_GETPWENT" |
| 17265 |
.IX Item "HAS_GETPWENT" |
| 17266 |
This symbol, if defined, indicates that the \f(CW\*(C`getpwent\*(C'\fR routine is |
| 17267 |
available for sequential access of the passwd database. |
| 17268 |
If this is not available, the older \f(CWgetpw()\fR function may be available. |
| 17269 |
.ie n .IP """HAS_GETPWENT_R""" 4 |
| 17270 |
.el .IP \f(CWHAS_GETPWENT_R\fR 4 |
| 17271 |
.IX Xref "HAS_GETPWENT_R" |
| 17272 |
.IX Item "HAS_GETPWENT_R" |
| 17273 |
This symbol, if defined, indicates that the \f(CW\*(C`getpwent_r\*(C'\fR routine |
| 17274 |
is available to getpwent re-entrantly. |
| 17275 |
.ie n .IP """HAS_SETGRENT""" 4 |
| 17276 |
.el .IP \f(CWHAS_SETGRENT\fR 4 |
| 17277 |
.IX Xref "HAS_SETGRENT" |
| 17278 |
.IX Item "HAS_SETGRENT" |
| 17279 |
This symbol, if defined, indicates that the \f(CW\*(C`setgrent\*(C'\fR routine is |
| 17280 |
available for initializing sequential access of the group database. |
| 17281 |
.ie n .IP """HAS_SETGRENT_R""" 4 |
| 17282 |
.el .IP \f(CWHAS_SETGRENT_R\fR 4 |
| 17283 |
.IX Xref "HAS_SETGRENT_R" |
| 17284 |
.IX Item "HAS_SETGRENT_R" |
| 17285 |
This symbol, if defined, indicates that the \f(CW\*(C`setgrent_r\*(C'\fR routine |
| 17286 |
is available to setgrent re-entrantly. |
| 17287 |
.ie n .IP """HAS_SETPWENT""" 4 |
| 17288 |
.el .IP \f(CWHAS_SETPWENT\fR 4 |
| 17289 |
.IX Xref "HAS_SETPWENT" |
| 17290 |
.IX Item "HAS_SETPWENT" |
| 17291 |
This symbol, if defined, indicates that the \f(CW\*(C`setpwent\*(C'\fR routine is |
| 17292 |
available for initializing sequential access of the passwd database. |
| 17293 |
.ie n .IP """HAS_SETPWENT_R""" 4 |
| 17294 |
.el .IP \f(CWHAS_SETPWENT_R\fR 4 |
| 17295 |
.IX Xref "HAS_SETPWENT_R" |
| 17296 |
.IX Item "HAS_SETPWENT_R" |
| 17297 |
This symbol, if defined, indicates that the \f(CW\*(C`setpwent_r\*(C'\fR routine |
| 17298 |
is available to setpwent re-entrantly. |
| 17299 |
.ie n .IP """PWAGE""" 4 |
| 17300 |
.el .IP \f(CWPWAGE\fR 4 |
| 17301 |
.IX Xref "PWAGE" |
| 17302 |
.IX Item "PWAGE" |
| 17303 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17304 |
contains \f(CW\*(C`pw_age\*(C'\fR. |
| 17305 |
.ie n .IP """PWCHANGE""" 4 |
| 17306 |
.el .IP \f(CWPWCHANGE\fR 4 |
| 17307 |
.IX Xref "PWCHANGE" |
| 17308 |
.IX Item "PWCHANGE" |
| 17309 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17310 |
contains \f(CW\*(C`pw_change\*(C'\fR. |
| 17311 |
.ie n .IP """PWCLASS""" 4 |
| 17312 |
.el .IP \f(CWPWCLASS\fR 4 |
| 17313 |
.IX Xref "PWCLASS" |
| 17314 |
.IX Item "PWCLASS" |
| 17315 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17316 |
contains \f(CW\*(C`pw_class\*(C'\fR. |
| 17317 |
.ie n .IP """PWCOMMENT""" 4 |
| 17318 |
.el .IP \f(CWPWCOMMENT\fR 4 |
| 17319 |
.IX Xref "PWCOMMENT" |
| 17320 |
.IX Item "PWCOMMENT" |
| 17321 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17322 |
contains \f(CW\*(C`pw_comment\*(C'\fR. |
| 17323 |
.ie n .IP """PWEXPIRE""" 4 |
| 17324 |
.el .IP \f(CWPWEXPIRE\fR 4 |
| 17325 |
.IX Xref "PWEXPIRE" |
| 17326 |
.IX Item "PWEXPIRE" |
| 17327 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17328 |
contains \f(CW\*(C`pw_expire\*(C'\fR. |
| 17329 |
.ie n .IP """PWGECOS""" 4 |
| 17330 |
.el .IP \f(CWPWGECOS\fR 4 |
| 17331 |
.IX Xref "PWGECOS" |
| 17332 |
.IX Item "PWGECOS" |
| 17333 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17334 |
contains \f(CW\*(C`pw_gecos\*(C'\fR. |
| 17335 |
.ie n .IP """PWPASSWD""" 4 |
| 17336 |
.el .IP \f(CWPWPASSWD\fR 4 |
| 17337 |
.IX Xref "PWPASSWD" |
| 17338 |
.IX Item "PWPASSWD" |
| 17339 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17340 |
contains \f(CW\*(C`pw_passwd\*(C'\fR. |
| 17341 |
.ie n .IP """PWQUOTA""" 4 |
| 17342 |
.el .IP \f(CWPWQUOTA\fR 4 |
| 17343 |
.IX Xref "PWQUOTA" |
| 17344 |
.IX Item "PWQUOTA" |
| 17345 |
This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR |
| 17346 |
contains \f(CW\*(C`pw_quota\*(C'\fR. |
| 17347 |
.SH "Paths to system commands" |
| 17348 |
.IX Header "Paths to system commands" |
| 17349 |
.ie n .IP """CSH""" 4 |
| 17350 |
.el .IP \f(CWCSH\fR 4 |
| 17351 |
.IX Xref "CSH" |
| 17352 |
.IX Item "CSH" |
| 17353 |
This symbol, if defined, contains the full pathname of csh. |
| 17354 |
.ie n .IP """LOC_SED""" 4 |
| 17355 |
.el .IP \f(CWLOC_SED\fR 4 |
| 17356 |
.IX Xref "LOC_SED" |
| 17357 |
.IX Item "LOC_SED" |
| 17358 |
This symbol holds the complete pathname to the sed program. |
| 17359 |
.ie n .IP """SH_PATH""" 4 |
| 17360 |
.el .IP \f(CWSH_PATH\fR 4 |
| 17361 |
.IX Xref "SH_PATH" |
| 17362 |
.IX Item "SH_PATH" |
| 17363 |
This symbol contains the full pathname to the shell used on this |
| 17364 |
on this system to execute Bourne shell scripts. Usually, this will be |
| 17365 |
\&\fI/bin/sh\fR, though it's possible that some systems will have \fI/bin/ksh\fR, |
| 17366 |
\&\fI/bin/pdksh\fR, \fI/bin/ash\fR, \fI/bin/bash\fR, or even something such as |
| 17367 |
D:\fI/bin/sh.exe\fR. |
| 17368 |
.SH "Prototype information" |
| 17369 |
.IX Header "Prototype information" |
| 17370 |
.ie n .IP """CRYPT_R_PROTO""" 4 |
| 17371 |
.el .IP \f(CWCRYPT_R_PROTO\fR 4 |
| 17372 |
.IX Xref "CRYPT_R_PROTO" |
| 17373 |
.IX Item "CRYPT_R_PROTO" |
| 17374 |
This symbol encodes the prototype of \f(CW\*(C`crypt_r\*(C'\fR. |
| 17375 |
It is zero if \f(CW\*(C`d_crypt_r\*(C'\fR is undef, and one of the |
| 17376 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_crypt_r\*(C'\fR |
| 17377 |
is defined. |
| 17378 |
.ie n .IP """CTERMID_R_PROTO""" 4 |
| 17379 |
.el .IP \f(CWCTERMID_R_PROTO\fR 4 |
| 17380 |
.IX Xref "CTERMID_R_PROTO" |
| 17381 |
.IX Item "CTERMID_R_PROTO" |
| 17382 |
This symbol encodes the prototype of \f(CW\*(C`ctermid_r\*(C'\fR. |
| 17383 |
It is zero if \f(CW\*(C`d_ctermid_r\*(C'\fR is undef, and one of the |
| 17384 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctermid_r\*(C'\fR |
| 17385 |
is defined. |
| 17386 |
.ie n .IP """DRAND48_R_PROTO""" 4 |
| 17387 |
.el .IP \f(CWDRAND48_R_PROTO\fR 4 |
| 17388 |
.IX Xref "DRAND48_R_PROTO" |
| 17389 |
.IX Item "DRAND48_R_PROTO" |
| 17390 |
This symbol encodes the prototype of \f(CW\*(C`drand48_r\*(C'\fR. |
| 17391 |
It is zero if \f(CW\*(C`d_drand48_r\*(C'\fR is undef, and one of the |
| 17392 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_drand48_r\*(C'\fR |
| 17393 |
is defined. |
| 17394 |
.ie n .IP """ENDGRENT_R_PROTO""" 4 |
| 17395 |
.el .IP \f(CWENDGRENT_R_PROTO\fR 4 |
| 17396 |
.IX Xref "ENDGRENT_R_PROTO" |
| 17397 |
.IX Item "ENDGRENT_R_PROTO" |
| 17398 |
This symbol encodes the prototype of \f(CW\*(C`endgrent_r\*(C'\fR. |
| 17399 |
It is zero if \f(CW\*(C`d_endgrent_r\*(C'\fR is undef, and one of the |
| 17400 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endgrent_r\*(C'\fR |
| 17401 |
is defined. |
| 17402 |
.ie n .IP """ENDHOSTENT_R_PROTO""" 4 |
| 17403 |
.el .IP \f(CWENDHOSTENT_R_PROTO\fR 4 |
| 17404 |
.IX Xref "ENDHOSTENT_R_PROTO" |
| 17405 |
.IX Item "ENDHOSTENT_R_PROTO" |
| 17406 |
This symbol encodes the prototype of \f(CW\*(C`endhostent_r\*(C'\fR. |
| 17407 |
It is zero if \f(CW\*(C`d_endhostent_r\*(C'\fR is undef, and one of the |
| 17408 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endhostent_r\*(C'\fR |
| 17409 |
is defined. |
| 17410 |
.ie n .IP """ENDNETENT_R_PROTO""" 4 |
| 17411 |
.el .IP \f(CWENDNETENT_R_PROTO\fR 4 |
| 17412 |
.IX Xref "ENDNETENT_R_PROTO" |
| 17413 |
.IX Item "ENDNETENT_R_PROTO" |
| 17414 |
This symbol encodes the prototype of \f(CW\*(C`endnetent_r\*(C'\fR. |
| 17415 |
It is zero if \f(CW\*(C`d_endnetent_r\*(C'\fR is undef, and one of the |
| 17416 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endnetent_r\*(C'\fR |
| 17417 |
is defined. |
| 17418 |
.ie n .IP """ENDPROTOENT_R_PROTO""" 4 |
| 17419 |
.el .IP \f(CWENDPROTOENT_R_PROTO\fR 4 |
| 17420 |
.IX Xref "ENDPROTOENT_R_PROTO" |
| 17421 |
.IX Item "ENDPROTOENT_R_PROTO" |
| 17422 |
This symbol encodes the prototype of \f(CW\*(C`endprotoent_r\*(C'\fR. |
| 17423 |
It is zero if \f(CW\*(C`d_endprotoent_r\*(C'\fR is undef, and one of the |
| 17424 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endprotoent_r\*(C'\fR |
| 17425 |
is defined. |
| 17426 |
.ie n .IP """ENDPWENT_R_PROTO""" 4 |
| 17427 |
.el .IP \f(CWENDPWENT_R_PROTO\fR 4 |
| 17428 |
.IX Xref "ENDPWENT_R_PROTO" |
| 17429 |
.IX Item "ENDPWENT_R_PROTO" |
| 17430 |
This symbol encodes the prototype of \f(CW\*(C`endpwent_r\*(C'\fR. |
| 17431 |
It is zero if \f(CW\*(C`d_endpwent_r\*(C'\fR is undef, and one of the |
| 17432 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endpwent_r\*(C'\fR |
| 17433 |
is defined. |
| 17434 |
.ie n .IP """ENDSERVENT_R_PROTO""" 4 |
| 17435 |
.el .IP \f(CWENDSERVENT_R_PROTO\fR 4 |
| 17436 |
.IX Xref "ENDSERVENT_R_PROTO" |
| 17437 |
.IX Item "ENDSERVENT_R_PROTO" |
| 17438 |
This symbol encodes the prototype of \f(CW\*(C`endservent_r\*(C'\fR. |
| 17439 |
It is zero if \f(CW\*(C`d_endservent_r\*(C'\fR is undef, and one of the |
| 17440 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endservent_r\*(C'\fR |
| 17441 |
is defined. |
| 17442 |
.ie n .IP """GDBMNDBM_H_USES_PROTOTYPES""" 4 |
| 17443 |
.el .IP \f(CWGDBMNDBM_H_USES_PROTOTYPES\fR 4 |
| 17444 |
.IX Xref "GDBMNDBM_H_USES_PROTOTYPES" |
| 17445 |
.IX Item "GDBMNDBM_H_USES_PROTOTYPES" |
| 17446 |
This symbol, if defined, indicates that \fIgdbm/ndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C |
| 17447 |
prototypes instead of K&R style function declarations without any |
| 17448 |
parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++, |
| 17449 |
K&R style function declarations will yield errors. |
| 17450 |
.ie n .IP """GDBM_NDBM_H_USES_PROTOTYPES""" 4 |
| 17451 |
.el .IP \f(CWGDBM_NDBM_H_USES_PROTOTYPES\fR 4 |
| 17452 |
.IX Xref "GDBM_NDBM_H_USES_PROTOTYPES" |
| 17453 |
.IX Item "GDBM_NDBM_H_USES_PROTOTYPES" |
| 17454 |
This symbol, if defined, indicates that <gdbm\-\fIndbm.h\fR> uses real \f(CW\*(C`ANSI\*(C'\fR C |
| 17455 |
prototypes instead of K&R style function declarations without any |
| 17456 |
parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++, |
| 17457 |
K&R style function declarations will yield errors. |
| 17458 |
.ie n .IP """GETGRENT_R_PROTO""" 4 |
| 17459 |
.el .IP \f(CWGETGRENT_R_PROTO\fR 4 |
| 17460 |
.IX Xref "GETGRENT_R_PROTO" |
| 17461 |
.IX Item "GETGRENT_R_PROTO" |
| 17462 |
This symbol encodes the prototype of \f(CW\*(C`getgrent_r\*(C'\fR. |
| 17463 |
It is zero if \f(CW\*(C`d_getgrent_r\*(C'\fR is undef, and one of the |
| 17464 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrent_r\*(C'\fR |
| 17465 |
is defined. |
| 17466 |
.ie n .IP """GETGRGID_R_PROTO""" 4 |
| 17467 |
.el .IP \f(CWGETGRGID_R_PROTO\fR 4 |
| 17468 |
.IX Xref "GETGRGID_R_PROTO" |
| 17469 |
.IX Item "GETGRGID_R_PROTO" |
| 17470 |
This symbol encodes the prototype of \f(CW\*(C`getgrgid_r\*(C'\fR. |
| 17471 |
It is zero if \f(CW\*(C`d_getgrgid_r\*(C'\fR is undef, and one of the |
| 17472 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrgid_r\*(C'\fR |
| 17473 |
is defined. |
| 17474 |
.ie n .IP """GETGRNAM_R_PROTO""" 4 |
| 17475 |
.el .IP \f(CWGETGRNAM_R_PROTO\fR 4 |
| 17476 |
.IX Xref "GETGRNAM_R_PROTO" |
| 17477 |
.IX Item "GETGRNAM_R_PROTO" |
| 17478 |
This symbol encodes the prototype of \f(CW\*(C`getgrnam_r\*(C'\fR. |
| 17479 |
It is zero if \f(CW\*(C`d_getgrnam_r\*(C'\fR is undef, and one of the |
| 17480 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrnam_r\*(C'\fR |
| 17481 |
is defined. |
| 17482 |
.ie n .IP """GETHOSTBYADDR_R_PROTO""" 4 |
| 17483 |
.el .IP \f(CWGETHOSTBYADDR_R_PROTO\fR 4 |
| 17484 |
.IX Xref "GETHOSTBYADDR_R_PROTO" |
| 17485 |
.IX Item "GETHOSTBYADDR_R_PROTO" |
| 17486 |
This symbol encodes the prototype of \f(CW\*(C`gethostbyaddr_r\*(C'\fR. |
| 17487 |
It is zero if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR is undef, and one of the |
| 17488 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR |
| 17489 |
is defined. |
| 17490 |
.ie n .IP """GETHOSTBYNAME_R_PROTO""" 4 |
| 17491 |
.el .IP \f(CWGETHOSTBYNAME_R_PROTO\fR 4 |
| 17492 |
.IX Xref "GETHOSTBYNAME_R_PROTO" |
| 17493 |
.IX Item "GETHOSTBYNAME_R_PROTO" |
| 17494 |
This symbol encodes the prototype of \f(CW\*(C`gethostbyname_r\*(C'\fR. |
| 17495 |
It is zero if \f(CW\*(C`d_gethostbyname_r\*(C'\fR is undef, and one of the |
| 17496 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyname_r\*(C'\fR |
| 17497 |
is defined. |
| 17498 |
.ie n .IP """GETHOSTENT_R_PROTO""" 4 |
| 17499 |
.el .IP \f(CWGETHOSTENT_R_PROTO\fR 4 |
| 17500 |
.IX Xref "GETHOSTENT_R_PROTO" |
| 17501 |
.IX Item "GETHOSTENT_R_PROTO" |
| 17502 |
This symbol encodes the prototype of \f(CW\*(C`gethostent_r\*(C'\fR. |
| 17503 |
It is zero if \f(CW\*(C`d_gethostent_r\*(C'\fR is undef, and one of the |
| 17504 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostent_r\*(C'\fR |
| 17505 |
is defined. |
| 17506 |
.ie n .IP """GETLOGIN_R_PROTO""" 4 |
| 17507 |
.el .IP \f(CWGETLOGIN_R_PROTO\fR 4 |
| 17508 |
.IX Xref "GETLOGIN_R_PROTO" |
| 17509 |
.IX Item "GETLOGIN_R_PROTO" |
| 17510 |
This symbol encodes the prototype of \f(CW\*(C`getlogin_r\*(C'\fR. |
| 17511 |
It is zero if \f(CW\*(C`d_getlogin_r\*(C'\fR is undef, and one of the |
| 17512 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getlogin_r\*(C'\fR |
| 17513 |
is defined. |
| 17514 |
.ie n .IP """GETNETBYADDR_R_PROTO""" 4 |
| 17515 |
.el .IP \f(CWGETNETBYADDR_R_PROTO\fR 4 |
| 17516 |
.IX Xref "GETNETBYADDR_R_PROTO" |
| 17517 |
.IX Item "GETNETBYADDR_R_PROTO" |
| 17518 |
This symbol encodes the prototype of \f(CW\*(C`getnetbyaddr_r\*(C'\fR. |
| 17519 |
It is zero if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR is undef, and one of the |
| 17520 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR |
| 17521 |
is defined. |
| 17522 |
.ie n .IP """GETNETBYNAME_R_PROTO""" 4 |
| 17523 |
.el .IP \f(CWGETNETBYNAME_R_PROTO\fR 4 |
| 17524 |
.IX Xref "GETNETBYNAME_R_PROTO" |
| 17525 |
.IX Item "GETNETBYNAME_R_PROTO" |
| 17526 |
This symbol encodes the prototype of \f(CW\*(C`getnetbyname_r\*(C'\fR. |
| 17527 |
It is zero if \f(CW\*(C`d_getnetbyname_r\*(C'\fR is undef, and one of the |
| 17528 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyname_r\*(C'\fR |
| 17529 |
is defined. |
| 17530 |
.ie n .IP """GETNETENT_R_PROTO""" 4 |
| 17531 |
.el .IP \f(CWGETNETENT_R_PROTO\fR 4 |
| 17532 |
.IX Xref "GETNETENT_R_PROTO" |
| 17533 |
.IX Item "GETNETENT_R_PROTO" |
| 17534 |
This symbol encodes the prototype of \f(CW\*(C`getnetent_r\*(C'\fR. |
| 17535 |
It is zero if \f(CW\*(C`d_getnetent_r\*(C'\fR is undef, and one of the |
| 17536 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetent_r\*(C'\fR |
| 17537 |
is defined. |
| 17538 |
.ie n .IP """GETPROTOBYNAME_R_PROTO""" 4 |
| 17539 |
.el .IP \f(CWGETPROTOBYNAME_R_PROTO\fR 4 |
| 17540 |
.IX Xref "GETPROTOBYNAME_R_PROTO" |
| 17541 |
.IX Item "GETPROTOBYNAME_R_PROTO" |
| 17542 |
This symbol encodes the prototype of \f(CW\*(C`getprotobyname_r\*(C'\fR. |
| 17543 |
It is zero if \f(CW\*(C`d_getprotobyname_r\*(C'\fR is undef, and one of the |
| 17544 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobyname_r\*(C'\fR |
| 17545 |
is defined. |
| 17546 |
.ie n .IP """GETPROTOBYNUMBER_R_PROTO""" 4 |
| 17547 |
.el .IP \f(CWGETPROTOBYNUMBER_R_PROTO\fR 4 |
| 17548 |
.IX Xref "GETPROTOBYNUMBER_R_PROTO" |
| 17549 |
.IX Item "GETPROTOBYNUMBER_R_PROTO" |
| 17550 |
This symbol encodes the prototype of \f(CW\*(C`getprotobynumber_r\*(C'\fR. |
| 17551 |
It is zero if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR is undef, and one of the |
| 17552 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR |
| 17553 |
is defined. |
| 17554 |
.ie n .IP """GETPROTOENT_R_PROTO""" 4 |
| 17555 |
.el .IP \f(CWGETPROTOENT_R_PROTO\fR 4 |
| 17556 |
.IX Xref "GETPROTOENT_R_PROTO" |
| 17557 |
.IX Item "GETPROTOENT_R_PROTO" |
| 17558 |
This symbol encodes the prototype of \f(CW\*(C`getprotoent_r\*(C'\fR. |
| 17559 |
It is zero if \f(CW\*(C`d_getprotoent_r\*(C'\fR is undef, and one of the |
| 17560 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotoent_r\*(C'\fR |
| 17561 |
is defined. |
| 17562 |
.ie n .IP """GETPWENT_R_PROTO""" 4 |
| 17563 |
.el .IP \f(CWGETPWENT_R_PROTO\fR 4 |
| 17564 |
.IX Xref "GETPWENT_R_PROTO" |
| 17565 |
.IX Item "GETPWENT_R_PROTO" |
| 17566 |
This symbol encodes the prototype of \f(CW\*(C`getpwent_r\*(C'\fR. |
| 17567 |
It is zero if \f(CW\*(C`d_getpwent_r\*(C'\fR is undef, and one of the |
| 17568 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwent_r\*(C'\fR |
| 17569 |
is defined. |
| 17570 |
.ie n .IP """GETPWNAM_R_PROTO""" 4 |
| 17571 |
.el .IP \f(CWGETPWNAM_R_PROTO\fR 4 |
| 17572 |
.IX Xref "GETPWNAM_R_PROTO" |
| 17573 |
.IX Item "GETPWNAM_R_PROTO" |
| 17574 |
This symbol encodes the prototype of \f(CW\*(C`getpwnam_r\*(C'\fR. |
| 17575 |
It is zero if \f(CW\*(C`d_getpwnam_r\*(C'\fR is undef, and one of the |
| 17576 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwnam_r\*(C'\fR |
| 17577 |
is defined. |
| 17578 |
.ie n .IP """GETPWUID_R_PROTO""" 4 |
| 17579 |
.el .IP \f(CWGETPWUID_R_PROTO\fR 4 |
| 17580 |
.IX Xref "GETPWUID_R_PROTO" |
| 17581 |
.IX Item "GETPWUID_R_PROTO" |
| 17582 |
This symbol encodes the prototype of \f(CW\*(C`getpwuid_r\*(C'\fR. |
| 17583 |
It is zero if \f(CW\*(C`d_getpwuid_r\*(C'\fR is undef, and one of the |
| 17584 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwuid_r\*(C'\fR |
| 17585 |
is defined. |
| 17586 |
.ie n .IP """GETSERVBYNAME_R_PROTO""" 4 |
| 17587 |
.el .IP \f(CWGETSERVBYNAME_R_PROTO\fR 4 |
| 17588 |
.IX Xref "GETSERVBYNAME_R_PROTO" |
| 17589 |
.IX Item "GETSERVBYNAME_R_PROTO" |
| 17590 |
This symbol encodes the prototype of \f(CW\*(C`getservbyname_r\*(C'\fR. |
| 17591 |
It is zero if \f(CW\*(C`d_getservbyname_r\*(C'\fR is undef, and one of the |
| 17592 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyname_r\*(C'\fR |
| 17593 |
is defined. |
| 17594 |
.ie n .IP """GETSERVBYPORT_R_PROTO""" 4 |
| 17595 |
.el .IP \f(CWGETSERVBYPORT_R_PROTO\fR 4 |
| 17596 |
.IX Xref "GETSERVBYPORT_R_PROTO" |
| 17597 |
.IX Item "GETSERVBYPORT_R_PROTO" |
| 17598 |
This symbol encodes the prototype of \f(CW\*(C`getservbyport_r\*(C'\fR. |
| 17599 |
It is zero if \f(CW\*(C`d_getservbyport_r\*(C'\fR is undef, and one of the |
| 17600 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyport_r\*(C'\fR |
| 17601 |
is defined. |
| 17602 |
.ie n .IP """GETSERVENT_R_PROTO""" 4 |
| 17603 |
.el .IP \f(CWGETSERVENT_R_PROTO\fR 4 |
| 17604 |
.IX Xref "GETSERVENT_R_PROTO" |
| 17605 |
.IX Item "GETSERVENT_R_PROTO" |
| 17606 |
This symbol encodes the prototype of \f(CW\*(C`getservent_r\*(C'\fR. |
| 17607 |
It is zero if \f(CW\*(C`d_getservent_r\*(C'\fR is undef, and one of the |
| 17608 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservent_r\*(C'\fR |
| 17609 |
is defined. |
| 17610 |
.ie n .IP """GETSPNAM_R_PROTO""" 4 |
| 17611 |
.el .IP \f(CWGETSPNAM_R_PROTO\fR 4 |
| 17612 |
.IX Xref "GETSPNAM_R_PROTO" |
| 17613 |
.IX Item "GETSPNAM_R_PROTO" |
| 17614 |
This symbol encodes the prototype of \f(CW\*(C`getspnam_r\*(C'\fR. |
| 17615 |
It is zero if \f(CW\*(C`d_getspnam_r\*(C'\fR is undef, and one of the |
| 17616 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getspnam_r\*(C'\fR |
| 17617 |
is defined. |
| 17618 |
.ie n .IP """HAS_DBMINIT_PROTO""" 4 |
| 17619 |
.el .IP \f(CWHAS_DBMINIT_PROTO\fR 4 |
| 17620 |
.IX Xref "HAS_DBMINIT_PROTO" |
| 17621 |
.IX Item "HAS_DBMINIT_PROTO" |
| 17622 |
This symbol, if defined, indicates that the system provides |
| 17623 |
a prototype for the \f(CWdbminit()\fR function. Otherwise, it is up |
| 17624 |
to the program to supply one. A good guess is |
| 17625 |
.Sp |
| 17626 |
.Vb 1 |
| 17627 |
\& extern int dbminit(char *); |
| 17628 |
.Ve |
| 17629 |
.ie n .IP """HAS_DRAND48_PROTO""" 4 |
| 17630 |
.el .IP \f(CWHAS_DRAND48_PROTO\fR 4 |
| 17631 |
.IX Xref "HAS_DRAND48_PROTO" |
| 17632 |
.IX Item "HAS_DRAND48_PROTO" |
| 17633 |
This symbol, if defined, indicates that the system provides |
| 17634 |
a prototype for the \f(CWdrand48()\fR function. Otherwise, it is up |
| 17635 |
to the program to supply one. A good guess is |
| 17636 |
.Sp |
| 17637 |
.Vb 1 |
| 17638 |
\& extern double drand48(void); |
| 17639 |
.Ve |
| 17640 |
.ie n .IP """HAS_FLOCK_PROTO""" 4 |
| 17641 |
.el .IP \f(CWHAS_FLOCK_PROTO\fR 4 |
| 17642 |
.IX Xref "HAS_FLOCK_PROTO" |
| 17643 |
.IX Item "HAS_FLOCK_PROTO" |
| 17644 |
This symbol, if defined, indicates that the system provides |
| 17645 |
a prototype for the \f(CWflock()\fR function. Otherwise, it is up |
| 17646 |
to the program to supply one. A good guess is |
| 17647 |
.Sp |
| 17648 |
.Vb 1 |
| 17649 |
\& extern int flock(int, int); |
| 17650 |
.Ve |
| 17651 |
.ie n .IP """HAS_GETHOST_PROTOS""" 4 |
| 17652 |
.el .IP \f(CWHAS_GETHOST_PROTOS\fR 4 |
| 17653 |
.IX Xref "HAS_GETHOST_PROTOS" |
| 17654 |
.IX Item "HAS_GETHOST_PROTOS" |
| 17655 |
This symbol, if defined, indicates that \fInetdb.h\fR includes |
| 17656 |
prototypes for \f(CWgethostent()\fR, \f(CWgethostbyname()\fR, and |
| 17657 |
\&\f(CWgethostbyaddr()\fR. Otherwise, it is up to the program to guess |
| 17658 |
them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types. |
| 17659 |
.ie n .IP """HAS_GETNET_PROTOS""" 4 |
| 17660 |
.el .IP \f(CWHAS_GETNET_PROTOS\fR 4 |
| 17661 |
.IX Xref "HAS_GETNET_PROTOS" |
| 17662 |
.IX Item "HAS_GETNET_PROTOS" |
| 17663 |
This symbol, if defined, indicates that \fInetdb.h\fR includes |
| 17664 |
prototypes for \f(CWgetnetent()\fR, \f(CWgetnetbyname()\fR, and |
| 17665 |
\&\f(CWgetnetbyaddr()\fR. Otherwise, it is up to the program to guess |
| 17666 |
them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types. |
| 17667 |
.ie n .IP """HAS_GETPROTO_PROTOS""" 4 |
| 17668 |
.el .IP \f(CWHAS_GETPROTO_PROTOS\fR 4 |
| 17669 |
.IX Xref "HAS_GETPROTO_PROTOS" |
| 17670 |
.IX Item "HAS_GETPROTO_PROTOS" |
| 17671 |
This symbol, if defined, indicates that \fInetdb.h\fR includes |
| 17672 |
prototypes for \f(CWgetprotoent()\fR, \f(CWgetprotobyname()\fR, and |
| 17673 |
\&\f(CWgetprotobyaddr()\fR. Otherwise, it is up to the program to guess |
| 17674 |
them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types. |
| 17675 |
.ie n .IP """HAS_GETSERV_PROTOS""" 4 |
| 17676 |
.el .IP \f(CWHAS_GETSERV_PROTOS\fR 4 |
| 17677 |
.IX Xref "HAS_GETSERV_PROTOS" |
| 17678 |
.IX Item "HAS_GETSERV_PROTOS" |
| 17679 |
This symbol, if defined, indicates that \fInetdb.h\fR includes |
| 17680 |
prototypes for \f(CWgetservent()\fR, \f(CWgetservbyname()\fR, and |
| 17681 |
\&\f(CWgetservbyaddr()\fR. Otherwise, it is up to the program to guess |
| 17682 |
them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types. |
| 17683 |
.ie n .IP """HAS_MODFL_PROTO""" 4 |
| 17684 |
.el .IP \f(CWHAS_MODFL_PROTO\fR 4 |
| 17685 |
.IX Xref "HAS_MODFL_PROTO" |
| 17686 |
.IX Item "HAS_MODFL_PROTO" |
| 17687 |
This symbol, if defined, indicates that the system provides |
| 17688 |
a prototype for the \f(CWmodfl()\fR function. Otherwise, it is up |
| 17689 |
to the program to supply one. |
| 17690 |
.ie n .IP """HAS_SBRK_PROTO""" 4 |
| 17691 |
.el .IP \f(CWHAS_SBRK_PROTO\fR 4 |
| 17692 |
.IX Xref "HAS_SBRK_PROTO" |
| 17693 |
.IX Item "HAS_SBRK_PROTO" |
| 17694 |
This symbol, if defined, indicates that the system provides |
| 17695 |
a prototype for the \f(CWsbrk()\fR function. Otherwise, it is up |
| 17696 |
to the program to supply one. Good guesses are |
| 17697 |
.Sp |
| 17698 |
.Vb 2 |
| 17699 |
\& extern void* sbrk(int); |
| 17700 |
\& extern void* sbrk(size_t); |
| 17701 |
.Ve |
| 17702 |
.ie n .IP """HAS_SETRESGID_PROTO""" 4 |
| 17703 |
.el .IP \f(CWHAS_SETRESGID_PROTO\fR 4 |
| 17704 |
.IX Xref "HAS_SETRESGID_PROTO" |
| 17705 |
.IX Item "HAS_SETRESGID_PROTO" |
| 17706 |
This symbol, if defined, indicates that the system provides |
| 17707 |
a prototype for the \f(CWsetresgid()\fR function. Otherwise, it is up |
| 17708 |
to the program to supply one. Good guesses are |
| 17709 |
.Sp |
| 17710 |
.Vb 1 |
| 17711 |
\& extern int setresgid(uid_t ruid, uid_t euid, uid_t suid); |
| 17712 |
.Ve |
| 17713 |
.ie n .IP """HAS_SETRESUID_PROTO""" 4 |
| 17714 |
.el .IP \f(CWHAS_SETRESUID_PROTO\fR 4 |
| 17715 |
.IX Xref "HAS_SETRESUID_PROTO" |
| 17716 |
.IX Item "HAS_SETRESUID_PROTO" |
| 17717 |
This symbol, if defined, indicates that the system provides |
| 17718 |
a prototype for the \f(CWsetresuid()\fR function. Otherwise, it is up |
| 17719 |
to the program to supply one. Good guesses are |
| 17720 |
.Sp |
| 17721 |
.Vb 1 |
| 17722 |
\& extern int setresuid(uid_t ruid, uid_t euid, uid_t suid); |
| 17723 |
.Ve |
| 17724 |
.ie n .IP """HAS_SHMAT_PROTOTYPE""" 4 |
| 17725 |
.el .IP \f(CWHAS_SHMAT_PROTOTYPE\fR 4 |
| 17726 |
.IX Xref "HAS_SHMAT_PROTOTYPE" |
| 17727 |
.IX Item "HAS_SHMAT_PROTOTYPE" |
| 17728 |
This symbol, if defined, indicates that the \fIsys/shm.h\fR includes |
| 17729 |
a prototype for \f(CWshmat()\fR. Otherwise, it is up to the program to |
| 17730 |
guess one. \f(CW\*(C`Shmat_t\*(C'\fR \f(CW\*(C`shmat(int, Shmat_t, int)\*(C'\fR is a good guess, |
| 17731 |
but not always right so it should be emitted by the program only |
| 17732 |
when \f(CW\*(C`HAS_SHMAT_PROTOTYPE\*(C'\fR is not defined to avoid conflicting defs. |
| 17733 |
.ie n .IP """HAS_SOCKATMARK_PROTO""" 4 |
| 17734 |
.el .IP \f(CWHAS_SOCKATMARK_PROTO\fR 4 |
| 17735 |
.IX Xref "HAS_SOCKATMARK_PROTO" |
| 17736 |
.IX Item "HAS_SOCKATMARK_PROTO" |
| 17737 |
This symbol, if defined, indicates that the system provides |
| 17738 |
a prototype for the \f(CWsockatmark()\fR function. Otherwise, it is up |
| 17739 |
to the program to supply one. A good guess is |
| 17740 |
.Sp |
| 17741 |
.Vb 1 |
| 17742 |
\& extern int sockatmark(int); |
| 17743 |
.Ve |
| 17744 |
.ie n .IP """HAS_SYSCALL_PROTO""" 4 |
| 17745 |
.el .IP \f(CWHAS_SYSCALL_PROTO\fR 4 |
| 17746 |
.IX Xref "HAS_SYSCALL_PROTO" |
| 17747 |
.IX Item "HAS_SYSCALL_PROTO" |
| 17748 |
This symbol, if defined, indicates that the system provides |
| 17749 |
a prototype for the \f(CWsyscall()\fR function. Otherwise, it is up |
| 17750 |
to the program to supply one. Good guesses are |
| 17751 |
.Sp |
| 17752 |
.Vb 2 |
| 17753 |
\& extern int syscall(int, ...); |
| 17754 |
\& extern int syscall(long, ...); |
| 17755 |
.Ve |
| 17756 |
.ie n .IP """HAS_TELLDIR_PROTO""" 4 |
| 17757 |
.el .IP \f(CWHAS_TELLDIR_PROTO\fR 4 |
| 17758 |
.IX Xref "HAS_TELLDIR_PROTO" |
| 17759 |
.IX Item "HAS_TELLDIR_PROTO" |
| 17760 |
This symbol, if defined, indicates that the system provides |
| 17761 |
a prototype for the \f(CWtelldir()\fR function. Otherwise, it is up |
| 17762 |
to the program to supply one. A good guess is |
| 17763 |
.Sp |
| 17764 |
.Vb 1 |
| 17765 |
\& extern long telldir(DIR*); |
| 17766 |
.Ve |
| 17767 |
.ie n .IP """NDBM_H_USES_PROTOTYPES""" 4 |
| 17768 |
.el .IP \f(CWNDBM_H_USES_PROTOTYPES\fR 4 |
| 17769 |
.IX Xref "NDBM_H_USES_PROTOTYPES" |
| 17770 |
.IX Item "NDBM_H_USES_PROTOTYPES" |
| 17771 |
This symbol, if defined, indicates that \fIndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C |
| 17772 |
prototypes instead of K&R style function declarations without any |
| 17773 |
parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++, |
| 17774 |
K&R style function declarations will yield errors. |
| 17775 |
.ie n .IP """RANDOM_R_PROTO""" 4 |
| 17776 |
.el .IP \f(CWRANDOM_R_PROTO\fR 4 |
| 17777 |
.IX Xref "RANDOM_R_PROTO" |
| 17778 |
.IX Item "RANDOM_R_PROTO" |
| 17779 |
This symbol encodes the prototype of \f(CW\*(C`random_r\*(C'\fR. |
| 17780 |
It is zero if \f(CW\*(C`d_random_r\*(C'\fR is undef, and one of the |
| 17781 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_random_r\*(C'\fR |
| 17782 |
is defined. |
| 17783 |
.ie n .IP """READDIR_R_PROTO""" 4 |
| 17784 |
.el .IP \f(CWREADDIR_R_PROTO\fR 4 |
| 17785 |
.IX Xref "READDIR_R_PROTO" |
| 17786 |
.IX Item "READDIR_R_PROTO" |
| 17787 |
This symbol encodes the prototype of \f(CW\*(C`readdir_r\*(C'\fR. |
| 17788 |
It is zero if \f(CW\*(C`d_readdir_r\*(C'\fR is undef, and one of the |
| 17789 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir_r\*(C'\fR |
| 17790 |
is defined. |
| 17791 |
.ie n .IP """SETGRENT_R_PROTO""" 4 |
| 17792 |
.el .IP \f(CWSETGRENT_R_PROTO\fR 4 |
| 17793 |
.IX Xref "SETGRENT_R_PROTO" |
| 17794 |
.IX Item "SETGRENT_R_PROTO" |
| 17795 |
This symbol encodes the prototype of \f(CW\*(C`setgrent_r\*(C'\fR. |
| 17796 |
It is zero if \f(CW\*(C`d_setgrent_r\*(C'\fR is undef, and one of the |
| 17797 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setgrent_r\*(C'\fR |
| 17798 |
is defined. |
| 17799 |
.ie n .IP """SETHOSTENT_R_PROTO""" 4 |
| 17800 |
.el .IP \f(CWSETHOSTENT_R_PROTO\fR 4 |
| 17801 |
.IX Xref "SETHOSTENT_R_PROTO" |
| 17802 |
.IX Item "SETHOSTENT_R_PROTO" |
| 17803 |
This symbol encodes the prototype of \f(CW\*(C`sethostent_r\*(C'\fR. |
| 17804 |
It is zero if \f(CW\*(C`d_sethostent_r\*(C'\fR is undef, and one of the |
| 17805 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_sethostent_r\*(C'\fR |
| 17806 |
is defined. |
| 17807 |
.ie n .IP """SETLOCALE_R_PROTO""" 4 |
| 17808 |
.el .IP \f(CWSETLOCALE_R_PROTO\fR 4 |
| 17809 |
.IX Xref "SETLOCALE_R_PROTO" |
| 17810 |
.IX Item "SETLOCALE_R_PROTO" |
| 17811 |
This symbol encodes the prototype of \f(CW\*(C`setlocale_r\*(C'\fR. |
| 17812 |
It is zero if \f(CW\*(C`d_setlocale_r\*(C'\fR is undef, and one of the |
| 17813 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setlocale_r\*(C'\fR |
| 17814 |
is defined. |
| 17815 |
.ie n .IP """SETNETENT_R_PROTO""" 4 |
| 17816 |
.el .IP \f(CWSETNETENT_R_PROTO\fR 4 |
| 17817 |
.IX Xref "SETNETENT_R_PROTO" |
| 17818 |
.IX Item "SETNETENT_R_PROTO" |
| 17819 |
This symbol encodes the prototype of \f(CW\*(C`setnetent_r\*(C'\fR. |
| 17820 |
It is zero if \f(CW\*(C`d_setnetent_r\*(C'\fR is undef, and one of the |
| 17821 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setnetent_r\*(C'\fR |
| 17822 |
is defined. |
| 17823 |
.ie n .IP """SETPROTOENT_R_PROTO""" 4 |
| 17824 |
.el .IP \f(CWSETPROTOENT_R_PROTO\fR 4 |
| 17825 |
.IX Xref "SETPROTOENT_R_PROTO" |
| 17826 |
.IX Item "SETPROTOENT_R_PROTO" |
| 17827 |
This symbol encodes the prototype of \f(CW\*(C`setprotoent_r\*(C'\fR. |
| 17828 |
It is zero if \f(CW\*(C`d_setprotoent_r\*(C'\fR is undef, and one of the |
| 17829 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setprotoent_r\*(C'\fR |
| 17830 |
is defined. |
| 17831 |
.ie n .IP """SETPWENT_R_PROTO""" 4 |
| 17832 |
.el .IP \f(CWSETPWENT_R_PROTO\fR 4 |
| 17833 |
.IX Xref "SETPWENT_R_PROTO" |
| 17834 |
.IX Item "SETPWENT_R_PROTO" |
| 17835 |
This symbol encodes the prototype of \f(CW\*(C`setpwent_r\*(C'\fR. |
| 17836 |
It is zero if \f(CW\*(C`d_setpwent_r\*(C'\fR is undef, and one of the |
| 17837 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setpwent_r\*(C'\fR |
| 17838 |
is defined. |
| 17839 |
.ie n .IP """SETSERVENT_R_PROTO""" 4 |
| 17840 |
.el .IP \f(CWSETSERVENT_R_PROTO\fR 4 |
| 17841 |
.IX Xref "SETSERVENT_R_PROTO" |
| 17842 |
.IX Item "SETSERVENT_R_PROTO" |
| 17843 |
This symbol encodes the prototype of \f(CW\*(C`setservent_r\*(C'\fR. |
| 17844 |
It is zero if \f(CW\*(C`d_setservent_r\*(C'\fR is undef, and one of the |
| 17845 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setservent_r\*(C'\fR |
| 17846 |
is defined. |
| 17847 |
.ie n .IP """SRANDOM_R_PROTO""" 4 |
| 17848 |
.el .IP \f(CWSRANDOM_R_PROTO\fR 4 |
| 17849 |
.IX Xref "SRANDOM_R_PROTO" |
| 17850 |
.IX Item "SRANDOM_R_PROTO" |
| 17851 |
This symbol encodes the prototype of \f(CW\*(C`srandom_r\*(C'\fR. |
| 17852 |
It is zero if \f(CW\*(C`d_srandom_r\*(C'\fR is undef, and one of the |
| 17853 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srandom_r\*(C'\fR |
| 17854 |
is defined. |
| 17855 |
.ie n .IP """SRAND48_R_PROTO""" 4 |
| 17856 |
.el .IP \f(CWSRAND48_R_PROTO\fR 4 |
| 17857 |
.IX Xref "SRAND48_R_PROTO" |
| 17858 |
.IX Item "SRAND48_R_PROTO" |
| 17859 |
This symbol encodes the prototype of \f(CW\*(C`srand48_r\*(C'\fR. |
| 17860 |
It is zero if \f(CW\*(C`d_srand48_r\*(C'\fR is undef, and one of the |
| 17861 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srand48_r\*(C'\fR |
| 17862 |
is defined. |
| 17863 |
.ie n .IP """STRERROR_R_PROTO""" 4 |
| 17864 |
.el .IP \f(CWSTRERROR_R_PROTO\fR 4 |
| 17865 |
.IX Xref "STRERROR_R_PROTO" |
| 17866 |
.IX Item "STRERROR_R_PROTO" |
| 17867 |
This symbol encodes the prototype of \f(CW\*(C`strerror_r\*(C'\fR. |
| 17868 |
It is zero if \f(CW\*(C`d_strerror_r\*(C'\fR is undef, and one of the |
| 17869 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_strerror_r\*(C'\fR |
| 17870 |
is defined. |
| 17871 |
.ie n .IP """TMPNAM_R_PROTO""" 4 |
| 17872 |
.el .IP \f(CWTMPNAM_R_PROTO\fR 4 |
| 17873 |
.IX Xref "TMPNAM_R_PROTO" |
| 17874 |
.IX Item "TMPNAM_R_PROTO" |
| 17875 |
This symbol encodes the prototype of \f(CW\*(C`tmpnam_r\*(C'\fR. |
| 17876 |
It is zero if \f(CW\*(C`d_tmpnam_r\*(C'\fR is undef, and one of the |
| 17877 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_tmpnam_r\*(C'\fR |
| 17878 |
is defined. |
| 17879 |
.ie n .IP """TTYNAME_R_PROTO""" 4 |
| 17880 |
.el .IP \f(CWTTYNAME_R_PROTO\fR 4 |
| 17881 |
.IX Xref "TTYNAME_R_PROTO" |
| 17882 |
.IX Item "TTYNAME_R_PROTO" |
| 17883 |
This symbol encodes the prototype of \f(CW\*(C`ttyname_r\*(C'\fR. |
| 17884 |
It is zero if \f(CW\*(C`d_ttyname_r\*(C'\fR is undef, and one of the |
| 17885 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ttyname_r\*(C'\fR |
| 17886 |
is defined. |
| 17887 |
.SH "Reference-counted stack manipulation" |
| 17888 |
.IX Header "Reference-counted stack manipulation" |
| 17889 |
Functions for pushing and pulling items on the stack when the |
| 17890 |
stack is reference counted. They are intended as replacements |
| 17891 |
for the old PUSHs, POPi, EXTEND etc pp macros within pp |
| 17892 |
functions. |
| 17893 |
.ie n .IP """rpp_context""" 4 |
| 17894 |
.el .IP \f(CWrpp_context\fR 4 |
| 17895 |
.IX Xref "rpp_context" |
| 17896 |
.IX Item "rpp_context" |
| 17897 |
NOTE: \f(CW\*(C`rpp_context\*(C'\fR is \fBexperimental\fR and may change or be |
| 17898 |
removed without notice. |
| 17899 |
.Sp |
| 17900 |
Impose void, scalar or list context on the stack. |
| 17901 |
First, pop \f(CW\*(C`extra\*(C'\fR items off the stack, then when \f(CW\*(C`gimme\*(C'\fR is: |
| 17902 |
\&\f(CW\*(C`G_LIST\*(C'\fR: return as-is. |
| 17903 |
\&\f(CW\*(C`G_VOID\*(C'\fR: pop everything back to \f(CW\*(C`mark\*(C'\fR |
| 17904 |
\&\f(CW\*(C`G_SCALAR\*(C'\fR: move the top stack item (or \f(CW&PL_sv_undef\fR if none) to |
| 17905 |
\&\f(CW\*(C`mark+1\*(C'\fR and free everything above it. |
| 17906 |
.RS 4 |
| 17907 |
.Sp |
| 17908 |
.Vb 1 |
| 17909 |
\& void rpp_context(SV **mark, U8 gimme, SSize_t extra) |
| 17910 |
.Ve |
| 17911 |
.RE |
| 17912 |
.RS 4 |
| 17913 |
.RE |
| 17914 |
.ie n .IP """rpp_extend""" 4 |
| 17915 |
.el .IP \f(CWrpp_extend\fR 4 |
| 17916 |
.IX Xref "rpp_extend" |
| 17917 |
.IX Item "rpp_extend" |
| 17918 |
NOTE: \f(CW\*(C`rpp_extend\*(C'\fR is \fBexperimental\fR and may change or be |
| 17919 |
removed without notice. |
| 17920 |
.Sp |
| 17921 |
Ensures that there is space on the stack to push \f(CW\*(C`n\*(C'\fR items, extending it |
| 17922 |
if necessary. |
| 17923 |
.RS 4 |
| 17924 |
.Sp |
| 17925 |
.Vb 1 |
| 17926 |
\& void rpp_extend(SSize_t n) |
| 17927 |
.Ve |
| 17928 |
.RE |
| 17929 |
.RS 4 |
| 17930 |
.RE |
| 17931 |
.ie n .IP """rpp_invoke_xs""" 4 |
| 17932 |
.el .IP \f(CWrpp_invoke_xs\fR 4 |
| 17933 |
.IX Xref "rpp_invoke_xs" |
| 17934 |
.IX Item "rpp_invoke_xs" |
| 17935 |
NOTE: \f(CW\*(C`rpp_invoke_xs\*(C'\fR is \fBexperimental\fR and may change or be |
| 17936 |
removed without notice. |
| 17937 |
.Sp |
| 17938 |
Call the XS function associated with \f(CW\*(C`cv\*(C'\fR. Wraps the call if necessary to |
| 17939 |
handle XS functions which are not aware of reference-counted stacks. |
| 17940 |
.RS 4 |
| 17941 |
.Sp |
| 17942 |
.Vb 1 |
| 17943 |
\& void rpp_invoke_xs(CV *cv) |
| 17944 |
.Ve |
| 17945 |
.RE |
| 17946 |
.RS 4 |
| 17947 |
.RE |
| 17948 |
.ie n .IP """rpp_is_lone""" 4 |
| 17949 |
.el .IP \f(CWrpp_is_lone\fR 4 |
| 17950 |
.IX Xref "rpp_is_lone" |
| 17951 |
.IX Item "rpp_is_lone" |
| 17952 |
NOTE: \f(CW\*(C`rpp_is_lone\*(C'\fR is \fBexperimental\fR and may change or be |
| 17953 |
removed without notice. |
| 17954 |
.Sp |
| 17955 |
Indicates whether the stacked SV \f(CW\*(C`sv\*(C'\fR (assumed to be not yet popped off |
| 17956 |
the stack) is only kept alive due to a single reference from the argument |
| 17957 |
stack and/or and the temps stack. |
| 17958 |
.Sp |
| 17959 |
This can used for example to decide whether the copying of return values |
| 17960 |
in rvalue context can be skipped, or whether it shouldn't be assigned to |
| 17961 |
in lvalue context. |
| 17962 |
.RS 4 |
| 17963 |
.Sp |
| 17964 |
.Vb 1 |
| 17965 |
\& bool rpp_is_lone(SV *sv) |
| 17966 |
.Ve |
| 17967 |
.RE |
| 17968 |
.RS 4 |
| 17969 |
.RE |
| 17970 |
.ie n .IP """rpp_popfree_1_NN""" 4 |
| 17971 |
.el .IP \f(CWrpp_popfree_1_NN\fR 4 |
| 17972 |
.IX Xref "rpp_popfree_1_NN" |
| 17973 |
.IX Item "rpp_popfree_1_NN" |
| 17974 |
NOTE: \f(CW\*(C`rpp_popfree_1_NN\*(C'\fR is \fBexperimental\fR and may change or be |
| 17975 |
removed without notice. |
| 17976 |
.Sp |
| 17977 |
A variant of \fBrpp_popfree_1()\fR which assumes that the pointer being popped |
| 17978 |
off the stack is non-NULL. |
| 17979 |
.RS 4 |
| 17980 |
.Sp |
| 17981 |
.Vb 1 |
| 17982 |
\& void rpp_popfree_1_NN() |
| 17983 |
.Ve |
| 17984 |
.RE |
| 17985 |
.RS 4 |
| 17986 |
.RE |
| 17987 |
.ie n .IP """rpp_popfree_2_NN""" 4 |
| 17988 |
.el .IP \f(CWrpp_popfree_2_NN\fR 4 |
| 17989 |
.IX Xref "rpp_popfree_2_NN" |
| 17990 |
.IX Item "rpp_popfree_2_NN" |
| 17991 |
NOTE: \f(CW\*(C`rpp_popfree_2_NN\*(C'\fR is \fBexperimental\fR and may change or be |
| 17992 |
removed without notice. |
| 17993 |
.Sp |
| 17994 |
A variant of \fBrpp_popfree_2()\fR which assumes that the two pointers being |
| 17995 |
popped off the stack are non-NULL. |
| 17996 |
.RS 4 |
| 17997 |
.Sp |
| 17998 |
.Vb 1 |
| 17999 |
\& void rpp_popfree_2_NN() |
| 18000 |
.Ve |
| 18001 |
.RE |
| 18002 |
.RS 4 |
| 18003 |
.RE |
| 18004 |
.ie n .IP """rpp_popfree_to""" 4 |
| 18005 |
.el .IP \f(CWrpp_popfree_to\fR 4 |
| 18006 |
.IX Xref "rpp_popfree_to" |
| 18007 |
.IX Item "rpp_popfree_to" |
| 18008 |
NOTE: \f(CW\*(C`rpp_popfree_to\*(C'\fR is \fBexperimental\fR and may change or be |
| 18009 |
removed without notice. |
| 18010 |
.Sp |
| 18011 |
Pop and free all items on the argument stack above \f(CW\*(C`sp\*(C'\fR. On return, |
| 18012 |
\&\f(CW\*(C`PL_stack_sp\*(C'\fR will be equal to \f(CW\*(C`sp\*(C'\fR. |
| 18013 |
.RS 4 |
| 18014 |
.Sp |
| 18015 |
.Vb 1 |
| 18016 |
\& void rpp_popfree_to(SV **sp) |
| 18017 |
.Ve |
| 18018 |
.RE |
| 18019 |
.RS 4 |
| 18020 |
.RE |
| 18021 |
.ie n .IP """rpp_popfree_to_NN""" 4 |
| 18022 |
.el .IP \f(CWrpp_popfree_to_NN\fR 4 |
| 18023 |
.IX Xref "rpp_popfree_to_NN" |
| 18024 |
.IX Item "rpp_popfree_to_NN" |
| 18025 |
NOTE: \f(CW\*(C`rpp_popfree_to_NN\*(C'\fR is \fBexperimental\fR and may change or be |
| 18026 |
removed without notice. |
| 18027 |
.Sp |
| 18028 |
A variant of \fBrpp_popfree_to()\fR which assumes that all the pointers being |
| 18029 |
popped off the stack are non-NULL. |
| 18030 |
.RS 4 |
| 18031 |
.Sp |
| 18032 |
.Vb 1 |
| 18033 |
\& void rpp_popfree_to_NN(SV **sp) |
| 18034 |
.Ve |
| 18035 |
.RE |
| 18036 |
.RS 4 |
| 18037 |
.RE |
| 18038 |
.ie n .IP """rpp_popfree_1""" 4 |
| 18039 |
.el .IP \f(CWrpp_popfree_1\fR 4 |
| 18040 |
.IX Xref "rpp_popfree_1" |
| 18041 |
.IX Item "rpp_popfree_1" |
| 18042 |
NOTE: \f(CW\*(C`rpp_popfree_1\*(C'\fR is \fBexperimental\fR and may change or be |
| 18043 |
removed without notice. |
| 18044 |
.Sp |
| 18045 |
Pop and free the top item on the argument stack and update \f(CW\*(C`PL_stack_sp\*(C'\fR. |
| 18046 |
.RS 4 |
| 18047 |
.Sp |
| 18048 |
.Vb 1 |
| 18049 |
\& void rpp_popfree_1() |
| 18050 |
.Ve |
| 18051 |
.RE |
| 18052 |
.RS 4 |
| 18053 |
.RE |
| 18054 |
.ie n .IP """rpp_popfree_2""" 4 |
| 18055 |
.el .IP \f(CWrpp_popfree_2\fR 4 |
| 18056 |
.IX Xref "rpp_popfree_2" |
| 18057 |
.IX Item "rpp_popfree_2" |
| 18058 |
NOTE: \f(CW\*(C`rpp_popfree_2\*(C'\fR is \fBexperimental\fR and may change or be |
| 18059 |
removed without notice. |
| 18060 |
.Sp |
| 18061 |
Pop and free the top two items on the argument stack and update |
| 18062 |
\&\f(CW\*(C`PL_stack_sp\*(C'\fR. |
| 18063 |
.RS 4 |
| 18064 |
.Sp |
| 18065 |
.Vb 1 |
| 18066 |
\& void rpp_popfree_2() |
| 18067 |
.Ve |
| 18068 |
.RE |
| 18069 |
.RS 4 |
| 18070 |
.RE |
| 18071 |
.ie n .IP """rpp_pop_1_norc""" 4 |
| 18072 |
.el .IP \f(CWrpp_pop_1_norc\fR 4 |
| 18073 |
.IX Xref "rpp_pop_1_norc" |
| 18074 |
.IX Item "rpp_pop_1_norc" |
| 18075 |
NOTE: \f(CW\*(C`rpp_pop_1_norc\*(C'\fR is \fBexperimental\fR and may change or be |
| 18076 |
removed without notice. |
| 18077 |
.Sp |
| 18078 |
Pop and return the top item off the argument stack and update |
| 18079 |
\&\f(CW\*(C`PL_stack_sp\*(C'\fR. It's similar to \fBrpp_popfree_1()\fR, except that it actually |
| 18080 |
returns a value, and it \fIdoesn't\fR decrement the SV's reference count. |
| 18081 |
On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR builds it actually increments the SV's reference |
| 18082 |
count. |
| 18083 |
.Sp |
| 18084 |
This is useful in cases where the popped value is immediately embedded |
| 18085 |
somewhere e.g. via \fBav_store()\fR, allowing you skip decrementing and then |
| 18086 |
immediately incrementing the reference count again (and risk prematurely |
| 18087 |
freeing the SV if it had a RC of 1). On non-RC builds, the reference count |
| 18088 |
bookkeeping still works too, which is why it should be used rather than |
| 18089 |
a simple \f(CW\*(C`*PL_stack_sp\-\-\*(C'\fR. |
| 18090 |
.RS 4 |
| 18091 |
.Sp |
| 18092 |
.Vb 1 |
| 18093 |
\& SV * rpp_pop_1_norc() |
| 18094 |
.Ve |
| 18095 |
.RE |
| 18096 |
.RS 4 |
| 18097 |
.RE |
| 18098 |
.ie n .IP """rpp_push_1_norc""" 4 |
| 18099 |
.el .IP \f(CWrpp_push_1_norc\fR 4 |
| 18100 |
.IX Xref "rpp_push_1_norc" |
| 18101 |
.IX Item "rpp_push_1_norc" |
| 18102 |
NOTE: \f(CW\*(C`rpp_push_1_norc\*(C'\fR is \fBexperimental\fR and may change or be |
| 18103 |
removed without notice. |
| 18104 |
.Sp |
| 18105 |
Push \f(CW\*(C`sv\*(C'\fR onto the stack without incrementing its reference count, and |
| 18106 |
update \f(CW\*(C`PL_stack_sp\*(C'\fR. On non\-PERL_RC_STACK builds, mortalise too. |
| 18107 |
.Sp |
| 18108 |
This is most useful where an SV has just been created and already has a |
| 18109 |
reference count of 1, but has not yet been anchored anywhere. |
| 18110 |
.RS 4 |
| 18111 |
.Sp |
| 18112 |
.Vb 1 |
| 18113 |
\& void rpp_push_1_norc(SV *sv) |
| 18114 |
.Ve |
| 18115 |
.RE |
| 18116 |
.RS 4 |
| 18117 |
.RE |
| 18118 |
.ie n .IP """rpp_push_1""" 4 |
| 18119 |
.el .IP \f(CWrpp_push_1\fR 4 |
| 18120 |
.IX Item "rpp_push_1" |
| 18121 |
.PD 0 |
| 18122 |
.ie n .IP """rpp_push_IMM""" 4 |
| 18123 |
.el .IP \f(CWrpp_push_IMM\fR 4 |
| 18124 |
.IX Item "rpp_push_IMM" |
| 18125 |
.ie n .IP """rpp_push_2""" 4 |
| 18126 |
.el .IP \f(CWrpp_push_2\fR 4 |
| 18127 |
.IX Item "rpp_push_2" |
| 18128 |
.ie n .IP """rpp_xpush_1""" 4 |
| 18129 |
.el .IP \f(CWrpp_xpush_1\fR 4 |
| 18130 |
.IX Item "rpp_xpush_1" |
| 18131 |
.ie n .IP """rpp_xpush_IMM""" 4 |
| 18132 |
.el .IP \f(CWrpp_xpush_IMM\fR 4 |
| 18133 |
.IX Item "rpp_xpush_IMM" |
| 18134 |
.ie n .IP """rpp_xpush_2""" 4 |
| 18135 |
.el .IP \f(CWrpp_xpush_2\fR 4 |
| 18136 |
.IX Xref "rpp_push_1 rpp_push_IMM rpp_push_2 rpp_xpush_1 rpp_xpush_IMM rpp_xpush_2" |
| 18137 |
.IX Item "rpp_xpush_2" |
| 18138 |
.PD |
| 18139 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 18140 |
removed without notice. |
| 18141 |
.Sp |
| 18142 |
Push one or two SVs onto the stack, incrementing their reference counts |
| 18143 |
and updating \f(CW\*(C`PL_stack_sp\*(C'\fR. With the \f(CW\*(C`x\*(C'\fR variants, it extends the stack |
| 18144 |
first. The \f(CW\*(C`IMM\*(C'\fR variants assume that the single argument is an immortal |
| 18145 |
such as <&PL_sv_undef> and, for efficiency, will skip incrementing its |
| 18146 |
reference count. |
| 18147 |
.RS 4 |
| 18148 |
.Sp |
| 18149 |
.Vb 6 |
| 18150 |
\& void rpp_push_1 (SV *sv) |
| 18151 |
\& void rpp_push_IMM (SV *sv) |
| 18152 |
\& void rpp_push_2 (SV *sv1, SV *sv2) |
| 18153 |
\& void rpp_xpush_1 (SV *sv) |
| 18154 |
\& void rpp_xpush_IMM(SV *sv) |
| 18155 |
\& void rpp_xpush_2 (SV *sv1, SV *sv2) |
| 18156 |
.Ve |
| 18157 |
.RE |
| 18158 |
.RS 4 |
| 18159 |
.RE |
| 18160 |
.ie n .IP """rpp_replace_at""" 4 |
| 18161 |
.el .IP \f(CWrpp_replace_at\fR 4 |
| 18162 |
.IX Xref "rpp_replace_at" |
| 18163 |
.IX Item "rpp_replace_at" |
| 18164 |
NOTE: \f(CW\*(C`rpp_replace_at\*(C'\fR is \fBexperimental\fR and may change or be |
| 18165 |
removed without notice. |
| 18166 |
.Sp |
| 18167 |
Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably |
| 18168 |
adjusting reference counts. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR, except with proper |
| 18169 |
reference count handling. |
| 18170 |
.RS 4 |
| 18171 |
.Sp |
| 18172 |
.Vb 1 |
| 18173 |
\& void rpp_replace_at(SV **sp, SV *sv) |
| 18174 |
.Ve |
| 18175 |
.RE |
| 18176 |
.RS 4 |
| 18177 |
.RE |
| 18178 |
.ie n .IP """rpp_replace_at_NN""" 4 |
| 18179 |
.el .IP \f(CWrpp_replace_at_NN\fR 4 |
| 18180 |
.IX Xref "rpp_replace_at_NN" |
| 18181 |
.IX Item "rpp_replace_at_NN" |
| 18182 |
NOTE: \f(CW\*(C`rpp_replace_at_NN\*(C'\fR is \fBexperimental\fR and may change or be |
| 18183 |
removed without notice. |
| 18184 |
.Sp |
| 18185 |
A variant of \fBrpp_replace_at()\fR which assumes that the SV pointer on the |
| 18186 |
stack is non-NULL. |
| 18187 |
.RS 4 |
| 18188 |
.Sp |
| 18189 |
.Vb 1 |
| 18190 |
\& void rpp_replace_at_NN(SV **sp, SV *sv) |
| 18191 |
.Ve |
| 18192 |
.RE |
| 18193 |
.RS 4 |
| 18194 |
.RE |
| 18195 |
.ie n .IP """rpp_replace_at_norc""" 4 |
| 18196 |
.el .IP \f(CWrpp_replace_at_norc\fR 4 |
| 18197 |
.IX Xref "rpp_replace_at_norc" |
| 18198 |
.IX Item "rpp_replace_at_norc" |
| 18199 |
NOTE: \f(CW\*(C`rpp_replace_at_norc\*(C'\fR is \fBexperimental\fR and may change or be |
| 18200 |
removed without notice. |
| 18201 |
.Sp |
| 18202 |
Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably |
| 18203 |
adjusting the reference count of the old SV. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR, |
| 18204 |
except with proper reference count handling. |
| 18205 |
.Sp |
| 18206 |
\&\f(CW\*(C`sv\*(C'\fR's reference count doesn't get incremented. On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR |
| 18207 |
builds, it gets mortalised too. |
| 18208 |
.Sp |
| 18209 |
This is most useful where an SV has just been created and already has a |
| 18210 |
reference count of 1, but has not yet been anchored anywhere. |
| 18211 |
.RS 4 |
| 18212 |
.Sp |
| 18213 |
.Vb 1 |
| 18214 |
\& void rpp_replace_at_norc(SV **sp, SV *sv) |
| 18215 |
.Ve |
| 18216 |
.RE |
| 18217 |
.RS 4 |
| 18218 |
.RE |
| 18219 |
.ie n .IP """rpp_replace_at_norc_NN""" 4 |
| 18220 |
.el .IP \f(CWrpp_replace_at_norc_NN\fR 4 |
| 18221 |
.IX Xref "rpp_replace_at_norc_NN" |
| 18222 |
.IX Item "rpp_replace_at_norc_NN" |
| 18223 |
NOTE: \f(CW\*(C`rpp_replace_at_norc_NN\*(C'\fR is \fBexperimental\fR and may change or be |
| 18224 |
removed without notice. |
| 18225 |
.Sp |
| 18226 |
A variant of \fBrpp_replace_at_norc()\fR which assumes that the SV pointer on the |
| 18227 |
stack is non-NULL. |
| 18228 |
.RS 4 |
| 18229 |
.Sp |
| 18230 |
.Vb 1 |
| 18231 |
\& void rpp_replace_at_norc_NN(SV **sp, SV *sv) |
| 18232 |
.Ve |
| 18233 |
.RE |
| 18234 |
.RS 4 |
| 18235 |
.RE |
| 18236 |
.ie n .IP """rpp_replace_1_1""" 4 |
| 18237 |
.el .IP \f(CWrpp_replace_1_1\fR 4 |
| 18238 |
.IX Item "rpp_replace_1_1" |
| 18239 |
.PD 0 |
| 18240 |
.ie n .IP """rpp_replace_1_1_NN""" 4 |
| 18241 |
.el .IP \f(CWrpp_replace_1_1_NN\fR 4 |
| 18242 |
.IX Item "rpp_replace_1_1_NN" |
| 18243 |
.ie n .IP """rpp_replace_1_IMM_NN""" 4 |
| 18244 |
.el .IP \f(CWrpp_replace_1_IMM_NN\fR 4 |
| 18245 |
.IX Xref "rpp_replace_1_1 rpp_replace_1_1_NN rpp_replace_1_IMM_NN" |
| 18246 |
.IX Item "rpp_replace_1_IMM_NN" |
| 18247 |
.PD |
| 18248 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 18249 |
removed without notice. |
| 18250 |
.Sp |
| 18251 |
Replace the current top stack item with \f(CW\*(C`sv\*(C'\fR, while suitably adjusting |
| 18252 |
reference counts. Equivalent to \fBrpp_popfree_1()\fR; rpp_push_1(sv), but |
| 18253 |
is more efficient and handles both SVs being the same. |
| 18254 |
.Sp |
| 18255 |
The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointer on the stack to the SV being |
| 18256 |
freed is non-NULL. |
| 18257 |
.Sp |
| 18258 |
The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes |
| 18259 |
that the single argument is an immortal such as <&PL_sv_undef> and, for |
| 18260 |
efficiency, will skip incrementing its reference count. |
| 18261 |
.RS 4 |
| 18262 |
.Sp |
| 18263 |
.Vb 1 |
| 18264 |
\& void rpp_replace_1_1(SV *sv) |
| 18265 |
.Ve |
| 18266 |
.RE |
| 18267 |
.RS 4 |
| 18268 |
.RE |
| 18269 |
.ie n .IP """rpp_replace_2_1""" 4 |
| 18270 |
.el .IP \f(CWrpp_replace_2_1\fR 4 |
| 18271 |
.IX Item "rpp_replace_2_1" |
| 18272 |
.PD 0 |
| 18273 |
.ie n .IP """rpp_replace_2_1_NN""" 4 |
| 18274 |
.el .IP \f(CWrpp_replace_2_1_NN\fR 4 |
| 18275 |
.IX Item "rpp_replace_2_1_NN" |
| 18276 |
.ie n .IP """rpp_replace_2_IMM_NN""" 4 |
| 18277 |
.el .IP \f(CWrpp_replace_2_IMM_NN\fR 4 |
| 18278 |
.IX Xref "rpp_replace_2_1 rpp_replace_2_1_NN rpp_replace_2_IMM_NN" |
| 18279 |
.IX Item "rpp_replace_2_IMM_NN" |
| 18280 |
.PD |
| 18281 |
NOTE: all these forms are \fBexperimental\fR and may change or be |
| 18282 |
removed without notice. |
| 18283 |
.Sp |
| 18284 |
Replace the current top to stacks item with \f(CW\*(C`sv\*(C'\fR, while suitably |
| 18285 |
adjusting reference counts. Equivalent to \fBrpp_popfree_2()\fR; rpp_push_1(sv), |
| 18286 |
but is more efficient and handles SVs being the same. |
| 18287 |
.Sp |
| 18288 |
The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointers on the stack to the SVs being |
| 18289 |
freed are non-NULL. |
| 18290 |
.Sp |
| 18291 |
The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes |
| 18292 |
that the single argument is an immortal such as <&PL_sv_undef> and, for |
| 18293 |
efficiency, will skip incrementing its reference count. |
| 18294 |
.RS 4 |
| 18295 |
.Sp |
| 18296 |
.Vb 1 |
| 18297 |
\& void rpp_replace_2_1(SV *sv) |
| 18298 |
.Ve |
| 18299 |
.RE |
| 18300 |
.RS 4 |
| 18301 |
.RE |
| 18302 |
.ie n .IP """rpp_stack_is_rc""" 4 |
| 18303 |
.el .IP \f(CWrpp_stack_is_rc\fR 4 |
| 18304 |
.IX Xref "rpp_stack_is_rc" |
| 18305 |
.IX Item "rpp_stack_is_rc" |
| 18306 |
NOTE: \f(CW\*(C`rpp_stack_is_rc\*(C'\fR is \fBexperimental\fR and may change or be |
| 18307 |
removed without notice. |
| 18308 |
.Sp |
| 18309 |
Returns a boolean value indicating whether the stack is currently |
| 18310 |
reference-counted. Note that if the stack is split (bottom half RC, top |
| 18311 |
half non-RC), this function returns false, even if the top half currently |
| 18312 |
contains zero items. |
| 18313 |
.RS 4 |
| 18314 |
.Sp |
| 18315 |
.Vb 1 |
| 18316 |
\& bool rpp_stack_is_rc() |
| 18317 |
.Ve |
| 18318 |
.RE |
| 18319 |
.RS 4 |
| 18320 |
.RE |
| 18321 |
.ie n .IP """rpp_try_AMAGIC_1""" 4 |
| 18322 |
.el .IP \f(CWrpp_try_AMAGIC_1\fR 4 |
| 18323 |
.IX Item "rpp_try_AMAGIC_1" |
| 18324 |
.PD 0 |
| 18325 |
.ie n .IP """rpp_try_AMAGIC_2""" 4 |
| 18326 |
.el .IP \f(CWrpp_try_AMAGIC_2\fR 4 |
| 18327 |
.IX Xref "rpp_try_AMAGIC_1 rpp_try_AMAGIC_2" |
| 18328 |
.IX Item "rpp_try_AMAGIC_2" |
| 18329 |
.PD |
| 18330 |
NOTE: both forms are \fBexperimental\fR and may change or be |
| 18331 |
removed without notice. |
| 18332 |
.Sp |
| 18333 |
Check whether either of the one or two SVs at the top of the stack is |
| 18334 |
magical or a ref, and in either case handle it specially: invoke get |
| 18335 |
magic, call an overload method, or replace a ref with a temporary numeric |
| 18336 |
value, as appropriate. If this function returns true, it indicates that |
| 18337 |
the correct return value is already on the stack. Intended to be used at |
| 18338 |
the beginning of the PP function for unary or binary ops. |
| 18339 |
.RS 4 |
| 18340 |
.Sp |
| 18341 |
.Vb 1 |
| 18342 |
\& bool rpp_try_AMAGIC_1(int method, int flags) |
| 18343 |
.Ve |
| 18344 |
.RE |
| 18345 |
.RS 4 |
| 18346 |
.RE |
| 18347 |
.ie n .IP """XSPP_wrapped""" 4 |
| 18348 |
.el .IP \f(CWXSPP_wrapped\fR 4 |
| 18349 |
.IX Xref "XSPP_wrapped" |
| 18350 |
.IX Item "XSPP_wrapped" |
| 18351 |
NOTE: \f(CW\*(C`XSPP_wrapped\*(C'\fR is \fBexperimental\fR and may change or be |
| 18352 |
removed without notice. |
| 18353 |
.Sp |
| 18354 |
Declare and wrap a non-reference-counted PP-style function. |
| 18355 |
On traditional perl builds where the stack isn't reference-counted, this |
| 18356 |
just produces a function declaration like |
| 18357 |
.Sp |
| 18358 |
.Vb 1 |
| 18359 |
\& OP * xsppw_name(pTHX) |
| 18360 |
.Ve |
| 18361 |
.Sp |
| 18362 |
Conversely, in ref-counted builds it creates \fBxsppw_name()\fR as a small |
| 18363 |
wrapper function which calls the real function via a wrapper which |
| 18364 |
processes the args and return values to ensure that reference counts are |
| 18365 |
properly handled for code which uses old-style dSP, \fBPUSHs()\fR, \fBPOPs()\fR etc, |
| 18366 |
which don't adjust the reference counts of the items they manipulate. |
| 18367 |
.Sp |
| 18368 |
xsppw_nargs indicates how many arguments the function consumes off the |
| 18369 |
stack. It can be a constant value or an expression, such as |
| 18370 |
.Sp |
| 18371 |
.Vb 1 |
| 18372 |
\& ((PL_op\->op_flags & OPf_STACKED) ? 2 : 1) |
| 18373 |
.Ve |
| 18374 |
.Sp |
| 18375 |
Alternatively if xsppw_nlists is 1, it indicates that the PP function |
| 18376 |
consumes a list (or \- rarely \- if 2, consumes two lists, like |
| 18377 |
\&\fBpp_aassign()\fR), as indicated by the top markstack position. |
| 18378 |
.Sp |
| 18379 |
This is intended as a temporary fix when converting XS code to run under |
| 18380 |
PERL_RC_STACK builds. In the longer term, the PP function should be |
| 18381 |
rewritten to replace \fBPUSHs()\fR etc with \fBrpp_push_1()\fR etc. |
| 18382 |
.RS 4 |
| 18383 |
.Sp |
| 18384 |
.Vb 1 |
| 18385 |
\& XSPP_wrapped(xsppw_name, I32 xsppw_nargs, I32 xsppw_nlists) |
| 18386 |
.Ve |
| 18387 |
.RE |
| 18388 |
.RS 4 |
| 18389 |
.RE |
| 18390 |
.SH "REGEXP Functions" |
| 18391 |
.IX Xref "RX_OFFS_END RX_OFFS_START RX_OFFS_VALID RXp_OFFS_END RXp_OFFS_START RXp_OFFS_VALID" |
| 18392 |
.IX Header "REGEXP Functions" |
| 18393 |
.ie n .IP """pregcomp""" 4 |
| 18394 |
.el .IP \f(CWpregcomp\fR 4 |
| 18395 |
.IX Item "pregcomp" |
| 18396 |
Described in perlreguts. |
| 18397 |
.RS 4 |
| 18398 |
.Sp |
| 18399 |
.Vb 1 |
| 18400 |
\& REGEXP * pregcomp(SV * const pattern, const U32 flags) |
| 18401 |
.Ve |
| 18402 |
.RE |
| 18403 |
.RS 4 |
| 18404 |
.RE |
| 18405 |
.ie n .IP """pregexec""" 4 |
| 18406 |
.el .IP \f(CWpregexec\fR 4 |
| 18407 |
.IX Item "pregexec" |
| 18408 |
Described in perlreguts. |
| 18409 |
.RS 4 |
| 18410 |
.Sp |
| 18411 |
.Vb 3 |
| 18412 |
\& I32 pregexec(REGEXP * const prog, char *stringarg, char *strend, |
| 18413 |
\& char *strbeg, SSize_t minend, SV *screamer, |
| 18414 |
\& U32 nosave) |
| 18415 |
.Ve |
| 18416 |
.RE |
| 18417 |
.RS 4 |
| 18418 |
.RE |
| 18419 |
.ie n .IP """re_compile""" 4 |
| 18420 |
.el .IP \f(CWre_compile\fR 4 |
| 18421 |
.IX Xref "re_compile" |
| 18422 |
.IX Item "re_compile" |
| 18423 |
Compile the regular expression pattern \f(CW\*(C`pattern\*(C'\fR, returning a pointer to the |
| 18424 |
compiled object for later matching with the internal regex engine. |
| 18425 |
.Sp |
| 18426 |
This function is typically used by a custom regexp engine \f(CW\*(C`.comp()\*(C'\fR function |
| 18427 |
to hand off to the core regexp engine those patterns it doesn't want to handle |
| 18428 |
itself (typically passing through the same flags it was called with). In |
| 18429 |
almost all other cases, a regexp should be compiled by calling "\f(CW\*(C`pregcomp\*(C'\fR" |
| 18430 |
to compile using the currently active regexp engine. |
| 18431 |
.Sp |
| 18432 |
If \f(CW\*(C`pattern\*(C'\fR is already a \f(CW\*(C`REGEXP\*(C'\fR, this function does nothing but return a |
| 18433 |
pointer to the input. Otherwise the PV is extracted and treated like a string |
| 18434 |
representing a pattern. See perlre. |
| 18435 |
.Sp |
| 18436 |
The possible flags for \f(CW\*(C`rx_flags\*(C'\fR are documented in perlreapi. Their names |
| 18437 |
all begin with \f(CW\*(C`RXf_\*(C'\fR. |
| 18438 |
.RS 4 |
| 18439 |
.Sp |
| 18440 |
.Vb 1 |
| 18441 |
\& REGEXP * re_compile(SV * const pattern, U32 orig_rx_flags) |
| 18442 |
.Ve |
| 18443 |
.RE |
| 18444 |
.RS 4 |
| 18445 |
.RE |
| 18446 |
.ie n .IP """re_dup_guts""" 4 |
| 18447 |
.el .IP \f(CWre_dup_guts\fR 4 |
| 18448 |
.IX Xref "re_dup_guts" |
| 18449 |
.IX Item "re_dup_guts" |
| 18450 |
Duplicate a regexp. |
| 18451 |
.Sp |
| 18452 |
This routine is expected to clone a given regexp structure. It is only |
| 18453 |
compiled under USE_ITHREADS. |
| 18454 |
.Sp |
| 18455 |
After all of the core data stored in struct regexp is duplicated |
| 18456 |
the \f(CW\*(C`regexp_engine.dupe\*(C'\fR method is used to copy any private data |
| 18457 |
stored in the *pprivate pointer. This allows extensions to handle |
| 18458 |
any duplication they need to do. |
| 18459 |
.RS 4 |
| 18460 |
.Sp |
| 18461 |
.Vb 2 |
| 18462 |
\& void re_dup_guts(const REGEXP *sstr, REGEXP *dstr, |
| 18463 |
\& CLONE_PARAMS *param) |
| 18464 |
.Ve |
| 18465 |
.RE |
| 18466 |
.RS 4 |
| 18467 |
.RE |
| 18468 |
.ie n .IP """REGEX_LOCALE_CHARSET""" 4 |
| 18469 |
.el .IP \f(CWREGEX_LOCALE_CHARSET\fR 4 |
| 18470 |
.IX Item "REGEX_LOCALE_CHARSET" |
| 18471 |
Described in perlreapi. |
| 18472 |
.ie n .IP """REGEXP""" 4 |
| 18473 |
.el .IP \f(CWREGEXP\fR 4 |
| 18474 |
.IX Item "REGEXP" |
| 18475 |
Described in perlreapi. |
| 18476 |
.ie n .IP """regexp_engine""" 4 |
| 18477 |
.el .IP \f(CWregexp_engine\fR 4 |
| 18478 |
.IX Xref "regexp_engine" |
| 18479 |
.IX Item "regexp_engine" |
| 18480 |
When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at |
| 18481 |
the appropriate structure, so that when it needs to be used Perl can find |
| 18482 |
the right routines to do so. |
| 18483 |
.Sp |
| 18484 |
In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set |
| 18485 |
to an integer which (when casted appropriately) resolves to one of these |
| 18486 |
structures. When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the |
| 18487 |
resulting \f(CW\*(C`regexp\*(C'\fR structure's engine field is expected to point back at |
| 18488 |
the same structure. |
| 18489 |
.Sp |
| 18490 |
The pTHX_ symbol in the definition is a macro used by Perl under threading |
| 18491 |
to provide an extra argument to the routine holding a pointer back to |
| 18492 |
the interpreter that is executing the regexp. So under threading all |
| 18493 |
routines get an extra argument. |
| 18494 |
.ie n .IP """regexp_paren_pair""" 4 |
| 18495 |
.el .IP \f(CWregexp_paren_pair\fR 4 |
| 18496 |
.IX Item "regexp_paren_pair" |
| 18497 |
Described in perlreapi. |
| 18498 |
.ie n .IP """regmatch_info""" 4 |
| 18499 |
.el .IP \f(CWregmatch_info\fR 4 |
| 18500 |
.IX Xref "regmatch_info" |
| 18501 |
.IX Item "regmatch_info" |
| 18502 |
Some basic information about the current match that is created by |
| 18503 |
Perl_regexec_flags and then passed to \fBregtry()\fR, \fBregmatch()\fR etc. |
| 18504 |
It is allocated as a local var on the stack, so nothing should be |
| 18505 |
stored in it that needs preserving or clearing up on \fBcroak()\fR. |
| 18506 |
For that, see the aux_info and aux_info_eval members of the |
| 18507 |
regmatch_state union. |
| 18508 |
.ie n .IP """REXEC_COPY_SKIP_POST""" 4 |
| 18509 |
.el .IP \f(CWREXEC_COPY_SKIP_POST\fR 4 |
| 18510 |
.IX Item "REXEC_COPY_SKIP_POST" |
| 18511 |
.PD 0 |
| 18512 |
.ie n .IP """REXEC_COPY_SKIP_PRE""" 4 |
| 18513 |
.el .IP \f(CWREXEC_COPY_SKIP_PRE\fR 4 |
| 18514 |
.IX Item "REXEC_COPY_SKIP_PRE" |
| 18515 |
.ie n .IP """REXEC_COPY_STR""" 4 |
| 18516 |
.el .IP \f(CWREXEC_COPY_STR\fR 4 |
| 18517 |
.IX Item "REXEC_COPY_STR" |
| 18518 |
.PD |
| 18519 |
Described in perlreapi. |
| 18520 |
.ie n .IP """RXapif_ALL""" 4 |
| 18521 |
.el .IP \f(CWRXapif_ALL\fR 4 |
| 18522 |
.IX Item "RXapif_ALL" |
| 18523 |
.PD 0 |
| 18524 |
.ie n .IP """RXapif_CLEAR""" 4 |
| 18525 |
.el .IP \f(CWRXapif_CLEAR\fR 4 |
| 18526 |
.IX Item "RXapif_CLEAR" |
| 18527 |
.ie n .IP """RXapif_DELETE""" 4 |
| 18528 |
.el .IP \f(CWRXapif_DELETE\fR 4 |
| 18529 |
.IX Item "RXapif_DELETE" |
| 18530 |
.ie n .IP """RXapif_EXISTS""" 4 |
| 18531 |
.el .IP \f(CWRXapif_EXISTS\fR 4 |
| 18532 |
.IX Item "RXapif_EXISTS" |
| 18533 |
.ie n .IP """RXapif_FETCH""" 4 |
| 18534 |
.el .IP \f(CWRXapif_FETCH\fR 4 |
| 18535 |
.IX Item "RXapif_FETCH" |
| 18536 |
.ie n .IP """RXapif_FIRSTKEY""" 4 |
| 18537 |
.el .IP \f(CWRXapif_FIRSTKEY\fR 4 |
| 18538 |
.IX Item "RXapif_FIRSTKEY" |
| 18539 |
.ie n .IP """RXapif_NEXTKEY""" 4 |
| 18540 |
.el .IP \f(CWRXapif_NEXTKEY\fR 4 |
| 18541 |
.IX Item "RXapif_NEXTKEY" |
| 18542 |
.ie n .IP """RXapif_ONE""" 4 |
| 18543 |
.el .IP \f(CWRXapif_ONE\fR 4 |
| 18544 |
.IX Item "RXapif_ONE" |
| 18545 |
.ie n .IP """RXapif_REGNAME""" 4 |
| 18546 |
.el .IP \f(CWRXapif_REGNAME\fR 4 |
| 18547 |
.IX Item "RXapif_REGNAME" |
| 18548 |
.ie n .IP """RXapif_REGNAMES""" 4 |
| 18549 |
.el .IP \f(CWRXapif_REGNAMES\fR 4 |
| 18550 |
.IX Item "RXapif_REGNAMES" |
| 18551 |
.ie n .IP """RXapif_REGNAMES_COUNT""" 4 |
| 18552 |
.el .IP \f(CWRXapif_REGNAMES_COUNT\fR 4 |
| 18553 |
.IX Item "RXapif_REGNAMES_COUNT" |
| 18554 |
.ie n .IP """RXapif_SCALAR""" 4 |
| 18555 |
.el .IP \f(CWRXapif_SCALAR\fR 4 |
| 18556 |
.IX Item "RXapif_SCALAR" |
| 18557 |
.ie n .IP """RXapif_STORE""" 4 |
| 18558 |
.el .IP \f(CWRXapif_STORE\fR 4 |
| 18559 |
.IX Item "RXapif_STORE" |
| 18560 |
.PD |
| 18561 |
Described in perlreapi. |
| 18562 |
.ie n .IP """RX_BUFF_IDX_CARET_FULLMATCH""" 4 |
| 18563 |
.el .IP \f(CWRX_BUFF_IDX_CARET_FULLMATCH\fR 4 |
| 18564 |
.IX Item "RX_BUFF_IDX_CARET_FULLMATCH" |
| 18565 |
.PD 0 |
| 18566 |
.ie n .IP """RX_BUFF_IDX_CARET_POSTMATCH""" 4 |
| 18567 |
.el .IP \f(CWRX_BUFF_IDX_CARET_POSTMATCH\fR 4 |
| 18568 |
.IX Item "RX_BUFF_IDX_CARET_POSTMATCH" |
| 18569 |
.ie n .IP """RX_BUFF_IDX_CARET_PREMATCH""" 4 |
| 18570 |
.el .IP \f(CWRX_BUFF_IDX_CARET_PREMATCH\fR 4 |
| 18571 |
.IX Item "RX_BUFF_IDX_CARET_PREMATCH" |
| 18572 |
.ie n .IP """RX_BUFF_IDX_FULLMATCH""" 4 |
| 18573 |
.el .IP \f(CWRX_BUFF_IDX_FULLMATCH\fR 4 |
| 18574 |
.IX Item "RX_BUFF_IDX_FULLMATCH" |
| 18575 |
.ie n .IP """RX_BUFF_IDX_POSTMATCH""" 4 |
| 18576 |
.el .IP \f(CWRX_BUFF_IDX_POSTMATCH\fR 4 |
| 18577 |
.IX Item "RX_BUFF_IDX_POSTMATCH" |
| 18578 |
.ie n .IP """RX_BUFF_IDX_PREMATCH""" 4 |
| 18579 |
.el .IP \f(CWRX_BUFF_IDX_PREMATCH\fR 4 |
| 18580 |
.IX Item "RX_BUFF_IDX_PREMATCH" |
| 18581 |
.PD |
| 18582 |
Described in perlreapi. |
| 18583 |
.ie n .IP """RXf_NO_INPLACE_SUBST""" 4 |
| 18584 |
.el .IP \f(CWRXf_NO_INPLACE_SUBST\fR 4 |
| 18585 |
.IX Item "RXf_NO_INPLACE_SUBST" |
| 18586 |
.PD 0 |
| 18587 |
.ie n .IP """RXf_NULL""" 4 |
| 18588 |
.el .IP \f(CWRXf_NULL\fR 4 |
| 18589 |
.IX Item "RXf_NULL" |
| 18590 |
.ie n .IP """RXf_SKIPWHITE""" 4 |
| 18591 |
.el .IP \f(CWRXf_SKIPWHITE\fR 4 |
| 18592 |
.IX Item "RXf_SKIPWHITE" |
| 18593 |
.ie n .IP """RXf_SPLIT""" 4 |
| 18594 |
.el .IP \f(CWRXf_SPLIT\fR 4 |
| 18595 |
.IX Item "RXf_SPLIT" |
| 18596 |
.ie n .IP """RXf_START_ONLY""" 4 |
| 18597 |
.el .IP \f(CWRXf_START_ONLY\fR 4 |
| 18598 |
.IX Item "RXf_START_ONLY" |
| 18599 |
.ie n .IP """RXf_WHITE""" 4 |
| 18600 |
.el .IP \f(CWRXf_WHITE\fR 4 |
| 18601 |
.IX Item "RXf_WHITE" |
| 18602 |
.PD |
| 18603 |
Described in perlreapi. |
| 18604 |
.ie n .IP """RXf_PMf_EXTENDED""" 4 |
| 18605 |
.el .IP \f(CWRXf_PMf_EXTENDED\fR 4 |
| 18606 |
.IX Item "RXf_PMf_EXTENDED" |
| 18607 |
.PD 0 |
| 18608 |
.ie n .IP """RXf_PMf_FOLD""" 4 |
| 18609 |
.el .IP \f(CWRXf_PMf_FOLD\fR 4 |
| 18610 |
.IX Item "RXf_PMf_FOLD" |
| 18611 |
.ie n .IP """RXf_PMf_KEEPCOPY""" 4 |
| 18612 |
.el .IP \f(CWRXf_PMf_KEEPCOPY\fR 4 |
| 18613 |
.IX Item "RXf_PMf_KEEPCOPY" |
| 18614 |
.ie n .IP """RXf_PMf_MULTILINE""" 4 |
| 18615 |
.el .IP \f(CWRXf_PMf_MULTILINE\fR 4 |
| 18616 |
.IX Item "RXf_PMf_MULTILINE" |
| 18617 |
.ie n .IP """RXf_PMf_SINGLELINE""" 4 |
| 18618 |
.el .IP \f(CWRXf_PMf_SINGLELINE\fR 4 |
| 18619 |
.IX Item "RXf_PMf_SINGLELINE" |
| 18620 |
.PD |
| 18621 |
Described in perlreapi. |
| 18622 |
.ie n .IP """RX_MATCH_COPIED""" 4 |
| 18623 |
.el .IP \f(CWRX_MATCH_COPIED\fR 4 |
| 18624 |
.IX Item "RX_MATCH_COPIED" |
| 18625 |
Described in perlreapi. |
| 18626 |
.RS 4 |
| 18627 |
.Sp |
| 18628 |
.Vb 1 |
| 18629 |
\& RX_MATCH_COPIED(const REGEXP * rx_sv) |
| 18630 |
.Ve |
| 18631 |
.RE |
| 18632 |
.RS 4 |
| 18633 |
.RE |
| 18634 |
.ie n .IP """struct regexp""" 4 |
| 18635 |
.el .IP "\f(CWstruct regexp\fR" 4 |
| 18636 |
.IX Item "struct regexp" |
| 18637 |
Described in perlreapi. |
| 18638 |
.ie n .IP """SvRX""" 4 |
| 18639 |
.el .IP \f(CWSvRX\fR 4 |
| 18640 |
.IX Xref "SvRX" |
| 18641 |
.IX Item "SvRX" |
| 18642 |
Convenience macro to get the REGEXP from a SV. This is approximately |
| 18643 |
equivalent to the following snippet: |
| 18644 |
.Sp |
| 18645 |
.Vb 6 |
| 18646 |
\& if (SvMAGICAL(sv)) |
| 18647 |
\& mg_get(sv); |
| 18648 |
\& if (SvROK(sv)) |
| 18649 |
\& sv = MUTABLE_SV(SvRV(sv)); |
| 18650 |
\& if (SvTYPE(sv) == SVt_REGEXP) |
| 18651 |
\& return (REGEXP*) sv; |
| 18652 |
.Ve |
| 18653 |
.Sp |
| 18654 |
\&\f(CW\*(C`NULL\*(C'\fR will be returned if a REGEXP* is not found. |
| 18655 |
.RS 4 |
| 18656 |
.Sp |
| 18657 |
.Vb 1 |
| 18658 |
\& REGEXP * SvRX(SV *sv) |
| 18659 |
.Ve |
| 18660 |
.RE |
| 18661 |
.RS 4 |
| 18662 |
.RE |
| 18663 |
.ie n .IP """SvRXOK""" 4 |
| 18664 |
.el .IP \f(CWSvRXOK\fR 4 |
| 18665 |
.IX Xref "SvRXOK" |
| 18666 |
.IX Item "SvRXOK" |
| 18667 |
Returns a boolean indicating whether the SV (or the one it references) |
| 18668 |
is a REGEXP. |
| 18669 |
.Sp |
| 18670 |
If you want to do something with the REGEXP* later use SvRX instead |
| 18671 |
and check for NULL. |
| 18672 |
.RS 4 |
| 18673 |
.Sp |
| 18674 |
.Vb 1 |
| 18675 |
\& bool SvRXOK(SV* sv) |
| 18676 |
.Ve |
| 18677 |
.RE |
| 18678 |
.RS 4 |
| 18679 |
.RE |
| 18680 |
.ie n .IP """SV_SAVED_COPY""" 4 |
| 18681 |
.el .IP \f(CWSV_SAVED_COPY\fR 4 |
| 18682 |
.IX Item "SV_SAVED_COPY" |
| 18683 |
Described in perlreapi. |
| 18684 |
.SH "Reports and Formats" |
| 18685 |
.IX Header "Reports and Formats" |
| 18686 |
These are used in the simple report generation feature of Perl. |
| 18687 |
See perlform. |
| 18688 |
.ie n .IP """IoBOTTOM_GV""" 4 |
| 18689 |
.el .IP \f(CWIoBOTTOM_GV\fR 4 |
| 18690 |
.IX Item "IoBOTTOM_GV" |
| 18691 |
Described in perlguts. |
| 18692 |
.RS 4 |
| 18693 |
.Sp |
| 18694 |
.Vb 1 |
| 18695 |
\& GV * IoBOTTOM_GV(IO *io) |
| 18696 |
.Ve |
| 18697 |
.RE |
| 18698 |
.RS 4 |
| 18699 |
.RE |
| 18700 |
.ie n .IP """IoBOTTOM_NAME""" 4 |
| 18701 |
.el .IP \f(CWIoBOTTOM_NAME\fR 4 |
| 18702 |
.IX Item "IoBOTTOM_NAME" |
| 18703 |
Described in perlguts. |
| 18704 |
.RS 4 |
| 18705 |
.Sp |
| 18706 |
.Vb 1 |
| 18707 |
\& char * IoBOTTOM_NAME(IO *io) |
| 18708 |
.Ve |
| 18709 |
.RE |
| 18710 |
.RS 4 |
| 18711 |
.RE |
| 18712 |
.ie n .IP """IoFMT_GV""" 4 |
| 18713 |
.el .IP \f(CWIoFMT_GV\fR 4 |
| 18714 |
.IX Item "IoFMT_GV" |
| 18715 |
Described in perlguts. |
| 18716 |
.RS 4 |
| 18717 |
.Sp |
| 18718 |
.Vb 1 |
| 18719 |
\& GV * IoFMT_GV(IO *io) |
| 18720 |
.Ve |
| 18721 |
.RE |
| 18722 |
.RS 4 |
| 18723 |
.RE |
| 18724 |
.ie n .IP """IoFMT_NAME""" 4 |
| 18725 |
.el .IP \f(CWIoFMT_NAME\fR 4 |
| 18726 |
.IX Item "IoFMT_NAME" |
| 18727 |
Described in perlguts. |
| 18728 |
.RS 4 |
| 18729 |
.Sp |
| 18730 |
.Vb 1 |
| 18731 |
\& char * IoFMT_NAME(IO *io) |
| 18732 |
.Ve |
| 18733 |
.RE |
| 18734 |
.RS 4 |
| 18735 |
.RE |
| 18736 |
.ie n .IP """IoLINES""" 4 |
| 18737 |
.el .IP \f(CWIoLINES\fR 4 |
| 18738 |
.IX Item "IoLINES" |
| 18739 |
Described in perlguts. |
| 18740 |
.RS 4 |
| 18741 |
.Sp |
| 18742 |
.Vb 1 |
| 18743 |
\& IV IoLINES(IO *io) |
| 18744 |
.Ve |
| 18745 |
.RE |
| 18746 |
.RS 4 |
| 18747 |
.RE |
| 18748 |
.ie n .IP """IoLINES_LEFT""" 4 |
| 18749 |
.el .IP \f(CWIoLINES_LEFT\fR 4 |
| 18750 |
.IX Item "IoLINES_LEFT" |
| 18751 |
Described in perlguts. |
| 18752 |
.RS 4 |
| 18753 |
.Sp |
| 18754 |
.Vb 1 |
| 18755 |
\& IV IoLINES_LEFT(IO *io) |
| 18756 |
.Ve |
| 18757 |
.RE |
| 18758 |
.RS 4 |
| 18759 |
.RE |
| 18760 |
.ie n .IP """IoPAGE""" 4 |
| 18761 |
.el .IP \f(CWIoPAGE\fR 4 |
| 18762 |
.IX Item "IoPAGE" |
| 18763 |
Described in perlguts. |
| 18764 |
.RS 4 |
| 18765 |
.Sp |
| 18766 |
.Vb 1 |
| 18767 |
\& IV IoPAGE(IO *io) |
| 18768 |
.Ve |
| 18769 |
.RE |
| 18770 |
.RS 4 |
| 18771 |
.RE |
| 18772 |
.ie n .IP """IoPAGE_LEN""" 4 |
| 18773 |
.el .IP \f(CWIoPAGE_LEN\fR 4 |
| 18774 |
.IX Item "IoPAGE_LEN" |
| 18775 |
Described in perlguts. |
| 18776 |
.RS 4 |
| 18777 |
.Sp |
| 18778 |
.Vb 1 |
| 18779 |
\& IV IoPAGE_LEN(IO *io) |
| 18780 |
.Ve |
| 18781 |
.RE |
| 18782 |
.RS 4 |
| 18783 |
.RE |
| 18784 |
.ie n .IP """IoTOP_GV""" 4 |
| 18785 |
.el .IP \f(CWIoTOP_GV\fR 4 |
| 18786 |
.IX Item "IoTOP_GV" |
| 18787 |
Described in perlguts. |
| 18788 |
.RS 4 |
| 18789 |
.Sp |
| 18790 |
.Vb 1 |
| 18791 |
\& GV * IoTOP_GV(IO *io) |
| 18792 |
.Ve |
| 18793 |
.RE |
| 18794 |
.RS 4 |
| 18795 |
.RE |
| 18796 |
.ie n .IP """IoTOP_NAME""" 4 |
| 18797 |
.el .IP \f(CWIoTOP_NAME\fR 4 |
| 18798 |
.IX Item "IoTOP_NAME" |
| 18799 |
Described in perlguts. |
| 18800 |
.RS 4 |
| 18801 |
.Sp |
| 18802 |
.Vb 1 |
| 18803 |
\& char * IoTOP_NAME(IO *io) |
| 18804 |
.Ve |
| 18805 |
.RE |
| 18806 |
.RS 4 |
| 18807 |
.RE |
| 18808 |
.SH Signals |
| 18809 |
.IX Header "Signals" |
| 18810 |
.ie n .IP """HAS_SIGINFO_SI_ADDR""" 4 |
| 18811 |
.el .IP \f(CWHAS_SIGINFO_SI_ADDR\fR 4 |
| 18812 |
.IX Xref "HAS_SIGINFO_SI_ADDR" |
| 18813 |
.IX Item "HAS_SIGINFO_SI_ADDR" |
| 18814 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18815 |
\&\f(CW\*(C`si_addr\*(C'\fR member |
| 18816 |
.ie n .IP """HAS_SIGINFO_SI_BAND""" 4 |
| 18817 |
.el .IP \f(CWHAS_SIGINFO_SI_BAND\fR 4 |
| 18818 |
.IX Xref "HAS_SIGINFO_SI_BAND" |
| 18819 |
.IX Item "HAS_SIGINFO_SI_BAND" |
| 18820 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18821 |
\&\f(CW\*(C`si_band\*(C'\fR member |
| 18822 |
.ie n .IP """HAS_SIGINFO_SI_ERRNO""" 4 |
| 18823 |
.el .IP \f(CWHAS_SIGINFO_SI_ERRNO\fR 4 |
| 18824 |
.IX Xref "HAS_SIGINFO_SI_ERRNO" |
| 18825 |
.IX Item "HAS_SIGINFO_SI_ERRNO" |
| 18826 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18827 |
\&\f(CW\*(C`si_errno\*(C'\fR member |
| 18828 |
.ie n .IP """HAS_SIGINFO_SI_PID""" 4 |
| 18829 |
.el .IP \f(CWHAS_SIGINFO_SI_PID\fR 4 |
| 18830 |
.IX Xref "HAS_SIGINFO_SI_PID" |
| 18831 |
.IX Item "HAS_SIGINFO_SI_PID" |
| 18832 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18833 |
\&\f(CW\*(C`si_pid\*(C'\fR member |
| 18834 |
.ie n .IP """HAS_SIGINFO_SI_STATUS""" 4 |
| 18835 |
.el .IP \f(CWHAS_SIGINFO_SI_STATUS\fR 4 |
| 18836 |
.IX Xref "HAS_SIGINFO_SI_STATUS" |
| 18837 |
.IX Item "HAS_SIGINFO_SI_STATUS" |
| 18838 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18839 |
\&\f(CW\*(C`si_status\*(C'\fR member |
| 18840 |
.ie n .IP """HAS_SIGINFO_SI_UID""" 4 |
| 18841 |
.el .IP \f(CWHAS_SIGINFO_SI_UID\fR 4 |
| 18842 |
.IX Xref "HAS_SIGINFO_SI_UID" |
| 18843 |
.IX Item "HAS_SIGINFO_SI_UID" |
| 18844 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18845 |
\&\f(CW\*(C`si_uid\*(C'\fR member |
| 18846 |
.ie n .IP """HAS_SIGINFO_SI_VALUE""" 4 |
| 18847 |
.el .IP \f(CWHAS_SIGINFO_SI_VALUE\fR 4 |
| 18848 |
.IX Xref "HAS_SIGINFO_SI_VALUE" |
| 18849 |
.IX Item "HAS_SIGINFO_SI_VALUE" |
| 18850 |
This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the |
| 18851 |
\&\f(CW\*(C`si_value\*(C'\fR member |
| 18852 |
.ie n .IP """PERL_SIGNALS_UNSAFE_FLAG""" 4 |
| 18853 |
.el .IP \f(CWPERL_SIGNALS_UNSAFE_FLAG\fR 4 |
| 18854 |
.IX Xref "PERL_SIGNALS_UNSAFE_FLAG" |
| 18855 |
.IX Item "PERL_SIGNALS_UNSAFE_FLAG" |
| 18856 |
If this bit in \f(CW\*(C`PL_signals\*(C'\fR is set, the system is uing the pre-Perl 5.8 |
| 18857 |
unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred Signals |
| 18858 |
(Safe Signals)" in perlipc. |
| 18859 |
.RS 4 |
| 18860 |
.Sp |
| 18861 |
.Vb 1 |
| 18862 |
\& U32 PERL_SIGNALS_UNSAFE_FLAG |
| 18863 |
.Ve |
| 18864 |
.RE |
| 18865 |
.RS 4 |
| 18866 |
.RE |
| 18867 |
.ie n .IP """rsignal""" 4 |
| 18868 |
.el .IP \f(CWrsignal\fR 4 |
| 18869 |
.IX Xref "rsignal" |
| 18870 |
.IX Item "rsignal" |
| 18871 |
A wrapper for the C library functions \fBsigaction\fR\|(2) or \fBsignal\fR\|(2). |
| 18872 |
Use this instead of those libc functions, as the Perl version gives the |
| 18873 |
safest available implementation, and knows things that interact with the |
| 18874 |
rest of the perl interpreter. |
| 18875 |
.RS 4 |
| 18876 |
.Sp |
| 18877 |
.Vb 1 |
| 18878 |
\& Sighandler_t rsignal(int i, Sighandler_t t) |
| 18879 |
.Ve |
| 18880 |
.RE |
| 18881 |
.RS 4 |
| 18882 |
.RE |
| 18883 |
.ie n .IP """rsignal_state""" 4 |
| 18884 |
.el .IP \f(CWrsignal_state\fR 4 |
| 18885 |
.IX Xref "rsignal_state" |
| 18886 |
.IX Item "rsignal_state" |
| 18887 |
Returns a the current signal handler for signal \f(CW\*(C`signo\*(C'\fR. |
| 18888 |
See "\f(CW\*(C`rsignal\*(C'\fR". |
| 18889 |
.RS 4 |
| 18890 |
.Sp |
| 18891 |
.Vb 1 |
| 18892 |
\& Sighandler_t rsignal_state(int i) |
| 18893 |
.Ve |
| 18894 |
.RE |
| 18895 |
.RS 4 |
| 18896 |
.RE |
| 18897 |
.ie n .IP """Sigjmp_buf""" 4 |
| 18898 |
.el .IP \f(CWSigjmp_buf\fR 4 |
| 18899 |
.IX Xref "Sigjmp_buf" |
| 18900 |
.IX Item "Sigjmp_buf" |
| 18901 |
This is the buffer type to be used with Sigsetjmp and Siglongjmp. |
| 18902 |
.ie n .IP """Siglongjmp""" 4 |
| 18903 |
.el .IP \f(CWSiglongjmp\fR 4 |
| 18904 |
.IX Xref "Siglongjmp" |
| 18905 |
.IX Item "Siglongjmp" |
| 18906 |
This macro is used in the same way as \f(CWsiglongjmp()\fR, but will invoke |
| 18907 |
traditional \f(CWlongjmp()\fR if siglongjmp isn't available. |
| 18908 |
See \f(CW"HAS_SIGSETJMP"\fR. |
| 18909 |
.RS 4 |
| 18910 |
.Sp |
| 18911 |
.Vb 1 |
| 18912 |
\& void Siglongjmp(jmp_buf env, int val) |
| 18913 |
.Ve |
| 18914 |
.RE |
| 18915 |
.RS 4 |
| 18916 |
.RE |
| 18917 |
.ie n .IP """SIG_NAME""" 4 |
| 18918 |
.el .IP \f(CWSIG_NAME\fR 4 |
| 18919 |
.IX Xref "SIG_NAME" |
| 18920 |
.IX Item "SIG_NAME" |
| 18921 |
This symbol contains a list of signal names in order of |
| 18922 |
signal number. This is intended |
| 18923 |
to be used as a static array initialization, like this: |
| 18924 |
.Sp |
| 18925 |
.Vb 1 |
| 18926 |
\& char *sig_name[] = { SIG_NAME }; |
| 18927 |
.Ve |
| 18928 |
.Sp |
| 18929 |
The signals in the list are separated with commas, and each signal |
| 18930 |
is surrounded by double quotes. There is no leading \f(CW\*(C`SIG\*(C'\fR in the signal |
| 18931 |
name, i.e. \f(CW\*(C`SIGQUIT\*(C'\fR is known as "\f(CW\*(C`QUIT\*(C'\fR". |
| 18932 |
Gaps in the signal numbers (up to \f(CW\*(C`NSIG\*(C'\fR) are filled in with \f(CW\*(C`NUMnn\*(C'\fR, |
| 18933 |
etc., where nn is the actual signal number (e.g. \f(CW\*(C`NUM37\*(C'\fR). |
| 18934 |
The signal number for \f(CW\*(C`sig_name[i]\*(C'\fR is stored in \f(CW\*(C`sig_num[i]\*(C'\fR. |
| 18935 |
The last element is 0 to terminate the list with a \f(CW\*(C`NULL\*(C'\fR. This |
| 18936 |
corresponds to the 0 at the end of the \f(CW\*(C`sig_name_init\*(C'\fR list. |
| 18937 |
Note that this variable is initialized from the \f(CW\*(C`sig_name_init\*(C'\fR, |
| 18938 |
not from \f(CW\*(C`sig_name\*(C'\fR (which is unused). |
| 18939 |
.ie n .IP """SIG_NUM""" 4 |
| 18940 |
.el .IP \f(CWSIG_NUM\fR 4 |
| 18941 |
.IX Xref "SIG_NUM" |
| 18942 |
.IX Item "SIG_NUM" |
| 18943 |
This symbol contains a list of signal numbers, in the same order as the |
| 18944 |
\&\f(CW\*(C`SIG_NAME\*(C'\fR list. It is suitable for static array initialization, as in: |
| 18945 |
.Sp |
| 18946 |
.Vb 1 |
| 18947 |
\& int sig_num[] = { SIG_NUM }; |
| 18948 |
.Ve |
| 18949 |
.Sp |
| 18950 |
The signals in the list are separated with commas, and the indices |
| 18951 |
within that list and the \f(CW\*(C`SIG_NAME\*(C'\fR list match, so it's easy to compute |
| 18952 |
the signal name from a number or vice versa at the price of a small |
| 18953 |
dynamic linear lookup. |
| 18954 |
Duplicates are allowed, but are moved to the end of the list. |
| 18955 |
The signal number corresponding to \f(CW\*(C`sig_name[i]\*(C'\fR is \f(CW\*(C`sig_number[i]\*(C'\fR. |
| 18956 |
if (i < \f(CW\*(C`NSIG\*(C'\fR) then \f(CW\*(C`sig_number[i]\*(C'\fR == i. |
| 18957 |
The last element is 0, corresponding to the 0 at the end of |
| 18958 |
the \f(CW\*(C`sig_name_init\*(C'\fR list. |
| 18959 |
Note that this variable is initialized from the \f(CW\*(C`sig_num_init\*(C'\fR, |
| 18960 |
not from \f(CW\*(C`sig_num\*(C'\fR (which is unused). |
| 18961 |
.ie n .IP """Sigsetjmp""" 4 |
| 18962 |
.el .IP \f(CWSigsetjmp\fR 4 |
| 18963 |
.IX Xref "Sigsetjmp" |
| 18964 |
.IX Item "Sigsetjmp" |
| 18965 |
This macro is used in the same way as \f(CWsigsetjmp()\fR, but will invoke |
| 18966 |
traditional \f(CWsetjmp()\fR if sigsetjmp isn't available. |
| 18967 |
See \f(CW"HAS_SIGSETJMP"\fR. |
| 18968 |
.RS 4 |
| 18969 |
.Sp |
| 18970 |
.Vb 1 |
| 18971 |
\& int Sigsetjmp(jmp_buf env, int savesigs) |
| 18972 |
.Ve |
| 18973 |
.RE |
| 18974 |
.RS 4 |
| 18975 |
.RE |
| 18976 |
.ie n .IP """SIG_SIZE""" 4 |
| 18977 |
.el .IP \f(CWSIG_SIZE\fR 4 |
| 18978 |
.IX Xref "SIG_SIZE" |
| 18979 |
.IX Item "SIG_SIZE" |
| 18980 |
This variable contains the number of elements of the \f(CW\*(C`SIG_NAME\*(C'\fR |
| 18981 |
and \f(CW\*(C`SIG_NUM\*(C'\fR arrays, excluding the final \f(CW\*(C`NULL\*(C'\fR entry. |
| 18982 |
.ie n .IP """whichsig""" 4 |
| 18983 |
.el .IP \f(CWwhichsig\fR 4 |
| 18984 |
.IX Item "whichsig" |
| 18985 |
.PD 0 |
| 18986 |
.ie n .IP """whichsig_pv""" 4 |
| 18987 |
.el .IP \f(CWwhichsig_pv\fR 4 |
| 18988 |
.IX Item "whichsig_pv" |
| 18989 |
.ie n .IP """whichsig_pvn""" 4 |
| 18990 |
.el .IP \f(CWwhichsig_pvn\fR 4 |
| 18991 |
.IX Item "whichsig_pvn" |
| 18992 |
.ie n .IP """whichsig_sv""" 4 |
| 18993 |
.el .IP \f(CWwhichsig_sv\fR 4 |
| 18994 |
.IX Xref "whichsig whichsig_pv whichsig_pvn whichsig_sv" |
| 18995 |
.IX Item "whichsig_sv" |
| 18996 |
.PD |
| 18997 |
These all convert a signal name into its corresponding signal number; |
| 18998 |
returning \-1 if no corresponding number was found. |
| 18999 |
.Sp |
| 19000 |
They differ only in the source of the signal name: |
| 19001 |
.Sp |
| 19002 |
\&\f(CW\*(C`whichsig_pv\*(C'\fR takes the name from the \f(CW\*(C`NUL\*(C'\fR\-terminated string starting at |
| 19003 |
\&\f(CW\*(C`sig\*(C'\fR. |
| 19004 |
.Sp |
| 19005 |
\&\f(CW\*(C`whichsig\*(C'\fR is merely a different spelling, a synonym, of \f(CW\*(C`whichsig_pv\*(C'\fR. |
| 19006 |
.Sp |
| 19007 |
\&\f(CW\*(C`whichsig_pvn\*(C'\fR takes the name from the string starting at \f(CW\*(C`sig\*(C'\fR, with length |
| 19008 |
\&\f(CW\*(C`len\*(C'\fR bytes. |
| 19009 |
.Sp |
| 19010 |
\&\f(CW\*(C`whichsig_sv\*(C'\fR takes the name from the PV stored in the SV \f(CW\*(C`sigsv\*(C'\fR. |
| 19011 |
.RS 4 |
| 19012 |
.Sp |
| 19013 |
.Vb 4 |
| 19014 |
\& I32 whichsig (const char *sig) |
| 19015 |
\& I32 whichsig_pv (const char *sig) |
| 19016 |
\& I32 whichsig_pvn(const char *sig, STRLEN len) |
| 19017 |
\& I32 whichsig_sv (SV *sigsv) |
| 19018 |
.Ve |
| 19019 |
.RE |
| 19020 |
.RS 4 |
| 19021 |
.RE |
| 19022 |
.SH "Site configuration" |
| 19023 |
.IX Header "Site configuration" |
| 19024 |
These variables give details as to where various libraries, |
| 19025 |
installation destinations, \fIetc.\fR, go, as well as what various |
| 19026 |
installation options were selected |
| 19027 |
.ie n .IP """ARCHLIB""" 4 |
| 19028 |
.el .IP \f(CWARCHLIB\fR 4 |
| 19029 |
.IX Xref "ARCHLIB" |
| 19030 |
.IX Item "ARCHLIB" |
| 19031 |
This variable, if defined, holds the name of the directory in |
| 19032 |
which the user wants to put architecture-dependent public |
| 19033 |
library files for perl5. It is most often a local directory |
| 19034 |
such as \fI/usr/local/lib\fR. Programs using this variable must be |
| 19035 |
prepared to deal with filename expansion. If \f(CW\*(C`ARCHLIB\*(C'\fR is the |
| 19036 |
same as \f(CW\*(C`PRIVLIB\*(C'\fR, it is not defined, since presumably the |
| 19037 |
program already searches \f(CW\*(C`PRIVLIB\*(C'\fR. |
| 19038 |
.ie n .IP """ARCHLIB_EXP""" 4 |
| 19039 |
.el .IP \f(CWARCHLIB_EXP\fR 4 |
| 19040 |
.IX Xref "ARCHLIB_EXP" |
| 19041 |
.IX Item "ARCHLIB_EXP" |
| 19042 |
This symbol contains the ~name expanded version of \f(CW\*(C`ARCHLIB\*(C'\fR, to be used |
| 19043 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19044 |
.ie n .IP """ARCHNAME""" 4 |
| 19045 |
.el .IP \f(CWARCHNAME\fR 4 |
| 19046 |
.IX Xref "ARCHNAME" |
| 19047 |
.IX Item "ARCHNAME" |
| 19048 |
This symbol holds a string representing the architecture name. |
| 19049 |
It may be used to construct an architecture-dependant pathname |
| 19050 |
where library files may be held under a private library, for |
| 19051 |
instance. |
| 19052 |
.ie n .IP """BIN""" 4 |
| 19053 |
.el .IP \f(CWBIN\fR 4 |
| 19054 |
.IX Xref "BIN" |
| 19055 |
.IX Item "BIN" |
| 19056 |
This symbol holds the path of the bin directory where the package will |
| 19057 |
be installed. Program must be prepared to deal with ~name substitution. |
| 19058 |
.ie n .IP """BIN_EXP""" 4 |
| 19059 |
.el .IP \f(CWBIN_EXP\fR 4 |
| 19060 |
.IX Xref "BIN_EXP" |
| 19061 |
.IX Item "BIN_EXP" |
| 19062 |
This symbol is the filename expanded version of the \f(CW\*(C`BIN\*(C'\fR symbol, for |
| 19063 |
programs that do not want to deal with that at run-time. |
| 19064 |
.ie n .IP """INSTALL_USR_BIN_PERL""" 4 |
| 19065 |
.el .IP \f(CWINSTALL_USR_BIN_PERL\fR 4 |
| 19066 |
.IX Xref "INSTALL_USR_BIN_PERL" |
| 19067 |
.IX Item "INSTALL_USR_BIN_PERL" |
| 19068 |
This symbol, if defined, indicates that Perl is to be installed |
| 19069 |
also as \fI/usr/bin/perl\fR. |
| 19070 |
.ie n .IP """MULTIARCH""" 4 |
| 19071 |
.el .IP \f(CWMULTIARCH\fR 4 |
| 19072 |
.IX Xref "MULTIARCH" |
| 19073 |
.IX Item "MULTIARCH" |
| 19074 |
This symbol, if defined, signifies that the build |
| 19075 |
process will produce some binary files that are going to be |
| 19076 |
used in a cross-platform environment. This is the case for |
| 19077 |
example with the NeXT "fat" binaries that contain executables |
| 19078 |
for several \f(CW\*(C`CPUs\*(C'\fR. |
| 19079 |
.ie n .IP """PERL_INC_VERSION_LIST""" 4 |
| 19080 |
.el .IP \f(CWPERL_INC_VERSION_LIST\fR 4 |
| 19081 |
.IX Xref "PERL_INC_VERSION_LIST" |
| 19082 |
.IX Item "PERL_INC_VERSION_LIST" |
| 19083 |
This variable specifies the list of subdirectories in over |
| 19084 |
which \fIperl.c\fR:\f(CWincpush()\fR and \fIlib/lib.pm\fR will automatically |
| 19085 |
search when adding directories to @\f(CW\*(C`INC\*(C'\fR, in a format suitable |
| 19086 |
for a C initialization string. See the \f(CW\*(C`inc_version_list\*(C'\fR entry |
| 19087 |
in Porting/Glossary for more details. |
| 19088 |
.ie n .IP """PERL_OTHERLIBDIRS""" 4 |
| 19089 |
.el .IP \f(CWPERL_OTHERLIBDIRS\fR 4 |
| 19090 |
.IX Xref "PERL_OTHERLIBDIRS" |
| 19091 |
.IX Item "PERL_OTHERLIBDIRS" |
| 19092 |
This variable contains a colon-separated set of paths for the perl |
| 19093 |
binary to search for additional library files or modules. |
| 19094 |
These directories will be tacked to the end of @\f(CW\*(C`INC\*(C'\fR. |
| 19095 |
Perl will automatically search below each path for version\- |
| 19096 |
and architecture-specific directories. See \f(CW"PERL_INC_VERSION_LIST"\fR |
| 19097 |
for more details. |
| 19098 |
.ie n .IP """PERL_RELOCATABLE_INC""" 4 |
| 19099 |
.el .IP \f(CWPERL_RELOCATABLE_INC\fR 4 |
| 19100 |
.IX Xref "PERL_RELOCATABLE_INC" |
| 19101 |
.IX Item "PERL_RELOCATABLE_INC" |
| 19102 |
This symbol, if defined, indicates that we'd like to relocate entries |
| 19103 |
in @\f(CW\*(C`INC\*(C'\fR at run time based on the location of the perl binary. |
| 19104 |
.ie n .IP """PERL_TARGETARCH""" 4 |
| 19105 |
.el .IP \f(CWPERL_TARGETARCH\fR 4 |
| 19106 |
.IX Xref "PERL_TARGETARCH" |
| 19107 |
.IX Item "PERL_TARGETARCH" |
| 19108 |
This symbol, if defined, indicates the target architecture |
| 19109 |
Perl has been cross-compiled to. Undefined if not a cross-compile. |
| 19110 |
.ie n .IP """PERL_USE_DEVEL""" 4 |
| 19111 |
.el .IP \f(CWPERL_USE_DEVEL\fR 4 |
| 19112 |
.IX Xref "PERL_USE_DEVEL" |
| 19113 |
.IX Item "PERL_USE_DEVEL" |
| 19114 |
This symbol, if defined, indicates that Perl was configured with |
| 19115 |
\&\f(CW\*(C`\-Dusedevel\*(C'\fR, to enable development features. This should not be |
| 19116 |
done for production builds. |
| 19117 |
.ie n .IP """PERL_VENDORARCH""" 4 |
| 19118 |
.el .IP \f(CWPERL_VENDORARCH\fR 4 |
| 19119 |
.IX Xref "PERL_VENDORARCH" |
| 19120 |
.IX Item "PERL_VENDORARCH" |
| 19121 |
If defined, this symbol contains the name of a private library. |
| 19122 |
The library is private in the sense that it needn't be in anyone's |
| 19123 |
execution path, but it should be accessible by the world. |
| 19124 |
It may have a ~ on the front. |
| 19125 |
The standard distribution will put nothing in this directory. |
| 19126 |
Vendors who distribute perl may wish to place their own |
| 19127 |
architecture-dependent modules and extensions in this directory with |
| 19128 |
.Sp |
| 19129 |
.Vb 1 |
| 19130 |
\& MakeMaker Makefile.PL INSTALLDIRS=vendor |
| 19131 |
.Ve |
| 19132 |
.Sp |
| 19133 |
or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details. |
| 19134 |
.ie n .IP """PERL_VENDORARCH_EXP""" 4 |
| 19135 |
.el .IP \f(CWPERL_VENDORARCH_EXP\fR 4 |
| 19136 |
.IX Xref "PERL_VENDORARCH_EXP" |
| 19137 |
.IX Item "PERL_VENDORARCH_EXP" |
| 19138 |
This symbol contains the ~name expanded version of \f(CW\*(C`PERL_VENDORARCH\*(C'\fR, to be used |
| 19139 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19140 |
.ie n .IP """PERL_VENDORLIB_EXP""" 4 |
| 19141 |
.el .IP \f(CWPERL_VENDORLIB_EXP\fR 4 |
| 19142 |
.IX Xref "PERL_VENDORLIB_EXP" |
| 19143 |
.IX Item "PERL_VENDORLIB_EXP" |
| 19144 |
This symbol contains the ~name expanded version of \f(CW\*(C`VENDORLIB\*(C'\fR, to be used |
| 19145 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19146 |
.ie n .IP """PERL_VENDORLIB_STEM""" 4 |
| 19147 |
.el .IP \f(CWPERL_VENDORLIB_STEM\fR 4 |
| 19148 |
.IX Xref "PERL_VENDORLIB_STEM" |
| 19149 |
.IX Item "PERL_VENDORLIB_STEM" |
| 19150 |
This define is \f(CW\*(C`PERL_VENDORLIB_EXP\*(C'\fR with any trailing version-specific component |
| 19151 |
removed. The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can |
| 19152 |
be tacked onto this variable to generate a list of directories to search. |
| 19153 |
.ie n .IP """PRIVLIB""" 4 |
| 19154 |
.el .IP \f(CWPRIVLIB\fR 4 |
| 19155 |
.IX Xref "PRIVLIB" |
| 19156 |
.IX Item "PRIVLIB" |
| 19157 |
This symbol contains the name of the private library for this package. |
| 19158 |
The library is private in the sense that it needn't be in anyone's |
| 19159 |
execution path, but it should be accessible by the world. The program |
| 19160 |
should be prepared to do ~ expansion. |
| 19161 |
.ie n .IP """PRIVLIB_EXP""" 4 |
| 19162 |
.el .IP \f(CWPRIVLIB_EXP\fR 4 |
| 19163 |
.IX Xref "PRIVLIB_EXP" |
| 19164 |
.IX Item "PRIVLIB_EXP" |
| 19165 |
This symbol contains the ~name expanded version of \f(CW\*(C`PRIVLIB\*(C'\fR, to be used |
| 19166 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19167 |
.ie n .IP """SITEARCH""" 4 |
| 19168 |
.el .IP \f(CWSITEARCH\fR 4 |
| 19169 |
.IX Xref "SITEARCH" |
| 19170 |
.IX Item "SITEARCH" |
| 19171 |
This symbol contains the name of the private library for this package. |
| 19172 |
The library is private in the sense that it needn't be in anyone's |
| 19173 |
execution path, but it should be accessible by the world. The program |
| 19174 |
should be prepared to do ~ expansion. |
| 19175 |
The standard distribution will put nothing in this directory. |
| 19176 |
After perl has been installed, users may install their own local |
| 19177 |
architecture-dependent modules in this directory with |
| 19178 |
.Sp |
| 19179 |
.Vb 1 |
| 19180 |
\& MakeMaker Makefile.PL |
| 19181 |
.Ve |
| 19182 |
.Sp |
| 19183 |
or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details. |
| 19184 |
.ie n .IP """SITEARCH_EXP""" 4 |
| 19185 |
.el .IP \f(CWSITEARCH_EXP\fR 4 |
| 19186 |
.IX Xref "SITEARCH_EXP" |
| 19187 |
.IX Item "SITEARCH_EXP" |
| 19188 |
This symbol contains the ~name expanded version of \f(CW\*(C`SITEARCH\*(C'\fR, to be used |
| 19189 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19190 |
.ie n .IP """SITELIB""" 4 |
| 19191 |
.el .IP \f(CWSITELIB\fR 4 |
| 19192 |
.IX Xref "SITELIB" |
| 19193 |
.IX Item "SITELIB" |
| 19194 |
This symbol contains the name of the private library for this package. |
| 19195 |
The library is private in the sense that it needn't be in anyone's |
| 19196 |
execution path, but it should be accessible by the world. The program |
| 19197 |
should be prepared to do ~ expansion. |
| 19198 |
The standard distribution will put nothing in this directory. |
| 19199 |
After perl has been installed, users may install their own local |
| 19200 |
architecture-independent modules in this directory with |
| 19201 |
.Sp |
| 19202 |
.Vb 1 |
| 19203 |
\& MakeMaker Makefile.PL |
| 19204 |
.Ve |
| 19205 |
.Sp |
| 19206 |
or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details. |
| 19207 |
.ie n .IP """SITELIB_EXP""" 4 |
| 19208 |
.el .IP \f(CWSITELIB_EXP\fR 4 |
| 19209 |
.IX Xref "SITELIB_EXP" |
| 19210 |
.IX Item "SITELIB_EXP" |
| 19211 |
This symbol contains the ~name expanded version of \f(CW\*(C`SITELIB\*(C'\fR, to be used |
| 19212 |
in programs that are not prepared to deal with ~ expansion at run-time. |
| 19213 |
.ie n .IP """SITELIB_STEM""" 4 |
| 19214 |
.el .IP \f(CWSITELIB_STEM\fR 4 |
| 19215 |
.IX Xref "SITELIB_STEM" |
| 19216 |
.IX Item "SITELIB_STEM" |
| 19217 |
This define is \f(CW\*(C`SITELIB_EXP\*(C'\fR with any trailing version-specific component |
| 19218 |
removed. The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can |
| 19219 |
be tacked onto this variable to generate a list of directories to search. |
| 19220 |
.ie n .IP """STARTPERL""" 4 |
| 19221 |
.el .IP \f(CWSTARTPERL\fR 4 |
| 19222 |
.IX Xref "STARTPERL" |
| 19223 |
.IX Item "STARTPERL" |
| 19224 |
This variable contains the string to put in front of a perl |
| 19225 |
script to make sure (one hopes) that it runs with perl and not |
| 19226 |
some shell. |
| 19227 |
.ie n .IP """USE_64_BIT_ALL""" 4 |
| 19228 |
.el .IP \f(CWUSE_64_BIT_ALL\fR 4 |
| 19229 |
.IX Xref "USE_64_BIT_ALL" |
| 19230 |
.IX Item "USE_64_BIT_ALL" |
| 19231 |
This symbol, if defined, indicates that 64\-bit integers should |
| 19232 |
be used when available. If not defined, the native integers |
| 19233 |
will be used (be they 32 or 64 bits). The maximal possible |
| 19234 |
64\-bitness is employed: LP64 or \f(CW\*(C`ILP64\*(C'\fR, meaning that you will |
| 19235 |
be able to use more than 2 gigabytes of memory. This mode is |
| 19236 |
even more binary incompatible than \f(CW\*(C`USE_64_BIT_INT\*(C'\fR. You may not |
| 19237 |
be able to run the resulting executable in a 32\-bit \f(CW\*(C`CPU\*(C'\fR at all or |
| 19238 |
you may need at least to reboot your OS to 64\-bit mode. |
| 19239 |
.ie n .IP """USE_64_BIT_INT""" 4 |
| 19240 |
.el .IP \f(CWUSE_64_BIT_INT\fR 4 |
| 19241 |
.IX Xref "USE_64_BIT_INT" |
| 19242 |
.IX Item "USE_64_BIT_INT" |
| 19243 |
This symbol, if defined, indicates that 64\-bit integers should |
| 19244 |
be used when available. If not defined, the native integers |
| 19245 |
will be employed (be they 32 or 64 bits). The minimal possible |
| 19246 |
64\-bitness is used, just enough to get 64\-bit integers into Perl. |
| 19247 |
This may mean using for example "long longs", while your memory |
| 19248 |
may still be limited to 2 gigabytes. |
| 19249 |
.ie n .IP """USE_BSD_GETPGRP""" 4 |
| 19250 |
.el .IP \f(CWUSE_BSD_GETPGRP\fR 4 |
| 19251 |
.IX Xref "USE_BSD_GETPGRP" |
| 19252 |
.IX Item "USE_BSD_GETPGRP" |
| 19253 |
This symbol, if defined, indicates that getpgrp needs one |
| 19254 |
arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none. |
| 19255 |
.ie n .IP """USE_BSD_SETPGRP""" 4 |
| 19256 |
.el .IP \f(CWUSE_BSD_SETPGRP\fR 4 |
| 19257 |
.IX Xref "USE_BSD_SETPGRP" |
| 19258 |
.IX Item "USE_BSD_SETPGRP" |
| 19259 |
This symbol, if defined, indicates that setpgrp needs two |
| 19260 |
arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none. See also \f(CW"HAS_SETPGID"\fR |
| 19261 |
for a \f(CW\*(C`POSIX\*(C'\fR interface. |
| 19262 |
.ie n .IP """USE_C_BACKTRACE""" 4 |
| 19263 |
.el .IP \f(CWUSE_C_BACKTRACE\fR 4 |
| 19264 |
.IX Xref "USE_C_BACKTRACE" |
| 19265 |
.IX Item "USE_C_BACKTRACE" |
| 19266 |
This symbol, if defined, indicates that Perl should |
| 19267 |
be built with support for backtrace. |
| 19268 |
.ie n .IP """USE_CPLUSPLUS""" 4 |
| 19269 |
.el .IP \f(CWUSE_CPLUSPLUS\fR 4 |
| 19270 |
.IX Xref "USE_CPLUSPLUS" |
| 19271 |
.IX Item "USE_CPLUSPLUS" |
| 19272 |
This symbol, if defined, indicates that a C++ compiler was |
| 19273 |
used to compiled Perl and will be used to compile extensions. |
| 19274 |
.ie n .IP """USE_CROSS_COMPILE""" 4 |
| 19275 |
.el .IP \f(CWUSE_CROSS_COMPILE\fR 4 |
| 19276 |
.IX Xref "USE_CROSS_COMPILE" |
| 19277 |
.IX Item "USE_CROSS_COMPILE" |
| 19278 |
This symbol, if defined, indicates that Perl is being cross-compiled. |
| 19279 |
.ie n .IP """USE_DTRACE""" 4 |
| 19280 |
.el .IP \f(CWUSE_DTRACE\fR 4 |
| 19281 |
.IX Xref "USE_DTRACE" |
| 19282 |
.IX Item "USE_DTRACE" |
| 19283 |
This symbol, if defined, indicates that Perl should |
| 19284 |
be built with support for DTrace. |
| 19285 |
.ie n .IP """USE_DYNAMIC_LOADING""" 4 |
| 19286 |
.el .IP \f(CWUSE_DYNAMIC_LOADING\fR 4 |
| 19287 |
.IX Xref "USE_DYNAMIC_LOADING" |
| 19288 |
.IX Item "USE_DYNAMIC_LOADING" |
| 19289 |
This symbol, if defined, indicates that dynamic loading of |
| 19290 |
some sort is available. |
| 19291 |
.ie n .IP """USE_FAST_STDIO""" 4 |
| 19292 |
.el .IP \f(CWUSE_FAST_STDIO\fR 4 |
| 19293 |
.IX Xref "USE_FAST_STDIO" |
| 19294 |
.IX Item "USE_FAST_STDIO" |
| 19295 |
This symbol, if defined, indicates that Perl should |
| 19296 |
be built to use 'fast stdio'. |
| 19297 |
Defaults to define in Perls 5.8 and earlier, to undef later. |
| 19298 |
.ie n .IP """USE_ITHREADS""" 4 |
| 19299 |
.el .IP \f(CWUSE_ITHREADS\fR 4 |
| 19300 |
.IX Xref "USE_ITHREADS" |
| 19301 |
.IX Item "USE_ITHREADS" |
| 19302 |
This symbol, if defined, indicates that Perl should be built to |
| 19303 |
use the interpreter-based threading implementation. |
| 19304 |
.ie n .IP """USE_KERN_PROC_PATHNAME""" 4 |
| 19305 |
.el .IP \f(CWUSE_KERN_PROC_PATHNAME\fR 4 |
| 19306 |
.IX Xref "USE_KERN_PROC_PATHNAME" |
| 19307 |
.IX Item "USE_KERN_PROC_PATHNAME" |
| 19308 |
This symbol, if defined, indicates that we can use sysctl with |
| 19309 |
\&\f(CW\*(C`KERN_PROC_PATHNAME\*(C'\fR to get a full path for the executable, and hence |
| 19310 |
convert $^X to an absolute path. |
| 19311 |
.ie n .IP """USE_LARGE_FILES""" 4 |
| 19312 |
.el .IP \f(CWUSE_LARGE_FILES\fR 4 |
| 19313 |
.IX Xref "USE_LARGE_FILES" |
| 19314 |
.IX Item "USE_LARGE_FILES" |
| 19315 |
This symbol, if defined, indicates that large file support |
| 19316 |
should be used when available. |
| 19317 |
.ie n .IP """USE_LONG_DOUBLE""" 4 |
| 19318 |
.el .IP \f(CWUSE_LONG_DOUBLE\fR 4 |
| 19319 |
.IX Xref "USE_LONG_DOUBLE" |
| 19320 |
.IX Item "USE_LONG_DOUBLE" |
| 19321 |
This symbol, if defined, indicates that long doubles should |
| 19322 |
be used when available. |
| 19323 |
.ie n .IP """USE_MORE_BITS""" 4 |
| 19324 |
.el .IP \f(CWUSE_MORE_BITS\fR 4 |
| 19325 |
.IX Xref "USE_MORE_BITS" |
| 19326 |
.IX Item "USE_MORE_BITS" |
| 19327 |
This symbol, if defined, indicates that 64\-bit interfaces and |
| 19328 |
long doubles should be used when available. |
| 19329 |
.ie n .IP """USE_NSGETEXECUTABLEPATH""" 4 |
| 19330 |
.el .IP \f(CWUSE_NSGETEXECUTABLEPATH\fR 4 |
| 19331 |
.IX Xref "USE_NSGETEXECUTABLEPATH" |
| 19332 |
.IX Item "USE_NSGETEXECUTABLEPATH" |
| 19333 |
This symbol, if defined, indicates that we can use \f(CW\*(C`_NSGetExecutablePath\*(C'\fR |
| 19334 |
and realpath to get a full path for the executable, and hence convert |
| 19335 |
$^X to an absolute path. |
| 19336 |
.ie n .IP """USE_PERLIO""" 4 |
| 19337 |
.el .IP \f(CWUSE_PERLIO\fR 4 |
| 19338 |
.IX Xref "USE_PERLIO" |
| 19339 |
.IX Item "USE_PERLIO" |
| 19340 |
This symbol, if defined, indicates that the PerlIO abstraction should |
| 19341 |
be used throughout. If not defined, stdio should be |
| 19342 |
used in a fully backward compatible manner. |
| 19343 |
.ie n .IP """USE_QUADMATH""" 4 |
| 19344 |
.el .IP \f(CWUSE_QUADMATH\fR 4 |
| 19345 |
.IX Xref "USE_QUADMATH" |
| 19346 |
.IX Item "USE_QUADMATH" |
| 19347 |
This symbol, if defined, indicates that the quadmath library should |
| 19348 |
be used when available. |
| 19349 |
.ie n .IP """USE_REENTRANT_API""" 4 |
| 19350 |
.el .IP \f(CWUSE_REENTRANT_API\fR 4 |
| 19351 |
.IX Xref "USE_REENTRANT_API" |
| 19352 |
.IX Item "USE_REENTRANT_API" |
| 19353 |
This symbol, if defined, indicates that Perl should |
| 19354 |
try to use the various \f(CW\*(C`_r\*(C'\fR versions of library functions. |
| 19355 |
This is extremely experimental. |
| 19356 |
.ie n .IP """USE_SEMCTL_SEMID_DS""" 4 |
| 19357 |
.el .IP \f(CWUSE_SEMCTL_SEMID_DS\fR 4 |
| 19358 |
.IX Xref "USE_SEMCTL_SEMID_DS" |
| 19359 |
.IX Item "USE_SEMCTL_SEMID_DS" |
| 19360 |
This symbol, if defined, indicates that \f(CW\*(C`struct semid_ds\*(C'\fR * is |
| 19361 |
used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR. |
| 19362 |
.ie n .IP """USE_SEMCTL_SEMUN""" 4 |
| 19363 |
.el .IP \f(CWUSE_SEMCTL_SEMUN\fR 4 |
| 19364 |
.IX Xref "USE_SEMCTL_SEMUN" |
| 19365 |
.IX Item "USE_SEMCTL_SEMUN" |
| 19366 |
This symbol, if defined, indicates that \f(CW\*(C`union semun\*(C'\fR is |
| 19367 |
used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR. |
| 19368 |
.ie n .IP """USE_SITECUSTOMIZE""" 4 |
| 19369 |
.el .IP \f(CWUSE_SITECUSTOMIZE\fR 4 |
| 19370 |
.IX Xref "USE_SITECUSTOMIZE" |
| 19371 |
.IX Item "USE_SITECUSTOMIZE" |
| 19372 |
This symbol, if defined, indicates that sitecustomize should |
| 19373 |
be used. |
| 19374 |
.ie n .IP """USE_SOCKS""" 4 |
| 19375 |
.el .IP \f(CWUSE_SOCKS\fR 4 |
| 19376 |
.IX Xref "USE_SOCKS" |
| 19377 |
.IX Item "USE_SOCKS" |
| 19378 |
This symbol, if defined, indicates that Perl should |
| 19379 |
be built to use socks. |
| 19380 |
.ie n .IP """USE_STAT_BLOCKS""" 4 |
| 19381 |
.el .IP \f(CWUSE_STAT_BLOCKS\fR 4 |
| 19382 |
.IX Xref "USE_STAT_BLOCKS" |
| 19383 |
.IX Item "USE_STAT_BLOCKS" |
| 19384 |
This symbol is defined if this system has a stat structure declaring |
| 19385 |
\&\f(CW\*(C`st_blksize\*(C'\fR and \f(CW\*(C`st_blocks\*(C'\fR. |
| 19386 |
.ie n .IP """USE_STDIO_BASE""" 4 |
| 19387 |
.el .IP \f(CWUSE_STDIO_BASE\fR 4 |
| 19388 |
.IX Xref "USE_STDIO_BASE" |
| 19389 |
.IX Item "USE_STDIO_BASE" |
| 19390 |
This symbol is defined if the \f(CW\*(C`_base\*(C'\fR field (or similar) of the |
| 19391 |
stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer for |
| 19392 |
a file handle. If this is defined, then the \f(CWFILE_base(fp)\fR macro |
| 19393 |
will also be defined and should be used to access this field. |
| 19394 |
Also, the \f(CWFILE_bufsiz(fp)\fR macro will be defined and should be used |
| 19395 |
to determine the number of bytes in the buffer. \f(CW\*(C`USE_STDIO_BASE\*(C'\fR |
| 19396 |
will never be defined unless \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is. |
| 19397 |
.ie n .IP """USE_STDIO_PTR""" 4 |
| 19398 |
.el .IP \f(CWUSE_STDIO_PTR\fR 4 |
| 19399 |
.IX Xref "USE_STDIO_PTR" |
| 19400 |
.IX Item "USE_STDIO_PTR" |
| 19401 |
This symbol is defined if the \f(CW\*(C`_ptr\*(C'\fR and \f(CW\*(C`_cnt\*(C'\fR fields (or similar) |
| 19402 |
of the stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer |
| 19403 |
for a file handle. If this is defined, then the \f(CWFILE_ptr(fp)\fR |
| 19404 |
and \f(CWFILE_cnt(fp)\fR macros will also be defined and should be used |
| 19405 |
to access these fields. |
| 19406 |
.ie n .IP """USE_STRICT_BY_DEFAULT""" 4 |
| 19407 |
.el .IP \f(CWUSE_STRICT_BY_DEFAULT\fR 4 |
| 19408 |
.IX Xref "USE_STRICT_BY_DEFAULT" |
| 19409 |
.IX Item "USE_STRICT_BY_DEFAULT" |
| 19410 |
This symbol, if defined, enables additional defaults. |
| 19411 |
At this time it only enables implicit strict by default. |
| 19412 |
.ie n .IP """USE_THREADS""" 4 |
| 19413 |
.el .IP \f(CWUSE_THREADS\fR 4 |
| 19414 |
.IX Xref "USE_THREADS" |
| 19415 |
.IX Item "USE_THREADS" |
| 19416 |
This symbol, if defined, indicates that Perl should |
| 19417 |
be built to use threads. At present, it is a synonym for |
| 19418 |
and \f(CW\*(C`USE_ITHREADS\*(C'\fR, but eventually the source ought to be |
| 19419 |
changed to use this to mean \f(CW\*(C`_any_\*(C'\fR threading implementation. |
| 19420 |
.SH "Sockets configuration values" |
| 19421 |
.IX Header "Sockets configuration values" |
| 19422 |
.ie n .IP """HAS_SOCKADDR_IN6""" 4 |
| 19423 |
.el .IP \f(CWHAS_SOCKADDR_IN6\fR 4 |
| 19424 |
.IX Xref "HAS_SOCKADDR_IN6" |
| 19425 |
.IX Item "HAS_SOCKADDR_IN6" |
| 19426 |
This symbol, if defined, indicates the availability of |
| 19427 |
\&\f(CW\*(C`struct sockaddr_in6\*(C'\fR; |
| 19428 |
.ie n .IP """HAS_SOCKADDR_SA_LEN""" 4 |
| 19429 |
.el .IP \f(CWHAS_SOCKADDR_SA_LEN\fR 4 |
| 19430 |
.IX Xref "HAS_SOCKADDR_SA_LEN" |
| 19431 |
.IX Item "HAS_SOCKADDR_SA_LEN" |
| 19432 |
This symbol, if defined, indicates that the \f(CW\*(C`struct sockaddr\*(C'\fR |
| 19433 |
structure has a member called \f(CW\*(C`sa_len\*(C'\fR, indicating the length of |
| 19434 |
the structure. |
| 19435 |
.ie n .IP """HAS_SOCKADDR_STORAGE""" 4 |
| 19436 |
.el .IP \f(CWHAS_SOCKADDR_STORAGE\fR 4 |
| 19437 |
.IX Xref "HAS_SOCKADDR_STORAGE" |
| 19438 |
.IX Item "HAS_SOCKADDR_STORAGE" |
| 19439 |
This symbol, if defined, indicates the availability of |
| 19440 |
\&\f(CW\*(C`struct sockaddr_storage\*(C'\fR; |
| 19441 |
.ie n .IP """HAS_SOCKATMARK""" 4 |
| 19442 |
.el .IP \f(CWHAS_SOCKATMARK\fR 4 |
| 19443 |
.IX Xref "HAS_SOCKATMARK" |
| 19444 |
.IX Item "HAS_SOCKATMARK" |
| 19445 |
This symbol, if defined, indicates that the \f(CW\*(C`sockatmark\*(C'\fR routine is |
| 19446 |
available to test whether a socket is at the out-of-band mark. |
| 19447 |
.ie n .IP """HAS_SOCKET""" 4 |
| 19448 |
.el .IP \f(CWHAS_SOCKET\fR 4 |
| 19449 |
.IX Xref "HAS_SOCKET" |
| 19450 |
.IX Item "HAS_SOCKET" |
| 19451 |
This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CW\*(C`socket\*(C'\fR interface is |
| 19452 |
supported. |
| 19453 |
.ie n .IP """HAS_SOCKETPAIR""" 4 |
| 19454 |
.el .IP \f(CWHAS_SOCKETPAIR\fR 4 |
| 19455 |
.IX Xref "HAS_SOCKETPAIR" |
| 19456 |
.IX Item "HAS_SOCKETPAIR" |
| 19457 |
This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CWsocketpair()\fR call is |
| 19458 |
supported. |
| 19459 |
.ie n .IP """HAS_SOCKS5_INIT""" 4 |
| 19460 |
.el .IP \f(CWHAS_SOCKS5_INIT\fR 4 |
| 19461 |
.IX Xref "HAS_SOCKS5_INIT" |
| 19462 |
.IX Item "HAS_SOCKS5_INIT" |
| 19463 |
This symbol, if defined, indicates that the \f(CW\*(C`socks5_init\*(C'\fR routine is |
| 19464 |
available to initialize \f(CW\*(C`SOCKS\*(C'\fR 5. |
| 19465 |
.ie n .IP """I_SOCKS""" 4 |
| 19466 |
.el .IP \f(CWI_SOCKS\fR 4 |
| 19467 |
.IX Xref "I_SOCKS" |
| 19468 |
.IX Item "I_SOCKS" |
| 19469 |
This symbol, if defined, indicates that \fIsocks.h\fR exists and |
| 19470 |
should be included. |
| 19471 |
.RS 4 |
| 19472 |
.Sp |
| 19473 |
.Vb 3 |
| 19474 |
\& #ifdef I_SOCKS |
| 19475 |
\& #include <socks.h> |
| 19476 |
\& #endif |
| 19477 |
.Ve |
| 19478 |
.RE |
| 19479 |
.RS 4 |
| 19480 |
.RE |
| 19481 |
.ie n .IP """I_SYS_SOCKIO""" 4 |
| 19482 |
.el .IP \f(CWI_SYS_SOCKIO\fR 4 |
| 19483 |
.IX Xref "I_SYS_SOCKIO" |
| 19484 |
.IX Item "I_SYS_SOCKIO" |
| 19485 |
This symbol, if defined, indicates the \fIsys/sockio.h\fR should be included |
| 19486 |
to get socket ioctl options, like \f(CW\*(C`SIOCATMARK\*(C'\fR. |
| 19487 |
.RS 4 |
| 19488 |
.Sp |
| 19489 |
.Vb 3 |
| 19490 |
\& #ifdef I_SYS_SOCKIO |
| 19491 |
\& #include <sys_sockio.h> |
| 19492 |
\& #endif |
| 19493 |
.Ve |
| 19494 |
.RE |
| 19495 |
.RS 4 |
| 19496 |
.RE |
| 19497 |
.SH "Source Filters" |
| 19498 |
.IX Header "Source Filters" |
| 19499 |
.ie n .IP """apply_builtin_cv_attributes""" 4 |
| 19500 |
.el .IP \f(CWapply_builtin_cv_attributes\fR 4 |
| 19501 |
.IX Xref "apply_builtin_cv_attributes" |
| 19502 |
.IX Item "apply_builtin_cv_attributes" |
| 19503 |
Given an OP_LIST containing attribute definitions, filter it for known builtin |
| 19504 |
attributes to apply to the cv, returning a possibly-smaller list containing |
| 19505 |
just the remaining ones. |
| 19506 |
.RS 4 |
| 19507 |
.Sp |
| 19508 |
.Vb 1 |
| 19509 |
\& OP * apply_builtin_cv_attributes(CV *cv, OP *attrlist) |
| 19510 |
.Ve |
| 19511 |
.RE |
| 19512 |
.RS 4 |
| 19513 |
.RE |
| 19514 |
.ie n .IP """filter_add""" 4 |
| 19515 |
.el .IP \f(CWfilter_add\fR 4 |
| 19516 |
.IX Item "filter_add" |
| 19517 |
Described in perlfilter. |
| 19518 |
.RS 4 |
| 19519 |
.Sp |
| 19520 |
.Vb 1 |
| 19521 |
\& SV * filter_add(filter_t funcp, SV *datasv) |
| 19522 |
.Ve |
| 19523 |
.RE |
| 19524 |
.RS 4 |
| 19525 |
.RE |
| 19526 |
.ie n .IP """filter_del""" 4 |
| 19527 |
.el .IP \f(CWfilter_del\fR 4 |
| 19528 |
.IX Xref "filter_del" |
| 19529 |
.IX Item "filter_del" |
| 19530 |
Delete most recently added instance of the filter function argument |
| 19531 |
.RS 4 |
| 19532 |
.Sp |
| 19533 |
.Vb 1 |
| 19534 |
\& void filter_del(filter_t funcp) |
| 19535 |
.Ve |
| 19536 |
.RE |
| 19537 |
.RS 4 |
| 19538 |
.RE |
| 19539 |
.ie n .IP """filter_read""" 4 |
| 19540 |
.el .IP \f(CWfilter_read\fR 4 |
| 19541 |
.IX Item "filter_read" |
| 19542 |
Described in perlfilter. |
| 19543 |
.RS 4 |
| 19544 |
.Sp |
| 19545 |
.Vb 1 |
| 19546 |
\& I32 filter_read(int idx, SV *buf_sv, int maxlen) |
| 19547 |
.Ve |
| 19548 |
.RE |
| 19549 |
.RS 4 |
| 19550 |
.RE |
| 19551 |
.ie n .IP """scan_vstring""" 4 |
| 19552 |
.el .IP \f(CWscan_vstring\fR 4 |
| 19553 |
.IX Xref "scan_vstring" |
| 19554 |
.IX Item "scan_vstring" |
| 19555 |
Returns a pointer to the next character after the parsed |
| 19556 |
vstring, as well as updating the passed in sv. |
| 19557 |
.Sp |
| 19558 |
Function must be called like |
| 19559 |
.Sp |
| 19560 |
.Vb 2 |
| 19561 |
\& sv = sv_2mortal(newSV(5)); |
| 19562 |
\& s = scan_vstring(s,e,sv); |
| 19563 |
.Ve |
| 19564 |
.Sp |
| 19565 |
where s and e are the start and end of the string. |
| 19566 |
The sv should already be large enough to store the vstring |
| 19567 |
passed in, for performance reasons. |
| 19568 |
.Sp |
| 19569 |
This function may croak if fatal warnings are enabled in the |
| 19570 |
calling scope, hence the sv_2mortal in the example (to prevent |
| 19571 |
a leak). Make sure to do SvREFCNT_inc afterwards if you use |
| 19572 |
sv_2mortal. |
| 19573 |
.RS 4 |
| 19574 |
.Sp |
| 19575 |
.Vb 1 |
| 19576 |
\& char * scan_vstring(const char *s, const char * const e, SV *sv) |
| 19577 |
.Ve |
| 19578 |
.RE |
| 19579 |
.RS 4 |
| 19580 |
.RE |
| 19581 |
.ie n .IP """start_subparse""" 4 |
| 19582 |
.el .IP \f(CWstart_subparse\fR 4 |
| 19583 |
.IX Xref "start_subparse" |
| 19584 |
.IX Item "start_subparse" |
| 19585 |
Set things up for parsing a subroutine. |
| 19586 |
.Sp |
| 19587 |
If \f(CW\*(C`is_format\*(C'\fR is non-zero, the input is to be considered a format sub |
| 19588 |
(a specialised sub used to implement perl's \f(CW\*(C`format\*(C'\fR feature); else a |
| 19589 |
normal \f(CW\*(C`sub\*(C'\fR. |
| 19590 |
.Sp |
| 19591 |
\&\f(CW\*(C`flags\*(C'\fR are added to the flags for \f(CW\*(C`PL_compcv\*(C'\fR. \f(CW\*(C`flags\*(C'\fR may include the |
| 19592 |
\&\f(CW\*(C`CVf_IsMETHOD\*(C'\fR bit, which causes the new subroutine to be a method. |
| 19593 |
.Sp |
| 19594 |
This returns the value of \f(CW\*(C`PL_savestack_ix\*(C'\fR that was in effect upon entry to |
| 19595 |
the function; |
| 19596 |
.RS 4 |
| 19597 |
.Sp |
| 19598 |
.Vb 1 |
| 19599 |
\& I32 start_subparse(I32 is_format, U32 flags) |
| 19600 |
.Ve |
| 19601 |
.RE |
| 19602 |
.RS 4 |
| 19603 |
.RE |
| 19604 |
.SH "Stack Manipulation Macros" |
| 19605 |
.IX Header "Stack Manipulation Macros" |
| 19606 |
.ie n .IP """dMARK""" 4 |
| 19607 |
.el .IP \f(CWdMARK\fR 4 |
| 19608 |
.IX Xref "dMARK" |
| 19609 |
.IX Item "dMARK" |
| 19610 |
Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the XSUB. See \f(CW"MARK"\fR and |
| 19611 |
\&\f(CW"dORIGMARK"\fR. |
| 19612 |
.RS 4 |
| 19613 |
.Sp |
| 19614 |
.Vb 1 |
| 19615 |
\& dMARK; |
| 19616 |
.Ve |
| 19617 |
.RE |
| 19618 |
.RS 4 |
| 19619 |
.RE |
| 19620 |
.ie n .IP """dORIGMARK""" 4 |
| 19621 |
.el .IP \f(CWdORIGMARK\fR 4 |
| 19622 |
.IX Xref "dORIGMARK" |
| 19623 |
.IX Item "dORIGMARK" |
| 19624 |
Saves the original stack mark for the XSUB. See \f(CW"ORIGMARK"\fR. |
| 19625 |
.RS 4 |
| 19626 |
.Sp |
| 19627 |
.Vb 1 |
| 19628 |
\& dORIGMARK; |
| 19629 |
.Ve |
| 19630 |
.RE |
| 19631 |
.RS 4 |
| 19632 |
.RE |
| 19633 |
.ie n .IP """dSP""" 4 |
| 19634 |
.el .IP \f(CWdSP\fR 4 |
| 19635 |
.IX Xref "dSP" |
| 19636 |
.IX Item "dSP" |
| 19637 |
Declares a local copy of perl's stack pointer for the XSUB, available via |
| 19638 |
the \f(CW\*(C`SP\*(C'\fR macro. See \f(CW"SP"\fR. |
| 19639 |
.RS 4 |
| 19640 |
.Sp |
| 19641 |
.Vb 1 |
| 19642 |
\& dSP; |
| 19643 |
.Ve |
| 19644 |
.RE |
| 19645 |
.RS 4 |
| 19646 |
.RE |
| 19647 |
.ie n .IP """dTARGET""" 4 |
| 19648 |
.el .IP \f(CWdTARGET\fR 4 |
| 19649 |
.IX Xref "dTARGET" |
| 19650 |
.IX Item "dTARGET" |
| 19651 |
Declare that this function uses \f(CW\*(C`TARG\*(C'\fR, and initializes it |
| 19652 |
.RS 4 |
| 19653 |
.Sp |
| 19654 |
.Vb 1 |
| 19655 |
\& dTARGET; |
| 19656 |
.Ve |
| 19657 |
.RE |
| 19658 |
.RS 4 |
| 19659 |
.RE |
| 19660 |
.ie n .IP """EXTEND""" 4 |
| 19661 |
.el .IP \f(CWEXTEND\fR 4 |
| 19662 |
.IX Xref "EXTEND" |
| 19663 |
.IX Item "EXTEND" |
| 19664 |
Used to extend the argument stack for an XSUB's return values. Once |
| 19665 |
used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed |
| 19666 |
onto the stack. |
| 19667 |
.RS 4 |
| 19668 |
.Sp |
| 19669 |
.Vb 1 |
| 19670 |
\& void EXTEND(SP, SSize_t nitems) |
| 19671 |
.Ve |
| 19672 |
.RE |
| 19673 |
.RS 4 |
| 19674 |
.RE |
| 19675 |
.ie n .IP """MARK""" 4 |
| 19676 |
.el .IP \f(CWMARK\fR 4 |
| 19677 |
.IX Xref "MARK" |
| 19678 |
.IX Item "MARK" |
| 19679 |
Stack marker variable for the XSUB. See \f(CW"dMARK"\fR. |
| 19680 |
.ie n .IP """mPUSHi""" 4 |
| 19681 |
.el .IP \f(CWmPUSHi\fR 4 |
| 19682 |
.IX Xref "mPUSHi" |
| 19683 |
.IX Item "mPUSHi" |
| 19684 |
Push an integer onto the stack. The stack must have room for this element. |
| 19685 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHi"\fR, \f(CW"mXPUSHi"\fR and \f(CW"XPUSHi"\fR. |
| 19686 |
.RS 4 |
| 19687 |
.Sp |
| 19688 |
.Vb 1 |
| 19689 |
\& void mPUSHi(IV iv) |
| 19690 |
.Ve |
| 19691 |
.RE |
| 19692 |
.RS 4 |
| 19693 |
.RE |
| 19694 |
.ie n .IP """mPUSHn""" 4 |
| 19695 |
.el .IP \f(CWmPUSHn\fR 4 |
| 19696 |
.IX Xref "mPUSHn" |
| 19697 |
.IX Item "mPUSHn" |
| 19698 |
Push a double onto the stack. The stack must have room for this element. |
| 19699 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHn"\fR, \f(CW"mXPUSHn"\fR and \f(CW"XPUSHn"\fR. |
| 19700 |
.RS 4 |
| 19701 |
.Sp |
| 19702 |
.Vb 1 |
| 19703 |
\& void mPUSHn(NV nv) |
| 19704 |
.Ve |
| 19705 |
.RE |
| 19706 |
.RS 4 |
| 19707 |
.RE |
| 19708 |
.ie n .IP """mPUSHp""" 4 |
| 19709 |
.el .IP \f(CWmPUSHp\fR 4 |
| 19710 |
.IX Xref "mPUSHp" |
| 19711 |
.IX Item "mPUSHp" |
| 19712 |
Push a string onto the stack. The stack must have room for this element. |
| 19713 |
The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR. |
| 19714 |
See also \f(CW"PUSHp"\fR, \f(CW"mXPUSHp"\fR and \f(CW"XPUSHp"\fR. |
| 19715 |
.RS 4 |
| 19716 |
.Sp |
| 19717 |
.Vb 1 |
| 19718 |
\& void mPUSHp(char* str, STRLEN len) |
| 19719 |
.Ve |
| 19720 |
.RE |
| 19721 |
.RS 4 |
| 19722 |
.RE |
| 19723 |
.ie n .IP """mPUSHpvs""" 4 |
| 19724 |
.el .IP \f(CWmPUSHpvs\fR 4 |
| 19725 |
.IX Xref "mPUSHpvs" |
| 19726 |
.IX Item "mPUSHpvs" |
| 19727 |
A variation on \f(CW\*(C`mPUSHp\*(C'\fR that takes a literal string and calculates its size |
| 19728 |
directly. |
| 19729 |
.RS 4 |
| 19730 |
.Sp |
| 19731 |
.Vb 1 |
| 19732 |
\& void mPUSHpvs("literal string") |
| 19733 |
.Ve |
| 19734 |
.RE |
| 19735 |
.RS 4 |
| 19736 |
.RE |
| 19737 |
.ie n .IP """mPUSHs""" 4 |
| 19738 |
.el .IP \f(CWmPUSHs\fR 4 |
| 19739 |
.IX Xref "mPUSHs" |
| 19740 |
.IX Item "mPUSHs" |
| 19741 |
Push an SV onto the stack and mortalizes the SV. The stack must have room |
| 19742 |
for this element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR and |
| 19743 |
\&\f(CW"mXPUSHs"\fR. |
| 19744 |
.RS 4 |
| 19745 |
.Sp |
| 19746 |
.Vb 1 |
| 19747 |
\& void mPUSHs(SV* sv) |
| 19748 |
.Ve |
| 19749 |
.RE |
| 19750 |
.RS 4 |
| 19751 |
.RE |
| 19752 |
.ie n .IP """mPUSHu""" 4 |
| 19753 |
.el .IP \f(CWmPUSHu\fR 4 |
| 19754 |
.IX Xref "mPUSHu" |
| 19755 |
.IX Item "mPUSHu" |
| 19756 |
Push an unsigned integer onto the stack. The stack must have room for this |
| 19757 |
element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHu"\fR, \f(CW"mXPUSHu"\fR and |
| 19758 |
\&\f(CW"XPUSHu"\fR. |
| 19759 |
.RS 4 |
| 19760 |
.Sp |
| 19761 |
.Vb 1 |
| 19762 |
\& void mPUSHu(UV uv) |
| 19763 |
.Ve |
| 19764 |
.RE |
| 19765 |
.RS 4 |
| 19766 |
.RE |
| 19767 |
.ie n .IP """mXPUSHi""" 4 |
| 19768 |
.el .IP \f(CWmXPUSHi\fR 4 |
| 19769 |
.IX Xref "mXPUSHi" |
| 19770 |
.IX Item "mXPUSHi" |
| 19771 |
Push an integer onto the stack, extending the stack if necessary. |
| 19772 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHi"\fR, \f(CW"mPUSHi"\fR and \f(CW"PUSHi"\fR. |
| 19773 |
.RS 4 |
| 19774 |
.Sp |
| 19775 |
.Vb 1 |
| 19776 |
\& void mXPUSHi(IV iv) |
| 19777 |
.Ve |
| 19778 |
.RE |
| 19779 |
.RS 4 |
| 19780 |
.RE |
| 19781 |
.ie n .IP """mXPUSHn""" 4 |
| 19782 |
.el .IP \f(CWmXPUSHn\fR 4 |
| 19783 |
.IX Xref "mXPUSHn" |
| 19784 |
.IX Item "mXPUSHn" |
| 19785 |
Push a double onto the stack, extending the stack if necessary. |
| 19786 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHn"\fR, \f(CW"mPUSHn"\fR and \f(CW"PUSHn"\fR. |
| 19787 |
.RS 4 |
| 19788 |
.Sp |
| 19789 |
.Vb 1 |
| 19790 |
\& void mXPUSHn(NV nv) |
| 19791 |
.Ve |
| 19792 |
.RE |
| 19793 |
.RS 4 |
| 19794 |
.RE |
| 19795 |
.ie n .IP """mXPUSHp""" 4 |
| 19796 |
.el .IP \f(CWmXPUSHp\fR 4 |
| 19797 |
.IX Xref "mXPUSHp" |
| 19798 |
.IX Item "mXPUSHp" |
| 19799 |
Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR |
| 19800 |
indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR. See also |
| 19801 |
\&\f(CW"XPUSHp"\fR, \f(CW\*(C`mPUSHp\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR. |
| 19802 |
.RS 4 |
| 19803 |
.Sp |
| 19804 |
.Vb 1 |
| 19805 |
\& void mXPUSHp(char* str, STRLEN len) |
| 19806 |
.Ve |
| 19807 |
.RE |
| 19808 |
.RS 4 |
| 19809 |
.RE |
| 19810 |
.ie n .IP """mXPUSHpvs""" 4 |
| 19811 |
.el .IP \f(CWmXPUSHpvs\fR 4 |
| 19812 |
.IX Xref "mXPUSHpvs" |
| 19813 |
.IX Item "mXPUSHpvs" |
| 19814 |
A variation on \f(CW\*(C`mXPUSHp\*(C'\fR that takes a literal string and calculates its size |
| 19815 |
directly. |
| 19816 |
.RS 4 |
| 19817 |
.Sp |
| 19818 |
.Vb 1 |
| 19819 |
\& void mXPUSHpvs("literal string") |
| 19820 |
.Ve |
| 19821 |
.RE |
| 19822 |
.RS 4 |
| 19823 |
.RE |
| 19824 |
.ie n .IP """mXPUSHs""" 4 |
| 19825 |
.el .IP \f(CWmXPUSHs\fR 4 |
| 19826 |
.IX Xref "mXPUSHs" |
| 19827 |
.IX Item "mXPUSHs" |
| 19828 |
Push an SV onto the stack, extending the stack if necessary and mortalizes |
| 19829 |
the SV. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR and \f(CW"mPUSHs"\fR. |
| 19830 |
.RS 4 |
| 19831 |
.Sp |
| 19832 |
.Vb 1 |
| 19833 |
\& void mXPUSHs(SV* sv) |
| 19834 |
.Ve |
| 19835 |
.RE |
| 19836 |
.RS 4 |
| 19837 |
.RE |
| 19838 |
.ie n .IP """mXPUSHu""" 4 |
| 19839 |
.el .IP \f(CWmXPUSHu\fR 4 |
| 19840 |
.IX Xref "mXPUSHu" |
| 19841 |
.IX Item "mXPUSHu" |
| 19842 |
Push an unsigned integer onto the stack, extending the stack if necessary. |
| 19843 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHu"\fR, \f(CW"mPUSHu"\fR and \f(CW"PUSHu"\fR. |
| 19844 |
.RS 4 |
| 19845 |
.Sp |
| 19846 |
.Vb 1 |
| 19847 |
\& void mXPUSHu(UV uv) |
| 19848 |
.Ve |
| 19849 |
.RE |
| 19850 |
.RS 4 |
| 19851 |
.RE |
| 19852 |
.ie n .IP """newXSproto""" 4 |
| 19853 |
.el .IP \f(CWnewXSproto\fR 4 |
| 19854 |
.IX Xref "newXSproto" |
| 19855 |
.IX Item "newXSproto" |
| 19856 |
Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. Adds Perl prototypes to |
| 19857 |
the subs. |
| 19858 |
.ie n .IP """ORIGMARK""" 4 |
| 19859 |
.el .IP \f(CWORIGMARK\fR 4 |
| 19860 |
.IX Xref "ORIGMARK" |
| 19861 |
.IX Item "ORIGMARK" |
| 19862 |
The original stack mark for the XSUB. See \f(CW"dORIGMARK"\fR. |
| 19863 |
.ie n .IP """PL_markstack""" 4 |
| 19864 |
.el .IP \f(CWPL_markstack\fR 4 |
| 19865 |
.IX Item "PL_markstack" |
| 19866 |
Described in perlguts. |
| 19867 |
.ie n .IP """PL_markstack_ptr""" 4 |
| 19868 |
.el .IP \f(CWPL_markstack_ptr\fR 4 |
| 19869 |
.IX Item "PL_markstack_ptr" |
| 19870 |
Described in perlguts. |
| 19871 |
.ie n .IP """PL_savestack""" 4 |
| 19872 |
.el .IP \f(CWPL_savestack\fR 4 |
| 19873 |
.IX Item "PL_savestack" |
| 19874 |
Described in perlguts. |
| 19875 |
.ie n .IP """PL_savestack_ix""" 4 |
| 19876 |
.el .IP \f(CWPL_savestack_ix\fR 4 |
| 19877 |
.IX Item "PL_savestack_ix" |
| 19878 |
Described in perlguts. |
| 19879 |
.ie n .IP """PL_scopestack""" 4 |
| 19880 |
.el .IP \f(CWPL_scopestack\fR 4 |
| 19881 |
.IX Item "PL_scopestack" |
| 19882 |
Described in perlguts. |
| 19883 |
.ie n .IP """PL_scopestack_ix""" 4 |
| 19884 |
.el .IP \f(CWPL_scopestack_ix\fR 4 |
| 19885 |
.IX Item "PL_scopestack_ix" |
| 19886 |
Described in perlguts. |
| 19887 |
.ie n .IP """PL_scopestack_name""" 4 |
| 19888 |
.el .IP \f(CWPL_scopestack_name\fR 4 |
| 19889 |
.IX Item "PL_scopestack_name" |
| 19890 |
Described in perlguts. |
| 19891 |
.ie n .IP """PL_stack_base""" 4 |
| 19892 |
.el .IP \f(CWPL_stack_base\fR 4 |
| 19893 |
.IX Item "PL_stack_base" |
| 19894 |
Described in perlguts. |
| 19895 |
.ie n .IP """PL_stack_sp""" 4 |
| 19896 |
.el .IP \f(CWPL_stack_sp\fR 4 |
| 19897 |
.IX Item "PL_stack_sp" |
| 19898 |
Described in perlguts. |
| 19899 |
.ie n .IP """PL_tmps_floor""" 4 |
| 19900 |
.el .IP \f(CWPL_tmps_floor\fR 4 |
| 19901 |
.IX Item "PL_tmps_floor" |
| 19902 |
Described in perlguts. |
| 19903 |
.ie n .IP """PL_tmps_ix""" 4 |
| 19904 |
.el .IP \f(CWPL_tmps_ix\fR 4 |
| 19905 |
.IX Item "PL_tmps_ix" |
| 19906 |
Described in perlguts. |
| 19907 |
.ie n .IP """PL_tmps_stack""" 4 |
| 19908 |
.el .IP \f(CWPL_tmps_stack\fR 4 |
| 19909 |
.IX Item "PL_tmps_stack" |
| 19910 |
Described in perlguts. |
| 19911 |
.ie n .IP """POPi""" 4 |
| 19912 |
.el .IP \f(CWPOPi\fR 4 |
| 19913 |
.IX Xref "POPi" |
| 19914 |
.IX Item "POPi" |
| 19915 |
Pops an integer off the stack. |
| 19916 |
.RS 4 |
| 19917 |
.Sp |
| 19918 |
.Vb 1 |
| 19919 |
\& IV POPi |
| 19920 |
.Ve |
| 19921 |
.RE |
| 19922 |
.RS 4 |
| 19923 |
.RE |
| 19924 |
.ie n .IP """POPl""" 4 |
| 19925 |
.el .IP \f(CWPOPl\fR 4 |
| 19926 |
.IX Xref "POPl" |
| 19927 |
.IX Item "POPl" |
| 19928 |
Pops a long off the stack. |
| 19929 |
.RS 4 |
| 19930 |
.Sp |
| 19931 |
.Vb 1 |
| 19932 |
\& long POPl |
| 19933 |
.Ve |
| 19934 |
.RE |
| 19935 |
.RS 4 |
| 19936 |
.RE |
| 19937 |
.ie n .IP """POPn""" 4 |
| 19938 |
.el .IP \f(CWPOPn\fR 4 |
| 19939 |
.IX Xref "POPn" |
| 19940 |
.IX Item "POPn" |
| 19941 |
Pops a double off the stack. |
| 19942 |
.RS 4 |
| 19943 |
.Sp |
| 19944 |
.Vb 1 |
| 19945 |
\& NV POPn |
| 19946 |
.Ve |
| 19947 |
.RE |
| 19948 |
.RS 4 |
| 19949 |
.RE |
| 19950 |
.ie n .IP """POPp""" 4 |
| 19951 |
.el .IP \f(CWPOPp\fR 4 |
| 19952 |
.IX Xref "POPp" |
| 19953 |
.IX Item "POPp" |
| 19954 |
Pops a string off the stack. |
| 19955 |
.RS 4 |
| 19956 |
.Sp |
| 19957 |
.Vb 1 |
| 19958 |
\& char* POPp |
| 19959 |
.Ve |
| 19960 |
.RE |
| 19961 |
.RS 4 |
| 19962 |
.RE |
| 19963 |
.ie n .IP """POPpbytex""" 4 |
| 19964 |
.el .IP \f(CWPOPpbytex\fR 4 |
| 19965 |
.IX Xref "POPpbytex" |
| 19966 |
.IX Item "POPpbytex" |
| 19967 |
Pops a string off the stack which must consist of bytes i.e. characters < 256. |
| 19968 |
.RS 4 |
| 19969 |
.Sp |
| 19970 |
.Vb 1 |
| 19971 |
\& char* POPpbytex |
| 19972 |
.Ve |
| 19973 |
.RE |
| 19974 |
.RS 4 |
| 19975 |
.RE |
| 19976 |
.ie n .IP """POPpx""" 4 |
| 19977 |
.el .IP \f(CWPOPpx\fR 4 |
| 19978 |
.IX Xref "POPpx" |
| 19979 |
.IX Item "POPpx" |
| 19980 |
Pops a string off the stack. Identical to POPp. There are two names for |
| 19981 |
historical reasons. |
| 19982 |
.RS 4 |
| 19983 |
.Sp |
| 19984 |
.Vb 1 |
| 19985 |
\& char* POPpx |
| 19986 |
.Ve |
| 19987 |
.RE |
| 19988 |
.RS 4 |
| 19989 |
.RE |
| 19990 |
.ie n .IP """POPs""" 4 |
| 19991 |
.el .IP \f(CWPOPs\fR 4 |
| 19992 |
.IX Xref "POPs" |
| 19993 |
.IX Item "POPs" |
| 19994 |
Pops an SV off the stack. |
| 19995 |
.RS 4 |
| 19996 |
.Sp |
| 19997 |
.Vb 1 |
| 19998 |
\& SV* POPs |
| 19999 |
.Ve |
| 20000 |
.RE |
| 20001 |
.RS 4 |
| 20002 |
.RE |
| 20003 |
.ie n .IP """POPu""" 4 |
| 20004 |
.el .IP \f(CWPOPu\fR 4 |
| 20005 |
.IX Xref "POPu" |
| 20006 |
.IX Item "POPu" |
| 20007 |
Pops an unsigned integer off the stack. |
| 20008 |
.RS 4 |
| 20009 |
.Sp |
| 20010 |
.Vb 1 |
| 20011 |
\& UV POPu |
| 20012 |
.Ve |
| 20013 |
.RE |
| 20014 |
.RS 4 |
| 20015 |
.RE |
| 20016 |
.ie n .IP """POPul""" 4 |
| 20017 |
.el .IP \f(CWPOPul\fR 4 |
| 20018 |
.IX Xref "POPul" |
| 20019 |
.IX Item "POPul" |
| 20020 |
Pops an unsigned long off the stack. |
| 20021 |
.RS 4 |
| 20022 |
.Sp |
| 20023 |
.Vb 1 |
| 20024 |
\& long POPul |
| 20025 |
.Ve |
| 20026 |
.RE |
| 20027 |
.RS 4 |
| 20028 |
.RE |
| 20029 |
.ie n .IP """PUSHi""" 4 |
| 20030 |
.el .IP \f(CWPUSHi\fR 4 |
| 20031 |
.IX Xref "PUSHi" |
| 20032 |
.IX Item "PUSHi" |
| 20033 |
Push an integer onto the stack. The stack must have room for this element. |
| 20034 |
Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be |
| 20035 |
called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to |
| 20036 |
return lists from XSUB's \- see \f(CW"mPUSHi"\fR instead. See also \f(CW"XPUSHi"\fR |
| 20037 |
and \f(CW"mXPUSHi"\fR. |
| 20038 |
.RS 4 |
| 20039 |
.Sp |
| 20040 |
.Vb 1 |
| 20041 |
\& void PUSHi(IV iv) |
| 20042 |
.Ve |
| 20043 |
.RE |
| 20044 |
.RS 4 |
| 20045 |
.RE |
| 20046 |
.ie n .IP """PUSHMARK""" 4 |
| 20047 |
.el .IP \f(CWPUSHMARK\fR 4 |
| 20048 |
.IX Xref "PUSHMARK" |
| 20049 |
.IX Item "PUSHMARK" |
| 20050 |
Opening bracket for arguments on a callback. See \f(CW"PUTBACK"\fR and |
| 20051 |
perlcall. |
| 20052 |
.RS 4 |
| 20053 |
.Sp |
| 20054 |
.Vb 1 |
| 20055 |
\& void PUSHMARK(SP) |
| 20056 |
.Ve |
| 20057 |
.RE |
| 20058 |
.RS 4 |
| 20059 |
.RE |
| 20060 |
.ie n .IP """PUSHmortal""" 4 |
| 20061 |
.el .IP \f(CWPUSHmortal\fR 4 |
| 20062 |
.IX Xref "PUSHmortal" |
| 20063 |
.IX Item "PUSHmortal" |
| 20064 |
Push a new mortal SV onto the stack. The stack must have room for this |
| 20065 |
element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR, \f(CW"XPUSHmortal"\fR and |
| 20066 |
\&\f(CW"XPUSHs"\fR. |
| 20067 |
.RS 4 |
| 20068 |
.Sp |
| 20069 |
.Vb 1 |
| 20070 |
\& void PUSHmortal |
| 20071 |
.Ve |
| 20072 |
.RE |
| 20073 |
.RS 4 |
| 20074 |
.RE |
| 20075 |
.ie n .IP """PUSHn""" 4 |
| 20076 |
.el .IP \f(CWPUSHn\fR 4 |
| 20077 |
.IX Xref "PUSHn" |
| 20078 |
.IX Item "PUSHn" |
| 20079 |
Push a double onto the stack. The stack must have room for this element. |
| 20080 |
Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be |
| 20081 |
called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to |
| 20082 |
return lists from XSUB's \- see \f(CW"mPUSHn"\fR instead. See also \f(CW"XPUSHn"\fR |
| 20083 |
and \f(CW"mXPUSHn"\fR. |
| 20084 |
.RS 4 |
| 20085 |
.Sp |
| 20086 |
.Vb 1 |
| 20087 |
\& void PUSHn(NV nv) |
| 20088 |
.Ve |
| 20089 |
.RE |
| 20090 |
.RS 4 |
| 20091 |
.RE |
| 20092 |
.ie n .IP """PUSHp""" 4 |
| 20093 |
.el .IP \f(CWPUSHp\fR 4 |
| 20094 |
.IX Xref "PUSHp" |
| 20095 |
.IX Item "PUSHp" |
| 20096 |
Push a string onto the stack. The stack must have room for this element. |
| 20097 |
The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles 'set' magic. Uses |
| 20098 |
\&\f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not |
| 20099 |
call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see |
| 20100 |
\&\f(CW"mPUSHp"\fR instead. See also \f(CW"XPUSHp"\fR and \f(CW"mXPUSHp"\fR. |
| 20101 |
.RS 4 |
| 20102 |
.Sp |
| 20103 |
.Vb 1 |
| 20104 |
\& void PUSHp(char* str, STRLEN len) |
| 20105 |
.Ve |
| 20106 |
.RE |
| 20107 |
.RS 4 |
| 20108 |
.RE |
| 20109 |
.ie n .IP """PUSHpvs""" 4 |
| 20110 |
.el .IP \f(CWPUSHpvs\fR 4 |
| 20111 |
.IX Xref "PUSHpvs" |
| 20112 |
.IX Item "PUSHpvs" |
| 20113 |
A variation on \f(CW\*(C`PUSHp\*(C'\fR that takes a literal string and calculates its size |
| 20114 |
directly. |
| 20115 |
.RS 4 |
| 20116 |
.Sp |
| 20117 |
.Vb 1 |
| 20118 |
\& void PUSHpvs("literal string") |
| 20119 |
.Ve |
| 20120 |
.RE |
| 20121 |
.RS 4 |
| 20122 |
.RE |
| 20123 |
.ie n .IP """PUSHs""" 4 |
| 20124 |
.el .IP \f(CWPUSHs\fR 4 |
| 20125 |
.IX Xref "PUSHs" |
| 20126 |
.IX Item "PUSHs" |
| 20127 |
Push an SV onto the stack. The stack must have room for this element. |
| 20128 |
Does not handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also |
| 20129 |
\&\f(CW"PUSHmortal"\fR, \f(CW"XPUSHs"\fR, and \f(CW"XPUSHmortal"\fR. |
| 20130 |
.RS 4 |
| 20131 |
.Sp |
| 20132 |
.Vb 1 |
| 20133 |
\& void PUSHs(SV* sv) |
| 20134 |
.Ve |
| 20135 |
.RE |
| 20136 |
.RS 4 |
| 20137 |
.RE |
| 20138 |
.ie n .IP """PUSHu""" 4 |
| 20139 |
.el .IP \f(CWPUSHu\fR 4 |
| 20140 |
.IX Xref "PUSHu" |
| 20141 |
.IX Item "PUSHu" |
| 20142 |
Push an unsigned integer onto the stack. The stack must have room for this |
| 20143 |
element. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR |
| 20144 |
should be called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented |
| 20145 |
macros to return lists from XSUB's \- see \f(CW"mPUSHu"\fR instead. See also |
| 20146 |
\&\f(CW"XPUSHu"\fR and \f(CW"mXPUSHu"\fR. |
| 20147 |
.RS 4 |
| 20148 |
.Sp |
| 20149 |
.Vb 1 |
| 20150 |
\& void PUSHu(UV uv) |
| 20151 |
.Ve |
| 20152 |
.RE |
| 20153 |
.RS 4 |
| 20154 |
.RE |
| 20155 |
.ie n .IP """PUTBACK""" 4 |
| 20156 |
.el .IP \f(CWPUTBACK\fR 4 |
| 20157 |
.IX Xref "PUTBACK" |
| 20158 |
.IX Item "PUTBACK" |
| 20159 |
Closing bracket for XSUB arguments. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. |
| 20160 |
See \f(CW"PUSHMARK"\fR and perlcall for other uses. |
| 20161 |
.RS 4 |
| 20162 |
.Sp |
| 20163 |
.Vb 1 |
| 20164 |
\& PUTBACK; |
| 20165 |
.Ve |
| 20166 |
.RE |
| 20167 |
.RS 4 |
| 20168 |
.RE |
| 20169 |
.ie n .IP """SAVEt_INT""" 4 |
| 20170 |
.el .IP \f(CWSAVEt_INT\fR 4 |
| 20171 |
.IX Item "SAVEt_INT" |
| 20172 |
Described in perlguts. |
| 20173 |
.ie n .IP """SP""" 4 |
| 20174 |
.el .IP \f(CWSP\fR 4 |
| 20175 |
.IX Xref "SP" |
| 20176 |
.IX Item "SP" |
| 20177 |
Stack pointer. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. See \f(CW"dSP"\fR and |
| 20178 |
\&\f(CW\*(C`SPAGAIN\*(C'\fR. |
| 20179 |
.ie n .IP """SPAGAIN""" 4 |
| 20180 |
.el .IP \f(CWSPAGAIN\fR 4 |
| 20181 |
.IX Xref "SPAGAIN" |
| 20182 |
.IX Item "SPAGAIN" |
| 20183 |
Refetch the stack pointer. Used after a callback. See perlcall. |
| 20184 |
.RS 4 |
| 20185 |
.Sp |
| 20186 |
.Vb 1 |
| 20187 |
\& SPAGAIN; |
| 20188 |
.Ve |
| 20189 |
.RE |
| 20190 |
.RS 4 |
| 20191 |
.RE |
| 20192 |
.ie n .IP """SSNEW""" 4 |
| 20193 |
.el .IP \f(CWSSNEW\fR 4 |
| 20194 |
.IX Item "SSNEW" |
| 20195 |
.PD 0 |
| 20196 |
.ie n .IP """SSNEWa""" 4 |
| 20197 |
.el .IP \f(CWSSNEWa\fR 4 |
| 20198 |
.IX Item "SSNEWa" |
| 20199 |
.ie n .IP """SSNEWat""" 4 |
| 20200 |
.el .IP \f(CWSSNEWat\fR 4 |
| 20201 |
.IX Item "SSNEWat" |
| 20202 |
.ie n .IP """SSNEWt""" 4 |
| 20203 |
.el .IP \f(CWSSNEWt\fR 4 |
| 20204 |
.IX Xref "SSNEW SSNEWa SSNEWat SSNEWt" |
| 20205 |
.IX Item "SSNEWt" |
| 20206 |
.PD |
| 20207 |
These each temporarily allocate data on the savestack, returning an SSize_t |
| 20208 |
index into the savestack, because a pointer would get broken if the savestack |
| 20209 |
is moved on reallocation. Use "\f(CW\*(C`SSPTR\*(C'\fR" to convert the returned index into |
| 20210 |
a pointer. |
| 20211 |
.Sp |
| 20212 |
The forms differ in that plain \f(CW\*(C`SSNEW\*(C'\fR allocates \f(CW\*(C`size\*(C'\fR bytes; |
| 20213 |
\&\f(CW\*(C`SSNEWt\*(C'\fR and \f(CW\*(C`SSNEWat\*(C'\fR allocate \f(CW\*(C`size\*(C'\fR objects, each of which is type |
| 20214 |
\&\f(CW\*(C`type\*(C'\fR; |
| 20215 |
and <SSNEWa> and \f(CW\*(C`SSNEWat\*(C'\fR make sure to align the new data to an \f(CW\*(C`align\*(C'\fR |
| 20216 |
boundary. The most useful value for the alignment is likely to be |
| 20217 |
"\f(CW\*(C`MEM_ALIGNBYTES\*(C'\fR". The alignment will be preserved through savestack |
| 20218 |
reallocation \fBonly\fR if realloc returns data aligned to a size divisible by |
| 20219 |
"align"! |
| 20220 |
.RS 4 |
| 20221 |
.Sp |
| 20222 |
.Vb 4 |
| 20223 |
\& SSize_t SSNEW (Size_t size) |
| 20224 |
\& SSize_t SSNEWa (Size_t size, Size_t align) |
| 20225 |
\& SSize_t SSNEWat(Size_t size, type, Size_t align) |
| 20226 |
\& SSize_t SSNEWt (Size_t size, type) |
| 20227 |
.Ve |
| 20228 |
.RE |
| 20229 |
.RS 4 |
| 20230 |
.RE |
| 20231 |
.ie n .IP """SSPTR""" 4 |
| 20232 |
.el .IP \f(CWSSPTR\fR 4 |
| 20233 |
.IX Item "SSPTR" |
| 20234 |
.PD 0 |
| 20235 |
.ie n .IP """SSPTRt""" 4 |
| 20236 |
.el .IP \f(CWSSPTRt\fR 4 |
| 20237 |
.IX Xref "SSPTR SSPTRt" |
| 20238 |
.IX Item "SSPTRt" |
| 20239 |
.PD |
| 20240 |
These convert the \f(CW\*(C`index\*(C'\fR returned by L/<\f(CW\*(C`SSNEW\*(C'\fR> and kin into actual pointers. |
| 20241 |
.Sp |
| 20242 |
The difference is that \f(CW\*(C`SSPTR\*(C'\fR casts the result to \f(CW\*(C`type\*(C'\fR, and \f(CW\*(C`SSPTRt\*(C'\fR |
| 20243 |
casts it to a pointer of that \f(CW\*(C`type\*(C'\fR. |
| 20244 |
.RS 4 |
| 20245 |
.Sp |
| 20246 |
.Vb 2 |
| 20247 |
\& type SSPTR (SSize_t index, type) |
| 20248 |
\& type * SSPTRt(SSize_t index, type) |
| 20249 |
.Ve |
| 20250 |
.RE |
| 20251 |
.RS 4 |
| 20252 |
.RE |
| 20253 |
.ie n .IP """TARG""" 4 |
| 20254 |
.el .IP \f(CWTARG\fR 4 |
| 20255 |
.IX Xref "TARG" |
| 20256 |
.IX Item "TARG" |
| 20257 |
\&\f(CW\*(C`TARG\*(C'\fR is short for "target". It is an entry in the pad that an OPs |
| 20258 |
\&\f(CW\*(C`op_targ\*(C'\fR refers to. It is scratchpad space, often used as a return |
| 20259 |
value for the OP, but some use it for other purposes. |
| 20260 |
.RS 4 |
| 20261 |
.Sp |
| 20262 |
.Vb 1 |
| 20263 |
\& TARG; |
| 20264 |
.Ve |
| 20265 |
.RE |
| 20266 |
.RS 4 |
| 20267 |
.RE |
| 20268 |
.ie n .IP """TOPs""" 4 |
| 20269 |
.el .IP \f(CWTOPs\fR 4 |
| 20270 |
.IX Item "TOPs" |
| 20271 |
Described in perlguts. |
| 20272 |
.ie n .IP """XPUSHi""" 4 |
| 20273 |
.el .IP \f(CWXPUSHi\fR 4 |
| 20274 |
.IX Xref "XPUSHi" |
| 20275 |
.IX Item "XPUSHi" |
| 20276 |
Push an integer onto the stack, extending the stack if necessary. Handles |
| 20277 |
\&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to |
| 20278 |
declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists |
| 20279 |
from XSUB's \- see \f(CW"mXPUSHi"\fR instead. See also \f(CW"PUSHi"\fR and |
| 20280 |
\&\f(CW"mPUSHi"\fR. |
| 20281 |
.RS 4 |
| 20282 |
.Sp |
| 20283 |
.Vb 1 |
| 20284 |
\& void XPUSHi(IV iv) |
| 20285 |
.Ve |
| 20286 |
.RE |
| 20287 |
.RS 4 |
| 20288 |
.RE |
| 20289 |
.ie n .IP """XPUSHmortal""" 4 |
| 20290 |
.el .IP \f(CWXPUSHmortal\fR 4 |
| 20291 |
.IX Xref "XPUSHmortal" |
| 20292 |
.IX Item "XPUSHmortal" |
| 20293 |
Push a new mortal SV onto the stack, extending the stack if necessary. |
| 20294 |
Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR, \f(CW"PUSHmortal"\fR and |
| 20295 |
\&\f(CW"PUSHs"\fR. |
| 20296 |
.RS 4 |
| 20297 |
.Sp |
| 20298 |
.Vb 1 |
| 20299 |
\& void XPUSHmortal |
| 20300 |
.Ve |
| 20301 |
.RE |
| 20302 |
.RS 4 |
| 20303 |
.RE |
| 20304 |
.ie n .IP """XPUSHn""" 4 |
| 20305 |
.el .IP \f(CWXPUSHn\fR 4 |
| 20306 |
.IX Xref "XPUSHn" |
| 20307 |
.IX Item "XPUSHn" |
| 20308 |
Push a double onto the stack, extending the stack if necessary. Handles |
| 20309 |
\&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to |
| 20310 |
declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists |
| 20311 |
from XSUB's \- see \f(CW"mXPUSHn"\fR instead. See also \f(CW"PUSHn"\fR and |
| 20312 |
\&\f(CW"mPUSHn"\fR. |
| 20313 |
.RS 4 |
| 20314 |
.Sp |
| 20315 |
.Vb 1 |
| 20316 |
\& void XPUSHn(NV nv) |
| 20317 |
.Ve |
| 20318 |
.RE |
| 20319 |
.RS 4 |
| 20320 |
.RE |
| 20321 |
.ie n .IP """XPUSHp""" 4 |
| 20322 |
.el .IP \f(CWXPUSHp\fR 4 |
| 20323 |
.IX Xref "XPUSHp" |
| 20324 |
.IX Item "XPUSHp" |
| 20325 |
Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR |
| 20326 |
indicates the length of the string. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so |
| 20327 |
\&\f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not call |
| 20328 |
multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see |
| 20329 |
\&\f(CW"mXPUSHp"\fR instead. See also \f(CW"PUSHp"\fR and \f(CW"mPUSHp"\fR. |
| 20330 |
.RS 4 |
| 20331 |
.Sp |
| 20332 |
.Vb 1 |
| 20333 |
\& void XPUSHp(char* str, STRLEN len) |
| 20334 |
.Ve |
| 20335 |
.RE |
| 20336 |
.RS 4 |
| 20337 |
.RE |
| 20338 |
.ie n .IP """XPUSHpvs""" 4 |
| 20339 |
.el .IP \f(CWXPUSHpvs\fR 4 |
| 20340 |
.IX Xref "XPUSHpvs" |
| 20341 |
.IX Item "XPUSHpvs" |
| 20342 |
A variation on \f(CW\*(C`XPUSHp\*(C'\fR that takes a literal string and calculates its size |
| 20343 |
directly. |
| 20344 |
.RS 4 |
| 20345 |
.Sp |
| 20346 |
.Vb 1 |
| 20347 |
\& void XPUSHpvs("literal string") |
| 20348 |
.Ve |
| 20349 |
.RE |
| 20350 |
.RS 4 |
| 20351 |
.RE |
| 20352 |
.ie n .IP """XPUSHs""" 4 |
| 20353 |
.el .IP \f(CWXPUSHs\fR 4 |
| 20354 |
.IX Xref "XPUSHs" |
| 20355 |
.IX Item "XPUSHs" |
| 20356 |
Push an SV onto the stack, extending the stack if necessary. Does not |
| 20357 |
handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHmortal"\fR, |
| 20358 |
\&\f(CW\*(C`PUSHs\*(C'\fR and \f(CW\*(C`PUSHmortal\*(C'\fR. |
| 20359 |
.RS 4 |
| 20360 |
.Sp |
| 20361 |
.Vb 1 |
| 20362 |
\& void XPUSHs(SV* sv) |
| 20363 |
.Ve |
| 20364 |
.RE |
| 20365 |
.RS 4 |
| 20366 |
.RE |
| 20367 |
.ie n .IP """XPUSHu""" 4 |
| 20368 |
.el .IP \f(CWXPUSHu\fR 4 |
| 20369 |
.IX Xref "XPUSHu" |
| 20370 |
.IX Item "XPUSHu" |
| 20371 |
Push an unsigned integer onto the stack, extending the stack if necessary. |
| 20372 |
Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be |
| 20373 |
called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to |
| 20374 |
return lists from XSUB's \- see \f(CW"mXPUSHu"\fR instead. See also \f(CW"PUSHu"\fR and |
| 20375 |
\&\f(CW"mPUSHu"\fR. |
| 20376 |
.RS 4 |
| 20377 |
.Sp |
| 20378 |
.Vb 1 |
| 20379 |
\& void XPUSHu(UV uv) |
| 20380 |
.Ve |
| 20381 |
.RE |
| 20382 |
.RS 4 |
| 20383 |
.RE |
| 20384 |
.ie n .IP """XS_APIVERSION_BOOTCHECK""" 4 |
| 20385 |
.el .IP \f(CWXS_APIVERSION_BOOTCHECK\fR 4 |
| 20386 |
.IX Xref "XS_APIVERSION_BOOTCHECK" |
| 20387 |
.IX Item "XS_APIVERSION_BOOTCHECK" |
| 20388 |
Macro to verify that the perl api version an XS module has been compiled against |
| 20389 |
matches the api version of the perl interpreter it's being loaded into. |
| 20390 |
.RS 4 |
| 20391 |
.Sp |
| 20392 |
.Vb 1 |
| 20393 |
\& XS_APIVERSION_BOOTCHECK; |
| 20394 |
.Ve |
| 20395 |
.RE |
| 20396 |
.RS 4 |
| 20397 |
.RE |
| 20398 |
.ie n .IP """XSRETURN""" 4 |
| 20399 |
.el .IP \f(CWXSRETURN\fR 4 |
| 20400 |
.IX Xref "XSRETURN" |
| 20401 |
.IX Item "XSRETURN" |
| 20402 |
Return from XSUB, indicating number of items on the stack. This is usually |
| 20403 |
handled by \f(CW\*(C`xsubpp\*(C'\fR. |
| 20404 |
.RS 4 |
| 20405 |
.Sp |
| 20406 |
.Vb 1 |
| 20407 |
\& void XSRETURN(int nitems) |
| 20408 |
.Ve |
| 20409 |
.RE |
| 20410 |
.RS 4 |
| 20411 |
.RE |
| 20412 |
.ie n .IP """XSRETURN_EMPTY""" 4 |
| 20413 |
.el .IP \f(CWXSRETURN_EMPTY\fR 4 |
| 20414 |
.IX Xref "XSRETURN_EMPTY" |
| 20415 |
.IX Item "XSRETURN_EMPTY" |
| 20416 |
Return an empty list from an XSUB immediately. |
| 20417 |
.RS 4 |
| 20418 |
.Sp |
| 20419 |
.Vb 1 |
| 20420 |
\& XSRETURN_EMPTY; |
| 20421 |
.Ve |
| 20422 |
.RE |
| 20423 |
.RS 4 |
| 20424 |
.RE |
| 20425 |
.ie n .IP """XSRETURN_IV""" 4 |
| 20426 |
.el .IP \f(CWXSRETURN_IV\fR 4 |
| 20427 |
.IX Xref "XSRETURN_IV" |
| 20428 |
.IX Item "XSRETURN_IV" |
| 20429 |
Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mIV\*(C'\fR. |
| 20430 |
.RS 4 |
| 20431 |
.Sp |
| 20432 |
.Vb 1 |
| 20433 |
\& void XSRETURN_IV(IV iv) |
| 20434 |
.Ve |
| 20435 |
.RE |
| 20436 |
.RS 4 |
| 20437 |
.RE |
| 20438 |
.ie n .IP """XSRETURN_NO""" 4 |
| 20439 |
.el .IP \f(CWXSRETURN_NO\fR 4 |
| 20440 |
.IX Xref "XSRETURN_NO" |
| 20441 |
.IX Item "XSRETURN_NO" |
| 20442 |
Return \f(CW&PL_sv_no\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mNO\*(C'\fR. |
| 20443 |
.RS 4 |
| 20444 |
.Sp |
| 20445 |
.Vb 1 |
| 20446 |
\& XSRETURN_NO; |
| 20447 |
.Ve |
| 20448 |
.RE |
| 20449 |
.RS 4 |
| 20450 |
.RE |
| 20451 |
.ie n .IP """XSRETURN_NV""" 4 |
| 20452 |
.el .IP \f(CWXSRETURN_NV\fR 4 |
| 20453 |
.IX Xref "XSRETURN_NV" |
| 20454 |
.IX Item "XSRETURN_NV" |
| 20455 |
Return a double from an XSUB immediately. Uses \f(CW\*(C`XST_mNV\*(C'\fR. |
| 20456 |
.RS 4 |
| 20457 |
.Sp |
| 20458 |
.Vb 1 |
| 20459 |
\& void XSRETURN_NV(NV nv) |
| 20460 |
.Ve |
| 20461 |
.RE |
| 20462 |
.RS 4 |
| 20463 |
.RE |
| 20464 |
.ie n .IP """XSRETURN_PV""" 4 |
| 20465 |
.el .IP \f(CWXSRETURN_PV\fR 4 |
| 20466 |
.IX Xref "XSRETURN_PV" |
| 20467 |
.IX Item "XSRETURN_PV" |
| 20468 |
Return a copy of a string from an XSUB immediately. Uses \f(CW\*(C`XST_mPV\*(C'\fR. |
| 20469 |
.RS 4 |
| 20470 |
.Sp |
| 20471 |
.Vb 1 |
| 20472 |
\& void XSRETURN_PV(char* str) |
| 20473 |
.Ve |
| 20474 |
.RE |
| 20475 |
.RS 4 |
| 20476 |
.RE |
| 20477 |
.ie n .IP """XSRETURN_UNDEF""" 4 |
| 20478 |
.el .IP \f(CWXSRETURN_UNDEF\fR 4 |
| 20479 |
.IX Xref "XSRETURN_UNDEF" |
| 20480 |
.IX Item "XSRETURN_UNDEF" |
| 20481 |
Return \f(CW&PL_sv_undef\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR. |
| 20482 |
.RS 4 |
| 20483 |
.Sp |
| 20484 |
.Vb 1 |
| 20485 |
\& XSRETURN_UNDEF; |
| 20486 |
.Ve |
| 20487 |
.RE |
| 20488 |
.RS 4 |
| 20489 |
.RE |
| 20490 |
.ie n .IP """XSRETURN_UV""" 4 |
| 20491 |
.el .IP \f(CWXSRETURN_UV\fR 4 |
| 20492 |
.IX Xref "XSRETURN_UV" |
| 20493 |
.IX Item "XSRETURN_UV" |
| 20494 |
Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mUV\*(C'\fR. |
| 20495 |
.RS 4 |
| 20496 |
.Sp |
| 20497 |
.Vb 1 |
| 20498 |
\& void XSRETURN_UV(IV uv) |
| 20499 |
.Ve |
| 20500 |
.RE |
| 20501 |
.RS 4 |
| 20502 |
.RE |
| 20503 |
.ie n .IP """XSRETURN_YES""" 4 |
| 20504 |
.el .IP \f(CWXSRETURN_YES\fR 4 |
| 20505 |
.IX Xref "XSRETURN_YES" |
| 20506 |
.IX Item "XSRETURN_YES" |
| 20507 |
Return \f(CW&PL_sv_yes\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mYES\*(C'\fR. |
| 20508 |
.RS 4 |
| 20509 |
.Sp |
| 20510 |
.Vb 1 |
| 20511 |
\& XSRETURN_YES; |
| 20512 |
.Ve |
| 20513 |
.RE |
| 20514 |
.RS 4 |
| 20515 |
.RE |
| 20516 |
.ie n .IP """XST_mIV""" 4 |
| 20517 |
.el .IP \f(CWXST_mIV\fR 4 |
| 20518 |
.IX Xref "XST_mIV" |
| 20519 |
.IX Item "XST_mIV" |
| 20520 |
Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The |
| 20521 |
value is stored in a new mortal SV. |
| 20522 |
.RS 4 |
| 20523 |
.Sp |
| 20524 |
.Vb 1 |
| 20525 |
\& void XST_mIV(int pos, IV iv) |
| 20526 |
.Ve |
| 20527 |
.RE |
| 20528 |
.RS 4 |
| 20529 |
.RE |
| 20530 |
.ie n .IP """XST_mNO""" 4 |
| 20531 |
.el .IP \f(CWXST_mNO\fR 4 |
| 20532 |
.IX Xref "XST_mNO" |
| 20533 |
.IX Item "XST_mNO" |
| 20534 |
Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the |
| 20535 |
stack. |
| 20536 |
.RS 4 |
| 20537 |
.Sp |
| 20538 |
.Vb 1 |
| 20539 |
\& void XST_mNO(int pos) |
| 20540 |
.Ve |
| 20541 |
.RE |
| 20542 |
.RS 4 |
| 20543 |
.RE |
| 20544 |
.ie n .IP """XST_mNV""" 4 |
| 20545 |
.el .IP \f(CWXST_mNV\fR 4 |
| 20546 |
.IX Xref "XST_mNV" |
| 20547 |
.IX Item "XST_mNV" |
| 20548 |
Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The value |
| 20549 |
is stored in a new mortal SV. |
| 20550 |
.RS 4 |
| 20551 |
.Sp |
| 20552 |
.Vb 1 |
| 20553 |
\& void XST_mNV(int pos, NV nv) |
| 20554 |
.Ve |
| 20555 |
.RE |
| 20556 |
.RS 4 |
| 20557 |
.RE |
| 20558 |
.ie n .IP """XST_mPV""" 4 |
| 20559 |
.el .IP \f(CWXST_mPV\fR 4 |
| 20560 |
.IX Xref "XST_mPV" |
| 20561 |
.IX Item "XST_mPV" |
| 20562 |
Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. |
| 20563 |
The value is stored in a new mortal SV. |
| 20564 |
.RS 4 |
| 20565 |
.Sp |
| 20566 |
.Vb 1 |
| 20567 |
\& void XST_mPV(int pos, char* str) |
| 20568 |
.Ve |
| 20569 |
.RE |
| 20570 |
.RS 4 |
| 20571 |
.RE |
| 20572 |
.ie n .IP """XST_mUNDEF""" 4 |
| 20573 |
.el .IP \f(CWXST_mUNDEF\fR 4 |
| 20574 |
.IX Xref "XST_mUNDEF" |
| 20575 |
.IX Item "XST_mUNDEF" |
| 20576 |
Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the |
| 20577 |
stack. |
| 20578 |
.RS 4 |
| 20579 |
.Sp |
| 20580 |
.Vb 1 |
| 20581 |
\& void XST_mUNDEF(int pos) |
| 20582 |
.Ve |
| 20583 |
.RE |
| 20584 |
.RS 4 |
| 20585 |
.RE |
| 20586 |
.ie n .IP """XST_mUV""" 4 |
| 20587 |
.el .IP \f(CWXST_mUV\fR 4 |
| 20588 |
.IX Xref "XST_mUV" |
| 20589 |
.IX Item "XST_mUV" |
| 20590 |
Place an unsigned integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The |
| 20591 |
value is stored in a new mortal SV. |
| 20592 |
.RS 4 |
| 20593 |
.Sp |
| 20594 |
.Vb 1 |
| 20595 |
\& void XST_mUV(int pos, UV uv) |
| 20596 |
.Ve |
| 20597 |
.RE |
| 20598 |
.RS 4 |
| 20599 |
.RE |
| 20600 |
.ie n .IP """XST_mYES""" 4 |
| 20601 |
.el .IP \f(CWXST_mYES\fR 4 |
| 20602 |
.IX Xref "XST_mYES" |
| 20603 |
.IX Item "XST_mYES" |
| 20604 |
Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the |
| 20605 |
stack. |
| 20606 |
.RS 4 |
| 20607 |
.Sp |
| 20608 |
.Vb 1 |
| 20609 |
\& void XST_mYES(int pos) |
| 20610 |
.Ve |
| 20611 |
.RE |
| 20612 |
.RS 4 |
| 20613 |
.RE |
| 20614 |
.ie n .IP """XS_VERSION""" 4 |
| 20615 |
.el .IP \f(CWXS_VERSION\fR 4 |
| 20616 |
.IX Xref "XS_VERSION" |
| 20617 |
.IX Item "XS_VERSION" |
| 20618 |
The version identifier for an XS module. This is usually |
| 20619 |
handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. See |
| 20620 |
\&\f(CW"XS_VERSION_BOOTCHECK"\fR. |
| 20621 |
.ie n .IP """XS_VERSION_BOOTCHECK""" 4 |
| 20622 |
.el .IP \f(CWXS_VERSION_BOOTCHECK\fR 4 |
| 20623 |
.IX Xref "XS_VERSION_BOOTCHECK" |
| 20624 |
.IX Item "XS_VERSION_BOOTCHECK" |
| 20625 |
Macro to verify that a PM module's \f(CW$VERSION\fR variable matches the XS |
| 20626 |
module's \f(CW\*(C`XS_VERSION\*(C'\fR variable. This is usually handled automatically by |
| 20627 |
\&\f(CW\*(C`xsubpp\*(C'\fR. See "The VERSIONCHECK: Keyword" in perlxs. |
| 20628 |
.RS 4 |
| 20629 |
.Sp |
| 20630 |
.Vb 1 |
| 20631 |
\& XS_VERSION_BOOTCHECK; |
| 20632 |
.Ve |
| 20633 |
.RE |
| 20634 |
.RS 4 |
| 20635 |
.RE |
| 20636 |
.SH "String Handling" |
| 20637 |
.IX Header "String Handling" |
| 20638 |
See also \f(CW"Unicode Support"\fR. |
| 20639 |
.ie n .IP """CAT2""" 4 |
| 20640 |
.el .IP \f(CWCAT2\fR 4 |
| 20641 |
.IX Xref "CAT2" |
| 20642 |
.IX Item "CAT2" |
| 20643 |
This macro concatenates 2 tokens together. |
| 20644 |
.RS 4 |
| 20645 |
.Sp |
| 20646 |
.Vb 1 |
| 20647 |
\& token CAT2(token x, token y) |
| 20648 |
.Ve |
| 20649 |
.RE |
| 20650 |
.RS 4 |
| 20651 |
.RE |
| 20652 |
.ie n .IP """Copy""" 4 |
| 20653 |
.el .IP \f(CWCopy\fR 4 |
| 20654 |
.IX Item "Copy" |
| 20655 |
.PD 0 |
| 20656 |
.ie n .IP """CopyD""" 4 |
| 20657 |
.el .IP \f(CWCopyD\fR 4 |
| 20658 |
.IX Xref "Copy CopyD" |
| 20659 |
.IX Item "CopyD" |
| 20660 |
.PD |
| 20661 |
The XSUB-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the |
| 20662 |
source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and |
| 20663 |
\&\f(CW\*(C`type\*(C'\fR is the type. May fail on overlapping copies. See also \f(CW"Move"\fR. |
| 20664 |
.Sp |
| 20665 |
\&\f(CW\*(C`CopyD\*(C'\fR is like \f(CW\*(C`Copy\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful |
| 20666 |
for encouraging compilers to tail-call |
| 20667 |
optimise. |
| 20668 |
.RS 4 |
| 20669 |
.Sp |
| 20670 |
.Vb 2 |
| 20671 |
\& void Copy (void* src, void* dest, int nitems, type) |
| 20672 |
\& void * CopyD(void* src, void* dest, int nitems, type) |
| 20673 |
.Ve |
| 20674 |
.RE |
| 20675 |
.RS 4 |
| 20676 |
.RE |
| 20677 |
.ie n .IP """delimcpy""" 4 |
| 20678 |
.el .IP \f(CWdelimcpy\fR 4 |
| 20679 |
.IX Xref "delimcpy" |
| 20680 |
.IX Item "delimcpy" |
| 20681 |
Copy a source buffer to a destination buffer, stopping at (but not including) |
| 20682 |
the first occurrence in the source of an unescaped (defined below) delimiter |
| 20683 |
byte, \f(CW\*(C`delim\*(C'\fR. The source is the bytes between \f(CW\*(C`from\*(C'\fR\ and\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1. Similarly, the dest is \f(CW\*(C`to\*(C'\fR up to \f(CW\*(C`to_end\*(C'\fR. |
| 20684 |
.Sp |
| 20685 |
The number of bytes copied is written to \f(CW*retlen\fR. |
| 20686 |
.Sp |
| 20687 |
Returns the position of the first uncopied \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but |
| 20688 |
if there is no such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned, |
| 20689 |
and the entire buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied. |
| 20690 |
.Sp |
| 20691 |
If there is room in the destination available after the copy, an extra |
| 20692 |
terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned |
| 20693 |
length). |
| 20694 |
.Sp |
| 20695 |
The error case is if the destination buffer is not large enough to accommodate |
| 20696 |
everything that should be copied. In this situation, a value larger than |
| 20697 |
\&\f(CW\*(C`to_end\*(C'\fR\ \-\ \f(CW\*(C`to\*(C'\fR is written to \f(CW*retlen\fR, and as much of the source as |
| 20698 |
fits will be written to the destination. Not having room for the safety \f(CW\*(C`NUL\*(C'\fR |
| 20699 |
is not considered an error. |
| 20700 |
.Sp |
| 20701 |
In the following examples, let \f(CW\*(C`x\*(C'\fR be the delimiter, and \f(CW0\fR represent a \f(CW\*(C`NUL\*(C'\fR |
| 20702 |
byte (\fBNOT\fR the digit \f(CW0\fR). Then we would have |
| 20703 |
.Sp |
| 20704 |
.Vb 2 |
| 20705 |
\& Source Destination |
| 20706 |
\& abcxdef abc0 |
| 20707 |
.Ve |
| 20708 |
.Sp |
| 20709 |
provided the destination buffer is at least 4 bytes long. |
| 20710 |
.Sp |
| 20711 |
An escaped delimiter is one which is immediately preceded by a single |
| 20712 |
backslash. Escaped delimiters are copied, and the copy continues past the |
| 20713 |
delimiter; the backslash is not copied: |
| 20714 |
.Sp |
| 20715 |
.Vb 2 |
| 20716 |
\& Source Destination |
| 20717 |
\& abc\exdef abcxdef0 |
| 20718 |
.Ve |
| 20719 |
.Sp |
| 20720 |
(provided the destination buffer is at least 8 bytes long). |
| 20721 |
.Sp |
| 20722 |
It's actually somewhat more complicated than that. A sequence of any odd number |
| 20723 |
of backslashes escapes the following delimiter, and the copy continues with |
| 20724 |
exactly one of the backslashes stripped. |
| 20725 |
.Sp |
| 20726 |
.Vb 4 |
| 20727 |
\& Source Destination |
| 20728 |
\& abc\exdef abcxdef0 |
| 20729 |
\& abc\e\e\exdef abc\e\exdef0 |
| 20730 |
\& abc\e\e\e\e\exdef abc\e\e\e\exdef0 |
| 20731 |
.Ve |
| 20732 |
.Sp |
| 20733 |
(as always, if the destination is large enough) |
| 20734 |
.Sp |
| 20735 |
An even number of preceding backslashes does not escape the delimiter, so that |
| 20736 |
the copy stops just before it, and includes all the backslashes (no stripping; |
| 20737 |
zero is considered even): |
| 20738 |
.Sp |
| 20739 |
.Vb 4 |
| 20740 |
\& Source Destination |
| 20741 |
\& abcxdef abc0 |
| 20742 |
\& abc\e\exdef abc\e\e0 |
| 20743 |
\& abc\e\e\e\exdef abc\e\e\e\e0 |
| 20744 |
.Ve |
| 20745 |
.RS 4 |
| 20746 |
.Sp |
| 20747 |
.Vb 3 |
| 20748 |
\& char * delimcpy(char *to, const char *to_end, const char *from, |
| 20749 |
\& const char *from_end, const int delim, |
| 20750 |
\& I32 *retlen) |
| 20751 |
.Ve |
| 20752 |
.RE |
| 20753 |
.RS 4 |
| 20754 |
.RE |
| 20755 |
.ie n .IP """do_join""" 4 |
| 20756 |
.el .IP \f(CWdo_join\fR 4 |
| 20757 |
.IX Xref "do_join" |
| 20758 |
.IX Item "do_join" |
| 20759 |
This performs a Perl \f(CW\*(C`join\*(C'\fR, placing the joined output |
| 20760 |
into \f(CW\*(C`sv\*(C'\fR. |
| 20761 |
.Sp |
| 20762 |
The elements to join are in SVs, stored in a C array of pointers to SVs, from |
| 20763 |
\&\f(CW**mark\fR to \f(CW\*(C`**sp\ \-\ 1\*(C'\fR. Hence \f(CW*mark\fR is a reference to the first SV. |
| 20764 |
Each SV will be coerced into a PV if not one already. |
| 20765 |
.Sp |
| 20766 |
\&\f(CW\*(C`delim\*(C'\fR contains the string (or coerced into a string) that is to separate |
| 20767 |
each of the joined elements. |
| 20768 |
.Sp |
| 20769 |
If any component is in UTF\-8, the result will be as well, and all non\-UTF\-8 |
| 20770 |
components will be converted to UTF\-8 as necessary. |
| 20771 |
.Sp |
| 20772 |
Magic and tainting are handled. |
| 20773 |
.RS 4 |
| 20774 |
.Sp |
| 20775 |
.Vb 1 |
| 20776 |
\& void do_join(SV *sv, SV *delim, SV **mark, SV **sp) |
| 20777 |
.Ve |
| 20778 |
.RE |
| 20779 |
.RS 4 |
| 20780 |
.RE |
| 20781 |
.ie n .IP """do_sprintf""" 4 |
| 20782 |
.el .IP \f(CWdo_sprintf\fR 4 |
| 20783 |
.IX Xref "do_sprintf" |
| 20784 |
.IX Item "do_sprintf" |
| 20785 |
This performs a Perl \f(CW\*(C`sprintf\*(C'\fR placing the string output |
| 20786 |
into \f(CW\*(C`sv\*(C'\fR. |
| 20787 |
.Sp |
| 20788 |
The elements to format are in SVs, stored in a C array of pointers to SVs of |
| 20789 |
length \f(CW\*(C`len\*(C'\fR> and beginning at \f(CW**sarg\fR. The element referenced by \f(CW*sarg\fR |
| 20790 |
is the format. |
| 20791 |
.Sp |
| 20792 |
Magic and tainting are handled. |
| 20793 |
.RS 4 |
| 20794 |
.Sp |
| 20795 |
.Vb 1 |
| 20796 |
\& void do_sprintf(SV *sv, SSize_t len, SV **sarg) |
| 20797 |
.Ve |
| 20798 |
.RE |
| 20799 |
.RS 4 |
| 20800 |
.RE |
| 20801 |
.ie n .IP """fbm_compile""" 4 |
| 20802 |
.el .IP \f(CWfbm_compile\fR 4 |
| 20803 |
.IX Xref "fbm_compile" |
| 20804 |
.IX Item "fbm_compile" |
| 20805 |
Analyzes the string in order to make fast searches on it using \f(CWfbm_instr()\fR |
| 20806 |
\&\-\- the Boyer-Moore algorithm. |
| 20807 |
.RS 4 |
| 20808 |
.Sp |
| 20809 |
.Vb 1 |
| 20810 |
\& void fbm_compile(SV *sv, U32 flags) |
| 20811 |
.Ve |
| 20812 |
.RE |
| 20813 |
.RS 4 |
| 20814 |
.RE |
| 20815 |
.ie n .IP """fbm_instr""" 4 |
| 20816 |
.el .IP \f(CWfbm_instr\fR 4 |
| 20817 |
.IX Xref "fbm_instr" |
| 20818 |
.IX Item "fbm_instr" |
| 20819 |
Returns the location of the SV in the string delimited by \f(CW\*(C`big\*(C'\fR and |
| 20820 |
\&\f(CW\*(C`bigend\*(C'\fR (\f(CW\*(C`bigend\*(C'\fR) is the char following the last char). |
| 20821 |
It returns \f(CW\*(C`NULL\*(C'\fR if the string can't be found. The \f(CW\*(C`sv\*(C'\fR |
| 20822 |
does not have to be \f(CW\*(C`fbm_compiled\*(C'\fR, but the search will not be as fast |
| 20823 |
then. |
| 20824 |
.RS 4 |
| 20825 |
.Sp |
| 20826 |
.Vb 2 |
| 20827 |
\& char * fbm_instr(unsigned char *big, unsigned char *bigend, |
| 20828 |
\& SV *littlestr, U32 flags) |
| 20829 |
.Ve |
| 20830 |
.RE |
| 20831 |
.RS 4 |
| 20832 |
.RE |
| 20833 |
.ie n .IP """foldEQ""" 4 |
| 20834 |
.el .IP \f(CWfoldEQ\fR 4 |
| 20835 |
.IX Xref "foldEQ" |
| 20836 |
.IX Item "foldEQ" |
| 20837 |
Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the |
| 20838 |
same |
| 20839 |
case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes |
| 20840 |
match themselves and their opposite case counterparts. Non-cased and non-ASCII |
| 20841 |
range bytes match only themselves. |
| 20842 |
.RS 4 |
| 20843 |
.Sp |
| 20844 |
.Vb 1 |
| 20845 |
\& I32 foldEQ(const char *a, const char *b, I32 len) |
| 20846 |
.Ve |
| 20847 |
.RE |
| 20848 |
.RS 4 |
| 20849 |
.RE |
| 20850 |
.ie n .IP """ibcmp""" 4 |
| 20851 |
.el .IP \f(CWibcmp\fR 4 |
| 20852 |
.IX Xref "ibcmp" |
| 20853 |
.IX Item "ibcmp" |
| 20854 |
This is a synonym for \f(CW\*(C`(!\ foldEQ())\*(C'\fR |
| 20855 |
.RS 4 |
| 20856 |
.Sp |
| 20857 |
.Vb 1 |
| 20858 |
\& I32 ibcmp(const char *a, const char *b, I32 len) |
| 20859 |
.Ve |
| 20860 |
.RE |
| 20861 |
.RS 4 |
| 20862 |
.RE |
| 20863 |
.ie n .IP """ibcmp_locale""" 4 |
| 20864 |
.el .IP \f(CWibcmp_locale\fR 4 |
| 20865 |
.IX Xref "ibcmp_locale" |
| 20866 |
.IX Item "ibcmp_locale" |
| 20867 |
This is a synonym for \f(CW\*(C`(!\ foldEQ_locale())\*(C'\fR |
| 20868 |
.RS 4 |
| 20869 |
.Sp |
| 20870 |
.Vb 1 |
| 20871 |
\& I32 ibcmp_locale(const char *a, const char *b, I32 len) |
| 20872 |
.Ve |
| 20873 |
.RE |
| 20874 |
.RS 4 |
| 20875 |
.RE |
| 20876 |
.ie n .IP """ibcmp_utf8""" 4 |
| 20877 |
.el .IP \f(CWibcmp_utf8\fR 4 |
| 20878 |
.IX Xref "ibcmp_utf8" |
| 20879 |
.IX Item "ibcmp_utf8" |
| 20880 |
This is a synonym for \f(CW\*(C`(!\ foldEQ_utf8())\*(C'\fR |
| 20881 |
.RS 4 |
| 20882 |
.Sp |
| 20883 |
.Vb 2 |
| 20884 |
\& I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, |
| 20885 |
\& const char *s2, char **pe2, UV l2, bool u2) |
| 20886 |
.Ve |
| 20887 |
.RE |
| 20888 |
.RS 4 |
| 20889 |
.RE |
| 20890 |
.ie n .IP """instr""" 4 |
| 20891 |
.el .IP \f(CWinstr\fR 4 |
| 20892 |
.IX Xref "instr" |
| 20893 |
.IX Item "instr" |
| 20894 |
Same as \fBstrstr\fR\|(3), which finds and returns a pointer to the first occurrence |
| 20895 |
of the NUL-terminated substring \f(CW\*(C`little\*(C'\fR in the NUL-terminated string \f(CW\*(C`big\*(C'\fR, |
| 20896 |
returning NULL if not found. The terminating NUL bytes are not compared. |
| 20897 |
.RS 4 |
| 20898 |
.Sp |
| 20899 |
.Vb 1 |
| 20900 |
\& char * instr(const char *big, const char *little) |
| 20901 |
.Ve |
| 20902 |
.RE |
| 20903 |
.RS 4 |
| 20904 |
.RE |
| 20905 |
.ie n .IP """memCHRs""" 4 |
| 20906 |
.el .IP \f(CWmemCHRs\fR 4 |
| 20907 |
.IX Xref "memCHRs" |
| 20908 |
.IX Item "memCHRs" |
| 20909 |
Returns the position of the first occurrence of the byte \f(CW\*(C`c\*(C'\fR in the literal |
| 20910 |
string \f(CW"list"\fR, or NULL if \f(CW\*(C`c\*(C'\fR doesn't appear in \f(CW"list"\fR. All bytes are |
| 20911 |
treated as unsigned char. Thus this macro can be used to determine if \f(CW\*(C`c\*(C'\fR is |
| 20912 |
in a set of particular characters. Unlike \fBstrchr\fR\|(3), it works even if \f(CW\*(C`c\*(C'\fR |
| 20913 |
is \f(CW\*(C`NUL\*(C'\fR (and the set doesn't include \f(CW\*(C`NUL\*(C'\fR). |
| 20914 |
.RS 4 |
| 20915 |
.Sp |
| 20916 |
.Vb 1 |
| 20917 |
\& bool memCHRs("list", char c) |
| 20918 |
.Ve |
| 20919 |
.RE |
| 20920 |
.RS 4 |
| 20921 |
.RE |
| 20922 |
.ie n .IP """memEQ""" 4 |
| 20923 |
.el .IP \f(CWmemEQ\fR 4 |
| 20924 |
.IX Xref "memEQ" |
| 20925 |
.IX Item "memEQ" |
| 20926 |
Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they |
| 20927 |
are equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare. |
| 20928 |
Returns true or false. It is undefined behavior if either of the buffers |
| 20929 |
doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes. |
| 20930 |
.RS 4 |
| 20931 |
.Sp |
| 20932 |
.Vb 1 |
| 20933 |
\& bool memEQ(char* s1, char* s2, STRLEN len) |
| 20934 |
.Ve |
| 20935 |
.RE |
| 20936 |
.RS 4 |
| 20937 |
.RE |
| 20938 |
.ie n .IP """memEQs""" 4 |
| 20939 |
.el .IP \f(CWmemEQs\fR 4 |
| 20940 |
.IX Xref "memEQs" |
| 20941 |
.IX Item "memEQs" |
| 20942 |
Like "memEQ", but the second string is a literal enclosed in double quotes, |
| 20943 |
\&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR. |
| 20944 |
Returns true or false. |
| 20945 |
.RS 4 |
| 20946 |
.Sp |
| 20947 |
.Vb 1 |
| 20948 |
\& bool memEQs(char* s1, STRLEN l1, "s2") |
| 20949 |
.Ve |
| 20950 |
.RE |
| 20951 |
.RS 4 |
| 20952 |
.RE |
| 20953 |
.ie n .IP """memNE""" 4 |
| 20954 |
.el .IP \f(CWmemNE\fR 4 |
| 20955 |
.IX Xref "memNE" |
| 20956 |
.IX Item "memNE" |
| 20957 |
Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they |
| 20958 |
are not equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare. |
| 20959 |
Returns true or false. It is undefined behavior if either of the buffers |
| 20960 |
doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes. |
| 20961 |
.RS 4 |
| 20962 |
.Sp |
| 20963 |
.Vb 1 |
| 20964 |
\& bool memNE(char* s1, char* s2, STRLEN len) |
| 20965 |
.Ve |
| 20966 |
.RE |
| 20967 |
.RS 4 |
| 20968 |
.RE |
| 20969 |
.ie n .IP """memNEs""" 4 |
| 20970 |
.el .IP \f(CWmemNEs\fR 4 |
| 20971 |
.IX Xref "memNEs" |
| 20972 |
.IX Item "memNEs" |
| 20973 |
Like "memNE", but the second string is a literal enclosed in double quotes, |
| 20974 |
\&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR. |
| 20975 |
Returns true or false. |
| 20976 |
.RS 4 |
| 20977 |
.Sp |
| 20978 |
.Vb 1 |
| 20979 |
\& bool memNEs(char* s1, STRLEN l1, "s2") |
| 20980 |
.Ve |
| 20981 |
.RE |
| 20982 |
.RS 4 |
| 20983 |
.RE |
| 20984 |
.ie n .IP """Move""" 4 |
| 20985 |
.el .IP \f(CWMove\fR 4 |
| 20986 |
.IX Item "Move" |
| 20987 |
.PD 0 |
| 20988 |
.ie n .IP """MoveD""" 4 |
| 20989 |
.el .IP \f(CWMoveD\fR 4 |
| 20990 |
.IX Xref "Move MoveD" |
| 20991 |
.IX Item "MoveD" |
| 20992 |
.PD |
| 20993 |
The XSUB-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the |
| 20994 |
source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and |
| 20995 |
\&\f(CW\*(C`type\*(C'\fR is the type. Can do overlapping moves. See also \f(CW"Copy"\fR. |
| 20996 |
.Sp |
| 20997 |
\&\f(CW\*(C`MoveD\*(C'\fR is like \f(CW\*(C`Move\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful |
| 20998 |
for encouraging compilers to tail-call |
| 20999 |
optimise. |
| 21000 |
.RS 4 |
| 21001 |
.Sp |
| 21002 |
.Vb 2 |
| 21003 |
\& void Move (void* src, void* dest, int nitems, type) |
| 21004 |
\& void * MoveD(void* src, void* dest, int nitems, type) |
| 21005 |
.Ve |
| 21006 |
.RE |
| 21007 |
.RS 4 |
| 21008 |
.RE |
| 21009 |
.ie n .IP """my_snprintf""" 4 |
| 21010 |
.el .IP \f(CWmy_snprintf\fR 4 |
| 21011 |
.IX Xref "my_snprintf" |
| 21012 |
.IX Item "my_snprintf" |
| 21013 |
The C library \f(CW\*(C`snprintf\*(C'\fR functionality, if available and |
| 21014 |
standards-compliant (uses \f(CW\*(C`vsnprintf\*(C'\fR, actually). However, if the |
| 21015 |
\&\f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately use the unsafe |
| 21016 |
\&\f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an overrun check, |
| 21017 |
but that may be too late). Consider using \f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or |
| 21018 |
getting \f(CW\*(C`vsnprintf\*(C'\fR. |
| 21019 |
.RS 4 |
| 21020 |
.Sp |
| 21021 |
.Vb 2 |
| 21022 |
\& int my_snprintf(char *buffer, const Size_t len, |
| 21023 |
\& const char *format, ...) |
| 21024 |
.Ve |
| 21025 |
.RE |
| 21026 |
.RS 4 |
| 21027 |
.RE |
| 21028 |
.ie n .IP """my_sprintf""" 4 |
| 21029 |
.el .IP \f(CWmy_sprintf\fR 4 |
| 21030 |
.IX Xref "my_sprintf" |
| 21031 |
.IX Item "my_sprintf" |
| 21032 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`my_sprintf\*(C'\fR |
| 21033 |
from a future release of Perl. Do not use it for |
| 21034 |
new code; remove it from existing code. |
| 21035 |
.Sp |
| 21036 |
Do NOT use this due to the possibility of overflowing \f(CW\*(C`buffer\*(C'\fR. Instead use |
| 21037 |
\&\fBmy_snprintf()\fR |
| 21038 |
.RS 4 |
| 21039 |
.Sp |
| 21040 |
.Vb 1 |
| 21041 |
\& int my_sprintf(NN char *buffer, NN const char *pat, ...) |
| 21042 |
.Ve |
| 21043 |
.RE |
| 21044 |
.RS 4 |
| 21045 |
.RE |
| 21046 |
.ie n .IP """my_strnlen""" 4 |
| 21047 |
.el .IP \f(CWmy_strnlen\fR 4 |
| 21048 |
.IX Xref "my_strnlen" |
| 21049 |
.IX Item "my_strnlen" |
| 21050 |
The C library \f(CW\*(C`strnlen\*(C'\fR if available, or a Perl implementation of it. |
| 21051 |
.Sp |
| 21052 |
\&\f(CWmy_strnlen()\fR computes the length of the string, up to \f(CW\*(C`maxlen\*(C'\fR |
| 21053 |
bytes. It will never attempt to address more than \f(CW\*(C`maxlen\*(C'\fR |
| 21054 |
bytes, making it suitable for use with strings that are not |
| 21055 |
guaranteed to be NUL-terminated. |
| 21056 |
.RS 4 |
| 21057 |
.Sp |
| 21058 |
.Vb 1 |
| 21059 |
\& Size_t my_strnlen(const char *str, Size_t maxlen) |
| 21060 |
.Ve |
| 21061 |
.RE |
| 21062 |
.RS 4 |
| 21063 |
.RE |
| 21064 |
.ie n .IP """my_vsnprintf""" 4 |
| 21065 |
.el .IP \f(CWmy_vsnprintf\fR 4 |
| 21066 |
.IX Xref "my_vsnprintf" |
| 21067 |
.IX Item "my_vsnprintf" |
| 21068 |
The C library \f(CW\*(C`vsnprintf\*(C'\fR if available and standards-compliant. |
| 21069 |
However, if the \f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately |
| 21070 |
use the unsafe \f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an |
| 21071 |
overrun check, but that may be too late). Consider using |
| 21072 |
\&\f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or getting \f(CW\*(C`vsnprintf\*(C'\fR. |
| 21073 |
.RS 4 |
| 21074 |
.Sp |
| 21075 |
.Vb 2 |
| 21076 |
\& int my_vsnprintf(char *buffer, const Size_t len, |
| 21077 |
\& const char *format, va_list ap) |
| 21078 |
.Ve |
| 21079 |
.RE |
| 21080 |
.RS 4 |
| 21081 |
.RE |
| 21082 |
.ie n .IP """NewCopy""" 4 |
| 21083 |
.el .IP \f(CWNewCopy\fR 4 |
| 21084 |
.IX Xref "NewCopy" |
| 21085 |
.IX Item "NewCopy" |
| 21086 |
Combines \fBNewx()\fR and \fBCopy()\fR into a single macro. Dest will be allocated |
| 21087 |
using \fBNewx()\fR and then src will be copied into it. |
| 21088 |
.RS 4 |
| 21089 |
.Sp |
| 21090 |
.Vb 1 |
| 21091 |
\& void NewCopy(void* src, void* dest, int nitems, type) |
| 21092 |
.Ve |
| 21093 |
.RE |
| 21094 |
.RS 4 |
| 21095 |
.RE |
| 21096 |
.ie n .IP """ninstr""" 4 |
| 21097 |
.el .IP \f(CWninstr\fR 4 |
| 21098 |
.IX Xref "ninstr" |
| 21099 |
.IX Item "ninstr" |
| 21100 |
Find the first (leftmost) occurrence of a sequence of bytes within another |
| 21101 |
sequence. This is the Perl version of \f(CWstrstr()\fR, extended to handle |
| 21102 |
arbitrary sequences, potentially containing embedded \f(CW\*(C`NUL\*(C'\fR characters (\f(CW\*(C`NUL\*(C'\fR |
| 21103 |
is what the initial \f(CW\*(C`n\*(C'\fR in the function name stands for; some systems have an |
| 21104 |
equivalent, \f(CWmemmem()\fR, but with a somewhat different API). |
| 21105 |
.Sp |
| 21106 |
Another way of thinking about this function is finding a needle in a haystack. |
| 21107 |
\&\f(CW\*(C`big\*(C'\fR points to the first byte in the haystack. \f(CW\*(C`big_end\*(C'\fR points to one byte |
| 21108 |
beyond the final byte in the haystack. \f(CW\*(C`little\*(C'\fR points to the first byte in |
| 21109 |
the needle. \f(CW\*(C`little_end\*(C'\fR points to one byte beyond the final byte in the |
| 21110 |
needle. All the parameters must be non\-\f(CW\*(C`NULL\*(C'\fR. |
| 21111 |
.Sp |
| 21112 |
The function returns \f(CW\*(C`NULL\*(C'\fR if there is no occurrence of \f(CW\*(C`little\*(C'\fR within |
| 21113 |
\&\f(CW\*(C`big\*(C'\fR. If \f(CW\*(C`little\*(C'\fR is the empty string, \f(CW\*(C`big\*(C'\fR is returned. |
| 21114 |
.Sp |
| 21115 |
Because this function operates at the byte level, and because of the inherent |
| 21116 |
characteristics of UTF\-8 (or UTF-EBCDIC), it will work properly if both the |
| 21117 |
needle and the haystack are strings with the same UTF\-8ness, but not if the |
| 21118 |
UTF\-8ness differs. |
| 21119 |
.RS 4 |
| 21120 |
.Sp |
| 21121 |
.Vb 2 |
| 21122 |
\& char * ninstr(const char *big, const char *bigend, |
| 21123 |
\& const char *little, const char *lend) |
| 21124 |
.Ve |
| 21125 |
.RE |
| 21126 |
.RS 4 |
| 21127 |
.RE |
| 21128 |
.ie n .IP """Nullch""" 4 |
| 21129 |
.el .IP \f(CWNullch\fR 4 |
| 21130 |
.IX Xref "Nullch" |
| 21131 |
.IX Item "Nullch" |
| 21132 |
Null character pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is |
| 21133 |
defined.) |
| 21134 |
.ie n .IP """PL_na""" 4 |
| 21135 |
.el .IP \f(CWPL_na\fR 4 |
| 21136 |
.IX Xref "PL_na" |
| 21137 |
.IX Item "PL_na" |
| 21138 |
A scratch pad variable in which to store a \f(CW\*(C`STRLEN\*(C'\fR value. If would have been |
| 21139 |
better named something like \f(CW\*(C`PL_temp_strlen\*(C'\fR. |
| 21140 |
.Sp |
| 21141 |
It is is typically used with \f(CW\*(C`SvPV\*(C'\fR when one is actually planning to discard |
| 21142 |
the returned length, (hence the length is "Not Applicable", which is how this |
| 21143 |
variable got its name). |
| 21144 |
.Sp |
| 21145 |
\&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it |
| 21146 |
is in a call stack with something else that is using it, this variable would |
| 21147 |
get zapped, leading to hard-to-diagnose errors. |
| 21148 |
.Sp |
| 21149 |
It is usually more efficient to either declare a local variable and use that |
| 21150 |
instead, or to use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro. |
| 21151 |
.RS 4 |
| 21152 |
.Sp |
| 21153 |
.Vb 1 |
| 21154 |
\& STRLEN PL_na |
| 21155 |
.Ve |
| 21156 |
.RE |
| 21157 |
.RS 4 |
| 21158 |
.RE |
| 21159 |
.ie n .IP """rninstr""" 4 |
| 21160 |
.el .IP \f(CWrninstr\fR 4 |
| 21161 |
.IX Xref "rninstr" |
| 21162 |
.IX Item "rninstr" |
| 21163 |
Like \f(CW"ninstr"\fR, but instead finds the final (rightmost) occurrence of a |
| 21164 |
sequence of bytes within another sequence, returning \f(CW\*(C`NULL\*(C'\fR if there is no |
| 21165 |
such occurrence. |
| 21166 |
.RS 4 |
| 21167 |
.Sp |
| 21168 |
.Vb 2 |
| 21169 |
\& char * rninstr(const char *big, const char *bigend, |
| 21170 |
\& const char *little, const char *lend) |
| 21171 |
.Ve |
| 21172 |
.RE |
| 21173 |
.RS 4 |
| 21174 |
.RE |
| 21175 |
.ie n .IP """savepv""" 4 |
| 21176 |
.el .IP \f(CWsavepv\fR 4 |
| 21177 |
.IX Xref "savepv" |
| 21178 |
.IX Item "savepv" |
| 21179 |
Perl's version of \f(CWstrdup()\fR. Returns a pointer to a newly allocated |
| 21180 |
string which is a duplicate of \f(CW\*(C`pv\*(C'\fR. The size of the string is |
| 21181 |
determined by \f(CWstrlen()\fR, which means it may not contain embedded \f(CW\*(C`NUL\*(C'\fR |
| 21182 |
characters and must have a trailing \f(CW\*(C`NUL\*(C'\fR. To prevent memory leaks, the |
| 21183 |
memory allocated for the new string needs to be freed when no longer needed. |
| 21184 |
This can be done with the \f(CW"Safefree"\fR function, or |
| 21185 |
\&\f(CW\*(C`SAVEFREEPV\*(C'\fR. |
| 21186 |
.Sp |
| 21187 |
On some platforms, Windows for example, all allocated memory owned by a thread |
| 21188 |
is deallocated when that thread ends. So if you need that not to happen, you |
| 21189 |
need to use the shared memory functions, such as \f(CW"savesharedpv"\fR. |
| 21190 |
.RS 4 |
| 21191 |
.Sp |
| 21192 |
.Vb 1 |
| 21193 |
\& char * savepv(const char *pv) |
| 21194 |
.Ve |
| 21195 |
.RE |
| 21196 |
.RS 4 |
| 21197 |
.RE |
| 21198 |
.ie n .IP """savepvn""" 4 |
| 21199 |
.el .IP \f(CWsavepvn\fR 4 |
| 21200 |
.IX Xref "savepvn" |
| 21201 |
.IX Item "savepvn" |
| 21202 |
Perl's version of what \f(CWstrndup()\fR would be if it existed. Returns a |
| 21203 |
pointer to a newly allocated string which is a duplicate of the first |
| 21204 |
\&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR, plus a trailing |
| 21205 |
\&\f(CW\*(C`NUL\*(C'\fR byte. The memory allocated for |
| 21206 |
the new string can be freed with the \f(CWSafefree()\fR function. |
| 21207 |
.Sp |
| 21208 |
On some platforms, Windows for example, all allocated memory owned by a thread |
| 21209 |
is deallocated when that thread ends. So if you need that not to happen, you |
| 21210 |
need to use the shared memory functions, such as \f(CW"savesharedpvn"\fR. |
| 21211 |
.RS 4 |
| 21212 |
.Sp |
| 21213 |
.Vb 1 |
| 21214 |
\& char * savepvn(const char *pv, Size_t len) |
| 21215 |
.Ve |
| 21216 |
.RE |
| 21217 |
.RS 4 |
| 21218 |
.RE |
| 21219 |
.ie n .IP """savepvs""" 4 |
| 21220 |
.el .IP \f(CWsavepvs\fR 4 |
| 21221 |
.IX Xref "savepvs" |
| 21222 |
.IX Item "savepvs" |
| 21223 |
Like \f(CW\*(C`savepvn\*(C'\fR, but takes a literal string instead of a |
| 21224 |
string/length pair. |
| 21225 |
.RS 4 |
| 21226 |
.Sp |
| 21227 |
.Vb 1 |
| 21228 |
\& char* savepvs("literal string") |
| 21229 |
.Ve |
| 21230 |
.RE |
| 21231 |
.RS 4 |
| 21232 |
.RE |
| 21233 |
.ie n .IP """savesharedpv""" 4 |
| 21234 |
.el .IP \f(CWsavesharedpv\fR 4 |
| 21235 |
.IX Xref "savesharedpv" |
| 21236 |
.IX Item "savesharedpv" |
| 21237 |
A version of \f(CWsavepv()\fR which allocates the duplicate string in memory |
| 21238 |
which is shared between threads. |
| 21239 |
.RS 4 |
| 21240 |
.Sp |
| 21241 |
.Vb 1 |
| 21242 |
\& char * savesharedpv(const char *pv) |
| 21243 |
.Ve |
| 21244 |
.RE |
| 21245 |
.RS 4 |
| 21246 |
.RE |
| 21247 |
.ie n .IP """savesharedpvn""" 4 |
| 21248 |
.el .IP \f(CWsavesharedpvn\fR 4 |
| 21249 |
.IX Xref "savesharedpvn" |
| 21250 |
.IX Item "savesharedpvn" |
| 21251 |
A version of \f(CWsavepvn()\fR which allocates the duplicate string in memory |
| 21252 |
which is shared between threads. (With the specific difference that a \f(CW\*(C`NULL\*(C'\fR |
| 21253 |
pointer is not acceptable) |
| 21254 |
.RS 4 |
| 21255 |
.Sp |
| 21256 |
.Vb 1 |
| 21257 |
\& char * savesharedpvn(const char * const pv, const STRLEN len) |
| 21258 |
.Ve |
| 21259 |
.RE |
| 21260 |
.RS 4 |
| 21261 |
.RE |
| 21262 |
.ie n .IP """savesharedpvs""" 4 |
| 21263 |
.el .IP \f(CWsavesharedpvs\fR 4 |
| 21264 |
.IX Xref "savesharedpvs" |
| 21265 |
.IX Item "savesharedpvs" |
| 21266 |
A version of \f(CWsavepvs()\fR which allocates the duplicate string in memory |
| 21267 |
which is shared between threads. |
| 21268 |
.RS 4 |
| 21269 |
.Sp |
| 21270 |
.Vb 1 |
| 21271 |
\& char* savesharedpvs("literal string") |
| 21272 |
.Ve |
| 21273 |
.RE |
| 21274 |
.RS 4 |
| 21275 |
.RE |
| 21276 |
.ie n .IP """savesharedsvpv""" 4 |
| 21277 |
.el .IP \f(CWsavesharedsvpv\fR 4 |
| 21278 |
.IX Xref "savesharedsvpv" |
| 21279 |
.IX Item "savesharedsvpv" |
| 21280 |
A version of \f(CWsavesharedpv()\fR which allocates the duplicate string in |
| 21281 |
memory which is shared between threads. |
| 21282 |
.RS 4 |
| 21283 |
.Sp |
| 21284 |
.Vb 1 |
| 21285 |
\& char * savesharedsvpv(SV *sv) |
| 21286 |
.Ve |
| 21287 |
.RE |
| 21288 |
.RS 4 |
| 21289 |
.RE |
| 21290 |
.ie n .IP """savesvpv""" 4 |
| 21291 |
.el .IP \f(CWsavesvpv\fR 4 |
| 21292 |
.IX Xref "savesvpv" |
| 21293 |
.IX Item "savesvpv" |
| 21294 |
A version of \f(CWsavepv()\fR/\f(CWsavepvn()\fR which gets the string to duplicate from |
| 21295 |
the passed in SV using \f(CWSvPV()\fR |
| 21296 |
.Sp |
| 21297 |
On some platforms, Windows for example, all allocated memory owned by a thread |
| 21298 |
is deallocated when that thread ends. So if you need that not to happen, you |
| 21299 |
need to use the shared memory functions, such as \f(CW"savesharedsvpv"\fR. |
| 21300 |
.RS 4 |
| 21301 |
.Sp |
| 21302 |
.Vb 1 |
| 21303 |
\& char * savesvpv(SV *sv) |
| 21304 |
.Ve |
| 21305 |
.RE |
| 21306 |
.RS 4 |
| 21307 |
.RE |
| 21308 |
.ie n .IP """strEQ""" 4 |
| 21309 |
.el .IP \f(CWstrEQ\fR 4 |
| 21310 |
.IX Xref "strEQ" |
| 21311 |
.IX Item "strEQ" |
| 21312 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. Returns true or |
| 21313 |
false. |
| 21314 |
.RS 4 |
| 21315 |
.Sp |
| 21316 |
.Vb 1 |
| 21317 |
\& bool strEQ(char* s1, char* s2) |
| 21318 |
.Ve |
| 21319 |
.RE |
| 21320 |
.RS 4 |
| 21321 |
.RE |
| 21322 |
.ie n .IP """strGE""" 4 |
| 21323 |
.el .IP \f(CWstrGE\fR 4 |
| 21324 |
.IX Xref "strGE" |
| 21325 |
.IX Item "strGE" |
| 21326 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than |
| 21327 |
or equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. |
| 21328 |
.RS 4 |
| 21329 |
.Sp |
| 21330 |
.Vb 1 |
| 21331 |
\& bool strGE(char* s1, char* s2) |
| 21332 |
.Ve |
| 21333 |
.RE |
| 21334 |
.RS 4 |
| 21335 |
.RE |
| 21336 |
.ie n .IP """strGT""" 4 |
| 21337 |
.el .IP \f(CWstrGT\fR 4 |
| 21338 |
.IX Xref "strGT" |
| 21339 |
.IX Item "strGT" |
| 21340 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than |
| 21341 |
the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. |
| 21342 |
.RS 4 |
| 21343 |
.Sp |
| 21344 |
.Vb 1 |
| 21345 |
\& bool strGT(char* s1, char* s2) |
| 21346 |
.Ve |
| 21347 |
.RE |
| 21348 |
.RS 4 |
| 21349 |
.RE |
| 21350 |
.ie n .IP """STRINGIFY""" 4 |
| 21351 |
.el .IP \f(CWSTRINGIFY\fR 4 |
| 21352 |
.IX Xref "STRINGIFY" |
| 21353 |
.IX Item "STRINGIFY" |
| 21354 |
This macro surrounds its token with double quotes. |
| 21355 |
.RS 4 |
| 21356 |
.Sp |
| 21357 |
.Vb 1 |
| 21358 |
\& string STRINGIFY(token x) |
| 21359 |
.Ve |
| 21360 |
.RE |
| 21361 |
.RS 4 |
| 21362 |
.RE |
| 21363 |
.ie n .IP """strLE""" 4 |
| 21364 |
.el .IP \f(CWstrLE\fR 4 |
| 21365 |
.IX Xref "strLE" |
| 21366 |
.IX Item "strLE" |
| 21367 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than or |
| 21368 |
equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. |
| 21369 |
.RS 4 |
| 21370 |
.Sp |
| 21371 |
.Vb 1 |
| 21372 |
\& bool strLE(char* s1, char* s2) |
| 21373 |
.Ve |
| 21374 |
.RE |
| 21375 |
.RS 4 |
| 21376 |
.RE |
| 21377 |
.ie n .IP """STRLEN""" 4 |
| 21378 |
.el .IP \f(CWSTRLEN\fR 4 |
| 21379 |
.IX Item "STRLEN" |
| 21380 |
Described in perlguts. |
| 21381 |
.ie n .IP """strLT""" 4 |
| 21382 |
.el .IP \f(CWstrLT\fR 4 |
| 21383 |
.IX Xref "strLT" |
| 21384 |
.IX Item "strLT" |
| 21385 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than the |
| 21386 |
second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. |
| 21387 |
.RS 4 |
| 21388 |
.Sp |
| 21389 |
.Vb 1 |
| 21390 |
\& bool strLT(char* s1, char* s2) |
| 21391 |
.Ve |
| 21392 |
.RE |
| 21393 |
.RS 4 |
| 21394 |
.RE |
| 21395 |
.ie n .IP """strNE""" 4 |
| 21396 |
.el .IP \f(CWstrNE\fR 4 |
| 21397 |
.IX Xref "strNE" |
| 21398 |
.IX Item "strNE" |
| 21399 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. Returns true |
| 21400 |
or false. |
| 21401 |
.RS 4 |
| 21402 |
.Sp |
| 21403 |
.Vb 1 |
| 21404 |
\& bool strNE(char* s1, char* s2) |
| 21405 |
.Ve |
| 21406 |
.RE |
| 21407 |
.RS 4 |
| 21408 |
.RE |
| 21409 |
.ie n .IP """strnEQ""" 4 |
| 21410 |
.el .IP \f(CWstrnEQ\fR 4 |
| 21411 |
.IX Xref "strnEQ" |
| 21412 |
.IX Item "strnEQ" |
| 21413 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. The \f(CW\*(C`len\*(C'\fR |
| 21414 |
parameter indicates the number of bytes to compare. Returns true or false. (A |
| 21415 |
wrapper for \f(CW\*(C`strncmp\*(C'\fR). |
| 21416 |
.RS 4 |
| 21417 |
.Sp |
| 21418 |
.Vb 1 |
| 21419 |
\& bool strnEQ(char* s1, char* s2, STRLEN len) |
| 21420 |
.Ve |
| 21421 |
.RE |
| 21422 |
.RS 4 |
| 21423 |
.RE |
| 21424 |
.ie n .IP """strnNE""" 4 |
| 21425 |
.el .IP \f(CWstrnNE\fR 4 |
| 21426 |
.IX Xref "strnNE" |
| 21427 |
.IX Item "strnNE" |
| 21428 |
Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. The \f(CW\*(C`len\*(C'\fR |
| 21429 |
parameter indicates the number of bytes to compare. Returns true or false. (A |
| 21430 |
wrapper for \f(CW\*(C`strncmp\*(C'\fR). |
| 21431 |
.RS 4 |
| 21432 |
.Sp |
| 21433 |
.Vb 1 |
| 21434 |
\& bool strnNE(char* s1, char* s2, STRLEN len) |
| 21435 |
.Ve |
| 21436 |
.RE |
| 21437 |
.RS 4 |
| 21438 |
.RE |
| 21439 |
.ie n .IP """STR_WITH_LEN""" 4 |
| 21440 |
.el .IP \f(CWSTR_WITH_LEN\fR 4 |
| 21441 |
.IX Xref "STR_WITH_LEN" |
| 21442 |
.IX Item "STR_WITH_LEN" |
| 21443 |
Returns two comma separated tokens of the input literal string, and its length. |
| 21444 |
This is convenience macro which helps out in some API calls. |
| 21445 |
Note that it can't be used as an argument to macros or functions that under |
| 21446 |
some configurations might be macros, which means that it requires the full |
| 21447 |
Perl_xxx(aTHX_ ...) form for any API calls where it's used. |
| 21448 |
.RS 4 |
| 21449 |
.Sp |
| 21450 |
.Vb 1 |
| 21451 |
\& pair STR_WITH_LEN("literal string") |
| 21452 |
.Ve |
| 21453 |
.RE |
| 21454 |
.RS 4 |
| 21455 |
.RE |
| 21456 |
.ie n .IP """Zero""" 4 |
| 21457 |
.el .IP \f(CWZero\fR 4 |
| 21458 |
.IX Item "Zero" |
| 21459 |
.PD 0 |
| 21460 |
.ie n .IP """ZeroD""" 4 |
| 21461 |
.el .IP \f(CWZeroD\fR 4 |
| 21462 |
.IX Xref "Zero ZeroD" |
| 21463 |
.IX Item "ZeroD" |
| 21464 |
.PD |
| 21465 |
The XSUB-writer's interface to the C \f(CW\*(C`memzero\*(C'\fR function. The \f(CW\*(C`dest\*(C'\fR is the |
| 21466 |
destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type. |
| 21467 |
.Sp |
| 21468 |
\&\f(CW\*(C`ZeroD\*(C'\fR is like \f(CW\*(C`Zero\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful |
| 21469 |
for encouraging compilers to tail-call |
| 21470 |
optimise. |
| 21471 |
.RS 4 |
| 21472 |
.Sp |
| 21473 |
.Vb 2 |
| 21474 |
\& void Zero (void* dest, int nitems, type) |
| 21475 |
\& void * ZeroD(void* dest, int nitems, type) |
| 21476 |
.Ve |
| 21477 |
.RE |
| 21478 |
.RS 4 |
| 21479 |
.RE |
| 21480 |
.SH "SV Flags" |
| 21481 |
.IX Header "SV Flags" |
| 21482 |
.ie n .IP """SVt_IV""" 4 |
| 21483 |
.el .IP \f(CWSVt_IV\fR 4 |
| 21484 |
.IX Xref "SVt_IV" |
| 21485 |
.IX Item "SVt_IV" |
| 21486 |
Type flag for scalars. See "svtype". |
| 21487 |
.ie n .IP """SVt_NULL""" 4 |
| 21488 |
.el .IP \f(CWSVt_NULL\fR 4 |
| 21489 |
.IX Xref "SVt_NULL" |
| 21490 |
.IX Item "SVt_NULL" |
| 21491 |
Type flag for scalars. See "svtype". |
| 21492 |
.ie n .IP """SVt_NV""" 4 |
| 21493 |
.el .IP \f(CWSVt_NV\fR 4 |
| 21494 |
.IX Xref "SVt_NV" |
| 21495 |
.IX Item "SVt_NV" |
| 21496 |
Type flag for scalars. See "svtype". |
| 21497 |
.ie n .IP """SVt_PV""" 4 |
| 21498 |
.el .IP \f(CWSVt_PV\fR 4 |
| 21499 |
.IX Xref "SVt_PV" |
| 21500 |
.IX Item "SVt_PV" |
| 21501 |
Type flag for scalars. See "svtype". |
| 21502 |
.ie n .IP """SVt_PVAV""" 4 |
| 21503 |
.el .IP \f(CWSVt_PVAV\fR 4 |
| 21504 |
.IX Xref "SVt_PVAV" |
| 21505 |
.IX Item "SVt_PVAV" |
| 21506 |
Type flag for arrays. See "svtype". |
| 21507 |
.ie n .IP """SVt_PVCV""" 4 |
| 21508 |
.el .IP \f(CWSVt_PVCV\fR 4 |
| 21509 |
.IX Xref "SVt_PVCV" |
| 21510 |
.IX Item "SVt_PVCV" |
| 21511 |
Type flag for subroutines. See "svtype". |
| 21512 |
.ie n .IP """SVt_PVFM""" 4 |
| 21513 |
.el .IP \f(CWSVt_PVFM\fR 4 |
| 21514 |
.IX Xref "SVt_PVFM" |
| 21515 |
.IX Item "SVt_PVFM" |
| 21516 |
Type flag for formats. See "svtype". |
| 21517 |
.ie n .IP """SVt_PVGV""" 4 |
| 21518 |
.el .IP \f(CWSVt_PVGV\fR 4 |
| 21519 |
.IX Xref "SVt_PVGV" |
| 21520 |
.IX Item "SVt_PVGV" |
| 21521 |
Type flag for typeglobs. See "svtype". |
| 21522 |
.ie n .IP """SVt_PVHV""" 4 |
| 21523 |
.el .IP \f(CWSVt_PVHV\fR 4 |
| 21524 |
.IX Xref "SVt_PVHV" |
| 21525 |
.IX Item "SVt_PVHV" |
| 21526 |
Type flag for hashes. See "svtype". |
| 21527 |
.ie n .IP """SVt_PVIO""" 4 |
| 21528 |
.el .IP \f(CWSVt_PVIO\fR 4 |
| 21529 |
.IX Xref "SVt_PVIO" |
| 21530 |
.IX Item "SVt_PVIO" |
| 21531 |
Type flag for I/O objects. See "svtype". |
| 21532 |
.ie n .IP """SVt_PVIV""" 4 |
| 21533 |
.el .IP \f(CWSVt_PVIV\fR 4 |
| 21534 |
.IX Xref "SVt_PVIV" |
| 21535 |
.IX Item "SVt_PVIV" |
| 21536 |
Type flag for scalars. See "svtype". |
| 21537 |
.ie n .IP """SVt_PVLV""" 4 |
| 21538 |
.el .IP \f(CWSVt_PVLV\fR 4 |
| 21539 |
.IX Xref "SVt_PVLV" |
| 21540 |
.IX Item "SVt_PVLV" |
| 21541 |
Type flag for scalars. See "svtype". |
| 21542 |
.ie n .IP """SVt_PVMG""" 4 |
| 21543 |
.el .IP \f(CWSVt_PVMG\fR 4 |
| 21544 |
.IX Xref "SVt_PVMG" |
| 21545 |
.IX Item "SVt_PVMG" |
| 21546 |
Type flag for scalars. See "svtype". |
| 21547 |
.ie n .IP """SVt_PVNV""" 4 |
| 21548 |
.el .IP \f(CWSVt_PVNV\fR 4 |
| 21549 |
.IX Xref "SVt_PVNV" |
| 21550 |
.IX Item "SVt_PVNV" |
| 21551 |
Type flag for scalars. See "svtype". |
| 21552 |
.ie n .IP """SVt_PVOBJ""" 4 |
| 21553 |
.el .IP \f(CWSVt_PVOBJ\fR 4 |
| 21554 |
.IX Xref "SVt_PVOBJ" |
| 21555 |
.IX Item "SVt_PVOBJ" |
| 21556 |
NOTE: \f(CW\*(C`SVt_PVOBJ\*(C'\fR is \fBexperimental\fR and may change or be |
| 21557 |
removed without notice. |
| 21558 |
.Sp |
| 21559 |
Type flag for object instances. See "svtype". |
| 21560 |
.ie n .IP """SVt_REGEXP""" 4 |
| 21561 |
.el .IP \f(CWSVt_REGEXP\fR 4 |
| 21562 |
.IX Xref "SVt_REGEXP" |
| 21563 |
.IX Item "SVt_REGEXP" |
| 21564 |
Type flag for regular expressions. See "svtype". |
| 21565 |
.ie n .IP """svtype""" 4 |
| 21566 |
.el .IP \f(CWsvtype\fR 4 |
| 21567 |
.IX Xref "svtype" |
| 21568 |
.IX Item "svtype" |
| 21569 |
An enum of flags for Perl types. These are found in the file \fIsv.h\fR |
| 21570 |
in the \f(CW\*(C`svtype\*(C'\fR enum. Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro. |
| 21571 |
.Sp |
| 21572 |
The types are: |
| 21573 |
.Sp |
| 21574 |
.Vb 10 |
| 21575 |
\& SVt_NULL |
| 21576 |
\& SVt_IV |
| 21577 |
\& SVt_NV |
| 21578 |
\& SVt_RV |
| 21579 |
\& SVt_PV |
| 21580 |
\& SVt_PVIV |
| 21581 |
\& SVt_PVNV |
| 21582 |
\& SVt_PVMG |
| 21583 |
\& SVt_INVLIST |
| 21584 |
\& SVt_REGEXP |
| 21585 |
\& SVt_PVGV |
| 21586 |
\& SVt_PVLV |
| 21587 |
\& SVt_PVAV |
| 21588 |
\& SVt_PVHV |
| 21589 |
\& SVt_PVCV |
| 21590 |
\& SVt_PVFM |
| 21591 |
\& SVt_PVIO |
| 21592 |
\& SVt_PVOBJ |
| 21593 |
.Ve |
| 21594 |
.Sp |
| 21595 |
These are most easily explained from the bottom up. |
| 21596 |
.Sp |
| 21597 |
\&\f(CW\*(C`SVt_PVOBJ\*(C'\fR is for object instances of the new `use feature 'class'` kind. |
| 21598 |
\&\f(CW\*(C`SVt_PVIO\*(C'\fR is for I/O objects, \f(CW\*(C`SVt_PVFM\*(C'\fR for formats, \f(CW\*(C`SVt_PVCV\*(C'\fR for |
| 21599 |
subroutines, \f(CW\*(C`SVt_PVHV\*(C'\fR for hashes and \f(CW\*(C`SVt_PVAV\*(C'\fR for arrays. |
| 21600 |
.Sp |
| 21601 |
All the others are scalar types, that is, things that can be bound to a |
| 21602 |
\&\f(CW\*(C`$\*(C'\fR variable. For these, the internal types are mostly orthogonal to |
| 21603 |
types in the Perl language. |
| 21604 |
.Sp |
| 21605 |
Hence, checking \f(CW\*(C`SvTYPE(sv) < SVt_PVAV\*(C'\fR is the best way to see whether |
| 21606 |
something is a scalar. |
| 21607 |
.Sp |
| 21608 |
\&\f(CW\*(C`SVt_PVGV\*(C'\fR represents a typeglob. If \f(CW\*(C`!SvFAKE(sv)\*(C'\fR, then it is a real, |
| 21609 |
incoercible typeglob. If \f(CWSvFAKE(sv)\fR, then it is a scalar to which a |
| 21610 |
typeglob has been assigned. Assigning to it again will stop it from being |
| 21611 |
a typeglob. \f(CW\*(C`SVt_PVLV\*(C'\fR represents a scalar that delegates to another scalar |
| 21612 |
behind the scenes. It is used, e.g., for the return value of \f(CW\*(C`substr\*(C'\fR and |
| 21613 |
for tied hash and array elements. It can hold any scalar value, including |
| 21614 |
a typeglob. \f(CW\*(C`SVt_REGEXP\*(C'\fR is for regular |
| 21615 |
expressions. \f(CW\*(C`SVt_INVLIST\*(C'\fR is for Perl |
| 21616 |
core internal use only. |
| 21617 |
.Sp |
| 21618 |
\&\f(CW\*(C`SVt_PVMG\*(C'\fR represents a "normal" scalar (not a typeglob, regular expression, |
| 21619 |
or delegate). Since most scalars do not need all the internal fields of a |
| 21620 |
PVMG, we save memory by allocating smaller structs when possible. All the |
| 21621 |
other types are just simpler forms of \f(CW\*(C`SVt_PVMG\*(C'\fR, with fewer internal fields. |
| 21622 |
\&\f(CW\*(C`SVt_NULL\*(C'\fR can only hold undef. \f(CW\*(C`SVt_IV\*(C'\fR can hold undef, an integer, or a |
| 21623 |
reference. (\f(CW\*(C`SVt_RV\*(C'\fR is an alias for \f(CW\*(C`SVt_IV\*(C'\fR, which exists for backward |
| 21624 |
compatibility.) \f(CW\*(C`SVt_NV\*(C'\fR can hold undef or a double. (In builds that support |
| 21625 |
headless NVs, these could also hold a reference via a suitable offset, in the |
| 21626 |
same way that SVt_IV does, but this is not currently supported and seems to |
| 21627 |
be a rare use case.) \f(CW\*(C`SVt_PV\*(C'\fR can hold \f(CW\*(C`undef\*(C'\fR, a string, or a reference. |
| 21628 |
\&\f(CW\*(C`SVt_PVIV\*(C'\fR is a superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_IV\*(C'\fR. \f(CW\*(C`SVt_PVNV\*(C'\fR is a |
| 21629 |
superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_NV\*(C'\fR. \f(CW\*(C`SVt_PVMG\*(C'\fR can hold anything \f(CW\*(C`SVt_PVNV\*(C'\fR |
| 21630 |
can hold, but it may also be blessed or magical. |
| 21631 |
.SH "SV Handling" |
| 21632 |
.IX Xref "SV_CATBYTES SV_CATUTF8 SV_COW_DROP_PV SV_FORCE_UTF8_UPGRADE SV_GMAGIC SV_HAS_TRAILING_NUL SV_IMMEDIATE_UNREF SV_NOSTEAL SV_SMAGIC SV_UTF8_NO_ENCODING SVs_TEMP" |
| 21633 |
.IX Header "SV Handling" |
| 21634 |
.ie n .IP """AV_FROM_REF""" 4 |
| 21635 |
.el .IP \f(CWAV_FROM_REF\fR 4 |
| 21636 |
.IX Item "AV_FROM_REF" |
| 21637 |
.PD 0 |
| 21638 |
.ie n .IP """CV_FROM_REF""" 4 |
| 21639 |
.el .IP \f(CWCV_FROM_REF\fR 4 |
| 21640 |
.IX Item "CV_FROM_REF" |
| 21641 |
.ie n .IP """HV_FROM_REF""" 4 |
| 21642 |
.el .IP \f(CWHV_FROM_REF\fR 4 |
| 21643 |
.IX Xref "AV_FROM_REF CV_FROM_REF HV_FROM_REF" |
| 21644 |
.IX Item "HV_FROM_REF" |
| 21645 |
.PD |
| 21646 |
The \f(CW\*(C`\fR\f(CI*\fR\f(CWV_FROM_REF\*(C'\fR macros extract the \f(CWSvRV()\fR from a given reference SV |
| 21647 |
and return a suitably-cast to pointer to the referenced SV. When running |
| 21648 |
under \f(CW\*(C`\-DDEBUGGING\*(C'\fR, assertions are also applied that check that \fIref\fR is |
| 21649 |
definitely a reference SV that refers to an SV of the right type. |
| 21650 |
.RS 4 |
| 21651 |
.Sp |
| 21652 |
.Vb 3 |
| 21653 |
\& AV * AV_FROM_REF(SV * ref) |
| 21654 |
\& CV * CV_FROM_REF(SV * ref) |
| 21655 |
\& HV * HV_FROM_REF(SV * ref) |
| 21656 |
.Ve |
| 21657 |
.RE |
| 21658 |
.RS 4 |
| 21659 |
.RE |
| 21660 |
.ie n .IP """BOOL_INTERNALS_sv_isbool""" 4 |
| 21661 |
.el .IP \f(CWBOOL_INTERNALS_sv_isbool\fR 4 |
| 21662 |
.IX Xref "BOOL_INTERNALS_sv_isbool" |
| 21663 |
.IX Item "BOOL_INTERNALS_sv_isbool" |
| 21664 |
Checks if a \f(CWSvBoolFlagsOK()\fR sv is a bool. \fBNote\fR that it is the |
| 21665 |
caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR before |
| 21666 |
calling this. This is only useful in specialized logic like |
| 21667 |
serialization code where performance is critical and the flags have |
| 21668 |
already been checked to be correct. Almost always you should be using |
| 21669 |
\&\f(CWsv_isbool(sv)\fR instead. |
| 21670 |
.RS 4 |
| 21671 |
.Sp |
| 21672 |
.Vb 1 |
| 21673 |
\& bool BOOL_INTERNALS_sv_isbool(SV* sv) |
| 21674 |
.Ve |
| 21675 |
.RE |
| 21676 |
.RS 4 |
| 21677 |
.RE |
| 21678 |
.ie n .IP """BOOL_INTERNALS_sv_isbool_false""" 4 |
| 21679 |
.el .IP \f(CWBOOL_INTERNALS_sv_isbool_false\fR 4 |
| 21680 |
.IX Xref "BOOL_INTERNALS_sv_isbool_false" |
| 21681 |
.IX Item "BOOL_INTERNALS_sv_isbool_false" |
| 21682 |
Checks if a \f(CWSvBoolFlagsOK()\fR sv is a false bool. \fBNote\fR that it is |
| 21683 |
the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR |
| 21684 |
before calling this. This is only useful in specialized logic like |
| 21685 |
serialization code where performance is critical and the flags have |
| 21686 |
already been checked to be correct. This is \fBNOT\fR what you should use |
| 21687 |
to check if an SV is "false", for that you should be using |
| 21688 |
\&\f(CW\*(C`!SvTRUE(sv)\*(C'\fR instead. |
| 21689 |
.RS 4 |
| 21690 |
.Sp |
| 21691 |
.Vb 1 |
| 21692 |
\& bool BOOL_INTERNALS_sv_isbool_false(SV* sv) |
| 21693 |
.Ve |
| 21694 |
.RE |
| 21695 |
.RS 4 |
| 21696 |
.RE |
| 21697 |
.ie n .IP """BOOL_INTERNALS_sv_isbool_true""" 4 |
| 21698 |
.el .IP \f(CWBOOL_INTERNALS_sv_isbool_true\fR 4 |
| 21699 |
.IX Xref "BOOL_INTERNALS_sv_isbool_true" |
| 21700 |
.IX Item "BOOL_INTERNALS_sv_isbool_true" |
| 21701 |
Checks if a \f(CWSvBoolFlagsOK()\fR sv is a true bool. \fBNote\fR that it is |
| 21702 |
the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR |
| 21703 |
before calling this. This is only useful in specialized logic like |
| 21704 |
serialization code where performance is critical and the flags have |
| 21705 |
already been checked to be correct. This is \fBNOT\fR what you should use |
| 21706 |
to check if an SV is "true", for that you should be using |
| 21707 |
\&\f(CWSvTRUE(sv)\fR instead. |
| 21708 |
.RS 4 |
| 21709 |
.Sp |
| 21710 |
.Vb 1 |
| 21711 |
\& bool BOOL_INTERNALS_sv_isbool_true(SV* sv) |
| 21712 |
.Ve |
| 21713 |
.RE |
| 21714 |
.RS 4 |
| 21715 |
.RE |
| 21716 |
.ie n .IP """boolSV""" 4 |
| 21717 |
.el .IP \f(CWboolSV\fR 4 |
| 21718 |
.IX Xref "boolSV" |
| 21719 |
.IX Item "boolSV" |
| 21720 |
Returns a true SV if \f(CW\*(C`b\*(C'\fR is a true value, or a false SV if \f(CW\*(C`b\*(C'\fR is 0. |
| 21721 |
.Sp |
| 21722 |
See also \f(CW"PL_sv_yes"\fR and \f(CW"PL_sv_no"\fR. |
| 21723 |
.RS 4 |
| 21724 |
.Sp |
| 21725 |
.Vb 1 |
| 21726 |
\& SV * boolSV(bool b) |
| 21727 |
.Ve |
| 21728 |
.RE |
| 21729 |
.RS 4 |
| 21730 |
.RE |
| 21731 |
.ie n .IP """croak_xs_usage""" 4 |
| 21732 |
.el .IP \f(CWcroak_xs_usage\fR 4 |
| 21733 |
.IX Xref "croak_xs_usage" |
| 21734 |
.IX Item "croak_xs_usage" |
| 21735 |
A specialised variant of \f(CWcroak()\fR for emitting the usage message for xsubs |
| 21736 |
.Sp |
| 21737 |
.Vb 1 |
| 21738 |
\& croak_xs_usage(cv, "eee_yow"); |
| 21739 |
.Ve |
| 21740 |
.Sp |
| 21741 |
works out the package name and subroutine name from \f(CW\*(C`cv\*(C'\fR, and then calls |
| 21742 |
\&\f(CWcroak()\fR. Hence if \f(CW\*(C`cv\*(C'\fR is \f(CW&ouch::awk\fR, it would call \f(CW\*(C`croak\*(C'\fR as: |
| 21743 |
.Sp |
| 21744 |
.Vb 3 |
| 21745 |
\& diag_listed_as: SKIPME |
| 21746 |
\& Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk", |
| 21747 |
\& "eee_yow"); |
| 21748 |
.Ve |
| 21749 |
.RS 4 |
| 21750 |
.Sp |
| 21751 |
.Vb 2 |
| 21752 |
\& void croak_xs_usage(const CV * const cv, |
| 21753 |
\& const char * const params) |
| 21754 |
.Ve |
| 21755 |
.RE |
| 21756 |
.RS 4 |
| 21757 |
.RE |
| 21758 |
.ie n .IP """DEFSV""" 4 |
| 21759 |
.el .IP \f(CWDEFSV\fR 4 |
| 21760 |
.IX Xref "DEFSV" |
| 21761 |
.IX Item "DEFSV" |
| 21762 |
Returns the SV associated with \f(CW$_\fR |
| 21763 |
.RS 4 |
| 21764 |
.Sp |
| 21765 |
.Vb 1 |
| 21766 |
\& SV * DEFSV |
| 21767 |
.Ve |
| 21768 |
.RE |
| 21769 |
.RS 4 |
| 21770 |
.RE |
| 21771 |
.ie n .IP """DEFSV_set""" 4 |
| 21772 |
.el .IP \f(CWDEFSV_set\fR 4 |
| 21773 |
.IX Xref "DEFSV_set" |
| 21774 |
.IX Item "DEFSV_set" |
| 21775 |
Associate \f(CW\*(C`sv\*(C'\fR with \f(CW$_\fR |
| 21776 |
.RS 4 |
| 21777 |
.Sp |
| 21778 |
.Vb 1 |
| 21779 |
\& void DEFSV_set(SV * sv) |
| 21780 |
.Ve |
| 21781 |
.RE |
| 21782 |
.RS 4 |
| 21783 |
.RE |
| 21784 |
.ie n .IP """get_sv""" 4 |
| 21785 |
.el .IP \f(CWget_sv\fR 4 |
| 21786 |
.IX Xref "get_sv" |
| 21787 |
.IX Item "get_sv" |
| 21788 |
Returns the SV of the specified Perl scalar. \f(CW\*(C`flags\*(C'\fR are passed to |
| 21789 |
"\f(CW\*(C`gv_fetchpv\*(C'\fR". If \f(CW\*(C`GV_ADD\*(C'\fR is set and the |
| 21790 |
Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero |
| 21791 |
and the variable does not exist then NULL is returned. |
| 21792 |
.Sp |
| 21793 |
NOTE: the \f(CWperl_get_sv()\fR form is \fBdeprecated\fR. |
| 21794 |
.RS 4 |
| 21795 |
.Sp |
| 21796 |
.Vb 1 |
| 21797 |
\& SV * get_sv(const char *name, I32 flags) |
| 21798 |
.Ve |
| 21799 |
.RE |
| 21800 |
.RS 4 |
| 21801 |
.RE |
| 21802 |
.ie n .IP """isGV_with_GP""" 4 |
| 21803 |
.el .IP \f(CWisGV_with_GP\fR 4 |
| 21804 |
.IX Xref "isGV_with_GP" |
| 21805 |
.IX Item "isGV_with_GP" |
| 21806 |
Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR is a GV with a pointer to a GP |
| 21807 |
(glob pointer). |
| 21808 |
.RS 4 |
| 21809 |
.Sp |
| 21810 |
.Vb 1 |
| 21811 |
\& bool isGV_with_GP(SV * sv) |
| 21812 |
.Ve |
| 21813 |
.RE |
| 21814 |
.RS 4 |
| 21815 |
.RE |
| 21816 |
.ie n .IP """looks_like_number""" 4 |
| 21817 |
.el .IP \f(CWlooks_like_number\fR 4 |
| 21818 |
.IX Xref "looks_like_number" |
| 21819 |
.IX Item "looks_like_number" |
| 21820 |
Test if the content of an SV looks like a number (or is a number). |
| 21821 |
\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a |
| 21822 |
non-numeric warning), even if your \f(CWatof()\fR doesn't grok them. Get-magic is |
| 21823 |
ignored. |
| 21824 |
.RS 4 |
| 21825 |
.Sp |
| 21826 |
.Vb 1 |
| 21827 |
\& I32 looks_like_number(SV * const sv) |
| 21828 |
.Ve |
| 21829 |
.RE |
| 21830 |
.RS 4 |
| 21831 |
.RE |
| 21832 |
.ie n .IP """MUTABLE_AV""" 4 |
| 21833 |
.el .IP \f(CWMUTABLE_AV\fR 4 |
| 21834 |
.IX Item "MUTABLE_AV" |
| 21835 |
.PD 0 |
| 21836 |
.ie n .IP """MUTABLE_CV""" 4 |
| 21837 |
.el .IP \f(CWMUTABLE_CV\fR 4 |
| 21838 |
.IX Item "MUTABLE_CV" |
| 21839 |
.ie n .IP """MUTABLE_GV""" 4 |
| 21840 |
.el .IP \f(CWMUTABLE_GV\fR 4 |
| 21841 |
.IX Item "MUTABLE_GV" |
| 21842 |
.ie n .IP """MUTABLE_HV""" 4 |
| 21843 |
.el .IP \f(CWMUTABLE_HV\fR 4 |
| 21844 |
.IX Item "MUTABLE_HV" |
| 21845 |
.ie n .IP """MUTABLE_IO""" 4 |
| 21846 |
.el .IP \f(CWMUTABLE_IO\fR 4 |
| 21847 |
.IX Item "MUTABLE_IO" |
| 21848 |
.ie n .IP """MUTABLE_PTR""" 4 |
| 21849 |
.el .IP \f(CWMUTABLE_PTR\fR 4 |
| 21850 |
.IX Item "MUTABLE_PTR" |
| 21851 |
.ie n .IP """MUTABLE_SV""" 4 |
| 21852 |
.el .IP \f(CWMUTABLE_SV\fR 4 |
| 21853 |
.IX Xref "MUTABLE_AV MUTABLE_CV MUTABLE_GV MUTABLE_HV MUTABLE_IO MUTABLE_PTR MUTABLE_SV" |
| 21854 |
.IX Item "MUTABLE_SV" |
| 21855 |
.PD |
| 21856 |
The \f(CW\*(C`MUTABLE_\fR\f(CI*\fR\f(CW\*(C'\fR() macros cast pointers to the types shown, in such a way |
| 21857 |
(compiler permitting) that casting away const-ness will give a warning; |
| 21858 |
e.g.: |
| 21859 |
.Sp |
| 21860 |
.Vb 4 |
| 21861 |
\& const SV *sv = ...; |
| 21862 |
\& AV *av1 = (AV*)sv; <== BAD: the const has been silently |
| 21863 |
\& cast away |
| 21864 |
\& AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn |
| 21865 |
.Ve |
| 21866 |
.Sp |
| 21867 |
\&\f(CW\*(C`MUTABLE_PTR\*(C'\fR is the base macro used to derive new casts. The other |
| 21868 |
already-built-in ones return pointers to what their names indicate. |
| 21869 |
.RS 4 |
| 21870 |
.Sp |
| 21871 |
.Vb 7 |
| 21872 |
\& AV * MUTABLE_AV (AV * p) |
| 21873 |
\& CV * MUTABLE_CV (CV * p) |
| 21874 |
\& GV * MUTABLE_GV (GV * p) |
| 21875 |
\& HV * MUTABLE_HV (HV * p) |
| 21876 |
\& IO * MUTABLE_IO (IO * p) |
| 21877 |
\& void * MUTABLE_PTR(void * p) |
| 21878 |
\& SV * MUTABLE_SV (SV * p) |
| 21879 |
.Ve |
| 21880 |
.RE |
| 21881 |
.RS 4 |
| 21882 |
.RE |
| 21883 |
.ie n .IP """newRV""" 4 |
| 21884 |
.el .IP \f(CWnewRV\fR 4 |
| 21885 |
.IX Item "newRV" |
| 21886 |
.PD 0 |
| 21887 |
.ie n .IP """newRV_inc""" 4 |
| 21888 |
.el .IP \f(CWnewRV_inc\fR 4 |
| 21889 |
.IX Xref "newRV newRV_inc" |
| 21890 |
.IX Item "newRV_inc" |
| 21891 |
.PD |
| 21892 |
These are identical. They create an RV wrapper for an SV. The reference count |
| 21893 |
for the original SV is incremented. |
| 21894 |
.RS 4 |
| 21895 |
.Sp |
| 21896 |
.Vb 1 |
| 21897 |
\& SV * newRV(SV * const sv) |
| 21898 |
.Ve |
| 21899 |
.RE |
| 21900 |
.RS 4 |
| 21901 |
.RE |
| 21902 |
.ie n .IP """newRV_noinc""" 4 |
| 21903 |
.el .IP \f(CWnewRV_noinc\fR 4 |
| 21904 |
.IX Xref "newRV_noinc" |
| 21905 |
.IX Item "newRV_noinc" |
| 21906 |
Creates an RV wrapper for an SV. The reference count for the original |
| 21907 |
SV is \fBnot\fR incremented. |
| 21908 |
.RS 4 |
| 21909 |
.Sp |
| 21910 |
.Vb 1 |
| 21911 |
\& SV * newRV_noinc(SV * const tmpRef) |
| 21912 |
.Ve |
| 21913 |
.RE |
| 21914 |
.RS 4 |
| 21915 |
.RE |
| 21916 |
.ie n .IP """newSV""" 4 |
| 21917 |
.el .IP \f(CWnewSV\fR 4 |
| 21918 |
.IX Xref "newSV" |
| 21919 |
.IX Item "newSV" |
| 21920 |
Creates a new SV. A non-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of |
| 21921 |
bytes of preallocated string space the SV should have. An extra byte for a |
| 21922 |
trailing \f(CW\*(C`NUL\*(C'\fR is also reserved. (\f(CW\*(C`SvPOK\*(C'\fR is not set for the SV even if string |
| 21923 |
space is allocated.) The reference count for the new SV is set to 1. |
| 21924 |
.Sp |
| 21925 |
In 5.9.3, \f(CWnewSV()\fR replaces the older \f(CWNEWSV()\fR API, and drops the first |
| 21926 |
parameter, \fIx\fR, a debug aid which allowed callers to identify themselves. |
| 21927 |
This aid has been superseded by a new build option, \f(CW\*(C`PERL_MEM_LOG\*(C'\fR (see |
| 21928 |
"PERL_MEM_LOG" in perlhacktips). The older API is still there for use in XS |
| 21929 |
modules supporting older perls. |
| 21930 |
.RS 4 |
| 21931 |
.Sp |
| 21932 |
.Vb 1 |
| 21933 |
\& SV * newSV(const STRLEN len) |
| 21934 |
.Ve |
| 21935 |
.RE |
| 21936 |
.RS 4 |
| 21937 |
.RE |
| 21938 |
.ie n .IP """newSVbool""" 4 |
| 21939 |
.el .IP \f(CWnewSVbool\fR 4 |
| 21940 |
.IX Xref "newSVbool" |
| 21941 |
.IX Item "newSVbool" |
| 21942 |
Creates a new SV boolean. |
| 21943 |
.RS 4 |
| 21944 |
.Sp |
| 21945 |
.Vb 1 |
| 21946 |
\& SV * newSVbool(const bool bool_val) |
| 21947 |
.Ve |
| 21948 |
.RE |
| 21949 |
.RS 4 |
| 21950 |
.RE |
| 21951 |
.ie n .IP """newSV_false""" 4 |
| 21952 |
.el .IP \f(CWnewSV_false\fR 4 |
| 21953 |
.IX Xref "newSV_false" |
| 21954 |
.IX Item "newSV_false" |
| 21955 |
Creates a new SV that is a boolean false. |
| 21956 |
.RS 4 |
| 21957 |
.Sp |
| 21958 |
.Vb 1 |
| 21959 |
\& SV * newSV_false() |
| 21960 |
.Ve |
| 21961 |
.RE |
| 21962 |
.RS 4 |
| 21963 |
.RE |
| 21964 |
.ie n .IP """newSVhek""" 4 |
| 21965 |
.el .IP \f(CWnewSVhek\fR 4 |
| 21966 |
.IX Xref "newSVhek" |
| 21967 |
.IX Item "newSVhek" |
| 21968 |
Creates a new SV from the hash key structure. It will generate scalars that |
| 21969 |
point to the shared string table where possible. Returns a new (undefined) |
| 21970 |
SV if \f(CW\*(C`hek\*(C'\fR is NULL. |
| 21971 |
.RS 4 |
| 21972 |
.Sp |
| 21973 |
.Vb 1 |
| 21974 |
\& SV * newSVhek(const HEK * const hek) |
| 21975 |
.Ve |
| 21976 |
.RE |
| 21977 |
.RS 4 |
| 21978 |
.RE |
| 21979 |
.ie n .IP """newSVhek_mortal""" 4 |
| 21980 |
.el .IP \f(CWnewSVhek_mortal\fR 4 |
| 21981 |
.IX Xref "newSVhek_mortal" |
| 21982 |
.IX Item "newSVhek_mortal" |
| 21983 |
Creates a new mortal SV from the hash key structure. It will generate |
| 21984 |
scalars that point to the shared string table where possible. Returns |
| 21985 |
a new (undefined) SV if \f(CW\*(C`hek\*(C'\fR is NULL. |
| 21986 |
.Sp |
| 21987 |
This is more efficient than using sv_2mortal(newSVhek( ... )) |
| 21988 |
.RS 4 |
| 21989 |
.Sp |
| 21990 |
.Vb 1 |
| 21991 |
\& SV * newSVhek_mortal(const HEK * const hek) |
| 21992 |
.Ve |
| 21993 |
.RE |
| 21994 |
.RS 4 |
| 21995 |
.RE |
| 21996 |
.ie n .IP """newSViv""" 4 |
| 21997 |
.el .IP \f(CWnewSViv\fR 4 |
| 21998 |
.IX Xref "newSViv" |
| 21999 |
.IX Item "newSViv" |
| 22000 |
Creates a new SV and copies an integer into it. The reference count for the |
| 22001 |
SV is set to 1. |
| 22002 |
.RS 4 |
| 22003 |
.Sp |
| 22004 |
.Vb 1 |
| 22005 |
\& SV * newSViv(const IV i) |
| 22006 |
.Ve |
| 22007 |
.RE |
| 22008 |
.RS 4 |
| 22009 |
.RE |
| 22010 |
.ie n .IP """newSVnv""" 4 |
| 22011 |
.el .IP \f(CWnewSVnv\fR 4 |
| 22012 |
.IX Xref "newSVnv" |
| 22013 |
.IX Item "newSVnv" |
| 22014 |
Creates a new SV and copies a floating point value into it. |
| 22015 |
The reference count for the SV is set to 1. |
| 22016 |
.RS 4 |
| 22017 |
.Sp |
| 22018 |
.Vb 1 |
| 22019 |
\& SV * newSVnv(const NV n) |
| 22020 |
.Ve |
| 22021 |
.RE |
| 22022 |
.RS 4 |
| 22023 |
.RE |
| 22024 |
.ie n .IP """newSVpadname""" 4 |
| 22025 |
.el .IP \f(CWnewSVpadname\fR 4 |
| 22026 |
.IX Xref "newSVpadname" |
| 22027 |
.IX Item "newSVpadname" |
| 22028 |
NOTE: \f(CW\*(C`newSVpadname\*(C'\fR is \fBexperimental\fR and may change or be |
| 22029 |
removed without notice. |
| 22030 |
.Sp |
| 22031 |
Creates a new SV containing the pad name. |
| 22032 |
.RS 4 |
| 22033 |
.Sp |
| 22034 |
.Vb 1 |
| 22035 |
\& SV* newSVpadname(PADNAME *pn) |
| 22036 |
.Ve |
| 22037 |
.RE |
| 22038 |
.RS 4 |
| 22039 |
.RE |
| 22040 |
.ie n .IP """newSVpv""" 4 |
| 22041 |
.el .IP \f(CWnewSVpv\fR 4 |
| 22042 |
.IX Xref "newSVpv" |
| 22043 |
.IX Item "newSVpv" |
| 22044 |
Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR) |
| 22045 |
characters) into it. The reference count for the |
| 22046 |
SV is set to 1. If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using |
| 22047 |
\&\f(CWstrlen()\fR, (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded |
| 22048 |
\&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte). |
| 22049 |
.Sp |
| 22050 |
This function can cause reliability issues if you are likely to pass in |
| 22051 |
empty strings that are not null terminated, because it will run |
| 22052 |
strlen on the string and potentially run past valid memory. |
| 22053 |
.Sp |
| 22054 |
Using "newSVpvn" is a safer alternative for non \f(CW\*(C`NUL\*(C'\fR terminated strings. |
| 22055 |
For string literals use "newSVpvs" instead. This function will work fine for |
| 22056 |
\&\f(CW\*(C`NUL\*(C'\fR terminated strings, but if you want to avoid the if statement on whether |
| 22057 |
to call \f(CW\*(C`strlen\*(C'\fR use \f(CW\*(C`newSVpvn\*(C'\fR instead (calling \f(CW\*(C`strlen\*(C'\fR yourself). |
| 22058 |
.RS 4 |
| 22059 |
.Sp |
| 22060 |
.Vb 1 |
| 22061 |
\& SV * newSVpv(const char * const s, const STRLEN len) |
| 22062 |
.Ve |
| 22063 |
.RE |
| 22064 |
.RS 4 |
| 22065 |
.RE |
| 22066 |
.ie n .IP """newSVpvf""" 4 |
| 22067 |
.el .IP \f(CWnewSVpvf\fR 4 |
| 22068 |
.IX Xref "newSVpvf" |
| 22069 |
.IX Item "newSVpvf" |
| 22070 |
Creates a new SV and initializes it with the string formatted like |
| 22071 |
\&\f(CW\*(C`sv_catpvf\*(C'\fR. |
| 22072 |
.Sp |
| 22073 |
NOTE: \f(CW\*(C`newSVpvf\*(C'\fR must be explicitly called as |
| 22074 |
\&\f(CW\*(C`Perl_newSVpvf\*(C'\fR |
| 22075 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 22076 |
.RS 4 |
| 22077 |
.Sp |
| 22078 |
.Vb 1 |
| 22079 |
\& SV * Perl_newSVpvf(pTHX_ const char * const pat, ...) |
| 22080 |
.Ve |
| 22081 |
.RE |
| 22082 |
.RS 4 |
| 22083 |
.RE |
| 22084 |
.ie n .IP """newSVpvf_nocontext""" 4 |
| 22085 |
.el .IP \f(CWnewSVpvf_nocontext\fR 4 |
| 22086 |
.IX Xref "newSVpvf_nocontext" |
| 22087 |
.IX Item "newSVpvf_nocontext" |
| 22088 |
Like \f(CW"newSVpvf"\fR but does not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter, |
| 22089 |
so is used in situations where the caller doesn't already have the thread |
| 22090 |
context. |
| 22091 |
.RS 4 |
| 22092 |
.Sp |
| 22093 |
.Vb 1 |
| 22094 |
\& SV * newSVpvf_nocontext(const char * const pat, ...) |
| 22095 |
.Ve |
| 22096 |
.RE |
| 22097 |
.RS 4 |
| 22098 |
.RE |
| 22099 |
.ie n .IP """newSVpvn""" 4 |
| 22100 |
.el .IP \f(CWnewSVpvn\fR 4 |
| 22101 |
.IX Xref "newSVpvn" |
| 22102 |
.IX Item "newSVpvn" |
| 22103 |
Creates a new SV and copies a string into it, which may contain \f(CW\*(C`NUL\*(C'\fR characters |
| 22104 |
(\f(CW\*(C`\e0\*(C'\fR) and other binary data. The reference count for the SV is set to 1. |
| 22105 |
Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length (Perl) string. You |
| 22106 |
are responsible for ensuring that the source buffer is at least |
| 22107 |
\&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`buffer\*(C'\fR argument is NULL the new SV will be |
| 22108 |
undefined. |
| 22109 |
.RS 4 |
| 22110 |
.Sp |
| 22111 |
.Vb 1 |
| 22112 |
\& SV * newSVpvn(const char * const buffer, const STRLEN len) |
| 22113 |
.Ve |
| 22114 |
.RE |
| 22115 |
.RS 4 |
| 22116 |
.RE |
| 22117 |
.ie n .IP """newSVpvn_flags""" 4 |
| 22118 |
.el .IP \f(CWnewSVpvn_flags\fR 4 |
| 22119 |
.IX Xref "newSVpvn_flags" |
| 22120 |
.IX Item "newSVpvn_flags" |
| 22121 |
Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR) |
| 22122 |
characters) into it. The reference count for the |
| 22123 |
SV is set to 1. Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length |
| 22124 |
string. You are responsible for ensuring that the source string is at least |
| 22125 |
\&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`s\*(C'\fR argument is NULL the new SV will be undefined. |
| 22126 |
Currently the only flag bits accepted are \f(CW\*(C`SVf_UTF8\*(C'\fR and \f(CW\*(C`SVs_TEMP\*(C'\fR. |
| 22127 |
If \f(CW\*(C`SVs_TEMP\*(C'\fR is set, then \f(CWsv_2mortal()\fR is called on the result before |
| 22128 |
returning. If \f(CW\*(C`SVf_UTF8\*(C'\fR is set, \f(CW\*(C`s\*(C'\fR |
| 22129 |
is considered to be in UTF\-8 and the |
| 22130 |
\&\f(CW\*(C`SVf_UTF8\*(C'\fR flag will be set on the new SV. |
| 22131 |
\&\f(CWnewSVpvn_utf8()\fR is a convenience wrapper for this function, defined as |
| 22132 |
.Sp |
| 22133 |
.Vb 2 |
| 22134 |
\& #define newSVpvn_utf8(s, len, u) \e |
| 22135 |
\& newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0) |
| 22136 |
.Ve |
| 22137 |
.RS 4 |
| 22138 |
.Sp |
| 22139 |
.Vb 2 |
| 22140 |
\& SV * newSVpvn_flags(const char * const s, const STRLEN len, |
| 22141 |
\& const U32 flags) |
| 22142 |
.Ve |
| 22143 |
.RE |
| 22144 |
.RS 4 |
| 22145 |
.RE |
| 22146 |
.ie n .IP """newSVpvn_share""" 4 |
| 22147 |
.el .IP \f(CWnewSVpvn_share\fR 4 |
| 22148 |
.IX Xref "newSVpvn_share" |
| 22149 |
.IX Item "newSVpvn_share" |
| 22150 |
Creates a new SV with its \f(CW\*(C`SvPVX_const\*(C'\fR pointing to a shared string in the string |
| 22151 |
table. If the string does not already exist in the table, it is |
| 22152 |
created first. Turns on the \f(CW\*(C`SvIsCOW\*(C'\fR flag (or \f(CW\*(C`READONLY\*(C'\fR |
| 22153 |
and \f(CW\*(C`FAKE\*(C'\fR in 5.16 and earlier). If the \f(CW\*(C`hash\*(C'\fR parameter |
| 22154 |
is non-zero, that value is used; otherwise the hash is computed. |
| 22155 |
The string's hash can later be retrieved from the SV |
| 22156 |
with the \f(CW"SvSHARED_HASH"\fR macro. The idea here is |
| 22157 |
that as the string table is used for shared hash keys these strings will have |
| 22158 |
\&\f(CW\*(C`SvPVX_const == HeKEY\*(C'\fR and hash lookup will avoid string compare. |
| 22159 |
.RS 4 |
| 22160 |
.Sp |
| 22161 |
.Vb 1 |
| 22162 |
\& SV * newSVpvn_share(const char *s, I32 len, U32 hash) |
| 22163 |
.Ve |
| 22164 |
.RE |
| 22165 |
.RS 4 |
| 22166 |
.RE |
| 22167 |
.ie n .IP """newSVpvn_utf8""" 4 |
| 22168 |
.el .IP \f(CWnewSVpvn_utf8\fR 4 |
| 22169 |
.IX Xref "newSVpvn_utf8" |
| 22170 |
.IX Item "newSVpvn_utf8" |
| 22171 |
Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR) |
| 22172 |
characters) into it. If \f(CW\*(C`utf8\*(C'\fR is true, calls |
| 22173 |
\&\f(CW\*(C`SvUTF8_on\*(C'\fR on the new SV. Implemented as a wrapper around \f(CW\*(C`newSVpvn_flags\*(C'\fR. |
| 22174 |
.RS 4 |
| 22175 |
.Sp |
| 22176 |
.Vb 1 |
| 22177 |
\& SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8) |
| 22178 |
.Ve |
| 22179 |
.RE |
| 22180 |
.RS 4 |
| 22181 |
.RE |
| 22182 |
.ie n .IP """newSVpvs""" 4 |
| 22183 |
.el .IP \f(CWnewSVpvs\fR 4 |
| 22184 |
.IX Xref "newSVpvs" |
| 22185 |
.IX Item "newSVpvs" |
| 22186 |
Like \f(CW\*(C`newSVpvn\*(C'\fR, but takes a literal string instead of a |
| 22187 |
string/length pair. |
| 22188 |
.RS 4 |
| 22189 |
.Sp |
| 22190 |
.Vb 1 |
| 22191 |
\& SV* newSVpvs("literal string") |
| 22192 |
.Ve |
| 22193 |
.RE |
| 22194 |
.RS 4 |
| 22195 |
.RE |
| 22196 |
.ie n .IP """newSVpvs_flags""" 4 |
| 22197 |
.el .IP \f(CWnewSVpvs_flags\fR 4 |
| 22198 |
.IX Xref "newSVpvs_flags" |
| 22199 |
.IX Item "newSVpvs_flags" |
| 22200 |
Like \f(CW\*(C`newSVpvn_flags\*(C'\fR, but takes a literal string instead of |
| 22201 |
a string/length pair. |
| 22202 |
.RS 4 |
| 22203 |
.Sp |
| 22204 |
.Vb 1 |
| 22205 |
\& SV* newSVpvs_flags("literal string", U32 flags) |
| 22206 |
.Ve |
| 22207 |
.RE |
| 22208 |
.RS 4 |
| 22209 |
.RE |
| 22210 |
.ie n .IP """newSVpv_share""" 4 |
| 22211 |
.el .IP \f(CWnewSVpv_share\fR 4 |
| 22212 |
.IX Xref "newSVpv_share" |
| 22213 |
.IX Item "newSVpv_share" |
| 22214 |
Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a \f(CW\*(C`NUL\*(C'\fR\-terminated string instead of a |
| 22215 |
string/length pair. |
| 22216 |
.RS 4 |
| 22217 |
.Sp |
| 22218 |
.Vb 1 |
| 22219 |
\& SV * newSVpv_share(const char *s, U32 hash) |
| 22220 |
.Ve |
| 22221 |
.RE |
| 22222 |
.RS 4 |
| 22223 |
.RE |
| 22224 |
.ie n .IP """newSVpvs_share""" 4 |
| 22225 |
.el .IP \f(CWnewSVpvs_share\fR 4 |
| 22226 |
.IX Xref "newSVpvs_share" |
| 22227 |
.IX Item "newSVpvs_share" |
| 22228 |
Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a literal string instead of |
| 22229 |
a string/length pair and omits the hash parameter. |
| 22230 |
.RS 4 |
| 22231 |
.Sp |
| 22232 |
.Vb 1 |
| 22233 |
\& SV* newSVpvs_share("literal string") |
| 22234 |
.Ve |
| 22235 |
.RE |
| 22236 |
.RS 4 |
| 22237 |
.RE |
| 22238 |
.ie n .IP """newSVrv""" 4 |
| 22239 |
.el .IP \f(CWnewSVrv\fR 4 |
| 22240 |
.IX Xref "newSVrv" |
| 22241 |
.IX Item "newSVrv" |
| 22242 |
Creates a new SV for the existing RV, \f(CW\*(C`rv\*(C'\fR, to point to. If \f(CW\*(C`rv\*(C'\fR is not an |
| 22243 |
RV then it will be upgraded to one. If \f(CW\*(C`classname\*(C'\fR is non-null then the new |
| 22244 |
SV will be blessed in the specified package. The new SV is returned and its |
| 22245 |
reference count is 1. The reference count 1 is owned by \f(CW\*(C`rv\*(C'\fR. See also |
| 22246 |
\&\fBnewRV_inc()\fR and \fBnewRV_noinc()\fR for creating a new RV properly. |
| 22247 |
.RS 4 |
| 22248 |
.Sp |
| 22249 |
.Vb 1 |
| 22250 |
\& SV * newSVrv(SV * const rv, const char * const classname) |
| 22251 |
.Ve |
| 22252 |
.RE |
| 22253 |
.RS 4 |
| 22254 |
.RE |
| 22255 |
.ie n .IP """newSVsv""" 4 |
| 22256 |
.el .IP \f(CWnewSVsv\fR 4 |
| 22257 |
.IX Item "newSVsv" |
| 22258 |
.PD 0 |
| 22259 |
.ie n .IP """newSVsv_flags""" 4 |
| 22260 |
.el .IP \f(CWnewSVsv_flags\fR 4 |
| 22261 |
.IX Item "newSVsv_flags" |
| 22262 |
.ie n .IP """newSVsv_nomg""" 4 |
| 22263 |
.el .IP \f(CWnewSVsv_nomg\fR 4 |
| 22264 |
.IX Xref "newSVsv newSVsv_flags newSVsv_nomg" |
| 22265 |
.IX Item "newSVsv_nomg" |
| 22266 |
.PD |
| 22267 |
These create a new SV which is an exact duplicate of the original SV |
| 22268 |
(using \f(CW\*(C`sv_setsv\*(C'\fR.) |
| 22269 |
.Sp |
| 22270 |
They differ only in that \f(CW\*(C`newSVsv\*(C'\fR performs 'get' magic; \f(CW\*(C`newSVsv_nomg\*(C'\fR skips |
| 22271 |
any magic; and \f(CW\*(C`newSVsv_flags\*(C'\fR allows you to explicitly set a \f(CW\*(C`flags\*(C'\fR |
| 22272 |
parameter. |
| 22273 |
.RS 4 |
| 22274 |
.Sp |
| 22275 |
.Vb 3 |
| 22276 |
\& SV * newSVsv (SV * const old) |
| 22277 |
\& SV * newSVsv_flags(SV * const old, I32 flags) |
| 22278 |
\& SV * newSVsv_nomg (SV * const old) |
| 22279 |
.Ve |
| 22280 |
.RE |
| 22281 |
.RS 4 |
| 22282 |
.RE |
| 22283 |
.ie n .IP """newSV_true""" 4 |
| 22284 |
.el .IP \f(CWnewSV_true\fR 4 |
| 22285 |
.IX Xref "newSV_true" |
| 22286 |
.IX Item "newSV_true" |
| 22287 |
Creates a new SV that is a boolean true. |
| 22288 |
.RS 4 |
| 22289 |
.Sp |
| 22290 |
.Vb 1 |
| 22291 |
\& SV * newSV_true() |
| 22292 |
.Ve |
| 22293 |
.RE |
| 22294 |
.RS 4 |
| 22295 |
.RE |
| 22296 |
.ie n .IP """newSV_type""" 4 |
| 22297 |
.el .IP \f(CWnewSV_type\fR 4 |
| 22298 |
.IX Xref "newSV_type" |
| 22299 |
.IX Item "newSV_type" |
| 22300 |
Creates a new SV, of the type specified. The reference count for the new SV |
| 22301 |
is set to 1. |
| 22302 |
.RS 4 |
| 22303 |
.Sp |
| 22304 |
.Vb 1 |
| 22305 |
\& SV * newSV_type(const svtype type) |
| 22306 |
.Ve |
| 22307 |
.RE |
| 22308 |
.RS 4 |
| 22309 |
.RE |
| 22310 |
.ie n .IP """newSV_type_mortal""" 4 |
| 22311 |
.el .IP \f(CWnewSV_type_mortal\fR 4 |
| 22312 |
.IX Xref "newSV_type_mortal" |
| 22313 |
.IX Item "newSV_type_mortal" |
| 22314 |
Creates a new mortal SV, of the type specified. The reference count for the |
| 22315 |
new SV is set to 1. |
| 22316 |
.Sp |
| 22317 |
This is equivalent to |
| 22318 |
SV* sv = sv_2mortal(newSV_type(<some type>)) |
| 22319 |
and |
| 22320 |
SV* sv = \fBsv_newmortal()\fR; |
| 22321 |
sv_upgrade(sv, <some_type>) |
| 22322 |
but should be more efficient than both of them. (Unless sv_2mortal is inlined |
| 22323 |
at some point in the future.) |
| 22324 |
.RS 4 |
| 22325 |
.Sp |
| 22326 |
.Vb 1 |
| 22327 |
\& SV * newSV_type_mortal(const svtype type) |
| 22328 |
.Ve |
| 22329 |
.RE |
| 22330 |
.RS 4 |
| 22331 |
.RE |
| 22332 |
.ie n .IP """newSVuv""" 4 |
| 22333 |
.el .IP \f(CWnewSVuv\fR 4 |
| 22334 |
.IX Xref "newSVuv" |
| 22335 |
.IX Item "newSVuv" |
| 22336 |
Creates a new SV and copies an unsigned integer into it. |
| 22337 |
The reference count for the SV is set to 1. |
| 22338 |
.RS 4 |
| 22339 |
.Sp |
| 22340 |
.Vb 1 |
| 22341 |
\& SV * newSVuv(const UV u) |
| 22342 |
.Ve |
| 22343 |
.RE |
| 22344 |
.RS 4 |
| 22345 |
.RE |
| 22346 |
.ie n .IP """Nullsv""" 4 |
| 22347 |
.el .IP \f(CWNullsv\fR 4 |
| 22348 |
.IX Xref "Nullsv" |
| 22349 |
.IX Item "Nullsv" |
| 22350 |
Null SV pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is defined.) |
| 22351 |
.ie n .IP """PL_sv_no""" 4 |
| 22352 |
.el .IP \f(CWPL_sv_no\fR 4 |
| 22353 |
.IX Xref "PL_sv_no" |
| 22354 |
.IX Item "PL_sv_no" |
| 22355 |
This is the \f(CW\*(C`false\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_yes"\fR. Always refer |
| 22356 |
to this as \f(CW&PL_sv_no\fR. |
| 22357 |
.RS 4 |
| 22358 |
.Sp |
| 22359 |
.Vb 1 |
| 22360 |
\& SV PL_sv_no |
| 22361 |
.Ve |
| 22362 |
.RE |
| 22363 |
.RS 4 |
| 22364 |
.RE |
| 22365 |
.ie n .IP """PL_sv_undef""" 4 |
| 22366 |
.el .IP \f(CWPL_sv_undef\fR 4 |
| 22367 |
.IX Xref "PL_sv_undef" |
| 22368 |
.IX Item "PL_sv_undef" |
| 22369 |
This is the \f(CW\*(C`undef\*(C'\fR SV. It is readonly. Always refer to this as |
| 22370 |
\&\f(CW&PL_sv_undef\fR. |
| 22371 |
.RS 4 |
| 22372 |
.Sp |
| 22373 |
.Vb 1 |
| 22374 |
\& SV PL_sv_undef |
| 22375 |
.Ve |
| 22376 |
.RE |
| 22377 |
.RS 4 |
| 22378 |
.RE |
| 22379 |
.ie n .IP """PL_sv_yes""" 4 |
| 22380 |
.el .IP \f(CWPL_sv_yes\fR 4 |
| 22381 |
.IX Xref "PL_sv_yes" |
| 22382 |
.IX Item "PL_sv_yes" |
| 22383 |
This is the \f(CW\*(C`true\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_no"\fR. Always refer to |
| 22384 |
this as \f(CW&PL_sv_yes\fR. |
| 22385 |
.RS 4 |
| 22386 |
.Sp |
| 22387 |
.Vb 1 |
| 22388 |
\& SV PL_sv_yes |
| 22389 |
.Ve |
| 22390 |
.RE |
| 22391 |
.RS 4 |
| 22392 |
.RE |
| 22393 |
.ie n .IP """PL_sv_zero""" 4 |
| 22394 |
.el .IP \f(CWPL_sv_zero\fR 4 |
| 22395 |
.IX Xref "PL_sv_zero" |
| 22396 |
.IX Item "PL_sv_zero" |
| 22397 |
This readonly SV has a zero numeric value and a \f(CW"0"\fR string value. It's |
| 22398 |
similar to \f(CW"PL_sv_no"\fR except for its string value. Can be used as a |
| 22399 |
cheap alternative to \f(CWmXPUSHi(0)\fR for example. Always refer to this as |
| 22400 |
\&\f(CW&PL_sv_zero\fR. Introduced in 5.28. |
| 22401 |
.RS 4 |
| 22402 |
.Sp |
| 22403 |
.Vb 1 |
| 22404 |
\& SV PL_sv_zero |
| 22405 |
.Ve |
| 22406 |
.RE |
| 22407 |
.RS 4 |
| 22408 |
.RE |
| 22409 |
.ie n .IP """SAVE_DEFSV""" 4 |
| 22410 |
.el .IP \f(CWSAVE_DEFSV\fR 4 |
| 22411 |
.IX Xref "SAVE_DEFSV" |
| 22412 |
.IX Item "SAVE_DEFSV" |
| 22413 |
Localize \f(CW$_\fR. See "Localizing changes" in perlguts. |
| 22414 |
.RS 4 |
| 22415 |
.Sp |
| 22416 |
.Vb 1 |
| 22417 |
\& void SAVE_DEFSV |
| 22418 |
.Ve |
| 22419 |
.RE |
| 22420 |
.RS 4 |
| 22421 |
.RE |
| 22422 |
.ie n .IP """sortsv""" 4 |
| 22423 |
.el .IP \f(CWsortsv\fR 4 |
| 22424 |
.IX Xref "sortsv" |
| 22425 |
.IX Item "sortsv" |
| 22426 |
In-place sort an array of SV pointers with the given comparison routine. |
| 22427 |
.Sp |
| 22428 |
Currently this always uses mergesort. See \f(CW"sortsv_flags"\fR for a more |
| 22429 |
flexible routine. |
| 22430 |
.RS 4 |
| 22431 |
.Sp |
| 22432 |
.Vb 1 |
| 22433 |
\& void sortsv(SV **array, size_t num_elts, SVCOMPARE_t cmp) |
| 22434 |
.Ve |
| 22435 |
.RE |
| 22436 |
.RS 4 |
| 22437 |
.RE |
| 22438 |
.ie n .IP """sortsv_flags""" 4 |
| 22439 |
.el .IP \f(CWsortsv_flags\fR 4 |
| 22440 |
.IX Xref "sortsv_flags" |
| 22441 |
.IX Item "sortsv_flags" |
| 22442 |
In-place sort an array of SV pointers with the given comparison routine, |
| 22443 |
with various SORTf_* flag options. |
| 22444 |
.RS 4 |
| 22445 |
.Sp |
| 22446 |
.Vb 2 |
| 22447 |
\& void sortsv_flags(SV **array, size_t num_elts, SVCOMPARE_t cmp, |
| 22448 |
\& U32 flags) |
| 22449 |
.Ve |
| 22450 |
.RE |
| 22451 |
.RS 4 |
| 22452 |
.RE |
| 22453 |
.ie n .IP """SV""" 4 |
| 22454 |
.el .IP \f(CWSV\fR 4 |
| 22455 |
.IX Item "SV" |
| 22456 |
Described in perlguts. |
| 22457 |
.ie n .IP """SvAMAGIC""" 4 |
| 22458 |
.el .IP \f(CWSvAMAGIC\fR 4 |
| 22459 |
.IX Xref "SvAMAGIC" |
| 22460 |
.IX Item "SvAMAGIC" |
| 22461 |
Returns a boolean as to whether \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled or |
| 22462 |
not. |
| 22463 |
.RS 4 |
| 22464 |
.Sp |
| 22465 |
.Vb 1 |
| 22466 |
\& bool SvAMAGIC(SV * sv) |
| 22467 |
.Ve |
| 22468 |
.RE |
| 22469 |
.RS 4 |
| 22470 |
.RE |
| 22471 |
.ie n .IP """SvAMAGIC_off""" 4 |
| 22472 |
.el .IP \f(CWSvAMAGIC_off\fR 4 |
| 22473 |
.IX Xref "SvAMAGIC_off" |
| 22474 |
.IX Item "SvAMAGIC_off" |
| 22475 |
Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) disabled. |
| 22476 |
.RS 4 |
| 22477 |
.Sp |
| 22478 |
.Vb 1 |
| 22479 |
\& void SvAMAGIC_off(SV *sv) |
| 22480 |
.Ve |
| 22481 |
.RE |
| 22482 |
.RS 4 |
| 22483 |
.RE |
| 22484 |
.ie n .IP """SvAMAGIC_on""" 4 |
| 22485 |
.el .IP \f(CWSvAMAGIC_on\fR 4 |
| 22486 |
.IX Xref "SvAMAGIC_on" |
| 22487 |
.IX Item "SvAMAGIC_on" |
| 22488 |
Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled. |
| 22489 |
.RS 4 |
| 22490 |
.Sp |
| 22491 |
.Vb 1 |
| 22492 |
\& void SvAMAGIC_on(SV *sv) |
| 22493 |
.Ve |
| 22494 |
.RE |
| 22495 |
.RS 4 |
| 22496 |
.RE |
| 22497 |
.ie n .IP """sv_backoff""" 4 |
| 22498 |
.el .IP \f(CWsv_backoff\fR 4 |
| 22499 |
.IX Xref "sv_backoff" |
| 22500 |
.IX Item "sv_backoff" |
| 22501 |
Remove any string offset. You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro |
| 22502 |
wrapper instead. |
| 22503 |
.RS 4 |
| 22504 |
.Sp |
| 22505 |
.Vb 1 |
| 22506 |
\& void sv_backoff(SV * const sv) |
| 22507 |
.Ve |
| 22508 |
.RE |
| 22509 |
.RS 4 |
| 22510 |
.RE |
| 22511 |
.ie n .IP """sv_bless""" 4 |
| 22512 |
.el .IP \f(CWsv_bless\fR 4 |
| 22513 |
.IX Xref "sv_bless" |
| 22514 |
.IX Item "sv_bless" |
| 22515 |
Blesses an SV into a specified package. The SV must be an RV. The package |
| 22516 |
must be designated by its stash (see \f(CW"gv_stashpv"\fR). The reference count |
| 22517 |
of the SV is unaffected. |
| 22518 |
.RS 4 |
| 22519 |
.Sp |
| 22520 |
.Vb 1 |
| 22521 |
\& SV * sv_bless(SV * const sv, HV * const stash) |
| 22522 |
.Ve |
| 22523 |
.RE |
| 22524 |
.RS 4 |
| 22525 |
.RE |
| 22526 |
.ie n .IP """SvBoolFlagsOK""" 4 |
| 22527 |
.el .IP \f(CWSvBoolFlagsOK\fR 4 |
| 22528 |
.IX Xref "SvBoolFlagsOK" |
| 22529 |
.IX Item "SvBoolFlagsOK" |
| 22530 |
Returns a bool indicating whether the SV has the right flags set such |
| 22531 |
that it is safe to call \f(CWBOOL_INTERNALS_sv_isbool()\fR or |
| 22532 |
\&\f(CWBOOL_INTERNALS_sv_isbool_true()\fR or |
| 22533 |
\&\f(CWBOOL_INTERNALS_sv_isbool_false()\fR. Currently equivalent to |
| 22534 |
\&\f(CWSvIandPOK(sv)\fR or \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR. Serialization may want to |
| 22535 |
unroll this check. If so you are strongly recommended to add code like |
| 22536 |
\&\f(CW\*(C`assert(SvBoolFlagsOK(sv));\*(C'\fR \fBbefore\fR calling using any of the |
| 22537 |
BOOL_INTERNALS macros. |
| 22538 |
.RS 4 |
| 22539 |
.Sp |
| 22540 |
.Vb 1 |
| 22541 |
\& U32 SvBoolFlagsOK(SV* sv) |
| 22542 |
.Ve |
| 22543 |
.RE |
| 22544 |
.RS 4 |
| 22545 |
.RE |
| 22546 |
.ie n .IP """sv_catpv""" 4 |
| 22547 |
.el .IP \f(CWsv_catpv\fR 4 |
| 22548 |
.IX Item "sv_catpv" |
| 22549 |
.PD 0 |
| 22550 |
.ie n .IP """sv_catpv_flags""" 4 |
| 22551 |
.el .IP \f(CWsv_catpv_flags\fR 4 |
| 22552 |
.IX Item "sv_catpv_flags" |
| 22553 |
.ie n .IP """sv_catpv_mg""" 4 |
| 22554 |
.el .IP \f(CWsv_catpv_mg\fR 4 |
| 22555 |
.IX Item "sv_catpv_mg" |
| 22556 |
.ie n .IP """sv_catpv_nomg""" 4 |
| 22557 |
.el .IP \f(CWsv_catpv_nomg\fR 4 |
| 22558 |
.IX Xref "sv_catpv sv_catpv_flags sv_catpv_mg sv_catpv_nomg" |
| 22559 |
.IX Item "sv_catpv_nomg" |
| 22560 |
.PD |
| 22561 |
These concatenate the \f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`sstr\*(C'\fR onto the end of the |
| 22562 |
string which is in the SV. |
| 22563 |
If the SV has the UTF\-8 status set, then the bytes appended should be |
| 22564 |
valid UTF\-8. |
| 22565 |
.Sp |
| 22566 |
They differ only in how they handle magic: |
| 22567 |
.Sp |
| 22568 |
\&\f(CW\*(C`sv_catpv_mg\*(C'\fR performs both 'get' and 'set' magic. |
| 22569 |
.Sp |
| 22570 |
\&\f(CW\*(C`sv_catpv\*(C'\fR performs only 'get' magic. |
| 22571 |
.Sp |
| 22572 |
\&\f(CW\*(C`sv_catpv_nomg\*(C'\fR skips all magic. |
| 22573 |
.Sp |
| 22574 |
\&\f(CW\*(C`sv_catpv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify |
| 22575 |
any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR), and |
| 22576 |
to also override the UTF\-8 handling. By supplying the \f(CW\*(C`SV_CATUTF8\*(C'\fR flag, the |
| 22577 |
appended string is forced to be interpreted as UTF\-8; by supplying instead the |
| 22578 |
\&\f(CW\*(C`SV_CATBYTES\*(C'\fR flag, it will be interpreted as just bytes. Either the SV or |
| 22579 |
the string appended will be upgraded to UTF\-8 if necessary. |
| 22580 |
.RS 4 |
| 22581 |
.Sp |
| 22582 |
.Vb 4 |
| 22583 |
\& void sv_catpv (SV * const dsv, const char *sstr) |
| 22584 |
\& void sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags) |
| 22585 |
\& void sv_catpv_mg (SV * const dsv, const char * const sstr) |
| 22586 |
\& void sv_catpv_nomg (SV * const dsv, const char *sstr) |
| 22587 |
.Ve |
| 22588 |
.RE |
| 22589 |
.RS 4 |
| 22590 |
.RE |
| 22591 |
.ie n .IP """sv_catpvf""" 4 |
| 22592 |
.el .IP \f(CWsv_catpvf\fR 4 |
| 22593 |
.IX Item "sv_catpvf" |
| 22594 |
.PD 0 |
| 22595 |
.ie n .IP """sv_catpvf_mg""" 4 |
| 22596 |
.el .IP \f(CWsv_catpvf_mg\fR 4 |
| 22597 |
.IX Item "sv_catpvf_mg" |
| 22598 |
.ie n .IP """sv_catpvf_mg_nocontext""" 4 |
| 22599 |
.el .IP \f(CWsv_catpvf_mg_nocontext\fR 4 |
| 22600 |
.IX Item "sv_catpvf_mg_nocontext" |
| 22601 |
.ie n .IP """sv_catpvf_nocontext""" 4 |
| 22602 |
.el .IP \f(CWsv_catpvf_nocontext\fR 4 |
| 22603 |
.IX Xref "sv_catpvf sv_catpvf_mg sv_catpvf_mg_nocontext sv_catpvf_nocontext" |
| 22604 |
.IX Item "sv_catpvf_nocontext" |
| 22605 |
.PD |
| 22606 |
These process their arguments like \f(CW\*(C`sprintf\*(C'\fR, and append the formatted |
| 22607 |
output to an SV. As with \f(CW\*(C`sv_vcatpvfn\*(C'\fR, argument reordering is not supporte |
| 22608 |
when called with a non-null C\-style variable argument list. |
| 22609 |
.Sp |
| 22610 |
If the appended data contains "wide" characters |
| 22611 |
(including, but not limited to, SVs with a UTF\-8 PV formatted with \f(CW%s\fR, |
| 22612 |
and characters >255 formatted with \f(CW%c\fR), the original SV might get |
| 22613 |
upgraded to UTF\-8. |
| 22614 |
.Sp |
| 22615 |
If the original SV was UTF\-8, the pattern should be |
| 22616 |
valid UTF\-8; if the original SV was bytes, the pattern should be too. |
| 22617 |
.Sp |
| 22618 |
All perform 'get' magic, but only \f(CW\*(C`sv_catpvf_mg\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR |
| 22619 |
perform 'set' magic. |
| 22620 |
.Sp |
| 22621 |
\&\f(CW\*(C`sv_catpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR do not take a thread |
| 22622 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller |
| 22623 |
doesn't already have the thread context. |
| 22624 |
.Sp |
| 22625 |
NOTE: \f(CW\*(C`sv_catpvf\*(C'\fR must be explicitly called as |
| 22626 |
\&\f(CW\*(C`Perl_sv_catpvf\*(C'\fR |
| 22627 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 22628 |
.Sp |
| 22629 |
NOTE: \f(CW\*(C`sv_catpvf_mg\*(C'\fR must be explicitly called as |
| 22630 |
\&\f(CW\*(C`Perl_sv_catpvf_mg\*(C'\fR |
| 22631 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 22632 |
.RS 4 |
| 22633 |
.Sp |
| 22634 |
.Vb 8 |
| 22635 |
\& void Perl_sv_catpvf (pTHX_ SV * const sv, |
| 22636 |
\& const char * const pat, ...) |
| 22637 |
\& void Perl_sv_catpvf_mg (pTHX_ SV * const sv, |
| 22638 |
\& const char * const pat, ...) |
| 22639 |
\& void sv_catpvf_mg_nocontext(SV * const sv, |
| 22640 |
\& const char * const pat, ...) |
| 22641 |
\& void sv_catpvf_nocontext (SV * const sv, |
| 22642 |
\& const char * const pat, ...) |
| 22643 |
.Ve |
| 22644 |
.RE |
| 22645 |
.RS 4 |
| 22646 |
.RE |
| 22647 |
.ie n .IP """sv_catpvn""" 4 |
| 22648 |
.el .IP \f(CWsv_catpvn\fR 4 |
| 22649 |
.IX Item "sv_catpvn" |
| 22650 |
.PD 0 |
| 22651 |
.ie n .IP """sv_catpvn_flags""" 4 |
| 22652 |
.el .IP \f(CWsv_catpvn_flags\fR 4 |
| 22653 |
.IX Item "sv_catpvn_flags" |
| 22654 |
.ie n .IP """sv_catpvn_mg""" 4 |
| 22655 |
.el .IP \f(CWsv_catpvn_mg\fR 4 |
| 22656 |
.IX Item "sv_catpvn_mg" |
| 22657 |
.ie n .IP """sv_catpvn_nomg""" 4 |
| 22658 |
.el .IP \f(CWsv_catpvn_nomg\fR 4 |
| 22659 |
.IX Xref "sv_catpvn sv_catpvn_flags sv_catpvn_mg sv_catpvn_nomg" |
| 22660 |
.IX Item "sv_catpvn_nomg" |
| 22661 |
.PD |
| 22662 |
These concatenate the \f(CW\*(C`len\*(C'\fR bytes of the string beginning at \f(CW\*(C`ptr\*(C'\fR onto the |
| 22663 |
end of the string which is in \f(CW\*(C`dsv\*(C'\fR. The caller must make sure \f(CW\*(C`ptr\*(C'\fR |
| 22664 |
contains at least \f(CW\*(C`len\*(C'\fR bytes. |
| 22665 |
.Sp |
| 22666 |
For all but \f(CW\*(C`sv_catpvn_flags\*(C'\fR, the string appended is assumed to be valid |
| 22667 |
UTF\-8 if the SV has the UTF\-8 status set, and a string of bytes otherwise. |
| 22668 |
.Sp |
| 22669 |
They differ in that: |
| 22670 |
.Sp |
| 22671 |
\&\f(CW\*(C`sv_catpvn_mg\*(C'\fR performs both 'get' and 'set' magic on \f(CW\*(C`dsv\*(C'\fR. |
| 22672 |
.Sp |
| 22673 |
\&\f(CW\*(C`sv_catpvn\*(C'\fR performs only 'get' magic. |
| 22674 |
.Sp |
| 22675 |
\&\f(CW\*(C`sv_catpvn_nomg\*(C'\fR skips all magic. |
| 22676 |
.Sp |
| 22677 |
\&\f(CW\*(C`sv_catpvn_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify |
| 22678 |
any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR) and |
| 22679 |
to also override the UTF\-8 handling. By supplying the \f(CW\*(C`SV_CATBYTES\*(C'\fR flag, the |
| 22680 |
appended string is interpreted as plain bytes; by supplying instead the |
| 22681 |
\&\f(CW\*(C`SV_CATUTF8\*(C'\fR flag, it will be interpreted as UTF\-8, and the \f(CW\*(C`dsv\*(C'\fR will be |
| 22682 |
upgraded to UTF\-8 if necessary. |
| 22683 |
.Sp |
| 22684 |
\&\f(CW\*(C`sv_catpvn\*(C'\fR, \f(CW\*(C`sv_catpvn_mg\*(C'\fR, and \f(CW\*(C`sv_catpvn_nomg\*(C'\fR are implemented |
| 22685 |
in terms of \f(CW\*(C`sv_catpvn_flags\*(C'\fR. |
| 22686 |
.RS 4 |
| 22687 |
.Sp |
| 22688 |
.Vb 5 |
| 22689 |
\& void sv_catpvn (SV *dsv, const char *sstr, STRLEN len) |
| 22690 |
\& void sv_catpvn_flags(SV * const dsv, const char *sstr, |
| 22691 |
\& const STRLEN len, const I32 flags) |
| 22692 |
\& void sv_catpvn_mg (SV *dsv, const char *sstr, STRLEN len) |
| 22693 |
\& void sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len) |
| 22694 |
.Ve |
| 22695 |
.RE |
| 22696 |
.RS 4 |
| 22697 |
.RE |
| 22698 |
.ie n .IP """sv_catpvs""" 4 |
| 22699 |
.el .IP \f(CWsv_catpvs\fR 4 |
| 22700 |
.IX Xref "sv_catpvs" |
| 22701 |
.IX Item "sv_catpvs" |
| 22702 |
Like \f(CW\*(C`sv_catpvn\*(C'\fR, but takes a literal string instead of a |
| 22703 |
string/length pair. |
| 22704 |
.RS 4 |
| 22705 |
.Sp |
| 22706 |
.Vb 1 |
| 22707 |
\& void sv_catpvs(SV* sv, "literal string") |
| 22708 |
.Ve |
| 22709 |
.RE |
| 22710 |
.RS 4 |
| 22711 |
.RE |
| 22712 |
.ie n .IP """sv_catpvs_flags""" 4 |
| 22713 |
.el .IP \f(CWsv_catpvs_flags\fR 4 |
| 22714 |
.IX Xref "sv_catpvs_flags" |
| 22715 |
.IX Item "sv_catpvs_flags" |
| 22716 |
Like \f(CW\*(C`sv_catpvn_flags\*(C'\fR, but takes a literal string instead |
| 22717 |
of a string/length pair. |
| 22718 |
.RS 4 |
| 22719 |
.Sp |
| 22720 |
.Vb 1 |
| 22721 |
\& void sv_catpvs_flags(SV* sv, "literal string", I32 flags) |
| 22722 |
.Ve |
| 22723 |
.RE |
| 22724 |
.RS 4 |
| 22725 |
.RE |
| 22726 |
.ie n .IP """sv_catpvs_mg""" 4 |
| 22727 |
.el .IP \f(CWsv_catpvs_mg\fR 4 |
| 22728 |
.IX Xref "sv_catpvs_mg" |
| 22729 |
.IX Item "sv_catpvs_mg" |
| 22730 |
Like \f(CW\*(C`sv_catpvn_mg\*(C'\fR, but takes a literal string instead of a |
| 22731 |
string/length pair. |
| 22732 |
.RS 4 |
| 22733 |
.Sp |
| 22734 |
.Vb 1 |
| 22735 |
\& void sv_catpvs_mg(SV* sv, "literal string") |
| 22736 |
.Ve |
| 22737 |
.RE |
| 22738 |
.RS 4 |
| 22739 |
.RE |
| 22740 |
.ie n .IP """sv_catpvs_nomg""" 4 |
| 22741 |
.el .IP \f(CWsv_catpvs_nomg\fR 4 |
| 22742 |
.IX Xref "sv_catpvs_nomg" |
| 22743 |
.IX Item "sv_catpvs_nomg" |
| 22744 |
Like \f(CW\*(C`sv_catpvn_nomg\*(C'\fR, but takes a literal string instead of |
| 22745 |
a string/length pair. |
| 22746 |
.RS 4 |
| 22747 |
.Sp |
| 22748 |
.Vb 1 |
| 22749 |
\& void sv_catpvs_nomg(SV* sv, "literal string") |
| 22750 |
.Ve |
| 22751 |
.RE |
| 22752 |
.RS 4 |
| 22753 |
.RE |
| 22754 |
.ie n .IP """sv_catsv""" 4 |
| 22755 |
.el .IP \f(CWsv_catsv\fR 4 |
| 22756 |
.IX Item "sv_catsv" |
| 22757 |
.PD 0 |
| 22758 |
.ie n .IP """sv_catsv_flags""" 4 |
| 22759 |
.el .IP \f(CWsv_catsv_flags\fR 4 |
| 22760 |
.IX Item "sv_catsv_flags" |
| 22761 |
.ie n .IP """sv_catsv_mg""" 4 |
| 22762 |
.el .IP \f(CWsv_catsv_mg\fR 4 |
| 22763 |
.IX Item "sv_catsv_mg" |
| 22764 |
.ie n .IP """sv_catsv_nomg""" 4 |
| 22765 |
.el .IP \f(CWsv_catsv_nomg\fR 4 |
| 22766 |
.IX Xref "sv_catsv sv_catsv_flags sv_catsv_mg sv_catsv_nomg" |
| 22767 |
.IX Item "sv_catsv_nomg" |
| 22768 |
.PD |
| 22769 |
These concatenate the string from SV \f(CW\*(C`sstr\*(C'\fR onto the end of the string in SV |
| 22770 |
\&\f(CW\*(C`dsv\*(C'\fR. If \f(CW\*(C`sstr\*(C'\fR is null, these are no-ops; otherwise only \f(CW\*(C`dsv\*(C'\fR is |
| 22771 |
modified. |
| 22772 |
.Sp |
| 22773 |
They differ only in what magic they perform: |
| 22774 |
.Sp |
| 22775 |
\&\f(CW\*(C`sv_catsv_mg\*(C'\fR performs 'get' magic on both SVs before the copy, and 'set' magic |
| 22776 |
on \f(CW\*(C`dsv\*(C'\fR afterwards. |
| 22777 |
.Sp |
| 22778 |
\&\f(CW\*(C`sv_catsv\*(C'\fR performs just 'get' magic, on both SVs. |
| 22779 |
.Sp |
| 22780 |
\&\f(CW\*(C`sv_catsv_nomg\*(C'\fR skips all magic. |
| 22781 |
.Sp |
| 22782 |
\&\f(CW\*(C`sv_catsv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to use |
| 22783 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR to specify any combination of magic handling |
| 22784 |
(although either both or neither SV will have 'get' magic applied to it.) |
| 22785 |
.Sp |
| 22786 |
\&\f(CW\*(C`sv_catsv\*(C'\fR, \f(CW\*(C`sv_catsv_mg\*(C'\fR, and \f(CW\*(C`sv_catsv_nomg\*(C'\fR are implemented |
| 22787 |
in terms of \f(CW\*(C`sv_catsv_flags\*(C'\fR. |
| 22788 |
.RS 4 |
| 22789 |
.Sp |
| 22790 |
.Vb 5 |
| 22791 |
\& void sv_catsv (SV *dsv, SV *sstr) |
| 22792 |
\& void sv_catsv_flags(SV * const dsv, SV * const sstr, |
| 22793 |
\& const I32 flags) |
| 22794 |
\& void sv_catsv_mg (SV *dsv, SV *sstr) |
| 22795 |
\& void sv_catsv_nomg (SV *dsv, SV *sstr) |
| 22796 |
.Ve |
| 22797 |
.RE |
| 22798 |
.RS 4 |
| 22799 |
.RE |
| 22800 |
.ie n .IP """SV_CHECK_THINKFIRST""" 4 |
| 22801 |
.el .IP \f(CWSV_CHECK_THINKFIRST\fR 4 |
| 22802 |
.IX Xref "SV_CHECK_THINKFIRST" |
| 22803 |
.IX Item "SV_CHECK_THINKFIRST" |
| 22804 |
Remove any encumbrances from \f(CW\*(C`sv\*(C'\fR, that need to be taken care of before it |
| 22805 |
is modifiable. For example if it is Copy on Write (COW), now is the time to |
| 22806 |
make that copy. |
| 22807 |
.Sp |
| 22808 |
If you know that you are about to change the PV value of \f(CW\*(C`sv\*(C'\fR, instead use |
| 22809 |
"\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" to avoid the write that would be |
| 22810 |
immediately written again. |
| 22811 |
.RS 4 |
| 22812 |
.Sp |
| 22813 |
.Vb 1 |
| 22814 |
\& void SV_CHECK_THINKFIRST(SV * sv) |
| 22815 |
.Ve |
| 22816 |
.RE |
| 22817 |
.RS 4 |
| 22818 |
.RE |
| 22819 |
.ie n .IP """SV_CHECK_THINKFIRST_COW_DROP""" 4 |
| 22820 |
.el .IP \f(CWSV_CHECK_THINKFIRST_COW_DROP\fR 4 |
| 22821 |
.IX Xref "SV_CHECK_THINKFIRST_COW_DROP" |
| 22822 |
.IX Item "SV_CHECK_THINKFIRST_COW_DROP" |
| 22823 |
Call this when you are about to replace the PV value in \f(CW\*(C`sv\*(C'\fR, which is |
| 22824 |
potentially copy-on-write. It stops any sharing with other SVs, so that no |
| 22825 |
Copy on Write (COW) actually happens. This COW would be useless, as it would |
| 22826 |
immediately get changed to something else. This function also removes any |
| 22827 |
other encumbrances that would be problematic when changing \f(CW\*(C`sv\*(C'\fR. |
| 22828 |
.RS 4 |
| 22829 |
.Sp |
| 22830 |
.Vb 1 |
| 22831 |
\& void SV_CHECK_THINKFIRST_COW_DROP(SV * sv) |
| 22832 |
.Ve |
| 22833 |
.RE |
| 22834 |
.RS 4 |
| 22835 |
.RE |
| 22836 |
.ie n .IP """sv_chop""" 4 |
| 22837 |
.el .IP \f(CWsv_chop\fR 4 |
| 22838 |
.IX Xref "sv_chop" |
| 22839 |
.IX Item "sv_chop" |
| 22840 |
Efficient removal of characters from the beginning of the string buffer. |
| 22841 |
\&\f(CWSvPOK(sv)\fR, or at least \f(CWSvPOKp(sv)\fR, must be true and \f(CW\*(C`ptr\*(C'\fR must be a |
| 22842 |
pointer to somewhere inside the string buffer. \f(CW\*(C`ptr\*(C'\fR becomes the first |
| 22843 |
character of the adjusted string. Uses the \f(CW\*(C`OOK\*(C'\fR hack. On return, only |
| 22844 |
\&\f(CWSvPOK(sv)\fR and \f(CWSvPOKp(sv)\fR among the \f(CW\*(C`OK\*(C'\fR flags will be true. |
| 22845 |
.Sp |
| 22846 |
Beware: after this function returns, \f(CW\*(C`ptr\*(C'\fR and SvPVX_const(sv) may no longer |
| 22847 |
refer to the same chunk of data. |
| 22848 |
.Sp |
| 22849 |
The unfortunate similarity of this function's name to that of Perl's \f(CW\*(C`chop\*(C'\fR |
| 22850 |
operator is strictly coincidental. This function works from the left; |
| 22851 |
\&\f(CW\*(C`chop\*(C'\fR works from the right. |
| 22852 |
.RS 4 |
| 22853 |
.Sp |
| 22854 |
.Vb 1 |
| 22855 |
\& void sv_chop(SV * const sv, const char * const ptr) |
| 22856 |
.Ve |
| 22857 |
.RE |
| 22858 |
.RS 4 |
| 22859 |
.RE |
| 22860 |
.ie n .IP """sv_clear""" 4 |
| 22861 |
.el .IP \f(CWsv_clear\fR 4 |
| 22862 |
.IX Xref "sv_clear" |
| 22863 |
.IX Item "sv_clear" |
| 22864 |
Clear an SV: call any destructors, free up any memory used by the body, |
| 22865 |
and free the body itself. The SV's head is \fInot\fR freed, although |
| 22866 |
its type is set to all 1's so that it won't inadvertently be assumed |
| 22867 |
to be live during global destruction etc. |
| 22868 |
This function should only be called when \f(CW\*(C`REFCNT\*(C'\fR is zero. Most of the time |
| 22869 |
you'll want to call \f(CW\*(C`SvREFCNT_dec\*(C'\fR instead. |
| 22870 |
.RS 4 |
| 22871 |
.Sp |
| 22872 |
.Vb 1 |
| 22873 |
\& void sv_clear(SV * const orig_sv) |
| 22874 |
.Ve |
| 22875 |
.RE |
| 22876 |
.RS 4 |
| 22877 |
.RE |
| 22878 |
.ie n .IP """sv_cmp""" 4 |
| 22879 |
.el .IP \f(CWsv_cmp\fR 4 |
| 22880 |
.IX Xref "sv_cmp" |
| 22881 |
.IX Item "sv_cmp" |
| 22882 |
Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the |
| 22883 |
string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in |
| 22884 |
\&\f(CW\*(C`sv2\*(C'\fR. Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will |
| 22885 |
coerce its args to strings if necessary. See also \f(CW"sv_cmp_locale"\fR. |
| 22886 |
.RS 4 |
| 22887 |
.Sp |
| 22888 |
.Vb 1 |
| 22889 |
\& I32 sv_cmp(SV * const sv1, SV * const sv2) |
| 22890 |
.Ve |
| 22891 |
.RE |
| 22892 |
.RS 4 |
| 22893 |
.RE |
| 22894 |
.ie n .IP """sv_cmp_flags""" 4 |
| 22895 |
.el .IP \f(CWsv_cmp_flags\fR 4 |
| 22896 |
.IX Xref "sv_cmp_flags" |
| 22897 |
.IX Item "sv_cmp_flags" |
| 22898 |
Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the |
| 22899 |
string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in |
| 22900 |
\&\f(CW\*(C`sv2\*(C'\fR. Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings |
| 22901 |
if necessary. If the flags has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles get magic. See |
| 22902 |
also \f(CW"sv_cmp_locale_flags"\fR. |
| 22903 |
.RS 4 |
| 22904 |
.Sp |
| 22905 |
.Vb 1 |
| 22906 |
\& I32 sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags) |
| 22907 |
.Ve |
| 22908 |
.RE |
| 22909 |
.RS 4 |
| 22910 |
.RE |
| 22911 |
.ie n .IP """sv_cmp_locale""" 4 |
| 22912 |
.el .IP \f(CWsv_cmp_locale\fR 4 |
| 22913 |
.IX Xref "sv_cmp_locale" |
| 22914 |
.IX Item "sv_cmp_locale" |
| 22915 |
Compares the strings in two SVs in a locale-aware manner. Is UTF\-8 and |
| 22916 |
\&\f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will coerce its args to strings |
| 22917 |
if necessary. See also \f(CW"sv_cmp"\fR. |
| 22918 |
.RS 4 |
| 22919 |
.Sp |
| 22920 |
.Vb 1 |
| 22921 |
\& I32 sv_cmp_locale(SV * const sv1, SV * const sv2) |
| 22922 |
.Ve |
| 22923 |
.RE |
| 22924 |
.RS 4 |
| 22925 |
.RE |
| 22926 |
.ie n .IP """sv_cmp_locale_flags""" 4 |
| 22927 |
.el .IP \f(CWsv_cmp_locale_flags\fR 4 |
| 22928 |
.IX Xref "sv_cmp_locale_flags" |
| 22929 |
.IX Item "sv_cmp_locale_flags" |
| 22930 |
Compares the strings in two SVs in a locale-aware manner. Is UTF\-8 and |
| 22931 |
\&\f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings if necessary. If |
| 22932 |
the flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get magic. See also |
| 22933 |
\&\f(CW"sv_cmp_flags"\fR. |
| 22934 |
.RS 4 |
| 22935 |
.Sp |
| 22936 |
.Vb 2 |
| 22937 |
\& I32 sv_cmp_locale_flags(SV * const sv1, SV * const sv2, |
| 22938 |
\& const U32 flags) |
| 22939 |
.Ve |
| 22940 |
.RE |
| 22941 |
.RS 4 |
| 22942 |
.RE |
| 22943 |
.ie n .IP """sv_collxfrm""" 4 |
| 22944 |
.el .IP \f(CWsv_collxfrm\fR 4 |
| 22945 |
.IX Xref "sv_collxfrm" |
| 22946 |
.IX Item "sv_collxfrm" |
| 22947 |
This calls \f(CW\*(C`sv_collxfrm_flags\*(C'\fR with the SV_GMAGIC flag. See |
| 22948 |
\&\f(CW"sv_collxfrm_flags"\fR. |
| 22949 |
.RS 4 |
| 22950 |
.Sp |
| 22951 |
.Vb 1 |
| 22952 |
\& char * sv_collxfrm(SV * const sv, STRLEN * const nxp) |
| 22953 |
.Ve |
| 22954 |
.RE |
| 22955 |
.RS 4 |
| 22956 |
.RE |
| 22957 |
.ie n .IP """sv_collxfrm_flags""" 4 |
| 22958 |
.el .IP \f(CWsv_collxfrm_flags\fR 4 |
| 22959 |
.IX Xref "sv_collxfrm_flags" |
| 22960 |
.IX Item "sv_collxfrm_flags" |
| 22961 |
Add Collate Transform magic to an SV if it doesn't already have it. If the |
| 22962 |
flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get-magic. |
| 22963 |
.Sp |
| 22964 |
Any scalar variable may carry \f(CW\*(C`PERL_MAGIC_collxfrm\*(C'\fR magic that contains the |
| 22965 |
scalar data of the variable, but transformed to such a format that a normal |
| 22966 |
memory comparison can be used to compare the data according to the locale |
| 22967 |
settings. |
| 22968 |
.RS 4 |
| 22969 |
.Sp |
| 22970 |
.Vb 2 |
| 22971 |
\& char * sv_collxfrm_flags(SV * const sv, STRLEN * const nxp, |
| 22972 |
\& I32 const flags) |
| 22973 |
.Ve |
| 22974 |
.RE |
| 22975 |
.RS 4 |
| 22976 |
.RE |
| 22977 |
.ie n .IP """sv_copypv""" 4 |
| 22978 |
.el .IP \f(CWsv_copypv\fR 4 |
| 22979 |
.IX Item "sv_copypv" |
| 22980 |
.PD 0 |
| 22981 |
.ie n .IP """sv_copypv_flags""" 4 |
| 22982 |
.el .IP \f(CWsv_copypv_flags\fR 4 |
| 22983 |
.IX Item "sv_copypv_flags" |
| 22984 |
.ie n .IP """sv_copypv_nomg""" 4 |
| 22985 |
.el .IP \f(CWsv_copypv_nomg\fR 4 |
| 22986 |
.IX Xref "sv_copypv sv_copypv_flags sv_copypv_nomg" |
| 22987 |
.IX Item "sv_copypv_nomg" |
| 22988 |
.PD |
| 22989 |
These copy a stringified representation of the source SV into the |
| 22990 |
destination SV. They automatically perform coercion of numeric values into |
| 22991 |
strings. Guaranteed to preserve the \f(CW\*(C`UTF8\*(C'\fR flag even from overloaded objects. |
| 22992 |
Similar in nature to \f(CW\*(C`sv_2pv[_flags]\*(C'\fR but they operate directly on an SV |
| 22993 |
instead of just the string. Mostly they use "\f(CW\*(C`sv_2pv_flags\*(C'\fR" to |
| 22994 |
do the work, except when that would lose the UTF\-8'ness of the PV. |
| 22995 |
.Sp |
| 22996 |
The three forms differ only in whether or not they perform 'get magic' on |
| 22997 |
\&\f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_copypv_nomg\*(C'\fR skips 'get magic'; \f(CW\*(C`sv_copypv\*(C'\fR performs it; and |
| 22998 |
\&\f(CW\*(C`sv_copypv_flags\*(C'\fR either performs it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set in |
| 22999 |
\&\f(CW\*(C`flags\*(C'\fR) or doesn't (if that bit is cleared). |
| 23000 |
.RS 4 |
| 23001 |
.Sp |
| 23002 |
.Vb 4 |
| 23003 |
\& void sv_copypv (SV * const dsv, SV * const ssv) |
| 23004 |
\& void sv_copypv_flags(SV * const dsv, SV * const ssv, |
| 23005 |
\& const I32 flags) |
| 23006 |
\& void sv_copypv_nomg (SV * const dsv, SV * const ssv) |
| 23007 |
.Ve |
| 23008 |
.RE |
| 23009 |
.RS 4 |
| 23010 |
.RE |
| 23011 |
.ie n .IP """SvCUR""" 4 |
| 23012 |
.el .IP \f(CWSvCUR\fR 4 |
| 23013 |
.IX Xref "SvCUR" |
| 23014 |
.IX Item "SvCUR" |
| 23015 |
Returns the length, in bytes, of the PV inside the SV. |
| 23016 |
Note that this may not match Perl's \f(CW\*(C`length\*(C'\fR; for that, use |
| 23017 |
\&\f(CWsv_len_utf8(sv)\fR. See \f(CW"SvLEN"\fR also. |
| 23018 |
.RS 4 |
| 23019 |
.Sp |
| 23020 |
.Vb 1 |
| 23021 |
\& STRLEN SvCUR(SV* sv) |
| 23022 |
.Ve |
| 23023 |
.RE |
| 23024 |
.RS 4 |
| 23025 |
.RE |
| 23026 |
.ie n .IP """SvCUR_set""" 4 |
| 23027 |
.el .IP \f(CWSvCUR_set\fR 4 |
| 23028 |
.IX Xref "SvCUR_set" |
| 23029 |
.IX Item "SvCUR_set" |
| 23030 |
Sets the current length, in bytes, of the C string which is in the SV. |
| 23031 |
See \f(CW"SvCUR"\fR and \f(CW\*(C`SvIV_set\*(C'\fR>. |
| 23032 |
.RS 4 |
| 23033 |
.Sp |
| 23034 |
.Vb 1 |
| 23035 |
\& void SvCUR_set(SV* sv, STRLEN len) |
| 23036 |
.Ve |
| 23037 |
.RE |
| 23038 |
.RS 4 |
| 23039 |
.RE |
| 23040 |
.ie n .IP """sv_2cv""" 4 |
| 23041 |
.el .IP \f(CWsv_2cv\fR 4 |
| 23042 |
.IX Xref "sv_2cv" |
| 23043 |
.IX Item "sv_2cv" |
| 23044 |
Using various gambits, try to get a CV from an SV; in addition, try if |
| 23045 |
possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and GV associated with it. |
| 23046 |
The flags in \f(CW\*(C`lref\*(C'\fR are passed to \f(CW\*(C`gv_fetchsv\*(C'\fR. |
| 23047 |
.RS 4 |
| 23048 |
.Sp |
| 23049 |
.Vb 2 |
| 23050 |
\& CV * sv_2cv(SV *sv, HV ** const st, GV ** const gvp, |
| 23051 |
\& const I32 lref) |
| 23052 |
.Ve |
| 23053 |
.RE |
| 23054 |
.RS 4 |
| 23055 |
.RE |
| 23056 |
.ie n .IP """sv_dec""" 4 |
| 23057 |
.el .IP \f(CWsv_dec\fR 4 |
| 23058 |
.IX Item "sv_dec" |
| 23059 |
.PD 0 |
| 23060 |
.ie n .IP """sv_dec_nomg""" 4 |
| 23061 |
.el .IP \f(CWsv_dec_nomg\fR 4 |
| 23062 |
.IX Xref "sv_dec sv_dec_nomg" |
| 23063 |
.IX Item "sv_dec_nomg" |
| 23064 |
.PD |
| 23065 |
These auto-decrement the value in the SV, doing string to numeric conversion |
| 23066 |
if necessary. They both handle operator overloading. |
| 23067 |
.Sp |
| 23068 |
They differ only in that: |
| 23069 |
.Sp |
| 23070 |
\&\f(CW\*(C`sv_dec\*(C'\fR handles 'get' magic; \f(CW\*(C`sv_dec_nomg\*(C'\fR skips 'get' magic. |
| 23071 |
.RS 4 |
| 23072 |
.Sp |
| 23073 |
.Vb 1 |
| 23074 |
\& void sv_dec(SV * const sv) |
| 23075 |
.Ve |
| 23076 |
.RE |
| 23077 |
.RS 4 |
| 23078 |
.RE |
| 23079 |
.ie n .IP """sv_derived_from""" 4 |
| 23080 |
.el .IP \f(CWsv_derived_from\fR 4 |
| 23081 |
.IX Xref "sv_derived_from" |
| 23082 |
.IX Item "sv_derived_from" |
| 23083 |
Exactly like "sv_derived_from_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter. |
| 23084 |
.RS 4 |
| 23085 |
.Sp |
| 23086 |
.Vb 1 |
| 23087 |
\& bool sv_derived_from(SV *sv, const char * const name) |
| 23088 |
.Ve |
| 23089 |
.RE |
| 23090 |
.RS 4 |
| 23091 |
.RE |
| 23092 |
.ie n .IP """sv_derived_from_hv""" 4 |
| 23093 |
.el .IP \f(CWsv_derived_from_hv\fR 4 |
| 23094 |
.IX Xref "sv_derived_from_hv" |
| 23095 |
.IX Item "sv_derived_from_hv" |
| 23096 |
Exactly like "sv_derived_from_pvn", but takes the name string as the |
| 23097 |
\&\f(CW\*(C`HvNAME\*(C'\fR of the given HV (which would presumably represent a stash). |
| 23098 |
.RS 4 |
| 23099 |
.Sp |
| 23100 |
.Vb 1 |
| 23101 |
\& bool sv_derived_from_hv(SV *sv, HV *hv) |
| 23102 |
.Ve |
| 23103 |
.RE |
| 23104 |
.RS 4 |
| 23105 |
.RE |
| 23106 |
.ie n .IP """sv_derived_from_pv""" 4 |
| 23107 |
.el .IP \f(CWsv_derived_from_pv\fR 4 |
| 23108 |
.IX Xref "sv_derived_from_pv" |
| 23109 |
.IX Item "sv_derived_from_pv" |
| 23110 |
Exactly like "sv_derived_from_pvn", but takes a nul-terminated string |
| 23111 |
instead of a string/length pair. |
| 23112 |
.RS 4 |
| 23113 |
.Sp |
| 23114 |
.Vb 2 |
| 23115 |
\& bool sv_derived_from_pv(SV *sv, const char * const name, |
| 23116 |
\& U32 flags) |
| 23117 |
.Ve |
| 23118 |
.RE |
| 23119 |
.RS 4 |
| 23120 |
.RE |
| 23121 |
.ie n .IP """sv_derived_from_pvn""" 4 |
| 23122 |
.el .IP \f(CWsv_derived_from_pvn\fR 4 |
| 23123 |
.IX Xref "sv_derived_from_pvn" |
| 23124 |
.IX Item "sv_derived_from_pvn" |
| 23125 |
Returns a boolean indicating whether the SV is derived from the specified class |
| 23126 |
\&\fIat the C level\fR. To check derivation at the Perl level, call \f(CWisa()\fR as a |
| 23127 |
normal Perl method. |
| 23128 |
.Sp |
| 23129 |
Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is SVf_UTF8. |
| 23130 |
.RS 4 |
| 23131 |
.Sp |
| 23132 |
.Vb 2 |
| 23133 |
\& bool sv_derived_from_pvn(SV *sv, const char * const name, |
| 23134 |
\& const STRLEN len, U32 flags) |
| 23135 |
.Ve |
| 23136 |
.RE |
| 23137 |
.RS 4 |
| 23138 |
.RE |
| 23139 |
.ie n .IP """sv_derived_from_sv""" 4 |
| 23140 |
.el .IP \f(CWsv_derived_from_sv\fR 4 |
| 23141 |
.IX Xref "sv_derived_from_sv" |
| 23142 |
.IX Item "sv_derived_from_sv" |
| 23143 |
Exactly like "sv_derived_from_pvn", but takes the name string in the form |
| 23144 |
of an SV instead of a string/length pair. This is the advised form. |
| 23145 |
.RS 4 |
| 23146 |
.Sp |
| 23147 |
.Vb 1 |
| 23148 |
\& bool sv_derived_from_sv(SV *sv, SV *namesv, U32 flags) |
| 23149 |
.Ve |
| 23150 |
.RE |
| 23151 |
.RS 4 |
| 23152 |
.RE |
| 23153 |
.ie n .IP """sv_does""" 4 |
| 23154 |
.el .IP \f(CWsv_does\fR 4 |
| 23155 |
.IX Xref "sv_does" |
| 23156 |
.IX Item "sv_does" |
| 23157 |
Like "sv_does_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter. |
| 23158 |
.RS 4 |
| 23159 |
.Sp |
| 23160 |
.Vb 1 |
| 23161 |
\& bool sv_does(SV *sv, const char * const name) |
| 23162 |
.Ve |
| 23163 |
.RE |
| 23164 |
.RS 4 |
| 23165 |
.RE |
| 23166 |
.ie n .IP """sv_does_pv""" 4 |
| 23167 |
.el .IP \f(CWsv_does_pv\fR 4 |
| 23168 |
.IX Xref "sv_does_pv" |
| 23169 |
.IX Item "sv_does_pv" |
| 23170 |
Like "sv_does_sv", but takes a nul-terminated string instead of an SV. |
| 23171 |
.RS 4 |
| 23172 |
.Sp |
| 23173 |
.Vb 1 |
| 23174 |
\& bool sv_does_pv(SV *sv, const char * const name, U32 flags) |
| 23175 |
.Ve |
| 23176 |
.RE |
| 23177 |
.RS 4 |
| 23178 |
.RE |
| 23179 |
.ie n .IP """sv_does_pvn""" 4 |
| 23180 |
.el .IP \f(CWsv_does_pvn\fR 4 |
| 23181 |
.IX Xref "sv_does_pvn" |
| 23182 |
.IX Item "sv_does_pvn" |
| 23183 |
Like "sv_does_sv", but takes a string/length pair instead of an SV. |
| 23184 |
.RS 4 |
| 23185 |
.Sp |
| 23186 |
.Vb 2 |
| 23187 |
\& bool sv_does_pvn(SV *sv, const char * const name, |
| 23188 |
\& const STRLEN len, U32 flags) |
| 23189 |
.Ve |
| 23190 |
.RE |
| 23191 |
.RS 4 |
| 23192 |
.RE |
| 23193 |
.ie n .IP """sv_does_sv""" 4 |
| 23194 |
.el .IP \f(CWsv_does_sv\fR 4 |
| 23195 |
.IX Xref "sv_does_sv" |
| 23196 |
.IX Item "sv_does_sv" |
| 23197 |
Returns a boolean indicating whether the SV performs a specific, named role. |
| 23198 |
The SV can be a Perl object or the name of a Perl class. |
| 23199 |
.RS 4 |
| 23200 |
.Sp |
| 23201 |
.Vb 1 |
| 23202 |
\& bool sv_does_sv(SV *sv, SV *namesv, U32 flags) |
| 23203 |
.Ve |
| 23204 |
.RE |
| 23205 |
.RS 4 |
| 23206 |
.RE |
| 23207 |
.ie n .IP """SvEND""" 4 |
| 23208 |
.el .IP \f(CWSvEND\fR 4 |
| 23209 |
.IX Xref "SvEND" |
| 23210 |
.IX Item "SvEND" |
| 23211 |
Returns a pointer to the spot just after the last character in |
| 23212 |
the string which is in the SV, where there is usually a trailing |
| 23213 |
\&\f(CW\*(C`NUL\*(C'\fR character (even though Perl scalars do not strictly require it). |
| 23214 |
See \f(CW"SvCUR"\fR. Access the character as \f(CW\*(C`*(SvEND(sv))\*(C'\fR. |
| 23215 |
.Sp |
| 23216 |
Warning: If \f(CW\*(C`SvCUR\*(C'\fR is equal to \f(CW\*(C`SvLEN\*(C'\fR, then \f(CW\*(C`SvEND\*(C'\fR points to |
| 23217 |
unallocated memory. |
| 23218 |
.RS 4 |
| 23219 |
.Sp |
| 23220 |
.Vb 1 |
| 23221 |
\& char* SvEND(SV* sv) |
| 23222 |
.Ve |
| 23223 |
.RE |
| 23224 |
.RS 4 |
| 23225 |
.RE |
| 23226 |
.ie n .IP """sv_eq""" 4 |
| 23227 |
.el .IP \f(CWsv_eq\fR 4 |
| 23228 |
.IX Item "sv_eq" |
| 23229 |
.PD 0 |
| 23230 |
.ie n .IP """sv_eq_flags""" 4 |
| 23231 |
.el .IP \f(CWsv_eq_flags\fR 4 |
| 23232 |
.IX Xref "sv_eq sv_eq_flags" |
| 23233 |
.IX Item "sv_eq_flags" |
| 23234 |
.PD |
| 23235 |
These each return a boolean indicating whether or not the strings in the two |
| 23236 |
SVs are equal. If \f(CW\*(Aquse\ bytes\*(Aq\fR is in effect, the comparison is |
| 23237 |
byte-by-byte; otherwise character-by-character. Each will coerce its args to |
| 23238 |
strings if necessary. |
| 23239 |
.Sp |
| 23240 |
They differ only in that \f(CW\*(C`sv_eq\*(C'\fR always processes get magic, while |
| 23241 |
\&\f(CW\*(C`sv_eq_flags\*(C'\fR processes get magic only when the \f(CW\*(C`flags\*(C'\fR parameter has the |
| 23242 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR bit set. |
| 23243 |
.Sp |
| 23244 |
These functions do not handle operator overloading. For versions that do, |
| 23245 |
see instead \f(CW"sv_streq"\fR or \f(CW"sv_streq_flags"\fR. |
| 23246 |
.RS 4 |
| 23247 |
.Sp |
| 23248 |
.Vb 2 |
| 23249 |
\& I32 sv_eq (SV *sv1, SV *sv2) |
| 23250 |
\& I32 sv_eq_flags(SV *sv1, SV *sv2, const U32 flags) |
| 23251 |
.Ve |
| 23252 |
.RE |
| 23253 |
.RS 4 |
| 23254 |
.RE |
| 23255 |
.ie n .IP """sv_force_normal""" 4 |
| 23256 |
.el .IP \f(CWsv_force_normal\fR 4 |
| 23257 |
.IX Xref "sv_force_normal" |
| 23258 |
.IX Item "sv_force_normal" |
| 23259 |
Undo various types of fakery on an SV: if the PV is a shared string, make |
| 23260 |
a private copy; if we're a ref, stop refing; if we're a glob, downgrade to |
| 23261 |
an \f(CW\*(C`xpvmg\*(C'\fR. See also \f(CW"sv_force_normal_flags"\fR. |
| 23262 |
.RS 4 |
| 23263 |
.Sp |
| 23264 |
.Vb 1 |
| 23265 |
\& void sv_force_normal(SV *sv) |
| 23266 |
.Ve |
| 23267 |
.RE |
| 23268 |
.RS 4 |
| 23269 |
.RE |
| 23270 |
.ie n .IP """sv_force_normal_flags""" 4 |
| 23271 |
.el .IP \f(CWsv_force_normal_flags\fR 4 |
| 23272 |
.IX Xref "sv_force_normal_flags" |
| 23273 |
.IX Item "sv_force_normal_flags" |
| 23274 |
Undo various types of fakery on an SV, where fakery means |
| 23275 |
"more than" a string: if the PV is a shared string, make |
| 23276 |
a private copy; if we're a ref, stop refing; if we're a glob, downgrade to |
| 23277 |
an \f(CW\*(C`xpvmg\*(C'\fR; if we're a copy-on-write scalar, this is the on-write time when |
| 23278 |
we do the copy, and is also used locally; if this is a |
| 23279 |
vstring, drop the vstring magic. If \f(CW\*(C`SV_COW_DROP_PV\*(C'\fR is set |
| 23280 |
then a copy-on-write scalar drops its PV buffer (if any) and becomes |
| 23281 |
\&\f(CW\*(C`SvPOK_off\*(C'\fR rather than making a copy. (Used where this |
| 23282 |
scalar is about to be set to some other value.) In addition, |
| 23283 |
the \f(CW\*(C`flags\*(C'\fR parameter gets passed to \f(CWsv_unref_flags()\fR |
| 23284 |
when unreffing. \f(CW\*(C`sv_force_normal\*(C'\fR calls this function |
| 23285 |
with flags set to 0. |
| 23286 |
.Sp |
| 23287 |
This function is expected to be used to signal to perl that this SV is |
| 23288 |
about to be written to, and any extra book-keeping needs to be taken care |
| 23289 |
of. Hence, it croaks on read-only values. |
| 23290 |
.RS 4 |
| 23291 |
.Sp |
| 23292 |
.Vb 1 |
| 23293 |
\& void sv_force_normal_flags(SV * const sv, const U32 flags) |
| 23294 |
.Ve |
| 23295 |
.RE |
| 23296 |
.RS 4 |
| 23297 |
.RE |
| 23298 |
.ie n .IP """sv_free""" 4 |
| 23299 |
.el .IP \f(CWsv_free\fR 4 |
| 23300 |
.IX Xref "sv_free" |
| 23301 |
.IX Item "sv_free" |
| 23302 |
Decrement an SV's reference count, and if it drops to zero, call |
| 23303 |
\&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by |
| 23304 |
the body; finally, deallocating the SV's head itself. |
| 23305 |
Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR. |
| 23306 |
.RS 4 |
| 23307 |
.Sp |
| 23308 |
.Vb 1 |
| 23309 |
\& void sv_free(SV * const sv) |
| 23310 |
.Ve |
| 23311 |
.RE |
| 23312 |
.RS 4 |
| 23313 |
.RE |
| 23314 |
.ie n .IP """SvGAMAGIC""" 4 |
| 23315 |
.el .IP \f(CWSvGAMAGIC\fR 4 |
| 23316 |
.IX Xref "SvGAMAGIC" |
| 23317 |
.IX Item "SvGAMAGIC" |
| 23318 |
Returns true if the SV has get magic or |
| 23319 |
overloading. If either is true then |
| 23320 |
the scalar is active data, and has the potential to return a new value every |
| 23321 |
time it is accessed. Hence you must be careful to |
| 23322 |
only read it once per user logical operation and work |
| 23323 |
with that returned value. If neither is true then |
| 23324 |
the scalar's value cannot change unless written to. |
| 23325 |
.RS 4 |
| 23326 |
.Sp |
| 23327 |
.Vb 1 |
| 23328 |
\& U32 SvGAMAGIC(SV* sv) |
| 23329 |
.Ve |
| 23330 |
.RE |
| 23331 |
.RS 4 |
| 23332 |
.RE |
| 23333 |
.ie n .IP """sv_get_backrefs""" 4 |
| 23334 |
.el .IP \f(CWsv_get_backrefs\fR 4 |
| 23335 |
.IX Xref "sv_get_backrefs" |
| 23336 |
.IX Item "sv_get_backrefs" |
| 23337 |
NOTE: \f(CW\*(C`sv_get_backrefs\*(C'\fR is \fBexperimental\fR and may change or be |
| 23338 |
removed without notice. |
| 23339 |
.Sp |
| 23340 |
If \f(CW\*(C`sv\*(C'\fR is the target of a weak reference then it returns the back |
| 23341 |
references structure associated with the sv; otherwise return \f(CW\*(C`NULL\*(C'\fR. |
| 23342 |
.Sp |
| 23343 |
When returning a non-null result the type of the return is relevant. If it |
| 23344 |
is an AV then the elements of the AV are the weak reference RVs which |
| 23345 |
point at this item. If it is any other type then the item itself is the |
| 23346 |
weak reference. |
| 23347 |
.Sp |
| 23348 |
See also \f(CWPerl_sv_add_backref()\fR, \f(CWPerl_sv_del_backref()\fR, |
| 23349 |
\&\f(CWPerl_sv_kill_backrefs()\fR |
| 23350 |
.RS 4 |
| 23351 |
.Sp |
| 23352 |
.Vb 1 |
| 23353 |
\& SV * sv_get_backrefs(SV * const sv) |
| 23354 |
.Ve |
| 23355 |
.RE |
| 23356 |
.RS 4 |
| 23357 |
.RE |
| 23358 |
.ie n .IP """SvGETMAGIC""" 4 |
| 23359 |
.el .IP \f(CWSvGETMAGIC\fR 4 |
| 23360 |
.IX Xref "SvGETMAGIC" |
| 23361 |
.IX Item "SvGETMAGIC" |
| 23362 |
Invokes \f(CW"mg_get"\fR on an SV if it has 'get' magic. For example, this |
| 23363 |
will call \f(CW\*(C`FETCH\*(C'\fR on a tied variable. As of 5.37.1, this function is |
| 23364 |
guaranteed to evaluate its argument exactly once. |
| 23365 |
.RS 4 |
| 23366 |
.Sp |
| 23367 |
.Vb 1 |
| 23368 |
\& void SvGETMAGIC(SV *sv) |
| 23369 |
.Ve |
| 23370 |
.RE |
| 23371 |
.RS 4 |
| 23372 |
.RE |
| 23373 |
.ie n .IP """sv_gets""" 4 |
| 23374 |
.el .IP \f(CWsv_gets\fR 4 |
| 23375 |
.IX Xref "sv_gets" |
| 23376 |
.IX Item "sv_gets" |
| 23377 |
Get a line from the filehandle and store it into the SV, optionally |
| 23378 |
appending to the currently-stored string. If \f(CW\*(C`append\*(C'\fR is not 0, the |
| 23379 |
line is appended to the SV instead of overwriting it. \f(CW\*(C`append\*(C'\fR should |
| 23380 |
be set to the byte offset that the appended string should start at |
| 23381 |
in the SV (typically, \f(CWSvCUR(sv)\fR is a suitable choice). |
| 23382 |
.RS 4 |
| 23383 |
.Sp |
| 23384 |
.Vb 1 |
| 23385 |
\& char * sv_gets(SV * const sv, PerlIO * const fp, I32 append) |
| 23386 |
.Ve |
| 23387 |
.RE |
| 23388 |
.RS 4 |
| 23389 |
.RE |
| 23390 |
.ie n .IP """SvGROW""" 4 |
| 23391 |
.el .IP \f(CWSvGROW\fR 4 |
| 23392 |
.IX Xref "SvGROW" |
| 23393 |
.IX Item "SvGROW" |
| 23394 |
Expands the character buffer in the SV so that it has room for the |
| 23395 |
indicated number of bytes (remember to reserve space for an extra trailing |
| 23396 |
\&\f(CW\*(C`NUL\*(C'\fR character). Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary. |
| 23397 |
Returns a pointer to the character |
| 23398 |
buffer. SV must be of type >= \f(CW\*(C`SVt_PV\*(C'\fR. One |
| 23399 |
alternative is to call \f(CW\*(C`sv_grow\*(C'\fR if you are not sure of the type of SV. |
| 23400 |
.Sp |
| 23401 |
You might mistakenly think that \f(CW\*(C`len\*(C'\fR is the number of bytes to add to the |
| 23402 |
existing size, but instead it is the total size \f(CW\*(C`sv\*(C'\fR should be. |
| 23403 |
.RS 4 |
| 23404 |
.Sp |
| 23405 |
.Vb 1 |
| 23406 |
\& char * SvGROW(SV* sv, STRLEN len) |
| 23407 |
.Ve |
| 23408 |
.RE |
| 23409 |
.RS 4 |
| 23410 |
.RE |
| 23411 |
.ie n .IP """SvIandPOK""" 4 |
| 23412 |
.el .IP \f(CWSvIandPOK\fR 4 |
| 23413 |
.IX Xref "SvIandPOK" |
| 23414 |
.IX Item "SvIandPOK" |
| 23415 |
Returns a bool indicating whether the SV is both \f(CWSvPOK()\fR and |
| 23416 |
\&\f(CWSvIOK()\fR at the same time. Equivalent to \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR but |
| 23417 |
more efficient. |
| 23418 |
.RS 4 |
| 23419 |
.Sp |
| 23420 |
.Vb 1 |
| 23421 |
\& U32 SvIandPOK(SV* sv) |
| 23422 |
.Ve |
| 23423 |
.RE |
| 23424 |
.RS 4 |
| 23425 |
.RE |
| 23426 |
.ie n .IP """SvIandPOK_off""" 4 |
| 23427 |
.el .IP \f(CWSvIandPOK_off\fR 4 |
| 23428 |
.IX Xref "SvIandPOK_off" |
| 23429 |
.IX Item "SvIandPOK_off" |
| 23430 |
Unsets the PV and IV status of an SV in one operation. Equivalent to |
| 23431 |
\&\f(CW\*(C`SvIOK_off(sv); SvPK_off(v);\*(C'\fR but more efficient. |
| 23432 |
.RS 4 |
| 23433 |
.Sp |
| 23434 |
.Vb 1 |
| 23435 |
\& void SvIandPOK_off(SV* sv) |
| 23436 |
.Ve |
| 23437 |
.RE |
| 23438 |
.RS 4 |
| 23439 |
.RE |
| 23440 |
.ie n .IP """SvIandPOK_on""" 4 |
| 23441 |
.el .IP \f(CWSvIandPOK_on\fR 4 |
| 23442 |
.IX Xref "SvIandPOK_on" |
| 23443 |
.IX Item "SvIandPOK_on" |
| 23444 |
Tells an SV that is a string and a number in one operation. Equivalent |
| 23445 |
to \f(CW\*(C`SvIOK_on(sv); SvPOK_on(sv);\*(C'\fR but more efficient. |
| 23446 |
.RS 4 |
| 23447 |
.Sp |
| 23448 |
.Vb 1 |
| 23449 |
\& void SvIandPOK_on(SV* sv) |
| 23450 |
.Ve |
| 23451 |
.RE |
| 23452 |
.RS 4 |
| 23453 |
.RE |
| 23454 |
.ie n .IP """sv_inc""" 4 |
| 23455 |
.el .IP \f(CWsv_inc\fR 4 |
| 23456 |
.IX Item "sv_inc" |
| 23457 |
.PD 0 |
| 23458 |
.ie n .IP """sv_inc_nomg""" 4 |
| 23459 |
.el .IP \f(CWsv_inc_nomg\fR 4 |
| 23460 |
.IX Xref "sv_inc sv_inc_nomg" |
| 23461 |
.IX Item "sv_inc_nomg" |
| 23462 |
.PD |
| 23463 |
These auto-increment the value in the SV, doing string to numeric conversion |
| 23464 |
if necessary. They both handle operator overloading. |
| 23465 |
.Sp |
| 23466 |
They differ only in that \f(CW\*(C`sv_inc\*(C'\fR performs 'get' magic; \f(CW\*(C`sv_inc_nomg\*(C'\fR skips |
| 23467 |
any magic. |
| 23468 |
.RS 4 |
| 23469 |
.Sp |
| 23470 |
.Vb 1 |
| 23471 |
\& void sv_inc(SV * const sv) |
| 23472 |
.Ve |
| 23473 |
.RE |
| 23474 |
.RS 4 |
| 23475 |
.RE |
| 23476 |
.ie n .IP """sv_insert""" 4 |
| 23477 |
.el .IP \f(CWsv_insert\fR 4 |
| 23478 |
.IX Item "sv_insert" |
| 23479 |
.PD 0 |
| 23480 |
.ie n .IP """sv_insert_flags""" 4 |
| 23481 |
.el .IP \f(CWsv_insert_flags\fR 4 |
| 23482 |
.IX Xref "sv_insert sv_insert_flags" |
| 23483 |
.IX Item "sv_insert_flags" |
| 23484 |
.PD |
| 23485 |
These insert and/or replace a string at the specified offset/length within the |
| 23486 |
SV. Similar to the Perl \f(CWsubstr()\fR function, with \f(CW\*(C`littlelen\*(C'\fR bytes starting |
| 23487 |
at \f(CW\*(C`little\*(C'\fR replacing \f(CW\*(C`len\*(C'\fR bytes of the string in \f(CW\*(C`bigstr\*(C'\fR starting at |
| 23488 |
\&\f(CW\*(C`offset\*(C'\fR. They handle get magic. |
| 23489 |
.Sp |
| 23490 |
\&\f(CW\*(C`sv_insert_flags\*(C'\fR is identical to plain \f(CW\*(C`sv_insert\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR |
| 23491 |
are passed to the \f(CW\*(C`SvPV_force_flags\*(C'\fR operation that is internally applied to |
| 23492 |
\&\f(CW\*(C`bigstr\*(C'\fR. |
| 23493 |
.RS 4 |
| 23494 |
.Sp |
| 23495 |
.Vb 6 |
| 23496 |
\& void sv_insert (SV * const bigstr, const STRLEN offset, |
| 23497 |
\& const STRLEN len, const char * const little, |
| 23498 |
\& const STRLEN littlelen) |
| 23499 |
\& void sv_insert_flags(SV * const bigstr, const STRLEN offset, |
| 23500 |
\& const STRLEN len, const char *little, |
| 23501 |
\& const STRLEN littlelen, const U32 flags) |
| 23502 |
.Ve |
| 23503 |
.RE |
| 23504 |
.RS 4 |
| 23505 |
.RE |
| 23506 |
.ie n .IP """sv_2io""" 4 |
| 23507 |
.el .IP \f(CWsv_2io\fR 4 |
| 23508 |
.IX Xref "sv_2io" |
| 23509 |
.IX Item "sv_2io" |
| 23510 |
Using various gambits, try to get an IO from an SV: the IO slot if its a |
| 23511 |
GV; or the recursive result if we're an RV; or the IO slot of the symbol |
| 23512 |
named after the PV if we're a string. |
| 23513 |
.Sp |
| 23514 |
\&'Get' magic is ignored on the \f(CW\*(C`sv\*(C'\fR passed in, but will be called on |
| 23515 |
\&\f(CWSvRV(sv)\fR if \f(CW\*(C`sv\*(C'\fR is an RV. |
| 23516 |
.RS 4 |
| 23517 |
.Sp |
| 23518 |
.Vb 1 |
| 23519 |
\& IO * sv_2io(SV * const sv) |
| 23520 |
.Ve |
| 23521 |
.RE |
| 23522 |
.RS 4 |
| 23523 |
.RE |
| 23524 |
.ie n .IP """SvIOK""" 4 |
| 23525 |
.el .IP \f(CWSvIOK\fR 4 |
| 23526 |
.IX Xref "SvIOK" |
| 23527 |
.IX Item "SvIOK" |
| 23528 |
Returns a U32 value indicating whether the SV contains an integer. |
| 23529 |
.RS 4 |
| 23530 |
.Sp |
| 23531 |
.Vb 1 |
| 23532 |
\& U32 SvIOK(SV* sv) |
| 23533 |
.Ve |
| 23534 |
.RE |
| 23535 |
.RS 4 |
| 23536 |
.RE |
| 23537 |
.ie n .IP """SvIOK_notUV""" 4 |
| 23538 |
.el .IP \f(CWSvIOK_notUV\fR 4 |
| 23539 |
.IX Xref "SvIOK_notUV" |
| 23540 |
.IX Item "SvIOK_notUV" |
| 23541 |
Returns a boolean indicating whether the SV contains a signed integer. |
| 23542 |
.RS 4 |
| 23543 |
.Sp |
| 23544 |
.Vb 1 |
| 23545 |
\& bool SvIOK_notUV(SV* sv) |
| 23546 |
.Ve |
| 23547 |
.RE |
| 23548 |
.RS 4 |
| 23549 |
.RE |
| 23550 |
.ie n .IP """SvIOK_off""" 4 |
| 23551 |
.el .IP \f(CWSvIOK_off\fR 4 |
| 23552 |
.IX Xref "SvIOK_off" |
| 23553 |
.IX Item "SvIOK_off" |
| 23554 |
Unsets the IV status of an SV. |
| 23555 |
.RS 4 |
| 23556 |
.Sp |
| 23557 |
.Vb 1 |
| 23558 |
\& void SvIOK_off(SV* sv) |
| 23559 |
.Ve |
| 23560 |
.RE |
| 23561 |
.RS 4 |
| 23562 |
.RE |
| 23563 |
.ie n .IP """SvIOK_on""" 4 |
| 23564 |
.el .IP \f(CWSvIOK_on\fR 4 |
| 23565 |
.IX Xref "SvIOK_on" |
| 23566 |
.IX Item "SvIOK_on" |
| 23567 |
Tells an SV that it is an integer. |
| 23568 |
.RS 4 |
| 23569 |
.Sp |
| 23570 |
.Vb 1 |
| 23571 |
\& void SvIOK_on(SV* sv) |
| 23572 |
.Ve |
| 23573 |
.RE |
| 23574 |
.RS 4 |
| 23575 |
.RE |
| 23576 |
.ie n .IP """SvIOK_only""" 4 |
| 23577 |
.el .IP \f(CWSvIOK_only\fR 4 |
| 23578 |
.IX Xref "SvIOK_only" |
| 23579 |
.IX Item "SvIOK_only" |
| 23580 |
Tells an SV that it is an integer and disables all other \f(CW\*(C`OK\*(C'\fR bits. |
| 23581 |
.RS 4 |
| 23582 |
.Sp |
| 23583 |
.Vb 1 |
| 23584 |
\& void SvIOK_only(SV* sv) |
| 23585 |
.Ve |
| 23586 |
.RE |
| 23587 |
.RS 4 |
| 23588 |
.RE |
| 23589 |
.ie n .IP """SvIOK_only_UV""" 4 |
| 23590 |
.el .IP \f(CWSvIOK_only_UV\fR 4 |
| 23591 |
.IX Xref "SvIOK_only_UV" |
| 23592 |
.IX Item "SvIOK_only_UV" |
| 23593 |
Tells an SV that it is an unsigned integer and disables all other \f(CW\*(C`OK\*(C'\fR bits. |
| 23594 |
.RS 4 |
| 23595 |
.Sp |
| 23596 |
.Vb 1 |
| 23597 |
\& void SvIOK_only_UV(SV* sv) |
| 23598 |
.Ve |
| 23599 |
.RE |
| 23600 |
.RS 4 |
| 23601 |
.RE |
| 23602 |
.ie n .IP """SvIOKp""" 4 |
| 23603 |
.el .IP \f(CWSvIOKp\fR 4 |
| 23604 |
.IX Xref "SvIOKp" |
| 23605 |
.IX Item "SvIOKp" |
| 23606 |
Returns a U32 value indicating whether the SV contains an integer. Checks |
| 23607 |
the \fBprivate\fR setting. Use \f(CW\*(C`SvIOK\*(C'\fR instead. |
| 23608 |
.RS 4 |
| 23609 |
.Sp |
| 23610 |
.Vb 1 |
| 23611 |
\& U32 SvIOKp(SV* sv) |
| 23612 |
.Ve |
| 23613 |
.RE |
| 23614 |
.RS 4 |
| 23615 |
.RE |
| 23616 |
.ie n .IP """SvIOK_UV""" 4 |
| 23617 |
.el .IP \f(CWSvIOK_UV\fR 4 |
| 23618 |
.IX Xref "SvIOK_UV" |
| 23619 |
.IX Item "SvIOK_UV" |
| 23620 |
Returns a boolean indicating whether the SV contains an integer that must be |
| 23621 |
interpreted as unsigned. A non-negative integer whose value is within the |
| 23622 |
range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR. |
| 23623 |
.RS 4 |
| 23624 |
.Sp |
| 23625 |
.Vb 1 |
| 23626 |
\& bool SvIOK_UV(SV* sv) |
| 23627 |
.Ve |
| 23628 |
.RE |
| 23629 |
.RS 4 |
| 23630 |
.RE |
| 23631 |
.ie n .IP """sv_isa""" 4 |
| 23632 |
.el .IP \f(CWsv_isa\fR 4 |
| 23633 |
.IX Xref "sv_isa" |
| 23634 |
.IX Item "sv_isa" |
| 23635 |
Returns a boolean indicating whether the SV is blessed into the specified |
| 23636 |
class. |
| 23637 |
.Sp |
| 23638 |
This does not check for subtypes or method overloading. Use \f(CW\*(C`sv_isa_sv\*(C'\fR to |
| 23639 |
verify an inheritance relationship in the same way as the \f(CW\*(C`isa\*(C'\fR operator by |
| 23640 |
respecting any \f(CWisa()\fR method overloading; or \f(CW\*(C`sv_derived_from_sv\*(C'\fR to test |
| 23641 |
directly on the actual object type. |
| 23642 |
.RS 4 |
| 23643 |
.Sp |
| 23644 |
.Vb 1 |
| 23645 |
\& int sv_isa(SV *sv, const char * const name) |
| 23646 |
.Ve |
| 23647 |
.RE |
| 23648 |
.RS 4 |
| 23649 |
.RE |
| 23650 |
.ie n .IP """sv_isa_sv""" 4 |
| 23651 |
.el .IP \f(CWsv_isa_sv\fR 4 |
| 23652 |
.IX Xref "sv_isa_sv" |
| 23653 |
.IX Item "sv_isa_sv" |
| 23654 |
Returns a boolean indicating whether the SV is an object reference and is |
| 23655 |
derived from the specified class, respecting any \f(CWisa()\fR method overloading |
| 23656 |
it may have. Returns false if \f(CW\*(C`sv\*(C'\fR is not a reference to an object, or is |
| 23657 |
not derived from the specified class. |
| 23658 |
.Sp |
| 23659 |
This is the function used to implement the behaviour of the \f(CW\*(C`isa\*(C'\fR operator. |
| 23660 |
.Sp |
| 23661 |
Does not invoke magic on \f(CW\*(C`sv\*(C'\fR. |
| 23662 |
.Sp |
| 23663 |
Not to be confused with the older \f(CW\*(C`sv_isa\*(C'\fR function, which does not use an |
| 23664 |
overloaded \f(CWisa()\fR method, nor will check subclassing. |
| 23665 |
.RS 4 |
| 23666 |
.Sp |
| 23667 |
.Vb 1 |
| 23668 |
\& bool sv_isa_sv(SV *sv, SV *namesv) |
| 23669 |
.Ve |
| 23670 |
.RE |
| 23671 |
.RS 4 |
| 23672 |
.RE |
| 23673 |
.ie n .IP """SvIsBOOL""" 4 |
| 23674 |
.el .IP \f(CWSvIsBOOL\fR 4 |
| 23675 |
.IX Xref "SvIsBOOL" |
| 23676 |
.IX Item "SvIsBOOL" |
| 23677 |
Returns true if the SV is one of the special boolean constants (PL_sv_yes or |
| 23678 |
PL_sv_no), or is a regular SV whose last assignment stored a copy of one. |
| 23679 |
.RS 4 |
| 23680 |
.Sp |
| 23681 |
.Vb 1 |
| 23682 |
\& bool SvIsBOOL(SV* sv) |
| 23683 |
.Ve |
| 23684 |
.RE |
| 23685 |
.RS 4 |
| 23686 |
.RE |
| 23687 |
.ie n .IP """SvIsCOW""" 4 |
| 23688 |
.el .IP \f(CWSvIsCOW\fR 4 |
| 23689 |
.IX Xref "SvIsCOW" |
| 23690 |
.IX Item "SvIsCOW" |
| 23691 |
Returns a U32 value indicating whether the SV is Copy-On-Write (either shared |
| 23692 |
hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for |
| 23693 |
COW). |
| 23694 |
.RS 4 |
| 23695 |
.Sp |
| 23696 |
.Vb 1 |
| 23697 |
\& U32 SvIsCOW(SV* sv) |
| 23698 |
.Ve |
| 23699 |
.RE |
| 23700 |
.RS 4 |
| 23701 |
.RE |
| 23702 |
.ie n .IP """SvIsCOW_shared_hash""" 4 |
| 23703 |
.el .IP \f(CWSvIsCOW_shared_hash\fR 4 |
| 23704 |
.IX Xref "SvIsCOW_shared_hash" |
| 23705 |
.IX Item "SvIsCOW_shared_hash" |
| 23706 |
Returns a boolean indicating whether the SV is Copy-On-Write shared hash key |
| 23707 |
scalar. |
| 23708 |
.RS 4 |
| 23709 |
.Sp |
| 23710 |
.Vb 1 |
| 23711 |
\& bool SvIsCOW_shared_hash(SV* sv) |
| 23712 |
.Ve |
| 23713 |
.RE |
| 23714 |
.RS 4 |
| 23715 |
.RE |
| 23716 |
.ie n .IP """sv_isobject""" 4 |
| 23717 |
.el .IP \f(CWsv_isobject\fR 4 |
| 23718 |
.IX Xref "sv_isobject" |
| 23719 |
.IX Item "sv_isobject" |
| 23720 |
Returns a boolean indicating whether the SV is an RV pointing to a blessed |
| 23721 |
object. If the SV is not an RV, or if the object is not blessed, then this |
| 23722 |
will return false. |
| 23723 |
.RS 4 |
| 23724 |
.Sp |
| 23725 |
.Vb 1 |
| 23726 |
\& int sv_isobject(SV *sv) |
| 23727 |
.Ve |
| 23728 |
.RE |
| 23729 |
.RS 4 |
| 23730 |
.RE |
| 23731 |
.ie n .IP """SvIV""" 4 |
| 23732 |
.el .IP \f(CWSvIV\fR 4 |
| 23733 |
.IX Item "SvIV" |
| 23734 |
.PD 0 |
| 23735 |
.ie n .IP """SvIV_nomg""" 4 |
| 23736 |
.el .IP \f(CWSvIV_nomg\fR 4 |
| 23737 |
.IX Item "SvIV_nomg" |
| 23738 |
.ie n .IP """SvIVx""" 4 |
| 23739 |
.el .IP \f(CWSvIVx\fR 4 |
| 23740 |
.IX Xref "SvIV SvIV_nomg SvIVx" |
| 23741 |
.IX Item "SvIVx" |
| 23742 |
.PD |
| 23743 |
These each coerce the given SV to IV and return it. The returned value in many |
| 23744 |
circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's IV slot, but not in all cases. (Use |
| 23745 |
\&\f(CW"sv_setiv"\fR to make sure it does). |
| 23746 |
.Sp |
| 23747 |
As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 23748 |
.Sp |
| 23749 |
\&\f(CW\*(C`SvIVx\*(C'\fR is now identical to \f(CW\*(C`SvIV\*(C'\fR, but prior to 5.37.1, it was the only form |
| 23750 |
guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 23751 |
.Sp |
| 23752 |
\&\f(CW\*(C`SvIV_nomg\*(C'\fR is the same as \f(CW\*(C`SvIV\*(C'\fR, but does not perform 'get' magic. |
| 23753 |
.RS 4 |
| 23754 |
.Sp |
| 23755 |
.Vb 1 |
| 23756 |
\& IV SvIV(SV *sv) |
| 23757 |
.Ve |
| 23758 |
.RE |
| 23759 |
.RS 4 |
| 23760 |
.RE |
| 23761 |
.ie n .IP """sv_2iv_flags""" 4 |
| 23762 |
.el .IP \f(CWsv_2iv_flags\fR 4 |
| 23763 |
.IX Xref "sv_2iv_flags" |
| 23764 |
.IX Item "sv_2iv_flags" |
| 23765 |
Return the integer value of an SV, doing any necessary string |
| 23766 |
conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first. |
| 23767 |
Normally used via the \f(CWSvIV(sv)\fR and \f(CWSvIVx(sv)\fR macros. |
| 23768 |
.RS 4 |
| 23769 |
.Sp |
| 23770 |
.Vb 1 |
| 23771 |
\& IV sv_2iv_flags(SV * const sv, const I32 flags) |
| 23772 |
.Ve |
| 23773 |
.RE |
| 23774 |
.RS 4 |
| 23775 |
.RE |
| 23776 |
.ie n .IP """SvIV_set""" 4 |
| 23777 |
.el .IP \f(CWSvIV_set\fR 4 |
| 23778 |
.IX Xref "SvIV_set" |
| 23779 |
.IX Item "SvIV_set" |
| 23780 |
Set the value of the IV pointer in sv to val. It is possible to perform |
| 23781 |
the same function of this macro with an lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR. |
| 23782 |
With future Perls, however, it will be more efficient to use |
| 23783 |
\&\f(CW\*(C`SvIV_set\*(C'\fR instead of the lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR. |
| 23784 |
.RS 4 |
| 23785 |
.Sp |
| 23786 |
.Vb 1 |
| 23787 |
\& void SvIV_set(SV* sv, IV val) |
| 23788 |
.Ve |
| 23789 |
.RE |
| 23790 |
.RS 4 |
| 23791 |
.RE |
| 23792 |
.ie n .IP """SvIVX""" 4 |
| 23793 |
.el .IP \f(CWSvIVX\fR 4 |
| 23794 |
.IX Xref "SvIVX" |
| 23795 |
.IX Item "SvIVX" |
| 23796 |
Returns the raw value in the SV's IV slot, without checks or conversions. |
| 23797 |
Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvIV"\fR. |
| 23798 |
.RS 4 |
| 23799 |
.Sp |
| 23800 |
.Vb 1 |
| 23801 |
\& IV SvIVX(SV* sv) |
| 23802 |
.Ve |
| 23803 |
.RE |
| 23804 |
.RS 4 |
| 23805 |
.RE |
| 23806 |
.ie n .IP """SvLEN""" 4 |
| 23807 |
.el .IP \f(CWSvLEN\fR 4 |
| 23808 |
.IX Xref "SvLEN" |
| 23809 |
.IX Item "SvLEN" |
| 23810 |
Returns the size of the string buffer in the SV, not including any part |
| 23811 |
attributable to \f(CW\*(C`SvOOK\*(C'\fR. See \f(CW"SvCUR"\fR. |
| 23812 |
.RS 4 |
| 23813 |
.Sp |
| 23814 |
.Vb 1 |
| 23815 |
\& STRLEN SvLEN(SV* sv) |
| 23816 |
.Ve |
| 23817 |
.RE |
| 23818 |
.RS 4 |
| 23819 |
.RE |
| 23820 |
.ie n .IP """sv_len""" 4 |
| 23821 |
.el .IP \f(CWsv_len\fR 4 |
| 23822 |
.IX Xref "sv_len" |
| 23823 |
.IX Item "sv_len" |
| 23824 |
Returns the length of the string in the SV. Handles magic and type |
| 23825 |
coercion and sets the UTF8 flag appropriately. See also \f(CW"SvCUR"\fR, which |
| 23826 |
gives raw access to the \f(CW\*(C`xpv_cur\*(C'\fR slot. |
| 23827 |
.RS 4 |
| 23828 |
.Sp |
| 23829 |
.Vb 1 |
| 23830 |
\& STRLEN sv_len(SV * const sv) |
| 23831 |
.Ve |
| 23832 |
.RE |
| 23833 |
.RS 4 |
| 23834 |
.RE |
| 23835 |
.ie n .IP """SvLEN_set""" 4 |
| 23836 |
.el .IP \f(CWSvLEN_set\fR 4 |
| 23837 |
.IX Xref "SvLEN_set" |
| 23838 |
.IX Item "SvLEN_set" |
| 23839 |
Set the size of the string buffer for the SV. See \f(CW"SvLEN"\fR. |
| 23840 |
.RS 4 |
| 23841 |
.Sp |
| 23842 |
.Vb 1 |
| 23843 |
\& void SvLEN_set(SV* sv, STRLEN len) |
| 23844 |
.Ve |
| 23845 |
.RE |
| 23846 |
.RS 4 |
| 23847 |
.RE |
| 23848 |
.ie n .IP """sv_len_utf8""" 4 |
| 23849 |
.el .IP \f(CWsv_len_utf8\fR 4 |
| 23850 |
.IX Item "sv_len_utf8" |
| 23851 |
.PD 0 |
| 23852 |
.ie n .IP """sv_len_utf8_nomg""" 4 |
| 23853 |
.el .IP \f(CWsv_len_utf8_nomg\fR 4 |
| 23854 |
.IX Xref "sv_len_utf8 sv_len_utf8_nomg" |
| 23855 |
.IX Item "sv_len_utf8_nomg" |
| 23856 |
.PD |
| 23857 |
These return the number of characters in the string in an SV, counting wide |
| 23858 |
UTF\-8 bytes as a single character. Both handle type coercion. |
| 23859 |
They differ only in that \f(CW\*(C`sv_len_utf8\*(C'\fR performs 'get' magic; |
| 23860 |
\&\f(CW\*(C`sv_len_utf8_nomg\*(C'\fR skips any magic. |
| 23861 |
.RS 4 |
| 23862 |
.Sp |
| 23863 |
.Vb 1 |
| 23864 |
\& STRLEN sv_len_utf8(SV * const sv) |
| 23865 |
.Ve |
| 23866 |
.RE |
| 23867 |
.RS 4 |
| 23868 |
.RE |
| 23869 |
.ie n .IP """SvLOCK""" 4 |
| 23870 |
.el .IP \f(CWSvLOCK\fR 4 |
| 23871 |
.IX Xref "SvLOCK" |
| 23872 |
.IX Item "SvLOCK" |
| 23873 |
Arranges for a mutual exclusion lock to be obtained on \f(CW\*(C`sv\*(C'\fR if a suitable module |
| 23874 |
has been loaded. |
| 23875 |
.RS 4 |
| 23876 |
.Sp |
| 23877 |
.Vb 1 |
| 23878 |
\& void SvLOCK(SV* sv) |
| 23879 |
.Ve |
| 23880 |
.RE |
| 23881 |
.RS 4 |
| 23882 |
.RE |
| 23883 |
.ie n .IP """sv_magic""" 4 |
| 23884 |
.el .IP \f(CWsv_magic\fR 4 |
| 23885 |
.IX Xref "sv_magic" |
| 23886 |
.IX Item "sv_magic" |
| 23887 |
Adds magic to an SV. First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if |
| 23888 |
necessary, then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the |
| 23889 |
magic list. |
| 23890 |
.Sp |
| 23891 |
See \f(CW"sv_magicext"\fR (which \f(CW\*(C`sv_magic\*(C'\fR now calls) for a description of the |
| 23892 |
handling of the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments. |
| 23893 |
.Sp |
| 23894 |
You need to use \f(CW\*(C`sv_magicext\*(C'\fR to add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs and also |
| 23895 |
to add more than one instance of the same \f(CW\*(C`how\*(C'\fR. |
| 23896 |
.RS 4 |
| 23897 |
.Sp |
| 23898 |
.Vb 2 |
| 23899 |
\& void sv_magic(SV * const sv, SV * const obj, const int how, |
| 23900 |
\& const char * const name, const I32 namlen) |
| 23901 |
.Ve |
| 23902 |
.RE |
| 23903 |
.RS 4 |
| 23904 |
.RE |
| 23905 |
.ie n .IP """sv_magicext""" 4 |
| 23906 |
.el .IP \f(CWsv_magicext\fR 4 |
| 23907 |
.IX Xref "sv_magicext" |
| 23908 |
.IX Item "sv_magicext" |
| 23909 |
Adds magic to an SV, upgrading it if necessary. Applies the |
| 23910 |
supplied \f(CW\*(C`vtable\*(C'\fR and returns a pointer to the magic added. |
| 23911 |
.Sp |
| 23912 |
Note that \f(CW\*(C`sv_magicext\*(C'\fR will allow things that \f(CW\*(C`sv_magic\*(C'\fR will not. |
| 23913 |
In particular, you can add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs, and add more than |
| 23914 |
one instance of the same \f(CW\*(C`how\*(C'\fR. |
| 23915 |
.Sp |
| 23916 |
If \f(CW\*(C`namlen\*(C'\fR is greater than zero then a \f(CW\*(C`savepvn\*(C'\fR \fIcopy\fR of \f(CW\*(C`name\*(C'\fR is |
| 23917 |
stored, if \f(CW\*(C`namlen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as-is and \- as another |
| 23918 |
special case \- if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed |
| 23919 |
to contain an SV* and is stored as-is with its \f(CW\*(C`REFCNT\*(C'\fR incremented. |
| 23920 |
.Sp |
| 23921 |
(This is now used as a subroutine by \f(CW\*(C`sv_magic\*(C'\fR.) |
| 23922 |
.RS 4 |
| 23923 |
.Sp |
| 23924 |
.Vb 3 |
| 23925 |
\& MAGIC * sv_magicext(SV * const sv, SV * const obj, const int how, |
| 23926 |
\& const MGVTBL * const vtbl, |
| 23927 |
\& const char * const name, const I32 namlen) |
| 23928 |
.Ve |
| 23929 |
.RE |
| 23930 |
.RS 4 |
| 23931 |
.RE |
| 23932 |
.ie n .IP """SvMAGIC_set""" 4 |
| 23933 |
.el .IP \f(CWSvMAGIC_set\fR 4 |
| 23934 |
.IX Xref "SvMAGIC_set" |
| 23935 |
.IX Item "SvMAGIC_set" |
| 23936 |
Set the value of the MAGIC pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR. |
| 23937 |
.RS 4 |
| 23938 |
.Sp |
| 23939 |
.Vb 1 |
| 23940 |
\& void SvMAGIC_set(SV* sv, MAGIC* val) |
| 23941 |
.Ve |
| 23942 |
.RE |
| 23943 |
.RS 4 |
| 23944 |
.RE |
| 23945 |
.ie n .IP """sv_2mortal""" 4 |
| 23946 |
.el .IP \f(CWsv_2mortal\fR 4 |
| 23947 |
.IX Xref "sv_2mortal" |
| 23948 |
.IX Item "sv_2mortal" |
| 23949 |
Marks an existing SV as mortal. The SV will be destroyed "soon", either |
| 23950 |
by an explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as |
| 23951 |
statement boundaries. \f(CWSvTEMP()\fR is turned on which means that the SV's |
| 23952 |
string buffer can be "stolen" if this SV is copied. See also |
| 23953 |
\&\f(CW"sv_newmortal"\fR and \f(CW"sv_mortalcopy"\fR. |
| 23954 |
.RS 4 |
| 23955 |
.Sp |
| 23956 |
.Vb 1 |
| 23957 |
\& SV * sv_2mortal(SV * const sv) |
| 23958 |
.Ve |
| 23959 |
.RE |
| 23960 |
.RS 4 |
| 23961 |
.RE |
| 23962 |
.ie n .IP """sv_mortalcopy""" 4 |
| 23963 |
.el .IP \f(CWsv_mortalcopy\fR 4 |
| 23964 |
.IX Xref "sv_mortalcopy" |
| 23965 |
.IX Item "sv_mortalcopy" |
| 23966 |
Creates a new SV which is a copy of the original SV (using \f(CW\*(C`sv_setsv\*(C'\fR). |
| 23967 |
The new SV is marked as mortal. It will be destroyed "soon", either by an |
| 23968 |
explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as |
| 23969 |
statement boundaries. See also \f(CW"sv_newmortal"\fR and \f(CW"sv_2mortal"\fR. |
| 23970 |
.RS 4 |
| 23971 |
.Sp |
| 23972 |
.Vb 1 |
| 23973 |
\& SV * sv_mortalcopy(SV * const oldsv) |
| 23974 |
.Ve |
| 23975 |
.RE |
| 23976 |
.RS 4 |
| 23977 |
.RE |
| 23978 |
.ie n .IP """sv_mortalcopy_flags""" 4 |
| 23979 |
.el .IP \f(CWsv_mortalcopy_flags\fR 4 |
| 23980 |
.IX Xref "sv_mortalcopy_flags" |
| 23981 |
.IX Item "sv_mortalcopy_flags" |
| 23982 |
Like \f(CW\*(C`sv_mortalcopy\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR are passed to the |
| 23983 |
\&\f(CW\*(C`sv_setsv_flags\*(C'\fR. |
| 23984 |
.RS 4 |
| 23985 |
.Sp |
| 23986 |
.Vb 1 |
| 23987 |
\& SV * sv_mortalcopy_flags(SV * const oldsv, U32 flags) |
| 23988 |
.Ve |
| 23989 |
.RE |
| 23990 |
.RS 4 |
| 23991 |
.RE |
| 23992 |
.ie n .IP """sv_newmortal""" 4 |
| 23993 |
.el .IP \f(CWsv_newmortal\fR 4 |
| 23994 |
.IX Xref "sv_newmortal" |
| 23995 |
.IX Item "sv_newmortal" |
| 23996 |
Creates a new null SV which is mortal. The reference count of the SV is |
| 23997 |
set to 1. It will be destroyed "soon", either by an explicit call to |
| 23998 |
\&\f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as statement boundaries. |
| 23999 |
See also \f(CW"sv_mortalcopy"\fR and \f(CW"sv_2mortal"\fR. |
| 24000 |
.RS 4 |
| 24001 |
.Sp |
| 24002 |
.Vb 1 |
| 24003 |
\& SV * sv_newmortal() |
| 24004 |
.Ve |
| 24005 |
.RE |
| 24006 |
.RS 4 |
| 24007 |
.RE |
| 24008 |
.ie n .IP """SvNIOK""" 4 |
| 24009 |
.el .IP \f(CWSvNIOK\fR 4 |
| 24010 |
.IX Xref "SvNIOK" |
| 24011 |
.IX Item "SvNIOK" |
| 24012 |
Returns a U32 value indicating whether the SV contains a number, integer or |
| 24013 |
double. |
| 24014 |
.RS 4 |
| 24015 |
.Sp |
| 24016 |
.Vb 1 |
| 24017 |
\& U32 SvNIOK(SV* sv) |
| 24018 |
.Ve |
| 24019 |
.RE |
| 24020 |
.RS 4 |
| 24021 |
.RE |
| 24022 |
.ie n .IP """SvNIOK_off""" 4 |
| 24023 |
.el .IP \f(CWSvNIOK_off\fR 4 |
| 24024 |
.IX Xref "SvNIOK_off" |
| 24025 |
.IX Item "SvNIOK_off" |
| 24026 |
Unsets the NV/IV status of an SV. |
| 24027 |
.RS 4 |
| 24028 |
.Sp |
| 24029 |
.Vb 1 |
| 24030 |
\& void SvNIOK_off(SV* sv) |
| 24031 |
.Ve |
| 24032 |
.RE |
| 24033 |
.RS 4 |
| 24034 |
.RE |
| 24035 |
.ie n .IP """SvNIOKp""" 4 |
| 24036 |
.el .IP \f(CWSvNIOKp\fR 4 |
| 24037 |
.IX Xref "SvNIOKp" |
| 24038 |
.IX Item "SvNIOKp" |
| 24039 |
Returns a U32 value indicating whether the SV contains a number, integer or |
| 24040 |
double. Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvNIOK\*(C'\fR instead. |
| 24041 |
.RS 4 |
| 24042 |
.Sp |
| 24043 |
.Vb 1 |
| 24044 |
\& U32 SvNIOKp(SV* sv) |
| 24045 |
.Ve |
| 24046 |
.RE |
| 24047 |
.RS 4 |
| 24048 |
.RE |
| 24049 |
.ie n .IP """SvNOK""" 4 |
| 24050 |
.el .IP \f(CWSvNOK\fR 4 |
| 24051 |
.IX Xref "SvNOK" |
| 24052 |
.IX Item "SvNOK" |
| 24053 |
Returns a U32 value indicating whether the SV contains a double. |
| 24054 |
.RS 4 |
| 24055 |
.Sp |
| 24056 |
.Vb 1 |
| 24057 |
\& U32 SvNOK(SV* sv) |
| 24058 |
.Ve |
| 24059 |
.RE |
| 24060 |
.RS 4 |
| 24061 |
.RE |
| 24062 |
.ie n .IP """SvNOK_off""" 4 |
| 24063 |
.el .IP \f(CWSvNOK_off\fR 4 |
| 24064 |
.IX Xref "SvNOK_off" |
| 24065 |
.IX Item "SvNOK_off" |
| 24066 |
Unsets the NV status of an SV. |
| 24067 |
.RS 4 |
| 24068 |
.Sp |
| 24069 |
.Vb 1 |
| 24070 |
\& void SvNOK_off(SV* sv) |
| 24071 |
.Ve |
| 24072 |
.RE |
| 24073 |
.RS 4 |
| 24074 |
.RE |
| 24075 |
.ie n .IP """SvNOK_on""" 4 |
| 24076 |
.el .IP \f(CWSvNOK_on\fR 4 |
| 24077 |
.IX Xref "SvNOK_on" |
| 24078 |
.IX Item "SvNOK_on" |
| 24079 |
Tells an SV that it is a double. |
| 24080 |
.RS 4 |
| 24081 |
.Sp |
| 24082 |
.Vb 1 |
| 24083 |
\& void SvNOK_on(SV* sv) |
| 24084 |
.Ve |
| 24085 |
.RE |
| 24086 |
.RS 4 |
| 24087 |
.RE |
| 24088 |
.ie n .IP """SvNOK_only""" 4 |
| 24089 |
.el .IP \f(CWSvNOK_only\fR 4 |
| 24090 |
.IX Xref "SvNOK_only" |
| 24091 |
.IX Item "SvNOK_only" |
| 24092 |
Tells an SV that it is a double and disables all other OK bits. |
| 24093 |
.RS 4 |
| 24094 |
.Sp |
| 24095 |
.Vb 1 |
| 24096 |
\& void SvNOK_only(SV* sv) |
| 24097 |
.Ve |
| 24098 |
.RE |
| 24099 |
.RS 4 |
| 24100 |
.RE |
| 24101 |
.ie n .IP """SvNOKp""" 4 |
| 24102 |
.el .IP \f(CWSvNOKp\fR 4 |
| 24103 |
.IX Xref "SvNOKp" |
| 24104 |
.IX Item "SvNOKp" |
| 24105 |
Returns a U32 value indicating whether the SV contains a double. Checks the |
| 24106 |
\&\fBprivate\fR setting. Use \f(CW\*(C`SvNOK\*(C'\fR instead. |
| 24107 |
.RS 4 |
| 24108 |
.Sp |
| 24109 |
.Vb 1 |
| 24110 |
\& U32 SvNOKp(SV* sv) |
| 24111 |
.Ve |
| 24112 |
.RE |
| 24113 |
.RS 4 |
| 24114 |
.RE |
| 24115 |
.ie n .IP """sv_nolocking""" 4 |
| 24116 |
.el .IP \f(CWsv_nolocking\fR 4 |
| 24117 |
.IX Xref "sv_nolocking" |
| 24118 |
.IX Item "sv_nolocking" |
| 24119 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nolocking\*(C'\fR |
| 24120 |
from a future release of Perl. Do not use it for |
| 24121 |
new code; remove it from existing code. |
| 24122 |
.Sp |
| 24123 |
Dummy routine which "locks" an SV when there is no locking module present. |
| 24124 |
Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could |
| 24125 |
potentially warn under some level of strict-ness. |
| 24126 |
.Sp |
| 24127 |
"Superseded" by \f(CWsv_nosharing()\fR. |
| 24128 |
.RS 4 |
| 24129 |
.Sp |
| 24130 |
.Vb 1 |
| 24131 |
\& void sv_nolocking(SV *sv) |
| 24132 |
.Ve |
| 24133 |
.RE |
| 24134 |
.RS 4 |
| 24135 |
.RE |
| 24136 |
.ie n .IP """sv_nounlocking""" 4 |
| 24137 |
.el .IP \f(CWsv_nounlocking\fR 4 |
| 24138 |
.IX Xref "sv_nounlocking" |
| 24139 |
.IX Item "sv_nounlocking" |
| 24140 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nounlocking\*(C'\fR |
| 24141 |
from a future release of Perl. Do not use it for |
| 24142 |
new code; remove it from existing code. |
| 24143 |
.Sp |
| 24144 |
Dummy routine which "unlocks" an SV when there is no locking module present. |
| 24145 |
Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could |
| 24146 |
potentially warn under some level of strict-ness. |
| 24147 |
.Sp |
| 24148 |
"Superseded" by \f(CWsv_nosharing()\fR. |
| 24149 |
.RS 4 |
| 24150 |
.Sp |
| 24151 |
.Vb 1 |
| 24152 |
\& void sv_nounlocking(SV *sv) |
| 24153 |
.Ve |
| 24154 |
.RE |
| 24155 |
.RS 4 |
| 24156 |
.RE |
| 24157 |
.ie n .IP """sv_numeq""" 4 |
| 24158 |
.el .IP \f(CWsv_numeq\fR 4 |
| 24159 |
.IX Xref "sv_numeq" |
| 24160 |
.IX Item "sv_numeq" |
| 24161 |
A convenient shortcut for calling \f(CW\*(C`sv_numeq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR |
| 24162 |
flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 == $sv2\*(C'\fR. |
| 24163 |
.RS 4 |
| 24164 |
.Sp |
| 24165 |
.Vb 1 |
| 24166 |
\& bool sv_numeq(SV *sv1, SV *sv2) |
| 24167 |
.Ve |
| 24168 |
.RE |
| 24169 |
.RS 4 |
| 24170 |
.RE |
| 24171 |
.ie n .IP """sv_numeq_flags""" 4 |
| 24172 |
.el .IP \f(CWsv_numeq_flags\fR 4 |
| 24173 |
.IX Xref "sv_numeq_flags" |
| 24174 |
.IX Item "sv_numeq_flags" |
| 24175 |
Returns a boolean indicating whether the numbers in the two SVs are |
| 24176 |
identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles |
| 24177 |
get-magic too. Will coerce its args to numbers if necessary. Treats |
| 24178 |
\&\f(CW\*(C`NULL\*(C'\fR as undef. |
| 24179 |
.Sp |
| 24180 |
If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use |
| 24181 |
\&\f(CW\*(C`==\*(C'\fR overloading will be made. If such overloading does not exist or the |
| 24182 |
flag is set, then regular numerical comparison will be used instead. |
| 24183 |
.RS 4 |
| 24184 |
.Sp |
| 24185 |
.Vb 1 |
| 24186 |
\& bool sv_numeq_flags(SV *sv1, SV *sv2, const U32 flags) |
| 24187 |
.Ve |
| 24188 |
.RE |
| 24189 |
.RS 4 |
| 24190 |
.RE |
| 24191 |
.ie n .IP """SvNV""" 4 |
| 24192 |
.el .IP \f(CWSvNV\fR 4 |
| 24193 |
.IX Item "SvNV" |
| 24194 |
.PD 0 |
| 24195 |
.ie n .IP """SvNV_nomg""" 4 |
| 24196 |
.el .IP \f(CWSvNV_nomg\fR 4 |
| 24197 |
.IX Item "SvNV_nomg" |
| 24198 |
.ie n .IP """SvNVx""" 4 |
| 24199 |
.el .IP \f(CWSvNVx\fR 4 |
| 24200 |
.IX Xref "SvNV SvNV_nomg SvNVx" |
| 24201 |
.IX Item "SvNVx" |
| 24202 |
.PD |
| 24203 |
These each coerce the given SV to NV and return it. The returned value in many |
| 24204 |
circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's NV slot, but not in all cases. (Use |
| 24205 |
\&\f(CW"sv_setnv"\fR to make sure it does). |
| 24206 |
.Sp |
| 24207 |
As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 24208 |
.Sp |
| 24209 |
\&\f(CW\*(C`SvNVx\*(C'\fR is now identical to \f(CW\*(C`SvNV\*(C'\fR, but prior to 5.37.1, it was the only form |
| 24210 |
guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 24211 |
.Sp |
| 24212 |
\&\f(CW\*(C`SvNV_nomg\*(C'\fR is the same as \f(CW\*(C`SvNV\*(C'\fR, but does not perform 'get' magic. |
| 24213 |
.RS 4 |
| 24214 |
.Sp |
| 24215 |
.Vb 1 |
| 24216 |
\& NV SvNV(SV *sv) |
| 24217 |
.Ve |
| 24218 |
.RE |
| 24219 |
.RS 4 |
| 24220 |
.RE |
| 24221 |
.ie n .IP """sv_2nv_flags""" 4 |
| 24222 |
.el .IP \f(CWsv_2nv_flags\fR 4 |
| 24223 |
.IX Xref "sv_2nv_flags" |
| 24224 |
.IX Item "sv_2nv_flags" |
| 24225 |
Return the num value of an SV, doing any necessary string or integer |
| 24226 |
conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first. |
| 24227 |
Normally used via the \f(CWSvNV(sv)\fR and \f(CWSvNVx(sv)\fR macros. |
| 24228 |
.RS 4 |
| 24229 |
.Sp |
| 24230 |
.Vb 1 |
| 24231 |
\& NV sv_2nv_flags(SV * const sv, const I32 flags) |
| 24232 |
.Ve |
| 24233 |
.RE |
| 24234 |
.RS 4 |
| 24235 |
.RE |
| 24236 |
.ie n .IP """SvNV_set""" 4 |
| 24237 |
.el .IP \f(CWSvNV_set\fR 4 |
| 24238 |
.IX Xref "SvNV_set" |
| 24239 |
.IX Item "SvNV_set" |
| 24240 |
Set the value of the NV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR. |
| 24241 |
.RS 4 |
| 24242 |
.Sp |
| 24243 |
.Vb 1 |
| 24244 |
\& void SvNV_set(SV* sv, NV val) |
| 24245 |
.Ve |
| 24246 |
.RE |
| 24247 |
.RS 4 |
| 24248 |
.RE |
| 24249 |
.ie n .IP """SvNVX""" 4 |
| 24250 |
.el .IP \f(CWSvNVX\fR 4 |
| 24251 |
.IX Xref "SvNVX" |
| 24252 |
.IX Item "SvNVX" |
| 24253 |
Returns the raw value in the SV's NV slot, without checks or conversions. |
| 24254 |
Only use when you are sure \f(CW\*(C`SvNOK\*(C'\fR is true. See also \f(CW"SvNV"\fR. |
| 24255 |
.RS 4 |
| 24256 |
.Sp |
| 24257 |
.Vb 1 |
| 24258 |
\& NV SvNVX(SV* sv) |
| 24259 |
.Ve |
| 24260 |
.RE |
| 24261 |
.RS 4 |
| 24262 |
.RE |
| 24263 |
.ie n .IP """SvOK""" 4 |
| 24264 |
.el .IP \f(CWSvOK\fR 4 |
| 24265 |
.IX Xref "SvOK" |
| 24266 |
.IX Item "SvOK" |
| 24267 |
Returns a U32 value indicating whether the value is defined. This is |
| 24268 |
only meaningful for scalars. |
| 24269 |
.RS 4 |
| 24270 |
.Sp |
| 24271 |
.Vb 1 |
| 24272 |
\& U32 SvOK(SV* sv) |
| 24273 |
.Ve |
| 24274 |
.RE |
| 24275 |
.RS 4 |
| 24276 |
.RE |
| 24277 |
.ie n .IP """SvOOK""" 4 |
| 24278 |
.el .IP \f(CWSvOOK\fR 4 |
| 24279 |
.IX Xref "SvOOK" |
| 24280 |
.IX Item "SvOOK" |
| 24281 |
Returns a U32 indicating whether the pointer to the string buffer is offset. |
| 24282 |
This hack is used internally to speed up removal of characters from the |
| 24283 |
beginning of a \f(CW"SvPV"\fR. When \f(CW\*(C`SvOOK\*(C'\fR is true, then the start of the |
| 24284 |
allocated string buffer is actually \f(CWSvOOK_offset()\fR bytes before \f(CW\*(C`SvPVX\*(C'\fR. |
| 24285 |
This offset used to be stored in \f(CW\*(C`SvIVX\*(C'\fR, but is now stored within the spare |
| 24286 |
part of the buffer. |
| 24287 |
.RS 4 |
| 24288 |
.Sp |
| 24289 |
.Vb 1 |
| 24290 |
\& U32 SvOOK(SV* sv) |
| 24291 |
.Ve |
| 24292 |
.RE |
| 24293 |
.RS 4 |
| 24294 |
.RE |
| 24295 |
.ie n .IP """SvOOK_off""" 4 |
| 24296 |
.el .IP \f(CWSvOOK_off\fR 4 |
| 24297 |
.IX Xref "SvOOK_off" |
| 24298 |
.IX Item "SvOOK_off" |
| 24299 |
Remove any string offset. |
| 24300 |
.RS 4 |
| 24301 |
.Sp |
| 24302 |
.Vb 1 |
| 24303 |
\& void SvOOK_off(SV * sv) |
| 24304 |
.Ve |
| 24305 |
.RE |
| 24306 |
.RS 4 |
| 24307 |
.RE |
| 24308 |
.ie n .IP """SvOOK_offset""" 4 |
| 24309 |
.el .IP \f(CWSvOOK_offset\fR 4 |
| 24310 |
.IX Xref "SvOOK_offset" |
| 24311 |
.IX Item "SvOOK_offset" |
| 24312 |
Reads into \f(CW\*(C`len\*(C'\fR the offset from \f(CW\*(C`SvPVX\*(C'\fR back to the true start of the |
| 24313 |
allocated buffer, which will be non-zero if \f(CW\*(C`sv_chop\*(C'\fR has been used to |
| 24314 |
efficiently remove characters from start of the buffer. Implemented as a |
| 24315 |
macro, which takes the address of \f(CW\*(C`len\*(C'\fR, which must be of type \f(CW\*(C`STRLEN\*(C'\fR. |
| 24316 |
Evaluates \f(CW\*(C`sv\*(C'\fR more than once. Sets \f(CW\*(C`len\*(C'\fR to 0 if \f(CWSvOOK(sv)\fR is false. |
| 24317 |
.RS 4 |
| 24318 |
.Sp |
| 24319 |
.Vb 1 |
| 24320 |
\& void SvOOK_offset(SV*sv, STRLEN len) |
| 24321 |
.Ve |
| 24322 |
.RE |
| 24323 |
.RS 4 |
| 24324 |
.RE |
| 24325 |
.ie n .IP """SvPOK""" 4 |
| 24326 |
.el .IP \f(CWSvPOK\fR 4 |
| 24327 |
.IX Xref "SvPOK" |
| 24328 |
.IX Item "SvPOK" |
| 24329 |
Returns a U32 value indicating whether the SV contains a character |
| 24330 |
string. |
| 24331 |
.RS 4 |
| 24332 |
.Sp |
| 24333 |
.Vb 1 |
| 24334 |
\& U32 SvPOK(SV* sv) |
| 24335 |
.Ve |
| 24336 |
.RE |
| 24337 |
.RS 4 |
| 24338 |
.RE |
| 24339 |
.ie n .IP """SvPOK_off""" 4 |
| 24340 |
.el .IP \f(CWSvPOK_off\fR 4 |
| 24341 |
.IX Xref "SvPOK_off" |
| 24342 |
.IX Item "SvPOK_off" |
| 24343 |
Unsets the PV status of an SV. |
| 24344 |
.RS 4 |
| 24345 |
.Sp |
| 24346 |
.Vb 1 |
| 24347 |
\& void SvPOK_off(SV* sv) |
| 24348 |
.Ve |
| 24349 |
.RE |
| 24350 |
.RS 4 |
| 24351 |
.RE |
| 24352 |
.ie n .IP """SvPOK_on""" 4 |
| 24353 |
.el .IP \f(CWSvPOK_on\fR 4 |
| 24354 |
.IX Xref "SvPOK_on" |
| 24355 |
.IX Item "SvPOK_on" |
| 24356 |
Tells an SV that it is a string. |
| 24357 |
.RS 4 |
| 24358 |
.Sp |
| 24359 |
.Vb 1 |
| 24360 |
\& void SvPOK_on(SV* sv) |
| 24361 |
.Ve |
| 24362 |
.RE |
| 24363 |
.RS 4 |
| 24364 |
.RE |
| 24365 |
.ie n .IP """SvPOK_only""" 4 |
| 24366 |
.el .IP \f(CWSvPOK_only\fR 4 |
| 24367 |
.IX Xref "SvPOK_only" |
| 24368 |
.IX Item "SvPOK_only" |
| 24369 |
Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits. |
| 24370 |
Will also turn off the UTF\-8 status. |
| 24371 |
.RS 4 |
| 24372 |
.Sp |
| 24373 |
.Vb 1 |
| 24374 |
\& void SvPOK_only(SV* sv) |
| 24375 |
.Ve |
| 24376 |
.RE |
| 24377 |
.RS 4 |
| 24378 |
.RE |
| 24379 |
.ie n .IP """SvPOK_only_UTF8""" 4 |
| 24380 |
.el .IP \f(CWSvPOK_only_UTF8\fR 4 |
| 24381 |
.IX Xref "SvPOK_only_UTF8" |
| 24382 |
.IX Item "SvPOK_only_UTF8" |
| 24383 |
Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits, |
| 24384 |
and leaves the UTF\-8 status as it was. |
| 24385 |
.RS 4 |
| 24386 |
.Sp |
| 24387 |
.Vb 1 |
| 24388 |
\& void SvPOK_only_UTF8(SV* sv) |
| 24389 |
.Ve |
| 24390 |
.RE |
| 24391 |
.RS 4 |
| 24392 |
.RE |
| 24393 |
.ie n .IP """SvPOKp""" 4 |
| 24394 |
.el .IP \f(CWSvPOKp\fR 4 |
| 24395 |
.IX Xref "SvPOKp" |
| 24396 |
.IX Item "SvPOKp" |
| 24397 |
Returns a U32 value indicating whether the SV contains a character string. |
| 24398 |
Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvPOK\*(C'\fR instead. |
| 24399 |
.RS 4 |
| 24400 |
.Sp |
| 24401 |
.Vb 1 |
| 24402 |
\& U32 SvPOKp(SV* sv) |
| 24403 |
.Ve |
| 24404 |
.RE |
| 24405 |
.RS 4 |
| 24406 |
.RE |
| 24407 |
.ie n .IP """sv_pos_b2u""" 4 |
| 24408 |
.el .IP \f(CWsv_pos_b2u\fR 4 |
| 24409 |
.IX Xref "sv_pos_b2u" |
| 24410 |
.IX Item "sv_pos_b2u" |
| 24411 |
Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of bytes from the |
| 24412 |
start of the string, to a count of the equivalent number of UTF\-8 chars. |
| 24413 |
Handles magic and type coercion. |
| 24414 |
.Sp |
| 24415 |
Use \f(CW\*(C`sv_pos_b2u_flags\*(C'\fR in preference, which correctly handles strings |
| 24416 |
longer than 2Gb. |
| 24417 |
.RS 4 |
| 24418 |
.Sp |
| 24419 |
.Vb 1 |
| 24420 |
\& void sv_pos_b2u(SV * const sv, I32 * const offsetp) |
| 24421 |
.Ve |
| 24422 |
.RE |
| 24423 |
.RS 4 |
| 24424 |
.RE |
| 24425 |
.ie n .IP """sv_pos_b2u_flags""" 4 |
| 24426 |
.el .IP \f(CWsv_pos_b2u_flags\fR 4 |
| 24427 |
.IX Xref "sv_pos_b2u_flags" |
| 24428 |
.IX Item "sv_pos_b2u_flags" |
| 24429 |
Converts \f(CW\*(C`offset\*(C'\fR from a count of bytes from the start of the string, to |
| 24430 |
a count of the equivalent number of UTF\-8 chars. Handles type coercion. |
| 24431 |
\&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be |
| 24432 |
\&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic. |
| 24433 |
.RS 4 |
| 24434 |
.Sp |
| 24435 |
.Vb 2 |
| 24436 |
\& STRLEN sv_pos_b2u_flags(SV * const sv, STRLEN const offset, |
| 24437 |
\& U32 flags) |
| 24438 |
.Ve |
| 24439 |
.RE |
| 24440 |
.RS 4 |
| 24441 |
.RE |
| 24442 |
.ie n .IP """sv_pos_u2b""" 4 |
| 24443 |
.el .IP \f(CWsv_pos_u2b\fR 4 |
| 24444 |
.IX Xref "sv_pos_u2b" |
| 24445 |
.IX Item "sv_pos_u2b" |
| 24446 |
Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of UTF\-8 chars from |
| 24447 |
the start of the string, to a count of the equivalent number of bytes; if |
| 24448 |
\&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from |
| 24449 |
the offset, rather than from the start of the string. Handles magic and |
| 24450 |
type coercion. |
| 24451 |
.Sp |
| 24452 |
Use \f(CW\*(C`sv_pos_u2b_flags\*(C'\fR in preference, which correctly handles strings longer |
| 24453 |
than 2Gb. |
| 24454 |
.RS 4 |
| 24455 |
.Sp |
| 24456 |
.Vb 2 |
| 24457 |
\& void sv_pos_u2b(SV * const sv, I32 * const offsetp, |
| 24458 |
\& I32 * const lenp) |
| 24459 |
.Ve |
| 24460 |
.RE |
| 24461 |
.RS 4 |
| 24462 |
.RE |
| 24463 |
.ie n .IP """sv_pos_u2b_flags""" 4 |
| 24464 |
.el .IP \f(CWsv_pos_u2b_flags\fR 4 |
| 24465 |
.IX Xref "sv_pos_u2b_flags" |
| 24466 |
.IX Item "sv_pos_u2b_flags" |
| 24467 |
Converts the offset from a count of UTF\-8 chars from |
| 24468 |
the start of the string, to a count of the equivalent number of bytes; if |
| 24469 |
\&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from |
| 24470 |
\&\f(CW\*(C`offset\*(C'\fR, rather than from the start |
| 24471 |
of the string. Handles type coercion. |
| 24472 |
\&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be |
| 24473 |
\&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic. |
| 24474 |
.RS 4 |
| 24475 |
.Sp |
| 24476 |
.Vb 2 |
| 24477 |
\& STRLEN sv_pos_u2b_flags(SV * const sv, STRLEN uoffset, |
| 24478 |
\& STRLEN * const lenp, U32 flags) |
| 24479 |
.Ve |
| 24480 |
.RE |
| 24481 |
.RS 4 |
| 24482 |
.RE |
| 24483 |
.ie n .IP """SvPV""" 4 |
| 24484 |
.el .IP \f(CWSvPV\fR 4 |
| 24485 |
.IX Item "SvPV" |
| 24486 |
.PD 0 |
| 24487 |
.ie n .IP """SvPV_const""" 4 |
| 24488 |
.el .IP \f(CWSvPV_const\fR 4 |
| 24489 |
.IX Item "SvPV_const" |
| 24490 |
.ie n .IP """SvPV_flags""" 4 |
| 24491 |
.el .IP \f(CWSvPV_flags\fR 4 |
| 24492 |
.IX Item "SvPV_flags" |
| 24493 |
.ie n .IP """SvPV_flags_const""" 4 |
| 24494 |
.el .IP \f(CWSvPV_flags_const\fR 4 |
| 24495 |
.IX Item "SvPV_flags_const" |
| 24496 |
.ie n .IP """SvPV_flags_mutable""" 4 |
| 24497 |
.el .IP \f(CWSvPV_flags_mutable\fR 4 |
| 24498 |
.IX Item "SvPV_flags_mutable" |
| 24499 |
.ie n .IP """SvPV_mutable""" 4 |
| 24500 |
.el .IP \f(CWSvPV_mutable\fR 4 |
| 24501 |
.IX Item "SvPV_mutable" |
| 24502 |
.ie n .IP """SvPV_nolen""" 4 |
| 24503 |
.el .IP \f(CWSvPV_nolen\fR 4 |
| 24504 |
.IX Item "SvPV_nolen" |
| 24505 |
.ie n .IP """SvPV_nolen_const""" 4 |
| 24506 |
.el .IP \f(CWSvPV_nolen_const\fR 4 |
| 24507 |
.IX Item "SvPV_nolen_const" |
| 24508 |
.ie n .IP """SvPV_nomg""" 4 |
| 24509 |
.el .IP \f(CWSvPV_nomg\fR 4 |
| 24510 |
.IX Item "SvPV_nomg" |
| 24511 |
.ie n .IP """SvPV_nomg_const""" 4 |
| 24512 |
.el .IP \f(CWSvPV_nomg_const\fR 4 |
| 24513 |
.IX Item "SvPV_nomg_const" |
| 24514 |
.ie n .IP """SvPV_nomg_const_nolen""" 4 |
| 24515 |
.el .IP \f(CWSvPV_nomg_const_nolen\fR 4 |
| 24516 |
.IX Item "SvPV_nomg_const_nolen" |
| 24517 |
.ie n .IP """SvPV_nomg_nolen""" 4 |
| 24518 |
.el .IP \f(CWSvPV_nomg_nolen\fR 4 |
| 24519 |
.IX Item "SvPV_nomg_nolen" |
| 24520 |
.ie n .IP """SvPVbyte""" 4 |
| 24521 |
.el .IP \f(CWSvPVbyte\fR 4 |
| 24522 |
.IX Item "SvPVbyte" |
| 24523 |
.ie n .IP """SvPVbyte_nolen""" 4 |
| 24524 |
.el .IP \f(CWSvPVbyte_nolen\fR 4 |
| 24525 |
.IX Item "SvPVbyte_nolen" |
| 24526 |
.ie n .IP """SvPVbyte_nomg""" 4 |
| 24527 |
.el .IP \f(CWSvPVbyte_nomg\fR 4 |
| 24528 |
.IX Item "SvPVbyte_nomg" |
| 24529 |
.ie n .IP """SvPVbyte_or_null""" 4 |
| 24530 |
.el .IP \f(CWSvPVbyte_or_null\fR 4 |
| 24531 |
.IX Item "SvPVbyte_or_null" |
| 24532 |
.ie n .IP """SvPVbyte_or_null_nomg""" 4 |
| 24533 |
.el .IP \f(CWSvPVbyte_or_null_nomg\fR 4 |
| 24534 |
.IX Item "SvPVbyte_or_null_nomg" |
| 24535 |
.ie n .IP """SvPVbytex""" 4 |
| 24536 |
.el .IP \f(CWSvPVbytex\fR 4 |
| 24537 |
.IX Item "SvPVbytex" |
| 24538 |
.ie n .IP """SvPVbytex_nolen""" 4 |
| 24539 |
.el .IP \f(CWSvPVbytex_nolen\fR 4 |
| 24540 |
.IX Item "SvPVbytex_nolen" |
| 24541 |
.ie n .IP """SvPVutf8""" 4 |
| 24542 |
.el .IP \f(CWSvPVutf8\fR 4 |
| 24543 |
.IX Item "SvPVutf8" |
| 24544 |
.ie n .IP """SvPVutf8_nolen""" 4 |
| 24545 |
.el .IP \f(CWSvPVutf8_nolen\fR 4 |
| 24546 |
.IX Item "SvPVutf8_nolen" |
| 24547 |
.ie n .IP """SvPVutf8_nomg""" 4 |
| 24548 |
.el .IP \f(CWSvPVutf8_nomg\fR 4 |
| 24549 |
.IX Item "SvPVutf8_nomg" |
| 24550 |
.ie n .IP """SvPVutf8_or_null""" 4 |
| 24551 |
.el .IP \f(CWSvPVutf8_or_null\fR 4 |
| 24552 |
.IX Item "SvPVutf8_or_null" |
| 24553 |
.ie n .IP """SvPVutf8_or_null_nomg""" 4 |
| 24554 |
.el .IP \f(CWSvPVutf8_or_null_nomg\fR 4 |
| 24555 |
.IX Item "SvPVutf8_or_null_nomg" |
| 24556 |
.ie n .IP """SvPVutf8x""" 4 |
| 24557 |
.el .IP \f(CWSvPVutf8x\fR 4 |
| 24558 |
.IX Item "SvPVutf8x" |
| 24559 |
.ie n .IP """SvPVx""" 4 |
| 24560 |
.el .IP \f(CWSvPVx\fR 4 |
| 24561 |
.IX Item "SvPVx" |
| 24562 |
.ie n .IP """SvPVx_const""" 4 |
| 24563 |
.el .IP \f(CWSvPVx_const\fR 4 |
| 24564 |
.IX Item "SvPVx_const" |
| 24565 |
.ie n .IP """SvPVx_nolen""" 4 |
| 24566 |
.el .IP \f(CWSvPVx_nolen\fR 4 |
| 24567 |
.IX Item "SvPVx_nolen" |
| 24568 |
.ie n .IP """SvPVx_nolen_const""" 4 |
| 24569 |
.el .IP \f(CWSvPVx_nolen_const\fR 4 |
| 24570 |
.IX Xref "SvPV SvPV_const SvPV_flags SvPV_flags_const SvPV_flags_mutable SvPV_mutable SvPV_nolen SvPV_nolen_const SvPV_nomg SvPV_nomg_const SvPV_nomg_const_nolen SvPV_nomg_nolen SvPVbyte SvPVbyte_nolen SvPVbyte_nomg SvPVbyte_or_null SvPVbyte_or_null_nomg SvPVbytex SvPVbytex_nolen SvPVutf8 SvPVutf8_nolen SvPVutf8_nomg SvPVutf8_or_null SvPVutf8_or_null_nomg SvPVutf8x SvPVx SvPVx_const SvPVx_nolen SvPVx_nolen_const" |
| 24571 |
.IX Item "SvPVx_nolen_const" |
| 24572 |
.PD |
| 24573 |
These each return a pointer to the string in \f(CW\*(C`sv\*(C'\fR, or a stringified form of |
| 24574 |
\&\f(CW\*(C`sv\*(C'\fR if it does not contain a string. The SV may cache the stringified |
| 24575 |
version becoming \f(CW\*(C`SvPOK\*(C'\fR. |
| 24576 |
.Sp |
| 24577 |
This is a very basic and common operation, so there are lots of slightly |
| 24578 |
different versions of it. |
| 24579 |
.Sp |
| 24580 |
Note that there is no guarantee that the return value of \f(CWSvPV(sv)\fR, for |
| 24581 |
example, is equal to \f(CWSvPVX(sv)\fR, or that \f(CWSvPVX(sv)\fR contains valid data, or |
| 24582 |
that successive calls to \f(CWSvPV(sv)\fR (or another of these forms) will return |
| 24583 |
the same pointer value each time. This is due to the way that things like |
| 24584 |
overloading and Copy-On-Write are handled. In these cases, the return value |
| 24585 |
may point to a temporary buffer or similar. If you absolutely need the |
| 24586 |
\&\f(CW\*(C`SvPVX\*(C'\fR field to be valid (for example, if you intend to write to it), then |
| 24587 |
see \f(CW"SvPV_force"\fR. |
| 24588 |
.Sp |
| 24589 |
The differences between the forms are: |
| 24590 |
.Sp |
| 24591 |
The forms with neither \f(CW\*(C`byte\*(C'\fR nor \f(CW\*(C`utf8\*(C'\fR in their names (e.g., \f(CW\*(C`SvPV\*(C'\fR or |
| 24592 |
\&\f(CW\*(C`SvPV_nolen\*(C'\fR) can expose the SV's internal string buffer. If |
| 24593 |
that buffer consists entirely of bytes 0\-255 and includes any bytes above |
| 24594 |
127, then you \fBMUST\fR consult \f(CW\*(C`SvUTF8\*(C'\fR to determine the actual code points |
| 24595 |
the string is meant to contain. Generally speaking, it is probably safer to |
| 24596 |
prefer \f(CW\*(C`SvPVbyte\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR, and the like. See |
| 24597 |
"How do I pass a Perl string to a C library?" in perlguts for more details. |
| 24598 |
.Sp |
| 24599 |
The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter |
| 24600 |
to specify to process 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip |
| 24601 |
\&'get' magic (by clearing it). The other forms process 'get' magic, except for |
| 24602 |
the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic. |
| 24603 |
.Sp |
| 24604 |
The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte |
| 24605 |
length of the resultant string (these are macros, so don't use \f(CW&len\fR). |
| 24606 |
.Sp |
| 24607 |
The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR |
| 24608 |
parameter. They should be used only when it is known that the PV is a C |
| 24609 |
string, terminated by a NUL byte, and without intermediate NUL characters; or |
| 24610 |
when you don't care about its length. |
| 24611 |
.Sp |
| 24612 |
The forms with \f(CW\*(C`const\*(C'\fR in their names return \f(CW\*(C`const\ char\ *\*(C'\fR so that the |
| 24613 |
compiler will hopefully complain if you were to try to modify the contents of |
| 24614 |
the string (unless you cast away const yourself). |
| 24615 |
.Sp |
| 24616 |
The other forms return a mutable pointer so that the string is modifiable by |
| 24617 |
the caller; this is emphasized for the ones with \f(CW\*(C`mutable\*(C'\fR in their names. |
| 24618 |
.Sp |
| 24619 |
As of 5.38, all forms are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR exactly once. For |
| 24620 |
earlier Perls, use a form whose name ends with \f(CW\*(C`x\*(C'\fR for single evaluation. |
| 24621 |
.Sp |
| 24622 |
\&\f(CW\*(C`SvPVutf8\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if not already |
| 24623 |
UTF\-8. Similarly, the other forms with \f(CW\*(C`utf8\*(C'\fR in their names correspond to |
| 24624 |
their respective forms without. |
| 24625 |
.Sp |
| 24626 |
\&\f(CW\*(C`SvPVutf8_or_null\*(C'\fR and \f(CW\*(C`SvPVutf8_or_null_nomg\*(C'\fR don't have corresponding |
| 24627 |
non\-\f(CW\*(C`utf8\*(C'\fR forms. Instead they are like \f(CW\*(C`SvPVutf8_nomg\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is |
| 24628 |
undef, they return \f(CW\*(C`NULL\*(C'\fR. |
| 24629 |
.Sp |
| 24630 |
\&\f(CW\*(C`SvPVbyte\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte representation first if |
| 24631 |
currently encoded as UTF\-8. If \f(CW\*(C`sv\*(C'\fR cannot be downgraded from UTF\-8, it |
| 24632 |
croaks. Similarly, the other forms with \f(CW\*(C`byte\*(C'\fR in their names correspond to |
| 24633 |
their respective forms without. |
| 24634 |
.Sp |
| 24635 |
\&\f(CW\*(C`SvPVbyte_or_null\*(C'\fR doesn't have a corresponding non\-\f(CW\*(C`byte\*(C'\fR form. Instead it |
| 24636 |
is like \f(CW\*(C`SvPVbyte\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is undef, it returns \f(CW\*(C`NULL\*(C'\fR. |
| 24637 |
.RS 4 |
| 24638 |
.Sp |
| 24639 |
.Vb 10 |
| 24640 |
\& char* SvPV (SV* sv, STRLEN len) |
| 24641 |
\& const char* SvPV_const (SV* sv, STRLEN len) |
| 24642 |
\& char* SvPV_flags (SV* sv, STRLEN len, U32 flags) |
| 24643 |
\& const char* SvPV_flags_const (SV* sv, STRLEN len, U32 flags) |
| 24644 |
\& char* SvPV_flags_mutable (SV* sv, STRLEN len, U32 flags) |
| 24645 |
\& char* SvPV_mutable (SV* sv, STRLEN len) |
| 24646 |
\& char* SvPV_nolen (SV* sv) |
| 24647 |
\& const char* SvPV_nolen_const (SV* sv) |
| 24648 |
\& char* SvPV_nomg (SV* sv, STRLEN len) |
| 24649 |
\& const char* SvPV_nomg_const (SV* sv, STRLEN len) |
| 24650 |
\& const char* SvPV_nomg_const_nolen(SV* sv) |
| 24651 |
\& char* SvPV_nomg_nolen (SV* sv) |
| 24652 |
\& char* SvPVbyte (SV* sv, STRLEN len) |
| 24653 |
\& char* SvPVbyte_nolen (SV* sv) |
| 24654 |
\& char* SvPVbyte_nomg (SV* sv, STRLEN len) |
| 24655 |
\& char* SvPVbyte_or_null (SV* sv, STRLEN len) |
| 24656 |
\& char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len) |
| 24657 |
\& char* SvPVbytex (SV* sv, STRLEN len) |
| 24658 |
\& char* SvPVbytex_nolen (SV* sv) |
| 24659 |
\& char* SvPVutf8 (SV* sv, STRLEN len) |
| 24660 |
\& char* SvPVutf8_nolen (SV* sv) |
| 24661 |
\& char* SvPVutf8_nomg (SV* sv, STRLEN len) |
| 24662 |
\& char* SvPVutf8_or_null (SV* sv, STRLEN len) |
| 24663 |
\& char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len) |
| 24664 |
\& char* SvPVutf8x (SV* sv, STRLEN len) |
| 24665 |
\& char* SvPVx (SV* sv, STRLEN len) |
| 24666 |
\& const char* SvPVx_const (SV* sv, STRLEN len) |
| 24667 |
\& char* SvPVx_nolen (SV* sv) |
| 24668 |
\& const char* SvPVx_nolen_const (SV* sv) |
| 24669 |
.Ve |
| 24670 |
.RE |
| 24671 |
.RS 4 |
| 24672 |
.RE |
| 24673 |
.ie n .IP """sv_2pv""" 4 |
| 24674 |
.el .IP \f(CWsv_2pv\fR 4 |
| 24675 |
.IX Item "sv_2pv" |
| 24676 |
.PD 0 |
| 24677 |
.ie n .IP """sv_2pv_flags""" 4 |
| 24678 |
.el .IP \f(CWsv_2pv_flags\fR 4 |
| 24679 |
.IX Xref "sv_2pv sv_2pv_flags" |
| 24680 |
.IX Item "sv_2pv_flags" |
| 24681 |
.PD |
| 24682 |
These implement the various forms of the "\f(CW\*(C`SvPV\*(C'\fR" in perlapi macros. |
| 24683 |
The macros are the preferred interface. |
| 24684 |
.Sp |
| 24685 |
These return a pointer to the string value of an SV (coercing it to a string if |
| 24686 |
necessary), and set \f(CW*lp\fR to its length in bytes. |
| 24687 |
.Sp |
| 24688 |
The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and |
| 24689 |
\&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains |
| 24690 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR. |
| 24691 |
.RS 4 |
| 24692 |
.Sp |
| 24693 |
.Vb 3 |
| 24694 |
\& char * sv_2pv (SV *sv, STRLEN *lp) |
| 24695 |
\& char * sv_2pv_flags(SV * const sv, STRLEN * const lp, |
| 24696 |
\& const U32 flags) |
| 24697 |
.Ve |
| 24698 |
.RE |
| 24699 |
.RS 4 |
| 24700 |
.RE |
| 24701 |
.ie n .IP """sv_2pvbyte""" 4 |
| 24702 |
.el .IP \f(CWsv_2pvbyte\fR 4 |
| 24703 |
.IX Item "sv_2pvbyte" |
| 24704 |
.PD 0 |
| 24705 |
.ie n .IP """sv_2pvbyte_flags""" 4 |
| 24706 |
.el .IP \f(CWsv_2pvbyte_flags\fR 4 |
| 24707 |
.IX Xref "sv_2pvbyte sv_2pvbyte_flags" |
| 24708 |
.IX Item "sv_2pvbyte_flags" |
| 24709 |
.PD |
| 24710 |
These implement the various forms of the "\f(CW\*(C`SvPVbyte\*(C'\fR" in perlapi macros. |
| 24711 |
The macros are the preferred interface. |
| 24712 |
.Sp |
| 24713 |
These return a pointer to the byte-encoded representation of the SV, and set |
| 24714 |
\&\f(CW*lp\fR to its length. If the SV is marked as being encoded as UTF\-8, it will |
| 24715 |
be downgraded, if possible, to a byte string. If the SV cannot be downgraded, |
| 24716 |
they croak. |
| 24717 |
.Sp |
| 24718 |
The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and |
| 24719 |
\&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains |
| 24720 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR. |
| 24721 |
.RS 4 |
| 24722 |
.Sp |
| 24723 |
.Vb 3 |
| 24724 |
\& char * sv_2pvbyte (SV *sv, STRLEN * const lp) |
| 24725 |
\& char * sv_2pvbyte_flags(SV *sv, STRLEN * const lp, |
| 24726 |
\& const U32 flags) |
| 24727 |
.Ve |
| 24728 |
.RE |
| 24729 |
.RS 4 |
| 24730 |
.RE |
| 24731 |
.ie n .IP """SvPVCLEAR""" 4 |
| 24732 |
.el .IP \f(CWSvPVCLEAR\fR 4 |
| 24733 |
.IX Xref "SvPVCLEAR" |
| 24734 |
.IX Item "SvPVCLEAR" |
| 24735 |
Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is |
| 24736 |
properly null terminated. Equivalent to sv_setpvs(""), but more efficient. |
| 24737 |
.RS 4 |
| 24738 |
.Sp |
| 24739 |
.Vb 1 |
| 24740 |
\& char * SvPVCLEAR(SV* sv) |
| 24741 |
.Ve |
| 24742 |
.RE |
| 24743 |
.RS 4 |
| 24744 |
.RE |
| 24745 |
.ie n .IP """SvPVCLEAR_FRESH""" 4 |
| 24746 |
.el .IP \f(CWSvPVCLEAR_FRESH\fR 4 |
| 24747 |
.IX Xref "SvPVCLEAR_FRESH" |
| 24748 |
.IX Item "SvPVCLEAR_FRESH" |
| 24749 |
Like SvPVCLEAR, but optimized for newly-minted SVt_PV/PVIV/PVNV/PVMG |
| 24750 |
that already have a PV buffer allocated, but no SvTHINKFIRST. |
| 24751 |
.RS 4 |
| 24752 |
.Sp |
| 24753 |
.Vb 1 |
| 24754 |
\& char * SvPVCLEAR_FRESH(SV* sv) |
| 24755 |
.Ve |
| 24756 |
.RE |
| 24757 |
.RS 4 |
| 24758 |
.RE |
| 24759 |
.ie n .IP """SvPV_force""" 4 |
| 24760 |
.el .IP \f(CWSvPV_force\fR 4 |
| 24761 |
.IX Item "SvPV_force" |
| 24762 |
.PD 0 |
| 24763 |
.ie n .IP """SvPV_force_flags""" 4 |
| 24764 |
.el .IP \f(CWSvPV_force_flags\fR 4 |
| 24765 |
.IX Item "SvPV_force_flags" |
| 24766 |
.ie n .IP """SvPV_force_flags_mutable""" 4 |
| 24767 |
.el .IP \f(CWSvPV_force_flags_mutable\fR 4 |
| 24768 |
.IX Item "SvPV_force_flags_mutable" |
| 24769 |
.ie n .IP """SvPV_force_flags_nolen""" 4 |
| 24770 |
.el .IP \f(CWSvPV_force_flags_nolen\fR 4 |
| 24771 |
.IX Item "SvPV_force_flags_nolen" |
| 24772 |
.ie n .IP """SvPV_force_mutable""" 4 |
| 24773 |
.el .IP \f(CWSvPV_force_mutable\fR 4 |
| 24774 |
.IX Item "SvPV_force_mutable" |
| 24775 |
.ie n .IP """SvPV_force_nolen""" 4 |
| 24776 |
.el .IP \f(CWSvPV_force_nolen\fR 4 |
| 24777 |
.IX Item "SvPV_force_nolen" |
| 24778 |
.ie n .IP """SvPV_force_nomg""" 4 |
| 24779 |
.el .IP \f(CWSvPV_force_nomg\fR 4 |
| 24780 |
.IX Item "SvPV_force_nomg" |
| 24781 |
.ie n .IP """SvPV_force_nomg_nolen""" 4 |
| 24782 |
.el .IP \f(CWSvPV_force_nomg_nolen\fR 4 |
| 24783 |
.IX Item "SvPV_force_nomg_nolen" |
| 24784 |
.ie n .IP """SvPVbyte_force""" 4 |
| 24785 |
.el .IP \f(CWSvPVbyte_force\fR 4 |
| 24786 |
.IX Item "SvPVbyte_force" |
| 24787 |
.ie n .IP """SvPVbytex_force""" 4 |
| 24788 |
.el .IP \f(CWSvPVbytex_force\fR 4 |
| 24789 |
.IX Item "SvPVbytex_force" |
| 24790 |
.ie n .IP """SvPVutf8_force""" 4 |
| 24791 |
.el .IP \f(CWSvPVutf8_force\fR 4 |
| 24792 |
.IX Item "SvPVutf8_force" |
| 24793 |
.ie n .IP """SvPVutf8x_force""" 4 |
| 24794 |
.el .IP \f(CWSvPVutf8x_force\fR 4 |
| 24795 |
.IX Item "SvPVutf8x_force" |
| 24796 |
.ie n .IP """SvPVx_force""" 4 |
| 24797 |
.el .IP \f(CWSvPVx_force\fR 4 |
| 24798 |
.IX Xref "SvPV_force SvPV_force_flags SvPV_force_flags_mutable SvPV_force_flags_nolen SvPV_force_mutable SvPV_force_nolen SvPV_force_nomg SvPV_force_nomg_nolen SvPVbyte_force SvPVbytex_force SvPVutf8_force SvPVutf8x_force SvPVx_force" |
| 24799 |
.IX Item "SvPVx_force" |
| 24800 |
.PD |
| 24801 |
These are like \f(CW"SvPV"\fR, returning the string in the SV, but will force the |
| 24802 |
SV into containing a string (\f(CW"SvPOK"\fR), and only a string |
| 24803 |
(\f(CW"SvPOK_only"\fR), by hook or by crook. You need to use one of these |
| 24804 |
\&\f(CW\*(C`force\*(C'\fR routines if you are going to update the \f(CW"SvPVX"\fR directly. |
| 24805 |
.Sp |
| 24806 |
Note that coercing an arbitrary scalar into a plain PV will potentially |
| 24807 |
strip useful data from it. For example if the SV was \f(CW\*(C`SvROK\*(C'\fR, then the |
| 24808 |
referent will have its reference count decremented, and the SV itself may |
| 24809 |
be converted to an \f(CW\*(C`SvPOK\*(C'\fR scalar with a string buffer containing a value |
| 24810 |
such as \f(CW"ARRAY(0x1234)"\fR. |
| 24811 |
.Sp |
| 24812 |
The differences between the forms are: |
| 24813 |
.Sp |
| 24814 |
The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter |
| 24815 |
to specify to perform 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip |
| 24816 |
\&'get' magic (by clearing it). The other forms do perform 'get' magic, except |
| 24817 |
for the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic. |
| 24818 |
.Sp |
| 24819 |
The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte |
| 24820 |
length of the resultant string (these are macros, so don't use \f(CW&len\fR). |
| 24821 |
.Sp |
| 24822 |
The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR |
| 24823 |
parameter. They should be used only when it is known that the PV is a C |
| 24824 |
string, terminated by a NUL byte, and without intermediate NUL characters; or |
| 24825 |
when you don't care about its length. |
| 24826 |
.Sp |
| 24827 |
The forms with \f(CW\*(C`mutable\*(C'\fR in their names are effectively the same as those without, |
| 24828 |
but the name emphasizes that the string is modifiable by the caller, which it is |
| 24829 |
in all the forms. |
| 24830 |
.Sp |
| 24831 |
\&\f(CW\*(C`SvPVutf8_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if |
| 24832 |
not already UTF\-8. |
| 24833 |
.Sp |
| 24834 |
\&\f(CW\*(C`SvPVutf8x_force\*(C'\fR is like \f(CW\*(C`SvPVutf8_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR |
| 24835 |
only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR otherwise. |
| 24836 |
.Sp |
| 24837 |
\&\f(CW\*(C`SvPVbyte_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte |
| 24838 |
representation first if currently encoded as UTF\-8. If the SV cannot be |
| 24839 |
downgraded from UTF\-8, this croaks. |
| 24840 |
.Sp |
| 24841 |
\&\f(CW\*(C`SvPVbytex_force\*(C'\fR is like \f(CW\*(C`SvPVbyte_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR |
| 24842 |
only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR otherwise. |
| 24843 |
.RS 4 |
| 24844 |
.Sp |
| 24845 |
.Vb 10 |
| 24846 |
\& char* SvPV_force (SV* sv, STRLEN len) |
| 24847 |
\& char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags) |
| 24848 |
\& char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags) |
| 24849 |
\& char* SvPV_force_flags_nolen (SV * sv, U32 flags) |
| 24850 |
\& char* SvPV_force_mutable (SV * sv, STRLEN len) |
| 24851 |
\& char* SvPV_force_nolen (SV* sv) |
| 24852 |
\& char* SvPV_force_nomg (SV* sv, STRLEN len) |
| 24853 |
\& char* SvPV_force_nomg_nolen (SV * sv) |
| 24854 |
\& char* SvPVbyte_force (SV * sv, STRLEN len) |
| 24855 |
\& char* SvPVbytex_force (SV * sv, STRLEN len) |
| 24856 |
\& char* SvPVutf8_force (SV * sv, STRLEN len) |
| 24857 |
\& char* SvPVutf8x_force (SV * sv, STRLEN len) |
| 24858 |
\& char* SvPVx_force (SV* sv, STRLEN len) |
| 24859 |
.Ve |
| 24860 |
.RE |
| 24861 |
.RS 4 |
| 24862 |
.RE |
| 24863 |
.ie n .IP """SvPV_free""" 4 |
| 24864 |
.el .IP \f(CWSvPV_free\fR 4 |
| 24865 |
.IX Xref "SvPV_free" |
| 24866 |
.IX Item "SvPV_free" |
| 24867 |
Frees the PV buffer in \f(CW\*(C`sv\*(C'\fR, leaving things in a precarious state, so should |
| 24868 |
only be used as part of a larger operation |
| 24869 |
.RS 4 |
| 24870 |
.Sp |
| 24871 |
.Vb 1 |
| 24872 |
\& void SvPV_free(SV * sv) |
| 24873 |
.Ve |
| 24874 |
.RE |
| 24875 |
.RS 4 |
| 24876 |
.RE |
| 24877 |
.ie n .IP """sv_pvn_force_flags""" 4 |
| 24878 |
.el .IP \f(CWsv_pvn_force_flags\fR 4 |
| 24879 |
.IX Xref "sv_pvn_force_flags" |
| 24880 |
.IX Item "sv_pvn_force_flags" |
| 24881 |
Get a sensible string out of the SV somehow. |
| 24882 |
If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW"mg_get"\fR on \f(CW\*(C`sv\*(C'\fR if |
| 24883 |
appropriate, else not. \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are |
| 24884 |
implemented in terms of this function. |
| 24885 |
You normally want to use the various wrapper macros instead: see |
| 24886 |
\&\f(CW"SvPV_force"\fR and \f(CW"SvPV_force_nomg"\fR. |
| 24887 |
.RS 4 |
| 24888 |
.Sp |
| 24889 |
.Vb 2 |
| 24890 |
\& char * sv_pvn_force_flags(SV * const sv, STRLEN * const lp, |
| 24891 |
\& const U32 flags) |
| 24892 |
.Ve |
| 24893 |
.RE |
| 24894 |
.RS 4 |
| 24895 |
.RE |
| 24896 |
.ie n .IP """SvPV_renew""" 4 |
| 24897 |
.el .IP \f(CWSvPV_renew\fR 4 |
| 24898 |
.IX Xref "SvPV_renew" |
| 24899 |
.IX Item "SvPV_renew" |
| 24900 |
Low level micro optimization of \f(CW"SvGROW"\fR. It is generally better to use |
| 24901 |
\&\f(CW\*(C`SvGROW\*(C'\fR instead. This is because \f(CW\*(C`SvPV_renew\*(C'\fR ignores potential issues that |
| 24902 |
\&\f(CW\*(C`SvGROW\*(C'\fR handles. \f(CW\*(C`sv\*(C'\fR needs to have a real \f(CW\*(C`PV\*(C'\fR that is unencumbered by |
| 24903 |
things like COW. Using \f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR or |
| 24904 |
\&\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR before calling this should clean it up, but |
| 24905 |
why not just use \f(CW\*(C`SvGROW\*(C'\fR if you're not sure about the provenance? |
| 24906 |
.RS 4 |
| 24907 |
.Sp |
| 24908 |
.Vb 1 |
| 24909 |
\& void SvPV_renew(SV* sv, STRLEN len) |
| 24910 |
.Ve |
| 24911 |
.RE |
| 24912 |
.RS 4 |
| 24913 |
.RE |
| 24914 |
.ie n .IP """SvPV_set""" 4 |
| 24915 |
.el .IP \f(CWSvPV_set\fR 4 |
| 24916 |
.IX Xref "SvPV_set" |
| 24917 |
.IX Item "SvPV_set" |
| 24918 |
This is probably not what you want to use, you probably wanted |
| 24919 |
"sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs". |
| 24920 |
.Sp |
| 24921 |
Set the value of the PV pointer in \f(CW\*(C`sv\*(C'\fR to the Perl allocated |
| 24922 |
\&\f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`val\*(C'\fR. See also \f(CW"SvIV_set"\fR. |
| 24923 |
.Sp |
| 24924 |
Remember to free the previous PV buffer. There are many things to check. |
| 24925 |
Beware that the existing pointer may be involved in copy-on-write or other |
| 24926 |
mischief, so do \f(CWSvOOK_off(sv)\fR and use \f(CW\*(C`sv_force_normal\*(C'\fR or |
| 24927 |
\&\f(CW\*(C`SvPV_force\*(C'\fR (or check the \f(CW\*(C`SvIsCOW\*(C'\fR flag) first to make sure this |
| 24928 |
modification is safe. Then finally, if it is not a COW, call |
| 24929 |
\&\f(CW"SvPV_free"\fR to free the previous PV buffer. |
| 24930 |
.RS 4 |
| 24931 |
.Sp |
| 24932 |
.Vb 1 |
| 24933 |
\& void SvPV_set(SV* sv, char* val) |
| 24934 |
.Ve |
| 24935 |
.RE |
| 24936 |
.RS 4 |
| 24937 |
.RE |
| 24938 |
.ie n .IP """SvPV_shrink_to_cur""" 4 |
| 24939 |
.el .IP \f(CWSvPV_shrink_to_cur\fR 4 |
| 24940 |
.IX Xref "SvPV_shrink_to_cur" |
| 24941 |
.IX Item "SvPV_shrink_to_cur" |
| 24942 |
Trim any trailing unused memory in the PV of \f(CW\*(C`sv\*(C'\fR, which needs to have a real |
| 24943 |
\&\f(CW\*(C`PV\*(C'\fR that is unencumbered by things like COW. Think first before using this |
| 24944 |
functionality. Is the space saving really worth giving up COW? Will the |
| 24945 |
needed size of \f(CW\*(C`sv\*(C'\fR stay the same? |
| 24946 |
.Sp |
| 24947 |
If the answers are both yes, then use "\f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR" or |
| 24948 |
"\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" before calling this. |
| 24949 |
.RS 4 |
| 24950 |
.Sp |
| 24951 |
.Vb 1 |
| 24952 |
\& void SvPV_shrink_to_cur(SV* sv) |
| 24953 |
.Ve |
| 24954 |
.RE |
| 24955 |
.RS 4 |
| 24956 |
.RE |
| 24957 |
.ie n .IP """sv_2pvutf8""" 4 |
| 24958 |
.el .IP \f(CWsv_2pvutf8\fR 4 |
| 24959 |
.IX Item "sv_2pvutf8" |
| 24960 |
.PD 0 |
| 24961 |
.ie n .IP """sv_2pvutf8_flags""" 4 |
| 24962 |
.el .IP \f(CWsv_2pvutf8_flags\fR 4 |
| 24963 |
.IX Xref "sv_2pvutf8 sv_2pvutf8_flags" |
| 24964 |
.IX Item "sv_2pvutf8_flags" |
| 24965 |
.PD |
| 24966 |
These implement the various forms of the "\f(CW\*(C`SvPVutf8\*(C'\fR" in perlapi macros. |
| 24967 |
The macros are the preferred interface. |
| 24968 |
.Sp |
| 24969 |
These return a pointer to the UTF\-8\-encoded representation of the SV, and set |
| 24970 |
\&\f(CW*lp\fR to its length in bytes. They may cause the SV to be upgraded to UTF\-8 |
| 24971 |
as a side-effect. |
| 24972 |
.Sp |
| 24973 |
The forms differ in that plain \f(CW\*(C`sv_2pvutf8\*(C'\fR always processes 'get' magic; and |
| 24974 |
\&\f(CW\*(C`sv_2pvutf8_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains |
| 24975 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR. |
| 24976 |
.RS 4 |
| 24977 |
.Sp |
| 24978 |
.Vb 3 |
| 24979 |
\& char * sv_2pvutf8 (SV *sv, STRLEN * const lp) |
| 24980 |
\& char * sv_2pvutf8_flags(SV *sv, STRLEN * const lp, |
| 24981 |
\& const U32 flags) |
| 24982 |
.Ve |
| 24983 |
.RE |
| 24984 |
.RS 4 |
| 24985 |
.RE |
| 24986 |
.ie n .IP """SvPVX""" 4 |
| 24987 |
.el .IP \f(CWSvPVX\fR 4 |
| 24988 |
.IX Item "SvPVX" |
| 24989 |
.PD 0 |
| 24990 |
.ie n .IP """SvPVX_const""" 4 |
| 24991 |
.el .IP \f(CWSvPVX_const\fR 4 |
| 24992 |
.IX Item "SvPVX_const" |
| 24993 |
.ie n .IP """SvPVX_mutable""" 4 |
| 24994 |
.el .IP \f(CWSvPVX_mutable\fR 4 |
| 24995 |
.IX Item "SvPVX_mutable" |
| 24996 |
.ie n .IP """SvPVXx""" 4 |
| 24997 |
.el .IP \f(CWSvPVXx\fR 4 |
| 24998 |
.IX Xref "SvPVX SvPVX_const SvPVX_mutable SvPVXx" |
| 24999 |
.IX Item "SvPVXx" |
| 25000 |
.PD |
| 25001 |
These return a pointer to the physical string in the SV. The SV must contain a |
| 25002 |
string. Prior to 5.9.3 it is not safe to execute these unless the SV's |
| 25003 |
type >= \f(CW\*(C`SVt_PV\*(C'\fR. |
| 25004 |
.Sp |
| 25005 |
These are also used to store the name of an autoloaded subroutine in an XS |
| 25006 |
AUTOLOAD routine. See "Autoloading with XSUBs" in perlguts. |
| 25007 |
.Sp |
| 25008 |
\&\f(CW\*(C`SvPVXx\*(C'\fR is identical to \f(CW\*(C`SvPVX\*(C'\fR. |
| 25009 |
.Sp |
| 25010 |
\&\f(CW\*(C`SvPVX_mutable\*(C'\fR is merely a synonym for \f(CW\*(C`SvPVX\*(C'\fR, but its name emphasizes that |
| 25011 |
the string is modifiable by the caller. |
| 25012 |
.Sp |
| 25013 |
\&\f(CW\*(C`SvPVX_const\*(C'\fR differs in that the return value has been cast so that the |
| 25014 |
compiler will complain if you were to try to modify the contents of the string, |
| 25015 |
(unless you cast away const yourself). |
| 25016 |
.RS 4 |
| 25017 |
.Sp |
| 25018 |
.Vb 4 |
| 25019 |
\& char* SvPVX (SV* sv) |
| 25020 |
\& const char* SvPVX_const (SV* sv) |
| 25021 |
\& char* SvPVX_mutable(SV* sv) |
| 25022 |
\& char* SvPVXx (SV* sv) |
| 25023 |
.Ve |
| 25024 |
.RE |
| 25025 |
.RS 4 |
| 25026 |
.RE |
| 25027 |
.ie n .IP """SvPVXtrue""" 4 |
| 25028 |
.el .IP \f(CWSvPVXtrue\fR 4 |
| 25029 |
.IX Xref "SvPVXtrue" |
| 25030 |
.IX Item "SvPVXtrue" |
| 25031 |
Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR contains a PV that is considered |
| 25032 |
TRUE. FALSE is returned if \f(CW\*(C`sv\*(C'\fR doesn't contain a PV, or if the PV it does |
| 25033 |
contain is zero length, or consists of just the single character '0'. Every |
| 25034 |
other PV value is considered TRUE. |
| 25035 |
.Sp |
| 25036 |
As of Perl v5.37.1, \f(CW\*(C`sv\*(C'\fR is evaluated exactly once; in earlier releases, it |
| 25037 |
could be evaluated more than once. |
| 25038 |
.RS 4 |
| 25039 |
.Sp |
| 25040 |
.Vb 1 |
| 25041 |
\& bool SvPVXtrue(SV *sv) |
| 25042 |
.Ve |
| 25043 |
.RE |
| 25044 |
.RS 4 |
| 25045 |
.RE |
| 25046 |
.ie n .IP """SvREADONLY""" 4 |
| 25047 |
.el .IP \f(CWSvREADONLY\fR 4 |
| 25048 |
.IX Xref "SvREADONLY" |
| 25049 |
.IX Item "SvREADONLY" |
| 25050 |
Returns true if the argument is readonly, otherwise returns false. |
| 25051 |
Exposed to perl code via \fBInternals::SvREADONLY()\fR. |
| 25052 |
.RS 4 |
| 25053 |
.Sp |
| 25054 |
.Vb 1 |
| 25055 |
\& U32 SvREADONLY(SV* sv) |
| 25056 |
.Ve |
| 25057 |
.RE |
| 25058 |
.RS 4 |
| 25059 |
.RE |
| 25060 |
.ie n .IP """SvREADONLY_off""" 4 |
| 25061 |
.el .IP \f(CWSvREADONLY_off\fR 4 |
| 25062 |
.IX Xref "SvREADONLY_off" |
| 25063 |
.IX Item "SvREADONLY_off" |
| 25064 |
Mark an object as not-readonly. Exactly what this mean depends on the |
| 25065 |
object type. Exposed to perl code via \fBInternals::SvREADONLY()\fR. |
| 25066 |
.RS 4 |
| 25067 |
.Sp |
| 25068 |
.Vb 1 |
| 25069 |
\& U32 SvREADONLY_off(SV* sv) |
| 25070 |
.Ve |
| 25071 |
.RE |
| 25072 |
.RS 4 |
| 25073 |
.RE |
| 25074 |
.ie n .IP """SvREADONLY_on""" 4 |
| 25075 |
.el .IP \f(CWSvREADONLY_on\fR 4 |
| 25076 |
.IX Xref "SvREADONLY_on" |
| 25077 |
.IX Item "SvREADONLY_on" |
| 25078 |
Mark an object as readonly. Exactly what this means depends on the object |
| 25079 |
type. Exposed to perl code via \fBInternals::SvREADONLY()\fR. |
| 25080 |
.RS 4 |
| 25081 |
.Sp |
| 25082 |
.Vb 1 |
| 25083 |
\& U32 SvREADONLY_on(SV* sv) |
| 25084 |
.Ve |
| 25085 |
.RE |
| 25086 |
.RS 4 |
| 25087 |
.RE |
| 25088 |
.ie n .IP """sv_ref""" 4 |
| 25089 |
.el .IP \f(CWsv_ref\fR 4 |
| 25090 |
.IX Xref "sv_ref" |
| 25091 |
.IX Item "sv_ref" |
| 25092 |
Returns a SV describing what the SV passed in is a reference to. |
| 25093 |
.Sp |
| 25094 |
dst can be a SV to be set to the description or NULL, in which case a |
| 25095 |
mortal SV is returned. |
| 25096 |
.Sp |
| 25097 |
If ob is true and the SV is blessed, the description is the class |
| 25098 |
name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc. |
| 25099 |
.RS 4 |
| 25100 |
.Sp |
| 25101 |
.Vb 1 |
| 25102 |
\& SV * sv_ref(SV *dst, const SV * const sv, const int ob) |
| 25103 |
.Ve |
| 25104 |
.RE |
| 25105 |
.RS 4 |
| 25106 |
.RE |
| 25107 |
.ie n .IP """SvREFCNT""" 4 |
| 25108 |
.el .IP \f(CWSvREFCNT\fR 4 |
| 25109 |
.IX Xref "SvREFCNT" |
| 25110 |
.IX Item "SvREFCNT" |
| 25111 |
Returns the value of the object's reference count. Exposed |
| 25112 |
to perl code via \fBInternals::SvREFCNT()\fR. |
| 25113 |
.RS 4 |
| 25114 |
.Sp |
| 25115 |
.Vb 1 |
| 25116 |
\& U32 SvREFCNT(SV* sv) |
| 25117 |
.Ve |
| 25118 |
.RE |
| 25119 |
.RS 4 |
| 25120 |
.RE |
| 25121 |
.ie n .IP """SvREFCNT_dec""" 4 |
| 25122 |
.el .IP \f(CWSvREFCNT_dec\fR 4 |
| 25123 |
.IX Item "SvREFCNT_dec" |
| 25124 |
.PD 0 |
| 25125 |
.ie n .IP """SvREFCNT_dec_set_NULL""" 4 |
| 25126 |
.el .IP \f(CWSvREFCNT_dec_set_NULL\fR 4 |
| 25127 |
.IX Item "SvREFCNT_dec_set_NULL" |
| 25128 |
.ie n .IP """SvREFCNT_dec_ret_NULL""" 4 |
| 25129 |
.el .IP \f(CWSvREFCNT_dec_ret_NULL\fR 4 |
| 25130 |
.IX Item "SvREFCNT_dec_ret_NULL" |
| 25131 |
.ie n .IP """SvREFCNT_dec_NN""" 4 |
| 25132 |
.el .IP \f(CWSvREFCNT_dec_NN\fR 4 |
| 25133 |
.IX Xref "SvREFCNT_dec SvREFCNT_dec_set_NULL SvREFCNT_dec_ret_NULL SvREFCNT_dec_NN" |
| 25134 |
.IX Item "SvREFCNT_dec_NN" |
| 25135 |
.PD |
| 25136 |
These decrement the reference count of the given SV. |
| 25137 |
.Sp |
| 25138 |
\&\f(CW\*(C`SvREFCNT_dec_NN\*(C'\fR may only be used when \f(CW\*(C`sv\*(C'\fR is known to not be \f(CW\*(C`NULL\*(C'\fR. |
| 25139 |
.Sp |
| 25140 |
The function \f(CWSvREFCNT_dec_ret_NULL()\fR is identical to the |
| 25141 |
\&\f(CWSvREFCNT_dec()\fR except it returns a NULL \f(CW\*(C`SV *\*(C'\fR. It is used by |
| 25142 |
\&\f(CWSvREFCNT_dec_set_NULL()\fR which is a macro which will, when passed a |
| 25143 |
non-NULL argument, decrement the reference count of its argument and |
| 25144 |
then set it to NULL. You can replace code of the following form: |
| 25145 |
.Sp |
| 25146 |
.Vb 4 |
| 25147 |
\& if (sv) { |
| 25148 |
\& SvREFCNT_dec_NN(sv); |
| 25149 |
\& sv = NULL; |
| 25150 |
\& } |
| 25151 |
.Ve |
| 25152 |
.Sp |
| 25153 |
with |
| 25154 |
.Sp |
| 25155 |
.Vb 1 |
| 25156 |
\& SvREFCNT_dec_set_NULL(sv); |
| 25157 |
.Ve |
| 25158 |
.RS 4 |
| 25159 |
.Sp |
| 25160 |
.Vb 4 |
| 25161 |
\& void SvREFCNT_dec (SV *sv) |
| 25162 |
\& void SvREFCNT_dec_set_NULL(SV *sv) |
| 25163 |
\& SV * SvREFCNT_dec_ret_NULL(SV *sv) |
| 25164 |
\& void SvREFCNT_dec_NN (SV *sv) |
| 25165 |
.Ve |
| 25166 |
.RE |
| 25167 |
.RS 4 |
| 25168 |
.RE |
| 25169 |
.ie n .IP """SvREFCNT_inc""" 4 |
| 25170 |
.el .IP \f(CWSvREFCNT_inc\fR 4 |
| 25171 |
.IX Item "SvREFCNT_inc" |
| 25172 |
.PD 0 |
| 25173 |
.ie n .IP """SvREFCNT_inc_NN""" 4 |
| 25174 |
.el .IP \f(CWSvREFCNT_inc_NN\fR 4 |
| 25175 |
.IX Item "SvREFCNT_inc_NN" |
| 25176 |
.ie n .IP """SvREFCNT_inc_simple""" 4 |
| 25177 |
.el .IP \f(CWSvREFCNT_inc_simple\fR 4 |
| 25178 |
.IX Item "SvREFCNT_inc_simple" |
| 25179 |
.ie n .IP """SvREFCNT_inc_simple_NN""" 4 |
| 25180 |
.el .IP \f(CWSvREFCNT_inc_simple_NN\fR 4 |
| 25181 |
.IX Item "SvREFCNT_inc_simple_NN" |
| 25182 |
.ie n .IP """SvREFCNT_inc_simple_void""" 4 |
| 25183 |
.el .IP \f(CWSvREFCNT_inc_simple_void\fR 4 |
| 25184 |
.IX Item "SvREFCNT_inc_simple_void" |
| 25185 |
.ie n .IP """SvREFCNT_inc_simple_void_NN""" 4 |
| 25186 |
.el .IP \f(CWSvREFCNT_inc_simple_void_NN\fR 4 |
| 25187 |
.IX Item "SvREFCNT_inc_simple_void_NN" |
| 25188 |
.ie n .IP """SvREFCNT_inc_void""" 4 |
| 25189 |
.el .IP \f(CWSvREFCNT_inc_void\fR 4 |
| 25190 |
.IX Item "SvREFCNT_inc_void" |
| 25191 |
.ie n .IP """SvREFCNT_inc_void_NN""" 4 |
| 25192 |
.el .IP \f(CWSvREFCNT_inc_void_NN\fR 4 |
| 25193 |
.IX Xref "SvREFCNT_inc SvREFCNT_inc_NN SvREFCNT_inc_simple SvREFCNT_inc_simple_NN SvREFCNT_inc_simple_void SvREFCNT_inc_simple_void_NN SvREFCNT_inc_void SvREFCNT_inc_void_NN" |
| 25194 |
.IX Item "SvREFCNT_inc_void_NN" |
| 25195 |
.PD |
| 25196 |
These all increment the reference count of the given SV. |
| 25197 |
The ones without \f(CW\*(C`void\*(C'\fR in their names return the SV. |
| 25198 |
.Sp |
| 25199 |
\&\f(CW\*(C`SvREFCNT_inc\*(C'\fR is the base operation; the rest are optimizations if various |
| 25200 |
input constraints are known to be true; hence, all can be replaced with |
| 25201 |
\&\f(CW\*(C`SvREFCNT_inc\*(C'\fR. |
| 25202 |
.Sp |
| 25203 |
\&\f(CW\*(C`SvREFCNT_inc_NN\*(C'\fR can only be used if you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. Since we |
| 25204 |
don't have to check the NULLness, it's faster and smaller. |
| 25205 |
.Sp |
| 25206 |
\&\f(CW\*(C`SvREFCNT_inc_void\*(C'\fR can only be used if you don't need the |
| 25207 |
return value. The macro doesn't need to return a meaningful value. |
| 25208 |
.Sp |
| 25209 |
\&\f(CW\*(C`SvREFCNT_inc_void_NN\*(C'\fR can only be used if you both don't need the return |
| 25210 |
value, and you know that \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. The macro doesn't need to |
| 25211 |
return a meaningful value, or check for NULLness, so it's smaller and faster. |
| 25212 |
.Sp |
| 25213 |
\&\f(CW\*(C`SvREFCNT_inc_simple\*(C'\fR can only be used with expressions without side |
| 25214 |
effects. Since we don't have to store a temporary value, it's faster. |
| 25215 |
.Sp |
| 25216 |
\&\f(CW\*(C`SvREFCNT_inc_simple_NN\*(C'\fR can only be used with expressions without side |
| 25217 |
effects and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. Since we don't have to store a |
| 25218 |
temporary value, nor check for NULLness, it's faster and smaller. |
| 25219 |
.Sp |
| 25220 |
\&\f(CW\*(C`SvREFCNT_inc_simple_void\*(C'\fR can only be used with expressions without side |
| 25221 |
effects and you don't need the return value. |
| 25222 |
.Sp |
| 25223 |
\&\f(CW\*(C`SvREFCNT_inc_simple_void_NN\*(C'\fR can only be used with expressions without side |
| 25224 |
effects, you don't need the return value, and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. |
| 25225 |
.RS 4 |
| 25226 |
.Sp |
| 25227 |
.Vb 8 |
| 25228 |
\& SV * SvREFCNT_inc (SV *sv) |
| 25229 |
\& SV * SvREFCNT_inc_NN (SV *sv) |
| 25230 |
\& SV* SvREFCNT_inc_simple (SV* sv) |
| 25231 |
\& SV* SvREFCNT_inc_simple_NN (SV* sv) |
| 25232 |
\& void SvREFCNT_inc_simple_void (SV* sv) |
| 25233 |
\& void SvREFCNT_inc_simple_void_NN(SV* sv) |
| 25234 |
\& void SvREFCNT_inc_void (SV *sv) |
| 25235 |
\& void SvREFCNT_inc_void_NN (SV* sv) |
| 25236 |
.Ve |
| 25237 |
.RE |
| 25238 |
.RS 4 |
| 25239 |
.RE |
| 25240 |
.ie n .IP """sv_reftype""" 4 |
| 25241 |
.el .IP \f(CWsv_reftype\fR 4 |
| 25242 |
.IX Xref "sv_reftype" |
| 25243 |
.IX Item "sv_reftype" |
| 25244 |
Returns a string describing what the SV is a reference to. |
| 25245 |
.Sp |
| 25246 |
If ob is true and the SV is blessed, the string is the class name, |
| 25247 |
otherwise it is the type of the SV, "SCALAR", "ARRAY" etc. |
| 25248 |
.RS 4 |
| 25249 |
.Sp |
| 25250 |
.Vb 1 |
| 25251 |
\& const char * sv_reftype(const SV * const sv, const int ob) |
| 25252 |
.Ve |
| 25253 |
.RE |
| 25254 |
.RS 4 |
| 25255 |
.RE |
| 25256 |
.ie n .IP """sv_replace""" 4 |
| 25257 |
.el .IP \f(CWsv_replace\fR 4 |
| 25258 |
.IX Xref "sv_replace" |
| 25259 |
.IX Item "sv_replace" |
| 25260 |
Make the first argument a copy of the second, then delete the original. |
| 25261 |
The target SV physically takes over ownership of the body of the source SV |
| 25262 |
and inherits its flags; however, the target keeps any magic it owns, |
| 25263 |
and any magic in the source is discarded. |
| 25264 |
Note that this is a rather specialist SV copying operation; most of the |
| 25265 |
time you'll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front-ends. |
| 25266 |
.RS 4 |
| 25267 |
.Sp |
| 25268 |
.Vb 1 |
| 25269 |
\& void sv_replace(SV * const sv, SV * const nsv) |
| 25270 |
.Ve |
| 25271 |
.RE |
| 25272 |
.RS 4 |
| 25273 |
.RE |
| 25274 |
.ie n .IP """sv_report_used""" 4 |
| 25275 |
.el .IP \f(CWsv_report_used\fR 4 |
| 25276 |
.IX Xref "sv_report_used" |
| 25277 |
.IX Item "sv_report_used" |
| 25278 |
Dump the contents of all SVs not yet freed (debugging aid). |
| 25279 |
.RS 4 |
| 25280 |
.Sp |
| 25281 |
.Vb 1 |
| 25282 |
\& void sv_report_used() |
| 25283 |
.Ve |
| 25284 |
.RE |
| 25285 |
.RS 4 |
| 25286 |
.RE |
| 25287 |
.ie n .IP """sv_reset""" 4 |
| 25288 |
.el .IP \f(CWsv_reset\fR 4 |
| 25289 |
.IX Xref "sv_reset" |
| 25290 |
.IX Item "sv_reset" |
| 25291 |
Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function. |
| 25292 |
Note that the perl-level function is vaguely deprecated. |
| 25293 |
.RS 4 |
| 25294 |
.Sp |
| 25295 |
.Vb 1 |
| 25296 |
\& void sv_reset(const char *s, HV * const stash) |
| 25297 |
.Ve |
| 25298 |
.RE |
| 25299 |
.RS 4 |
| 25300 |
.RE |
| 25301 |
.ie n .IP """SvROK""" 4 |
| 25302 |
.el .IP \f(CWSvROK\fR 4 |
| 25303 |
.IX Xref "SvROK" |
| 25304 |
.IX Item "SvROK" |
| 25305 |
Tests if the SV is an RV. |
| 25306 |
.RS 4 |
| 25307 |
.Sp |
| 25308 |
.Vb 1 |
| 25309 |
\& U32 SvROK(SV* sv) |
| 25310 |
.Ve |
| 25311 |
.RE |
| 25312 |
.RS 4 |
| 25313 |
.RE |
| 25314 |
.ie n .IP """SvROK_off""" 4 |
| 25315 |
.el .IP \f(CWSvROK_off\fR 4 |
| 25316 |
.IX Xref "SvROK_off" |
| 25317 |
.IX Item "SvROK_off" |
| 25318 |
Unsets the RV status of an SV. |
| 25319 |
.RS 4 |
| 25320 |
.Sp |
| 25321 |
.Vb 1 |
| 25322 |
\& void SvROK_off(SV* sv) |
| 25323 |
.Ve |
| 25324 |
.RE |
| 25325 |
.RS 4 |
| 25326 |
.RE |
| 25327 |
.ie n .IP """SvROK_on""" 4 |
| 25328 |
.el .IP \f(CWSvROK_on\fR 4 |
| 25329 |
.IX Xref "SvROK_on" |
| 25330 |
.IX Item "SvROK_on" |
| 25331 |
Tells an SV that it is an RV. |
| 25332 |
.RS 4 |
| 25333 |
.Sp |
| 25334 |
.Vb 1 |
| 25335 |
\& void SvROK_on(SV* sv) |
| 25336 |
.Ve |
| 25337 |
.RE |
| 25338 |
.RS 4 |
| 25339 |
.RE |
| 25340 |
.ie n .IP """SvRV""" 4 |
| 25341 |
.el .IP \f(CWSvRV\fR 4 |
| 25342 |
.IX Xref "SvRV" |
| 25343 |
.IX Item "SvRV" |
| 25344 |
Dereferences an RV to return the SV. |
| 25345 |
.RS 4 |
| 25346 |
.Sp |
| 25347 |
.Vb 1 |
| 25348 |
\& SV* SvRV(SV* sv) |
| 25349 |
.Ve |
| 25350 |
.RE |
| 25351 |
.RS 4 |
| 25352 |
.RE |
| 25353 |
.ie n .IP """SvRV_set""" 4 |
| 25354 |
.el .IP \f(CWSvRV_set\fR 4 |
| 25355 |
.IX Xref "SvRV_set" |
| 25356 |
.IX Item "SvRV_set" |
| 25357 |
Set the value of the RV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR. |
| 25358 |
.RS 4 |
| 25359 |
.Sp |
| 25360 |
.Vb 1 |
| 25361 |
\& void SvRV_set(SV* sv, SV* val) |
| 25362 |
.Ve |
| 25363 |
.RE |
| 25364 |
.RS 4 |
| 25365 |
.RE |
| 25366 |
.ie n .IP """sv_rvunweaken""" 4 |
| 25367 |
.el .IP \f(CWsv_rvunweaken\fR 4 |
| 25368 |
.IX Xref "sv_rvunweaken" |
| 25369 |
.IX Item "sv_rvunweaken" |
| 25370 |
Unweaken a reference: Clear the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; remove |
| 25371 |
the backreference to this RV from the array of backreferences |
| 25372 |
associated with the target SV, increment the refcount of the target. |
| 25373 |
Silently ignores \f(CW\*(C`undef\*(C'\fR and warns on non-weak references. |
| 25374 |
.RS 4 |
| 25375 |
.Sp |
| 25376 |
.Vb 1 |
| 25377 |
\& SV * sv_rvunweaken(SV * const sv) |
| 25378 |
.Ve |
| 25379 |
.RE |
| 25380 |
.RS 4 |
| 25381 |
.RE |
| 25382 |
.ie n .IP """sv_rvweaken""" 4 |
| 25383 |
.el .IP \f(CWsv_rvweaken\fR 4 |
| 25384 |
.IX Xref "sv_rvweaken" |
| 25385 |
.IX Item "sv_rvweaken" |
| 25386 |
Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; give the |
| 25387 |
referred-to SV \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn't already; and |
| 25388 |
push a back-reference to this RV onto the array of backreferences |
| 25389 |
associated with that magic. If the RV is magical, set magic will be |
| 25390 |
called after the RV is cleared. Silently ignores \f(CW\*(C`undef\*(C'\fR and warns |
| 25391 |
on already-weak references. |
| 25392 |
.RS 4 |
| 25393 |
.Sp |
| 25394 |
.Vb 1 |
| 25395 |
\& SV * sv_rvweaken(SV * const sv) |
| 25396 |
.Ve |
| 25397 |
.RE |
| 25398 |
.RS 4 |
| 25399 |
.RE |
| 25400 |
.ie n .IP """sv_setbool""" 4 |
| 25401 |
.el .IP \f(CWsv_setbool\fR 4 |
| 25402 |
.IX Item "sv_setbool" |
| 25403 |
.PD 0 |
| 25404 |
.ie n .IP """sv_setbool_mg""" 4 |
| 25405 |
.el .IP \f(CWsv_setbool_mg\fR 4 |
| 25406 |
.IX Xref "sv_setbool sv_setbool_mg" |
| 25407 |
.IX Item "sv_setbool_mg" |
| 25408 |
.PD |
| 25409 |
These set an SV to a true or false boolean value, upgrading first if necessary. |
| 25410 |
.Sp |
| 25411 |
They differ only in that \f(CW\*(C`sv_setbool_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setbool\*(C'\fR |
| 25412 |
does not. |
| 25413 |
.RS 4 |
| 25414 |
.Sp |
| 25415 |
.Vb 1 |
| 25416 |
\& void sv_setbool(SV *sv, bool b) |
| 25417 |
.Ve |
| 25418 |
.RE |
| 25419 |
.RS 4 |
| 25420 |
.RE |
| 25421 |
.ie n .IP """sv_set_bool""" 4 |
| 25422 |
.el .IP \f(CWsv_set_bool\fR 4 |
| 25423 |
.IX Xref "sv_set_bool" |
| 25424 |
.IX Item "sv_set_bool" |
| 25425 |
Equivalent to \f(CW\*(C`sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no)\*(C'\fR, but |
| 25426 |
may be made more efficient in the future. Doesn't handle set magic. |
| 25427 |
.Sp |
| 25428 |
The perl equivalent is \f(CW\*(C`$sv = !!$expr;\*(C'\fR. |
| 25429 |
.Sp |
| 25430 |
Introduced in perl 5.35.11. |
| 25431 |
.RS 4 |
| 25432 |
.Sp |
| 25433 |
.Vb 1 |
| 25434 |
\& void sv_set_bool(SV *sv, const bool bool_val) |
| 25435 |
.Ve |
| 25436 |
.RE |
| 25437 |
.RS 4 |
| 25438 |
.RE |
| 25439 |
.ie n .IP """sv_set_false""" 4 |
| 25440 |
.el .IP \f(CWsv_set_false\fR 4 |
| 25441 |
.IX Xref "sv_set_false" |
| 25442 |
.IX Item "sv_set_false" |
| 25443 |
Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_no)\*(C'\fR, but may be made more |
| 25444 |
efficient in the future. Doesn't handle set magic. |
| 25445 |
.Sp |
| 25446 |
The perl equivalent is \f(CW\*(C`$sv = !1;\*(C'\fR. |
| 25447 |
.Sp |
| 25448 |
Introduced in perl 5.35.11. |
| 25449 |
.RS 4 |
| 25450 |
.Sp |
| 25451 |
.Vb 1 |
| 25452 |
\& void sv_set_false(SV *sv) |
| 25453 |
.Ve |
| 25454 |
.RE |
| 25455 |
.RS 4 |
| 25456 |
.RE |
| 25457 |
.ie n .IP """sv_setiv""" 4 |
| 25458 |
.el .IP \f(CWsv_setiv\fR 4 |
| 25459 |
.IX Item "sv_setiv" |
| 25460 |
.PD 0 |
| 25461 |
.ie n .IP """sv_setiv_mg""" 4 |
| 25462 |
.el .IP \f(CWsv_setiv_mg\fR 4 |
| 25463 |
.IX Xref "sv_setiv sv_setiv_mg" |
| 25464 |
.IX Item "sv_setiv_mg" |
| 25465 |
.PD |
| 25466 |
These copy an integer into the given SV, upgrading first if necessary. |
| 25467 |
.Sp |
| 25468 |
They differ only in that \f(CW\*(C`sv_setiv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setiv\*(C'\fR does |
| 25469 |
not. |
| 25470 |
.RS 4 |
| 25471 |
.Sp |
| 25472 |
.Vb 2 |
| 25473 |
\& void sv_setiv (SV * const sv, const IV num) |
| 25474 |
\& void sv_setiv_mg(SV * const sv, const IV i) |
| 25475 |
.Ve |
| 25476 |
.RE |
| 25477 |
.RS 4 |
| 25478 |
.RE |
| 25479 |
.ie n .IP """SvSETMAGIC""" 4 |
| 25480 |
.el .IP \f(CWSvSETMAGIC\fR 4 |
| 25481 |
.IX Xref "SvSETMAGIC" |
| 25482 |
.IX Item "SvSETMAGIC" |
| 25483 |
Invokes \f(CW"mg_set"\fR on an SV if it has 'set' magic. This is necessary |
| 25484 |
after modifying a scalar, in case it is a magical variable like \f(CW$|\fR |
| 25485 |
or a tied variable (it calls \f(CW\*(C`STORE\*(C'\fR). This macro evaluates its |
| 25486 |
argument more than once. |
| 25487 |
.RS 4 |
| 25488 |
.Sp |
| 25489 |
.Vb 1 |
| 25490 |
\& void SvSETMAGIC(SV* sv) |
| 25491 |
.Ve |
| 25492 |
.RE |
| 25493 |
.RS 4 |
| 25494 |
.RE |
| 25495 |
.ie n .IP """SvSetMagicSV""" 4 |
| 25496 |
.el .IP \f(CWSvSetMagicSV\fR 4 |
| 25497 |
.IX Item "SvSetMagicSV" |
| 25498 |
.PD 0 |
| 25499 |
.ie n .IP """SvSetMagicSV_nosteal""" 4 |
| 25500 |
.el .IP \f(CWSvSetMagicSV_nosteal\fR 4 |
| 25501 |
.IX Item "SvSetMagicSV_nosteal" |
| 25502 |
.ie n .IP """SvSetSV""" 4 |
| 25503 |
.el .IP \f(CWSvSetSV\fR 4 |
| 25504 |
.IX Item "SvSetSV" |
| 25505 |
.ie n .IP """SvSetSV_nosteal""" 4 |
| 25506 |
.el .IP \f(CWSvSetSV_nosteal\fR 4 |
| 25507 |
.IX Xref "SvSetMagicSV SvSetMagicSV_nosteal SvSetSV SvSetSV_nosteal" |
| 25508 |
.IX Item "SvSetSV_nosteal" |
| 25509 |
.PD |
| 25510 |
if \f(CW\*(C`dsv\*(C'\fR is the same as \f(CW\*(C`ssv\*(C'\fR, these do nothing. Otherwise they all call |
| 25511 |
some form of \f(CW"sv_setsv"\fR. They may evaluate their arguments more than |
| 25512 |
once. |
| 25513 |
.Sp |
| 25514 |
The only differences are: |
| 25515 |
.Sp |
| 25516 |
\&\f(CW\*(C`SvSetMagicSV\*(C'\fR and \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR perform any required 'set' magic |
| 25517 |
afterwards on the destination SV; \f(CW\*(C`SvSetSV\*(C'\fR and \f(CW\*(C`SvSetSV_nosteal\*(C'\fR do not. |
| 25518 |
.Sp |
| 25519 |
\&\f(CW\*(C`SvSetSV_nosteal\*(C'\fR \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR call a non-destructive version of |
| 25520 |
\&\f(CW\*(C`sv_setsv\*(C'\fR. |
| 25521 |
.RS 4 |
| 25522 |
.Sp |
| 25523 |
.Vb 1 |
| 25524 |
\& void SvSetMagicSV(SV* dsv, SV* ssv) |
| 25525 |
.Ve |
| 25526 |
.RE |
| 25527 |
.RS 4 |
| 25528 |
.RE |
| 25529 |
.ie n .IP """sv_setnv""" 4 |
| 25530 |
.el .IP \f(CWsv_setnv\fR 4 |
| 25531 |
.IX Item "sv_setnv" |
| 25532 |
.PD 0 |
| 25533 |
.ie n .IP """sv_setnv_mg""" 4 |
| 25534 |
.el .IP \f(CWsv_setnv_mg\fR 4 |
| 25535 |
.IX Xref "sv_setnv sv_setnv_mg" |
| 25536 |
.IX Item "sv_setnv_mg" |
| 25537 |
.PD |
| 25538 |
These copy a double into the given SV, upgrading first if necessary. |
| 25539 |
.Sp |
| 25540 |
They differ only in that \f(CW\*(C`sv_setnv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setnv\*(C'\fR does |
| 25541 |
not. |
| 25542 |
.RS 4 |
| 25543 |
.Sp |
| 25544 |
.Vb 1 |
| 25545 |
\& void sv_setnv(SV * const sv, const NV num) |
| 25546 |
.Ve |
| 25547 |
.RE |
| 25548 |
.RS 4 |
| 25549 |
.RE |
| 25550 |
.ie n .IP """sv_setpv""" 4 |
| 25551 |
.el .IP \f(CWsv_setpv\fR 4 |
| 25552 |
.IX Item "sv_setpv" |
| 25553 |
.PD 0 |
| 25554 |
.ie n .IP """sv_setpv_mg""" 4 |
| 25555 |
.el .IP \f(CWsv_setpv_mg\fR 4 |
| 25556 |
.IX Item "sv_setpv_mg" |
| 25557 |
.ie n .IP """sv_setpvn""" 4 |
| 25558 |
.el .IP \f(CWsv_setpvn\fR 4 |
| 25559 |
.IX Item "sv_setpvn" |
| 25560 |
.ie n .IP """sv_setpvn_fresh""" 4 |
| 25561 |
.el .IP \f(CWsv_setpvn_fresh\fR 4 |
| 25562 |
.IX Item "sv_setpvn_fresh" |
| 25563 |
.ie n .IP """sv_setpvn_mg""" 4 |
| 25564 |
.el .IP \f(CWsv_setpvn_mg\fR 4 |
| 25565 |
.IX Item "sv_setpvn_mg" |
| 25566 |
.ie n .IP """sv_setpvs""" 4 |
| 25567 |
.el .IP \f(CWsv_setpvs\fR 4 |
| 25568 |
.IX Item "sv_setpvs" |
| 25569 |
.ie n .IP """sv_setpvs_mg""" 4 |
| 25570 |
.el .IP \f(CWsv_setpvs_mg\fR 4 |
| 25571 |
.IX Xref "sv_setpv sv_setpv_mg sv_setpvn sv_setpvn_fresh sv_setpvn_mg sv_setpvs sv_setpvs_mg" |
| 25572 |
.IX Item "sv_setpvs_mg" |
| 25573 |
.PD |
| 25574 |
These copy a string into the SV \f(CW\*(C`sv\*(C'\fR, making sure it is \f(CW"SvPOK_only"\fR. |
| 25575 |
.Sp |
| 25576 |
In the \f(CW\*(C`pvs\*(C'\fR forms, the string must be a C literal string, enclosed in double |
| 25577 |
quotes. |
| 25578 |
.Sp |
| 25579 |
In the \f(CW\*(C`pvn\*(C'\fR forms, the first byte of the string is pointed to by \f(CW\*(C`ptr\*(C'\fR, and |
| 25580 |
\&\f(CW\*(C`len\*(C'\fR indicates the number of bytes to be copied, potentially including |
| 25581 |
embedded \f(CW\*(C`NUL\*(C'\fR characters. |
| 25582 |
.Sp |
| 25583 |
In the plain \f(CW\*(C`pv\*(C'\fR forms, \f(CW\*(C`ptr\*(C'\fR points to a NUL-terminated C string. That is, |
| 25584 |
it points to the first byte of the string, and the copy proceeds up through the |
| 25585 |
first encountered \f(CW\*(C`NUL\*(C'\fR byte. |
| 25586 |
.Sp |
| 25587 |
In the forms that take a \f(CW\*(C`ptr\*(C'\fR argument, if it is NULL, the SV will become |
| 25588 |
undefined. |
| 25589 |
.Sp |
| 25590 |
\&\fBThe UTF\-8 flag is not changed by these functions.\fR |
| 25591 |
.Sp |
| 25592 |
A terminating NUL byte is guaranteed in the result. |
| 25593 |
.Sp |
| 25594 |
The \f(CW\*(C`_mg\*(C'\fR forms handle 'set' magic; the other forms skip all magic. |
| 25595 |
.Sp |
| 25596 |
\&\f(CW\*(C`sv_setpvn_fresh\*(C'\fR is a cut-down alternative to \f(CW\*(C`sv_setpvn\*(C'\fR, intended ONLY |
| 25597 |
to be used with a fresh sv that has been upgraded to a SVt_PV, SVt_PVIV, |
| 25598 |
SVt_PVNV, or SVt_PVMG. |
| 25599 |
.RS 4 |
| 25600 |
.Sp |
| 25601 |
.Vb 10 |
| 25602 |
\& void sv_setpv (SV * const sv, const char * const ptr) |
| 25603 |
\& void sv_setpv_mg (SV * const sv, const char * const ptr) |
| 25604 |
\& void sv_setpvn (SV * const sv, const char * const ptr, |
| 25605 |
\& const STRLEN len) |
| 25606 |
\& void sv_setpvn_fresh(SV * const sv, const char * const ptr, |
| 25607 |
\& const STRLEN len) |
| 25608 |
\& void sv_setpvn_mg (SV * const sv, const char * const ptr, |
| 25609 |
\& const STRLEN len) |
| 25610 |
\& void sv_setpvs (SV* sv, "literal string") |
| 25611 |
\& void sv_setpvs_mg (SV* sv, "literal string") |
| 25612 |
.Ve |
| 25613 |
.RE |
| 25614 |
.RS 4 |
| 25615 |
.RE |
| 25616 |
.ie n .IP """sv_setpv_bufsize""" 4 |
| 25617 |
.el .IP \f(CWsv_setpv_bufsize\fR 4 |
| 25618 |
.IX Xref "sv_setpv_bufsize" |
| 25619 |
.IX Item "sv_setpv_bufsize" |
| 25620 |
Sets the SV to be a string of \f(CW\*(C`cur\*(C'\fR bytes length, with at least |
| 25621 |
\&\f(CW\*(C`len\*(C'\fR bytes available. Ensures that there is a null byte at \f(CW\*(C`SvEND\*(C'\fR. |
| 25622 |
.Sp |
| 25623 |
Returns a char * pointer to the SvPV buffer. |
| 25624 |
.Sp |
| 25625 |
The caller must set the first \f(CW\*(C`cur\*(C'\fR bytes of \f(CW\*(C`sv\*(C'\fR before the first use of its |
| 25626 |
contents. This means that if \f(CW\*(C`cur\*(C'\fR is zero, the SV is immediately fully |
| 25627 |
formed and ready to use, just like any other SV containing an empty string. |
| 25628 |
.RS 4 |
| 25629 |
.Sp |
| 25630 |
.Vb 2 |
| 25631 |
\& char * sv_setpv_bufsize(SV * const sv, const STRLEN cur, |
| 25632 |
\& const STRLEN len) |
| 25633 |
.Ve |
| 25634 |
.RE |
| 25635 |
.RS 4 |
| 25636 |
.RE |
| 25637 |
.ie n .IP """sv_setpvf""" 4 |
| 25638 |
.el .IP \f(CWsv_setpvf\fR 4 |
| 25639 |
.IX Item "sv_setpvf" |
| 25640 |
.PD 0 |
| 25641 |
.ie n .IP """sv_setpvf_mg""" 4 |
| 25642 |
.el .IP \f(CWsv_setpvf_mg\fR 4 |
| 25643 |
.IX Item "sv_setpvf_mg" |
| 25644 |
.ie n .IP """sv_setpvf_mg_nocontext""" 4 |
| 25645 |
.el .IP \f(CWsv_setpvf_mg_nocontext\fR 4 |
| 25646 |
.IX Item "sv_setpvf_mg_nocontext" |
| 25647 |
.ie n .IP """sv_setpvf_nocontext""" 4 |
| 25648 |
.el .IP \f(CWsv_setpvf_nocontext\fR 4 |
| 25649 |
.IX Xref "sv_setpvf sv_setpvf_mg sv_setpvf_mg_nocontext sv_setpvf_nocontext" |
| 25650 |
.IX Item "sv_setpvf_nocontext" |
| 25651 |
.PD |
| 25652 |
These work like \f(CW"sv_catpvf"\fR but copy the text into the SV instead of |
| 25653 |
appending it. |
| 25654 |
.Sp |
| 25655 |
The differences between these are: |
| 25656 |
.Sp |
| 25657 |
\&\f(CW\*(C`sv_setpvf_mg\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR perform 'set' magic; \f(CW\*(C`sv_setpvf\*(C'\fR |
| 25658 |
and \f(CW\*(C`sv_setpvf_nocontext\*(C'\fR skip all magic. |
| 25659 |
.Sp |
| 25660 |
\&\f(CW\*(C`sv_setpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR do not take a thread |
| 25661 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller |
| 25662 |
doesn't already have the thread context. |
| 25663 |
.Sp |
| 25664 |
\&\fBThe UTF\-8 flag is not changed by these functions.\fR |
| 25665 |
.Sp |
| 25666 |
NOTE: \f(CW\*(C`sv_setpvf\*(C'\fR must be explicitly called as |
| 25667 |
\&\f(CW\*(C`Perl_sv_setpvf\*(C'\fR |
| 25668 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 25669 |
.Sp |
| 25670 |
NOTE: \f(CW\*(C`sv_setpvf_mg\*(C'\fR must be explicitly called as |
| 25671 |
\&\f(CW\*(C`Perl_sv_setpvf_mg\*(C'\fR |
| 25672 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 25673 |
.RS 4 |
| 25674 |
.Sp |
| 25675 |
.Vb 8 |
| 25676 |
\& void Perl_sv_setpvf (pTHX_ SV * const sv, |
| 25677 |
\& const char * const pat, ...) |
| 25678 |
\& void Perl_sv_setpvf_mg (pTHX_ SV * const sv, |
| 25679 |
\& const char * const pat, ...) |
| 25680 |
\& void sv_setpvf_mg_nocontext(SV * const sv, |
| 25681 |
\& const char * const pat, ...) |
| 25682 |
\& void sv_setpvf_nocontext (SV * const sv, |
| 25683 |
\& const char * const pat, ...) |
| 25684 |
.Ve |
| 25685 |
.RE |
| 25686 |
.RS 4 |
| 25687 |
.RE |
| 25688 |
.ie n .IP """sv_setref_iv""" 4 |
| 25689 |
.el .IP \f(CWsv_setref_iv\fR 4 |
| 25690 |
.IX Xref "sv_setref_iv" |
| 25691 |
.IX Item "sv_setref_iv" |
| 25692 |
Copies an integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR |
| 25693 |
argument will be upgraded to an RV. That RV will be modified to point to |
| 25694 |
the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the |
| 25695 |
blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV |
| 25696 |
will have a reference count of 1, and the RV will be returned. |
| 25697 |
.RS 4 |
| 25698 |
.Sp |
| 25699 |
.Vb 2 |
| 25700 |
\& SV * sv_setref_iv(SV * const rv, const char * const classname, |
| 25701 |
\& const IV iv) |
| 25702 |
.Ve |
| 25703 |
.RE |
| 25704 |
.RS 4 |
| 25705 |
.RE |
| 25706 |
.ie n .IP """sv_setref_nv""" 4 |
| 25707 |
.el .IP \f(CWsv_setref_nv\fR 4 |
| 25708 |
.IX Xref "sv_setref_nv" |
| 25709 |
.IX Item "sv_setref_nv" |
| 25710 |
Copies a double into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR |
| 25711 |
argument will be upgraded to an RV. That RV will be modified to point to |
| 25712 |
the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the |
| 25713 |
blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV |
| 25714 |
will have a reference count of 1, and the RV will be returned. |
| 25715 |
.RS 4 |
| 25716 |
.Sp |
| 25717 |
.Vb 2 |
| 25718 |
\& SV * sv_setref_nv(SV * const rv, const char * const classname, |
| 25719 |
\& const NV nv) |
| 25720 |
.Ve |
| 25721 |
.RE |
| 25722 |
.RS 4 |
| 25723 |
.RE |
| 25724 |
.ie n .IP """sv_setref_pv""" 4 |
| 25725 |
.el .IP \f(CWsv_setref_pv\fR 4 |
| 25726 |
.IX Xref "sv_setref_pv" |
| 25727 |
.IX Item "sv_setref_pv" |
| 25728 |
Copies a pointer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR |
| 25729 |
argument will be upgraded to an RV. That RV will be modified to point to |
| 25730 |
the new SV. If the \f(CW\*(C`pv\*(C'\fR argument is \f(CW\*(C`NULL\*(C'\fR, then \f(CW\*(C`PL_sv_undef\*(C'\fR will be placed |
| 25731 |
into the SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the |
| 25732 |
blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV |
| 25733 |
will have a reference count of 1, and the RV will be returned. |
| 25734 |
.Sp |
| 25735 |
Do not use with other Perl types such as HV, AV, SV, CV, because those |
| 25736 |
objects will become corrupted by the pointer copy process. |
| 25737 |
.Sp |
| 25738 |
Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer. |
| 25739 |
.RS 4 |
| 25740 |
.Sp |
| 25741 |
.Vb 2 |
| 25742 |
\& SV * sv_setref_pv(SV * const rv, const char * const classname, |
| 25743 |
\& void * const pv) |
| 25744 |
.Ve |
| 25745 |
.RE |
| 25746 |
.RS 4 |
| 25747 |
.RE |
| 25748 |
.ie n .IP """sv_setref_pvn""" 4 |
| 25749 |
.el .IP \f(CWsv_setref_pvn\fR 4 |
| 25750 |
.IX Xref "sv_setref_pvn" |
| 25751 |
.IX Item "sv_setref_pvn" |
| 25752 |
Copies a string into a new SV, optionally blessing the SV. The length of the |
| 25753 |
string must be specified with \f(CW\*(C`n\*(C'\fR. The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to |
| 25754 |
an RV. That RV will be modified to point to the new SV. The \f(CW\*(C`classname\*(C'\fR |
| 25755 |
argument indicates the package for the blessing. Set \f(CW\*(C`classname\*(C'\fR to |
| 25756 |
\&\f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV will have a reference count |
| 25757 |
of 1, and the RV will be returned. |
| 25758 |
.Sp |
| 25759 |
Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string. |
| 25760 |
.RS 4 |
| 25761 |
.Sp |
| 25762 |
.Vb 2 |
| 25763 |
\& SV * sv_setref_pvn(SV * const rv, const char * const classname, |
| 25764 |
\& const char * const pv, const STRLEN n) |
| 25765 |
.Ve |
| 25766 |
.RE |
| 25767 |
.RS 4 |
| 25768 |
.RE |
| 25769 |
.ie n .IP """sv_setref_pvs""" 4 |
| 25770 |
.el .IP \f(CWsv_setref_pvs\fR 4 |
| 25771 |
.IX Xref "sv_setref_pvs" |
| 25772 |
.IX Item "sv_setref_pvs" |
| 25773 |
Like \f(CW\*(C`sv_setref_pvn\*(C'\fR, but takes a literal string instead of |
| 25774 |
a string/length pair. |
| 25775 |
.RS 4 |
| 25776 |
.Sp |
| 25777 |
.Vb 2 |
| 25778 |
\& SV * sv_setref_pvs(SV *const rv, const char *const classname, |
| 25779 |
\& "literal string") |
| 25780 |
.Ve |
| 25781 |
.RE |
| 25782 |
.RS 4 |
| 25783 |
.RE |
| 25784 |
.ie n .IP """sv_setref_uv""" 4 |
| 25785 |
.el .IP \f(CWsv_setref_uv\fR 4 |
| 25786 |
.IX Xref "sv_setref_uv" |
| 25787 |
.IX Item "sv_setref_uv" |
| 25788 |
Copies an unsigned integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR |
| 25789 |
argument will be upgraded to an RV. That RV will be modified to point to |
| 25790 |
the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the |
| 25791 |
blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV |
| 25792 |
will have a reference count of 1, and the RV will be returned. |
| 25793 |
.RS 4 |
| 25794 |
.Sp |
| 25795 |
.Vb 2 |
| 25796 |
\& SV * sv_setref_uv(SV * const rv, const char * const classname, |
| 25797 |
\& const UV uv) |
| 25798 |
.Ve |
| 25799 |
.RE |
| 25800 |
.RS 4 |
| 25801 |
.RE |
| 25802 |
.ie n .IP """sv_setrv_inc""" 4 |
| 25803 |
.el .IP \f(CWsv_setrv_inc\fR 4 |
| 25804 |
.IX Item "sv_setrv_inc" |
| 25805 |
.PD 0 |
| 25806 |
.ie n .IP """sv_setrv_inc_mg""" 4 |
| 25807 |
.el .IP \f(CWsv_setrv_inc_mg\fR 4 |
| 25808 |
.IX Xref "sv_setrv_inc sv_setrv_inc_mg" |
| 25809 |
.IX Item "sv_setrv_inc_mg" |
| 25810 |
.PD |
| 25811 |
As \f(CW\*(C`sv_setrv_noinc\*(C'\fR but increments the reference count of \fIref\fR. |
| 25812 |
.Sp |
| 25813 |
\&\f(CW\*(C`sv_setrv_inc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_inc\*(C'\fR will |
| 25814 |
not. |
| 25815 |
.RS 4 |
| 25816 |
.Sp |
| 25817 |
.Vb 1 |
| 25818 |
\& void sv_setrv_inc(SV * const sv, SV * const ref) |
| 25819 |
.Ve |
| 25820 |
.RE |
| 25821 |
.RS 4 |
| 25822 |
.RE |
| 25823 |
.ie n .IP """sv_setrv_noinc""" 4 |
| 25824 |
.el .IP \f(CWsv_setrv_noinc\fR 4 |
| 25825 |
.IX Item "sv_setrv_noinc" |
| 25826 |
.PD 0 |
| 25827 |
.ie n .IP """sv_setrv_noinc_mg""" 4 |
| 25828 |
.el .IP \f(CWsv_setrv_noinc_mg\fR 4 |
| 25829 |
.IX Xref "sv_setrv_noinc sv_setrv_noinc_mg" |
| 25830 |
.IX Item "sv_setrv_noinc_mg" |
| 25831 |
.PD |
| 25832 |
Copies an SV pointer into the given SV as an SV reference, upgrading it if |
| 25833 |
necessary. After this, \f(CWSvRV(sv)\fR is equal to \fIref\fR. This does not adjust |
| 25834 |
the reference count of \fIref\fR. The reference \fIref\fR must not be NULL. |
| 25835 |
.Sp |
| 25836 |
\&\f(CW\*(C`sv_setrv_noinc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_noinc\*(C'\fR will |
| 25837 |
not. |
| 25838 |
.RS 4 |
| 25839 |
.Sp |
| 25840 |
.Vb 1 |
| 25841 |
\& void sv_setrv_noinc(SV * const sv, SV * const ref) |
| 25842 |
.Ve |
| 25843 |
.RE |
| 25844 |
.RS 4 |
| 25845 |
.RE |
| 25846 |
.ie n .IP """sv_setsv""" 4 |
| 25847 |
.el .IP \f(CWsv_setsv\fR 4 |
| 25848 |
.IX Item "sv_setsv" |
| 25849 |
.PD 0 |
| 25850 |
.ie n .IP """sv_setsv_flags""" 4 |
| 25851 |
.el .IP \f(CWsv_setsv_flags\fR 4 |
| 25852 |
.IX Item "sv_setsv_flags" |
| 25853 |
.ie n .IP """sv_setsv_mg""" 4 |
| 25854 |
.el .IP \f(CWsv_setsv_mg\fR 4 |
| 25855 |
.IX Item "sv_setsv_mg" |
| 25856 |
.ie n .IP """sv_setsv_nomg""" 4 |
| 25857 |
.el .IP \f(CWsv_setsv_nomg\fR 4 |
| 25858 |
.IX Xref "sv_setsv sv_setsv_flags sv_setsv_mg sv_setsv_nomg" |
| 25859 |
.IX Item "sv_setsv_nomg" |
| 25860 |
.PD |
| 25861 |
These copy the contents of the source SV \f(CW\*(C`ssv\*(C'\fR into the destination SV \f(CW\*(C`dsv\*(C'\fR. |
| 25862 |
\&\f(CW\*(C`ssv\*(C'\fR may be destroyed if it is mortal, so don't use these functions if |
| 25863 |
the source SV needs to be reused. |
| 25864 |
Loosely speaking, they perform a copy-by-value, obliterating any previous |
| 25865 |
content of the destination. |
| 25866 |
.Sp |
| 25867 |
They differ only in that: |
| 25868 |
.Sp |
| 25869 |
\&\f(CW\*(C`sv_setsv\*(C'\fR calls 'get' magic on \f(CW\*(C`ssv\*(C'\fR, but skips 'set' magic on \f(CW\*(C`dsv\*(C'\fR. |
| 25870 |
.Sp |
| 25871 |
\&\f(CW\*(C`sv_setsv_mg\*(C'\fR calls both 'get' magic on \f(CW\*(C`ssv\*(C'\fR and 'set' magic on \f(CW\*(C`dsv\*(C'\fR. |
| 25872 |
.Sp |
| 25873 |
\&\f(CW\*(C`sv_setsv_nomg\*(C'\fR skips all magic. |
| 25874 |
.Sp |
| 25875 |
\&\f(CW\*(C`sv_setsv_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter which you can use to specify any |
| 25876 |
combination of magic handling, and also you can specify \f(CW\*(C`SV_NOSTEAL\*(C'\fR so that |
| 25877 |
the buffers of temps will not be stolen. |
| 25878 |
.Sp |
| 25879 |
You probably want to instead use one of the assortment of wrappers, such as |
| 25880 |
\&\f(CW"SvSetSV"\fR, \f(CW"SvSetSV_nosteal"\fR, \f(CW"SvSetMagicSV"\fR and |
| 25881 |
\&\f(CW"SvSetMagicSV_nosteal"\fR. |
| 25882 |
.Sp |
| 25883 |
\&\f(CW\*(C`sv_setsv_flags\*(C'\fR is the primary function for copying scalars, and most other |
| 25884 |
copy-ish functions and macros use it underneath. |
| 25885 |
.RS 4 |
| 25886 |
.Sp |
| 25887 |
.Vb 4 |
| 25888 |
\& void sv_setsv (SV *dsv, SV *ssv) |
| 25889 |
\& void sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags) |
| 25890 |
\& void sv_setsv_mg (SV * const dsv, SV * const ssv) |
| 25891 |
\& void sv_setsv_nomg (SV *dsv, SV *ssv) |
| 25892 |
.Ve |
| 25893 |
.RE |
| 25894 |
.RS 4 |
| 25895 |
.RE |
| 25896 |
.ie n .IP """sv_set_true""" 4 |
| 25897 |
.el .IP \f(CWsv_set_true\fR 4 |
| 25898 |
.IX Xref "sv_set_true" |
| 25899 |
.IX Item "sv_set_true" |
| 25900 |
Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_yes)\*(C'\fR, but may be made more |
| 25901 |
efficient in the future. Doesn't handle set magic. |
| 25902 |
.Sp |
| 25903 |
The perl equivalent is \f(CW\*(C`$sv = !0;\*(C'\fR. |
| 25904 |
.Sp |
| 25905 |
Introduced in perl 5.35.11. |
| 25906 |
.RS 4 |
| 25907 |
.Sp |
| 25908 |
.Vb 1 |
| 25909 |
\& void sv_set_true(SV *sv) |
| 25910 |
.Ve |
| 25911 |
.RE |
| 25912 |
.RS 4 |
| 25913 |
.RE |
| 25914 |
.ie n .IP """sv_set_undef""" 4 |
| 25915 |
.el .IP \f(CWsv_set_undef\fR 4 |
| 25916 |
.IX Xref "sv_set_undef" |
| 25917 |
.IX Item "sv_set_undef" |
| 25918 |
Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_undef)\*(C'\fR, but more efficient. |
| 25919 |
Doesn't handle set magic. |
| 25920 |
.Sp |
| 25921 |
The perl equivalent is \f(CW\*(C`$sv = undef;\*(C'\fR. Note that it doesn't free any string |
| 25922 |
buffer, unlike \f(CW\*(C`undef $sv\*(C'\fR. |
| 25923 |
.Sp |
| 25924 |
Introduced in perl 5.25.12. |
| 25925 |
.RS 4 |
| 25926 |
.Sp |
| 25927 |
.Vb 1 |
| 25928 |
\& void sv_set_undef(SV *sv) |
| 25929 |
.Ve |
| 25930 |
.RE |
| 25931 |
.RS 4 |
| 25932 |
.RE |
| 25933 |
.ie n .IP """sv_setuv""" 4 |
| 25934 |
.el .IP \f(CWsv_setuv\fR 4 |
| 25935 |
.IX Item "sv_setuv" |
| 25936 |
.PD 0 |
| 25937 |
.ie n .IP """sv_setuv_mg""" 4 |
| 25938 |
.el .IP \f(CWsv_setuv_mg\fR 4 |
| 25939 |
.IX Xref "sv_setuv sv_setuv_mg" |
| 25940 |
.IX Item "sv_setuv_mg" |
| 25941 |
.PD |
| 25942 |
These copy an unsigned integer into the given SV, upgrading first if necessary. |
| 25943 |
.Sp |
| 25944 |
They differ only in that \f(CW\*(C`sv_setuv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setuv\*(C'\fR does |
| 25945 |
not. |
| 25946 |
.RS 4 |
| 25947 |
.Sp |
| 25948 |
.Vb 2 |
| 25949 |
\& void sv_setuv (SV * const sv, const UV num) |
| 25950 |
\& void sv_setuv_mg(SV * const sv, const UV u) |
| 25951 |
.Ve |
| 25952 |
.RE |
| 25953 |
.RS 4 |
| 25954 |
.RE |
| 25955 |
.ie n .IP """SvSHARE""" 4 |
| 25956 |
.el .IP \f(CWSvSHARE\fR 4 |
| 25957 |
.IX Xref "SvSHARE" |
| 25958 |
.IX Item "SvSHARE" |
| 25959 |
Arranges for \f(CW\*(C`sv\*(C'\fR to be shared between threads if a suitable module |
| 25960 |
has been loaded. |
| 25961 |
.RS 4 |
| 25962 |
.Sp |
| 25963 |
.Vb 1 |
| 25964 |
\& void SvSHARE(SV* sv) |
| 25965 |
.Ve |
| 25966 |
.RE |
| 25967 |
.RS 4 |
| 25968 |
.RE |
| 25969 |
.ie n .IP """SvSHARED_HASH""" 4 |
| 25970 |
.el .IP \f(CWSvSHARED_HASH\fR 4 |
| 25971 |
.IX Xref "SvSHARED_HASH" |
| 25972 |
.IX Item "SvSHARED_HASH" |
| 25973 |
Returns the hash for \f(CW\*(C`sv\*(C'\fR created by \f(CW"newSVpvn_share"\fR. |
| 25974 |
.RS 4 |
| 25975 |
.Sp |
| 25976 |
.Vb 1 |
| 25977 |
\& struct hek* SvSHARED_HASH(SV * sv) |
| 25978 |
.Ve |
| 25979 |
.RE |
| 25980 |
.RS 4 |
| 25981 |
.RE |
| 25982 |
.ie n .IP """SvSTASH""" 4 |
| 25983 |
.el .IP \f(CWSvSTASH\fR 4 |
| 25984 |
.IX Xref "SvSTASH" |
| 25985 |
.IX Item "SvSTASH" |
| 25986 |
Returns the stash of the SV. |
| 25987 |
.RS 4 |
| 25988 |
.Sp |
| 25989 |
.Vb 1 |
| 25990 |
\& HV* SvSTASH(SV* sv) |
| 25991 |
.Ve |
| 25992 |
.RE |
| 25993 |
.RS 4 |
| 25994 |
.RE |
| 25995 |
.ie n .IP """SvSTASH_set""" 4 |
| 25996 |
.el .IP \f(CWSvSTASH_set\fR 4 |
| 25997 |
.IX Xref "SvSTASH_set" |
| 25998 |
.IX Item "SvSTASH_set" |
| 25999 |
Set the value of the STASH pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR. |
| 26000 |
.RS 4 |
| 26001 |
.Sp |
| 26002 |
.Vb 1 |
| 26003 |
\& void SvSTASH_set(SV* sv, HV* val) |
| 26004 |
.Ve |
| 26005 |
.RE |
| 26006 |
.RS 4 |
| 26007 |
.RE |
| 26008 |
.ie n .IP """sv_streq""" 4 |
| 26009 |
.el .IP \f(CWsv_streq\fR 4 |
| 26010 |
.IX Xref "sv_streq" |
| 26011 |
.IX Item "sv_streq" |
| 26012 |
A convenient shortcut for calling \f(CW\*(C`sv_streq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR |
| 26013 |
flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 eq $sv2\*(C'\fR. |
| 26014 |
.RS 4 |
| 26015 |
.Sp |
| 26016 |
.Vb 1 |
| 26017 |
\& bool sv_streq(SV *sv1, SV *sv2) |
| 26018 |
.Ve |
| 26019 |
.RE |
| 26020 |
.RS 4 |
| 26021 |
.RE |
| 26022 |
.ie n .IP """sv_streq_flags""" 4 |
| 26023 |
.el .IP \f(CWsv_streq_flags\fR 4 |
| 26024 |
.IX Xref "sv_streq_flags" |
| 26025 |
.IX Item "sv_streq_flags" |
| 26026 |
Returns a boolean indicating whether the strings in the two SVs are |
| 26027 |
identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles |
| 26028 |
get-magic too. Will coerce its args to strings if necessary. Treats |
| 26029 |
\&\f(CW\*(C`NULL\*(C'\fR as undef. Correctly handles the UTF8 flag. |
| 26030 |
.Sp |
| 26031 |
If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use |
| 26032 |
\&\f(CW\*(C`eq\*(C'\fR overloading will be made. If such overloading does not exist or the |
| 26033 |
flag is set, then regular string comparison will be used instead. |
| 26034 |
.RS 4 |
| 26035 |
.Sp |
| 26036 |
.Vb 1 |
| 26037 |
\& bool sv_streq_flags(SV *sv1, SV *sv2, const U32 flags) |
| 26038 |
.Ve |
| 26039 |
.RE |
| 26040 |
.RS 4 |
| 26041 |
.RE |
| 26042 |
.ie n .IP """SvTRUE""" 4 |
| 26043 |
.el .IP \f(CWSvTRUE\fR 4 |
| 26044 |
.IX Item "SvTRUE" |
| 26045 |
.PD 0 |
| 26046 |
.ie n .IP """SvTRUE_NN""" 4 |
| 26047 |
.el .IP \f(CWSvTRUE_NN\fR 4 |
| 26048 |
.IX Item "SvTRUE_NN" |
| 26049 |
.ie n .IP """SvTRUE_nomg""" 4 |
| 26050 |
.el .IP \f(CWSvTRUE_nomg\fR 4 |
| 26051 |
.IX Item "SvTRUE_nomg" |
| 26052 |
.ie n .IP """SvTRUE_nomg_NN""" 4 |
| 26053 |
.el .IP \f(CWSvTRUE_nomg_NN\fR 4 |
| 26054 |
.IX Item "SvTRUE_nomg_NN" |
| 26055 |
.ie n .IP """SvTRUEx""" 4 |
| 26056 |
.el .IP \f(CWSvTRUEx\fR 4 |
| 26057 |
.IX Xref "SvTRUE SvTRUE_NN SvTRUE_nomg SvTRUE_nomg_NN SvTRUEx" |
| 26058 |
.IX Item "SvTRUEx" |
| 26059 |
.PD |
| 26060 |
These return a boolean indicating whether Perl would evaluate the SV as true or |
| 26061 |
false. See \f(CW"SvOK"\fR for a defined/undefined test. |
| 26062 |
.Sp |
| 26063 |
As of Perl 5.32, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. Prior to that |
| 26064 |
release, only \f(CW\*(C`SvTRUEx\*(C'\fR guaranteed single evaluation; now \f(CW\*(C`SvTRUEx\*(C'\fR is |
| 26065 |
identical to \f(CW\*(C`SvTRUE\*(C'\fR. |
| 26066 |
.Sp |
| 26067 |
\&\f(CW\*(C`SvTRUE_nomg\*(C'\fR and \f(CW\*(C`TRUE_nomg_NN\*(C'\fR do not perform 'get' magic; the others do |
| 26068 |
unless the scalar is already \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR, or \f(CW\*(C`SvNOK\*(C'\fR (the public, not |
| 26069 |
the private flags). |
| 26070 |
.Sp |
| 26071 |
\&\f(CW\*(C`SvTRUE_NN\*(C'\fR is like \f(CW"SvTRUE"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be |
| 26072 |
non-null (NN). If there is a possibility that it is NULL, use plain |
| 26073 |
\&\f(CW\*(C`SvTRUE\*(C'\fR. |
| 26074 |
.Sp |
| 26075 |
\&\f(CW\*(C`SvTRUE_nomg_NN\*(C'\fR is like \f(CW"SvTRUE_nomg"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be |
| 26076 |
non-null (NN). If there is a possibility that it is NULL, use plain |
| 26077 |
\&\f(CW\*(C`SvTRUE_nomg\*(C'\fR. |
| 26078 |
.RS 4 |
| 26079 |
.Sp |
| 26080 |
.Vb 1 |
| 26081 |
\& bool SvTRUE(SV *sv) |
| 26082 |
.Ve |
| 26083 |
.RE |
| 26084 |
.RS 4 |
| 26085 |
.RE |
| 26086 |
.ie n .IP """SvTYPE""" 4 |
| 26087 |
.el .IP \f(CWSvTYPE\fR 4 |
| 26088 |
.IX Xref "SvTYPE" |
| 26089 |
.IX Item "SvTYPE" |
| 26090 |
Returns the type of the SV. See \f(CW"svtype"\fR. |
| 26091 |
.RS 4 |
| 26092 |
.Sp |
| 26093 |
.Vb 1 |
| 26094 |
\& svtype SvTYPE(SV* sv) |
| 26095 |
.Ve |
| 26096 |
.RE |
| 26097 |
.RS 4 |
| 26098 |
.RE |
| 26099 |
.ie n .IP """SvUNLOCK""" 4 |
| 26100 |
.el .IP \f(CWSvUNLOCK\fR 4 |
| 26101 |
.IX Xref "SvUNLOCK" |
| 26102 |
.IX Item "SvUNLOCK" |
| 26103 |
Releases a mutual exclusion lock on \f(CW\*(C`sv\*(C'\fR if a suitable module |
| 26104 |
has been loaded. |
| 26105 |
.RS 4 |
| 26106 |
.Sp |
| 26107 |
.Vb 1 |
| 26108 |
\& void SvUNLOCK(SV* sv) |
| 26109 |
.Ve |
| 26110 |
.RE |
| 26111 |
.RS 4 |
| 26112 |
.RE |
| 26113 |
.ie n .IP """sv_unmagic""" 4 |
| 26114 |
.el .IP \f(CWsv_unmagic\fR 4 |
| 26115 |
.IX Xref "sv_unmagic" |
| 26116 |
.IX Item "sv_unmagic" |
| 26117 |
Removes all magic of type \f(CW\*(C`type\*(C'\fR from an SV. |
| 26118 |
.RS 4 |
| 26119 |
.Sp |
| 26120 |
.Vb 1 |
| 26121 |
\& int sv_unmagic(SV * const sv, const int type) |
| 26122 |
.Ve |
| 26123 |
.RE |
| 26124 |
.RS 4 |
| 26125 |
.RE |
| 26126 |
.ie n .IP """sv_unmagicext""" 4 |
| 26127 |
.el .IP \f(CWsv_unmagicext\fR 4 |
| 26128 |
.IX Xref "sv_unmagicext" |
| 26129 |
.IX Item "sv_unmagicext" |
| 26130 |
Removes all magic of type \f(CW\*(C`type\*(C'\fR with the specified \f(CW\*(C`vtbl\*(C'\fR from an SV. |
| 26131 |
.RS 4 |
| 26132 |
.Sp |
| 26133 |
.Vb 2 |
| 26134 |
\& int sv_unmagicext(SV * const sv, const int type, |
| 26135 |
\& const MGVTBL *vtbl) |
| 26136 |
.Ve |
| 26137 |
.RE |
| 26138 |
.RS 4 |
| 26139 |
.RE |
| 26140 |
.ie n .IP """sv_unref""" 4 |
| 26141 |
.el .IP \f(CWsv_unref\fR 4 |
| 26142 |
.IX Xref "sv_unref" |
| 26143 |
.IX Item "sv_unref" |
| 26144 |
Unsets the RV status of the SV, and decrements the reference count of |
| 26145 |
whatever was being referenced by the RV. This can almost be thought of |
| 26146 |
as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. This is \f(CW\*(C`sv_unref_flags\*(C'\fR with the \f(CW\*(C`flag\*(C'\fR |
| 26147 |
being zero. See \f(CW"SvROK_off"\fR. |
| 26148 |
.RS 4 |
| 26149 |
.Sp |
| 26150 |
.Vb 1 |
| 26151 |
\& void sv_unref(SV *sv) |
| 26152 |
.Ve |
| 26153 |
.RE |
| 26154 |
.RS 4 |
| 26155 |
.RE |
| 26156 |
.ie n .IP """sv_unref_flags""" 4 |
| 26157 |
.el .IP \f(CWsv_unref_flags\fR 4 |
| 26158 |
.IX Xref "sv_unref_flags" |
| 26159 |
.IX Item "sv_unref_flags" |
| 26160 |
Unsets the RV status of the SV, and decrements the reference count of |
| 26161 |
whatever was being referenced by the RV. This can almost be thought of |
| 26162 |
as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. The \f(CW\*(C`cflags\*(C'\fR argument can contain |
| 26163 |
\&\f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR to force the reference count to be decremented |
| 26164 |
(otherwise the decrementing is conditional on the reference count being |
| 26165 |
different from one or the reference being a readonly SV). |
| 26166 |
See \f(CW"SvROK_off"\fR. |
| 26167 |
.RS 4 |
| 26168 |
.Sp |
| 26169 |
.Vb 1 |
| 26170 |
\& void sv_unref_flags(SV * const ref, const U32 flags) |
| 26171 |
.Ve |
| 26172 |
.RE |
| 26173 |
.RS 4 |
| 26174 |
.RE |
| 26175 |
.ie n .IP """SvUOK""" 4 |
| 26176 |
.el .IP \f(CWSvUOK\fR 4 |
| 26177 |
.IX Xref "SvUOK" |
| 26178 |
.IX Item "SvUOK" |
| 26179 |
Returns a boolean indicating whether the SV contains an integer that must be |
| 26180 |
interpreted as unsigned. A non-negative integer whose value is within the |
| 26181 |
range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR. |
| 26182 |
.RS 4 |
| 26183 |
.Sp |
| 26184 |
.Vb 1 |
| 26185 |
\& bool SvUOK(SV* sv) |
| 26186 |
.Ve |
| 26187 |
.RE |
| 26188 |
.RS 4 |
| 26189 |
.RE |
| 26190 |
.ie n .IP """SvUPGRADE""" 4 |
| 26191 |
.el .IP \f(CWSvUPGRADE\fR 4 |
| 26192 |
.IX Xref "SvUPGRADE" |
| 26193 |
.IX Item "SvUPGRADE" |
| 26194 |
Used to upgrade an SV to a more complex form. Uses \f(CW\*(C`sv_upgrade\*(C'\fR to |
| 26195 |
perform the upgrade if necessary. See \f(CW"svtype"\fR. |
| 26196 |
.RS 4 |
| 26197 |
.Sp |
| 26198 |
.Vb 1 |
| 26199 |
\& void SvUPGRADE(SV* sv, svtype type) |
| 26200 |
.Ve |
| 26201 |
.RE |
| 26202 |
.RS 4 |
| 26203 |
.RE |
| 26204 |
.ie n .IP """sv_upgrade""" 4 |
| 26205 |
.el .IP \f(CWsv_upgrade\fR 4 |
| 26206 |
.IX Xref "sv_upgrade" |
| 26207 |
.IX Item "sv_upgrade" |
| 26208 |
Upgrade an SV to a more complex form. Generally adds a new body type to the |
| 26209 |
SV, then copies across as much information as possible from the old body. |
| 26210 |
It croaks if the SV is already in a more complex form than requested. You |
| 26211 |
generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper, which checks the type |
| 26212 |
before calling \f(CW\*(C`sv_upgrade\*(C'\fR, and hence does not croak. See also |
| 26213 |
\&\f(CW"svtype"\fR. |
| 26214 |
.RS 4 |
| 26215 |
.Sp |
| 26216 |
.Vb 1 |
| 26217 |
\& void sv_upgrade(SV * const sv, svtype new_type) |
| 26218 |
.Ve |
| 26219 |
.RE |
| 26220 |
.RS 4 |
| 26221 |
.RE |
| 26222 |
.ie n .IP """sv_usepvn""" 4 |
| 26223 |
.el .IP \f(CWsv_usepvn\fR 4 |
| 26224 |
.IX Item "sv_usepvn" |
| 26225 |
.PD 0 |
| 26226 |
.ie n .IP """sv_usepvn_flags""" 4 |
| 26227 |
.el .IP \f(CWsv_usepvn_flags\fR 4 |
| 26228 |
.IX Item "sv_usepvn_flags" |
| 26229 |
.ie n .IP """sv_usepvn_mg""" 4 |
| 26230 |
.el .IP \f(CWsv_usepvn_mg\fR 4 |
| 26231 |
.IX Xref "sv_usepvn sv_usepvn_flags sv_usepvn_mg" |
| 26232 |
.IX Item "sv_usepvn_mg" |
| 26233 |
.PD |
| 26234 |
These tell an SV to use \f(CW\*(C`ptr\*(C'\fR for its string value. Normally SVs have |
| 26235 |
their string stored inside the SV, but these tell the SV to use an |
| 26236 |
external string instead. |
| 26237 |
.Sp |
| 26238 |
\&\f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated |
| 26239 |
by "\f(CW\*(C`Newx\*(C'\fR". It must be |
| 26240 |
the start of a \f(CW\*(C`Newx\*(C'\fR\-ed block of memory, and not a pointer to the |
| 26241 |
middle of it (beware of \f(CW\*(C`OOK\*(C'\fR and copy-on-write), |
| 26242 |
and not be from a non\-\f(CW\*(C`Newx\*(C'\fR memory allocator like \f(CW\*(C`malloc\*(C'\fR. The |
| 26243 |
string length, \f(CW\*(C`len\*(C'\fR, must be supplied. By default this function |
| 26244 |
will "\f(CW\*(C`Renew\*(C'\fR" (i.e. realloc, move) the memory pointed to by \f(CW\*(C`ptr\*(C'\fR, |
| 26245 |
so that the pointer should not be freed or used by the programmer after giving |
| 26246 |
it to \f(CW\*(C`sv_usepvn\*(C'\fR, and neither should any pointers from "behind" that pointer |
| 26247 |
(\fIe.g.\fR, \f(CW\*(C`ptr\*(C'\fR\ +\ 1) be used. |
| 26248 |
.Sp |
| 26249 |
In the \f(CW\*(C`sv_usepvn_flags\*(C'\fR form, if \f(CW\*(C`flags\ &\ SV_SMAGIC\*(C'\fR is true, |
| 26250 |
\&\f(CW\*(C`SvSETMAGIC\*(C'\fR is called before returning. |
| 26251 |
And if \f(CW\*(C`flags\ &\ SV_HAS_TRAILING_NUL\*(C'\fR is true, then \f(CW\*(C`ptr[len]\*(C'\fR must be |
| 26252 |
\&\f(CW\*(C`NUL\*(C'\fR, and the realloc will be skipped (\fIi.e.\fR, the buffer is actually at |
| 26253 |
least 1 byte longer than \f(CW\*(C`len\*(C'\fR, and already meets the requirements for storing |
| 26254 |
in \f(CW\*(C`SvPVX\*(C'\fR). |
| 26255 |
.Sp |
| 26256 |
\&\f(CW\*(C`sv_usepvn\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to 0, so 'set' |
| 26257 |
magic is skipped. |
| 26258 |
.Sp |
| 26259 |
\&\f(CW\*(C`sv_usepvn_mg\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to \f(CW\*(C`SV_SMAGIC\*(C'\fR, |
| 26260 |
so 'set' magic is performed. |
| 26261 |
.RS 4 |
| 26262 |
.Sp |
| 26263 |
.Vb 4 |
| 26264 |
\& void sv_usepvn (SV *sv, char *ptr, STRLEN len) |
| 26265 |
\& void sv_usepvn_flags(SV * const sv, char *ptr, const STRLEN len, |
| 26266 |
\& const U32 flags) |
| 26267 |
\& void sv_usepvn_mg (SV *sv, char *ptr, STRLEN len) |
| 26268 |
.Ve |
| 26269 |
.RE |
| 26270 |
.RS 4 |
| 26271 |
.RE |
| 26272 |
.ie n .IP """sv_utf8_decode""" 4 |
| 26273 |
.el .IP \f(CWsv_utf8_decode\fR 4 |
| 26274 |
.IX Xref "sv_utf8_decode" |
| 26275 |
.IX Item "sv_utf8_decode" |
| 26276 |
If the PV of the SV is an octet sequence in Perl's extended UTF\-8 |
| 26277 |
and contains a multiple-byte character, the \f(CW\*(C`SvUTF8\*(C'\fR flag is turned on |
| 26278 |
so that it looks like a character. If the PV contains only single-byte |
| 26279 |
characters, the \f(CW\*(C`SvUTF8\*(C'\fR flag stays off. |
| 26280 |
Scans PV for validity and returns FALSE if the PV is invalid UTF\-8. |
| 26281 |
.RS 4 |
| 26282 |
.Sp |
| 26283 |
.Vb 1 |
| 26284 |
\& bool sv_utf8_decode(SV * const sv) |
| 26285 |
.Ve |
| 26286 |
.RE |
| 26287 |
.RS 4 |
| 26288 |
.RE |
| 26289 |
.ie n .IP """sv_utf8_downgrade""" 4 |
| 26290 |
.el .IP \f(CWsv_utf8_downgrade\fR 4 |
| 26291 |
.IX Item "sv_utf8_downgrade" |
| 26292 |
.PD 0 |
| 26293 |
.ie n .IP """sv_utf8_downgrade_flags""" 4 |
| 26294 |
.el .IP \f(CWsv_utf8_downgrade_flags\fR 4 |
| 26295 |
.IX Item "sv_utf8_downgrade_flags" |
| 26296 |
.ie n .IP """sv_utf8_downgrade_nomg""" 4 |
| 26297 |
.el .IP \f(CWsv_utf8_downgrade_nomg\fR 4 |
| 26298 |
.IX Xref "sv_utf8_downgrade sv_utf8_downgrade_flags sv_utf8_downgrade_nomg" |
| 26299 |
.IX Item "sv_utf8_downgrade_nomg" |
| 26300 |
.PD |
| 26301 |
These attempt to convert the PV of an SV from characters to bytes. If the PV |
| 26302 |
contains a character that cannot fit in a byte, this conversion will fail; in |
| 26303 |
this case, \f(CW\*(C`FALSE\*(C'\fR is returned if \f(CW\*(C`fail_ok\*(C'\fR is true; otherwise they croak. |
| 26304 |
.Sp |
| 26305 |
They are not a general purpose Unicode to byte encoding interface: |
| 26306 |
use the \f(CW\*(C`Encode\*(C'\fR extension for that. |
| 26307 |
.Sp |
| 26308 |
They differ only in that: |
| 26309 |
.Sp |
| 26310 |
\&\f(CW\*(C`sv_utf8_downgrade\*(C'\fR processes 'get' magic on \f(CW\*(C`sv\*(C'\fR. |
| 26311 |
.Sp |
| 26312 |
\&\f(CW\*(C`sv_utf8_downgrade_nomg\*(C'\fR does not. |
| 26313 |
.Sp |
| 26314 |
\&\f(CW\*(C`sv_utf8_downgrade_flags\*(C'\fR has an additional \f(CW\*(C`flags\*(C'\fR parameter in which you can specify |
| 26315 |
\&\f(CW\*(C`SV_GMAGIC\*(C'\fR to process 'get' magic, or leave it cleared to not process 'get' magic. |
| 26316 |
.RS 4 |
| 26317 |
.Sp |
| 26318 |
.Vb 4 |
| 26319 |
\& bool sv_utf8_downgrade (SV * const sv, const bool fail_ok) |
| 26320 |
\& bool sv_utf8_downgrade_flags(SV * const sv, const bool fail_ok, |
| 26321 |
\& const U32 flags) |
| 26322 |
\& bool sv_utf8_downgrade_nomg (SV * const sv, const bool fail_ok) |
| 26323 |
.Ve |
| 26324 |
.RE |
| 26325 |
.RS 4 |
| 26326 |
.RE |
| 26327 |
.ie n .IP """sv_utf8_encode""" 4 |
| 26328 |
.el .IP \f(CWsv_utf8_encode\fR 4 |
| 26329 |
.IX Xref "sv_utf8_encode" |
| 26330 |
.IX Item "sv_utf8_encode" |
| 26331 |
Converts the PV of an SV to UTF\-8, but then turns the \f(CW\*(C`SvUTF8\*(C'\fR |
| 26332 |
flag off so that it looks like octets again. |
| 26333 |
.RS 4 |
| 26334 |
.Sp |
| 26335 |
.Vb 1 |
| 26336 |
\& void sv_utf8_encode(SV * const sv) |
| 26337 |
.Ve |
| 26338 |
.RE |
| 26339 |
.RS 4 |
| 26340 |
.RE |
| 26341 |
.ie n .IP """SvUTF8_off""" 4 |
| 26342 |
.el .IP \f(CWSvUTF8_off\fR 4 |
| 26343 |
.IX Xref "SvUTF8_off" |
| 26344 |
.IX Item "SvUTF8_off" |
| 26345 |
Unsets the UTF\-8 status of an SV (the data is not changed, just the flag). |
| 26346 |
Do not use frivolously. |
| 26347 |
.RS 4 |
| 26348 |
.Sp |
| 26349 |
.Vb 1 |
| 26350 |
\& void SvUTF8_off(SV *sv) |
| 26351 |
.Ve |
| 26352 |
.RE |
| 26353 |
.RS 4 |
| 26354 |
.RE |
| 26355 |
.ie n .IP """SvUTF8_on""" 4 |
| 26356 |
.el .IP \f(CWSvUTF8_on\fR 4 |
| 26357 |
.IX Xref "SvUTF8_on" |
| 26358 |
.IX Item "SvUTF8_on" |
| 26359 |
Turn on the UTF\-8 status of an SV (the data is not changed, just the flag). |
| 26360 |
Do not use frivolously. |
| 26361 |
.RS 4 |
| 26362 |
.Sp |
| 26363 |
.Vb 1 |
| 26364 |
\& void SvUTF8_on(SV *sv) |
| 26365 |
.Ve |
| 26366 |
.RE |
| 26367 |
.RS 4 |
| 26368 |
.RE |
| 26369 |
.ie n .IP """sv_utf8_upgrade""" 4 |
| 26370 |
.el .IP \f(CWsv_utf8_upgrade\fR 4 |
| 26371 |
.IX Item "sv_utf8_upgrade" |
| 26372 |
.PD 0 |
| 26373 |
.ie n .IP """sv_utf8_upgrade_flags""" 4 |
| 26374 |
.el .IP \f(CWsv_utf8_upgrade_flags\fR 4 |
| 26375 |
.IX Item "sv_utf8_upgrade_flags" |
| 26376 |
.ie n .IP """sv_utf8_upgrade_flags_grow""" 4 |
| 26377 |
.el .IP \f(CWsv_utf8_upgrade_flags_grow\fR 4 |
| 26378 |
.IX Item "sv_utf8_upgrade_flags_grow" |
| 26379 |
.ie n .IP """sv_utf8_upgrade_nomg""" 4 |
| 26380 |
.el .IP \f(CWsv_utf8_upgrade_nomg\fR 4 |
| 26381 |
.IX Xref "sv_utf8_upgrade sv_utf8_upgrade_flags sv_utf8_upgrade_flags_grow sv_utf8_upgrade_nomg" |
| 26382 |
.IX Item "sv_utf8_upgrade_nomg" |
| 26383 |
.PD |
| 26384 |
These convert the PV of an SV to its UTF\-8\-encoded form. |
| 26385 |
The SV is forced to string form if it is not already. |
| 26386 |
They always set the \f(CW\*(C`SvUTF8\*(C'\fR flag to avoid future validity checks even if the |
| 26387 |
whole string is the same in UTF\-8 as not. |
| 26388 |
They return the number of bytes in the converted string |
| 26389 |
.Sp |
| 26390 |
The forms differ in just two ways. The main difference is whether or not they |
| 26391 |
perform 'get magic' on \f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR skips 'get magic'; |
| 26392 |
\&\f(CW\*(C`sv_utf8_upgrade\*(C'\fR performs it; and \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR and |
| 26393 |
\&\f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR either perform it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set |
| 26394 |
in \f(CW\*(C`flags\*(C'\fR) or don't (if that bit is cleared). |
| 26395 |
.Sp |
| 26396 |
The other difference is that \f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR has an additional |
| 26397 |
parameter, \f(CW\*(C`extra\*(C'\fR, which allows the caller to specify an amount of space to |
| 26398 |
be reserved as spare beyond what is needed for the actual conversion. This is |
| 26399 |
used when the caller knows it will soon be needing yet more space, and it is |
| 26400 |
more efficient to request space from the system in a single call. |
| 26401 |
This form is otherwise identical to \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR. |
| 26402 |
.Sp |
| 26403 |
These are not a general purpose byte encoding to Unicode interface: use the |
| 26404 |
Encode extension for that. |
| 26405 |
.Sp |
| 26406 |
The \f(CW\*(C`SV_FORCE_UTF8_UPGRADE\*(C'\fR flag is now ignored. |
| 26407 |
.RS 4 |
| 26408 |
.Sp |
| 26409 |
.Vb 5 |
| 26410 |
\& STRLEN sv_utf8_upgrade (SV *sv) |
| 26411 |
\& STRLEN sv_utf8_upgrade_flags (SV * const sv, const I32 flags) |
| 26412 |
\& STRLEN sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags, |
| 26413 |
\& STRLEN extra) |
| 26414 |
\& STRLEN sv_utf8_upgrade_nomg (SV *sv) |
| 26415 |
.Ve |
| 26416 |
.RE |
| 26417 |
.RS 4 |
| 26418 |
.RE |
| 26419 |
.ie n .IP """SvUTF8""" 4 |
| 26420 |
.el .IP \f(CWSvUTF8\fR 4 |
| 26421 |
.IX Xref "SvUTF8" |
| 26422 |
.IX Item "SvUTF8" |
| 26423 |
Returns a U32 value indicating the UTF\-8 status of an SV. If things are set-up |
| 26424 |
properly, this indicates whether or not the SV contains UTF\-8 encoded data. |
| 26425 |
You should use this \fIafter\fR a call to \f(CW"SvPV"\fR or one of its variants, in |
| 26426 |
case any call to string overloading updates the internal flag. |
| 26427 |
.Sp |
| 26428 |
If you want to take into account the bytes pragma, use \f(CW"DO_UTF8"\fR |
| 26429 |
instead. |
| 26430 |
.RS 4 |
| 26431 |
.Sp |
| 26432 |
.Vb 1 |
| 26433 |
\& U32 SvUTF8(SV* sv) |
| 26434 |
.Ve |
| 26435 |
.RE |
| 26436 |
.RS 4 |
| 26437 |
.RE |
| 26438 |
.ie n .IP """SvUV""" 4 |
| 26439 |
.el .IP \f(CWSvUV\fR 4 |
| 26440 |
.IX Item "SvUV" |
| 26441 |
.PD 0 |
| 26442 |
.ie n .IP """SvUV_nomg""" 4 |
| 26443 |
.el .IP \f(CWSvUV_nomg\fR 4 |
| 26444 |
.IX Item "SvUV_nomg" |
| 26445 |
.ie n .IP """SvUVx""" 4 |
| 26446 |
.el .IP \f(CWSvUVx\fR 4 |
| 26447 |
.IX Xref "SvUV SvUV_nomg SvUVx" |
| 26448 |
.IX Item "SvUVx" |
| 26449 |
.PD |
| 26450 |
These each coerce the given SV to UV and return it. The returned value in many |
| 26451 |
circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's UV slot, but not in all cases. (Use |
| 26452 |
\&\f(CW"sv_setuv"\fR to make sure it does). |
| 26453 |
.Sp |
| 26454 |
As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 26455 |
.Sp |
| 26456 |
\&\f(CW\*(C`SvUVx\*(C'\fR is now identical to \f(CW\*(C`SvUV\*(C'\fR, but prior to 5.37.1, it was the only form |
| 26457 |
guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. |
| 26458 |
.RS 4 |
| 26459 |
.Sp |
| 26460 |
.Vb 1 |
| 26461 |
\& UV SvUV(SV *sv) |
| 26462 |
.Ve |
| 26463 |
.RE |
| 26464 |
.RS 4 |
| 26465 |
.RE |
| 26466 |
.ie n .IP """sv_2uv_flags""" 4 |
| 26467 |
.el .IP \f(CWsv_2uv_flags\fR 4 |
| 26468 |
.IX Xref "sv_2uv_flags" |
| 26469 |
.IX Item "sv_2uv_flags" |
| 26470 |
Return the unsigned integer value of an SV, doing any necessary string |
| 26471 |
conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first. |
| 26472 |
Normally used via the \f(CWSvUV(sv)\fR and \f(CWSvUVx(sv)\fR macros. |
| 26473 |
.RS 4 |
| 26474 |
.Sp |
| 26475 |
.Vb 1 |
| 26476 |
\& UV sv_2uv_flags(SV * const sv, const I32 flags) |
| 26477 |
.Ve |
| 26478 |
.RE |
| 26479 |
.RS 4 |
| 26480 |
.RE |
| 26481 |
.ie n .IP """SvUV_set""" 4 |
| 26482 |
.el .IP \f(CWSvUV_set\fR 4 |
| 26483 |
.IX Xref "SvUV_set" |
| 26484 |
.IX Item "SvUV_set" |
| 26485 |
Set the value of the UV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR. |
| 26486 |
.RS 4 |
| 26487 |
.Sp |
| 26488 |
.Vb 1 |
| 26489 |
\& void SvUV_set(SV* sv, UV val) |
| 26490 |
.Ve |
| 26491 |
.RE |
| 26492 |
.RS 4 |
| 26493 |
.RE |
| 26494 |
.ie n .IP """SvUVX""" 4 |
| 26495 |
.el .IP \f(CWSvUVX\fR 4 |
| 26496 |
.IX Xref "SvUVX" |
| 26497 |
.IX Item "SvUVX" |
| 26498 |
Returns the raw value in the SV's UV slot, without checks or conversions. |
| 26499 |
Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvUV"\fR. |
| 26500 |
.RS 4 |
| 26501 |
.Sp |
| 26502 |
.Vb 1 |
| 26503 |
\& UV SvUVX(SV* sv) |
| 26504 |
.Ve |
| 26505 |
.RE |
| 26506 |
.RS 4 |
| 26507 |
.RE |
| 26508 |
.ie n .IP """SvUVXx""" 4 |
| 26509 |
.el .IP \f(CWSvUVXx\fR 4 |
| 26510 |
.IX Xref "SvUVXx" |
| 26511 |
.IX Item "SvUVXx" |
| 26512 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SvUVXx\*(C'\fR |
| 26513 |
from a future release of Perl. Do not use it for |
| 26514 |
new code; remove it from existing code. |
| 26515 |
.Sp |
| 26516 |
This is an unnecessary synonym for "SvUVX" |
| 26517 |
.RS 4 |
| 26518 |
.Sp |
| 26519 |
.Vb 1 |
| 26520 |
\& UV SvUVXx(SV* sv) |
| 26521 |
.Ve |
| 26522 |
.RE |
| 26523 |
.RS 4 |
| 26524 |
.RE |
| 26525 |
.ie n .IP """sv_vcatpvf""" 4 |
| 26526 |
.el .IP \f(CWsv_vcatpvf\fR 4 |
| 26527 |
.IX Item "sv_vcatpvf" |
| 26528 |
.PD 0 |
| 26529 |
.ie n .IP """sv_vcatpvf_mg""" 4 |
| 26530 |
.el .IP \f(CWsv_vcatpvf_mg\fR 4 |
| 26531 |
.IX Xref "sv_vcatpvf sv_vcatpvf_mg" |
| 26532 |
.IX Item "sv_vcatpvf_mg" |
| 26533 |
.PD |
| 26534 |
These process their arguments like \f(CW\*(C`sv_vcatpvfn\*(C'\fR called with a non-null |
| 26535 |
C\-style variable argument list, and append the formatted output to \f(CW\*(C`sv\*(C'\fR. |
| 26536 |
.Sp |
| 26537 |
They differ only in that \f(CW\*(C`sv_vcatpvf_mg\*(C'\fR performs 'set' magic; |
| 26538 |
\&\f(CW\*(C`sv_vcatpvf\*(C'\fR skips 'set' magic. |
| 26539 |
.Sp |
| 26540 |
Both perform 'get' magic. |
| 26541 |
.Sp |
| 26542 |
They are usually accessed via their frontends \f(CW"sv_catpvf"\fR and |
| 26543 |
\&\f(CW"sv_catpvf_mg"\fR. |
| 26544 |
.RS 4 |
| 26545 |
.Sp |
| 26546 |
.Vb 2 |
| 26547 |
\& void sv_vcatpvf(SV * const sv, const char * const pat, |
| 26548 |
\& va_list * const args) |
| 26549 |
.Ve |
| 26550 |
.RE |
| 26551 |
.RS 4 |
| 26552 |
.RE |
| 26553 |
.ie n .IP """sv_vcatpvfn""" 4 |
| 26554 |
.el .IP \f(CWsv_vcatpvfn\fR 4 |
| 26555 |
.IX Item "sv_vcatpvfn" |
| 26556 |
.PD 0 |
| 26557 |
.ie n .IP """sv_vcatpvfn_flags""" 4 |
| 26558 |
.el .IP \f(CWsv_vcatpvfn_flags\fR 4 |
| 26559 |
.IX Xref "sv_vcatpvfn sv_vcatpvfn_flags" |
| 26560 |
.IX Item "sv_vcatpvfn_flags" |
| 26561 |
.PD |
| 26562 |
These process their arguments like \f(CWvsprintf(3)\fR and append the formatted output |
| 26563 |
to an SV. They use an array of SVs if the C\-style variable argument list is |
| 26564 |
missing (\f(CW\*(C`NULL\*(C'\fR). Argument reordering (using format specifiers like \f(CW\*(C`%2$d\*(C'\fR or |
| 26565 |
\&\f(CW\*(C`%*2$d\*(C'\fR) is supported only when using an array of SVs; using a C\-style |
| 26566 |
\&\f(CW\*(C`va_list\*(C'\fR argument list with a format string that uses argument reordering |
| 26567 |
will yield an exception. |
| 26568 |
.Sp |
| 26569 |
When running with taint checks enabled, they indicate via \f(CW\*(C`maybe_tainted\*(C'\fR if |
| 26570 |
results are untrustworthy (often due to the use of locales). |
| 26571 |
.Sp |
| 26572 |
They assume that \f(CW\*(C`pat\*(C'\fR has the same utf8\-ness as \f(CW\*(C`sv\*(C'\fR. It's the caller's |
| 26573 |
responsibility to ensure that this is so. |
| 26574 |
.Sp |
| 26575 |
They differ in that \f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter in which you |
| 26576 |
can set or clear the \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or SV_SMAGIC flags, to specify which |
| 26577 |
magic to handle or not handle; whereas plain \f(CW\*(C`sv_vcatpvfn\*(C'\fR always specifies |
| 26578 |
both 'get' and 'set' magic. |
| 26579 |
.Sp |
| 26580 |
They are usually used via one of the frontends "\f(CW\*(C`sv_vcatpvf\*(C'\fR" and |
| 26581 |
"\f(CW\*(C`sv_vcatpvf_mg\*(C'\fR". |
| 26582 |
.RS 4 |
| 26583 |
.Sp |
| 26584 |
.Vb 9 |
| 26585 |
\& void sv_vcatpvfn (SV * const sv, const char * const pat, |
| 26586 |
\& const STRLEN patlen, va_list * const args, |
| 26587 |
\& SV ** const svargs, const Size_t sv_count, |
| 26588 |
\& bool * const maybe_tainted) |
| 26589 |
\& void sv_vcatpvfn_flags(SV * const sv, const char * const pat, |
| 26590 |
\& const STRLEN patlen, va_list * const args, |
| 26591 |
\& SV ** const svargs, const Size_t sv_count, |
| 26592 |
\& bool * const maybe_tainted, |
| 26593 |
\& const U32 flags) |
| 26594 |
.Ve |
| 26595 |
.RE |
| 26596 |
.RS 4 |
| 26597 |
.RE |
| 26598 |
.ie n .IP """SvVOK""" 4 |
| 26599 |
.el .IP \f(CWSvVOK\fR 4 |
| 26600 |
.IX Xref "SvVOK" |
| 26601 |
.IX Item "SvVOK" |
| 26602 |
Returns a boolean indicating whether the SV contains a v\-string. |
| 26603 |
.RS 4 |
| 26604 |
.Sp |
| 26605 |
.Vb 1 |
| 26606 |
\& bool SvVOK(SV* sv) |
| 26607 |
.Ve |
| 26608 |
.RE |
| 26609 |
.RS 4 |
| 26610 |
.RE |
| 26611 |
.ie n .IP """sv_vsetpvf""" 4 |
| 26612 |
.el .IP \f(CWsv_vsetpvf\fR 4 |
| 26613 |
.IX Item "sv_vsetpvf" |
| 26614 |
.PD 0 |
| 26615 |
.ie n .IP """sv_vsetpvf_mg""" 4 |
| 26616 |
.el .IP \f(CWsv_vsetpvf_mg\fR 4 |
| 26617 |
.IX Xref "sv_vsetpvf sv_vsetpvf_mg" |
| 26618 |
.IX Item "sv_vsetpvf_mg" |
| 26619 |
.PD |
| 26620 |
These work like \f(CW"sv_vcatpvf"\fR but copy the text into the SV instead of |
| 26621 |
appending it. |
| 26622 |
.Sp |
| 26623 |
They differ only in that \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR performs 'set' magic; |
| 26624 |
\&\f(CW\*(C`sv_vsetpvf\*(C'\fR skips all magic. |
| 26625 |
.Sp |
| 26626 |
They are usually used via their frontends, \f(CW"sv_setpvf"\fR and |
| 26627 |
\&\f(CW"sv_setpvf_mg"\fR. |
| 26628 |
.Sp |
| 26629 |
\&\fBThe UTF\-8 flag is not changed by these functions.\fR |
| 26630 |
.RS 4 |
| 26631 |
.Sp |
| 26632 |
.Vb 2 |
| 26633 |
\& void sv_vsetpvf(SV * const sv, const char * const pat, |
| 26634 |
\& va_list * const args) |
| 26635 |
.Ve |
| 26636 |
.RE |
| 26637 |
.RS 4 |
| 26638 |
.RE |
| 26639 |
.ie n .IP """sv_vsetpvfn""" 4 |
| 26640 |
.el .IP \f(CWsv_vsetpvfn\fR 4 |
| 26641 |
.IX Xref "sv_vsetpvfn" |
| 26642 |
.IX Item "sv_vsetpvfn" |
| 26643 |
Works like \f(CW\*(C`sv_vcatpvfn\*(C'\fR but copies the text into the SV instead of |
| 26644 |
appending it. |
| 26645 |
.Sp |
| 26646 |
\&\fBThe UTF\-8 flag is not changed by this function.\fR |
| 26647 |
.Sp |
| 26648 |
Usually used via one of its frontends "\f(CW\*(C`sv_vsetpvf\*(C'\fR" and |
| 26649 |
"\f(CW\*(C`sv_vsetpvf_mg\*(C'\fR". |
| 26650 |
.RS 4 |
| 26651 |
.Sp |
| 26652 |
.Vb 4 |
| 26653 |
\& void sv_vsetpvfn(SV * const sv, const char * const pat, |
| 26654 |
\& const STRLEN patlen, va_list * const args, |
| 26655 |
\& SV ** const svargs, const Size_t sv_count, |
| 26656 |
\& bool * const maybe_tainted) |
| 26657 |
.Ve |
| 26658 |
.RE |
| 26659 |
.RS 4 |
| 26660 |
.RE |
| 26661 |
.ie n .IP """SvVSTRING_mg""" 4 |
| 26662 |
.el .IP \f(CWSvVSTRING_mg\fR 4 |
| 26663 |
.IX Xref "SvVSTRING_mg" |
| 26664 |
.IX Item "SvVSTRING_mg" |
| 26665 |
Returns the vstring magic, or NULL if none |
| 26666 |
.RS 4 |
| 26667 |
.Sp |
| 26668 |
.Vb 1 |
| 26669 |
\& MAGIC* SvVSTRING_mg(SV * sv) |
| 26670 |
.Ve |
| 26671 |
.RE |
| 26672 |
.RS 4 |
| 26673 |
.RE |
| 26674 |
.ie n .IP """vnewSVpvf""" 4 |
| 26675 |
.el .IP \f(CWvnewSVpvf\fR 4 |
| 26676 |
.IX Xref "vnewSVpvf" |
| 26677 |
.IX Item "vnewSVpvf" |
| 26678 |
Like \f(CW"newSVpvf"\fR but the arguments are an encapsulated argument list. |
| 26679 |
.RS 4 |
| 26680 |
.Sp |
| 26681 |
.Vb 1 |
| 26682 |
\& SV * vnewSVpvf(const char * const pat, va_list * const args) |
| 26683 |
.Ve |
| 26684 |
.RE |
| 26685 |
.RS 4 |
| 26686 |
.RE |
| 26687 |
.SH Tainting |
| 26688 |
.IX Header "Tainting" |
| 26689 |
.ie n .IP """SvTAINT""" 4 |
| 26690 |
.el .IP \f(CWSvTAINT\fR 4 |
| 26691 |
.IX Xref "SvTAINT" |
| 26692 |
.IX Item "SvTAINT" |
| 26693 |
Taints an SV if tainting is enabled, and if some input to the current |
| 26694 |
expression is tainted\-\-usually a variable, but possibly also implicit |
| 26695 |
inputs such as locale settings. \f(CW\*(C`SvTAINT\*(C'\fR propagates that taintedness to |
| 26696 |
the outputs of an expression in a pessimistic fashion; i.e., without paying |
| 26697 |
attention to precisely which outputs are influenced by which inputs. |
| 26698 |
.RS 4 |
| 26699 |
.Sp |
| 26700 |
.Vb 1 |
| 26701 |
\& void SvTAINT(SV* sv) |
| 26702 |
.Ve |
| 26703 |
.RE |
| 26704 |
.RS 4 |
| 26705 |
.RE |
| 26706 |
.ie n .IP """SvTAINTED""" 4 |
| 26707 |
.el .IP \f(CWSvTAINTED\fR 4 |
| 26708 |
.IX Xref "SvTAINTED" |
| 26709 |
.IX Item "SvTAINTED" |
| 26710 |
Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if |
| 26711 |
not. |
| 26712 |
.RS 4 |
| 26713 |
.Sp |
| 26714 |
.Vb 1 |
| 26715 |
\& bool SvTAINTED(SV* sv) |
| 26716 |
.Ve |
| 26717 |
.RE |
| 26718 |
.RS 4 |
| 26719 |
.RE |
| 26720 |
.ie n .IP """SvTAINTED_off""" 4 |
| 26721 |
.el .IP \f(CWSvTAINTED_off\fR 4 |
| 26722 |
.IX Xref "SvTAINTED_off" |
| 26723 |
.IX Item "SvTAINTED_off" |
| 26724 |
Untaints an SV. Be \fIvery\fR careful with this routine, as it short-circuits |
| 26725 |
some of Perl's fundamental security features. XS module authors should not |
| 26726 |
use this function unless they fully understand all the implications of |
| 26727 |
unconditionally untainting the value. Untainting should be done in the |
| 26728 |
standard perl fashion, via a carefully crafted regexp, rather than directly |
| 26729 |
untainting variables. |
| 26730 |
.RS 4 |
| 26731 |
.Sp |
| 26732 |
.Vb 1 |
| 26733 |
\& void SvTAINTED_off(SV* sv) |
| 26734 |
.Ve |
| 26735 |
.RE |
| 26736 |
.RS 4 |
| 26737 |
.RE |
| 26738 |
.ie n .IP """SvTAINTED_on""" 4 |
| 26739 |
.el .IP \f(CWSvTAINTED_on\fR 4 |
| 26740 |
.IX Xref "SvTAINTED_on" |
| 26741 |
.IX Item "SvTAINTED_on" |
| 26742 |
Marks an SV as tainted if tainting is enabled. |
| 26743 |
.RS 4 |
| 26744 |
.Sp |
| 26745 |
.Vb 1 |
| 26746 |
\& void SvTAINTED_on(SV* sv) |
| 26747 |
.Ve |
| 26748 |
.RE |
| 26749 |
.RS 4 |
| 26750 |
.RE |
| 26751 |
.SH Time |
| 26752 |
.IX Header "Time" |
| 26753 |
.ie n .IP """ASCTIME_R_PROTO""" 4 |
| 26754 |
.el .IP \f(CWASCTIME_R_PROTO\fR 4 |
| 26755 |
.IX Xref "ASCTIME_R_PROTO" |
| 26756 |
.IX Item "ASCTIME_R_PROTO" |
| 26757 |
This symbol encodes the prototype of \f(CW\*(C`asctime_r\*(C'\fR. |
| 26758 |
It is zero if \f(CW\*(C`d_asctime_r\*(C'\fR is undef, and one of the |
| 26759 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_asctime_r\*(C'\fR |
| 26760 |
is defined. |
| 26761 |
.ie n .IP """CTIME_R_PROTO""" 4 |
| 26762 |
.el .IP \f(CWCTIME_R_PROTO\fR 4 |
| 26763 |
.IX Xref "CTIME_R_PROTO" |
| 26764 |
.IX Item "CTIME_R_PROTO" |
| 26765 |
This symbol encodes the prototype of \f(CW\*(C`ctime_r\*(C'\fR. |
| 26766 |
It is zero if \f(CW\*(C`d_ctime_r\*(C'\fR is undef, and one of the |
| 26767 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctime_r\*(C'\fR |
| 26768 |
is defined. |
| 26769 |
.ie n .IP """GMTIME_MAX""" 4 |
| 26770 |
.el .IP \f(CWGMTIME_MAX\fR 4 |
| 26771 |
.IX Xref "GMTIME_MAX" |
| 26772 |
.IX Item "GMTIME_MAX" |
| 26773 |
This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that |
| 26774 |
the system function gmtime () accepts, and defaults to 0 |
| 26775 |
.ie n .IP """GMTIME_MIN""" 4 |
| 26776 |
.el .IP \f(CWGMTIME_MIN\fR 4 |
| 26777 |
.IX Xref "GMTIME_MIN" |
| 26778 |
.IX Item "GMTIME_MIN" |
| 26779 |
This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that |
| 26780 |
the system function gmtime () accepts, and defaults to 0 |
| 26781 |
.ie n .IP """GMTIME_R_PROTO""" 4 |
| 26782 |
.el .IP \f(CWGMTIME_R_PROTO\fR 4 |
| 26783 |
.IX Xref "GMTIME_R_PROTO" |
| 26784 |
.IX Item "GMTIME_R_PROTO" |
| 26785 |
This symbol encodes the prototype of \f(CW\*(C`gmtime_r\*(C'\fR. |
| 26786 |
It is zero if \f(CW\*(C`d_gmtime_r\*(C'\fR is undef, and one of the |
| 26787 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gmtime_r\*(C'\fR |
| 26788 |
is defined. |
| 26789 |
.ie n .IP """HAS_ASCTIME_R""" 4 |
| 26790 |
.el .IP \f(CWHAS_ASCTIME_R\fR 4 |
| 26791 |
.IX Xref "HAS_ASCTIME_R" |
| 26792 |
.IX Item "HAS_ASCTIME_R" |
| 26793 |
This symbol, if defined, indicates that the \f(CW\*(C`asctime_r\*(C'\fR routine |
| 26794 |
is available to asctime re-entrantly. |
| 26795 |
.ie n .IP """HAS_ASCTIME64""" 4 |
| 26796 |
.el .IP \f(CWHAS_ASCTIME64\fR 4 |
| 26797 |
.IX Xref "HAS_ASCTIME64" |
| 26798 |
.IX Item "HAS_ASCTIME64" |
| 26799 |
This symbol, if defined, indicates that the \f(CW\*(C`asctime64\*(C'\fR () routine is |
| 26800 |
available to do the 64bit variant of asctime () |
| 26801 |
.ie n .IP """HAS_CTIME_R""" 4 |
| 26802 |
.el .IP \f(CWHAS_CTIME_R\fR 4 |
| 26803 |
.IX Xref "HAS_CTIME_R" |
| 26804 |
.IX Item "HAS_CTIME_R" |
| 26805 |
This symbol, if defined, indicates that the \f(CW\*(C`ctime_r\*(C'\fR routine |
| 26806 |
is available to ctime re-entrantly. |
| 26807 |
.ie n .IP """HAS_CTIME64""" 4 |
| 26808 |
.el .IP \f(CWHAS_CTIME64\fR 4 |
| 26809 |
.IX Xref "HAS_CTIME64" |
| 26810 |
.IX Item "HAS_CTIME64" |
| 26811 |
This symbol, if defined, indicates that the \f(CW\*(C`ctime64\*(C'\fR () routine is |
| 26812 |
available to do the 64bit variant of ctime () |
| 26813 |
.ie n .IP """HAS_DIFFTIME""" 4 |
| 26814 |
.el .IP \f(CWHAS_DIFFTIME\fR 4 |
| 26815 |
.IX Xref "HAS_DIFFTIME" |
| 26816 |
.IX Item "HAS_DIFFTIME" |
| 26817 |
This symbol, if defined, indicates that the \f(CW\*(C`difftime\*(C'\fR routine is |
| 26818 |
available. |
| 26819 |
.ie n .IP """HAS_DIFFTIME64""" 4 |
| 26820 |
.el .IP \f(CWHAS_DIFFTIME64\fR 4 |
| 26821 |
.IX Xref "HAS_DIFFTIME64" |
| 26822 |
.IX Item "HAS_DIFFTIME64" |
| 26823 |
This symbol, if defined, indicates that the \f(CW\*(C`difftime64\*(C'\fR () routine is |
| 26824 |
available to do the 64bit variant of difftime () |
| 26825 |
.ie n .IP """HAS_FUTIMES""" 4 |
| 26826 |
.el .IP \f(CWHAS_FUTIMES\fR 4 |
| 26827 |
.IX Xref "HAS_FUTIMES" |
| 26828 |
.IX Item "HAS_FUTIMES" |
| 26829 |
This symbol, if defined, indicates that the \f(CW\*(C`futimes\*(C'\fR routine is |
| 26830 |
available to change file descriptor time stamps with \f(CW\*(C`struct timevals\*(C'\fR. |
| 26831 |
.ie n .IP """HAS_GETITIMER""" 4 |
| 26832 |
.el .IP \f(CWHAS_GETITIMER\fR 4 |
| 26833 |
.IX Xref "HAS_GETITIMER" |
| 26834 |
.IX Item "HAS_GETITIMER" |
| 26835 |
This symbol, if defined, indicates that the \f(CW\*(C`getitimer\*(C'\fR routine is |
| 26836 |
available to return interval timers. |
| 26837 |
.ie n .IP """HAS_GETTIMEOFDAY""" 4 |
| 26838 |
.el .IP \f(CWHAS_GETTIMEOFDAY\fR 4 |
| 26839 |
.IX Xref "HAS_GETTIMEOFDAY" |
| 26840 |
.IX Item "HAS_GETTIMEOFDAY" |
| 26841 |
This symbol, if defined, indicates that the \f(CWgettimeofday()\fR system |
| 26842 |
call is available for a sub-second accuracy clock. Usually, the file |
| 26843 |
\&\fIsys/resource.h\fR needs to be included (see \f(CW"I_SYS_RESOURCE"\fR). |
| 26844 |
The type "Timeval" should be used to refer to "\f(CW\*(C`struct timeval\*(C'\fR". |
| 26845 |
.ie n .IP """HAS_GMTIME_R""" 4 |
| 26846 |
.el .IP \f(CWHAS_GMTIME_R\fR 4 |
| 26847 |
.IX Xref "HAS_GMTIME_R" |
| 26848 |
.IX Item "HAS_GMTIME_R" |
| 26849 |
This symbol, if defined, indicates that the \f(CW\*(C`gmtime_r\*(C'\fR routine |
| 26850 |
is available to gmtime re-entrantly. |
| 26851 |
.ie n .IP """HAS_GMTIME64""" 4 |
| 26852 |
.el .IP \f(CWHAS_GMTIME64\fR 4 |
| 26853 |
.IX Xref "HAS_GMTIME64" |
| 26854 |
.IX Item "HAS_GMTIME64" |
| 26855 |
This symbol, if defined, indicates that the \f(CW\*(C`gmtime64\*(C'\fR () routine is |
| 26856 |
available to do the 64bit variant of gmtime () |
| 26857 |
.ie n .IP """HAS_LOCALTIME_R""" 4 |
| 26858 |
.el .IP \f(CWHAS_LOCALTIME_R\fR 4 |
| 26859 |
.IX Xref "HAS_LOCALTIME_R" |
| 26860 |
.IX Item "HAS_LOCALTIME_R" |
| 26861 |
This symbol, if defined, indicates that the \f(CW\*(C`localtime_r\*(C'\fR routine |
| 26862 |
is available to localtime re-entrantly. |
| 26863 |
.ie n .IP """HAS_LOCALTIME64""" 4 |
| 26864 |
.el .IP \f(CWHAS_LOCALTIME64\fR 4 |
| 26865 |
.IX Xref "HAS_LOCALTIME64" |
| 26866 |
.IX Item "HAS_LOCALTIME64" |
| 26867 |
This symbol, if defined, indicates that the \f(CW\*(C`localtime64\*(C'\fR () routine is |
| 26868 |
available to do the 64bit variant of localtime () |
| 26869 |
.ie n .IP """HAS_MKTIME""" 4 |
| 26870 |
.el .IP \f(CWHAS_MKTIME\fR 4 |
| 26871 |
.IX Xref "HAS_MKTIME" |
| 26872 |
.IX Item "HAS_MKTIME" |
| 26873 |
This symbol, if defined, indicates that the \f(CW\*(C`mktime\*(C'\fR routine is |
| 26874 |
available. |
| 26875 |
.ie n .IP """HAS_MKTIME64""" 4 |
| 26876 |
.el .IP \f(CWHAS_MKTIME64\fR 4 |
| 26877 |
.IX Xref "HAS_MKTIME64" |
| 26878 |
.IX Item "HAS_MKTIME64" |
| 26879 |
This symbol, if defined, indicates that the \f(CW\*(C`mktime64\*(C'\fR () routine is |
| 26880 |
available to do the 64bit variant of mktime () |
| 26881 |
.ie n .IP """HAS_NANOSLEEP""" 4 |
| 26882 |
.el .IP \f(CWHAS_NANOSLEEP\fR 4 |
| 26883 |
.IX Xref "HAS_NANOSLEEP" |
| 26884 |
.IX Item "HAS_NANOSLEEP" |
| 26885 |
This symbol, if defined, indicates that the \f(CW\*(C`nanosleep\*(C'\fR |
| 26886 |
system call is available to sleep with 1E\-9 sec accuracy. |
| 26887 |
.ie n .IP """HAS_SETITIMER""" 4 |
| 26888 |
.el .IP \f(CWHAS_SETITIMER\fR 4 |
| 26889 |
.IX Xref "HAS_SETITIMER" |
| 26890 |
.IX Item "HAS_SETITIMER" |
| 26891 |
This symbol, if defined, indicates that the \f(CW\*(C`setitimer\*(C'\fR routine is |
| 26892 |
available to set interval timers. |
| 26893 |
.ie n .IP """HAS_STRFTIME""" 4 |
| 26894 |
.el .IP \f(CWHAS_STRFTIME\fR 4 |
| 26895 |
.IX Xref "HAS_STRFTIME" |
| 26896 |
.IX Item "HAS_STRFTIME" |
| 26897 |
This symbol, if defined, indicates that the \f(CW\*(C`strftime\*(C'\fR routine is |
| 26898 |
available to do time formatting. |
| 26899 |
.ie n .IP """HAS_TIME""" 4 |
| 26900 |
.el .IP \f(CWHAS_TIME\fR 4 |
| 26901 |
.IX Xref "HAS_TIME" |
| 26902 |
.IX Item "HAS_TIME" |
| 26903 |
This symbol, if defined, indicates that the \f(CWtime()\fR routine exists. |
| 26904 |
.ie n .IP """HAS_TIMEGM""" 4 |
| 26905 |
.el .IP \f(CWHAS_TIMEGM\fR 4 |
| 26906 |
.IX Xref "HAS_TIMEGM" |
| 26907 |
.IX Item "HAS_TIMEGM" |
| 26908 |
This symbol, if defined, indicates that the \f(CW\*(C`timegm\*(C'\fR routine is |
| 26909 |
available to do the opposite of gmtime () |
| 26910 |
.ie n .IP """HAS_TIMES""" 4 |
| 26911 |
.el .IP \f(CWHAS_TIMES\fR 4 |
| 26912 |
.IX Xref "HAS_TIMES" |
| 26913 |
.IX Item "HAS_TIMES" |
| 26914 |
This symbol, if defined, indicates that the \f(CWtimes()\fR routine exists. |
| 26915 |
Note that this became obsolete on some systems (\f(CW\*(C`SUNOS\*(C'\fR), which now |
| 26916 |
use \f(CWgetrusage()\fR. It may be necessary to include \fIsys/times.h\fR. |
| 26917 |
.ie n .IP """HAS_TM_TM_GMTOFF""" 4 |
| 26918 |
.el .IP \f(CWHAS_TM_TM_GMTOFF\fR 4 |
| 26919 |
.IX Xref "HAS_TM_TM_GMTOFF" |
| 26920 |
.IX Item "HAS_TM_TM_GMTOFF" |
| 26921 |
This symbol, if defined, indicates to the C program that |
| 26922 |
the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_gmtoff\*(C'\fR field. |
| 26923 |
.ie n .IP """HAS_TM_TM_ZONE""" 4 |
| 26924 |
.el .IP \f(CWHAS_TM_TM_ZONE\fR 4 |
| 26925 |
.IX Xref "HAS_TM_TM_ZONE" |
| 26926 |
.IX Item "HAS_TM_TM_ZONE" |
| 26927 |
This symbol, if defined, indicates to the C program that |
| 26928 |
the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_zone\*(C'\fR field. |
| 26929 |
.ie n .IP """HAS_TZNAME""" 4 |
| 26930 |
.el .IP \f(CWHAS_TZNAME\fR 4 |
| 26931 |
.IX Xref "HAS_TZNAME" |
| 26932 |
.IX Item "HAS_TZNAME" |
| 26933 |
This symbol, if defined, indicates that the \f(CW\*(C`tzname[]\*(C'\fR array is |
| 26934 |
available to access timezone names. |
| 26935 |
.ie n .IP """HAS_USLEEP""" 4 |
| 26936 |
.el .IP \f(CWHAS_USLEEP\fR 4 |
| 26937 |
.IX Xref "HAS_USLEEP" |
| 26938 |
.IX Item "HAS_USLEEP" |
| 26939 |
This symbol, if defined, indicates that the \f(CW\*(C`usleep\*(C'\fR routine is |
| 26940 |
available to let the process sleep on a sub-second accuracy. |
| 26941 |
.ie n .IP """HAS_USLEEP_PROTO""" 4 |
| 26942 |
.el .IP \f(CWHAS_USLEEP_PROTO\fR 4 |
| 26943 |
.IX Xref "HAS_USLEEP_PROTO" |
| 26944 |
.IX Item "HAS_USLEEP_PROTO" |
| 26945 |
This symbol, if defined, indicates that the system provides |
| 26946 |
a prototype for the \f(CWusleep()\fR function. Otherwise, it is up |
| 26947 |
to the program to supply one. A good guess is |
| 26948 |
.Sp |
| 26949 |
.Vb 1 |
| 26950 |
\& extern int usleep(useconds_t); |
| 26951 |
.Ve |
| 26952 |
.ie n .IP """I_TIME""" 4 |
| 26953 |
.el .IP \f(CWI_TIME\fR 4 |
| 26954 |
.IX Xref "I_TIME" |
| 26955 |
.IX Item "I_TIME" |
| 26956 |
This symbol is always defined, and indicates to the C program that |
| 26957 |
it should include \fItime.h\fR. |
| 26958 |
.RS 4 |
| 26959 |
.Sp |
| 26960 |
.Vb 3 |
| 26961 |
\& #ifdef I_TIME |
| 26962 |
\& #include <time.h> |
| 26963 |
\& #endif |
| 26964 |
.Ve |
| 26965 |
.RE |
| 26966 |
.RS 4 |
| 26967 |
.RE |
| 26968 |
.ie n .IP """I_UTIME""" 4 |
| 26969 |
.el .IP \f(CWI_UTIME\fR 4 |
| 26970 |
.IX Xref "I_UTIME" |
| 26971 |
.IX Item "I_UTIME" |
| 26972 |
This symbol, if defined, indicates to the C program that it should |
| 26973 |
include \fIutime.h\fR. |
| 26974 |
.RS 4 |
| 26975 |
.Sp |
| 26976 |
.Vb 3 |
| 26977 |
\& #ifdef I_UTIME |
| 26978 |
\& #include <utime.h> |
| 26979 |
\& #endif |
| 26980 |
.Ve |
| 26981 |
.RE |
| 26982 |
.RS 4 |
| 26983 |
.RE |
| 26984 |
.ie n .IP """LOCALTIME_MAX""" 4 |
| 26985 |
.el .IP \f(CWLOCALTIME_MAX\fR 4 |
| 26986 |
.IX Xref "LOCALTIME_MAX" |
| 26987 |
.IX Item "LOCALTIME_MAX" |
| 26988 |
This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that |
| 26989 |
the system function localtime () accepts, and defaults to 0 |
| 26990 |
.ie n .IP """LOCALTIME_MIN""" 4 |
| 26991 |
.el .IP \f(CWLOCALTIME_MIN\fR 4 |
| 26992 |
.IX Xref "LOCALTIME_MIN" |
| 26993 |
.IX Item "LOCALTIME_MIN" |
| 26994 |
This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that |
| 26995 |
the system function localtime () accepts, and defaults to 0 |
| 26996 |
.ie n .IP """LOCALTIME_R_NEEDS_TZSET""" 4 |
| 26997 |
.el .IP \f(CWLOCALTIME_R_NEEDS_TZSET\fR 4 |
| 26998 |
.IX Xref "LOCALTIME_R_NEEDS_TZSET" |
| 26999 |
.IX Item "LOCALTIME_R_NEEDS_TZSET" |
| 27000 |
Many libc's \f(CW\*(C`localtime_r\*(C'\fR implementations do not call tzset, |
| 27001 |
making them differ from \f(CWlocaltime()\fR, and making timezone |
| 27002 |
changes using $\f(CW\*(C`ENV\*(C'\fR{TZ} without explicitly calling tzset |
| 27003 |
impossible. This symbol makes us call tzset before \f(CW\*(C`localtime_r\*(C'\fR |
| 27004 |
.ie n .IP """LOCALTIME_R_PROTO""" 4 |
| 27005 |
.el .IP \f(CWLOCALTIME_R_PROTO\fR 4 |
| 27006 |
.IX Xref "LOCALTIME_R_PROTO" |
| 27007 |
.IX Item "LOCALTIME_R_PROTO" |
| 27008 |
This symbol encodes the prototype of \f(CW\*(C`localtime_r\*(C'\fR. |
| 27009 |
It is zero if \f(CW\*(C`d_localtime_r\*(C'\fR is undef, and one of the |
| 27010 |
\&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_localtime_r\*(C'\fR |
| 27011 |
is defined. |
| 27012 |
.ie n .IP """L_R_TZSET""" 4 |
| 27013 |
.el .IP \f(CWL_R_TZSET\fR 4 |
| 27014 |
.IX Xref "L_R_TZSET" |
| 27015 |
.IX Item "L_R_TZSET" |
| 27016 |
If \f(CWlocaltime_r()\fR needs tzset, it is defined in this define |
| 27017 |
.ie n .IP """mini_mktime""" 4 |
| 27018 |
.el .IP \f(CWmini_mktime\fR 4 |
| 27019 |
.IX Xref "mini_mktime" |
| 27020 |
.IX Item "mini_mktime" |
| 27021 |
normalise \f(CW\*(C`struct\ tm\*(C'\fR values without the \fBlocaltime()\fR semantics (and |
| 27022 |
overhead) of \fBmktime()\fR. |
| 27023 |
.RS 4 |
| 27024 |
.Sp |
| 27025 |
.Vb 1 |
| 27026 |
\& void mini_mktime(struct tm *ptm) |
| 27027 |
.Ve |
| 27028 |
.RE |
| 27029 |
.RS 4 |
| 27030 |
.RE |
| 27031 |
.ie n .IP """sv_strftime_tm""" 4 |
| 27032 |
.el .IP \f(CWsv_strftime_tm\fR 4 |
| 27033 |
.IX Item "sv_strftime_tm" |
| 27034 |
.PD 0 |
| 27035 |
.ie n .IP """my_strftime""" 4 |
| 27036 |
.el .IP \f(CWmy_strftime\fR 4 |
| 27037 |
.IX Xref "sv_strftime_tm my_strftime" |
| 27038 |
.IX Item "my_strftime" |
| 27039 |
.PD |
| 27040 |
These implement the libc \fBstrftime()\fR. |
| 27041 |
.Sp |
| 27042 |
On failure, they return NULL, and set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`EINVAL\*(C'\fR. |
| 27043 |
.Sp |
| 27044 |
\&\f(CW\*(C`sv_strftime_tm\*(C'\fR is preferred, as it transparently handles the UTF\-8ness of |
| 27045 |
the current locale, the input \f(CW\*(C`fmt\*(C'\fR, and the returned result. Only if the |
| 27046 |
current \f(CW\*(C`LC_TIME\*(C'\fR locale is a UTF\-8 one (and \f(CW\*(C`use\ bytes\*(C'\fR is not in effect) |
| 27047 |
will the result be marked as UTF\-8. |
| 27048 |
.Sp |
| 27049 |
\&\f(CW\*(C`sv_strftime_tm\*(C'\fR takes a pointer to a filled-in \f(CW\*(C`struct\ tm\*(C'\fR parameter. It |
| 27050 |
ignores the values of the \f(CW\*(C`wday\*(C'\fR and \f(CW\*(C`yday\*(C'\fR fields in it. The other fields |
| 27051 |
give enough information to accurately calculate these values, and are used for |
| 27052 |
that purpose. |
| 27053 |
.Sp |
| 27054 |
The caller assumes ownership of the returned SV with a reference count of 1. |
| 27055 |
.Sp |
| 27056 |
\&\f(CW\*(C`my_strftime\*(C'\fR is kept for backwards compatibility. Knowing if its result |
| 27057 |
should be considered UTF\-8 or not requires significant extra logic. |
| 27058 |
.Sp |
| 27059 |
The return value is a pointer to the formatted result (which MUST be arranged |
| 27060 |
to be FREED BY THE CALLER). This allows this function to increase the buffer |
| 27061 |
size as needed, so that the caller doesn't have to worry about that, unlike |
| 27062 |
libc \f(CWstrftime()\fR. |
| 27063 |
.Sp |
| 27064 |
The \f(CW\*(C`wday\*(C'\fR, \f(CW\*(C`yday\*(C'\fR, and \f(CW\*(C`isdst\*(C'\fR parameters are ignored by \f(CW\*(C`my_strftime\*(C'\fR. |
| 27065 |
Daylight savings time is never considered to exist, and the values returned for |
| 27066 |
the other two fields (if \f(CW\*(C`fmt\*(C'\fR even calls for them) are calculated from the |
| 27067 |
other parameters, without need for referencing these. |
| 27068 |
.Sp |
| 27069 |
Note that both functions are always executed in the underlying |
| 27070 |
\&\f(CW\*(C`LC_TIME\*(C'\fR locale of the program, giving results based on that locale. |
| 27071 |
.RS 4 |
| 27072 |
.Sp |
| 27073 |
.Vb 4 |
| 27074 |
\& SV * sv_strftime_tm(SV *fmt, const struct tm *mytm) |
| 27075 |
\& char * my_strftime (const char *fmt, int sec, int min, |
| 27076 |
\& int hour, int mday, int mon, int year, |
| 27077 |
\& int wday, int yday, int isdst) |
| 27078 |
.Ve |
| 27079 |
.RE |
| 27080 |
.RS 4 |
| 27081 |
.RE |
| 27082 |
.SH "Typedef names" |
| 27083 |
.IX Header "Typedef names" |
| 27084 |
.ie n .IP """DB_Hash_t""" 4 |
| 27085 |
.el .IP \f(CWDB_Hash_t\fR 4 |
| 27086 |
.IX Xref "DB_Hash_t" |
| 27087 |
.IX Item "DB_Hash_t" |
| 27088 |
This symbol contains the type of the prefix structure element |
| 27089 |
in the \fIdb.h\fR header file. In older versions of DB, it was |
| 27090 |
int, while in newer ones it is \f(CW\*(C`size_t\*(C'\fR. |
| 27091 |
.ie n .IP """DB_Prefix_t""" 4 |
| 27092 |
.el .IP \f(CWDB_Prefix_t\fR 4 |
| 27093 |
.IX Xref "DB_Prefix_t" |
| 27094 |
.IX Item "DB_Prefix_t" |
| 27095 |
This symbol contains the type of the prefix structure element |
| 27096 |
in the \fIdb.h\fR header file. In older versions of DB, it was |
| 27097 |
int, while in newer ones it is \f(CW\*(C`u_int32_t\*(C'\fR. |
| 27098 |
.ie n .IP """Direntry_t""" 4 |
| 27099 |
.el .IP \f(CWDirentry_t\fR 4 |
| 27100 |
.IX Xref "Direntry_t" |
| 27101 |
.IX Item "Direntry_t" |
| 27102 |
This symbol is set to '\f(CW\*(C`struct direct\*(C'\fR' or '\f(CW\*(C`struct dirent\*(C'\fR' depending on |
| 27103 |
whether dirent is available or not. You should use this pseudo type to |
| 27104 |
portably declare your directory entries. |
| 27105 |
.ie n .IP """Fpos_t""" 4 |
| 27106 |
.el .IP \f(CWFpos_t\fR 4 |
| 27107 |
.IX Xref "Fpos_t" |
| 27108 |
.IX Item "Fpos_t" |
| 27109 |
This symbol holds the type used to declare file positions in libc. |
| 27110 |
It can be \f(CW\*(C`fpos_t\*(C'\fR, long, uint, etc... It may be necessary to include |
| 27111 |
\&\fIsys/types.h\fR to get any typedef'ed information. |
| 27112 |
.ie n .IP """Free_t""" 4 |
| 27113 |
.el .IP \f(CWFree_t\fR 4 |
| 27114 |
.IX Xref "Free_t" |
| 27115 |
.IX Item "Free_t" |
| 27116 |
This variable contains the return type of \f(CWfree()\fR. It is usually |
| 27117 |
void, but occasionally int. |
| 27118 |
.ie n .IP """Gid_t""" 4 |
| 27119 |
.el .IP \f(CWGid_t\fR 4 |
| 27120 |
.IX Xref "Gid_t" |
| 27121 |
.IX Item "Gid_t" |
| 27122 |
This symbol holds the return type of \f(CWgetgid()\fR and the type of |
| 27123 |
argument to \f(CWsetrgid()\fR and related functions. Typically, |
| 27124 |
it is the type of group ids in the kernel. It can be int, ushort, |
| 27125 |
\&\f(CW\*(C`gid_t\*(C'\fR, etc... It may be necessary to include \fIsys/types.h\fR to get |
| 27126 |
any typedef'ed information. |
| 27127 |
.ie n .IP """Gid_t_f""" 4 |
| 27128 |
.el .IP \f(CWGid_t_f\fR 4 |
| 27129 |
.IX Xref "Gid_t_f" |
| 27130 |
.IX Item "Gid_t_f" |
| 27131 |
This symbol defines the format string used for printing a \f(CW\*(C`Gid_t\*(C'\fR. |
| 27132 |
.ie n .IP """Gid_t_sign""" 4 |
| 27133 |
.el .IP \f(CWGid_t_sign\fR 4 |
| 27134 |
.IX Xref "Gid_t_sign" |
| 27135 |
.IX Item "Gid_t_sign" |
| 27136 |
This symbol holds the signedness of a \f(CW\*(C`Gid_t\*(C'\fR. |
| 27137 |
1 for unsigned, \-1 for signed. |
| 27138 |
.ie n .IP """Gid_t_size""" 4 |
| 27139 |
.el .IP \f(CWGid_t_size\fR 4 |
| 27140 |
.IX Xref "Gid_t_size" |
| 27141 |
.IX Item "Gid_t_size" |
| 27142 |
This symbol holds the size of a \f(CW\*(C`Gid_t\*(C'\fR in bytes. |
| 27143 |
.ie n .IP """Groups_t""" 4 |
| 27144 |
.el .IP \f(CWGroups_t\fR 4 |
| 27145 |
.IX Xref "Groups_t" |
| 27146 |
.IX Item "Groups_t" |
| 27147 |
This symbol holds the type used for the second argument to |
| 27148 |
\&\f(CWgetgroups()\fR and \f(CWsetgroups()\fR. Usually, this is the same as |
| 27149 |
gidtype (\f(CW\*(C`gid_t\*(C'\fR) , but sometimes it isn't. |
| 27150 |
It can be int, ushort, \f(CW\*(C`gid_t\*(C'\fR, etc... |
| 27151 |
It may be necessary to include \fIsys/types.h\fR to get any |
| 27152 |
typedef'ed information. This is only required if you have |
| 27153 |
\&\f(CWgetgroups()\fR or \f(CWsetgroups()\fR.. |
| 27154 |
.ie n .IP """Malloc_t""" 4 |
| 27155 |
.el .IP \f(CWMalloc_t\fR 4 |
| 27156 |
.IX Xref "Malloc_t" |
| 27157 |
.IX Item "Malloc_t" |
| 27158 |
This symbol is the type of pointer returned by malloc and realloc. |
| 27159 |
.ie n .IP """Mmap_t""" 4 |
| 27160 |
.el .IP \f(CWMmap_t\fR 4 |
| 27161 |
.IX Xref "Mmap_t" |
| 27162 |
.IX Item "Mmap_t" |
| 27163 |
This symbol holds the return type of the \f(CWmmap()\fR system call |
| 27164 |
(and simultaneously the type of the first argument). |
| 27165 |
Usually set to 'void *' or '\f(CW\*(C`caddr_t\*(C'\fR'. |
| 27166 |
.ie n .IP """Mode_t""" 4 |
| 27167 |
.el .IP \f(CWMode_t\fR 4 |
| 27168 |
.IX Xref "Mode_t" |
| 27169 |
.IX Item "Mode_t" |
| 27170 |
This symbol holds the type used to declare file modes |
| 27171 |
for systems calls. It is usually \f(CW\*(C`mode_t\*(C'\fR, but may be |
| 27172 |
int or unsigned short. It may be necessary to include \fIsys/types.h\fR |
| 27173 |
to get any typedef'ed information. |
| 27174 |
.ie n .IP """Netdb_hlen_t""" 4 |
| 27175 |
.el .IP \f(CWNetdb_hlen_t\fR 4 |
| 27176 |
.IX Xref "Netdb_hlen_t" |
| 27177 |
.IX Item "Netdb_hlen_t" |
| 27178 |
This symbol holds the type used for the 2nd argument |
| 27179 |
to \f(CWgethostbyaddr()\fR. |
| 27180 |
.ie n .IP """Netdb_host_t""" 4 |
| 27181 |
.el .IP \f(CWNetdb_host_t\fR 4 |
| 27182 |
.IX Xref "Netdb_host_t" |
| 27183 |
.IX Item "Netdb_host_t" |
| 27184 |
This symbol holds the type used for the 1st argument |
| 27185 |
to \f(CWgethostbyaddr()\fR. |
| 27186 |
.ie n .IP """Netdb_name_t""" 4 |
| 27187 |
.el .IP \f(CWNetdb_name_t\fR 4 |
| 27188 |
.IX Xref "Netdb_name_t" |
| 27189 |
.IX Item "Netdb_name_t" |
| 27190 |
This symbol holds the type used for the argument to |
| 27191 |
\&\f(CWgethostbyname()\fR. |
| 27192 |
.ie n .IP """Netdb_net_t""" 4 |
| 27193 |
.el .IP \f(CWNetdb_net_t\fR 4 |
| 27194 |
.IX Xref "Netdb_net_t" |
| 27195 |
.IX Item "Netdb_net_t" |
| 27196 |
This symbol holds the type used for the 1st argument to |
| 27197 |
\&\f(CWgetnetbyaddr()\fR. |
| 27198 |
.ie n .IP """Off_t""" 4 |
| 27199 |
.el .IP \f(CWOff_t\fR 4 |
| 27200 |
.IX Xref "Off_t" |
| 27201 |
.IX Item "Off_t" |
| 27202 |
This symbol holds the type used to declare offsets in the kernel. |
| 27203 |
It can be int, long, \f(CW\*(C`off_t\*(C'\fR, etc... It may be necessary to include |
| 27204 |
\&\fIsys/types.h\fR to get any typedef'ed information. |
| 27205 |
.ie n .IP """Off_t_size""" 4 |
| 27206 |
.el .IP \f(CWOff_t_size\fR 4 |
| 27207 |
.IX Xref "Off_t_size" |
| 27208 |
.IX Item "Off_t_size" |
| 27209 |
This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR. |
| 27210 |
.ie n .IP """Pid_t""" 4 |
| 27211 |
.el .IP \f(CWPid_t\fR 4 |
| 27212 |
.IX Xref "Pid_t" |
| 27213 |
.IX Item "Pid_t" |
| 27214 |
This symbol holds the type used to declare process ids in the kernel. |
| 27215 |
It can be int, uint, \f(CW\*(C`pid_t\*(C'\fR, etc... It may be necessary to include |
| 27216 |
\&\fIsys/types.h\fR to get any typedef'ed information. |
| 27217 |
.ie n .IP """Rand_seed_t""" 4 |
| 27218 |
.el .IP \f(CWRand_seed_t\fR 4 |
| 27219 |
.IX Xref "Rand_seed_t" |
| 27220 |
.IX Item "Rand_seed_t" |
| 27221 |
This symbol defines the type of the argument of the |
| 27222 |
random seed function. |
| 27223 |
.ie n .IP """Select_fd_set_t""" 4 |
| 27224 |
.el .IP \f(CWSelect_fd_set_t\fR 4 |
| 27225 |
.IX Xref "Select_fd_set_t" |
| 27226 |
.IX Item "Select_fd_set_t" |
| 27227 |
This symbol holds the type used for the 2nd, 3rd, and 4th |
| 27228 |
arguments to select. Usually, this is '\f(CW\*(C`fd_set\*(C'\fR *', if \f(CW\*(C`HAS_FD_SET\*(C'\fR |
| 27229 |
is defined, and 'int *' otherwise. This is only useful if you |
| 27230 |
have \f(CWselect()\fR, of course. |
| 27231 |
.ie n .IP """Shmat_t""" 4 |
| 27232 |
.el .IP \f(CWShmat_t\fR 4 |
| 27233 |
.IX Xref "Shmat_t" |
| 27234 |
.IX Item "Shmat_t" |
| 27235 |
This symbol holds the return type of the \f(CWshmat()\fR system call. |
| 27236 |
Usually set to 'void *' or 'char *'. |
| 27237 |
.ie n .IP """Signal_t""" 4 |
| 27238 |
.el .IP \f(CWSignal_t\fR 4 |
| 27239 |
.IX Xref "Signal_t" |
| 27240 |
.IX Item "Signal_t" |
| 27241 |
This symbol's value is either "void" or "int", corresponding to the |
| 27242 |
appropriate return type of a signal handler. Thus, you can declare |
| 27243 |
a signal handler using "\f(CW\*(C`Signal_t\*(C'\fR (*handler)()", and define the |
| 27244 |
handler using "\f(CW\*(C`Signal_t\*(C'\fR \f(CWhandler(sig)\fR". |
| 27245 |
.ie n .IP """Size_t""" 4 |
| 27246 |
.el .IP \f(CWSize_t\fR 4 |
| 27247 |
.IX Xref "Size_t" |
| 27248 |
.IX Item "Size_t" |
| 27249 |
This symbol holds the type used to declare length parameters |
| 27250 |
for string functions. It is usually \f(CW\*(C`size_t\*(C'\fR, but may be |
| 27251 |
unsigned long, int, etc. It may be necessary to include |
| 27252 |
\&\fIsys/types.h\fR to get any typedef'ed information. |
| 27253 |
.ie n .IP """Size_t_size""" 4 |
| 27254 |
.el .IP \f(CWSize_t_size\fR 4 |
| 27255 |
.IX Xref "Size_t_size" |
| 27256 |
.IX Item "Size_t_size" |
| 27257 |
This symbol holds the size of a \f(CW\*(C`Size_t\*(C'\fR in bytes. |
| 27258 |
.ie n .IP """Sock_size_t""" 4 |
| 27259 |
.el .IP \f(CWSock_size_t\fR 4 |
| 27260 |
.IX Xref "Sock_size_t" |
| 27261 |
.IX Item "Sock_size_t" |
| 27262 |
This symbol holds the type used for the size argument of |
| 27263 |
various socket calls (just the base type, not the pointer-to). |
| 27264 |
.ie n .IP """SSize_t""" 4 |
| 27265 |
.el .IP \f(CWSSize_t\fR 4 |
| 27266 |
.IX Xref "SSize_t" |
| 27267 |
.IX Item "SSize_t" |
| 27268 |
This symbol holds the type used by functions that return |
| 27269 |
a count of bytes or an error condition. It must be a signed type. |
| 27270 |
It is usually \f(CW\*(C`ssize_t\*(C'\fR, but may be long or int, etc. |
| 27271 |
It may be necessary to include \fIsys/types.h\fR or \fIunistd.h\fR |
| 27272 |
to get any typedef'ed information. |
| 27273 |
We will pick a type such that \f(CWsizeof(SSize_t)\fR == \f(CWsizeof(Size_t)\fR. |
| 27274 |
.ie n .IP """Time_t""" 4 |
| 27275 |
.el .IP \f(CWTime_t\fR 4 |
| 27276 |
.IX Xref "Time_t" |
| 27277 |
.IX Item "Time_t" |
| 27278 |
This symbol holds the type returned by \f(CWtime()\fR. It can be long, |
| 27279 |
or \f(CW\*(C`time_t\*(C'\fR on \f(CW\*(C`BSD\*(C'\fR sites (in which case \fIsys/types.h\fR should be |
| 27280 |
included). |
| 27281 |
.ie n .IP """Uid_t""" 4 |
| 27282 |
.el .IP \f(CWUid_t\fR 4 |
| 27283 |
.IX Xref "Uid_t" |
| 27284 |
.IX Item "Uid_t" |
| 27285 |
This symbol holds the type used to declare user ids in the kernel. |
| 27286 |
It can be int, ushort, \f(CW\*(C`uid_t\*(C'\fR, etc... It may be necessary to include |
| 27287 |
\&\fIsys/types.h\fR to get any typedef'ed information. |
| 27288 |
.ie n .IP """Uid_t_f""" 4 |
| 27289 |
.el .IP \f(CWUid_t_f\fR 4 |
| 27290 |
.IX Xref "Uid_t_f" |
| 27291 |
.IX Item "Uid_t_f" |
| 27292 |
This symbol defines the format string used for printing a \f(CW\*(C`Uid_t\*(C'\fR. |
| 27293 |
.ie n .IP """Uid_t_sign""" 4 |
| 27294 |
.el .IP \f(CWUid_t_sign\fR 4 |
| 27295 |
.IX Xref "Uid_t_sign" |
| 27296 |
.IX Item "Uid_t_sign" |
| 27297 |
This symbol holds the signedness of a \f(CW\*(C`Uid_t\*(C'\fR. |
| 27298 |
1 for unsigned, \-1 for signed. |
| 27299 |
.ie n .IP """Uid_t_size""" 4 |
| 27300 |
.el .IP \f(CWUid_t_size\fR 4 |
| 27301 |
.IX Xref "Uid_t_size" |
| 27302 |
.IX Item "Uid_t_size" |
| 27303 |
This symbol holds the size of a \f(CW\*(C`Uid_t\*(C'\fR in bytes. |
| 27304 |
.SH "Unicode Support" |
| 27305 |
.IX Xref "UNICODE_DISALLOW_ABOVE_31_BIT UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE UNICODE_DISALLOW_ILLEGAL_INTERCHANGE UNICODE_DISALLOW_NONCHAR UNICODE_DISALLOW_PERL_EXTENDED UNICODE_DISALLOW_SUPER UNICODE_DISALLOW_SURROGATE UNICODE_WARN_ABOVE_31_BIT UNICODE_WARN_ILLEGAL_C9_INTERCHANGE UNICODE_WARN_ILLEGAL_INTERCHANGE UNICODE_WARN_NONCHAR UNICODE_WARN_PERL_EXTENDED UNICODE_WARN_SUPER UNICODE_WARN_SURROGATE UNI_DISPLAY_BACKSLASH UNI_DISPLAY_BACKSPACE UNI_DISPLAY_ISPRINT UNI_DISPLAY_QQ UNI_DISPLAY_REGEX UTF8_CHECK_ONLY UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE UTF8_DISALLOW_ILLEGAL_INTERCHANGE UTF8_DISALLOW_NONCHAR UTF8_DISALLOW_PERL_EXTENDED UTF8_DISALLOW_SUPER UTF8_DISALLOW_SURROGATE UTF8_GOT_CONTINUATION UTF8_GOT_EMPTY UTF8_GOT_LONG UTF8_GOT_NONCHAR UTF8_GOT_NON_CONTINUATION UTF8_GOT_OVERFLOW UTF8_GOT_PERL_EXTENDED UTF8_GOT_SHORT UTF8_GOT_SUPER UTF8_GOT_SURROGATE UTF8_WARN_ILLEGAL_C9_INTERCHANGE UTF8_WARN_ILLEGAL_INTERCHANGE UTF8_WARN_NONCHAR UTF8_WARN_PERL_EXTENDED UTF8_WARN_SUPER UTF8_WARN_SURROGATE" |
| 27306 |
.IX Header "Unicode Support" |
| 27307 |
"Unicode Support" in perlguts has an introduction to this API. |
| 27308 |
.PP |
| 27309 |
See also \f(CW"Character classification"\fR, |
| 27310 |
\&\f(CW"Character case changing"\fR, |
| 27311 |
and \f(CW"String Handling"\fR. |
| 27312 |
Various functions outside this section also work specially with |
| 27313 |
Unicode. Search for the string "utf8" in this document. |
| 27314 |
.ie n .IP """BOM_UTF8""" 4 |
| 27315 |
.el .IP \f(CWBOM_UTF8\fR 4 |
| 27316 |
.IX Xref "BOM_UTF8" |
| 27317 |
.IX Item "BOM_UTF8" |
| 27318 |
This is a macro that evaluates to a string constant of the UTF\-8 bytes that |
| 27319 |
define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl |
| 27320 |
is compiled on. This allows code to use a mnemonic for this character that |
| 27321 |
works on both ASCII and EBCDIC platforms. |
| 27322 |
\&\f(CW\*(C`sizeof(BOM_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in |
| 27323 |
bytes. |
| 27324 |
.ie n .IP """bytes_cmp_utf8""" 4 |
| 27325 |
.el .IP \f(CWbytes_cmp_utf8\fR 4 |
| 27326 |
.IX Xref "bytes_cmp_utf8" |
| 27327 |
.IX Item "bytes_cmp_utf8" |
| 27328 |
Compares the sequence of characters (stored as octets) in \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`blen\*(C'\fR with the |
| 27329 |
sequence of characters (stored as UTF\-8) |
| 27330 |
in \f(CW\*(C`u\*(C'\fR, \f(CW\*(C`ulen\*(C'\fR. Returns 0 if they are |
| 27331 |
equal, \-1 or \-2 if the first string is less than the second string, +1 or +2 |
| 27332 |
if the first string is greater than the second string. |
| 27333 |
.Sp |
| 27334 |
\&\-1 or +1 is returned if the shorter string was identical to the start of the |
| 27335 |
longer string. \-2 or +2 is returned if |
| 27336 |
there was a difference between characters |
| 27337 |
within the strings. |
| 27338 |
.RS 4 |
| 27339 |
.Sp |
| 27340 |
.Vb 2 |
| 27341 |
\& int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u, |
| 27342 |
\& STRLEN ulen) |
| 27343 |
.Ve |
| 27344 |
.RE |
| 27345 |
.RS 4 |
| 27346 |
.RE |
| 27347 |
.ie n .IP """bytes_from_utf8""" 4 |
| 27348 |
.el .IP \f(CWbytes_from_utf8\fR 4 |
| 27349 |
.IX Xref "bytes_from_utf8" |
| 27350 |
.IX Item "bytes_from_utf8" |
| 27351 |
NOTE: \f(CW\*(C`bytes_from_utf8\*(C'\fR is \fBexperimental\fR and may change or be |
| 27352 |
removed without notice. |
| 27353 |
.Sp |
| 27354 |
Converts a potentially UTF\-8 encoded string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR into native |
| 27355 |
byte encoding. On input, the boolean \f(CW*is_utf8p\fR gives whether or not \f(CW\*(C`s\*(C'\fR is |
| 27356 |
actually encoded in UTF\-8. |
| 27357 |
.Sp |
| 27358 |
Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-destructive of |
| 27359 |
the input string. |
| 27360 |
.Sp |
| 27361 |
Do nothing if \f(CW*is_utf8p\fR is 0, or if there are code points in the string |
| 27362 |
not expressible in native byte encoding. In these cases, \f(CW*is_utf8p\fR and |
| 27363 |
\&\f(CW*lenp\fR are unchanged, and the return value is the original \f(CW\*(C`s\*(C'\fR. |
| 27364 |
.Sp |
| 27365 |
Otherwise, \f(CW*is_utf8p\fR is set to 0, and the return value is a pointer to a |
| 27366 |
newly created string containing a downgraded copy of \f(CW\*(C`s\*(C'\fR, and whose length is |
| 27367 |
returned in \f(CW*lenp\fR, updated. The new string is \f(CW\*(C`NUL\*(C'\fR\-terminated. The |
| 27368 |
caller is responsible for arranging for the memory used by this string to get |
| 27369 |
freed. |
| 27370 |
.Sp |
| 27371 |
Upon successful return, the number of variants in the string can be computed by |
| 27372 |
having saved the value of \f(CW*lenp\fR before the call, and subtracting the |
| 27373 |
after-call value of \f(CW*lenp\fR from it. |
| 27374 |
.RS 4 |
| 27375 |
.Sp |
| 27376 |
.Vb 1 |
| 27377 |
\& U8 * bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p) |
| 27378 |
.Ve |
| 27379 |
.RE |
| 27380 |
.RS 4 |
| 27381 |
.RE |
| 27382 |
.ie n .IP """bytes_to_utf8""" 4 |
| 27383 |
.el .IP \f(CWbytes_to_utf8\fR 4 |
| 27384 |
.IX Xref "bytes_to_utf8" |
| 27385 |
.IX Item "bytes_to_utf8" |
| 27386 |
NOTE: \f(CW\*(C`bytes_to_utf8\*(C'\fR is \fBexperimental\fR and may change or be |
| 27387 |
removed without notice. |
| 27388 |
.Sp |
| 27389 |
Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR bytes from the native encoding into |
| 27390 |
UTF\-8. |
| 27391 |
Returns a pointer to the newly-created string, and sets \f(CW*lenp\fR to |
| 27392 |
reflect the new length in bytes. The caller is responsible for arranging for |
| 27393 |
the memory used by this string to get freed. |
| 27394 |
.Sp |
| 27395 |
Upon successful return, the number of variants in the string can be computed by |
| 27396 |
having saved the value of \f(CW*lenp\fR before the call, and subtracting it from the |
| 27397 |
after-call value of \f(CW*lenp\fR. |
| 27398 |
.Sp |
| 27399 |
A \f(CW\*(C`NUL\*(C'\fR character will be written after the end of the string. |
| 27400 |
.Sp |
| 27401 |
If you want to convert to UTF\-8 from encodings other than |
| 27402 |
the native (Latin1 or EBCDIC), |
| 27403 |
see "sv_recode_to_utf8"(). |
| 27404 |
.RS 4 |
| 27405 |
.Sp |
| 27406 |
.Vb 1 |
| 27407 |
\& U8 * bytes_to_utf8(const U8 *s, STRLEN *lenp) |
| 27408 |
.Ve |
| 27409 |
.RE |
| 27410 |
.RS 4 |
| 27411 |
.RE |
| 27412 |
.ie n .IP """DO_UTF8""" 4 |
| 27413 |
.el .IP \f(CWDO_UTF8\fR 4 |
| 27414 |
.IX Xref "DO_UTF8" |
| 27415 |
.IX Item "DO_UTF8" |
| 27416 |
Returns a bool giving whether or not the PV in \f(CW\*(C`sv\*(C'\fR is to be treated as being |
| 27417 |
encoded in UTF\-8. |
| 27418 |
.Sp |
| 27419 |
You should use this \fIafter\fR a call to \f(CWSvPV()\fR or one of its variants, in |
| 27420 |
case any call to string overloading updates the internal UTF\-8 encoding flag. |
| 27421 |
.RS 4 |
| 27422 |
.Sp |
| 27423 |
.Vb 1 |
| 27424 |
\& bool DO_UTF8(SV* sv) |
| 27425 |
.Ve |
| 27426 |
.RE |
| 27427 |
.RS 4 |
| 27428 |
.RE |
| 27429 |
.ie n .IP """foldEQ_utf8""" 4 |
| 27430 |
.el .IP \f(CWfoldEQ_utf8\fR 4 |
| 27431 |
.IX Xref "foldEQ_utf8" |
| 27432 |
.IX Item "foldEQ_utf8" |
| 27433 |
Returns true if the leading portions of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR (either or |
| 27434 |
both of which may be in UTF\-8) are the same case-insensitively; false |
| 27435 |
otherwise. How far into the strings to compare is determined by other input |
| 27436 |
parameters. |
| 27437 |
.Sp |
| 27438 |
If \f(CW\*(C`u1\*(C'\fR is true, the string \f(CW\*(C`s1\*(C'\fR is assumed to be in UTF\-8\-encoded Unicode; |
| 27439 |
otherwise it is assumed to be in native 8\-bit encoding. Correspondingly for |
| 27440 |
\&\f(CW\*(C`u2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR. |
| 27441 |
.Sp |
| 27442 |
If the byte length \f(CW\*(C`l1\*(C'\fR is non-zero, it says how far into \f(CW\*(C`s1\*(C'\fR to check for |
| 27443 |
fold equality. In other words, \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR will be used as a goal to reach. |
| 27444 |
The scan will not be considered to be a match unless the goal is reached, and |
| 27445 |
scanning won't continue past that goal. Correspondingly for \f(CW\*(C`l2\*(C'\fR with respect |
| 27446 |
to \f(CW\*(C`s2\*(C'\fR. |
| 27447 |
.Sp |
| 27448 |
If \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR and the pointer it points to is not \f(CW\*(C`NULL\*(C'\fR, that |
| 27449 |
pointer is considered an end pointer to the position 1 byte past the maximum |
| 27450 |
point in \f(CW\*(C`s1\*(C'\fR beyond which scanning will not continue under any circumstances. |
| 27451 |
(This routine assumes that UTF\-8 encoded input strings are not malformed; |
| 27452 |
malformed input can cause it to read past \f(CW\*(C`pe1\*(C'\fR). This means that if both |
| 27453 |
\&\f(CW\*(C`l1\*(C'\fR and \f(CW\*(C`pe1\*(C'\fR are specified, and \f(CW\*(C`pe1\*(C'\fR is less than \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR, the match |
| 27454 |
will never be successful because it can never |
| 27455 |
get as far as its goal (and in fact is asserted against). Correspondingly for |
| 27456 |
\&\f(CW\*(C`pe2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR. |
| 27457 |
.Sp |
| 27458 |
At least one of \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR must have a goal (at least one of \f(CW\*(C`l1\*(C'\fR and |
| 27459 |
\&\f(CW\*(C`l2\*(C'\fR must be non-zero), and if both do, both have to be |
| 27460 |
reached for a successful match. Also, if the fold of a character is multiple |
| 27461 |
characters, all of them must be matched (see tr21 reference below for |
| 27462 |
\&'folding'). |
| 27463 |
.Sp |
| 27464 |
Upon a successful match, if \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR, |
| 27465 |
it will be set to point to the beginning of the \fInext\fR character of \f(CW\*(C`s1\*(C'\fR |
| 27466 |
beyond what was matched. Correspondingly for \f(CW\*(C`pe2\*(C'\fR and \f(CW\*(C`s2\*(C'\fR. |
| 27467 |
.Sp |
| 27468 |
For case-insensitiveness, the "casefolding" of Unicode is used |
| 27469 |
instead of upper/lowercasing both the characters, see |
| 27470 |
<https://www.unicode.org/reports/tr21/> (Case Mappings). |
| 27471 |
.RS 4 |
| 27472 |
.Sp |
| 27473 |
.Vb 2 |
| 27474 |
\& I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1, |
| 27475 |
\& const char *s2, char **pe2, UV l2, bool u2) |
| 27476 |
.Ve |
| 27477 |
.RE |
| 27478 |
.RS 4 |
| 27479 |
.RE |
| 27480 |
.ie n .IP """is_ascii_string""" 4 |
| 27481 |
.el .IP \f(CWis_ascii_string\fR 4 |
| 27482 |
.IX Xref "is_ascii_string" |
| 27483 |
.IX Item "is_ascii_string" |
| 27484 |
This is a misleadingly-named synonym for "is_utf8_invariant_string". |
| 27485 |
On ASCII-ish platforms, the name isn't misleading: the ASCII-range characters |
| 27486 |
are exactly the UTF\-8 invariants. But EBCDIC machines have more invariants |
| 27487 |
than just the ASCII characters, so \f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred. |
| 27488 |
.RS 4 |
| 27489 |
.Sp |
| 27490 |
.Vb 1 |
| 27491 |
\& bool is_ascii_string(const U8 * const s, STRLEN len) |
| 27492 |
.Ve |
| 27493 |
.RE |
| 27494 |
.RS 4 |
| 27495 |
.RE |
| 27496 |
.ie n .IP """isC9_STRICT_UTF8_CHAR""" 4 |
| 27497 |
.el .IP \f(CWisC9_STRICT_UTF8_CHAR\fR 4 |
| 27498 |
.IX Xref "isC9_STRICT_UTF8_CHAR" |
| 27499 |
.IX Item "isC9_STRICT_UTF8_CHAR" |
| 27500 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 27501 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some |
| 27502 |
Unicode non-surrogate code point; otherwise it evaluates to 0. If non-zero, |
| 27503 |
the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's |
| 27504 |
representation. Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to |
| 27505 |
form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined. |
| 27506 |
.Sp |
| 27507 |
The largest acceptable code point is the Unicode maximum 0x10FFFF. This |
| 27508 |
differs from \f(CW"isSTRICT_UTF8_CHAR"\fR only in that it accepts non-character |
| 27509 |
code points. This corresponds to |
| 27510 |
Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>. |
| 27511 |
which said that non-character code points are merely discouraged rather than |
| 27512 |
completely forbidden in open interchange. See |
| 27513 |
"Noncharacter code points" in perlunicode. |
| 27514 |
.Sp |
| 27515 |
Use \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8; and |
| 27516 |
\&\f(CW"isUTF8_CHAR_flags"\fR for a more customized definition. |
| 27517 |
.Sp |
| 27518 |
Use \f(CW"is_c9strict_utf8_string"\fR, \f(CW"is_c9strict_utf8_string_loc"\fR, and |
| 27519 |
\&\f(CW"is_c9strict_utf8_string_loclen"\fR to check entire strings. |
| 27520 |
.RS 4 |
| 27521 |
.Sp |
| 27522 |
.Vb 2 |
| 27523 |
\& Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0, |
| 27524 |
\& const U8 * const e) |
| 27525 |
.Ve |
| 27526 |
.RE |
| 27527 |
.RS 4 |
| 27528 |
.RE |
| 27529 |
.ie n .IP """is_c9strict_utf8_string""" 4 |
| 27530 |
.el .IP \f(CWis_c9strict_utf8_string\fR 4 |
| 27531 |
.IX Xref "is_c9strict_utf8_string" |
| 27532 |
.IX Item "is_c9strict_utf8_string" |
| 27533 |
Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid |
| 27534 |
UTF\-8\-encoded string that conforms to |
| 27535 |
Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>; |
| 27536 |
otherwise it returns FALSE. If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using |
| 27537 |
\&\f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded |
| 27538 |
\&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte). Note that all |
| 27539 |
characters being ASCII constitute 'a valid UTF\-8 string'. |
| 27540 |
.Sp |
| 27541 |
This function returns FALSE for strings containing any code points above the |
| 27542 |
Unicode max of 0x10FFFF or surrogate code points, but accepts non-character |
| 27543 |
code points per |
| 27544 |
Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>. |
| 27545 |
.Sp |
| 27546 |
See also |
| 27547 |
\&\f(CW"is_utf8_invariant_string"\fR, |
| 27548 |
\&\f(CW"is_utf8_invariant_string_loc"\fR, |
| 27549 |
\&\f(CW"is_utf8_string"\fR, |
| 27550 |
\&\f(CW"is_utf8_string_flags"\fR, |
| 27551 |
\&\f(CW"is_utf8_string_loc"\fR, |
| 27552 |
\&\f(CW"is_utf8_string_loc_flags"\fR, |
| 27553 |
\&\f(CW"is_utf8_string_loclen"\fR, |
| 27554 |
\&\f(CW"is_utf8_string_loclen_flags"\fR, |
| 27555 |
\&\f(CW"is_utf8_fixed_width_buf_flags"\fR, |
| 27556 |
\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR, |
| 27557 |
\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR, |
| 27558 |
\&\f(CW"is_strict_utf8_string"\fR, |
| 27559 |
\&\f(CW"is_strict_utf8_string_loc"\fR, |
| 27560 |
\&\f(CW"is_strict_utf8_string_loclen"\fR, |
| 27561 |
\&\f(CW"is_c9strict_utf8_string_loc"\fR, |
| 27562 |
and |
| 27563 |
\&\f(CW"is_c9strict_utf8_string_loclen"\fR. |
| 27564 |
.RS 4 |
| 27565 |
.Sp |
| 27566 |
.Vb 1 |
| 27567 |
\& bool is_c9strict_utf8_string(const U8 *s, STRLEN len) |
| 27568 |
.Ve |
| 27569 |
.RE |
| 27570 |
.RS 4 |
| 27571 |
.RE |
| 27572 |
.ie n .IP """is_c9strict_utf8_string_loc""" 4 |
| 27573 |
.el .IP \f(CWis_c9strict_utf8_string_loc\fR 4 |
| 27574 |
.IX Xref "is_c9strict_utf8_string_loc" |
| 27575 |
.IX Item "is_c9strict_utf8_string_loc" |
| 27576 |
Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in |
| 27577 |
the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 27578 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer. |
| 27579 |
.Sp |
| 27580 |
See also \f(CW"is_c9strict_utf8_string_loclen"\fR. |
| 27581 |
.RS 4 |
| 27582 |
.Sp |
| 27583 |
.Vb 2 |
| 27584 |
\& bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len, |
| 27585 |
\& const U8 **ep) |
| 27586 |
.Ve |
| 27587 |
.RE |
| 27588 |
.RS 4 |
| 27589 |
.RE |
| 27590 |
.ie n .IP """is_c9strict_utf8_string_loclen""" 4 |
| 27591 |
.el .IP \f(CWis_c9strict_utf8_string_loclen\fR 4 |
| 27592 |
.IX Xref "is_c9strict_utf8_string_loclen" |
| 27593 |
.IX Item "is_c9strict_utf8_string_loclen" |
| 27594 |
Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in |
| 27595 |
the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 27596 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 encoded |
| 27597 |
characters in the \f(CW\*(C`el\*(C'\fR pointer. |
| 27598 |
.Sp |
| 27599 |
See also \f(CW"is_c9strict_utf8_string_loc"\fR. |
| 27600 |
.RS 4 |
| 27601 |
.Sp |
| 27602 |
.Vb 2 |
| 27603 |
\& bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len, |
| 27604 |
\& const U8 **ep, STRLEN *el) |
| 27605 |
.Ve |
| 27606 |
.RE |
| 27607 |
.RS 4 |
| 27608 |
.RE |
| 27609 |
.ie n .IP """is_invariant_string""" 4 |
| 27610 |
.el .IP \f(CWis_invariant_string\fR 4 |
| 27611 |
.IX Xref "is_invariant_string" |
| 27612 |
.IX Item "is_invariant_string" |
| 27613 |
This is a somewhat misleadingly-named synonym for "is_utf8_invariant_string". |
| 27614 |
\&\f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred, as it indicates under what conditions |
| 27615 |
the string is invariant. |
| 27616 |
.RS 4 |
| 27617 |
.Sp |
| 27618 |
.Vb 1 |
| 27619 |
\& bool is_invariant_string(const U8 * const s, STRLEN len) |
| 27620 |
.Ve |
| 27621 |
.RE |
| 27622 |
.RS 4 |
| 27623 |
.RE |
| 27624 |
.ie n .IP """isSTRICT_UTF8_CHAR""" 4 |
| 27625 |
.el .IP \f(CWisSTRICT_UTF8_CHAR\fR 4 |
| 27626 |
.IX Xref "isSTRICT_UTF8_CHAR" |
| 27627 |
.IX Item "isSTRICT_UTF8_CHAR" |
| 27628 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 27629 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some |
| 27630 |
Unicode code point completely acceptable for open interchange between all |
| 27631 |
applications; otherwise it evaluates to 0. If non-zero, the value gives how |
| 27632 |
many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation. Any |
| 27633 |
bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code |
| 27634 |
point in \f(CW\*(C`s\*(C'\fR, are not examined. |
| 27635 |
.Sp |
| 27636 |
The largest acceptable code point is the Unicode maximum 0x10FFFF, and must not |
| 27637 |
be a surrogate nor a non-character code point. Thus this excludes any code |
| 27638 |
point from Perl's extended UTF\-8. |
| 27639 |
.Sp |
| 27640 |
This is used to efficiently decide if the next few bytes in \f(CW\*(C`s\*(C'\fR is |
| 27641 |
legal Unicode-acceptable UTF\-8 for a single character. |
| 27642 |
.Sp |
| 27643 |
Use \f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum |
| 27644 |
#9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable |
| 27645 |
code points; \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8; |
| 27646 |
and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition. |
| 27647 |
.Sp |
| 27648 |
Use \f(CW"is_strict_utf8_string"\fR, \f(CW"is_strict_utf8_string_loc"\fR, and |
| 27649 |
\&\f(CW"is_strict_utf8_string_loclen"\fR to check entire strings. |
| 27650 |
.RS 4 |
| 27651 |
.Sp |
| 27652 |
.Vb 2 |
| 27653 |
\& Size_t isSTRICT_UTF8_CHAR(const U8 * const s0, |
| 27654 |
\& const U8 * const e) |
| 27655 |
.Ve |
| 27656 |
.RE |
| 27657 |
.RS 4 |
| 27658 |
.RE |
| 27659 |
.ie n .IP """is_strict_utf8_string""" 4 |
| 27660 |
.el .IP \f(CWis_strict_utf8_string\fR 4 |
| 27661 |
.IX Xref "is_strict_utf8_string" |
| 27662 |
.IX Item "is_strict_utf8_string" |
| 27663 |
Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid |
| 27664 |
UTF\-8\-encoded string that is fully interchangeable by any application using |
| 27665 |
Unicode rules; otherwise it returns FALSE. If \f(CW\*(C`len\*(C'\fR is 0, it will be |
| 27666 |
calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR |
| 27667 |
can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR |
| 27668 |
byte). Note that all characters being ASCII constitute 'a valid UTF\-8 string'. |
| 27669 |
.Sp |
| 27670 |
This function returns FALSE for strings containing any |
| 27671 |
code points above the Unicode max of 0x10FFFF, surrogate code points, or |
| 27672 |
non-character code points. |
| 27673 |
.Sp |
| 27674 |
See also |
| 27675 |
\&\f(CW"is_utf8_invariant_string"\fR, |
| 27676 |
\&\f(CW"is_utf8_invariant_string_loc"\fR, |
| 27677 |
\&\f(CW"is_utf8_string"\fR, |
| 27678 |
\&\f(CW"is_utf8_string_flags"\fR, |
| 27679 |
\&\f(CW"is_utf8_string_loc"\fR, |
| 27680 |
\&\f(CW"is_utf8_string_loc_flags"\fR, |
| 27681 |
\&\f(CW"is_utf8_string_loclen"\fR, |
| 27682 |
\&\f(CW"is_utf8_string_loclen_flags"\fR, |
| 27683 |
\&\f(CW"is_utf8_fixed_width_buf_flags"\fR, |
| 27684 |
\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR, |
| 27685 |
\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR, |
| 27686 |
\&\f(CW"is_strict_utf8_string_loc"\fR, |
| 27687 |
\&\f(CW"is_strict_utf8_string_loclen"\fR, |
| 27688 |
\&\f(CW"is_c9strict_utf8_string"\fR, |
| 27689 |
\&\f(CW"is_c9strict_utf8_string_loc"\fR, |
| 27690 |
and |
| 27691 |
\&\f(CW"is_c9strict_utf8_string_loclen"\fR. |
| 27692 |
.RS 4 |
| 27693 |
.Sp |
| 27694 |
.Vb 1 |
| 27695 |
\& bool is_strict_utf8_string(const U8 *s, STRLEN len) |
| 27696 |
.Ve |
| 27697 |
.RE |
| 27698 |
.RS 4 |
| 27699 |
.RE |
| 27700 |
.ie n .IP """is_strict_utf8_string_loc""" 4 |
| 27701 |
.el .IP \f(CWis_strict_utf8_string_loc\fR 4 |
| 27702 |
.IX Xref "is_strict_utf8_string_loc" |
| 27703 |
.IX Item "is_strict_utf8_string_loc" |
| 27704 |
Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the |
| 27705 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 27706 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer. |
| 27707 |
.Sp |
| 27708 |
See also \f(CW"is_strict_utf8_string_loclen"\fR. |
| 27709 |
.RS 4 |
| 27710 |
.Sp |
| 27711 |
.Vb 2 |
| 27712 |
\& bool is_strict_utf8_string_loc(const U8 *s, STRLEN len, |
| 27713 |
\& const U8 **ep) |
| 27714 |
.Ve |
| 27715 |
.RE |
| 27716 |
.RS 4 |
| 27717 |
.RE |
| 27718 |
.ie n .IP """is_strict_utf8_string_loclen""" 4 |
| 27719 |
.el .IP \f(CWis_strict_utf8_string_loclen\fR 4 |
| 27720 |
.IX Xref "is_strict_utf8_string_loclen" |
| 27721 |
.IX Item "is_strict_utf8_string_loclen" |
| 27722 |
Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the |
| 27723 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 27724 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 |
| 27725 |
encoded characters in the \f(CW\*(C`el\*(C'\fR pointer. |
| 27726 |
.Sp |
| 27727 |
See also \f(CW"is_strict_utf8_string_loc"\fR. |
| 27728 |
.RS 4 |
| 27729 |
.Sp |
| 27730 |
.Vb 2 |
| 27731 |
\& bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len, |
| 27732 |
\& const U8 **ep, STRLEN *el) |
| 27733 |
.Ve |
| 27734 |
.RE |
| 27735 |
.RS 4 |
| 27736 |
.RE |
| 27737 |
.ie n .IP """isUTF8_CHAR""" 4 |
| 27738 |
.el .IP \f(CWisUTF8_CHAR\fR 4 |
| 27739 |
.IX Xref "isUTF8_CHAR" |
| 27740 |
.IX Item "isUTF8_CHAR" |
| 27741 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 27742 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl, |
| 27743 |
that represents some code point; otherwise it evaluates to 0. If non-zero, the |
| 27744 |
value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's |
| 27745 |
representation. Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to |
| 27746 |
form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined. |
| 27747 |
.Sp |
| 27748 |
The code point can be any that will fit in an IV on this machine, using Perl's |
| 27749 |
extension to official UTF\-8 to represent those higher than the Unicode maximum |
| 27750 |
of 0x10FFFF. That means that this macro is used to efficiently decide if the |
| 27751 |
next few bytes in \f(CW\*(C`s\*(C'\fR is legal UTF\-8 for a single character. |
| 27752 |
.Sp |
| 27753 |
Use \f(CW"isSTRICT_UTF8_CHAR"\fR to restrict the acceptable code points to those |
| 27754 |
defined by Unicode to be fully interchangeable across applications; |
| 27755 |
\&\f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum |
| 27756 |
#9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable |
| 27757 |
code points; and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition. |
| 27758 |
.Sp |
| 27759 |
Use \f(CW"is_utf8_string"\fR, \f(CW"is_utf8_string_loc"\fR, and |
| 27760 |
\&\f(CW"is_utf8_string_loclen"\fR to check entire strings. |
| 27761 |
.Sp |
| 27762 |
Note also that a UTF\-8 "invariant" character (i.e. ASCII on non-EBCDIC |
| 27763 |
machines) is a valid UTF\-8 character. |
| 27764 |
.RS 4 |
| 27765 |
.Sp |
| 27766 |
.Vb 1 |
| 27767 |
\& Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e) |
| 27768 |
.Ve |
| 27769 |
.RE |
| 27770 |
.RS 4 |
| 27771 |
.RE |
| 27772 |
.ie n .IP """is_utf8_char_buf""" 4 |
| 27773 |
.el .IP \f(CWis_utf8_char_buf\fR 4 |
| 27774 |
.IX Xref "is_utf8_char_buf" |
| 27775 |
.IX Item "is_utf8_char_buf" |
| 27776 |
This is identical to the macro "isUTF8_CHAR" in perlapi. |
| 27777 |
.RS 4 |
| 27778 |
.Sp |
| 27779 |
.Vb 1 |
| 27780 |
\& STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end) |
| 27781 |
.Ve |
| 27782 |
.RE |
| 27783 |
.RS 4 |
| 27784 |
.RE |
| 27785 |
.ie n .IP """isUTF8_CHAR_flags""" 4 |
| 27786 |
.el .IP \f(CWisUTF8_CHAR_flags\fR 4 |
| 27787 |
.IX Xref "isUTF8_CHAR_flags" |
| 27788 |
.IX Item "isUTF8_CHAR_flags" |
| 27789 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 27790 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl, |
| 27791 |
that represents some code point, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR; |
| 27792 |
otherwise it evaluates to 0. If non-zero, the value gives how many bytes |
| 27793 |
starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation. Any bytes remaining |
| 27794 |
before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code point in \f(CW\*(C`s\*(C'\fR, |
| 27795 |
are not examined. |
| 27796 |
.Sp |
| 27797 |
If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"isUTF8_CHAR"\fR; |
| 27798 |
if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results |
| 27799 |
as \f(CW"isSTRICT_UTF8_CHAR"\fR; |
| 27800 |
and if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives |
| 27801 |
the same results as \f(CW"isC9_STRICT_UTF8_CHAR"\fR. |
| 27802 |
Otherwise \f(CW\*(C`flags\*(C'\fR may be any combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags |
| 27803 |
understood by \f(CW"utf8n_to_uvchr"\fR, with the same meanings. |
| 27804 |
.Sp |
| 27805 |
The three alternative macros are for the most commonly needed validations; they |
| 27806 |
are likely to run somewhat faster than this more general one, as they can be |
| 27807 |
inlined into your code. |
| 27808 |
.Sp |
| 27809 |
Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and |
| 27810 |
"is_utf8_string_loclen_flags" to check entire strings. |
| 27811 |
.RS 4 |
| 27812 |
.Sp |
| 27813 |
.Vb 2 |
| 27814 |
\& Size_t isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e, |
| 27815 |
\& const U32 flags) |
| 27816 |
.Ve |
| 27817 |
.RE |
| 27818 |
.RS 4 |
| 27819 |
.RE |
| 27820 |
.ie n .IP """is_utf8_fixed_width_buf_flags""" 4 |
| 27821 |
.el .IP \f(CWis_utf8_fixed_width_buf_flags\fR 4 |
| 27822 |
.IX Xref "is_utf8_fixed_width_buf_flags" |
| 27823 |
.IX Item "is_utf8_fixed_width_buf_flags" |
| 27824 |
Returns TRUE if the fixed-width buffer starting at \f(CW\*(C`s\*(C'\fR with length \f(CW\*(C`len\*(C'\fR |
| 27825 |
is entirely valid UTF\-8, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR; |
| 27826 |
otherwise it returns FALSE. |
| 27827 |
.Sp |
| 27828 |
If \f(CW\*(C`flags\*(C'\fR is 0, any well-formed UTF\-8, as extended by Perl, is accepted |
| 27829 |
without restriction. If the final few bytes of the buffer do not form a |
| 27830 |
complete code point, this will return TRUE anyway, provided that |
| 27831 |
\&\f(CW"is_utf8_valid_partial_char_flags"\fR returns TRUE for them. |
| 27832 |
.Sp |
| 27833 |
If \f(CW\*(C`flags\*(C'\fR in non-zero, it can be any combination of the |
| 27834 |
\&\f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR, and with the |
| 27835 |
same meanings. |
| 27836 |
.Sp |
| 27837 |
This function differs from \f(CW"is_utf8_string_flags"\fR only in that the latter |
| 27838 |
returns FALSE if the final few bytes of the string don't form a complete code |
| 27839 |
point. |
| 27840 |
.RS 4 |
| 27841 |
.Sp |
| 27842 |
.Vb 2 |
| 27843 |
\& bool is_utf8_fixed_width_buf_flags(const U8 * const s, |
| 27844 |
\& STRLEN len, const U32 flags) |
| 27845 |
.Ve |
| 27846 |
.RE |
| 27847 |
.RS 4 |
| 27848 |
.RE |
| 27849 |
.ie n .IP """is_utf8_fixed_width_buf_loc_flags""" 4 |
| 27850 |
.el .IP \f(CWis_utf8_fixed_width_buf_loc_flags\fR 4 |
| 27851 |
.IX Xref "is_utf8_fixed_width_buf_loc_flags" |
| 27852 |
.IX Item "is_utf8_fixed_width_buf_loc_flags" |
| 27853 |
Like \f(CW"is_utf8_fixed_width_buf_flags"\fR but stores the location of the |
| 27854 |
failure in the \f(CW\*(C`ep\*(C'\fR pointer. If the function returns TRUE, \f(CW*ep\fR will point |
| 27855 |
to the beginning of any partial character at the end of the buffer; if there is |
| 27856 |
no partial character \f(CW*ep\fR will contain \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR. |
| 27857 |
.Sp |
| 27858 |
See also \f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR. |
| 27859 |
.RS 4 |
| 27860 |
.Sp |
| 27861 |
.Vb 3 |
| 27862 |
\& bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s, |
| 27863 |
\& STRLEN len, const U8 **ep, |
| 27864 |
\& const U32 flags) |
| 27865 |
.Ve |
| 27866 |
.RE |
| 27867 |
.RS 4 |
| 27868 |
.RE |
| 27869 |
.ie n .IP """is_utf8_fixed_width_buf_loclen_flags""" 4 |
| 27870 |
.el .IP \f(CWis_utf8_fixed_width_buf_loclen_flags\fR 4 |
| 27871 |
.IX Xref "is_utf8_fixed_width_buf_loclen_flags" |
| 27872 |
.IX Item "is_utf8_fixed_width_buf_loclen_flags" |
| 27873 |
Like \f(CW"is_utf8_fixed_width_buf_loc_flags"\fR but stores the number of |
| 27874 |
complete, valid characters found in the \f(CW\*(C`el\*(C'\fR pointer. |
| 27875 |
.RS 4 |
| 27876 |
.Sp |
| 27877 |
.Vb 5 |
| 27878 |
\& bool is_utf8_fixed_width_buf_loclen_flags(const U8 * const s, |
| 27879 |
\& STRLEN len, |
| 27880 |
\& const U8 **ep, |
| 27881 |
\& STRLEN *el, |
| 27882 |
\& const U32 flags) |
| 27883 |
.Ve |
| 27884 |
.RE |
| 27885 |
.RS 4 |
| 27886 |
.RE |
| 27887 |
.ie n .IP """is_utf8_invariant_string""" 4 |
| 27888 |
.el .IP \f(CWis_utf8_invariant_string\fR 4 |
| 27889 |
.IX Xref "is_utf8_invariant_string" |
| 27890 |
.IX Item "is_utf8_invariant_string" |
| 27891 |
Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR are the same |
| 27892 |
regardless of the UTF\-8 encoding of the string (or UTF-EBCDIC encoding on |
| 27893 |
EBCDIC machines); otherwise it returns FALSE. That is, it returns TRUE if they |
| 27894 |
are UTF\-8 invariant. On ASCII-ish machines, all the ASCII characters and only |
| 27895 |
the ASCII characters fit this definition. On EBCDIC machines, the ASCII-range |
| 27896 |
characters are invariant, but so also are the C1 controls. |
| 27897 |
.Sp |
| 27898 |
If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using \f(CWstrlen(s)\fR, (which means if you |
| 27899 |
use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to |
| 27900 |
have a terminating \f(CW\*(C`NUL\*(C'\fR byte). |
| 27901 |
.Sp |
| 27902 |
See also |
| 27903 |
\&\f(CW"is_utf8_string"\fR, |
| 27904 |
\&\f(CW"is_utf8_string_flags"\fR, |
| 27905 |
\&\f(CW"is_utf8_string_loc"\fR, |
| 27906 |
\&\f(CW"is_utf8_string_loc_flags"\fR, |
| 27907 |
\&\f(CW"is_utf8_string_loclen"\fR, |
| 27908 |
\&\f(CW"is_utf8_string_loclen_flags"\fR, |
| 27909 |
\&\f(CW"is_utf8_fixed_width_buf_flags"\fR, |
| 27910 |
\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR, |
| 27911 |
\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR, |
| 27912 |
\&\f(CW"is_strict_utf8_string"\fR, |
| 27913 |
\&\f(CW"is_strict_utf8_string_loc"\fR, |
| 27914 |
\&\f(CW"is_strict_utf8_string_loclen"\fR, |
| 27915 |
\&\f(CW"is_c9strict_utf8_string"\fR, |
| 27916 |
\&\f(CW"is_c9strict_utf8_string_loc"\fR, |
| 27917 |
and |
| 27918 |
\&\f(CW"is_c9strict_utf8_string_loclen"\fR. |
| 27919 |
.RS 4 |
| 27920 |
.Sp |
| 27921 |
.Vb 1 |
| 27922 |
\& bool is_utf8_invariant_string(const U8 * const s, STRLEN len) |
| 27923 |
.Ve |
| 27924 |
.RE |
| 27925 |
.RS 4 |
| 27926 |
.RE |
| 27927 |
.ie n .IP """is_utf8_invariant_string_loc""" 4 |
| 27928 |
.el .IP \f(CWis_utf8_invariant_string_loc\fR 4 |
| 27929 |
.IX Xref "is_utf8_invariant_string_loc" |
| 27930 |
.IX Item "is_utf8_invariant_string_loc" |
| 27931 |
Like \f(CW"is_utf8_invariant_string"\fR but upon failure, stores the location of |
| 27932 |
the first UTF\-8 variant character in the \f(CW\*(C`ep\*(C'\fR pointer; if all characters are |
| 27933 |
UTF\-8 invariant, this function does not change the contents of \f(CW*ep\fR. |
| 27934 |
.RS 4 |
| 27935 |
.Sp |
| 27936 |
.Vb 2 |
| 27937 |
\& bool is_utf8_invariant_string_loc(const U8 * const s, STRLEN len, |
| 27938 |
\& const U8 **ep) |
| 27939 |
.Ve |
| 27940 |
.RE |
| 27941 |
.RS 4 |
| 27942 |
.RE |
| 27943 |
.ie n .IP """is_utf8_string""" 4 |
| 27944 |
.el .IP \f(CWis_utf8_string\fR 4 |
| 27945 |
.IX Xref "is_utf8_string" |
| 27946 |
.IX Item "is_utf8_string" |
| 27947 |
Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid |
| 27948 |
Perl\-extended\-UTF\-8 string; returns FALSE otherwise. If \f(CW\*(C`len\*(C'\fR is 0, it will |
| 27949 |
be calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR |
| 27950 |
can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR |
| 27951 |
byte). Note that all characters being ASCII constitute 'a valid UTF\-8 string'. |
| 27952 |
.Sp |
| 27953 |
This function considers Perl's extended UTF\-8 to be valid. That means that |
| 27954 |
code points above Unicode, surrogates, and non-character code points are |
| 27955 |
considered valid by this function. Use \f(CW"is_strict_utf8_string"\fR, |
| 27956 |
\&\f(CW"is_c9strict_utf8_string"\fR, or \f(CW"is_utf8_string_flags"\fR to restrict what |
| 27957 |
code points are considered valid. |
| 27958 |
.Sp |
| 27959 |
See also |
| 27960 |
\&\f(CW"is_utf8_invariant_string"\fR, |
| 27961 |
\&\f(CW"is_utf8_invariant_string_loc"\fR, |
| 27962 |
\&\f(CW"is_utf8_string_loc"\fR, |
| 27963 |
\&\f(CW"is_utf8_string_loclen"\fR, |
| 27964 |
\&\f(CW"is_utf8_fixed_width_buf_flags"\fR, |
| 27965 |
\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR, |
| 27966 |
\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR, |
| 27967 |
.RS 4 |
| 27968 |
.Sp |
| 27969 |
.Vb 1 |
| 27970 |
\& bool is_utf8_string(const U8 *s, STRLEN len) |
| 27971 |
.Ve |
| 27972 |
.RE |
| 27973 |
.RS 4 |
| 27974 |
.RE |
| 27975 |
.ie n .IP """is_utf8_string_flags""" 4 |
| 27976 |
.el .IP \f(CWis_utf8_string_flags\fR 4 |
| 27977 |
.IX Xref "is_utf8_string_flags" |
| 27978 |
.IX Item "is_utf8_string_flags" |
| 27979 |
Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid |
| 27980 |
UTF\-8 string, subject to the restrictions imposed by \f(CW\*(C`flags\*(C'\fR; |
| 27981 |
returns FALSE otherwise. If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated |
| 27982 |
using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have |
| 27983 |
embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte). Note |
| 27984 |
that all characters being ASCII constitute 'a valid UTF\-8 string'. |
| 27985 |
.Sp |
| 27986 |
If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"is_utf8_string"\fR; if |
| 27987 |
\&\f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results |
| 27988 |
as \f(CW"is_strict_utf8_string"\fR; and if \f(CW\*(C`flags\*(C'\fR is |
| 27989 |
\&\f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives the same results as |
| 27990 |
\&\f(CW"is_c9strict_utf8_string"\fR. Otherwise \f(CW\*(C`flags\*(C'\fR may be any |
| 27991 |
combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags understood by |
| 27992 |
\&\f(CW"utf8n_to_uvchr"\fR, with the same meanings. |
| 27993 |
.Sp |
| 27994 |
See also |
| 27995 |
\&\f(CW"is_utf8_invariant_string"\fR, |
| 27996 |
\&\f(CW"is_utf8_invariant_string_loc"\fR, |
| 27997 |
\&\f(CW"is_utf8_string"\fR, |
| 27998 |
\&\f(CW"is_utf8_string_loc"\fR, |
| 27999 |
\&\f(CW"is_utf8_string_loc_flags"\fR, |
| 28000 |
\&\f(CW"is_utf8_string_loclen"\fR, |
| 28001 |
\&\f(CW"is_utf8_string_loclen_flags"\fR, |
| 28002 |
\&\f(CW"is_utf8_fixed_width_buf_flags"\fR, |
| 28003 |
\&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR, |
| 28004 |
\&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR, |
| 28005 |
\&\f(CW"is_strict_utf8_string"\fR, |
| 28006 |
\&\f(CW"is_strict_utf8_string_loc"\fR, |
| 28007 |
\&\f(CW"is_strict_utf8_string_loclen"\fR, |
| 28008 |
\&\f(CW"is_c9strict_utf8_string"\fR, |
| 28009 |
\&\f(CW"is_c9strict_utf8_string_loc"\fR, |
| 28010 |
and |
| 28011 |
\&\f(CW"is_c9strict_utf8_string_loclen"\fR. |
| 28012 |
.RS 4 |
| 28013 |
.Sp |
| 28014 |
.Vb 2 |
| 28015 |
\& bool is_utf8_string_flags(const U8 *s, STRLEN len, |
| 28016 |
\& const U32 flags) |
| 28017 |
.Ve |
| 28018 |
.RE |
| 28019 |
.RS 4 |
| 28020 |
.RE |
| 28021 |
.ie n .IP """is_utf8_string_loc""" 4 |
| 28022 |
.el .IP \f(CWis_utf8_string_loc\fR 4 |
| 28023 |
.IX Xref "is_utf8_string_loc" |
| 28024 |
.IX Item "is_utf8_string_loc" |
| 28025 |
Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the |
| 28026 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 28027 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer. |
| 28028 |
.Sp |
| 28029 |
See also \f(CW"is_utf8_string_loclen"\fR. |
| 28030 |
.RS 4 |
| 28031 |
.Sp |
| 28032 |
.Vb 2 |
| 28033 |
\& bool is_utf8_string_loc(const U8 *s, const STRLEN len, |
| 28034 |
\& const U8 **ep) |
| 28035 |
.Ve |
| 28036 |
.RE |
| 28037 |
.RS 4 |
| 28038 |
.RE |
| 28039 |
.ie n .IP """is_utf8_string_loc_flags""" 4 |
| 28040 |
.el .IP \f(CWis_utf8_string_loc_flags\fR 4 |
| 28041 |
.IX Xref "is_utf8_string_loc_flags" |
| 28042 |
.IX Item "is_utf8_string_loc_flags" |
| 28043 |
Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the |
| 28044 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 28045 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer. |
| 28046 |
.Sp |
| 28047 |
See also \f(CW"is_utf8_string_loclen_flags"\fR. |
| 28048 |
.RS 4 |
| 28049 |
.Sp |
| 28050 |
.Vb 2 |
| 28051 |
\& bool is_utf8_string_loc_flags(const U8 *s, STRLEN len, |
| 28052 |
\& const U8 **ep, const U32 flags) |
| 28053 |
.Ve |
| 28054 |
.RE |
| 28055 |
.RS 4 |
| 28056 |
.RE |
| 28057 |
.ie n .IP """is_utf8_string_loclen""" 4 |
| 28058 |
.el .IP \f(CWis_utf8_string_loclen\fR 4 |
| 28059 |
.IX Xref "is_utf8_string_loclen" |
| 28060 |
.IX Item "is_utf8_string_loclen" |
| 28061 |
Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the |
| 28062 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 28063 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 |
| 28064 |
encoded characters in the \f(CW\*(C`el\*(C'\fR pointer. |
| 28065 |
.Sp |
| 28066 |
See also \f(CW"is_utf8_string_loc"\fR. |
| 28067 |
.RS 4 |
| 28068 |
.Sp |
| 28069 |
.Vb 2 |
| 28070 |
\& bool is_utf8_string_loclen(const U8 *s, STRLEN len, |
| 28071 |
\& const U8 **ep, STRLEN *el) |
| 28072 |
.Ve |
| 28073 |
.RE |
| 28074 |
.RS 4 |
| 28075 |
.RE |
| 28076 |
.ie n .IP """is_utf8_string_loclen_flags""" 4 |
| 28077 |
.el .IP \f(CWis_utf8_string_loclen_flags\fR 4 |
| 28078 |
.IX Xref "is_utf8_string_loclen_flags" |
| 28079 |
.IX Item "is_utf8_string_loclen_flags" |
| 28080 |
Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the |
| 28081 |
case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of |
| 28082 |
"utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 |
| 28083 |
encoded characters in the \f(CW\*(C`el\*(C'\fR pointer. |
| 28084 |
.Sp |
| 28085 |
See also \f(CW"is_utf8_string_loc_flags"\fR. |
| 28086 |
.RS 4 |
| 28087 |
.Sp |
| 28088 |
.Vb 3 |
| 28089 |
\& bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len, |
| 28090 |
\& const U8 **ep, STRLEN *el, |
| 28091 |
\& const U32 flags) |
| 28092 |
.Ve |
| 28093 |
.RE |
| 28094 |
.RS 4 |
| 28095 |
.RE |
| 28096 |
.ie n .IP """is_utf8_valid_partial_char""" 4 |
| 28097 |
.el .IP \f(CWis_utf8_valid_partial_char\fR 4 |
| 28098 |
.IX Xref "is_utf8_valid_partial_char" |
| 28099 |
.IX Item "is_utf8_valid_partial_char" |
| 28100 |
Returns 0 if the sequence of bytes starting at \f(CW\*(C`s\*(C'\fR and looking no further than |
| 28101 |
\&\f(CW\*(C`e\ \-\ 1\*(C'\fR is the UTF\-8 encoding, as extended by Perl, for one or more code |
| 28102 |
points. Otherwise, it returns 1 if there exists at least one non-empty |
| 28103 |
sequence of bytes that when appended to sequence \f(CW\*(C`s\*(C'\fR, starting at position |
| 28104 |
\&\f(CW\*(C`e\*(C'\fR causes the entire sequence to be the well-formed UTF\-8 of some code point; |
| 28105 |
otherwise returns 0. |
| 28106 |
.Sp |
| 28107 |
In other words this returns TRUE if \f(CW\*(C`s\*(C'\fR points to a partial UTF\-8\-encoded code |
| 28108 |
point. |
| 28109 |
.Sp |
| 28110 |
This is useful when a fixed-length buffer is being tested for being well-formed |
| 28111 |
UTF\-8, but the final few bytes in it don't comprise a full character; that is, |
| 28112 |
it is split somewhere in the middle of the final code point's UTF\-8 |
| 28113 |
representation. (Presumably when the buffer is refreshed with the next chunk |
| 28114 |
of data, the new first bytes will complete the partial code point.) This |
| 28115 |
function is used to verify that the final bytes in the current buffer are in |
| 28116 |
fact the legal beginning of some code point, so that if they aren't, the |
| 28117 |
failure can be signalled without having to wait for the next read. |
| 28118 |
.RS 4 |
| 28119 |
.Sp |
| 28120 |
.Vb 2 |
| 28121 |
\& bool is_utf8_valid_partial_char(const U8 * const s0, |
| 28122 |
\& const U8 * const e) |
| 28123 |
.Ve |
| 28124 |
.RE |
| 28125 |
.RS 4 |
| 28126 |
.RE |
| 28127 |
.ie n .IP """is_utf8_valid_partial_char_flags""" 4 |
| 28128 |
.el .IP \f(CWis_utf8_valid_partial_char_flags\fR 4 |
| 28129 |
.IX Xref "is_utf8_valid_partial_char_flags" |
| 28130 |
.IX Item "is_utf8_valid_partial_char_flags" |
| 28131 |
Like \f(CW"is_utf8_valid_partial_char"\fR, it returns a boolean giving whether |
| 28132 |
or not the input is a valid UTF\-8 encoded partial character, but it takes an |
| 28133 |
extra parameter, \f(CW\*(C`flags\*(C'\fR, which can further restrict which code points are |
| 28134 |
considered valid. |
| 28135 |
.Sp |
| 28136 |
If \f(CW\*(C`flags\*(C'\fR is 0, this behaves identically to |
| 28137 |
\&\f(CW"is_utf8_valid_partial_char"\fR. Otherwise \f(CW\*(C`flags\*(C'\fR can be any combination |
| 28138 |
of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR. If |
| 28139 |
there is any sequence of bytes that can complete the input partial character in |
| 28140 |
such a way that a non-prohibited character is formed, the function returns |
| 28141 |
TRUE; otherwise FALSE. Non character code points cannot be determined based on |
| 28142 |
partial character input. But many of the other possible excluded types can be |
| 28143 |
determined from just the first one or two bytes. |
| 28144 |
.RS 4 |
| 28145 |
.Sp |
| 28146 |
.Vb 3 |
| 28147 |
\& bool is_utf8_valid_partial_char_flags(const U8 * const s0, |
| 28148 |
\& const U8 * const e, |
| 28149 |
\& const U32 flags) |
| 28150 |
.Ve |
| 28151 |
.RE |
| 28152 |
.RS 4 |
| 28153 |
.RE |
| 28154 |
.ie n .IP """LATIN1_TO_NATIVE""" 4 |
| 28155 |
.el .IP \f(CWLATIN1_TO_NATIVE\fR 4 |
| 28156 |
.IX Xref "LATIN1_TO_NATIVE" |
| 28157 |
.IX Item "LATIN1_TO_NATIVE" |
| 28158 |
Returns the native equivalent of the input Latin\-1 code point (including ASCII |
| 28159 |
and control characters) given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWLATIN1_TO_NATIVE(66)\fR on |
| 28160 |
EBCDIC platforms returns 194. These each represent the character \f(CW"B"\fR on |
| 28161 |
their respective platforms. On ASCII platforms no conversion is needed, so |
| 28162 |
this macro expands to just its input, adding no time nor space requirements to |
| 28163 |
the implementation. |
| 28164 |
.Sp |
| 28165 |
For conversion of code points potentially larger than will fit in a character, |
| 28166 |
use "UNI_TO_NATIVE". |
| 28167 |
.RS 4 |
| 28168 |
.Sp |
| 28169 |
.Vb 1 |
| 28170 |
\& U8 LATIN1_TO_NATIVE(U8 ch) |
| 28171 |
.Ve |
| 28172 |
.RE |
| 28173 |
.RS 4 |
| 28174 |
.RE |
| 28175 |
.ie n .IP """NATIVE_TO_LATIN1""" 4 |
| 28176 |
.el .IP \f(CWNATIVE_TO_LATIN1\fR 4 |
| 28177 |
.IX Xref "NATIVE_TO_LATIN1" |
| 28178 |
.IX Item "NATIVE_TO_LATIN1" |
| 28179 |
Returns the Latin\-1 (including ASCII and control characters) equivalent of the |
| 28180 |
input native code point given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWNATIVE_TO_LATIN1(193)\fR on |
| 28181 |
EBCDIC platforms returns 65. These each represent the character \f(CW"A"\fR on |
| 28182 |
their respective platforms. On ASCII platforms no conversion is needed, so |
| 28183 |
this macro expands to just its input, adding no time nor space requirements to |
| 28184 |
the implementation. |
| 28185 |
.Sp |
| 28186 |
For conversion of code points potentially larger than will fit in a character, |
| 28187 |
use "NATIVE_TO_UNI". |
| 28188 |
.RS 4 |
| 28189 |
.Sp |
| 28190 |
.Vb 1 |
| 28191 |
\& U8 NATIVE_TO_LATIN1(U8 ch) |
| 28192 |
.Ve |
| 28193 |
.RE |
| 28194 |
.RS 4 |
| 28195 |
.RE |
| 28196 |
.ie n .IP """NATIVE_TO_UNI""" 4 |
| 28197 |
.el .IP \f(CWNATIVE_TO_UNI\fR 4 |
| 28198 |
.IX Xref "NATIVE_TO_UNI" |
| 28199 |
.IX Item "NATIVE_TO_UNI" |
| 28200 |
Returns the Unicode equivalent of the input native code point given by \f(CW\*(C`ch\*(C'\fR. |
| 28201 |
Thus, \f(CWNATIVE_TO_UNI(195)\fR on EBCDIC platforms returns 67. These each |
| 28202 |
represent the character \f(CW"C"\fR on their respective platforms. On ASCII |
| 28203 |
platforms no conversion is needed, so this macro expands to just its input, |
| 28204 |
adding no time nor space requirements to the implementation. |
| 28205 |
.RS 4 |
| 28206 |
.Sp |
| 28207 |
.Vb 1 |
| 28208 |
\& UV NATIVE_TO_UNI(UV ch) |
| 28209 |
.Ve |
| 28210 |
.RE |
| 28211 |
.RS 4 |
| 28212 |
.RE |
| 28213 |
.ie n .IP """pv_uni_display""" 4 |
| 28214 |
.el .IP \f(CWpv_uni_display\fR 4 |
| 28215 |
.IX Xref "pv_uni_display" |
| 28216 |
.IX Item "pv_uni_display" |
| 28217 |
Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the UTF\-8 encoded string |
| 28218 |
\&\f(CW\*(C`spv\*(C'\fR, length \f(CW\*(C`len\*(C'\fR, the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes |
| 28219 |
long (if longer, the rest is truncated and \f(CW"..."\fR will be appended). |
| 28220 |
.Sp |
| 28221 |
The \f(CW\*(C`flags\*(C'\fR argument can have \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR set to display |
| 28222 |
\&\f(CWisPRINT()\fRable characters as themselves, \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR |
| 28223 |
to display the \f(CW\*(C`\e\e[nrfta\e\e]\*(C'\fR as the backslashed versions (like \f(CW"\en"\fR) |
| 28224 |
(\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR is preferred over \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR for \f(CW"\e\e"\fR). |
| 28225 |
\&\f(CW\*(C`UNI_DISPLAY_QQ\*(C'\fR (and its alias \f(CW\*(C`UNI_DISPLAY_REGEX\*(C'\fR) have both |
| 28226 |
\&\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR and \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR turned on. |
| 28227 |
.Sp |
| 28228 |
Additionally, there is now \f(CW\*(C`UNI_DISPLAY_BACKSPACE\*(C'\fR which allows \f(CW\*(C`\eb\*(C'\fR for a |
| 28229 |
backspace, but only when \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR also is set. |
| 28230 |
.Sp |
| 28231 |
The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned. |
| 28232 |
.Sp |
| 28233 |
See also "sv_uni_display". |
| 28234 |
.RS 4 |
| 28235 |
.Sp |
| 28236 |
.Vb 2 |
| 28237 |
\& char * pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, |
| 28238 |
\& STRLEN pvlim, UV flags) |
| 28239 |
.Ve |
| 28240 |
.RE |
| 28241 |
.RS 4 |
| 28242 |
.RE |
| 28243 |
.ie n .IP """REPLACEMENT_CHARACTER_UTF8""" 4 |
| 28244 |
.el .IP \f(CWREPLACEMENT_CHARACTER_UTF8\fR 4 |
| 28245 |
.IX Xref "REPLACEMENT_CHARACTER_UTF8" |
| 28246 |
.IX Item "REPLACEMENT_CHARACTER_UTF8" |
| 28247 |
This is a macro that evaluates to a string constant of the UTF\-8 bytes that |
| 28248 |
define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl |
| 28249 |
is compiled on. This allows code to use a mnemonic for this character that |
| 28250 |
works on both ASCII and EBCDIC platforms. |
| 28251 |
\&\f(CW\*(C`sizeof(REPLACEMENT_CHARACTER_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in |
| 28252 |
bytes. |
| 28253 |
.ie n .IP """sv_cat_decode""" 4 |
| 28254 |
.el .IP \f(CWsv_cat_decode\fR 4 |
| 28255 |
.IX Xref "sv_cat_decode" |
| 28256 |
.IX Item "sv_cat_decode" |
| 28257 |
\&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, the PV of \f(CW\*(C`ssv\*(C'\fR is |
| 28258 |
assumed to be octets in that encoding and decoding the input starts |
| 28259 |
from the position which \f(CW\*(C`(PV\ +\ *offset)\*(C'\fR pointed to. \f(CW\*(C`dsv\*(C'\fR will be |
| 28260 |
concatenated with the decoded UTF\-8 string from \f(CW\*(C`ssv\*(C'\fR. Decoding will terminate |
| 28261 |
when the string \f(CW\*(C`tstr\*(C'\fR appears in decoding output or the input ends on |
| 28262 |
the PV of \f(CW\*(C`ssv\*(C'\fR. The value which \f(CW\*(C`offset\*(C'\fR points will be modified |
| 28263 |
to the last input position on \f(CW\*(C`ssv\*(C'\fR. |
| 28264 |
.Sp |
| 28265 |
Returns TRUE if the terminator was found, else returns FALSE. |
| 28266 |
.RS 4 |
| 28267 |
.Sp |
| 28268 |
.Vb 2 |
| 28269 |
\& bool sv_cat_decode(SV *dsv, SV *encoding, SV *ssv, int *offset, |
| 28270 |
\& char *tstr, int tlen) |
| 28271 |
.Ve |
| 28272 |
.RE |
| 28273 |
.RS 4 |
| 28274 |
.RE |
| 28275 |
.ie n .IP """sv_recode_to_utf8""" 4 |
| 28276 |
.el .IP \f(CWsv_recode_to_utf8\fR 4 |
| 28277 |
.IX Xref "sv_recode_to_utf8" |
| 28278 |
.IX Item "sv_recode_to_utf8" |
| 28279 |
\&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, on entry the PV |
| 28280 |
of \f(CW\*(C`sv\*(C'\fR is assumed to be octets in that encoding, and \f(CW\*(C`sv\*(C'\fR |
| 28281 |
will be converted into Unicode (and UTF\-8). |
| 28282 |
.Sp |
| 28283 |
If \f(CW\*(C`sv\*(C'\fR already is UTF\-8 (or if it is not \f(CW\*(C`POK\*(C'\fR), or if \f(CW\*(C`encoding\*(C'\fR |
| 28284 |
is not a reference, nothing is done to \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`encoding\*(C'\fR is not |
| 28285 |
an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen. |
| 28286 |
(See encoding and Encode.) |
| 28287 |
.Sp |
| 28288 |
The PV of \f(CW\*(C`sv\*(C'\fR is returned. |
| 28289 |
.RS 4 |
| 28290 |
.Sp |
| 28291 |
.Vb 1 |
| 28292 |
\& char * sv_recode_to_utf8(SV *sv, SV *encoding) |
| 28293 |
.Ve |
| 28294 |
.RE |
| 28295 |
.RS 4 |
| 28296 |
.RE |
| 28297 |
.ie n .IP """sv_uni_display""" 4 |
| 28298 |
.el .IP \f(CWsv_uni_display\fR 4 |
| 28299 |
.IX Xref "sv_uni_display" |
| 28300 |
.IX Item "sv_uni_display" |
| 28301 |
Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the scalar \f(CW\*(C`sv\*(C'\fR, |
| 28302 |
the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes long |
| 28303 |
(if longer, the rest is truncated and "..." will be appended). |
| 28304 |
.Sp |
| 28305 |
The \f(CW\*(C`flags\*(C'\fR argument is as in "pv_uni_display"(). |
| 28306 |
.Sp |
| 28307 |
The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned. |
| 28308 |
.RS 4 |
| 28309 |
.Sp |
| 28310 |
.Vb 1 |
| 28311 |
\& char * sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) |
| 28312 |
.Ve |
| 28313 |
.RE |
| 28314 |
.RS 4 |
| 28315 |
.RE |
| 28316 |
.ie n .IP """UNICODE_IS_NONCHAR""" 4 |
| 28317 |
.el .IP \f(CWUNICODE_IS_NONCHAR\fR 4 |
| 28318 |
.IX Xref "UNICODE_IS_NONCHAR" |
| 28319 |
.IX Item "UNICODE_IS_NONCHAR" |
| 28320 |
Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode |
| 28321 |
non-character code points |
| 28322 |
.RS 4 |
| 28323 |
.Sp |
| 28324 |
.Vb 1 |
| 28325 |
\& bool UNICODE_IS_NONCHAR(const UV uv) |
| 28326 |
.Ve |
| 28327 |
.RE |
| 28328 |
.RS 4 |
| 28329 |
.RE |
| 28330 |
.ie n .IP """UNICODE_IS_REPLACEMENT""" 4 |
| 28331 |
.el .IP \f(CWUNICODE_IS_REPLACEMENT\fR 4 |
| 28332 |
.IX Xref "UNICODE_IS_REPLACEMENT" |
| 28333 |
.IX Item "UNICODE_IS_REPLACEMENT" |
| 28334 |
Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is the Unicode REPLACEMENT |
| 28335 |
CHARACTER |
| 28336 |
.RS 4 |
| 28337 |
.Sp |
| 28338 |
.Vb 1 |
| 28339 |
\& bool UNICODE_IS_REPLACEMENT(const UV uv) |
| 28340 |
.Ve |
| 28341 |
.RE |
| 28342 |
.RS 4 |
| 28343 |
.RE |
| 28344 |
.ie n .IP """UNICODE_IS_SUPER""" 4 |
| 28345 |
.el .IP \f(CWUNICODE_IS_SUPER\fR 4 |
| 28346 |
.IX Xref "UNICODE_IS_SUPER" |
| 28347 |
.IX Item "UNICODE_IS_SUPER" |
| 28348 |
Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is above the maximum legal Unicode |
| 28349 |
code point of U+10FFFF. |
| 28350 |
.RS 4 |
| 28351 |
.Sp |
| 28352 |
.Vb 1 |
| 28353 |
\& bool UNICODE_IS_SUPER(const UV uv) |
| 28354 |
.Ve |
| 28355 |
.RE |
| 28356 |
.RS 4 |
| 28357 |
.RE |
| 28358 |
.ie n .IP """UNICODE_IS_SURROGATE""" 4 |
| 28359 |
.el .IP \f(CWUNICODE_IS_SURROGATE\fR 4 |
| 28360 |
.IX Xref "UNICODE_IS_SURROGATE" |
| 28361 |
.IX Item "UNICODE_IS_SURROGATE" |
| 28362 |
Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode surrogate |
| 28363 |
code points |
| 28364 |
.RS 4 |
| 28365 |
.Sp |
| 28366 |
.Vb 1 |
| 28367 |
\& bool UNICODE_IS_SURROGATE(const UV uv) |
| 28368 |
.Ve |
| 28369 |
.RE |
| 28370 |
.RS 4 |
| 28371 |
.RE |
| 28372 |
.ie n .IP """UNICODE_REPLACEMENT""" 4 |
| 28373 |
.el .IP \f(CWUNICODE_REPLACEMENT\fR 4 |
| 28374 |
.IX Xref "UNICODE_REPLACEMENT" |
| 28375 |
.IX Item "UNICODE_REPLACEMENT" |
| 28376 |
Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT CHARACTER |
| 28377 |
.ie n .IP """UNI_TO_NATIVE""" 4 |
| 28378 |
.el .IP \f(CWUNI_TO_NATIVE\fR 4 |
| 28379 |
.IX Xref "UNI_TO_NATIVE" |
| 28380 |
.IX Item "UNI_TO_NATIVE" |
| 28381 |
Returns the native equivalent of the input Unicode code point given by \f(CW\*(C`ch\*(C'\fR. |
| 28382 |
Thus, \f(CWUNI_TO_NATIVE(68)\fR on EBCDIC platforms returns 196. These each |
| 28383 |
represent the character \f(CW"D"\fR on their respective platforms. On ASCII |
| 28384 |
platforms no conversion is needed, so this macro expands to just its input, |
| 28385 |
adding no time nor space requirements to the implementation. |
| 28386 |
.RS 4 |
| 28387 |
.Sp |
| 28388 |
.Vb 1 |
| 28389 |
\& UV UNI_TO_NATIVE(UV ch) |
| 28390 |
.Ve |
| 28391 |
.RE |
| 28392 |
.RS 4 |
| 28393 |
.RE |
| 28394 |
.ie n .IP """UTF8_CHK_SKIP""" 4 |
| 28395 |
.el .IP \f(CWUTF8_CHK_SKIP\fR 4 |
| 28396 |
.IX Xref "UTF8_CHK_SKIP" |
| 28397 |
.IX Item "UTF8_CHK_SKIP" |
| 28398 |
This is a safer version of \f(CW"UTF8SKIP"\fR, but still not as safe as |
| 28399 |
\&\f(CW"UTF8_SAFE_SKIP"\fR. This version doesn't blindly assume that the input |
| 28400 |
string pointed to by \f(CW\*(C`s\*(C'\fR is well-formed, but verifies that there isn't a NUL |
| 28401 |
terminating character before the expected end of the next character in \f(CW\*(C`s\*(C'\fR. |
| 28402 |
The length \f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR returns stops just before any such NUL. |
| 28403 |
.Sp |
| 28404 |
Perl tends to add NULs, as an insurance policy, after the end of strings in |
| 28405 |
SV's, so it is likely that using this macro will prevent inadvertent reading |
| 28406 |
beyond the end of the input buffer, even if it is malformed UTF\-8. |
| 28407 |
.Sp |
| 28408 |
This macro is intended to be used by XS modules where the inputs could be |
| 28409 |
malformed, and it isn't feasible to restructure to use the safer |
| 28410 |
\&\f(CW"UTF8_SAFE_SKIP"\fR, for example when interfacing with a C library. |
| 28411 |
.RS 4 |
| 28412 |
.Sp |
| 28413 |
.Vb 1 |
| 28414 |
\& STRLEN UTF8_CHK_SKIP(char* s) |
| 28415 |
.Ve |
| 28416 |
.RE |
| 28417 |
.RS 4 |
| 28418 |
.RE |
| 28419 |
.ie n .IP """utf8_distance""" 4 |
| 28420 |
.el .IP \f(CWutf8_distance\fR 4 |
| 28421 |
.IX Xref "utf8_distance" |
| 28422 |
.IX Item "utf8_distance" |
| 28423 |
Returns the number of UTF\-8 characters between the UTF\-8 pointers \f(CW\*(C`a\*(C'\fR |
| 28424 |
and \f(CW\*(C`b\*(C'\fR. |
| 28425 |
.Sp |
| 28426 |
WARNING: use only if you *know* that the pointers point inside the |
| 28427 |
same UTF\-8 buffer. |
| 28428 |
.RS 4 |
| 28429 |
.Sp |
| 28430 |
.Vb 1 |
| 28431 |
\& IV utf8_distance(const U8 *a, const U8 *b) |
| 28432 |
.Ve |
| 28433 |
.RE |
| 28434 |
.RS 4 |
| 28435 |
.RE |
| 28436 |
.ie n .IP """utf8_hop""" 4 |
| 28437 |
.el .IP \f(CWutf8_hop\fR 4 |
| 28438 |
.IX Xref "utf8_hop" |
| 28439 |
.IX Item "utf8_hop" |
| 28440 |
Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either |
| 28441 |
forward (if \f(CW\*(C`off\*(C'\fR is positive) or backward (if negative). \f(CW\*(C`s\*(C'\fR does not need |
| 28442 |
to be pointing to the starting byte of a character. If it isn't, one count of |
| 28443 |
\&\f(CW\*(C`off\*(C'\fR will be used up to get to the start of the next character for forward |
| 28444 |
hops, and to the start of the current character for negative ones. |
| 28445 |
.Sp |
| 28446 |
WARNING: Prefer "utf8_hop_safe" to this one. |
| 28447 |
.Sp |
| 28448 |
Do NOT use this function unless you \fBknow\fR \f(CW\*(C`off\*(C'\fR is within |
| 28449 |
the UTF\-8 data pointed to by \f(CW\*(C`s\*(C'\fR \fBand\fR that on entry \f(CW\*(C`s\*(C'\fR is aligned |
| 28450 |
on the first byte of a character or just after the last byte of a character. |
| 28451 |
.RS 4 |
| 28452 |
.Sp |
| 28453 |
.Vb 1 |
| 28454 |
\& U8 * utf8_hop(const U8 *s, SSize_t off) |
| 28455 |
.Ve |
| 28456 |
.RE |
| 28457 |
.RS 4 |
| 28458 |
.RE |
| 28459 |
.ie n .IP """utf8_hop_back""" 4 |
| 28460 |
.el .IP \f(CWutf8_hop_back\fR 4 |
| 28461 |
.IX Xref "utf8_hop_back" |
| 28462 |
.IX Item "utf8_hop_back" |
| 28463 |
Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters, |
| 28464 |
backward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a |
| 28465 |
character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that |
| 28466 |
start. |
| 28467 |
.Sp |
| 28468 |
\&\f(CW\*(C`off\*(C'\fR must be non-positive. |
| 28469 |
.Sp |
| 28470 |
\&\f(CW\*(C`s\*(C'\fR must be after or equal to \f(CW\*(C`start\*(C'\fR. |
| 28471 |
.Sp |
| 28472 |
When moving backward it will not move before \f(CW\*(C`start\*(C'\fR. |
| 28473 |
.Sp |
| 28474 |
Will not exceed this limit even if the string is not valid "UTF\-8". |
| 28475 |
.RS 4 |
| 28476 |
.Sp |
| 28477 |
.Vb 1 |
| 28478 |
\& U8 * utf8_hop_back(const U8 *s, SSize_t off, const U8 *start) |
| 28479 |
.Ve |
| 28480 |
.RE |
| 28481 |
.RS 4 |
| 28482 |
.RE |
| 28483 |
.ie n .IP """utf8_hop_forward""" 4 |
| 28484 |
.el .IP \f(CWutf8_hop_forward\fR 4 |
| 28485 |
.IX Xref "utf8_hop_forward" |
| 28486 |
.IX Item "utf8_hop_forward" |
| 28487 |
Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters, |
| 28488 |
forward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a |
| 28489 |
character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to the |
| 28490 |
start of the next character. |
| 28491 |
.Sp |
| 28492 |
\&\f(CW\*(C`off\*(C'\fR must be non-negative. |
| 28493 |
.Sp |
| 28494 |
\&\f(CW\*(C`s\*(C'\fR must be before or equal to \f(CW\*(C`end\*(C'\fR. |
| 28495 |
.Sp |
| 28496 |
When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR. |
| 28497 |
.Sp |
| 28498 |
Will not exceed this limit even if the string is not valid "UTF\-8". |
| 28499 |
.RS 4 |
| 28500 |
.Sp |
| 28501 |
.Vb 1 |
| 28502 |
\& U8 * utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end) |
| 28503 |
.Ve |
| 28504 |
.RE |
| 28505 |
.RS 4 |
| 28506 |
.RE |
| 28507 |
.ie n .IP """utf8_hop_safe""" 4 |
| 28508 |
.el .IP \f(CWutf8_hop_safe\fR 4 |
| 28509 |
.IX Xref "utf8_hop_safe" |
| 28510 |
.IX Item "utf8_hop_safe" |
| 28511 |
Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters, |
| 28512 |
either forward or backward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting |
| 28513 |
byte of a character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get |
| 28514 |
to the start of the next character for forward hops, and to the start of the |
| 28515 |
current character for negative ones. |
| 28516 |
.Sp |
| 28517 |
When moving backward it will not move before \f(CW\*(C`start\*(C'\fR. |
| 28518 |
.Sp |
| 28519 |
When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR. |
| 28520 |
.Sp |
| 28521 |
Will not exceed those limits even if the string is not valid "UTF\-8". |
| 28522 |
.RS 4 |
| 28523 |
.Sp |
| 28524 |
.Vb 2 |
| 28525 |
\& U8 * utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start, |
| 28526 |
\& const U8 *end) |
| 28527 |
.Ve |
| 28528 |
.RE |
| 28529 |
.RS 4 |
| 28530 |
.RE |
| 28531 |
.ie n .IP """UTF8_IS_INVARIANT""" 4 |
| 28532 |
.el .IP \f(CWUTF8_IS_INVARIANT\fR 4 |
| 28533 |
.IX Xref "UTF8_IS_INVARIANT" |
| 28534 |
.IX Item "UTF8_IS_INVARIANT" |
| 28535 |
Evaluates to 1 if the byte \f(CW\*(C`c\*(C'\fR represents the same character when encoded in |
| 28536 |
UTF\-8 as when not; otherwise evaluates to 0. UTF\-8 invariant characters can be |
| 28537 |
copied as-is when converting to/from UTF\-8, saving time. |
| 28538 |
.Sp |
| 28539 |
In spite of the name, this macro gives the correct result if the input string |
| 28540 |
from which \f(CW\*(C`c\*(C'\fR comes is not encoded in UTF\-8. |
| 28541 |
.Sp |
| 28542 |
See \f(CW"UVCHR_IS_INVARIANT"\fR for checking if a UV is invariant. |
| 28543 |
.RS 4 |
| 28544 |
.Sp |
| 28545 |
.Vb 1 |
| 28546 |
\& bool UTF8_IS_INVARIANT(char c) |
| 28547 |
.Ve |
| 28548 |
.RE |
| 28549 |
.RS 4 |
| 28550 |
.RE |
| 28551 |
.ie n .IP """UTF8_IS_NONCHAR""" 4 |
| 28552 |
.el .IP \f(CWUTF8_IS_NONCHAR\fR 4 |
| 28553 |
.IX Xref "UTF8_IS_NONCHAR" |
| 28554 |
.IX Item "UTF8_IS_NONCHAR" |
| 28555 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 28556 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one |
| 28557 |
of the Unicode non-character code points; otherwise it evaluates to 0. If |
| 28558 |
non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code |
| 28559 |
point's representation. |
| 28560 |
.RS 4 |
| 28561 |
.Sp |
| 28562 |
.Vb 1 |
| 28563 |
\& bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e) |
| 28564 |
.Ve |
| 28565 |
.RE |
| 28566 |
.RS 4 |
| 28567 |
.RE |
| 28568 |
.ie n .IP """UTF8_IS_REPLACEMENT""" 4 |
| 28569 |
.el .IP \f(CWUTF8_IS_REPLACEMENT\fR 4 |
| 28570 |
.IX Xref "UTF8_IS_REPLACEMENT" |
| 28571 |
.IX Item "UTF8_IS_REPLACEMENT" |
| 28572 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 28573 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents the |
| 28574 |
Unicode REPLACEMENT CHARACTER; otherwise it evaluates to 0. If non-zero, the |
| 28575 |
value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's |
| 28576 |
representation. |
| 28577 |
.RS 4 |
| 28578 |
.Sp |
| 28579 |
.Vb 1 |
| 28580 |
\& bool UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e) |
| 28581 |
.Ve |
| 28582 |
.RE |
| 28583 |
.RS 4 |
| 28584 |
.RE |
| 28585 |
.ie n .IP """UTF8_IS_SUPER""" 4 |
| 28586 |
.el .IP \f(CWUTF8_IS_SUPER\fR 4 |
| 28587 |
.IX Xref "UTF8_IS_SUPER" |
| 28588 |
.IX Item "UTF8_IS_SUPER" |
| 28589 |
Recall that Perl recognizes an extension to UTF\-8 that can encode code |
| 28590 |
points larger than the ones defined by Unicode, which are 0..0x10FFFF. |
| 28591 |
.Sp |
| 28592 |
This macro evaluates to non-zero if the first few bytes of the string starting |
| 28593 |
at \f(CW\*(C`s\*(C'\fR and looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are from this UTF\-8 extension; |
| 28594 |
otherwise it evaluates to 0. If non-zero, the return is how many bytes |
| 28595 |
starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation. |
| 28596 |
.Sp |
| 28597 |
0 is returned if the bytes are not well-formed extended UTF\-8, or if they |
| 28598 |
represent a code point that cannot fit in a UV on the current platform. Hence |
| 28599 |
this macro can give different results when run on a 64\-bit word machine than on |
| 28600 |
one with a 32\-bit word size. |
| 28601 |
.Sp |
| 28602 |
Note that it is illegal in Perl to have code points that are larger than what can |
| 28603 |
fit in an IV on the current machine; and illegal in Unicode to have any that |
| 28604 |
this macro matches |
| 28605 |
.RS 4 |
| 28606 |
.Sp |
| 28607 |
.Vb 1 |
| 28608 |
\& bool UTF8_IS_SUPER(const U8 *s, const U8 *e) |
| 28609 |
.Ve |
| 28610 |
.RE |
| 28611 |
.RS 4 |
| 28612 |
.RE |
| 28613 |
.ie n .IP """UTF8_IS_SURROGATE""" 4 |
| 28614 |
.el .IP \f(CWUTF8_IS_SURROGATE\fR 4 |
| 28615 |
.IX Xref "UTF8_IS_SURROGATE" |
| 28616 |
.IX Item "UTF8_IS_SURROGATE" |
| 28617 |
Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and |
| 28618 |
looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one |
| 28619 |
of the Unicode surrogate code points; otherwise it evaluates to 0. If |
| 28620 |
non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code |
| 28621 |
point's representation. |
| 28622 |
.RS 4 |
| 28623 |
.Sp |
| 28624 |
.Vb 1 |
| 28625 |
\& bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e) |
| 28626 |
.Ve |
| 28627 |
.RE |
| 28628 |
.RS 4 |
| 28629 |
.RE |
| 28630 |
.ie n .IP """utf8_length""" 4 |
| 28631 |
.el .IP \f(CWutf8_length\fR 4 |
| 28632 |
.IX Xref "utf8_length" |
| 28633 |
.IX Item "utf8_length" |
| 28634 |
Returns the number of characters in the sequence of UTF\-8\-encoded bytes starting |
| 28635 |
at \f(CW\*(C`s\*(C'\fR and ending at the byte just before \f(CW\*(C`e\*(C'\fR. If <s> and <e> point to the |
| 28636 |
same place, it returns 0 with no warning raised. |
| 28637 |
.Sp |
| 28638 |
If \f(CW\*(C`e < s\*(C'\fR or if the scan would end up past \f(CW\*(C`e\*(C'\fR, it raises a UTF8 warning |
| 28639 |
and returns the number of valid characters. |
| 28640 |
.RS 4 |
| 28641 |
.Sp |
| 28642 |
.Vb 1 |
| 28643 |
\& STRLEN utf8_length(const U8 *s0, const U8 *e) |
| 28644 |
.Ve |
| 28645 |
.RE |
| 28646 |
.RS 4 |
| 28647 |
.RE |
| 28648 |
.ie n .IP """UTF8_MAXBYTES""" 4 |
| 28649 |
.el .IP \f(CWUTF8_MAXBYTES\fR 4 |
| 28650 |
.IX Xref "UTF8_MAXBYTES" |
| 28651 |
.IX Item "UTF8_MAXBYTES" |
| 28652 |
The maximum width of a single UTF\-8 encoded character, in bytes. |
| 28653 |
.Sp |
| 28654 |
NOTE: Strictly speaking Perl's UTF\-8 should not be called UTF\-8 since UTF\-8 |
| 28655 |
is an encoding of Unicode, and Unicode's upper limit, 0x10FFFF, can be |
| 28656 |
expressed with 4 bytes. However, Perl thinks of UTF\-8 as a way to encode |
| 28657 |
non-negative integers in a binary format, even those above Unicode. |
| 28658 |
.ie n .IP """UTF8_MAXBYTES_CASE""" 4 |
| 28659 |
.el .IP \f(CWUTF8_MAXBYTES_CASE\fR 4 |
| 28660 |
.IX Xref "UTF8_MAXBYTES_CASE" |
| 28661 |
.IX Item "UTF8_MAXBYTES_CASE" |
| 28662 |
The maximum number of UTF\-8 bytes a single Unicode character can |
| 28663 |
uppercase/lowercase/titlecase/fold into. |
| 28664 |
.ie n .IP """utf8ness_t""" 4 |
| 28665 |
.el .IP \f(CWutf8ness_t\fR 4 |
| 28666 |
.IX Xref "utf8ness_t" |
| 28667 |
.IX Item "utf8ness_t" |
| 28668 |
This typedef is used by several core functions that return PV strings, to |
| 28669 |
indicate the UTF\-8ness of those strings. |
| 28670 |
.Sp |
| 28671 |
(If you write a new function, you probably should instead return the PV in an |
| 28672 |
SV with the UTF\-8 flag of the SV properly set, rather than use this mechanism.) |
| 28673 |
.Sp |
| 28674 |
The possible values this can be are: |
| 28675 |
.RS 4 |
| 28676 |
.ie n .IP """UTF8NESS_YES""" 4 |
| 28677 |
.el .IP \f(CWUTF8NESS_YES\fR 4 |
| 28678 |
.IX Item "UTF8NESS_YES" |
| 28679 |
This means the string definitely should be treated as a sequence of |
| 28680 |
UTF\-8\-encoded characters. |
| 28681 |
.Sp |
| 28682 |
Most code that needs to handle this typedef should be of the form: |
| 28683 |
.Sp |
| 28684 |
.Vb 3 |
| 28685 |
\& if (utf8ness_flag == UTF8NESS_YES) { |
| 28686 |
\& treat as utf8; // like turning on an SV UTF\-8 flag |
| 28687 |
\& } |
| 28688 |
.Ve |
| 28689 |
.ie n .IP """UTF8NESS_NO""" 4 |
| 28690 |
.el .IP \f(CWUTF8NESS_NO\fR 4 |
| 28691 |
.IX Item "UTF8NESS_NO" |
| 28692 |
This means the string definitely should be treated as a sequence of bytes, not |
| 28693 |
encoded as UTF\-8. |
| 28694 |
.ie n .IP """UTF8NESS_IMMATERIAL""" 4 |
| 28695 |
.el .IP \f(CWUTF8NESS_IMMATERIAL\fR 4 |
| 28696 |
.IX Item "UTF8NESS_IMMATERIAL" |
| 28697 |
This means it is equally valid to treat the string as bytes, or as UTF\-8 |
| 28698 |
characters; use whichever way you want. This happens when the string consists |
| 28699 |
entirely of characters which have the same representation whether encoded in |
| 28700 |
UTF\-8 or not. |
| 28701 |
.ie n .IP """UTF8NESS_UNKNOWN""" 4 |
| 28702 |
.el .IP \f(CWUTF8NESS_UNKNOWN\fR 4 |
| 28703 |
.IX Item "UTF8NESS_UNKNOWN" |
| 28704 |
This means it is unknown how the string should be treated. No core function |
| 28705 |
will ever return this value to a non-core caller. Instead, it is used by the |
| 28706 |
caller to initialize a variable to a non-legal value. A typical call will look like: |
| 28707 |
.Sp |
| 28708 |
.Vb 5 |
| 28709 |
\& utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN |
| 28710 |
\& const char * string = foo(arg1, arg2, ..., &string_is_utf8); |
| 28711 |
\& if (string_is_utf8 == UTF8NESS_YES) { |
| 28712 |
\& do something for UTF\-8; |
| 28713 |
\& } |
| 28714 |
.Ve |
| 28715 |
.RE |
| 28716 |
.RS 4 |
| 28717 |
.Sp |
| 28718 |
The following relationships hold between the enum values: |
| 28719 |
.ie n .IP """0\ <=\ \fIenum\ value\fR\ <=\ UTF8NESS_IMMATERIAL""" 4 |
| 28720 |
.el .IP "\f(CW0\ <=\ \fR\f(CIenum\ value\fR\f(CW\ <=\ UTF8NESS_IMMATERIAL\fR" 4 |
| 28721 |
.IX Item "0 <= enum value <= UTF8NESS_IMMATERIAL" |
| 28722 |
the string may be treated in code as non\-UTF8 |
| 28723 |
.ie n .IP """UTF8NESS_IMMATERIAL\ <=\ <\fIenum\ value\fR""" 4 |
| 28724 |
.el .IP "\f(CWUTF8NESS_IMMATERIAL\ <=\ <\fR\f(CIenum\ value\fR\f(CW\fR" 4 |
| 28725 |
.IX Item "UTF8NESS_IMMATERIAL <= <enum value" |
| 28726 |
the string may be treated in code as encoded in UTF\-8 |
| 28727 |
.RE |
| 28728 |
.RS 4 |
| 28729 |
.RE |
| 28730 |
.ie n .IP """utf8n_to_uvchr""" 4 |
| 28731 |
.el .IP \f(CWutf8n_to_uvchr\fR 4 |
| 28732 |
.IX Xref "utf8n_to_uvchr" |
| 28733 |
.IX Item "utf8n_to_uvchr" |
| 28734 |
THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. |
| 28735 |
Most code should use "utf8_to_uvchr_buf"() rather than call this |
| 28736 |
directly. |
| 28737 |
.Sp |
| 28738 |
Bottom level UTF\-8 decode routine. |
| 28739 |
Returns the native code point value of the first character in the string \f(CW\*(C`s\*(C'\fR, |
| 28740 |
which is assumed to be in UTF\-8 (or UTF-EBCDIC) encoding, and no longer than |
| 28741 |
\&\f(CW\*(C`curlen\*(C'\fR bytes; \f(CW*retlen\fR (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) will be set to |
| 28742 |
the length, in bytes, of that character. |
| 28743 |
.Sp |
| 28744 |
The value of \f(CW\*(C`flags\*(C'\fR determines the behavior when \f(CW\*(C`s\*(C'\fR does not point to a |
| 28745 |
well-formed UTF\-8 character. If \f(CW\*(C`flags\*(C'\fR is 0, encountering a malformation |
| 28746 |
causes zero to be returned and \f(CW*retlen\fR is set so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) |
| 28747 |
is the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed |
| 28748 |
character. Also, if UTF\-8 warnings haven't been lexically disabled, a warning |
| 28749 |
is raised. Some UTF\-8 input sequences may contain multiple malformations. |
| 28750 |
This function tries to find every possible one in each call, so multiple |
| 28751 |
warnings can be raised for the same sequence. |
| 28752 |
.Sp |
| 28753 |
Various ALLOW flags can be set in \f(CW\*(C`flags\*(C'\fR to allow (and not warn on) |
| 28754 |
individual types of malformations, such as the sequence being overlong (that |
| 28755 |
is, when there is a shorter sequence that can express the same code point; |
| 28756 |
overlong sequences are expressly forbidden in the UTF\-8 standard due to |
| 28757 |
potential security issues). Another malformation example is the first byte of |
| 28758 |
a character not being a legal first byte. See \fIutf8.h\fR for the list of such |
| 28759 |
flags. Even if allowed, this function generally returns the Unicode |
| 28760 |
REPLACEMENT CHARACTER when it encounters a malformation. There are flags in |
| 28761 |
\&\fIutf8.h\fR to override this behavior for the overlong malformations, but don't |
| 28762 |
do that except for very specialized purposes. |
| 28763 |
.Sp |
| 28764 |
The \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag overrides the behavior when a non-allowed (by other |
| 28765 |
flags) malformation is found. If this flag is set, the routine assumes that |
| 28766 |
the caller will raise a warning, and this function will silently just set |
| 28767 |
\&\f(CW\*(C`retlen\*(C'\fR to \f(CW\-1\fR (cast to \f(CW\*(C`STRLEN\*(C'\fR) and return zero. |
| 28768 |
.Sp |
| 28769 |
Note that this API requires disambiguation between successful decoding a \f(CW\*(C`NUL\*(C'\fR |
| 28770 |
character, and an error return (unless the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag is set), as |
| 28771 |
in both cases, 0 is returned, and, depending on the malformation, \f(CW\*(C`retlen\*(C'\fR may |
| 28772 |
be set to 1. To disambiguate, upon a zero return, see if the first byte of |
| 28773 |
\&\f(CW\*(C`s\*(C'\fR is 0 as well. If so, the input was a \f(CW\*(C`NUL\*(C'\fR; if not, the input had an |
| 28774 |
error. Or you can use \f(CW"utf8n_to_uvchr_error"\fR. |
| 28775 |
.Sp |
| 28776 |
Certain code points are considered problematic. These are Unicode surrogates, |
| 28777 |
Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF. |
| 28778 |
By default these are considered regular code points, but certain situations |
| 28779 |
warrant special handling for them, which can be specified using the \f(CW\*(C`flags\*(C'\fR |
| 28780 |
parameter. If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, all |
| 28781 |
three classes are treated as malformations and handled as such. The flags |
| 28782 |
\&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR, \f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR, and |
| 28783 |
\&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR (meaning above the legal Unicode maximum) can be set to |
| 28784 |
disallow these categories individually. \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR |
| 28785 |
restricts the allowed inputs to the strict UTF\-8 traditionally defined by |
| 28786 |
Unicode. Use \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR to use the strictness |
| 28787 |
definition given by |
| 28788 |
Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>. |
| 28789 |
The difference between traditional strictness and C9 strictness is that the |
| 28790 |
latter does not forbid non-character code points. (They are still discouraged, |
| 28791 |
however.) For more discussion see "Noncharacter code points" in perlunicode. |
| 28792 |
.Sp |
| 28793 |
The flags \f(CW\*(C`UTF8_WARN_ILLEGAL_INTERCHANGE\*(C'\fR, |
| 28794 |
\&\f(CW\*(C`UTF8_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR, \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR, |
| 28795 |
\&\f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR, and \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR will cause warning messages to be |
| 28796 |
raised for their respective categories, but otherwise the code points are |
| 28797 |
considered valid (not malformations). To get a category to both be treated as |
| 28798 |
a malformation and raise a warning, specify both the WARN and DISALLOW flags. |
| 28799 |
(But note that warnings are not raised if lexically disabled nor if |
| 28800 |
\&\f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is also specified.) |
| 28801 |
.Sp |
| 28802 |
Extremely high code points were never specified in any standard, and require an |
| 28803 |
extension to UTF\-8 to express, which Perl does. It is likely that programs |
| 28804 |
written in something other than Perl would not be able to read files that |
| 28805 |
contain these; nor would Perl understand files written by something that uses a |
| 28806 |
different extension. For these reasons, there is a separate set of flags that |
| 28807 |
can warn and/or disallow these extremely high code points, even if other |
| 28808 |
above-Unicode ones are accepted. They are the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR and |
| 28809 |
\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR flags. For more information see |
| 28810 |
\&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR. Of course \f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR will treat all |
| 28811 |
above-Unicode code points, including these, as malformations. |
| 28812 |
(Note that the Unicode standard considers anything above 0x10FFFF to be |
| 28813 |
illegal, but there are standards predating it that allow up to 0x7FFF_FFFF |
| 28814 |
(2**31 \-1)) |
| 28815 |
.Sp |
| 28816 |
A somewhat misleadingly named synonym for \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR is |
| 28817 |
retained for backward compatibility: \f(CW\*(C`UTF8_WARN_ABOVE_31_BIT\*(C'\fR. Similarly, |
| 28818 |
\&\f(CW\*(C`UTF8_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named |
| 28819 |
\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR. The names are misleading because these flags |
| 28820 |
can apply to code points that actually do fit in 31 bits. This happens on |
| 28821 |
EBCDIC platforms, and sometimes when the overlong |
| 28822 |
malformation is also present. The new names accurately |
| 28823 |
describe the situation in all cases. |
| 28824 |
.Sp |
| 28825 |
All other code points corresponding to Unicode characters, including private |
| 28826 |
use and those yet to be assigned, are never considered malformed and never |
| 28827 |
warn. |
| 28828 |
.RS 4 |
| 28829 |
.Sp |
| 28830 |
.Vb 2 |
| 28831 |
\& UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, |
| 28832 |
\& const U32 flags) |
| 28833 |
.Ve |
| 28834 |
.RE |
| 28835 |
.RS 4 |
| 28836 |
.RE |
| 28837 |
.ie n .IP """utf8n_to_uvchr_error""" 4 |
| 28838 |
.el .IP \f(CWutf8n_to_uvchr_error\fR 4 |
| 28839 |
.IX Xref "utf8n_to_uvchr_error" |
| 28840 |
.IX Item "utf8n_to_uvchr_error" |
| 28841 |
THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. |
| 28842 |
Most code should use "utf8_to_uvchr_buf"() rather than call this |
| 28843 |
directly. |
| 28844 |
.Sp |
| 28845 |
This function is for code that needs to know what the precise malformation(s) |
| 28846 |
are when an error is found. If you also need to know the generated warning |
| 28847 |
messages, use "utf8n_to_uvchr_msgs"() instead. |
| 28848 |
.Sp |
| 28849 |
It is like \f(CW"utf8n_to_uvchr"\fR but it takes an extra parameter placed after |
| 28850 |
all the others, \f(CW\*(C`errors\*(C'\fR. If this parameter is 0, this function behaves |
| 28851 |
identically to \f(CW"utf8n_to_uvchr"\fR. Otherwise, \f(CW\*(C`errors\*(C'\fR should be a pointer |
| 28852 |
to a \f(CW\*(C`U32\*(C'\fR variable, which this function sets to indicate any errors found. |
| 28853 |
Upon return, if \f(CW*errors\fR is 0, there were no errors found. Otherwise, |
| 28854 |
\&\f(CW*errors\fR is the bit-wise \f(CW\*(C`OR\*(C'\fR of the bits described in the list below. Some |
| 28855 |
of these bits will be set if a malformation is found, even if the input |
| 28856 |
\&\f(CW\*(C`flags\*(C'\fR parameter indicates that the given malformation is allowed; those |
| 28857 |
exceptions are noted: |
| 28858 |
.RS 4 |
| 28859 |
.ie n .IP """UTF8_GOT_PERL_EXTENDED""" 4 |
| 28860 |
.el .IP \f(CWUTF8_GOT_PERL_EXTENDED\fR 4 |
| 28861 |
.IX Item "UTF8_GOT_PERL_EXTENDED" |
| 28862 |
The input sequence is not standard UTF\-8, but a Perl extension. This bit is |
| 28863 |
set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the |
| 28864 |
\&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR or the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR flags. |
| 28865 |
.Sp |
| 28866 |
Code points above 0x7FFF_FFFF (2**31 \- 1) were never specified in any standard, |
| 28867 |
and so some extension must be used to express them. Perl uses a natural |
| 28868 |
extension to UTF\-8 to represent the ones up to 2**36\-1, and invented a further |
| 28869 |
extension to represent even higher ones, so that any code point that fits in a |
| 28870 |
64\-bit word can be represented. Text using these extensions is not likely to |
| 28871 |
be portable to non-Perl code. We lump both of these extensions together and |
| 28872 |
refer to them as Perl extended UTF\-8. There exist other extensions that people |
| 28873 |
have invented, incompatible with Perl's. |
| 28874 |
.Sp |
| 28875 |
On EBCDIC platforms starting in Perl v5.24, the Perl extension for representing |
| 28876 |
extremely high code points kicks in at 0x3FFF_FFFF (2**30 \-1), which is lower |
| 28877 |
than on ASCII. Prior to that, code points 2**31 and higher were simply |
| 28878 |
unrepresentable, and a different, incompatible method was used to represent |
| 28879 |
code points between 2**30 and 2**31 \- 1. |
| 28880 |
.Sp |
| 28881 |
On both platforms, ASCII and EBCDIC, \f(CW\*(C`UTF8_GOT_PERL_EXTENDED\*(C'\fR is set if |
| 28882 |
Perl extended UTF\-8 is used. |
| 28883 |
.Sp |
| 28884 |
In earlier Perls, this bit was named \f(CW\*(C`UTF8_GOT_ABOVE_31_BIT\*(C'\fR, which you still |
| 28885 |
may use for backward compatibility. That name is misleading, as this flag may |
| 28886 |
be set when the code point actually does fit in 31 bits. This happens on |
| 28887 |
EBCDIC platforms, and sometimes when the overlong |
| 28888 |
malformation is also present. The new name accurately |
| 28889 |
describes the situation in all cases. |
| 28890 |
.ie n .IP """UTF8_GOT_CONTINUATION""" 4 |
| 28891 |
.el .IP \f(CWUTF8_GOT_CONTINUATION\fR 4 |
| 28892 |
.IX Item "UTF8_GOT_CONTINUATION" |
| 28893 |
The input sequence was malformed in that the first byte was a UTF\-8 |
| 28894 |
continuation byte. |
| 28895 |
.ie n .IP """UTF8_GOT_EMPTY""" 4 |
| 28896 |
.el .IP \f(CWUTF8_GOT_EMPTY\fR 4 |
| 28897 |
.IX Item "UTF8_GOT_EMPTY" |
| 28898 |
The input \f(CW\*(C`curlen\*(C'\fR parameter was 0. |
| 28899 |
.ie n .IP """UTF8_GOT_LONG""" 4 |
| 28900 |
.el .IP \f(CWUTF8_GOT_LONG\fR 4 |
| 28901 |
.IX Item "UTF8_GOT_LONG" |
| 28902 |
The input sequence was malformed in that there is some other sequence that |
| 28903 |
evaluates to the same code point, but that sequence is shorter than this one. |
| 28904 |
.Sp |
| 28905 |
Until Unicode 3.1, it was legal for programs to accept this malformation, but |
| 28906 |
it was discovered that this created security issues. |
| 28907 |
.ie n .IP """UTF8_GOT_NONCHAR""" 4 |
| 28908 |
.el .IP \f(CWUTF8_GOT_NONCHAR\fR 4 |
| 28909 |
.IX Item "UTF8_GOT_NONCHAR" |
| 28910 |
The code point represented by the input UTF\-8 sequence is for a Unicode |
| 28911 |
non-character code point. |
| 28912 |
This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the |
| 28913 |
\&\f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR or the \f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR flags. |
| 28914 |
.ie n .IP """UTF8_GOT_NON_CONTINUATION""" 4 |
| 28915 |
.el .IP \f(CWUTF8_GOT_NON_CONTINUATION\fR 4 |
| 28916 |
.IX Item "UTF8_GOT_NON_CONTINUATION" |
| 28917 |
The input sequence was malformed in that a non-continuation type byte was found |
| 28918 |
in a position where only a continuation type one should be. See also |
| 28919 |
\&\f(CW"UTF8_GOT_SHORT"\fR. |
| 28920 |
.ie n .IP """UTF8_GOT_OVERFLOW""" 4 |
| 28921 |
.el .IP \f(CWUTF8_GOT_OVERFLOW\fR 4 |
| 28922 |
.IX Item "UTF8_GOT_OVERFLOW" |
| 28923 |
The input sequence was malformed in that it is for a code point that is not |
| 28924 |
representable in the number of bits available in an IV on the current platform. |
| 28925 |
.ie n .IP """UTF8_GOT_SHORT""" 4 |
| 28926 |
.el .IP \f(CWUTF8_GOT_SHORT\fR 4 |
| 28927 |
.IX Item "UTF8_GOT_SHORT" |
| 28928 |
The input sequence was malformed in that \f(CW\*(C`curlen\*(C'\fR is smaller than required for |
| 28929 |
a complete sequence. In other words, the input is for a partial character |
| 28930 |
sequence. |
| 28931 |
.Sp |
| 28932 |
\&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR and \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR both indicate a too short |
| 28933 |
sequence. The difference is that \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR indicates always |
| 28934 |
that there is an error, while \f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR means that an incomplete |
| 28935 |
sequence was looked at. If no other flags are present, it means that the |
| 28936 |
sequence was valid as far as it went. Depending on the application, this could |
| 28937 |
mean one of three things: |
| 28938 |
.RS 4 |
| 28939 |
.IP \(bu 4 |
| 28940 |
The \f(CW\*(C`curlen\*(C'\fR length parameter passed in was too small, and the function was |
| 28941 |
prevented from examining all the necessary bytes. |
| 28942 |
.IP \(bu 4 |
| 28943 |
The buffer being looked at is based on reading data, and the data received so |
| 28944 |
far stopped in the middle of a character, so that the next read will |
| 28945 |
read the remainder of this character. (It is up to the caller to deal with the |
| 28946 |
split bytes somehow.) |
| 28947 |
.IP \(bu 4 |
| 28948 |
This is a real error, and the partial sequence is all we're going to get. |
| 28949 |
.RE |
| 28950 |
.RS 4 |
| 28951 |
.RE |
| 28952 |
.ie n .IP """UTF8_GOT_SUPER""" 4 |
| 28953 |
.el .IP \f(CWUTF8_GOT_SUPER\fR 4 |
| 28954 |
.IX Item "UTF8_GOT_SUPER" |
| 28955 |
The input sequence was malformed in that it is for a non-Unicode code point; |
| 28956 |
that is, one above the legal Unicode maximum. |
| 28957 |
This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the |
| 28958 |
\&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR flags. |
| 28959 |
.ie n .IP """UTF8_GOT_SURROGATE""" 4 |
| 28960 |
.el .IP \f(CWUTF8_GOT_SURROGATE\fR 4 |
| 28961 |
.IX Item "UTF8_GOT_SURROGATE" |
| 28962 |
The input sequence was malformed in that it is for a \-Unicode UTF\-16 surrogate |
| 28963 |
code point. |
| 28964 |
This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the |
| 28965 |
\&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR flags. |
| 28966 |
.RE |
| 28967 |
.RS 4 |
| 28968 |
.Sp |
| 28969 |
To do your own error handling, call this function with the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR |
| 28970 |
flag to suppress any warnings, and then examine the \f(CW*errors\fR return. |
| 28971 |
.Sp |
| 28972 |
.Vb 3 |
| 28973 |
\& UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen, |
| 28974 |
\& STRLEN *retlen, const U32 flags, |
| 28975 |
\& U32 *errors) |
| 28976 |
.Ve |
| 28977 |
.RE |
| 28978 |
.RS 4 |
| 28979 |
.RE |
| 28980 |
.ie n .IP """utf8n_to_uvchr_msgs""" 4 |
| 28981 |
.el .IP \f(CWutf8n_to_uvchr_msgs\fR 4 |
| 28982 |
.IX Xref "utf8n_to_uvchr_msgs" |
| 28983 |
.IX Item "utf8n_to_uvchr_msgs" |
| 28984 |
THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. |
| 28985 |
Most code should use "utf8_to_uvchr_buf"() rather than call this |
| 28986 |
directly. |
| 28987 |
.Sp |
| 28988 |
This function is for code that needs to know what the precise malformation(s) |
| 28989 |
are when an error is found, and wants the corresponding warning and/or error |
| 28990 |
messages to be returned to the caller rather than be displayed. All messages |
| 28991 |
that would have been displayed if all lexical warnings are enabled will be |
| 28992 |
returned. |
| 28993 |
.Sp |
| 28994 |
It is just like \f(CW"utf8n_to_uvchr_error"\fR but it takes an extra parameter |
| 28995 |
placed after all the others, \f(CW\*(C`msgs\*(C'\fR. If this parameter is 0, this function |
| 28996 |
behaves identically to \f(CW"utf8n_to_uvchr_error"\fR. Otherwise, \f(CW\*(C`msgs\*(C'\fR should |
| 28997 |
be a pointer to an \f(CW\*(C`AV *\*(C'\fR variable, in which this function creates a new AV to |
| 28998 |
contain any appropriate messages. The elements of the array are ordered so |
| 28999 |
that the first message that would have been displayed is in the 0th element, |
| 29000 |
and so on. Each element is a hash with three key-value pairs, as follows: |
| 29001 |
.RS 4 |
| 29002 |
.ie n .IP """text""" 4 |
| 29003 |
.el .IP \f(CWtext\fR 4 |
| 29004 |
.IX Item "text" |
| 29005 |
The text of the message as a \f(CW\*(C`SVpv\*(C'\fR. |
| 29006 |
.ie n .IP """warn_categories""" 4 |
| 29007 |
.el .IP \f(CWwarn_categories\fR 4 |
| 29008 |
.IX Item "warn_categories" |
| 29009 |
The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR. |
| 29010 |
.ie n .IP """flag""" 4 |
| 29011 |
.el .IP \f(CWflag\fR 4 |
| 29012 |
.IX Item "flag" |
| 29013 |
A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR. |
| 29014 |
The bit corresponds to some bit in the \f(CW*errors\fR return value, |
| 29015 |
such as \f(CW\*(C`UTF8_GOT_LONG\*(C'\fR. |
| 29016 |
.RE |
| 29017 |
.RS 4 |
| 29018 |
.Sp |
| 29019 |
It's important to note that specifying this parameter as non-null will cause |
| 29020 |
any warnings this function would otherwise generate to be suppressed, and |
| 29021 |
instead be placed in \f(CW*msgs\fR. The caller can check the lexical warnings state |
| 29022 |
(or not) when choosing what to do with the returned messages. |
| 29023 |
.Sp |
| 29024 |
If the flag \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is passed, no warnings are generated, and hence |
| 29025 |
no AV is created. |
| 29026 |
.Sp |
| 29027 |
The caller, of course, is responsible for freeing any returned AV. |
| 29028 |
.Sp |
| 29029 |
.Vb 3 |
| 29030 |
\& UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen, |
| 29031 |
\& STRLEN *retlen, const U32 flags, |
| 29032 |
\& U32 *errors, AV **msgs) |
| 29033 |
.Ve |
| 29034 |
.RE |
| 29035 |
.RS 4 |
| 29036 |
.RE |
| 29037 |
.ie n .IP """UTF8_SAFE_SKIP""" 4 |
| 29038 |
.el .IP \f(CWUTF8_SAFE_SKIP\fR 4 |
| 29039 |
.IX Xref "UTF8_SAFE_SKIP" |
| 29040 |
.IX Item "UTF8_SAFE_SKIP" |
| 29041 |
returns 0 if \f(CW\*(C`s\ >=\ e\*(C'\fR; otherwise returns the number of bytes in the |
| 29042 |
UTF\-8 encoded character whose first byte is pointed to by \f(CW\*(C`s\*(C'\fR. But it never |
| 29043 |
returns beyond \f(CW\*(C`e\*(C'\fR. On DEBUGGING builds, it asserts that \f(CW\*(C`s\ <=\ e\*(C'\fR. |
| 29044 |
.RS 4 |
| 29045 |
.Sp |
| 29046 |
.Vb 1 |
| 29047 |
\& STRLEN UTF8_SAFE_SKIP(char* s, char* e) |
| 29048 |
.Ve |
| 29049 |
.RE |
| 29050 |
.RS 4 |
| 29051 |
.RE |
| 29052 |
.ie n .IP """UTF8SKIP""" 4 |
| 29053 |
.el .IP \f(CWUTF8SKIP\fR 4 |
| 29054 |
.IX Xref "UTF8SKIP" |
| 29055 |
.IX Item "UTF8SKIP" |
| 29056 |
returns the number of bytes a non-malformed UTF\-8 encoded character whose first |
| 29057 |
(perhaps only) byte is pointed to by \f(CW\*(C`s\*(C'\fR. |
| 29058 |
.Sp |
| 29059 |
If there is a possibility of malformed input, use instead: |
| 29060 |
.RS 4 |
| 29061 |
.ie n .IP """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by ""s""; or" 4 |
| 29062 |
.el .IP "\f(CW""UTF8_SAFE_SKIP""\fR if you know the maximum ending pointer in the buffer pointed to by \f(CWs\fR; or" 4 |
| 29063 |
.IX Item """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by s; or" |
| 29064 |
.PD 0 |
| 29065 |
.ie n .IP """UTF8_CHK_SKIP"" if you don't know it." 4 |
| 29066 |
.el .IP "\f(CW""UTF8_CHK_SKIP""\fR if you don't know it." 4 |
| 29067 |
.IX Item """UTF8_CHK_SKIP"" if you don't know it." |
| 29068 |
.RE |
| 29069 |
.RS 4 |
| 29070 |
.PD |
| 29071 |
.Sp |
| 29072 |
It is better to restructure your code so the end pointer is passed down so that |
| 29073 |
you know what it actually is at the point of this call, but if that isn't |
| 29074 |
possible, \f(CW"UTF8_CHK_SKIP"\fR can minimize the chance of accessing beyond the end |
| 29075 |
of the input buffer. |
| 29076 |
.Sp |
| 29077 |
.Vb 1 |
| 29078 |
\& STRLEN UTF8SKIP(char* s) |
| 29079 |
.Ve |
| 29080 |
.RE |
| 29081 |
.RS 4 |
| 29082 |
.RE |
| 29083 |
.ie n .IP """UTF8_SKIP""" 4 |
| 29084 |
.el .IP \f(CWUTF8_SKIP\fR 4 |
| 29085 |
.IX Xref "UTF8_SKIP" |
| 29086 |
.IX Item "UTF8_SKIP" |
| 29087 |
This is a synonym for \f(CW"UTF8SKIP"\fR |
| 29088 |
.RS 4 |
| 29089 |
.Sp |
| 29090 |
.Vb 1 |
| 29091 |
\& STRLEN UTF8_SKIP(char* s) |
| 29092 |
.Ve |
| 29093 |
.RE |
| 29094 |
.RS 4 |
| 29095 |
.RE |
| 29096 |
.ie n .IP """utf8_to_bytes""" 4 |
| 29097 |
.el .IP \f(CWutf8_to_bytes\fR 4 |
| 29098 |
.IX Xref "utf8_to_bytes" |
| 29099 |
.IX Item "utf8_to_bytes" |
| 29100 |
NOTE: \f(CW\*(C`utf8_to_bytes\*(C'\fR is \fBexperimental\fR and may change or be |
| 29101 |
removed without notice. |
| 29102 |
.Sp |
| 29103 |
Converts a string \f(CW"s"\fR of length \f(CW*lenp\fR from UTF\-8 into native byte encoding. |
| 29104 |
Unlike "bytes_to_utf8", this over-writes the original string, and |
| 29105 |
updates \f(CW*lenp\fR to contain the new length. |
| 29106 |
Returns zero on failure (leaving \f(CW"s"\fR unchanged) setting \f(CW*lenp\fR to \-1. |
| 29107 |
.Sp |
| 29108 |
Upon successful return, the number of variants in the string can be computed by |
| 29109 |
having saved the value of \f(CW*lenp\fR before the call, and subtracting the |
| 29110 |
after-call value of \f(CW*lenp\fR from it. |
| 29111 |
.Sp |
| 29112 |
If you need a copy of the string, see "bytes_from_utf8". |
| 29113 |
.RS 4 |
| 29114 |
.Sp |
| 29115 |
.Vb 1 |
| 29116 |
\& U8 * utf8_to_bytes(U8 *s, STRLEN *lenp) |
| 29117 |
.Ve |
| 29118 |
.RE |
| 29119 |
.RS 4 |
| 29120 |
.RE |
| 29121 |
.ie n .IP """utf8_to_uvchr""" 4 |
| 29122 |
.el .IP \f(CWutf8_to_uvchr\fR 4 |
| 29123 |
.IX Xref "utf8_to_uvchr" |
| 29124 |
.IX Item "utf8_to_uvchr" |
| 29125 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`utf8_to_uvchr\*(C'\fR |
| 29126 |
from a future release of Perl. Do not use it for |
| 29127 |
new code; remove it from existing code. |
| 29128 |
.Sp |
| 29129 |
Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR |
| 29130 |
which is assumed to be in UTF\-8 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the |
| 29131 |
length, in bytes, of that character. |
| 29132 |
.Sp |
| 29133 |
Some, but not all, UTF\-8 malformations are detected, and in fact, some |
| 29134 |
malformed input could cause reading beyond the end of the input buffer, which |
| 29135 |
is why this function is deprecated. Use "utf8_to_uvchr_buf" instead. |
| 29136 |
.Sp |
| 29137 |
If \f(CW\*(C`s\*(C'\fR points to one of the detected malformations, and UTF8 warnings are |
| 29138 |
enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't |
| 29139 |
\&\f(CW\*(C`NULL\*(C'\fR) to \-1. If those warnings are off, the computed value if well-defined (or |
| 29140 |
the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and \f(CW*retlen\fR |
| 29141 |
is set (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the |
| 29142 |
next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character. |
| 29143 |
See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is returned. |
| 29144 |
.RS 4 |
| 29145 |
.Sp |
| 29146 |
.Vb 1 |
| 29147 |
\& UV utf8_to_uvchr(const U8 *s, STRLEN *retlen) |
| 29148 |
.Ve |
| 29149 |
.RE |
| 29150 |
.RS 4 |
| 29151 |
.RE |
| 29152 |
.ie n .IP """utf8_to_uvchr_buf""" 4 |
| 29153 |
.el .IP \f(CWutf8_to_uvchr_buf\fR 4 |
| 29154 |
.IX Xref "utf8_to_uvchr_buf" |
| 29155 |
.IX Item "utf8_to_uvchr_buf" |
| 29156 |
Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR which |
| 29157 |
is assumed to be in UTF\-8 encoding; \f(CW\*(C`send\*(C'\fR points to 1 beyond the end of \f(CW\*(C`s\*(C'\fR. |
| 29158 |
\&\f(CW*retlen\fR will be set to the length, in bytes, of that character. |
| 29159 |
.Sp |
| 29160 |
If \f(CW\*(C`s\*(C'\fR does not point to a well-formed UTF\-8 character and UTF8 warnings are |
| 29161 |
enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't |
| 29162 |
\&\f(CW\*(C`NULL\*(C'\fR) to \-1. If those warnings are off, the computed value, if well-defined |
| 29163 |
(or the Unicode REPLACEMENT CHARACTER if not), is silently returned, and |
| 29164 |
\&\f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't \f(CW\*(C`NULL\*(C'\fR) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is |
| 29165 |
the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character. |
| 29166 |
See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is |
| 29167 |
returned. |
| 29168 |
.RS 4 |
| 29169 |
.Sp |
| 29170 |
.Vb 1 |
| 29171 |
\& UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen) |
| 29172 |
.Ve |
| 29173 |
.RE |
| 29174 |
.RS 4 |
| 29175 |
.RE |
| 29176 |
.ie n .IP """UVCHR_IS_INVARIANT""" 4 |
| 29177 |
.el .IP \f(CWUVCHR_IS_INVARIANT\fR 4 |
| 29178 |
.IX Xref "UVCHR_IS_INVARIANT" |
| 29179 |
.IX Item "UVCHR_IS_INVARIANT" |
| 29180 |
Evaluates to 1 if the representation of code point \f(CW\*(C`cp\*(C'\fR is the same whether or |
| 29181 |
not it is encoded in UTF\-8; otherwise evaluates to 0. UTF\-8 invariant |
| 29182 |
characters can be copied as-is when converting to/from UTF\-8, saving time. |
| 29183 |
\&\f(CW\*(C`cp\*(C'\fR is Unicode if above 255; otherwise is platform-native. |
| 29184 |
.RS 4 |
| 29185 |
.Sp |
| 29186 |
.Vb 1 |
| 29187 |
\& bool UVCHR_IS_INVARIANT(UV cp) |
| 29188 |
.Ve |
| 29189 |
.RE |
| 29190 |
.RS 4 |
| 29191 |
.RE |
| 29192 |
.ie n .IP """UVCHR_SKIP""" 4 |
| 29193 |
.el .IP \f(CWUVCHR_SKIP\fR 4 |
| 29194 |
.IX Xref "UVCHR_SKIP" |
| 29195 |
.IX Item "UVCHR_SKIP" |
| 29196 |
returns the number of bytes required to represent the code point \f(CW\*(C`cp\*(C'\fR when |
| 29197 |
encoded as UTF\-8. \f(CW\*(C`cp\*(C'\fR is a native (ASCII or EBCDIC) code point if less than |
| 29198 |
255; a Unicode code point otherwise. |
| 29199 |
.RS 4 |
| 29200 |
.Sp |
| 29201 |
.Vb 1 |
| 29202 |
\& STRLEN UVCHR_SKIP(UV cp) |
| 29203 |
.Ve |
| 29204 |
.RE |
| 29205 |
.RS 4 |
| 29206 |
.RE |
| 29207 |
.ie n .IP """uvchr_to_utf8_flags""" 4 |
| 29208 |
.el .IP \f(CWuvchr_to_utf8_flags\fR 4 |
| 29209 |
.IX Xref "uvchr_to_utf8_flags" |
| 29210 |
.IX Item "uvchr_to_utf8_flags" |
| 29211 |
Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end |
| 29212 |
of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to |
| 29213 |
\&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available. The return value is the pointer to |
| 29214 |
the byte after the end of the new character. In other words, |
| 29215 |
.Sp |
| 29216 |
.Vb 1 |
| 29217 |
\& d = uvchr_to_utf8_flags(d, uv, flags); |
| 29218 |
.Ve |
| 29219 |
.Sp |
| 29220 |
or, in most cases, |
| 29221 |
.Sp |
| 29222 |
.Vb 1 |
| 29223 |
\& d = uvchr_to_utf8_flags(d, uv, 0); |
| 29224 |
.Ve |
| 29225 |
.Sp |
| 29226 |
This is the Unicode-aware way of saying |
| 29227 |
.Sp |
| 29228 |
.Vb 1 |
| 29229 |
\& *(d++) = uv; |
| 29230 |
.Ve |
| 29231 |
.Sp |
| 29232 |
If \f(CW\*(C`flags\*(C'\fR is 0, this function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as |
| 29233 |
input. \f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word. |
| 29234 |
.Sp |
| 29235 |
Specifying \f(CW\*(C`flags\*(C'\fR can further restrict what is allowed and not warned on, as |
| 29236 |
follows: |
| 29237 |
.Sp |
| 29238 |
If \f(CW\*(C`uv\*(C'\fR is a Unicode surrogate code point and \f(CW\*(C`UNICODE_WARN_SURROGATE\*(C'\fR is set, |
| 29239 |
the function will raise a warning, provided UTF8 warnings are enabled. If |
| 29240 |
instead \f(CW\*(C`UNICODE_DISALLOW_SURROGATE\*(C'\fR is set, the function will fail and return |
| 29241 |
NULL. If both flags are set, the function will both warn and return NULL. |
| 29242 |
.Sp |
| 29243 |
Similarly, the \f(CW\*(C`UNICODE_WARN_NONCHAR\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_NONCHAR\*(C'\fR flags |
| 29244 |
affect how the function handles a Unicode non-character. |
| 29245 |
.Sp |
| 29246 |
And likewise, the \f(CW\*(C`UNICODE_WARN_SUPER\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR flags |
| 29247 |
affect the handling of code points that are above the Unicode maximum of |
| 29248 |
0x10FFFF. Languages other than Perl may not be able to accept files that |
| 29249 |
contain these. |
| 29250 |
.Sp |
| 29251 |
The flag \f(CW\*(C`UNICODE_WARN_ILLEGAL_INTERCHANGE\*(C'\fR selects all three of |
| 29252 |
the above WARN flags; and \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR selects all |
| 29253 |
three DISALLOW flags. \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR restricts the |
| 29254 |
allowed inputs to the strict UTF\-8 traditionally defined by Unicode. |
| 29255 |
Similarly, \f(CW\*(C`UNICODE_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR and |
| 29256 |
\&\f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR are shortcuts to select the |
| 29257 |
above-Unicode and surrogate flags, but not the non-character ones, as |
| 29258 |
defined in |
| 29259 |
Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>. |
| 29260 |
See "Noncharacter code points" in perlunicode. |
| 29261 |
.Sp |
| 29262 |
Extremely high code points were never specified in any standard, and require an |
| 29263 |
extension to UTF\-8 to express, which Perl does. It is likely that programs |
| 29264 |
written in something other than Perl would not be able to read files that |
| 29265 |
contain these; nor would Perl understand files written by something that uses a |
| 29266 |
different extension. For these reasons, there is a separate set of flags that |
| 29267 |
can warn and/or disallow these extremely high code points, even if other |
| 29268 |
above-Unicode ones are accepted. They are the \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR |
| 29269 |
and \f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR flags. For more information see |
| 29270 |
\&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR. Of course \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR will |
| 29271 |
treat all above-Unicode code points, including these, as malformations. (Note |
| 29272 |
that the Unicode standard considers anything above 0x10FFFF to be illegal, but |
| 29273 |
there are standards predating it that allow up to 0x7FFF_FFFF (2**31 \-1)) |
| 29274 |
.Sp |
| 29275 |
A somewhat misleadingly named synonym for \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR is |
| 29276 |
retained for backward compatibility: \f(CW\*(C`UNICODE_WARN_ABOVE_31_BIT\*(C'\fR. Similarly, |
| 29277 |
\&\f(CW\*(C`UNICODE_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named |
| 29278 |
\&\f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR. The names are misleading because on EBCDIC |
| 29279 |
platforms,these flags can apply to code points that actually do fit in 31 bits. |
| 29280 |
The new names accurately describe the situation in all cases. |
| 29281 |
.RS 4 |
| 29282 |
.Sp |
| 29283 |
.Vb 1 |
| 29284 |
\& U8 * uvchr_to_utf8_flags(U8 *d, UV uv, UV flags) |
| 29285 |
.Ve |
| 29286 |
.RE |
| 29287 |
.RS 4 |
| 29288 |
.RE |
| 29289 |
.ie n .IP """uvchr_to_utf8_flags_msgs""" 4 |
| 29290 |
.el .IP \f(CWuvchr_to_utf8_flags_msgs\fR 4 |
| 29291 |
.IX Xref "uvchr_to_utf8_flags_msgs" |
| 29292 |
.IX Item "uvchr_to_utf8_flags_msgs" |
| 29293 |
THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. |
| 29294 |
.Sp |
| 29295 |
Most code should use \f(CW\*(C`"uvchr_to_utf8_flags"()\*(C'\fR rather than call this directly. |
| 29296 |
.Sp |
| 29297 |
This function is for code that wants any warning and/or error messages to be |
| 29298 |
returned to the caller rather than be displayed. All messages that would have |
| 29299 |
been displayed if all lexical warnings are enabled will be returned. |
| 29300 |
.Sp |
| 29301 |
It is just like \f(CW"uvchr_to_utf8_flags"\fR but it takes an extra parameter |
| 29302 |
placed after all the others, \f(CW\*(C`msgs\*(C'\fR. If this parameter is 0, this function |
| 29303 |
behaves identically to \f(CW"uvchr_to_utf8_flags"\fR. Otherwise, \f(CW\*(C`msgs\*(C'\fR should |
| 29304 |
be a pointer to an \f(CW\*(C`HV *\*(C'\fR variable, in which this function creates a new HV to |
| 29305 |
contain any appropriate messages. The hash has three key-value pairs, as |
| 29306 |
follows: |
| 29307 |
.RS 4 |
| 29308 |
.ie n .IP """text""" 4 |
| 29309 |
.el .IP \f(CWtext\fR 4 |
| 29310 |
.IX Item "text" |
| 29311 |
The text of the message as a \f(CW\*(C`SVpv\*(C'\fR. |
| 29312 |
.ie n .IP """warn_categories""" 4 |
| 29313 |
.el .IP \f(CWwarn_categories\fR 4 |
| 29314 |
.IX Item "warn_categories" |
| 29315 |
The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR. |
| 29316 |
.ie n .IP """flag""" 4 |
| 29317 |
.el .IP \f(CWflag\fR 4 |
| 29318 |
.IX Item "flag" |
| 29319 |
A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR. |
| 29320 |
The bit corresponds to some bit in the \f(CW*errors\fR return value, |
| 29321 |
such as \f(CW\*(C`UNICODE_GOT_SURROGATE\*(C'\fR. |
| 29322 |
.RE |
| 29323 |
.RS 4 |
| 29324 |
.Sp |
| 29325 |
It's important to note that specifying this parameter as non-null will cause |
| 29326 |
any warnings this function would otherwise generate to be suppressed, and |
| 29327 |
instead be placed in \f(CW*msgs\fR. The caller can check the lexical warnings state |
| 29328 |
(or not) when choosing what to do with the returned messages. |
| 29329 |
.Sp |
| 29330 |
The caller, of course, is responsible for freeing any returned HV. |
| 29331 |
.Sp |
| 29332 |
.Vb 1 |
| 29333 |
\& U8 * uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV **msgs) |
| 29334 |
.Ve |
| 29335 |
.RE |
| 29336 |
.RS 4 |
| 29337 |
.RE |
| 29338 |
.ie n .IP """uvchr_to_utf8""" 4 |
| 29339 |
.el .IP \f(CWuvchr_to_utf8\fR 4 |
| 29340 |
.IX Xref "uvchr_to_utf8" |
| 29341 |
.IX Item "uvchr_to_utf8" |
| 29342 |
Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end |
| 29343 |
of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to |
| 29344 |
\&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available. The return value is the pointer to |
| 29345 |
the byte after the end of the new character. In other words, |
| 29346 |
.Sp |
| 29347 |
.Vb 1 |
| 29348 |
\& d = uvchr_to_utf8(d, uv); |
| 29349 |
.Ve |
| 29350 |
.Sp |
| 29351 |
is the recommended wide native character-aware way of saying |
| 29352 |
.Sp |
| 29353 |
.Vb 1 |
| 29354 |
\& *(d++) = uv; |
| 29355 |
.Ve |
| 29356 |
.Sp |
| 29357 |
This function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as input. |
| 29358 |
\&\f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word. |
| 29359 |
.Sp |
| 29360 |
It is possible to forbid or warn on non-Unicode code points, or those that may |
| 29361 |
be problematic by using "uvchr_to_utf8_flags". |
| 29362 |
.RS 4 |
| 29363 |
.Sp |
| 29364 |
.Vb 1 |
| 29365 |
\& U8 * uvchr_to_utf8(U8 *d, UV uv) |
| 29366 |
.Ve |
| 29367 |
.RE |
| 29368 |
.RS 4 |
| 29369 |
.RE |
| 29370 |
.SH "Utility Functions" |
| 29371 |
.IX Header "Utility Functions" |
| 29372 |
.ie n .IP """C_ARRAY_END""" 4 |
| 29373 |
.el .IP \f(CWC_ARRAY_END\fR 4 |
| 29374 |
.IX Xref "C_ARRAY_END" |
| 29375 |
.IX Item "C_ARRAY_END" |
| 29376 |
Returns a pointer to one element past the final element of the input C array. |
| 29377 |
.RS 4 |
| 29378 |
.Sp |
| 29379 |
.Vb 1 |
| 29380 |
\& void * C_ARRAY_END(void *a) |
| 29381 |
.Ve |
| 29382 |
.RE |
| 29383 |
.RS 4 |
| 29384 |
.RE |
| 29385 |
.ie n .IP """C_ARRAY_LENGTH""" 4 |
| 29386 |
.el .IP \f(CWC_ARRAY_LENGTH\fR 4 |
| 29387 |
.IX Xref "C_ARRAY_LENGTH" |
| 29388 |
.IX Item "C_ARRAY_LENGTH" |
| 29389 |
Returns the number of elements in the input C array (so you want your |
| 29390 |
zero-based indices to be less than but not equal to). |
| 29391 |
.RS 4 |
| 29392 |
.Sp |
| 29393 |
.Vb 1 |
| 29394 |
\& STRLEN C_ARRAY_LENGTH(void *a) |
| 29395 |
.Ve |
| 29396 |
.RE |
| 29397 |
.RS 4 |
| 29398 |
.RE |
| 29399 |
.ie n .IP """getcwd_sv""" 4 |
| 29400 |
.el .IP \f(CWgetcwd_sv\fR 4 |
| 29401 |
.IX Xref "getcwd_sv" |
| 29402 |
.IX Item "getcwd_sv" |
| 29403 |
Fill \f(CW\*(C`sv\*(C'\fR with current working directory |
| 29404 |
.RS 4 |
| 29405 |
.Sp |
| 29406 |
.Vb 1 |
| 29407 |
\& int getcwd_sv(SV *sv) |
| 29408 |
.Ve |
| 29409 |
.RE |
| 29410 |
.RS 4 |
| 29411 |
.RE |
| 29412 |
.ie n .IP """IN_PERL_COMPILETIME""" 4 |
| 29413 |
.el .IP \f(CWIN_PERL_COMPILETIME\fR 4 |
| 29414 |
.IX Xref "IN_PERL_COMPILETIME" |
| 29415 |
.IX Item "IN_PERL_COMPILETIME" |
| 29416 |
Returns 1 if this macro is being called during the compilation phase of the |
| 29417 |
program; otherwise 0; |
| 29418 |
.RS 4 |
| 29419 |
.Sp |
| 29420 |
.Vb 1 |
| 29421 |
\& bool IN_PERL_COMPILETIME |
| 29422 |
.Ve |
| 29423 |
.RE |
| 29424 |
.RS 4 |
| 29425 |
.RE |
| 29426 |
.ie n .IP """IN_PERL_RUNTIME""" 4 |
| 29427 |
.el .IP \f(CWIN_PERL_RUNTIME\fR 4 |
| 29428 |
.IX Xref "IN_PERL_RUNTIME" |
| 29429 |
.IX Item "IN_PERL_RUNTIME" |
| 29430 |
Returns 1 if this macro is being called during the execution phase of the |
| 29431 |
program; otherwise 0; |
| 29432 |
.RS 4 |
| 29433 |
.Sp |
| 29434 |
.Vb 1 |
| 29435 |
\& bool IN_PERL_RUNTIME |
| 29436 |
.Ve |
| 29437 |
.RE |
| 29438 |
.RS 4 |
| 29439 |
.RE |
| 29440 |
.ie n .IP """IS_SAFE_SYSCALL""" 4 |
| 29441 |
.el .IP \f(CWIS_SAFE_SYSCALL\fR 4 |
| 29442 |
.IX Xref "IS_SAFE_SYSCALL" |
| 29443 |
.IX Item "IS_SAFE_SYSCALL" |
| 29444 |
Same as "is_safe_syscall". |
| 29445 |
.RS 4 |
| 29446 |
.Sp |
| 29447 |
.Vb 2 |
| 29448 |
\& bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len, |
| 29449 |
\& NN const char *what, NN const char *op_name) |
| 29450 |
.Ve |
| 29451 |
.RE |
| 29452 |
.RS 4 |
| 29453 |
.RE |
| 29454 |
.ie n .IP """is_safe_syscall""" 4 |
| 29455 |
.el .IP \f(CWis_safe_syscall\fR 4 |
| 29456 |
.IX Xref "is_safe_syscall" |
| 29457 |
.IX Item "is_safe_syscall" |
| 29458 |
Test that the given \f(CW\*(C`pv\*(C'\fR (with length \f(CW\*(C`len\*(C'\fR) doesn't contain any internal |
| 29459 |
\&\f(CW\*(C`NUL\*(C'\fR characters. |
| 29460 |
If it does, set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`ENOENT\*(C'\fR, optionally warn using the \f(CW\*(C`syscalls\*(C'\fR |
| 29461 |
category, and return FALSE. |
| 29462 |
.Sp |
| 29463 |
Return TRUE if the name is safe. |
| 29464 |
.Sp |
| 29465 |
\&\f(CW\*(C`what\*(C'\fR and \f(CW\*(C`op_name\*(C'\fR are used in any warning. |
| 29466 |
.Sp |
| 29467 |
Used by the \f(CWIS_SAFE_SYSCALL()\fR macro. |
| 29468 |
.RS 4 |
| 29469 |
.Sp |
| 29470 |
.Vb 2 |
| 29471 |
\& bool is_safe_syscall(const char *pv, STRLEN len, |
| 29472 |
\& const char *what, const char *op_name) |
| 29473 |
.Ve |
| 29474 |
.RE |
| 29475 |
.RS 4 |
| 29476 |
.RE |
| 29477 |
.ie n .IP """my_setenv""" 4 |
| 29478 |
.el .IP \f(CWmy_setenv\fR 4 |
| 29479 |
.IX Xref "my_setenv" |
| 29480 |
.IX Item "my_setenv" |
| 29481 |
A wrapper for the C library \fBsetenv\fR\|(3). Don't use the latter, as the perl |
| 29482 |
version has desirable safeguards |
| 29483 |
.RS 4 |
| 29484 |
.Sp |
| 29485 |
.Vb 1 |
| 29486 |
\& void my_setenv(const char *nam, const char *val) |
| 29487 |
.Ve |
| 29488 |
.RE |
| 29489 |
.RS 4 |
| 29490 |
.RE |
| 29491 |
.ie n .IP """newPADxVOP""" 4 |
| 29492 |
.el .IP \f(CWnewPADxVOP\fR 4 |
| 29493 |
.IX Xref "newPADxVOP" |
| 29494 |
.IX Item "newPADxVOP" |
| 29495 |
Constructs, checks and returns an op containing a pad offset. \f(CW\*(C`type\*(C'\fR is |
| 29496 |
the opcode, which should be one of \f(CW\*(C`OP_PADSV\*(C'\fR, \f(CW\*(C`OP_PADAV\*(C'\fR, \f(CW\*(C`OP_PADHV\*(C'\fR |
| 29497 |
or \f(CW\*(C`OP_PADCV\*(C'\fR. The returned op will have the \f(CW\*(C`op_targ\*(C'\fR field set by |
| 29498 |
the \f(CW\*(C`padix\*(C'\fR argument. |
| 29499 |
.Sp |
| 29500 |
This is convenient when constructing a large optree in nested function |
| 29501 |
calls, as it avoids needing to store the pad op directly to set the |
| 29502 |
\&\f(CW\*(C`op_targ\*(C'\fR field as a side-effect. For example |
| 29503 |
.Sp |
| 29504 |
.Vb 2 |
| 29505 |
\& o = op_append_elem(OP_LINESEQ, o, |
| 29506 |
\& newPADxVOP(OP_PADSV, 0, padix)); |
| 29507 |
.Ve |
| 29508 |
.RS 4 |
| 29509 |
.Sp |
| 29510 |
.Vb 1 |
| 29511 |
\& OP * newPADxVOP(I32 type, I32 flags, PADOFFSET padix) |
| 29512 |
.Ve |
| 29513 |
.RE |
| 29514 |
.RS 4 |
| 29515 |
.RE |
| 29516 |
.ie n .IP """phase_name""" 4 |
| 29517 |
.el .IP \f(CWphase_name\fR 4 |
| 29518 |
.IX Xref "phase_name" |
| 29519 |
.IX Item "phase_name" |
| 29520 |
Returns the given phase's name as a NUL-terminated string. |
| 29521 |
.Sp |
| 29522 |
For example, to print a stack trace that includes the current |
| 29523 |
interpreter phase you might do: |
| 29524 |
.Sp |
| 29525 |
.Vb 2 |
| 29526 |
\& const char* phase_name = phase_name(PL_phase); |
| 29527 |
\& mess("This is weird. (Perl phase: %s)", phase_name); |
| 29528 |
.Ve |
| 29529 |
.RS 4 |
| 29530 |
.Sp |
| 29531 |
.Vb 1 |
| 29532 |
\& const char * const phase_name(enum perl_phase) |
| 29533 |
.Ve |
| 29534 |
.RE |
| 29535 |
.RS 4 |
| 29536 |
.RE |
| 29537 |
.ie n .IP """Poison""" 4 |
| 29538 |
.el .IP \f(CWPoison\fR 4 |
| 29539 |
.IX Xref "Poison" |
| 29540 |
.IX Item "Poison" |
| 29541 |
PoisonWith(0xEF) for catching access to freed memory. |
| 29542 |
.RS 4 |
| 29543 |
.Sp |
| 29544 |
.Vb 1 |
| 29545 |
\& void Poison(void* dest, int nitems, type) |
| 29546 |
.Ve |
| 29547 |
.RE |
| 29548 |
.RS 4 |
| 29549 |
.RE |
| 29550 |
.ie n .IP """PoisonFree""" 4 |
| 29551 |
.el .IP \f(CWPoisonFree\fR 4 |
| 29552 |
.IX Xref "PoisonFree" |
| 29553 |
.IX Item "PoisonFree" |
| 29554 |
PoisonWith(0xEF) for catching access to freed memory. |
| 29555 |
.RS 4 |
| 29556 |
.Sp |
| 29557 |
.Vb 1 |
| 29558 |
\& void PoisonFree(void* dest, int nitems, type) |
| 29559 |
.Ve |
| 29560 |
.RE |
| 29561 |
.RS 4 |
| 29562 |
.RE |
| 29563 |
.ie n .IP """PoisonNew""" 4 |
| 29564 |
.el .IP \f(CWPoisonNew\fR 4 |
| 29565 |
.IX Xref "PoisonNew" |
| 29566 |
.IX Item "PoisonNew" |
| 29567 |
PoisonWith(0xAB) for catching access to allocated but uninitialized memory. |
| 29568 |
.RS 4 |
| 29569 |
.Sp |
| 29570 |
.Vb 1 |
| 29571 |
\& void PoisonNew(void* dest, int nitems, type) |
| 29572 |
.Ve |
| 29573 |
.RE |
| 29574 |
.RS 4 |
| 29575 |
.RE |
| 29576 |
.ie n .IP """PoisonWith""" 4 |
| 29577 |
.el .IP \f(CWPoisonWith\fR 4 |
| 29578 |
.IX Xref "PoisonWith" |
| 29579 |
.IX Item "PoisonWith" |
| 29580 |
Fill up memory with a byte pattern (a byte repeated over and over |
| 29581 |
again) that hopefully catches attempts to access uninitialized memory. |
| 29582 |
.RS 4 |
| 29583 |
.Sp |
| 29584 |
.Vb 1 |
| 29585 |
\& void PoisonWith(void* dest, int nitems, type, U8 byte) |
| 29586 |
.Ve |
| 29587 |
.RE |
| 29588 |
.RS 4 |
| 29589 |
.RE |
| 29590 |
.ie n .IP """StructCopy""" 4 |
| 29591 |
.el .IP \f(CWStructCopy\fR 4 |
| 29592 |
.IX Xref "StructCopy" |
| 29593 |
.IX Item "StructCopy" |
| 29594 |
This is an architecture-independent macro that does a shallow copy of one |
| 29595 |
structure to another. |
| 29596 |
.RS 4 |
| 29597 |
.Sp |
| 29598 |
.Vb 1 |
| 29599 |
\& void StructCopy(type *src, type *dest, type) |
| 29600 |
.Ve |
| 29601 |
.RE |
| 29602 |
.RS 4 |
| 29603 |
.RE |
| 29604 |
.ie n .IP """sv_destroyable""" 4 |
| 29605 |
.el .IP \f(CWsv_destroyable\fR 4 |
| 29606 |
.IX Xref "sv_destroyable" |
| 29607 |
.IX Item "sv_destroyable" |
| 29608 |
Dummy routine which reports that object can be destroyed when there is no |
| 29609 |
sharing module present. It ignores its single SV argument, and returns |
| 29610 |
\&'true'. Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it |
| 29611 |
could potentially warn under some level of strict-ness. |
| 29612 |
.RS 4 |
| 29613 |
.Sp |
| 29614 |
.Vb 1 |
| 29615 |
\& bool sv_destroyable(SV *sv) |
| 29616 |
.Ve |
| 29617 |
.RE |
| 29618 |
.RS 4 |
| 29619 |
.RE |
| 29620 |
.ie n .IP """sv_nosharing""" 4 |
| 29621 |
.el .IP \f(CWsv_nosharing\fR 4 |
| 29622 |
.IX Xref "sv_nosharing" |
| 29623 |
.IX Item "sv_nosharing" |
| 29624 |
Dummy routine which "shares" an SV when there is no sharing module present. |
| 29625 |
Or "locks" it. Or "unlocks" it. In other |
| 29626 |
words, ignores its single SV argument. |
| 29627 |
Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could |
| 29628 |
potentially warn under some level of strict-ness. |
| 29629 |
.RS 4 |
| 29630 |
.Sp |
| 29631 |
.Vb 1 |
| 29632 |
\& void sv_nosharing(SV *sv) |
| 29633 |
.Ve |
| 29634 |
.RE |
| 29635 |
.RS 4 |
| 29636 |
.RE |
| 29637 |
.SH Versioning |
| 29638 |
.IX Header "Versioning" |
| 29639 |
.ie n .IP """new_version""" 4 |
| 29640 |
.el .IP \f(CWnew_version\fR 4 |
| 29641 |
.IX Xref "new_version" |
| 29642 |
.IX Item "new_version" |
| 29643 |
Returns a new version object based on the passed in SV: |
| 29644 |
.Sp |
| 29645 |
.Vb 1 |
| 29646 |
\& SV *sv = new_version(SV *ver); |
| 29647 |
.Ve |
| 29648 |
.Sp |
| 29649 |
Does not alter the passed in ver SV. See "upg_version" if you |
| 29650 |
want to upgrade the SV. |
| 29651 |
.RS 4 |
| 29652 |
.Sp |
| 29653 |
.Vb 1 |
| 29654 |
\& SV * new_version(SV *ver) |
| 29655 |
.Ve |
| 29656 |
.RE |
| 29657 |
.RS 4 |
| 29658 |
.RE |
| 29659 |
.ie n .IP """PERL_REVISION""" 4 |
| 29660 |
.el .IP \f(CWPERL_REVISION\fR 4 |
| 29661 |
.IX Xref "PERL_REVISION" |
| 29662 |
.IX Item "PERL_REVISION" |
| 29663 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_REVISION\*(C'\fR |
| 29664 |
from a future release of Perl. Do not use it for |
| 29665 |
new code; remove it from existing code. |
| 29666 |
.Sp |
| 29667 |
The major number component of the perl interpreter currently being compiled or |
| 29668 |
executing. This has been \f(CW5\fR from 1993 into 2020. |
| 29669 |
.Sp |
| 29670 |
Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR. |
| 29671 |
.ie n .IP """PERL_SUBVERSION""" 4 |
| 29672 |
.el .IP \f(CWPERL_SUBVERSION\fR 4 |
| 29673 |
.IX Xref "PERL_SUBVERSION" |
| 29674 |
.IX Item "PERL_SUBVERSION" |
| 29675 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_SUBVERSION\*(C'\fR |
| 29676 |
from a future release of Perl. Do not use it for |
| 29677 |
new code; remove it from existing code. |
| 29678 |
.Sp |
| 29679 |
The micro number component of the perl interpreter currently being compiled or |
| 29680 |
executing. In stable releases this gives the dot release number for |
| 29681 |
maintenance updates. In development releases this gives a tag for a snapshot |
| 29682 |
of the status at various points in the development cycle. |
| 29683 |
.Sp |
| 29684 |
Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR. |
| 29685 |
.ie n .IP """PERL_VERSION""" 4 |
| 29686 |
.el .IP \f(CWPERL_VERSION\fR 4 |
| 29687 |
.IX Xref "PERL_VERSION" |
| 29688 |
.IX Item "PERL_VERSION" |
| 29689 |
\&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_VERSION\*(C'\fR |
| 29690 |
from a future release of Perl. Do not use it for |
| 29691 |
new code; remove it from existing code. |
| 29692 |
.Sp |
| 29693 |
The minor number component of the perl interpreter currently being compiled or |
| 29694 |
executing. Between 1993 into 2020, this has ranged from 0 to 33. |
| 29695 |
.Sp |
| 29696 |
Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR. |
| 29697 |
.ie n .IP """PERL_VERSION_EQ""" 4 |
| 29698 |
.el .IP \f(CWPERL_VERSION_EQ\fR 4 |
| 29699 |
.IX Item "PERL_VERSION_EQ" |
| 29700 |
.PD 0 |
| 29701 |
.ie n .IP """PERL_VERSION_GE""" 4 |
| 29702 |
.el .IP \f(CWPERL_VERSION_GE\fR 4 |
| 29703 |
.IX Item "PERL_VERSION_GE" |
| 29704 |
.ie n .IP """PERL_VERSION_GT""" 4 |
| 29705 |
.el .IP \f(CWPERL_VERSION_GT\fR 4 |
| 29706 |
.IX Item "PERL_VERSION_GT" |
| 29707 |
.ie n .IP """PERL_VERSION_LE""" 4 |
| 29708 |
.el .IP \f(CWPERL_VERSION_LE\fR 4 |
| 29709 |
.IX Item "PERL_VERSION_LE" |
| 29710 |
.ie n .IP """PERL_VERSION_LT""" 4 |
| 29711 |
.el .IP \f(CWPERL_VERSION_LT\fR 4 |
| 29712 |
.IX Item "PERL_VERSION_LT" |
| 29713 |
.ie n .IP """PERL_VERSION_NE""" 4 |
| 29714 |
.el .IP \f(CWPERL_VERSION_NE\fR 4 |
| 29715 |
.IX Xref "PERL_VERSION_EQ PERL_VERSION_GE PERL_VERSION_GT PERL_VERSION_LE PERL_VERSION_LT PERL_VERSION_NE" |
| 29716 |
.IX Item "PERL_VERSION_NE" |
| 29717 |
.PD |
| 29718 |
Returns whether or not the perl currently being compiled has the specified |
| 29719 |
relationship to the perl given by the parameters. For example, |
| 29720 |
.Sp |
| 29721 |
.Vb 5 |
| 29722 |
\& #if PERL_VERSION_GT(5,24,2) |
| 29723 |
\& code that will only be compiled on perls after v5.24.2 |
| 29724 |
\& #else |
| 29725 |
\& fallback code |
| 29726 |
\& #endif |
| 29727 |
.Ve |
| 29728 |
.Sp |
| 29729 |
Note that this is usable in making compile-time decisions |
| 29730 |
.Sp |
| 29731 |
You may use the special value '*' for the final number to mean ALL possible |
| 29732 |
values for it. Thus, |
| 29733 |
.Sp |
| 29734 |
.Vb 1 |
| 29735 |
\& #if PERL_VERSION_EQ(5,31,\*(Aq*\*(Aq) |
| 29736 |
.Ve |
| 29737 |
.Sp |
| 29738 |
means all perls in the 5.31 series. And |
| 29739 |
.Sp |
| 29740 |
.Vb 1 |
| 29741 |
\& #if PERL_VERSION_NE(5,24,\*(Aq*\*(Aq) |
| 29742 |
.Ve |
| 29743 |
.Sp |
| 29744 |
means all perls EXCEPT 5.24 ones. And |
| 29745 |
.Sp |
| 29746 |
.Vb 1 |
| 29747 |
\& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq) |
| 29748 |
.Ve |
| 29749 |
.Sp |
| 29750 |
is effectively |
| 29751 |
.Sp |
| 29752 |
.Vb 1 |
| 29753 |
\& #if PERL_VERSION_LT(5,10,0) |
| 29754 |
.Ve |
| 29755 |
.Sp |
| 29756 |
This means you don't have to think so much when converting from the existing |
| 29757 |
deprecated \f(CW\*(C`PERL_VERSION\*(C'\fR to using this macro: |
| 29758 |
.Sp |
| 29759 |
.Vb 1 |
| 29760 |
\& #if PERL_VERSION <= 9 |
| 29761 |
.Ve |
| 29762 |
.Sp |
| 29763 |
becomes |
| 29764 |
.Sp |
| 29765 |
.Vb 1 |
| 29766 |
\& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq) |
| 29767 |
.Ve |
| 29768 |
.RS 4 |
| 29769 |
.Sp |
| 29770 |
.Vb 2 |
| 29771 |
\& bool PERL_VERSION_EQ(const U8 major, const U8 minor, |
| 29772 |
\& const U8 patch) |
| 29773 |
.Ve |
| 29774 |
.RE |
| 29775 |
.RS 4 |
| 29776 |
.RE |
| 29777 |
.ie n .IP """prescan_version""" 4 |
| 29778 |
.el .IP \f(CWprescan_version\fR 4 |
| 29779 |
.IX Xref "prescan_version" |
| 29780 |
.IX Item "prescan_version" |
| 29781 |
Validate that a given string can be parsed as a version object, but doesn't |
| 29782 |
actually perform the parsing. Can use either strict or lax validation rules. |
| 29783 |
Can optionally set a number of hint variables to save the parsing code |
| 29784 |
some time when tokenizing. |
| 29785 |
.RS 4 |
| 29786 |
.Sp |
| 29787 |
.Vb 4 |
| 29788 |
\& const char * prescan_version(const char *s, bool strict, |
| 29789 |
\& const char **errstr, bool *sqv, |
| 29790 |
\& int *ssaw_decimal, int *swidth, |
| 29791 |
\& bool *salpha) |
| 29792 |
.Ve |
| 29793 |
.RE |
| 29794 |
.RS 4 |
| 29795 |
.RE |
| 29796 |
.ie n .IP """scan_version""" 4 |
| 29797 |
.el .IP \f(CWscan_version\fR 4 |
| 29798 |
.IX Xref "scan_version" |
| 29799 |
.IX Item "scan_version" |
| 29800 |
Returns a pointer to the next character after the parsed |
| 29801 |
version string, as well as upgrading the passed in SV to |
| 29802 |
an RV. |
| 29803 |
.Sp |
| 29804 |
Function must be called with an already existing SV like |
| 29805 |
.Sp |
| 29806 |
.Vb 2 |
| 29807 |
\& sv = newSV(0); |
| 29808 |
\& s = scan_version(s, SV *sv, bool qv); |
| 29809 |
.Ve |
| 29810 |
.Sp |
| 29811 |
Performs some preprocessing to the string to ensure that |
| 29812 |
it has the correct characteristics of a version. Flags the |
| 29813 |
object if it contains an underscore (which denotes this |
| 29814 |
is an alpha version). The boolean qv denotes that the version |
| 29815 |
should be interpreted as if it had multiple decimals, even if |
| 29816 |
it doesn't. |
| 29817 |
.RS 4 |
| 29818 |
.Sp |
| 29819 |
.Vb 1 |
| 29820 |
\& const char * scan_version(const char *s, SV *rv, bool qv) |
| 29821 |
.Ve |
| 29822 |
.RE |
| 29823 |
.RS 4 |
| 29824 |
.RE |
| 29825 |
.ie n .IP """upg_version""" 4 |
| 29826 |
.el .IP \f(CWupg_version\fR 4 |
| 29827 |
.IX Xref "upg_version" |
| 29828 |
.IX Item "upg_version" |
| 29829 |
In-place upgrade of the supplied SV to a version object. |
| 29830 |
.Sp |
| 29831 |
.Vb 1 |
| 29832 |
\& SV *sv = upg_version(SV *sv, bool qv); |
| 29833 |
.Ve |
| 29834 |
.Sp |
| 29835 |
Returns a pointer to the upgraded SV. Set the boolean qv if you want |
| 29836 |
to force this SV to be interpreted as an "extended" version. |
| 29837 |
.RS 4 |
| 29838 |
.Sp |
| 29839 |
.Vb 1 |
| 29840 |
\& SV * upg_version(SV *ver, bool qv) |
| 29841 |
.Ve |
| 29842 |
.RE |
| 29843 |
.RS 4 |
| 29844 |
.RE |
| 29845 |
.ie n .IP """vcmp""" 4 |
| 29846 |
.el .IP \f(CWvcmp\fR 4 |
| 29847 |
.IX Xref "vcmp" |
| 29848 |
.IX Item "vcmp" |
| 29849 |
Version object aware cmp. Both operands must already have been |
| 29850 |
converted into version objects. |
| 29851 |
.RS 4 |
| 29852 |
.Sp |
| 29853 |
.Vb 1 |
| 29854 |
\& int vcmp(SV *lhv, SV *rhv) |
| 29855 |
.Ve |
| 29856 |
.RE |
| 29857 |
.RS 4 |
| 29858 |
.RE |
| 29859 |
.ie n .IP """vnormal""" 4 |
| 29860 |
.el .IP \f(CWvnormal\fR 4 |
| 29861 |
.IX Xref "vnormal" |
| 29862 |
.IX Item "vnormal" |
| 29863 |
Accepts a version object and returns the normalized string |
| 29864 |
representation. Call like: |
| 29865 |
.Sp |
| 29866 |
.Vb 1 |
| 29867 |
\& sv = vnormal(rv); |
| 29868 |
.Ve |
| 29869 |
.Sp |
| 29870 |
NOTE: you can pass either the object directly or the SV |
| 29871 |
contained within the RV. |
| 29872 |
.Sp |
| 29873 |
The SV returned has a refcount of 1. |
| 29874 |
.RS 4 |
| 29875 |
.Sp |
| 29876 |
.Vb 1 |
| 29877 |
\& SV * vnormal(SV *vs) |
| 29878 |
.Ve |
| 29879 |
.RE |
| 29880 |
.RS 4 |
| 29881 |
.RE |
| 29882 |
.ie n .IP """vnumify""" 4 |
| 29883 |
.el .IP \f(CWvnumify\fR 4 |
| 29884 |
.IX Xref "vnumify" |
| 29885 |
.IX Item "vnumify" |
| 29886 |
Accepts a version object and returns the normalized floating |
| 29887 |
point representation. Call like: |
| 29888 |
.Sp |
| 29889 |
.Vb 1 |
| 29890 |
\& sv = vnumify(rv); |
| 29891 |
.Ve |
| 29892 |
.Sp |
| 29893 |
NOTE: you can pass either the object directly or the SV |
| 29894 |
contained within the RV. |
| 29895 |
.Sp |
| 29896 |
The SV returned has a refcount of 1. |
| 29897 |
.RS 4 |
| 29898 |
.Sp |
| 29899 |
.Vb 1 |
| 29900 |
\& SV * vnumify(SV *vs) |
| 29901 |
.Ve |
| 29902 |
.RE |
| 29903 |
.RS 4 |
| 29904 |
.RE |
| 29905 |
.ie n .IP """vstringify""" 4 |
| 29906 |
.el .IP \f(CWvstringify\fR 4 |
| 29907 |
.IX Xref "vstringify" |
| 29908 |
.IX Item "vstringify" |
| 29909 |
In order to maintain maximum compatibility with earlier versions |
| 29910 |
of Perl, this function will return either the floating point |
| 29911 |
notation or the multiple dotted notation, depending on whether |
| 29912 |
the original version contained 1 or more dots, respectively. |
| 29913 |
.Sp |
| 29914 |
The SV returned has a refcount of 1. |
| 29915 |
.RS 4 |
| 29916 |
.Sp |
| 29917 |
.Vb 1 |
| 29918 |
\& SV * vstringify(SV *vs) |
| 29919 |
.Ve |
| 29920 |
.RE |
| 29921 |
.RS 4 |
| 29922 |
.RE |
| 29923 |
.ie n .IP """vverify""" 4 |
| 29924 |
.el .IP \f(CWvverify\fR 4 |
| 29925 |
.IX Xref "vverify" |
| 29926 |
.IX Item "vverify" |
| 29927 |
Validates that the SV contains valid internal structure for a version object. |
| 29928 |
It may be passed either the version object (RV) or the hash itself (HV). If |
| 29929 |
the structure is valid, it returns the HV. If the structure is invalid, |
| 29930 |
it returns NULL. |
| 29931 |
.Sp |
| 29932 |
.Vb 1 |
| 29933 |
\& SV *hv = vverify(sv); |
| 29934 |
.Ve |
| 29935 |
.Sp |
| 29936 |
Note that it only confirms the bare minimum structure (so as not to get |
| 29937 |
confused by derived classes which may contain additional hash entries): |
| 29938 |
.RS 4 |
| 29939 |
.IP \(bu 4 |
| 29940 |
The SV is an HV or a reference to an HV |
| 29941 |
.IP \(bu 4 |
| 29942 |
The hash contains a "version" key |
| 29943 |
.IP \(bu 4 |
| 29944 |
The "version" key has a reference to an AV as its value |
| 29945 |
.RE |
| 29946 |
.RS 4 |
| 29947 |
.Sp |
| 29948 |
.Vb 1 |
| 29949 |
\& SV * vverify(SV *vs) |
| 29950 |
.Ve |
| 29951 |
.RE |
| 29952 |
.RS 4 |
| 29953 |
.RE |
| 29954 |
.SH "Warning and Dieing" |
| 29955 |
.IX Xref "WARN_ALL WARN_AMBIGUOUS WARN_BAREWORD WARN_CLOSED WARN_CLOSURE WARN_DEBUGGING WARN_DEPRECATED WARN_DEPRECATED__APOSTROPHE_AS_PACKAGE_SEPARATOR WARN_DEPRECATED__DELIMITER_WILL_BE_PAIRED WARN_DEPRECATED__DOT_IN_INC WARN_DEPRECATED__GOTO_CONSTRUCT WARN_DEPRECATED__MISSING_IMPORT_CALLED_WITH_ARGS WARN_DEPRECATED__SMARTMATCH WARN_DEPRECATED__SUBSEQUENT_USE_VERSION WARN_DEPRECATED__UNICODE_PROPERTY_NAME WARN_DEPRECATED__VERSION_DOWNGRADE WARN_DIGIT WARN_EXEC WARN_EXITING WARN_EXPERIMENTAL WARN_EXPERIMENTAL__ARGS_ARRAY_WITH_SIGNATURES WARN_EXPERIMENTAL__BUILTIN WARN_EXPERIMENTAL__CLASS WARN_EXPERIMENTAL__DECLARED_REFS WARN_EXPERIMENTAL__DEFER WARN_EXPERIMENTAL__EXTRA_PAIRED_DELIMITERS WARN_EXPERIMENTAL__PRIVATE_USE WARN_EXPERIMENTAL__REFALIASING WARN_EXPERIMENTAL__REGEX_SETS WARN_EXPERIMENTAL__RE_STRICT WARN_EXPERIMENTAL__TRY WARN_EXPERIMENTAL__UNIPROP_WILDCARDS WARN_EXPERIMENTAL__VLB WARN_GLOB WARN_ILLEGALPROTO WARN_IMPRECISION WARN_INPLACE WARN_INTERNAL WARN_IO WARN_LAYER WARN_LOCALE WARN_MALLOC WARN_MISC WARN_MISSING WARN_NEWLINE WARN_NONCHAR WARN_NON_UNICODE WARN_NUMERIC WARN_ONCE WARN_OVERFLOW WARN_PACK WARN_PARENTHESIS WARN_PIPE WARN_PORTABLE WARN_PRECEDENCE WARN_PRINTF WARN_PROTOTYPE WARN_QW WARN_RECURSION WARN_REDEFINE WARN_REDUNDANT WARN_REGEXP WARN_RESERVED WARN_SCALAR WARN_SEMICOLON WARN_SEVERE WARN_SHADOW WARN_SIGNAL WARN_SUBSTR WARN_SURROGATE WARN_SYNTAX WARN_SYSCALLS WARN_TAINT WARN_THREADS WARN_UNINITIALIZED WARN_UNOPENED WARN_UNPACK WARN_UNTIE WARN_UTF8 WARN_VOID" |
| 29956 |
.IX Header "Warning and Dieing" |
| 29957 |
In all these calls, the \f(CW\*(C`U32 w\fR\f(CIn\fR\f(CW\*(C'\fR parameters are warning category |
| 29958 |
constants. You can see the ones currently available in |
| 29959 |
"Category Hierarchy" in warnings, just capitalize all letters in the names |
| 29960 |
and prefix them by \f(CW\*(C`WARN_\*(C'\fR. So, for example, the category \f(CW\*(C`void\*(C'\fR used in a |
| 29961 |
perl program becomes \f(CW\*(C`WARN_VOID\*(C'\fR when used in XS code and passed to one of |
| 29962 |
the calls below. |
| 29963 |
.ie n .IP """ckWARN""" 4 |
| 29964 |
.el .IP \f(CWckWARN\fR 4 |
| 29965 |
.IX Item "ckWARN" |
| 29966 |
.PD 0 |
| 29967 |
.ie n .IP """ckWARN2""" 4 |
| 29968 |
.el .IP \f(CWckWARN2\fR 4 |
| 29969 |
.IX Item "ckWARN2" |
| 29970 |
.ie n .IP """ckWARN3""" 4 |
| 29971 |
.el .IP \f(CWckWARN3\fR 4 |
| 29972 |
.IX Item "ckWARN3" |
| 29973 |
.ie n .IP """ckWARN4""" 4 |
| 29974 |
.el .IP \f(CWckWARN4\fR 4 |
| 29975 |
.IX Xref "ckWARN ckWARN2 ckWARN3 ckWARN4" |
| 29976 |
.IX Item "ckWARN4" |
| 29977 |
.PD |
| 29978 |
These return a boolean as to whether or not warnings are enabled for any of |
| 29979 |
the warning category(ies) parameters: \f(CW\*(C`w\*(C'\fR, \f(CW\*(C`w1\*(C'\fR, .... |
| 29980 |
.Sp |
| 29981 |
Should any of the categories by default be enabled even if not within the |
| 29982 |
scope of \f(CW\*(C`use\ warnings\*(C'\fR, instead use the \f(CW"ckWARN_d"\fR macros. |
| 29983 |
.Sp |
| 29984 |
The categories must be completely independent, one may not be subclassed from |
| 29985 |
the other. |
| 29986 |
.RS 4 |
| 29987 |
.Sp |
| 29988 |
.Vb 4 |
| 29989 |
\& bool ckWARN (U32 w) |
| 29990 |
\& bool ckWARN2(U32 w1, U32 w2) |
| 29991 |
\& bool ckWARN3(U32 w1, U32 w2, U32 w3) |
| 29992 |
\& bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4) |
| 29993 |
.Ve |
| 29994 |
.RE |
| 29995 |
.RS 4 |
| 29996 |
.RE |
| 29997 |
.ie n .IP """ckWARN_d""" 4 |
| 29998 |
.el .IP \f(CWckWARN_d\fR 4 |
| 29999 |
.IX Item "ckWARN_d" |
| 30000 |
.PD 0 |
| 30001 |
.ie n .IP """ckWARN2_d""" 4 |
| 30002 |
.el .IP \f(CWckWARN2_d\fR 4 |
| 30003 |
.IX Item "ckWARN2_d" |
| 30004 |
.ie n .IP """ckWARN3_d""" 4 |
| 30005 |
.el .IP \f(CWckWARN3_d\fR 4 |
| 30006 |
.IX Item "ckWARN3_d" |
| 30007 |
.ie n .IP """ckWARN4_d""" 4 |
| 30008 |
.el .IP \f(CWckWARN4_d\fR 4 |
| 30009 |
.IX Xref "ckWARN_d ckWARN2_d ckWARN3_d ckWARN4_d" |
| 30010 |
.IX Item "ckWARN4_d" |
| 30011 |
.PD |
| 30012 |
Like \f(CW"ckWARN"\fR, but for use if and only if the warning category(ies) is by |
| 30013 |
default enabled even if not within the scope of \f(CW\*(C`use\ warnings\*(C'\fR. |
| 30014 |
.RS 4 |
| 30015 |
.Sp |
| 30016 |
.Vb 4 |
| 30017 |
\& bool ckWARN_d (U32 w) |
| 30018 |
\& bool ckWARN2_d(U32 w1, U32 w2) |
| 30019 |
\& bool ckWARN3_d(U32 w1, U32 w2, U32 w3) |
| 30020 |
\& bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4) |
| 30021 |
.Ve |
| 30022 |
.RE |
| 30023 |
.RS 4 |
| 30024 |
.RE |
| 30025 |
.ie n .IP """ck_warner""" 4 |
| 30026 |
.el .IP \f(CWck_warner\fR 4 |
| 30027 |
.IX Item "ck_warner" |
| 30028 |
.PD 0 |
| 30029 |
.ie n .IP """ck_warner_d""" 4 |
| 30030 |
.el .IP \f(CWck_warner_d\fR 4 |
| 30031 |
.IX Xref "ck_warner ck_warner_d" |
| 30032 |
.IX Item "ck_warner_d" |
| 30033 |
.PD |
| 30034 |
If none of the warning categories given by \f(CW\*(C`err\*(C'\fR are enabled, do nothing; |
| 30035 |
otherwise call \f(CW"warner"\fR or \f(CW"warner_nocontext"\fR with the passed-in |
| 30036 |
parameters;. |
| 30037 |
.Sp |
| 30038 |
\&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR, |
| 30039 |
\&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning |
| 30040 |
categories. |
| 30041 |
.Sp |
| 30042 |
The two forms differ only in that \f(CW\*(C`ck_warner_d\*(C'\fR should be used if warnings for |
| 30043 |
any of the categories are by default enabled. |
| 30044 |
.Sp |
| 30045 |
NOTE: \f(CW\*(C`ck_warner\*(C'\fR must be explicitly called as |
| 30046 |
\&\f(CW\*(C`Perl_ck_warner\*(C'\fR |
| 30047 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30048 |
.Sp |
| 30049 |
NOTE: \f(CW\*(C`ck_warner_d\*(C'\fR must be explicitly called as |
| 30050 |
\&\f(CW\*(C`Perl_ck_warner_d\*(C'\fR |
| 30051 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30052 |
.RS 4 |
| 30053 |
.Sp |
| 30054 |
.Vb 1 |
| 30055 |
\& void Perl_ck_warner(pTHX_ U32 err, const char *pat, ...) |
| 30056 |
.Ve |
| 30057 |
.RE |
| 30058 |
.RS 4 |
| 30059 |
.RE |
| 30060 |
.ie n .IP """CLEAR_ERRSV""" 4 |
| 30061 |
.el .IP \f(CWCLEAR_ERRSV\fR 4 |
| 30062 |
.IX Xref "CLEAR_ERRSV" |
| 30063 |
.IX Item "CLEAR_ERRSV" |
| 30064 |
Clear the contents of \f(CW$@\fR, setting it to the empty string. |
| 30065 |
.Sp |
| 30066 |
This replaces any read-only SV with a fresh SV and removes any magic. |
| 30067 |
.RS 4 |
| 30068 |
.Sp |
| 30069 |
.Vb 1 |
| 30070 |
\& void CLEAR_ERRSV() |
| 30071 |
.Ve |
| 30072 |
.RE |
| 30073 |
.RS 4 |
| 30074 |
.RE |
| 30075 |
.ie n .IP """croak""" 4 |
| 30076 |
.el .IP \f(CWcroak\fR 4 |
| 30077 |
.IX Item "croak" |
| 30078 |
.PD 0 |
| 30079 |
.ie n .IP """croak_nocontext""" 4 |
| 30080 |
.el .IP \f(CWcroak_nocontext\fR 4 |
| 30081 |
.IX Xref "croak croak_nocontext" |
| 30082 |
.IX Item "croak_nocontext" |
| 30083 |
.PD |
| 30084 |
These are XS interfaces to Perl's \f(CW\*(C`die\*(C'\fR function. |
| 30085 |
.Sp |
| 30086 |
They take a sprintf-style format pattern and argument list, which are used to |
| 30087 |
generate a string message. If the message does not end with a newline, then it |
| 30088 |
will be extended with some indication of the current location in the code, as |
| 30089 |
described for \f(CW"mess_sv"\fR. |
| 30090 |
.Sp |
| 30091 |
The error message will be used as an exception, by default |
| 30092 |
returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to |
| 30093 |
modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, these croak |
| 30094 |
functions never return normally. |
| 30095 |
.Sp |
| 30096 |
For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR |
| 30097 |
(\f(CW$@\fR) will be used as an error message or object instead of building an |
| 30098 |
error message from arguments. If you want to throw a non-string object, |
| 30099 |
or build an error message in an SV yourself, it is preferable to use |
| 30100 |
the \f(CW"croak_sv"\fR function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR. |
| 30101 |
.Sp |
| 30102 |
The two forms differ only in that \f(CW\*(C`croak_nocontext\*(C'\fR does not take a thread |
| 30103 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter. It is usually preferred as it takes up fewer |
| 30104 |
bytes of code than plain \f(CW\*(C`Perl_croak\*(C'\fR, and time is rarely a critical resource |
| 30105 |
when you are about to throw an exception. |
| 30106 |
.Sp |
| 30107 |
NOTE: \f(CW\*(C`croak\*(C'\fR must be explicitly called as |
| 30108 |
\&\f(CW\*(C`Perl_croak\*(C'\fR |
| 30109 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30110 |
.RS 4 |
| 30111 |
.Sp |
| 30112 |
.Vb 2 |
| 30113 |
\& void Perl_croak (pTHX_ const char *pat, ...) |
| 30114 |
\& void croak_nocontext(const char *pat, ...) |
| 30115 |
.Ve |
| 30116 |
.RE |
| 30117 |
.RS 4 |
| 30118 |
.RE |
| 30119 |
.ie n .IP """croak_no_modify""" 4 |
| 30120 |
.el .IP \f(CWcroak_no_modify\fR 4 |
| 30121 |
.IX Xref "croak_no_modify" |
| 30122 |
.IX Item "croak_no_modify" |
| 30123 |
This encapsulates a common reason for dying, generating terser object code than |
| 30124 |
using the generic \f(CW\*(C`Perl_croak\*(C'\fR. It is exactly equivalent to |
| 30125 |
\&\f(CW\*(C`Perl_croak(aTHX_ "%s", PL_no_modify)\*(C'\fR (which expands to something like |
| 30126 |
"Modification of a read-only value attempted"). |
| 30127 |
.Sp |
| 30128 |
Less code used on exception code paths reduces CPU cache pressure. |
| 30129 |
.RS 4 |
| 30130 |
.Sp |
| 30131 |
.Vb 1 |
| 30132 |
\& void croak_no_modify() |
| 30133 |
.Ve |
| 30134 |
.RE |
| 30135 |
.RS 4 |
| 30136 |
.RE |
| 30137 |
.ie n .IP """croak_sv""" 4 |
| 30138 |
.el .IP \f(CWcroak_sv\fR 4 |
| 30139 |
.IX Xref "croak_sv" |
| 30140 |
.IX Item "croak_sv" |
| 30141 |
This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function. |
| 30142 |
.Sp |
| 30143 |
\&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it |
| 30144 |
will be used as-is. Otherwise it is used as a string, and if it does |
| 30145 |
not end with a newline then it will be extended with some indication of |
| 30146 |
the current location in the code, as described for "mess_sv". |
| 30147 |
.Sp |
| 30148 |
The error message or object will be used as an exception, by default |
| 30149 |
returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to |
| 30150 |
modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak_sv\*(C'\fR |
| 30151 |
function never returns normally. |
| 30152 |
.Sp |
| 30153 |
To die with a simple string message, the "croak" function may be |
| 30154 |
more convenient. |
| 30155 |
.RS 4 |
| 30156 |
.Sp |
| 30157 |
.Vb 1 |
| 30158 |
\& void croak_sv(SV *baseex) |
| 30159 |
.Ve |
| 30160 |
.RE |
| 30161 |
.RS 4 |
| 30162 |
.RE |
| 30163 |
.ie n .IP """die""" 4 |
| 30164 |
.el .IP \f(CWdie\fR 4 |
| 30165 |
.IX Item "die" |
| 30166 |
.PD 0 |
| 30167 |
.ie n .IP """die_nocontext""" 4 |
| 30168 |
.el .IP \f(CWdie_nocontext\fR 4 |
| 30169 |
.IX Xref "die die_nocontext" |
| 30170 |
.IX Item "die_nocontext" |
| 30171 |
.PD |
| 30172 |
These behave the same as "croak", except for the return type. |
| 30173 |
They should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required. |
| 30174 |
They never actually return. |
| 30175 |
.Sp |
| 30176 |
The two forms differ only in that \f(CW\*(C`die_nocontext\*(C'\fR does not take a thread |
| 30177 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 30178 |
already have the thread context. |
| 30179 |
.Sp |
| 30180 |
NOTE: \f(CW\*(C`die\*(C'\fR must be explicitly called as |
| 30181 |
\&\f(CW\*(C`Perl_die\*(C'\fR |
| 30182 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30183 |
.RS 4 |
| 30184 |
.Sp |
| 30185 |
.Vb 2 |
| 30186 |
\& OP * Perl_die (pTHX_ const char *pat, ...) |
| 30187 |
\& OP * die_nocontext(const char *pat, ...) |
| 30188 |
.Ve |
| 30189 |
.RE |
| 30190 |
.RS 4 |
| 30191 |
.RE |
| 30192 |
.ie n .IP """die_sv""" 4 |
| 30193 |
.el .IP \f(CWdie_sv\fR 4 |
| 30194 |
.IX Xref "die_sv" |
| 30195 |
.IX Item "die_sv" |
| 30196 |
This behaves the same as "croak_sv", except for the return type. |
| 30197 |
It should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required. |
| 30198 |
The function never actually returns. |
| 30199 |
.RS 4 |
| 30200 |
.Sp |
| 30201 |
.Vb 1 |
| 30202 |
\& OP * die_sv(SV *baseex) |
| 30203 |
.Ve |
| 30204 |
.RE |
| 30205 |
.RS 4 |
| 30206 |
.RE |
| 30207 |
.ie n .IP """ERRSV""" 4 |
| 30208 |
.el .IP \f(CWERRSV\fR 4 |
| 30209 |
.IX Xref "ERRSV" |
| 30210 |
.IX Item "ERRSV" |
| 30211 |
Returns the SV for \f(CW$@\fR, creating it if needed. |
| 30212 |
.RS 4 |
| 30213 |
.Sp |
| 30214 |
.Vb 1 |
| 30215 |
\& SV * ERRSV |
| 30216 |
.Ve |
| 30217 |
.RE |
| 30218 |
.RS 4 |
| 30219 |
.RE |
| 30220 |
.ie n .IP """fatal_warner""" 4 |
| 30221 |
.el .IP \f(CWfatal_warner\fR 4 |
| 30222 |
.IX Xref "fatal_warner" |
| 30223 |
.IX Item "fatal_warner" |
| 30224 |
Like "warner" except that it acts as if fatal warnings are enabled |
| 30225 |
for the warning. |
| 30226 |
.Sp |
| 30227 |
If called when there are pending compilation errors this function may |
| 30228 |
return. |
| 30229 |
.Sp |
| 30230 |
This is currently used to generate "used only once" fatal warnings |
| 30231 |
since the COP where the name being reported is no longer the current |
| 30232 |
COP when the warning is generated and may be useful for similar cases. |
| 30233 |
.Sp |
| 30234 |
\&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR, |
| 30235 |
\&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning |
| 30236 |
categories. |
| 30237 |
.Sp |
| 30238 |
NOTE: \f(CW\*(C`fatal_warner\*(C'\fR must be explicitly called as |
| 30239 |
\&\f(CW\*(C`Perl_fatal_warner\*(C'\fR |
| 30240 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30241 |
.RS 4 |
| 30242 |
.Sp |
| 30243 |
.Vb 1 |
| 30244 |
\& void Perl_fatal_warner(pTHX_ U32 err, const char *pat, ...) |
| 30245 |
.Ve |
| 30246 |
.RE |
| 30247 |
.RS 4 |
| 30248 |
.RE |
| 30249 |
.ie n .IP """packWARN""" 4 |
| 30250 |
.el .IP \f(CWpackWARN\fR 4 |
| 30251 |
.IX Item "packWARN" |
| 30252 |
.PD 0 |
| 30253 |
.ie n .IP """packWARN2""" 4 |
| 30254 |
.el .IP \f(CWpackWARN2\fR 4 |
| 30255 |
.IX Item "packWARN2" |
| 30256 |
.ie n .IP """packWARN3""" 4 |
| 30257 |
.el .IP \f(CWpackWARN3\fR 4 |
| 30258 |
.IX Item "packWARN3" |
| 30259 |
.ie n .IP """packWARN4""" 4 |
| 30260 |
.el .IP \f(CWpackWARN4\fR 4 |
| 30261 |
.IX Xref "packWARN packWARN2 packWARN3 packWARN4" |
| 30262 |
.IX Item "packWARN4" |
| 30263 |
.PD |
| 30264 |
These macros are used to pack warning categories into a single U32 to pass to |
| 30265 |
macros and functions that take a warning category parameter. The number of |
| 30266 |
categories to pack is given by the name, with a corresponding number of |
| 30267 |
category parameters passed. |
| 30268 |
.RS 4 |
| 30269 |
.Sp |
| 30270 |
.Vb 4 |
| 30271 |
\& U32 packWARN (U32 w1) |
| 30272 |
\& U32 packWARN2(U32 w1, U32 w2) |
| 30273 |
\& U32 packWARN3(U32 w1, U32 w2, U32 w3) |
| 30274 |
\& U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4) |
| 30275 |
.Ve |
| 30276 |
.RE |
| 30277 |
.RS 4 |
| 30278 |
.RE |
| 30279 |
.ie n .IP """SANE_ERRSV""" 4 |
| 30280 |
.el .IP \f(CWSANE_ERRSV\fR 4 |
| 30281 |
.IX Xref "SANE_ERRSV" |
| 30282 |
.IX Item "SANE_ERRSV" |
| 30283 |
Clean up ERRSV so we can safely set it. |
| 30284 |
.Sp |
| 30285 |
This replaces any read-only SV with a fresh writable copy and removes |
| 30286 |
any magic. |
| 30287 |
.RS 4 |
| 30288 |
.Sp |
| 30289 |
.Vb 1 |
| 30290 |
\& void SANE_ERRSV() |
| 30291 |
.Ve |
| 30292 |
.RE |
| 30293 |
.RS 4 |
| 30294 |
.RE |
| 30295 |
.ie n .IP """vcroak""" 4 |
| 30296 |
.el .IP \f(CWvcroak\fR 4 |
| 30297 |
.IX Xref "vcroak" |
| 30298 |
.IX Item "vcroak" |
| 30299 |
This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function. |
| 30300 |
.Sp |
| 30301 |
\&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated |
| 30302 |
argument list. These are used to generate a string message. If the |
| 30303 |
message does not end with a newline, then it will be extended with |
| 30304 |
some indication of the current location in the code, as described for |
| 30305 |
"mess_sv". |
| 30306 |
.Sp |
| 30307 |
The error message will be used as an exception, by default |
| 30308 |
returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to |
| 30309 |
modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak\*(C'\fR |
| 30310 |
function never returns normally. |
| 30311 |
.Sp |
| 30312 |
For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR |
| 30313 |
(\f(CW$@\fR) will be used as an error message or object instead of building an |
| 30314 |
error message from arguments. If you want to throw a non-string object, |
| 30315 |
or build an error message in an SV yourself, it is preferable to use |
| 30316 |
the "croak_sv" function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR. |
| 30317 |
.RS 4 |
| 30318 |
.Sp |
| 30319 |
.Vb 1 |
| 30320 |
\& void vcroak(const char *pat, va_list *args) |
| 30321 |
.Ve |
| 30322 |
.RE |
| 30323 |
.RS 4 |
| 30324 |
.RE |
| 30325 |
.ie n .IP """vfatal_warner""" 4 |
| 30326 |
.el .IP \f(CWvfatal_warner\fR 4 |
| 30327 |
.IX Xref "vfatal_warner" |
| 30328 |
.IX Item "vfatal_warner" |
| 30329 |
This is like \f(CW"fatal_warner"\fR but \f(CW\*(C`args\*(C'\fR are an encapsulated |
| 30330 |
argument list. |
| 30331 |
.RS 4 |
| 30332 |
.Sp |
| 30333 |
.Vb 1 |
| 30334 |
\& void vfatal_warner(U32 err, const char *pat, va_list *args) |
| 30335 |
.Ve |
| 30336 |
.RE |
| 30337 |
.RS 4 |
| 30338 |
.RE |
| 30339 |
.ie n .IP """vwarn""" 4 |
| 30340 |
.el .IP \f(CWvwarn\fR 4 |
| 30341 |
.IX Xref "vwarn" |
| 30342 |
.IX Item "vwarn" |
| 30343 |
This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function. |
| 30344 |
.Sp |
| 30345 |
This is like \f(CW"warn"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated |
| 30346 |
argument list. |
| 30347 |
.Sp |
| 30348 |
Unlike with "vcroak", \f(CW\*(C`pat\*(C'\fR is not permitted to be null. |
| 30349 |
.RS 4 |
| 30350 |
.Sp |
| 30351 |
.Vb 1 |
| 30352 |
\& void vwarn(const char *pat, va_list *args) |
| 30353 |
.Ve |
| 30354 |
.RE |
| 30355 |
.RS 4 |
| 30356 |
.RE |
| 30357 |
.ie n .IP """vwarner""" 4 |
| 30358 |
.el .IP \f(CWvwarner\fR 4 |
| 30359 |
.IX Xref "vwarner" |
| 30360 |
.IX Item "vwarner" |
| 30361 |
This is like \f(CW"warner"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list. |
| 30362 |
.RS 4 |
| 30363 |
.Sp |
| 30364 |
.Vb 1 |
| 30365 |
\& void vwarner(U32 err, const char *pat, va_list *args) |
| 30366 |
.Ve |
| 30367 |
.RE |
| 30368 |
.RS 4 |
| 30369 |
.RE |
| 30370 |
.ie n .IP """warn""" 4 |
| 30371 |
.el .IP \f(CWwarn\fR 4 |
| 30372 |
.IX Item "warn" |
| 30373 |
.PD 0 |
| 30374 |
.ie n .IP """warn_nocontext""" 4 |
| 30375 |
.el .IP \f(CWwarn_nocontext\fR 4 |
| 30376 |
.IX Xref "warn warn_nocontext" |
| 30377 |
.IX Item "warn_nocontext" |
| 30378 |
.PD |
| 30379 |
These are XS interfaces to Perl's \f(CW\*(C`warn\*(C'\fR function. |
| 30380 |
.Sp |
| 30381 |
They take a sprintf-style format pattern and argument list, which are used to |
| 30382 |
generate a string message. If the message does not end with a newline, then it |
| 30383 |
will be extended with some indication of the current location in the code, as |
| 30384 |
described for \f(CW"mess_sv"\fR. |
| 30385 |
.Sp |
| 30386 |
The error message or object will by default be written to standard error, |
| 30387 |
but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler. |
| 30388 |
.Sp |
| 30389 |
Unlike with \f(CW"croak"\fR, \f(CW\*(C`pat\*(C'\fR is not permitted to be null. |
| 30390 |
.Sp |
| 30391 |
The two forms differ only in that \f(CW\*(C`warn_nocontext\*(C'\fR does not take a thread |
| 30392 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 30393 |
already have the thread context. |
| 30394 |
.Sp |
| 30395 |
NOTE: \f(CW\*(C`warn\*(C'\fR must be explicitly called as |
| 30396 |
\&\f(CW\*(C`Perl_warn\*(C'\fR |
| 30397 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30398 |
.RS 4 |
| 30399 |
.Sp |
| 30400 |
.Vb 2 |
| 30401 |
\& void Perl_warn (pTHX_ const char *pat, ...) |
| 30402 |
\& void warn_nocontext(const char *pat, ...) |
| 30403 |
.Ve |
| 30404 |
.RE |
| 30405 |
.RS 4 |
| 30406 |
.RE |
| 30407 |
.ie n .IP """warner""" 4 |
| 30408 |
.el .IP \f(CWwarner\fR 4 |
| 30409 |
.IX Item "warner" |
| 30410 |
.PD 0 |
| 30411 |
.ie n .IP """warner_nocontext""" 4 |
| 30412 |
.el .IP \f(CWwarner_nocontext\fR 4 |
| 30413 |
.IX Xref "warner warner_nocontext" |
| 30414 |
.IX Item "warner_nocontext" |
| 30415 |
.PD |
| 30416 |
These output a warning of the specified category (or categories) given by |
| 30417 |
\&\f(CW\*(C`err\*(C'\fR, using the sprintf-style format pattern \f(CW\*(C`pat\*(C'\fR, and argument list. |
| 30418 |
.Sp |
| 30419 |
\&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR, |
| 30420 |
\&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning |
| 30421 |
categories. If any of the warning categories they specify is fatal, a fatal |
| 30422 |
exception is thrown. |
| 30423 |
.Sp |
| 30424 |
In any event a message is generated by the pattern and arguments. If the |
| 30425 |
message does not end with a newline, then it will be extended with some |
| 30426 |
indication of the current location in the code, as described for "mess_sv". |
| 30427 |
.Sp |
| 30428 |
The error message or object will by default be written to standard error, |
| 30429 |
but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler. |
| 30430 |
.Sp |
| 30431 |
\&\f(CW\*(C`pat\*(C'\fR is not permitted to be null. |
| 30432 |
.Sp |
| 30433 |
The two forms differ only in that \f(CW\*(C`warner_nocontext\*(C'\fR does not take a thread |
| 30434 |
context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't |
| 30435 |
already have the thread context. |
| 30436 |
.Sp |
| 30437 |
These functions differ from the similarly named \f(CW"warn"\fR functions, in that |
| 30438 |
the latter are for XS code to unconditionally display a warning, whereas these |
| 30439 |
are for code that may be compiling a perl program, and does extra checking to |
| 30440 |
see if the warning should be fatal. |
| 30441 |
.Sp |
| 30442 |
NOTE: \f(CW\*(C`warner\*(C'\fR must be explicitly called as |
| 30443 |
\&\f(CW\*(C`Perl_warner\*(C'\fR |
| 30444 |
with an \f(CW\*(C`aTHX_\*(C'\fR parameter. |
| 30445 |
.RS 4 |
| 30446 |
.Sp |
| 30447 |
.Vb 2 |
| 30448 |
\& void Perl_warner (pTHX_ U32 err, const char *pat, ...) |
| 30449 |
\& void warner_nocontext(U32 err, const char *pat, ...) |
| 30450 |
.Ve |
| 30451 |
.RE |
| 30452 |
.RS 4 |
| 30453 |
.RE |
| 30454 |
.ie n .IP """warn_sv""" 4 |
| 30455 |
.el .IP \f(CWwarn_sv\fR 4 |
| 30456 |
.IX Xref "warn_sv" |
| 30457 |
.IX Item "warn_sv" |
| 30458 |
This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function. |
| 30459 |
.Sp |
| 30460 |
\&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it |
| 30461 |
will be used as-is. Otherwise it is used as a string, and if it does |
| 30462 |
not end with a newline then it will be extended with some indication of |
| 30463 |
the current location in the code, as described for "mess_sv". |
| 30464 |
.Sp |
| 30465 |
The error message or object will by default be written to standard error, |
| 30466 |
but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler. |
| 30467 |
.Sp |
| 30468 |
To warn with a simple string message, the "warn" function may be |
| 30469 |
more convenient. |
| 30470 |
.RS 4 |
| 30471 |
.Sp |
| 30472 |
.Vb 1 |
| 30473 |
\& void warn_sv(SV *baseex) |
| 30474 |
.Ve |
| 30475 |
.RE |
| 30476 |
.RS 4 |
| 30477 |
.RE |
| 30478 |
.SH XS |
| 30479 |
.IX Header "XS" |
| 30480 |
\&\fIxsubpp\fR compiles XS code into C. See "xsubpp" in perlutil. |
| 30481 |
.ie n .IP """aMY_CXT""" 4 |
| 30482 |
.el .IP \f(CWaMY_CXT\fR 4 |
| 30483 |
.IX Item "aMY_CXT" |
| 30484 |
Described in perlxs. |
| 30485 |
.ie n .IP """_aMY_CXT""" 4 |
| 30486 |
.el .IP \f(CW_aMY_CXT\fR 4 |
| 30487 |
.IX Item "_aMY_CXT" |
| 30488 |
Described in perlxs. |
| 30489 |
.ie n .IP """aMY_CXT_""" 4 |
| 30490 |
.el .IP \f(CWaMY_CXT_\fR 4 |
| 30491 |
.IX Item "aMY_CXT_" |
| 30492 |
Described in perlxs. |
| 30493 |
.ie n .IP """ax""" 4 |
| 30494 |
.el .IP \f(CWax\fR 4 |
| 30495 |
.IX Xref "ax" |
| 30496 |
.IX Item "ax" |
| 30497 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset, |
| 30498 |
used by the \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`XSprePUSH\*(C'\fR and \f(CW\*(C`XSRETURN\*(C'\fR macros. The \f(CW\*(C`dMARK\*(C'\fR macro |
| 30499 |
must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable. |
| 30500 |
.RS 4 |
| 30501 |
.Sp |
| 30502 |
.Vb 1 |
| 30503 |
\& Stack_off_t ax |
| 30504 |
.Ve |
| 30505 |
.RE |
| 30506 |
.RS 4 |
| 30507 |
.RE |
| 30508 |
.ie n .IP """CLASS""" 4 |
| 30509 |
.el .IP \f(CWCLASS\fR 4 |
| 30510 |
.IX Xref "CLASS" |
| 30511 |
.IX Item "CLASS" |
| 30512 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the |
| 30513 |
class name for a C++ XS constructor. This is always a \f(CW\*(C`char*\*(C'\fR. See |
| 30514 |
\&\f(CW"THIS"\fR. |
| 30515 |
.RS 4 |
| 30516 |
.Sp |
| 30517 |
.Vb 1 |
| 30518 |
\& char* CLASS |
| 30519 |
.Ve |
| 30520 |
.RE |
| 30521 |
.RS 4 |
| 30522 |
.RE |
| 30523 |
.ie n .IP """dAX""" 4 |
| 30524 |
.el .IP \f(CWdAX\fR 4 |
| 30525 |
.IX Xref "dAX" |
| 30526 |
.IX Item "dAX" |
| 30527 |
Sets up the \f(CW\*(C`ax\*(C'\fR variable. |
| 30528 |
This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. |
| 30529 |
.RS 4 |
| 30530 |
.Sp |
| 30531 |
.Vb 1 |
| 30532 |
\& dAX; |
| 30533 |
.Ve |
| 30534 |
.RE |
| 30535 |
.RS 4 |
| 30536 |
.RE |
| 30537 |
.ie n .IP """dAXMARK""" 4 |
| 30538 |
.el .IP \f(CWdAXMARK\fR 4 |
| 30539 |
.IX Xref "dAXMARK" |
| 30540 |
.IX Item "dAXMARK" |
| 30541 |
Sets up the \f(CW\*(C`ax\*(C'\fR variable and stack marker variable \f(CW\*(C`mark\*(C'\fR. |
| 30542 |
This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. |
| 30543 |
.RS 4 |
| 30544 |
.Sp |
| 30545 |
.Vb 1 |
| 30546 |
\& dAXMARK; |
| 30547 |
.Ve |
| 30548 |
.RE |
| 30549 |
.RS 4 |
| 30550 |
.RE |
| 30551 |
.ie n .IP """dITEMS""" 4 |
| 30552 |
.el .IP \f(CWdITEMS\fR 4 |
| 30553 |
.IX Xref "dITEMS" |
| 30554 |
.IX Item "dITEMS" |
| 30555 |
Sets up the \f(CW\*(C`items\*(C'\fR variable. |
| 30556 |
This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. |
| 30557 |
.RS 4 |
| 30558 |
.Sp |
| 30559 |
.Vb 1 |
| 30560 |
\& dITEMS; |
| 30561 |
.Ve |
| 30562 |
.RE |
| 30563 |
.RS 4 |
| 30564 |
.RE |
| 30565 |
.ie n .IP """dMY_CXT""" 4 |
| 30566 |
.el .IP \f(CWdMY_CXT\fR 4 |
| 30567 |
.IX Item "dMY_CXT" |
| 30568 |
Described in perlxs. |
| 30569 |
.ie n .IP """dMY_CXT_SV""" 4 |
| 30570 |
.el .IP \f(CWdMY_CXT_SV\fR 4 |
| 30571 |
.IX Xref "dMY_CXT_SV" |
| 30572 |
.IX Item "dMY_CXT_SV" |
| 30573 |
Now a placeholder that declares nothing |
| 30574 |
.RS 4 |
| 30575 |
.Sp |
| 30576 |
.Vb 1 |
| 30577 |
\& dMY_CXT_SV; |
| 30578 |
.Ve |
| 30579 |
.RE |
| 30580 |
.RS 4 |
| 30581 |
.RE |
| 30582 |
.ie n .IP """dUNDERBAR""" 4 |
| 30583 |
.el .IP \f(CWdUNDERBAR\fR 4 |
| 30584 |
.IX Xref "dUNDERBAR" |
| 30585 |
.IX Item "dUNDERBAR" |
| 30586 |
Sets up any variable needed by the \f(CW\*(C`UNDERBAR\*(C'\fR macro. It used to define |
| 30587 |
\&\f(CW\*(C`padoff_du\*(C'\fR, but it is currently a noop. However, it is strongly advised |
| 30588 |
to still use it for ensuring past and future compatibility. |
| 30589 |
.RS 4 |
| 30590 |
.Sp |
| 30591 |
.Vb 1 |
| 30592 |
\& dUNDERBAR; |
| 30593 |
.Ve |
| 30594 |
.RE |
| 30595 |
.RS 4 |
| 30596 |
.RE |
| 30597 |
.ie n .IP """dXSARGS""" 4 |
| 30598 |
.el .IP \f(CWdXSARGS\fR 4 |
| 30599 |
.IX Xref "dXSARGS" |
| 30600 |
.IX Item "dXSARGS" |
| 30601 |
Sets up stack and mark pointers for an XSUB, calling \f(CW\*(C`dSP\*(C'\fR and \f(CW\*(C`dMARK\*(C'\fR. |
| 30602 |
Sets up the \f(CW\*(C`ax\*(C'\fR and \f(CW\*(C`items\*(C'\fR variables by calling \f(CW\*(C`dAX\*(C'\fR and \f(CW\*(C`dITEMS\*(C'\fR. |
| 30603 |
This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. |
| 30604 |
.RS 4 |
| 30605 |
.Sp |
| 30606 |
.Vb 1 |
| 30607 |
\& dXSARGS; |
| 30608 |
.Ve |
| 30609 |
.RE |
| 30610 |
.RS 4 |
| 30611 |
.RE |
| 30612 |
.ie n .IP """dXSI32""" 4 |
| 30613 |
.el .IP \f(CWdXSI32\fR 4 |
| 30614 |
.IX Xref "dXSI32" |
| 30615 |
.IX Item "dXSI32" |
| 30616 |
Sets up the \f(CW\*(C`ix\*(C'\fR variable for an XSUB which has aliases. This is usually |
| 30617 |
handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. |
| 30618 |
.RS 4 |
| 30619 |
.Sp |
| 30620 |
.Vb 1 |
| 30621 |
\& dXSI32; |
| 30622 |
.Ve |
| 30623 |
.RE |
| 30624 |
.RS 4 |
| 30625 |
.RE |
| 30626 |
.ie n .IP """items""" 4 |
| 30627 |
.el .IP \f(CWitems\fR 4 |
| 30628 |
.IX Xref "items" |
| 30629 |
.IX Item "items" |
| 30630 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of |
| 30631 |
items on the stack. See "Variable-length Parameter Lists" in perlxs. |
| 30632 |
.RS 4 |
| 30633 |
.Sp |
| 30634 |
.Vb 1 |
| 30635 |
\& Stack_off_t items |
| 30636 |
.Ve |
| 30637 |
.RE |
| 30638 |
.RS 4 |
| 30639 |
.RE |
| 30640 |
.ie n .IP """ix""" 4 |
| 30641 |
.el .IP \f(CWix\fR 4 |
| 30642 |
.IX Xref "ix" |
| 30643 |
.IX Item "ix" |
| 30644 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an |
| 30645 |
XSUB's aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs. |
| 30646 |
.RS 4 |
| 30647 |
.Sp |
| 30648 |
.Vb 1 |
| 30649 |
\& I32 ix |
| 30650 |
.Ve |
| 30651 |
.RE |
| 30652 |
.RS 4 |
| 30653 |
.RE |
| 30654 |
.ie n .IP """MY_CXT""" 4 |
| 30655 |
.el .IP \f(CWMY_CXT\fR 4 |
| 30656 |
.IX Item "MY_CXT" |
| 30657 |
Described in perlxs. |
| 30658 |
.ie n .IP """MY_CXT_CLONE""" 4 |
| 30659 |
.el .IP \f(CWMY_CXT_CLONE\fR 4 |
| 30660 |
.IX Item "MY_CXT_CLONE" |
| 30661 |
Described in perlxs. |
| 30662 |
.ie n .IP """MY_CXT_INIT""" 4 |
| 30663 |
.el .IP \f(CWMY_CXT_INIT\fR 4 |
| 30664 |
.IX Item "MY_CXT_INIT" |
| 30665 |
Described in perlxs. |
| 30666 |
.ie n .IP """pMY_CXT""" 4 |
| 30667 |
.el .IP \f(CWpMY_CXT\fR 4 |
| 30668 |
.IX Item "pMY_CXT" |
| 30669 |
Described in perlxs. |
| 30670 |
.ie n .IP """_pMY_CXT""" 4 |
| 30671 |
.el .IP \f(CW_pMY_CXT\fR 4 |
| 30672 |
.IX Item "_pMY_CXT" |
| 30673 |
Described in perlxs. |
| 30674 |
.ie n .IP """pMY_CXT_""" 4 |
| 30675 |
.el .IP \f(CWpMY_CXT_\fR 4 |
| 30676 |
.IX Item "pMY_CXT_" |
| 30677 |
Described in perlxs. |
| 30678 |
.ie n .IP """RETVAL""" 4 |
| 30679 |
.el .IP \f(CWRETVAL\fR 4 |
| 30680 |
.IX Xref "RETVAL" |
| 30681 |
.IX Item "RETVAL" |
| 30682 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an |
| 30683 |
XSUB. This is always the proper type for the XSUB. See |
| 30684 |
"The RETVAL Variable" in perlxs. |
| 30685 |
.RS 4 |
| 30686 |
.Sp |
| 30687 |
.Vb 1 |
| 30688 |
\& type RETVAL |
| 30689 |
.Ve |
| 30690 |
.RE |
| 30691 |
.RS 4 |
| 30692 |
.RE |
| 30693 |
.ie n .IP """ST""" 4 |
| 30694 |
.el .IP \f(CWST\fR 4 |
| 30695 |
.IX Xref "ST" |
| 30696 |
.IX Item "ST" |
| 30697 |
Used to access elements on the XSUB's stack. |
| 30698 |
.RS 4 |
| 30699 |
.Sp |
| 30700 |
.Vb 1 |
| 30701 |
\& SV* ST(int ix) |
| 30702 |
.Ve |
| 30703 |
.RE |
| 30704 |
.RS 4 |
| 30705 |
.RE |
| 30706 |
.ie n .IP """START_MY_CXT""" 4 |
| 30707 |
.el .IP \f(CWSTART_MY_CXT\fR 4 |
| 30708 |
.IX Item "START_MY_CXT" |
| 30709 |
Described in perlxs. |
| 30710 |
.ie n .IP """THIS""" 4 |
| 30711 |
.el .IP \f(CWTHIS\fR 4 |
| 30712 |
.IX Xref "THIS" |
| 30713 |
.IX Item "THIS" |
| 30714 |
Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a C++ |
| 30715 |
XSUB. This is always the proper type for the C++ object. See \f(CW"CLASS"\fR and |
| 30716 |
"Using XS With C++" in perlxs. |
| 30717 |
.RS 4 |
| 30718 |
.Sp |
| 30719 |
.Vb 1 |
| 30720 |
\& type THIS |
| 30721 |
.Ve |
| 30722 |
.RE |
| 30723 |
.RS 4 |
| 30724 |
.RE |
| 30725 |
.ie n .IP """UNDERBAR""" 4 |
| 30726 |
.el .IP \f(CWUNDERBAR\fR 4 |
| 30727 |
.IX Xref "UNDERBAR" |
| 30728 |
.IX Item "UNDERBAR" |
| 30729 |
The SV* corresponding to the \f(CW$_\fR variable. Works even if there |
| 30730 |
is a lexical \f(CW$_\fR in scope. |
| 30731 |
.ie n .IP """XS""" 4 |
| 30732 |
.el .IP \f(CWXS\fR 4 |
| 30733 |
.IX Xref "XS" |
| 30734 |
.IX Item "XS" |
| 30735 |
Macro to declare an XSUB and its C parameter list. This is handled by |
| 30736 |
\&\f(CW\*(C`xsubpp\*(C'\fR. It is the same as using the more explicit \f(CW\*(C`XS_EXTERNAL\*(C'\fR macro; the |
| 30737 |
latter is preferred. |
| 30738 |
.ie n .IP """XS_EXTERNAL""" 4 |
| 30739 |
.el .IP \f(CWXS_EXTERNAL\fR 4 |
| 30740 |
.IX Xref "XS_EXTERNAL" |
| 30741 |
.IX Item "XS_EXTERNAL" |
| 30742 |
Macro to declare an XSUB and its C parameter list explicitly exporting the symbols. |
| 30743 |
.ie n .IP """XS_INTERNAL""" 4 |
| 30744 |
.el .IP \f(CWXS_INTERNAL\fR 4 |
| 30745 |
.IX Xref "XS_INTERNAL" |
| 30746 |
.IX Item "XS_INTERNAL" |
| 30747 |
Macro to declare an XSUB and its C parameter list without exporting the symbols. |
| 30748 |
This is handled by \f(CW\*(C`xsubpp\*(C'\fR and generally preferable over exporting the XSUB |
| 30749 |
symbols unnecessarily. |
| 30750 |
.ie n .IP """XSPROTO""" 4 |
| 30751 |
.el .IP \f(CWXSPROTO\fR 4 |
| 30752 |
.IX Xref "XSPROTO" |
| 30753 |
.IX Item "XSPROTO" |
| 30754 |
Macro used by \f(CW"XS_INTERNAL"\fR and \f(CW"XS_EXTERNAL"\fR to declare a function |
| 30755 |
prototype. You probably shouldn't be using this directly yourself. |
| 30756 |
.SH "Undocumented elements" |
| 30757 |
.IX Header "Undocumented elements" |
| 30758 |
The following functions have been flagged as part of the public |
| 30759 |
API, but are currently undocumented. Use them at your own risk, |
| 30760 |
as the interfaces are subject to change. Functions that are not |
| 30761 |
listed in this document are not intended for public use, and |
| 30762 |
should NOT be used under any circumstances. |
| 30763 |
.PP |
| 30764 |
If you feel you need to use one of these functions, first send |
| 30765 |
email to perl5\[email protected] <mailto:[email protected]>. |
| 30766 |
It may be that there is a good reason for the function not being |
| 30767 |
documented, and it should be removed from this list; or it may |
| 30768 |
just be that no one has gotten around to documenting it. In the |
| 30769 |
latter case, you will be asked to submit a patch to document the |
| 30770 |
function. Once your patch is accepted, it will indicate that the |
| 30771 |
interface is stable (unless it is explicitly marked otherwise) and |
| 30772 |
usable by you. |
| 30773 |
.PP |
| 30774 |
|
| 30775 |
.IX Xref "clone_params_del clone_params_new do_open do_openn PERL_BUILD_DATE resume_compcv sv_dup sv_dup_inc" |
| 30776 |
.PP |
| 30777 |
.Vb 2 |
| 30778 |
\& clone_params_del do_open PERL_BUILD_DATE sv_dup |
| 30779 |
\& clone_params_new do_openn resume_compcv sv_dup_inc |
| 30780 |
.Ve |
| 30781 |
.PP |
| 30782 |
Next are the API-flagged elements that are considered experimental. Using one |
| 30783 |
of these is even more risky than plain undocumented ones. They are listed |
| 30784 |
here because they should be listed somewhere (so their existence doesn't get |
| 30785 |
lost) and this is the best place for them. |
| 30786 |
.PP |
| 30787 |
|
| 30788 |
.IX Xref "apply_attrs_string gv_fetchmethod_pv_flags gv_fetchmethod_pvn_flags gv_fetchmethod_sv_flags hv_store_flags leave_adjust_stacks newXS_flags savetmps thread_locale_init thread_locale_term" |
| 30789 |
.PP |
| 30790 |
.Vb 4 |
| 30791 |
\& apply_attrs_string hv_store_flags thread_locale_init |
| 30792 |
\& gv_fetchmethod_pv_flags leave_adjust_stacks thread_locale_term |
| 30793 |
\& gv_fetchmethod_pvn_flags newXS_flags |
| 30794 |
\& gv_fetchmethod_sv_flags savetmps |
| 30795 |
.Ve |
| 30796 |
.PP |
| 30797 |
Finally are deprecated undocumented API elements. |
| 30798 |
Do not use any for new code; remove all occurrences of all of these from |
| 30799 |
existing code. |
| 30800 |
.PP |
| 30801 |
There are currently no items of this type |
| 30802 |
.SH AUTHORS |
| 30803 |
.IX Header "AUTHORS" |
| 30804 |
Until May 1997, this document was maintained by Jeff Okamoto |
| 30805 |
<[email protected]>. It is now maintained as part of Perl itself. |
| 30806 |
.PP |
| 30807 |
With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, |
| 30808 |
Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil |
| 30809 |
Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, |
| 30810 |
Stephen McCamant, and Gurusamy Sarathy. |
| 30811 |
.PP |
| 30812 |
API Listing originally by Dean Roehrich <[email protected]>. |
| 30813 |
.PP |
| 30814 |
Updated to be autogenerated from comments in the source by Benjamin Stuhl. |
| 30815 |
.SH "SEE ALSO" |
| 30816 |
.IX Header "SEE ALSO" |
| 30817 |
\&\fIconfig.h\fR, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs |