Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLAPI 1" | |
132 | .TH PERLAPI 1 "2002-06-08" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlapi \- autogenerated documentation for the perl public API | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | This file contains the documentation of the perl public \s-1API\s0 generated by | |
138 | embed.pl, specifically a listing of functions, macros, flags, and variables | |
139 | that may be used by extension writers. The interfaces of any functions that | |
140 | are not listed here are subject to change without notice. For this reason, | |
141 | blindly using functions listed in proto.h is to be avoided when writing | |
142 | extensions. | |
143 | .PP | |
144 | Note that all Perl \s-1API\s0 global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR | |
145 | prefix. Some macros are provided for compatibility with the older, | |
146 | unadorned names, but this support may be disabled in a future release. | |
147 | .PP | |
148 | The listing is alphabetical, case insensitive. | |
149 | .ie n .SH """Gimme"" Values" | |
150 | .el .SH "``Gimme'' Values" | |
151 | .IX Header "Gimme Values" | |
152 | .IP "\s-1GIMME\s0" 8 | |
153 | .IX Item "GIMME" | |
154 | A backward-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return | |
155 | \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_ARRAY\*(C'\fR; in a void context, it returns \f(CW\*(C`G_SCALAR\*(C'\fR. | |
156 | Deprecated. Use \f(CW\*(C`GIMME_V\*(C'\fR instead. | |
157 | .Sp | |
158 | .Vb 1 | |
159 | \& U32 GIMME | |
160 | .Ve | |
161 | .IP "\s-1GIMME_V\s0" 8 | |
162 | .IX Item "GIMME_V" | |
163 | The XSUB\-writer's equivalent to Perl's \f(CW\*(C`wantarray\*(C'\fR. Returns \f(CW\*(C`G_VOID\*(C'\fR, | |
164 | \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_ARRAY\*(C'\fR for void, scalar or list context, | |
165 | respectively. | |
166 | .Sp | |
167 | .Vb 1 | |
168 | \& U32 GIMME_V | |
169 | .Ve | |
170 | .IP "G_ARRAY" 8 | |
171 | .IX Item "G_ARRAY" | |
172 | Used to indicate list context. See \f(CW\*(C`GIMME_V\*(C'\fR, \f(CW\*(C`GIMME\*(C'\fR and | |
173 | perlcall. | |
174 | .IP "G_DISCARD" 8 | |
175 | .IX Item "G_DISCARD" | |
176 | Indicates that arguments returned from a callback should be discarded. See | |
177 | perlcall. | |
178 | .IP "G_EVAL" 8 | |
179 | .IX Item "G_EVAL" | |
180 | Used to force a Perl \f(CW\*(C`eval\*(C'\fR wrapper around a callback. See | |
181 | perlcall. | |
182 | .IP "G_NOARGS" 8 | |
183 | .IX Item "G_NOARGS" | |
184 | Indicates that no arguments are being sent to a callback. See | |
185 | perlcall. | |
186 | .IP "G_SCALAR" 8 | |
187 | .IX Item "G_SCALAR" | |
188 | Used to indicate scalar context. See \f(CW\*(C`GIMME_V\*(C'\fR, \f(CW\*(C`GIMME\*(C'\fR, and | |
189 | perlcall. | |
190 | .IP "G_VOID" 8 | |
191 | .IX Item "G_VOID" | |
192 | Used to indicate void context. See \f(CW\*(C`GIMME_V\*(C'\fR and perlcall. | |
193 | .SH "Array Manipulation Functions" | |
194 | .IX Header "Array Manipulation Functions" | |
195 | .IP "AvFILL" 8 | |
196 | .IX Item "AvFILL" | |
197 | Same as \f(CW\*(C`av_len()\*(C'\fR. Deprecated, use \f(CW\*(C`av_len()\*(C'\fR instead. | |
198 | .Sp | |
199 | .Vb 1 | |
200 | \& int AvFILL(AV* av) | |
201 | .Ve | |
202 | .IP "av_clear" 8 | |
203 | .IX Item "av_clear" | |
204 | Clears an array, making it empty. Does not free the memory used by the | |
205 | array itself. | |
206 | .Sp | |
207 | .Vb 1 | |
208 | \& void av_clear(AV* ar) | |
209 | .Ve | |
210 | .IP "av_delete" 8 | |
211 | .IX Item "av_delete" | |
212 | Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array. Returns the | |
213 | deleted element. \f(CW\*(C`flags\*(C'\fR is currently ignored. | |
214 | .Sp | |
215 | .Vb 1 | |
216 | \& SV* av_delete(AV* ar, I32 key, I32 flags) | |
217 | .Ve | |
218 | .IP "av_exists" 8 | |
219 | .IX Item "av_exists" | |
220 | Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized. | |
221 | .Sp | |
222 | This relies on the fact that uninitialized array elements are set to | |
223 | \&\f(CW&PL_sv_undef\fR. | |
224 | .Sp | |
225 | .Vb 1 | |
226 | \& bool av_exists(AV* ar, I32 key) | |
227 | .Ve | |
228 | .IP "av_extend" 8 | |
229 | .IX Item "av_extend" | |
230 | Pre-extend an array. The \f(CW\*(C`key\*(C'\fR is the index to which the array should be | |
231 | extended. | |
232 | .Sp | |
233 | .Vb 1 | |
234 | \& void av_extend(AV* ar, I32 key) | |
235 | .Ve | |
236 | .IP "av_fetch" 8 | |
237 | .IX Item "av_fetch" | |
238 | Returns the \s-1SV\s0 at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the | |
239 | index. If \f(CW\*(C`lval\*(C'\fR is set then the fetch will be part of a store. Check | |
240 | that the return value is non-null before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR. | |
241 | .Sp | |
242 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for | |
243 | more information on how to use this function on tied arrays. | |
244 | .Sp | |
245 | .Vb 1 | |
246 | \& SV** av_fetch(AV* ar, I32 key, I32 lval) | |
247 | .Ve | |
248 | .IP "av_fill" 8 | |
249 | .IX Item "av_fill" | |
250 | Ensure than an array has a given number of elements, equivalent to | |
251 | Perl's \f(CW\*(C`$#array = $fill;\*(C'\fR. | |
252 | .Sp | |
253 | .Vb 1 | |
254 | \& void av_fill(AV* ar, I32 fill) | |
255 | .Ve | |
256 | .IP "av_len" 8 | |
257 | .IX Item "av_len" | |
258 | Returns the highest index in the array. Returns \-1 if the array is | |
259 | empty. | |
260 | .Sp | |
261 | .Vb 1 | |
262 | \& I32 av_len(AV* ar) | |
263 | .Ve | |
264 | .IP "av_make" 8 | |
265 | .IX Item "av_make" | |
266 | Creates a new \s-1AV\s0 and populates it with a list of SVs. The SVs are copied | |
267 | into the array, so they may be freed after the call to av_make. The new \s-1AV\s0 | |
268 | will have a reference count of 1. | |
269 | .Sp | |
270 | .Vb 1 | |
271 | \& AV* av_make(I32 size, SV** svp) | |
272 | .Ve | |
273 | .IP "av_pop" 8 | |
274 | .IX Item "av_pop" | |
275 | Pops an \s-1SV\s0 off the end of the array. Returns \f(CW&PL_sv_undef\fR if the array | |
276 | is empty. | |
277 | .Sp | |
278 | .Vb 1 | |
279 | \& SV* av_pop(AV* ar) | |
280 | .Ve | |
281 | .IP "av_push" 8 | |
282 | .IX Item "av_push" | |
283 | Pushes an \s-1SV\s0 onto the end of the array. The array will grow automatically | |
284 | to accommodate the addition. | |
285 | .Sp | |
286 | .Vb 1 | |
287 | \& void av_push(AV* ar, SV* val) | |
288 | .Ve | |
289 | .IP "av_shift" 8 | |
290 | .IX Item "av_shift" | |
291 | Shifts an \s-1SV\s0 off the beginning of the array. | |
292 | .Sp | |
293 | .Vb 1 | |
294 | \& SV* av_shift(AV* ar) | |
295 | .Ve | |
296 | .IP "av_store" 8 | |
297 | .IX Item "av_store" | |
298 | Stores an \s-1SV\s0 in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. The | |
299 | return value will be \s-1NULL\s0 if the operation failed or if the value did not | |
300 | need to be actually stored within the array (as in the case of tied | |
301 | arrays). Otherwise it can be dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR. Note | |
302 | that the caller is responsible for suitably incrementing the reference | |
303 | count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function | |
304 | returned \s-1NULL\s0. | |
305 | .Sp | |
306 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for | |
307 | more information on how to use this function on tied arrays. | |
308 | .Sp | |
309 | .Vb 1 | |
310 | \& SV** av_store(AV* ar, I32 key, SV* val) | |
311 | .Ve | |
312 | .IP "av_undef" 8 | |
313 | .IX Item "av_undef" | |
314 | Undefines the array. Frees the memory used by the array itself. | |
315 | .Sp | |
316 | .Vb 1 | |
317 | \& void av_undef(AV* ar) | |
318 | .Ve | |
319 | .IP "av_unshift" 8 | |
320 | .IX Item "av_unshift" | |
321 | Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the | |
322 | array. The array will grow automatically to accommodate the addition. You | |
323 | must then use \f(CW\*(C`av_store\*(C'\fR to assign values to these new elements. | |
324 | .Sp | |
325 | .Vb 1 | |
326 | \& void av_unshift(AV* ar, I32 num) | |
327 | .Ve | |
328 | .IP "get_av" 8 | |
329 | .IX Item "get_av" | |
330 | Returns the \s-1AV\s0 of the specified Perl array. If \f(CW\*(C`create\*(C'\fR is set and the | |
331 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
332 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
333 | .Sp | |
334 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
335 | .Sp | |
336 | .Vb 1 | |
337 | \& AV* get_av(const char* name, I32 create) | |
338 | .Ve | |
339 | .IP "newAV" 8 | |
340 | .IX Item "newAV" | |
341 | Creates a new \s-1AV\s0. The reference count is set to 1. | |
342 | .Sp | |
343 | .Vb 1 | |
344 | \& AV* newAV() | |
345 | .Ve | |
346 | .IP "Nullav" 8 | |
347 | .IX Item "Nullav" | |
348 | Null \s-1AV\s0 pointer. | |
349 | .IP "sortsv" 8 | |
350 | .IX Item "sortsv" | |
351 | Sort an array. Here is an example: | |
352 | .Sp | |
353 | .Vb 1 | |
354 | \& sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); | |
355 | .Ve | |
356 | .Sp | |
357 | See lib/sort.pm for details about controlling the sorting algorithm. | |
358 | .Sp | |
359 | .Vb 1 | |
360 | \& void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) | |
361 | .Ve | |
362 | .SH "Callback Functions" | |
363 | .IX Header "Callback Functions" | |
364 | .IP "call_argv" 8 | |
365 | .IX Item "call_argv" | |
366 | Performs a callback to the specified Perl sub. See perlcall. | |
367 | .Sp | |
368 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
369 | .Sp | |
370 | .Vb 1 | |
371 | \& I32 call_argv(const char* sub_name, I32 flags, char** argv) | |
372 | .Ve | |
373 | .IP "call_method" 8 | |
374 | .IX Item "call_method" | |
375 | Performs a callback to the specified Perl method. The blessed object must | |
376 | be on the stack. See perlcall. | |
377 | .Sp | |
378 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
379 | .Sp | |
380 | .Vb 1 | |
381 | \& I32 call_method(const char* methname, I32 flags) | |
382 | .Ve | |
383 | .IP "call_pv" 8 | |
384 | .IX Item "call_pv" | |
385 | Performs a callback to the specified Perl sub. See perlcall. | |
386 | .Sp | |
387 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
388 | .Sp | |
389 | .Vb 1 | |
390 | \& I32 call_pv(const char* sub_name, I32 flags) | |
391 | .Ve | |
392 | .IP "call_sv" 8 | |
393 | .IX Item "call_sv" | |
394 | Performs a callback to the Perl sub whose name is in the \s-1SV\s0. See | |
395 | perlcall. | |
396 | .Sp | |
397 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
398 | .Sp | |
399 | .Vb 1 | |
400 | \& I32 call_sv(SV* sv, I32 flags) | |
401 | .Ve | |
402 | .IP "\s-1ENTER\s0" 8 | |
403 | .IX Item "ENTER" | |
404 | Opening bracket on a callback. See \f(CW\*(C`LEAVE\*(C'\fR and perlcall. | |
405 | .Sp | |
406 | .Vb 1 | |
407 | \& ENTER; | |
408 | .Ve | |
409 | .IP "eval_pv" 8 | |
410 | .IX Item "eval_pv" | |
411 | Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string and return an SV* result. | |
412 | .Sp | |
413 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
414 | .Sp | |
415 | .Vb 1 | |
416 | \& SV* eval_pv(const char* p, I32 croak_on_error) | |
417 | .Ve | |
418 | .IP "eval_sv" 8 | |
419 | .IX Item "eval_sv" | |
420 | Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the \s-1SV\s0. | |
421 | .Sp | |
422 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
423 | .Sp | |
424 | .Vb 1 | |
425 | \& I32 eval_sv(SV* sv, I32 flags) | |
426 | .Ve | |
427 | .IP "\s-1FREETMPS\s0" 8 | |
428 | .IX Item "FREETMPS" | |
429 | Closing bracket for temporaries on a callback. See \f(CW\*(C`SAVETMPS\*(C'\fR and | |
430 | perlcall. | |
431 | .Sp | |
432 | .Vb 1 | |
433 | \& FREETMPS; | |
434 | .Ve | |
435 | .IP "\s-1LEAVE\s0" 8 | |
436 | .IX Item "LEAVE" | |
437 | Closing bracket on a callback. See \f(CW\*(C`ENTER\*(C'\fR and perlcall. | |
438 | .Sp | |
439 | .Vb 1 | |
440 | \& LEAVE; | |
441 | .Ve | |
442 | .IP "\s-1SAVETMPS\s0" 8 | |
443 | .IX Item "SAVETMPS" | |
444 | Opening bracket for temporaries on a callback. See \f(CW\*(C`FREETMPS\*(C'\fR and | |
445 | perlcall. | |
446 | .Sp | |
447 | .Vb 1 | |
448 | \& SAVETMPS; | |
449 | .Ve | |
450 | .SH "Character classes" | |
451 | .IX Header "Character classes" | |
452 | .IP "isALNUM" 8 | |
453 | .IX Item "isALNUM" | |
454 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 alphanumeric | |
455 | character (including underscore) or digit. | |
456 | .Sp | |
457 | .Vb 1 | |
458 | \& bool isALNUM(char ch) | |
459 | .Ve | |
460 | .IP "isALPHA" 8 | |
461 | .IX Item "isALPHA" | |
462 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 alphabetic | |
463 | character. | |
464 | .Sp | |
465 | .Vb 1 | |
466 | \& bool isALPHA(char ch) | |
467 | .Ve | |
468 | .IP "isDIGIT" 8 | |
469 | .IX Item "isDIGIT" | |
470 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 | |
471 | digit. | |
472 | .Sp | |
473 | .Vb 1 | |
474 | \& bool isDIGIT(char ch) | |
475 | .Ve | |
476 | .IP "isLOWER" 8 | |
477 | .IX Item "isLOWER" | |
478 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is a lowercase | |
479 | character. | |
480 | .Sp | |
481 | .Vb 1 | |
482 | \& bool isLOWER(char ch) | |
483 | .Ve | |
484 | .IP "isSPACE" 8 | |
485 | .IX Item "isSPACE" | |
486 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is whitespace. | |
487 | .Sp | |
488 | .Vb 1 | |
489 | \& bool isSPACE(char ch) | |
490 | .Ve | |
491 | .IP "isUPPER" 8 | |
492 | .IX Item "isUPPER" | |
493 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an uppercase | |
494 | character. | |
495 | .Sp | |
496 | .Vb 1 | |
497 | \& bool isUPPER(char ch) | |
498 | .Ve | |
499 | .IP "toLOWER" 8 | |
500 | .IX Item "toLOWER" | |
501 | Converts the specified character to lowercase. | |
502 | .Sp | |
503 | .Vb 1 | |
504 | \& char toLOWER(char ch) | |
505 | .Ve | |
506 | .IP "toUPPER" 8 | |
507 | .IX Item "toUPPER" | |
508 | Converts the specified character to uppercase. | |
509 | .Sp | |
510 | .Vb 1 | |
511 | \& char toUPPER(char ch) | |
512 | .Ve | |
513 | .SH "Cloning an interpreter" | |
514 | .IX Header "Cloning an interpreter" | |
515 | .IP "perl_clone" 8 | |
516 | .IX Item "perl_clone" | |
517 | Create and return a new interpreter by cloning the current one. | |
518 | .Sp | |
519 | .Vb 1 | |
520 | \& PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) | |
521 | .Ve | |
522 | .SH "CV Manipulation Functions" | |
523 | .IX Header "CV Manipulation Functions" | |
524 | .IP "CvSTASH" 8 | |
525 | .IX Item "CvSTASH" | |
526 | Returns the stash of the \s-1CV\s0. | |
527 | .Sp | |
528 | .Vb 1 | |
529 | \& HV* CvSTASH(CV* cv) | |
530 | .Ve | |
531 | .IP "get_cv" 8 | |
532 | .IX Item "get_cv" | |
533 | Returns the \s-1CV\s0 of the specified Perl subroutine. If \f(CW\*(C`create\*(C'\fR is set and | |
534 | the Perl subroutine does not exist then it will be declared (which has the | |
535 | same effect as saying \f(CW\*(C`sub name;\*(C'\fR). If \f(CW\*(C`create\*(C'\fR is not set and the | |
536 | subroutine does not exist then \s-1NULL\s0 is returned. | |
537 | .Sp | |
538 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
539 | .Sp | |
540 | .Vb 1 | |
541 | \& CV* get_cv(const char* name, I32 create) | |
542 | .Ve | |
543 | .IP "Nullcv" 8 | |
544 | .IX Item "Nullcv" | |
545 | Null \s-1CV\s0 pointer. | |
546 | .SH "Embedding Functions" | |
547 | .IX Header "Embedding Functions" | |
548 | .IP "load_module" 8 | |
549 | .IX Item "load_module" | |
550 | Loads the module whose name is pointed to by the string part of name. | |
551 | Note that the actual module name, not its filename, should be given. | |
552 | Eg, \*(L"Foo::Bar\*(R" instead of \*(L"Foo/Bar.pm\*(R". flags can be any of | |
553 | \&\s-1PERL_LOADMOD_DENY\s0, \s-1PERL_LOADMOD_NOIMPORT\s0, or \s-1PERL_LOADMOD_IMPORT_OPS\s0 | |
554 | (or 0 for no flags). ver, if specified, provides version semantics | |
555 | similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional trailing SV* | |
556 | arguments can be used to specify arguments to the module's \fIimport()\fR | |
557 | method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR. | |
558 | .Sp | |
559 | .Vb 1 | |
560 | \& void load_module(U32 flags, SV* name, SV* ver, ...) | |
561 | .Ve | |
562 | .IP "nothreadhook" 8 | |
563 | .IX Item "nothreadhook" | |
564 | Stub that provides thread hook for perl_destruct when there are | |
565 | no threads. | |
566 | .Sp | |
567 | .Vb 1 | |
568 | \& int nothreadhook() | |
569 | .Ve | |
570 | .IP "perl_alloc" 8 | |
571 | .IX Item "perl_alloc" | |
572 | Allocates a new Perl interpreter. See perlembed. | |
573 | .Sp | |
574 | .Vb 1 | |
575 | \& PerlInterpreter* perl_alloc() | |
576 | .Ve | |
577 | .IP "perl_construct" 8 | |
578 | .IX Item "perl_construct" | |
579 | Initializes a new Perl interpreter. See perlembed. | |
580 | .Sp | |
581 | .Vb 1 | |
582 | \& void perl_construct(PerlInterpreter* interp) | |
583 | .Ve | |
584 | .IP "perl_destruct" 8 | |
585 | .IX Item "perl_destruct" | |
586 | Shuts down a Perl interpreter. See perlembed. | |
587 | .Sp | |
588 | .Vb 1 | |
589 | \& int perl_destruct(PerlInterpreter* interp) | |
590 | .Ve | |
591 | .IP "perl_free" 8 | |
592 | .IX Item "perl_free" | |
593 | Releases a Perl interpreter. See perlembed. | |
594 | .Sp | |
595 | .Vb 1 | |
596 | \& void perl_free(PerlInterpreter* interp) | |
597 | .Ve | |
598 | .IP "perl_parse" 8 | |
599 | .IX Item "perl_parse" | |
600 | Tells a Perl interpreter to parse a Perl script. See perlembed. | |
601 | .Sp | |
602 | .Vb 1 | |
603 | \& int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) | |
604 | .Ve | |
605 | .IP "perl_run" 8 | |
606 | .IX Item "perl_run" | |
607 | Tells a Perl interpreter to run. See perlembed. | |
608 | .Sp | |
609 | .Vb 1 | |
610 | \& int perl_run(PerlInterpreter* interp) | |
611 | .Ve | |
612 | .IP "require_pv" 8 | |
613 | .IX Item "require_pv" | |
614 | Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument. It is | |
615 | analogous to the Perl code \f(CW\*(C`eval "require '$file'"\*(C'\fR. It's even | |
616 | implemented that way; consider using Perl_load_module instead. | |
617 | .Sp | |
618 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
619 | .Sp | |
620 | .Vb 1 | |
621 | \& void require_pv(const char* pv) | |
622 | .Ve | |
623 | .SH "Functions in file pp_pack.c" | |
624 | .IX Header "Functions in file pp_pack.c" | |
625 | .IP "pack_cat" 8 | |
626 | .IX Item "pack_cat" | |
627 | The engine implementing \fIpack()\fR Perl function. | |
628 | .Sp | |
629 | .Vb 1 | |
630 | \& void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) | |
631 | .Ve | |
632 | .IP "unpack_str" 8 | |
633 | .IX Item "unpack_str" | |
634 | The engine implementing \fIunpack()\fR Perl function. | |
635 | .Sp | |
636 | .Vb 1 | |
637 | \& I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) | |
638 | .Ve | |
639 | .SH "Global Variables" | |
640 | .IX Header "Global Variables" | |
641 | .IP "PL_modglobal" 8 | |
642 | .IX Item "PL_modglobal" | |
643 | \&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global \s-1HV\s0 for use by | |
644 | extensions that need to keep information on a per-interpreter basis. | |
645 | In a pinch, it can also be used as a symbol table for extensions | |
646 | to share data among each other. It is a good idea to use keys | |
647 | prefixed by the package name of the extension that owns the data. | |
648 | .Sp | |
649 | .Vb 1 | |
650 | \& HV* PL_modglobal | |
651 | .Ve | |
652 | .IP "PL_na" 8 | |
653 | .IX Item "PL_na" | |
654 | A convenience variable which is typically used with \f(CW\*(C`SvPV\*(C'\fR when one | |
655 | doesn't care about the length of the string. It is usually more efficient | |
656 | to either declare a local variable and use that instead or to use the | |
657 | \&\f(CW\*(C`SvPV_nolen\*(C'\fR macro. | |
658 | .Sp | |
659 | .Vb 1 | |
660 | \& STRLEN PL_na | |
661 | .Ve | |
662 | .IP "PL_sv_no" 8 | |
663 | .IX Item "PL_sv_no" | |
664 | This is the \f(CW\*(C`false\*(C'\fR \s-1SV\s0. See \f(CW\*(C`PL_sv_yes\*(C'\fR. Always refer to this as | |
665 | \&\f(CW&PL_sv_no\fR. | |
666 | .Sp | |
667 | .Vb 1 | |
668 | \& SV PL_sv_no | |
669 | .Ve | |
670 | .IP "PL_sv_undef" 8 | |
671 | .IX Item "PL_sv_undef" | |
672 | This is the \f(CW\*(C`undef\*(C'\fR \s-1SV\s0. Always refer to this as \f(CW&PL_sv_undef\fR. | |
673 | .Sp | |
674 | .Vb 1 | |
675 | \& SV PL_sv_undef | |
676 | .Ve | |
677 | .IP "PL_sv_yes" 8 | |
678 | .IX Item "PL_sv_yes" | |
679 | This is the \f(CW\*(C`true\*(C'\fR \s-1SV\s0. See \f(CW\*(C`PL_sv_no\*(C'\fR. Always refer to this as | |
680 | \&\f(CW&PL_sv_yes\fR. | |
681 | .Sp | |
682 | .Vb 1 | |
683 | \& SV PL_sv_yes | |
684 | .Ve | |
685 | .SH "GV Functions" | |
686 | .IX Header "GV Functions" | |
687 | .IP "GvSV" 8 | |
688 | .IX Item "GvSV" | |
689 | Return the \s-1SV\s0 from the \s-1GV\s0. | |
690 | .Sp | |
691 | .Vb 1 | |
692 | \& SV* GvSV(GV* gv) | |
693 | .Ve | |
694 | .IP "gv_fetchmeth" 8 | |
695 | .IX Item "gv_fetchmeth" | |
696 | Returns the glob with the given \f(CW\*(C`name\*(C'\fR and a defined subroutine or | |
697 | \&\f(CW\*(C`NULL\*(C'\fR. The glob lives in the given \f(CW\*(C`stash\*(C'\fR, or in the stashes | |
698 | accessible via \f(CW@ISA\fR and \s-1UNIVERSAL::\s0. | |
699 | .Sp | |
700 | The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1. If \f(CW\*(C`level==0\*(C'\fR, as a | |
701 | side-effect creates a glob with the given \f(CW\*(C`name\*(C'\fR in the given \f(CW\*(C`stash\*(C'\fR | |
702 | which in the case of success contains an alias for the subroutine, and sets | |
703 | up caching info for this glob. Similarly for all the searched stashes. | |
704 | .Sp | |
705 | This function grants \f(CW"SUPER"\fR token as a postfix of the stash name. The | |
706 | \&\s-1GV\s0 returned from \f(CW\*(C`gv_fetchmeth\*(C'\fR may be a method cache entry, which is not | |
707 | visible to Perl code. So when calling \f(CW\*(C`call_sv\*(C'\fR, you should not use | |
708 | the \s-1GV\s0 directly; instead, you should use the method's \s-1CV\s0, which can be | |
709 | obtained from the \s-1GV\s0 with the \f(CW\*(C`GvCV\*(C'\fR macro. | |
710 | .Sp | |
711 | .Vb 1 | |
712 | \& GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) | |
713 | .Ve | |
714 | .IP "gv_fetchmethod" 8 | |
715 | .IX Item "gv_fetchmethod" | |
716 | See gv_fetchmethod_autoload. | |
717 | .Sp | |
718 | .Vb 1 | |
719 | \& GV* gv_fetchmethod(HV* stash, const char* name) | |
720 | .Ve | |
721 | .IP "gv_fetchmethod_autoload" 8 | |
722 | .IX Item "gv_fetchmethod_autoload" | |
723 | Returns the glob which contains the subroutine to call to invoke the method | |
724 | on the \f(CW\*(C`stash\*(C'\fR. In fact in the presence of autoloading this may be the | |
725 | glob for \*(L"\s-1AUTOLOAD\s0\*(R". In this case the corresponding variable \f(CW$AUTOLOAD\fR is | |
726 | already setup. | |
727 | .Sp | |
728 | The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether | |
729 | \&\s-1AUTOLOAD\s0 lookup is performed if the given method is not present: non-zero | |
730 | means yes, look for \s-1AUTOLOAD\s0; zero means no, don't look for \s-1AUTOLOAD\s0. | |
731 | Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR | |
732 | with a non-zero \f(CW\*(C`autoload\*(C'\fR parameter. | |
733 | .Sp | |
734 | These functions grant \f(CW"SUPER"\fR token as a prefix of the method name. Note | |
735 | that if you want to keep the returned glob for a long time, you need to | |
736 | check for it being \*(L"\s-1AUTOLOAD\s0\*(R", since at the later time the call may load a | |
737 | different subroutine due to \f(CW$AUTOLOAD\fR changing its value. Use the glob | |
738 | created via a side effect to do this. | |
739 | .Sp | |
740 | These functions have the same side-effects and as \f(CW\*(C`gv_fetchmeth\*(C'\fR with | |
741 | \&\f(CW\*(C`level==0\*(C'\fR. \f(CW\*(C`name\*(C'\fR should be writable if contains \f(CW':'\fR or \f(CW\*(C`' | |
742 | \&''\*(C'\fR. The warning against passing the \s-1GV\s0 returned by \f(CW\*(C`gv_fetchmeth\*(C'\fR to | |
743 | \&\f(CW\*(C`call_sv\*(C'\fR apply equally to these functions. | |
744 | .Sp | |
745 | .Vb 1 | |
746 | \& GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) | |
747 | .Ve | |
748 | .IP "gv_fetchmeth_autoload" 8 | |
749 | .IX Item "gv_fetchmeth_autoload" | |
750 | Same as \fIgv_fetchmeth()\fR, but looks for autoloaded subroutines too. | |
751 | Returns a glob for the subroutine. | |
752 | .Sp | |
753 | For an autoloaded subroutine without a \s-1GV\s0, will create a \s-1GV\s0 even | |
754 | if \f(CW\*(C`level < 0\*(C'\fR. For an autoloaded subroutine without a stub, \fIGvCV()\fR | |
755 | of the result may be zero. | |
756 | .Sp | |
757 | .Vb 1 | |
758 | \& GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) | |
759 | .Ve | |
760 | .IP "gv_stashpv" 8 | |
761 | .IX Item "gv_stashpv" | |
762 | Returns a pointer to the stash for a specified package. \f(CW\*(C`name\*(C'\fR should | |
763 | be a valid \s-1UTF\-8\s0 string. If \f(CW\*(C`create\*(C'\fR is set then the package will be | |
764 | created if it does not already exist. If \f(CW\*(C`create\*(C'\fR is not set and the | |
765 | package does not exist then \s-1NULL\s0 is returned. | |
766 | .Sp | |
767 | .Vb 1 | |
768 | \& HV* gv_stashpv(const char* name, I32 create) | |
769 | .Ve | |
770 | .IP "gv_stashsv" 8 | |
771 | .IX Item "gv_stashsv" | |
772 | Returns a pointer to the stash for a specified package, which must be a | |
773 | valid \s-1UTF\-8\s0 string. See \f(CW\*(C`gv_stashpv\*(C'\fR. | |
774 | .Sp | |
775 | .Vb 1 | |
776 | \& HV* gv_stashsv(SV* sv, I32 create) | |
777 | .Ve | |
778 | .SH "Handy Values" | |
779 | .IX Header "Handy Values" | |
780 | .IP "HEf_SVKEY" 8 | |
781 | .IX Item "HEf_SVKEY" | |
782 | This flag, used in the length slot of hash entries and magic structures, | |
783 | specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer | |
784 | is to be expected. (For information only\*(--not to be used). | |
785 | .IP "Nullch" 8 | |
786 | .IX Item "Nullch" | |
787 | Null character pointer. | |
788 | =for hackers | |
789 | Found in file handy.h | |
790 | .IP "Nullsv" 8 | |
791 | .IX Item "Nullsv" | |
792 | Null \s-1SV\s0 pointer. | |
793 | .SH "Hash Manipulation Functions" | |
794 | .IX Header "Hash Manipulation Functions" | |
795 | .IP "get_hv" 8 | |
796 | .IX Item "get_hv" | |
797 | Returns the \s-1HV\s0 of the specified Perl hash. If \f(CW\*(C`create\*(C'\fR is set and the | |
798 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
799 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
800 | .Sp | |
801 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
802 | .Sp | |
803 | .Vb 1 | |
804 | \& HV* get_hv(const char* name, I32 create) | |
805 | .Ve | |
806 | .IP "HeHASH" 8 | |
807 | .IX Item "HeHASH" | |
808 | Returns the computed hash stored in the hash entry. | |
809 | .Sp | |
810 | .Vb 1 | |
811 | \& U32 HeHASH(HE* he) | |
812 | .Ve | |
813 | .IP "HeKEY" 8 | |
814 | .IX Item "HeKEY" | |
815 | Returns the actual pointer stored in the key slot of the hash entry. The | |
816 | pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of | |
817 | \&\f(CW\*(C`HeKLEN()\*(C'\fR. Can be assigned to. The \f(CW\*(C`HePV()\*(C'\fR or \f(CW\*(C`HeSVKEY()\*(C'\fR macros are | |
818 | usually preferable for finding the value of a key. | |
819 | .Sp | |
820 | .Vb 1 | |
821 | \& void* HeKEY(HE* he) | |
822 | .Ve | |
823 | .IP "HeKLEN" 8 | |
824 | .IX Item "HeKLEN" | |
825 | If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry | |
826 | holds an \f(CW\*(C`SV*\*(C'\fR key. Otherwise, holds the actual length of the key. Can | |
827 | be assigned to. The \f(CW\*(C`HePV()\*(C'\fR macro is usually preferable for finding key | |
828 | lengths. | |
829 | .Sp | |
830 | .Vb 1 | |
831 | \& STRLEN HeKLEN(HE* he) | |
832 | .Ve | |
833 | .IP "HePV" 8 | |
834 | .IX Item "HePV" | |
835 | Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any | |
836 | necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The length of the string | |
837 | 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 | |
838 | not care about what the length of the key is, you may use the global | |
839 | variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local | |
840 | variable. Remember though, that hash keys in perl are free to contain | |
841 | embedded nulls, so using \f(CW\*(C`strlen()\*(C'\fR or similar is not a good way to find | |
842 | the length of hash keys. This is very similar to the \f(CW\*(C`SvPV()\*(C'\fR macro | |
843 | described elsewhere in this document. | |
844 | .Sp | |
845 | .Vb 1 | |
846 | \& char* HePV(HE* he, STRLEN len) | |
847 | .Ve | |
848 | .IP "HeSVKEY" 8 | |
849 | .IX Item "HeSVKEY" | |
850 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`Nullsv\*(C'\fR if the hash entry does not | |
851 | contain an \f(CW\*(C`SV*\*(C'\fR key. | |
852 | .Sp | |
853 | .Vb 1 | |
854 | \& SV* HeSVKEY(HE* he) | |
855 | .Ve | |
856 | .IP "HeSVKEY_force" 8 | |
857 | .IX Item "HeSVKEY_force" | |
858 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR. Will create and return a temporary mortal | |
859 | \&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key. | |
860 | .Sp | |
861 | .Vb 1 | |
862 | \& SV* HeSVKEY_force(HE* he) | |
863 | .Ve | |
864 | .IP "HeSVKEY_set" 8 | |
865 | .IX Item "HeSVKEY_set" | |
866 | Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to | |
867 | indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same | |
868 | \&\f(CW\*(C`SV*\*(C'\fR. | |
869 | .Sp | |
870 | .Vb 1 | |
871 | \& SV* HeSVKEY_set(HE* he, SV* sv) | |
872 | .Ve | |
873 | .IP "HeVAL" 8 | |
874 | .IX Item "HeVAL" | |
875 | Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR) stored in the hash entry. | |
876 | .Sp | |
877 | .Vb 1 | |
878 | \& SV* HeVAL(HE* he) | |
879 | .Ve | |
880 | .IP "HvNAME" 8 | |
881 | .IX Item "HvNAME" | |
882 | Returns the package name of a stash. See \f(CW\*(C`SvSTASH\*(C'\fR, \f(CW\*(C`CvSTASH\*(C'\fR. | |
883 | .Sp | |
884 | .Vb 1 | |
885 | \& char* HvNAME(HV* stash) | |
886 | .Ve | |
887 | .IP "hv_clear" 8 | |
888 | .IX Item "hv_clear" | |
889 | Clears a hash, making it empty. | |
890 | .Sp | |
891 | .Vb 1 | |
892 | \& void hv_clear(HV* tb) | |
893 | .Ve | |
894 | .IP "hv_delete" 8 | |
895 | .IX Item "hv_delete" | |
896 | Deletes a key/value pair in the hash. The value \s-1SV\s0 is removed from the | |
897 | hash and returned to the caller. The \f(CW\*(C`klen\*(C'\fR is the length of the key. | |
898 | The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if set to G_DISCARD then \s-1NULL\s0 | |
899 | will be returned. | |
900 | .Sp | |
901 | .Vb 1 | |
902 | \& SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags) | |
903 | .Ve | |
904 | .IP "hv_delete_ent" 8 | |
905 | .IX Item "hv_delete_ent" | |
906 | Deletes a key/value pair in the hash. The value \s-1SV\s0 is removed from the | |
907 | hash and returned to the caller. The \f(CW\*(C`flags\*(C'\fR value will normally be zero; | |
908 | if set to G_DISCARD then \s-1NULL\s0 will be returned. \f(CW\*(C`hash\*(C'\fR can be a valid | |
909 | precomputed hash value, or 0 to ask for it to be computed. | |
910 | .Sp | |
911 | .Vb 1 | |
912 | \& SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash) | |
913 | .Ve | |
914 | .IP "hv_exists" 8 | |
915 | .IX Item "hv_exists" | |
916 | Returns a boolean indicating whether the specified hash key exists. The | |
917 | \&\f(CW\*(C`klen\*(C'\fR is the length of the key. | |
918 | .Sp | |
919 | .Vb 1 | |
920 | \& bool hv_exists(HV* tb, const char* key, I32 klen) | |
921 | .Ve | |
922 | .IP "hv_exists_ent" 8 | |
923 | .IX Item "hv_exists_ent" | |
924 | Returns a boolean indicating whether the specified hash key exists. \f(CW\*(C`hash\*(C'\fR | |
925 | can be a valid precomputed hash value, or 0 to ask for it to be | |
926 | computed. | |
927 | .Sp | |
928 | .Vb 1 | |
929 | \& bool hv_exists_ent(HV* tb, SV* key, U32 hash) | |
930 | .Ve | |
931 | .IP "hv_fetch" 8 | |
932 | .IX Item "hv_fetch" | |
933 | Returns the \s-1SV\s0 which corresponds to the specified key in the hash. The | |
934 | \&\f(CW\*(C`klen\*(C'\fR is the length of the key. If \f(CW\*(C`lval\*(C'\fR is set then the fetch will be | |
935 | part of a store. Check that the return value is non-null before | |
936 | dereferencing it to an \f(CW\*(C`SV*\*(C'\fR. | |
937 | .Sp | |
938 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
939 | information on how to use this function on tied hashes. | |
940 | .Sp | |
941 | .Vb 1 | |
942 | \& SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval) | |
943 | .Ve | |
944 | .IP "hv_fetch_ent" 8 | |
945 | .IX Item "hv_fetch_ent" | |
946 | Returns the hash entry which corresponds to the specified key in the hash. | |
947 | \&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0 | |
948 | if you want the function to compute it. \s-1IF\s0 \f(CW\*(C`lval\*(C'\fR is set then the fetch | |
949 | will be part of a store. Make sure the return value is non-null before | |
950 | accessing it. The return value when \f(CW\*(C`tb\*(C'\fR is a tied hash is a pointer to a | |
951 | static location, so be sure to make a copy of the structure if you need to | |
952 | store it somewhere. | |
953 | .Sp | |
954 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
955 | information on how to use this function on tied hashes. | |
956 | .Sp | |
957 | .Vb 1 | |
958 | \& HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) | |
959 | .Ve | |
960 | .IP "hv_iterinit" 8 | |
961 | .IX Item "hv_iterinit" | |
962 | Prepares a starting point to traverse a hash table. Returns the number of | |
963 | keys in the hash (i.e. the same as \f(CW\*(C`HvKEYS(tb)\*(C'\fR). The return value is | |
964 | currently only meaningful for hashes without tie magic. | |
965 | .Sp | |
966 | \&\s-1NOTE:\s0 Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of | |
967 | hash buckets that happen to be in use. If you still need that esoteric | |
968 | value, you can get it through the macro \f(CW\*(C`HvFILL(tb)\*(C'\fR. | |
969 | .Sp | |
970 | .Vb 1 | |
971 | \& I32 hv_iterinit(HV* tb) | |
972 | .Ve | |
973 | .IP "hv_iterkey" 8 | |
974 | .IX Item "hv_iterkey" | |
975 | Returns the key from the current position of the hash iterator. See | |
976 | \&\f(CW\*(C`hv_iterinit\*(C'\fR. | |
977 | .Sp | |
978 | .Vb 1 | |
979 | \& char* hv_iterkey(HE* entry, I32* retlen) | |
980 | .Ve | |
981 | .IP "hv_iterkeysv" 8 | |
982 | .IX Item "hv_iterkeysv" | |
983 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash | |
984 | iterator. The return value will always be a mortal copy of the key. Also | |
985 | see \f(CW\*(C`hv_iterinit\*(C'\fR. | |
986 | .Sp | |
987 | .Vb 1 | |
988 | \& SV* hv_iterkeysv(HE* entry) | |
989 | .Ve | |
990 | .IP "hv_iternext" 8 | |
991 | .IX Item "hv_iternext" | |
992 | Returns entries from a hash iterator. See \f(CW\*(C`hv_iterinit\*(C'\fR. | |
993 | .Sp | |
994 | 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 | |
995 | iterator currently points to, without losing your place or invalidating your | |
996 | iterator. Note that in this case the current entry is deleted from the hash | |
997 | with your iterator holding the last reference to it. Your iterator is flagged | |
998 | to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard | |
999 | your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to | |
1000 | trigger the resource deallocation. | |
1001 | .Sp | |
1002 | .Vb 1 | |
1003 | \& HE* hv_iternext(HV* tb) | |
1004 | .Ve | |
1005 | .IP "hv_iternextsv" 8 | |
1006 | .IX Item "hv_iternextsv" | |
1007 | 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 | |
1008 | operation. | |
1009 | .Sp | |
1010 | .Vb 1 | |
1011 | \& SV* hv_iternextsv(HV* hv, char** key, I32* retlen) | |
1012 | .Ve | |
1013 | .IP "hv_iternext_flags" 8 | |
1014 | .IX Item "hv_iternext_flags" | |
1015 | Returns entries from a hash iterator. See \f(CW\*(C`hv_iterinit\*(C'\fR and \f(CW\*(C`hv_iternext\*(C'\fR. | |
1016 | The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \s-1HV_ITERNEXT_WANTPLACEHOLDERS\s0 is | |
1017 | set the placeholders keys (for restricted hashes) will be returned in addition | |
1018 | to normal keys. By default placeholders are automatically skipped over. | |
1019 | Currently a placeholder is implemented with a value that is literally | |
1020 | <&Perl_sv_undef> (a regular \f(CW\*(C`undef\*(C'\fR value is a normal read-write \s-1SV\s0 for which | |
1021 | \&\f(CW\*(C`!SvOK\*(C'\fR is false). Note that the implementation of placeholders and | |
1022 | restricted hashes may change, and the implementation currently is | |
1023 | insufficiently abstracted for any change to be tidy. | |
1024 | .Sp | |
1025 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
1026 | removed without notice. | |
1027 | .Sp | |
1028 | .Vb 1 | |
1029 | \& HE* hv_iternext_flags(HV* tb, I32 flags) | |
1030 | .Ve | |
1031 | .IP "hv_iterval" 8 | |
1032 | .IX Item "hv_iterval" | |
1033 | Returns the value from the current position of the hash iterator. See | |
1034 | \&\f(CW\*(C`hv_iterkey\*(C'\fR. | |
1035 | .Sp | |
1036 | .Vb 1 | |
1037 | \& SV* hv_iterval(HV* tb, HE* entry) | |
1038 | .Ve | |
1039 | .IP "hv_magic" 8 | |
1040 | .IX Item "hv_magic" | |
1041 | Adds magic to a hash. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1042 | .Sp | |
1043 | .Vb 1 | |
1044 | \& void hv_magic(HV* hv, GV* gv, int how) | |
1045 | .Ve | |
1046 | .IP "hv_store" 8 | |
1047 | .IX Item "hv_store" | |
1048 | Stores an \s-1SV\s0 in a hash. The hash key is specified as \f(CW\*(C`key\*(C'\fR and \f(CW\*(C`klen\*(C'\fR is | |
1049 | the length of the key. The \f(CW\*(C`hash\*(C'\fR parameter is the precomputed hash | |
1050 | value; if it is zero then Perl will compute it. The return value will be | |
1051 | \&\s-1NULL\s0 if the operation failed or if the value did not need to be actually | |
1052 | stored within the hash (as in the case of tied hashes). Otherwise it can | |
1053 | be dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR. Note that the caller is | |
1054 | responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before | |
1055 | the call, and decrementing it if the function returned \s-1NULL\s0. | |
1056 | .Sp | |
1057 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1058 | information on how to use this function on tied hashes. | |
1059 | .Sp | |
1060 | .Vb 1 | |
1061 | \& SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash) | |
1062 | .Ve | |
1063 | .IP "hv_store_ent" 8 | |
1064 | .IX Item "hv_store_ent" | |
1065 | 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 | |
1066 | parameter is the precomputed hash value; if it is zero then Perl will | |
1067 | compute it. The return value is the new hash entry so created. It will be | |
1068 | \&\s-1NULL\s0 if the operation failed or if the value did not need to be actually | |
1069 | stored within the hash (as in the case of tied hashes). Otherwise the | |
1070 | contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros | |
1071 | described here. Note that the caller is responsible for suitably | |
1072 | incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and | |
1073 | decrementing it if the function returned \s-1NULL\s0. | |
1074 | .Sp | |
1075 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1076 | information on how to use this function on tied hashes. | |
1077 | .Sp | |
1078 | .Vb 1 | |
1079 | \& HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) | |
1080 | .Ve | |
1081 | .IP "hv_undef" 8 | |
1082 | .IX Item "hv_undef" | |
1083 | Undefines the hash. | |
1084 | .Sp | |
1085 | .Vb 1 | |
1086 | \& void hv_undef(HV* tb) | |
1087 | .Ve | |
1088 | .IP "newHV" 8 | |
1089 | .IX Item "newHV" | |
1090 | Creates a new \s-1HV\s0. The reference count is set to 1. | |
1091 | .Sp | |
1092 | .Vb 1 | |
1093 | \& HV* newHV() | |
1094 | .Ve | |
1095 | .IP "Nullhv" 8 | |
1096 | .IX Item "Nullhv" | |
1097 | Null \s-1HV\s0 pointer. | |
1098 | .SH "Magical Functions" | |
1099 | .IX Header "Magical Functions" | |
1100 | .IP "mg_clear" 8 | |
1101 | .IX Item "mg_clear" | |
1102 | Clear something magical that the \s-1SV\s0 represents. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1103 | .Sp | |
1104 | .Vb 1 | |
1105 | \& int mg_clear(SV* sv) | |
1106 | .Ve | |
1107 | .IP "mg_copy" 8 | |
1108 | .IX Item "mg_copy" | |
1109 | Copies the magic from one \s-1SV\s0 to another. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1110 | .Sp | |
1111 | .Vb 1 | |
1112 | \& int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) | |
1113 | .Ve | |
1114 | .IP "mg_find" 8 | |
1115 | .IX Item "mg_find" | |
1116 | Finds the magic pointer for type matching the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1117 | .Sp | |
1118 | .Vb 1 | |
1119 | \& MAGIC* mg_find(SV* sv, int type) | |
1120 | .Ve | |
1121 | .IP "mg_free" 8 | |
1122 | .IX Item "mg_free" | |
1123 | Free any magic storage used by the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1124 | .Sp | |
1125 | .Vb 1 | |
1126 | \& int mg_free(SV* sv) | |
1127 | .Ve | |
1128 | .IP "mg_get" 8 | |
1129 | .IX Item "mg_get" | |
1130 | Do magic after a value is retrieved from the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1131 | .Sp | |
1132 | .Vb 1 | |
1133 | \& int mg_get(SV* sv) | |
1134 | .Ve | |
1135 | .IP "mg_length" 8 | |
1136 | .IX Item "mg_length" | |
1137 | Report on the \s-1SV\s0's length. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1138 | .Sp | |
1139 | .Vb 1 | |
1140 | \& U32 mg_length(SV* sv) | |
1141 | .Ve | |
1142 | .IP "mg_magical" 8 | |
1143 | .IX Item "mg_magical" | |
1144 | Turns on the magical status of an \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1145 | .Sp | |
1146 | .Vb 1 | |
1147 | \& void mg_magical(SV* sv) | |
1148 | .Ve | |
1149 | .IP "mg_set" 8 | |
1150 | .IX Item "mg_set" | |
1151 | Do magic after a value is assigned to the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1152 | .Sp | |
1153 | .Vb 1 | |
1154 | \& int mg_set(SV* sv) | |
1155 | .Ve | |
1156 | .IP "SvGETMAGIC" 8 | |
1157 | .IX Item "SvGETMAGIC" | |
1158 | Invokes \f(CW\*(C`mg_get\*(C'\fR on an \s-1SV\s0 if it has 'get' magic. This macro evaluates its | |
1159 | argument more than once. | |
1160 | .Sp | |
1161 | .Vb 1 | |
1162 | \& void SvGETMAGIC(SV* sv) | |
1163 | .Ve | |
1164 | .IP "SvLOCK" 8 | |
1165 | .IX Item "SvLOCK" | |
1166 | Arranges for a mutual exclusion lock to be obtained on sv if a suitable module | |
1167 | has been loaded. | |
1168 | .Sp | |
1169 | .Vb 1 | |
1170 | \& void SvLOCK(SV* sv) | |
1171 | .Ve | |
1172 | .IP "SvSETMAGIC" 8 | |
1173 | .IX Item "SvSETMAGIC" | |
1174 | Invokes \f(CW\*(C`mg_set\*(C'\fR on an \s-1SV\s0 if it has 'set' magic. This macro evaluates its | |
1175 | argument more than once. | |
1176 | .Sp | |
1177 | .Vb 1 | |
1178 | \& void SvSETMAGIC(SV* sv) | |
1179 | .Ve | |
1180 | .IP "SvSetMagicSV" 8 | |
1181 | .IX Item "SvSetMagicSV" | |
1182 | Like \f(CW\*(C`SvSetSV\*(C'\fR, but does any set magic required afterwards. | |
1183 | .Sp | |
1184 | .Vb 1 | |
1185 | \& void SvSetMagicSV(SV* dsb, SV* ssv) | |
1186 | .Ve | |
1187 | .IP "SvSetMagicSV_nosteal" 8 | |
1188 | .IX Item "SvSetMagicSV_nosteal" | |
1189 | Like \f(CW\*(C`SvSetMagicSV\*(C'\fR, but does any set magic required afterwards. | |
1190 | .Sp | |
1191 | .Vb 1 | |
1192 | \& void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) | |
1193 | .Ve | |
1194 | .IP "SvSetSV" 8 | |
1195 | .IX Item "SvSetSV" | |
1196 | Calls \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as ssv. May evaluate arguments | |
1197 | more than once. | |
1198 | .Sp | |
1199 | .Vb 1 | |
1200 | \& void SvSetSV(SV* dsb, SV* ssv) | |
1201 | .Ve | |
1202 | .IP "SvSetSV_nosteal" 8 | |
1203 | .IX Item "SvSetSV_nosteal" | |
1204 | Calls a non-destructive version of \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as | |
1205 | ssv. May evaluate arguments more than once. | |
1206 | .Sp | |
1207 | .Vb 1 | |
1208 | \& void SvSetSV_nosteal(SV* dsv, SV* ssv) | |
1209 | .Ve | |
1210 | .IP "SvSHARE" 8 | |
1211 | .IX Item "SvSHARE" | |
1212 | Arranges for sv to be shared between threads if a suitable module | |
1213 | has been loaded. | |
1214 | .Sp | |
1215 | .Vb 1 | |
1216 | \& void SvSHARE(SV* sv) | |
1217 | .Ve | |
1218 | .SH "Memory Management" | |
1219 | .IX Header "Memory Management" | |
1220 | .IP "Copy" 8 | |
1221 | .IX Item "Copy" | |
1222 | The XSUB\-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the | |
1223 | source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is | |
1224 | the type. May fail on overlapping copies. See also \f(CW\*(C`Move\*(C'\fR. | |
1225 | .Sp | |
1226 | .Vb 1 | |
1227 | \& void Copy(void* src, void* dest, int nitems, type) | |
1228 | .Ve | |
1229 | .IP "Move" 8 | |
1230 | .IX Item "Move" | |
1231 | The XSUB\-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the | |
1232 | source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is | |
1233 | the type. Can do overlapping moves. See also \f(CW\*(C`Copy\*(C'\fR. | |
1234 | .Sp | |
1235 | .Vb 1 | |
1236 | \& void Move(void* src, void* dest, int nitems, type) | |
1237 | .Ve | |
1238 | .IP "New" 8 | |
1239 | .IX Item "New" | |
1240 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function. | |
1241 | .Sp | |
1242 | .Vb 1 | |
1243 | \& void New(int id, void* ptr, int nitems, type) | |
1244 | .Ve | |
1245 | .IP "Newc" 8 | |
1246 | .IX Item "Newc" | |
1247 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with | |
1248 | cast. | |
1249 | .Sp | |
1250 | .Vb 1 | |
1251 | \& void Newc(int id, void* ptr, int nitems, type, cast) | |
1252 | .Ve | |
1253 | .IP "\s-1NEWSV\s0" 8 | |
1254 | .IX Item "NEWSV" | |
1255 | Creates a new \s-1SV\s0. A non-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of | |
1256 | bytes of preallocated string space the \s-1SV\s0 should have. An extra byte for a | |
1257 | tailing \s-1NUL\s0 is also reserved. (SvPOK is not set for the \s-1SV\s0 even if string | |
1258 | space is allocated.) The reference count for the new \s-1SV\s0 is set to 1. | |
1259 | \&\f(CW\*(C`id\*(C'\fR is an integer id between 0 and 1299 (used to identify leaks). | |
1260 | .Sp | |
1261 | .Vb 1 | |
1262 | \& SV* NEWSV(int id, STRLEN len) | |
1263 | .Ve | |
1264 | .IP "Newz" 8 | |
1265 | .IX Item "Newz" | |
1266 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function. The allocated | |
1267 | memory is zeroed with \f(CW\*(C`memzero\*(C'\fR. | |
1268 | .Sp | |
1269 | .Vb 1 | |
1270 | \& void Newz(int id, void* ptr, int nitems, type) | |
1271 | .Ve | |
1272 | .IP "Poison" 8 | |
1273 | .IX Item "Poison" | |
1274 | Fill up memory with a pattern (byte 0xAB over and over again) that | |
1275 | hopefully catches attempts to access uninitialized memory. | |
1276 | .Sp | |
1277 | .Vb 1 | |
1278 | \& void Poison(void* dest, int nitems, type) | |
1279 | .Ve | |
1280 | .IP "Renew" 8 | |
1281 | .IX Item "Renew" | |
1282 | The XSUB\-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function. | |
1283 | .Sp | |
1284 | .Vb 1 | |
1285 | \& void Renew(void* ptr, int nitems, type) | |
1286 | .Ve | |
1287 | .IP "Renewc" 8 | |
1288 | .IX Item "Renewc" | |
1289 | The XSUB\-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with | |
1290 | cast. | |
1291 | .Sp | |
1292 | .Vb 1 | |
1293 | \& void Renewc(void* ptr, int nitems, type, cast) | |
1294 | .Ve | |
1295 | .IP "Safefree" 8 | |
1296 | .IX Item "Safefree" | |
1297 | The XSUB\-writer's interface to the C \f(CW\*(C`free\*(C'\fR function. | |
1298 | .Sp | |
1299 | .Vb 1 | |
1300 | \& void Safefree(void* ptr) | |
1301 | .Ve | |
1302 | .IP "savepv" 8 | |
1303 | .IX Item "savepv" | |
1304 | Perl's version of \f(CW\*(C`strdup()\*(C'\fR. Returns a pointer to a newly allocated | |
1305 | string which is a duplicate of \f(CW\*(C`pv\*(C'\fR. The size of the string is | |
1306 | determined by \f(CW\*(C`strlen()\*(C'\fR. The memory allocated for the new string can | |
1307 | be freed with the \f(CW\*(C`Safefree()\*(C'\fR function. | |
1308 | .Sp | |
1309 | .Vb 1 | |
1310 | \& char* savepv(const char* pv) | |
1311 | .Ve | |
1312 | .IP "savepvn" 8 | |
1313 | .IX Item "savepvn" | |
1314 | Perl's version of what \f(CW\*(C`strndup()\*(C'\fR would be if it existed. Returns a | |
1315 | pointer to a newly allocated string which is a duplicate of the first | |
1316 | \&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR. The memory allocated for the new string can be | |
1317 | freed with the \f(CW\*(C`Safefree()\*(C'\fR function. | |
1318 | .Sp | |
1319 | .Vb 1 | |
1320 | \& char* savepvn(const char* pv, I32 len) | |
1321 | .Ve | |
1322 | .IP "savesharedpv" 8 | |
1323 | .IX Item "savesharedpv" | |
1324 | A version of \f(CW\*(C`savepv()\*(C'\fR which allocates the duplicate string in memory | |
1325 | which is shared between threads. | |
1326 | .Sp | |
1327 | .Vb 1 | |
1328 | \& char* savesharedpv(const char* pv) | |
1329 | .Ve | |
1330 | .IP "StructCopy" 8 | |
1331 | .IX Item "StructCopy" | |
1332 | This is an architecture-independent macro to copy one structure to another. | |
1333 | .Sp | |
1334 | .Vb 1 | |
1335 | \& void StructCopy(type src, type dest, type) | |
1336 | .Ve | |
1337 | .IP "Zero" 8 | |
1338 | .IX Item "Zero" | |
1339 | The XSUB\-writer's interface to the C \f(CW\*(C`memzero\*(C'\fR function. The \f(CW\*(C`dest\*(C'\fR is the | |
1340 | destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type. | |
1341 | .Sp | |
1342 | .Vb 1 | |
1343 | \& void Zero(void* dest, int nitems, type) | |
1344 | .Ve | |
1345 | .SH "Miscellaneous Functions" | |
1346 | .IX Header "Miscellaneous Functions" | |
1347 | .IP "fbm_compile" 8 | |
1348 | .IX Item "fbm_compile" | |
1349 | Analyses the string in order to make fast searches on it using \fIfbm_instr()\fR | |
1350 | \&\*(-- the Boyer-Moore algorithm. | |
1351 | .Sp | |
1352 | .Vb 1 | |
1353 | \& void fbm_compile(SV* sv, U32 flags) | |
1354 | .Ve | |
1355 | .IP "fbm_instr" 8 | |
1356 | .IX Item "fbm_instr" | |
1357 | Returns the location of the \s-1SV\s0 in the string delimited by \f(CW\*(C`str\*(C'\fR and | |
1358 | \&\f(CW\*(C`strend\*(C'\fR. It returns \f(CW\*(C`Nullch\*(C'\fR if the string can't be found. The \f(CW\*(C`sv\*(C'\fR | |
1359 | does not have to be fbm_compiled, but the search will not be as fast | |
1360 | then. | |
1361 | .Sp | |
1362 | .Vb 1 | |
1363 | \& char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) | |
1364 | .Ve | |
1365 | .IP "form" 8 | |
1366 | .IX Item "form" | |
1367 | Takes a sprintf-style format pattern and conventional | |
1368 | (non\-SV) arguments and returns the formatted string. | |
1369 | .Sp | |
1370 | .Vb 1 | |
1371 | \& (char *) Perl_form(pTHX_ const char* pat, ...) | |
1372 | .Ve | |
1373 | .Sp | |
1374 | can be used any place a string (char *) is required: | |
1375 | .Sp | |
1376 | .Vb 1 | |
1377 | \& char * s = Perl_form("%d.%d",major,minor); | |
1378 | .Ve | |
1379 | .Sp | |
1380 | Uses a single private buffer so if you want to format several strings you | |
1381 | must explicitly copy the earlier strings away (and free the copies when you | |
1382 | are done). | |
1383 | .Sp | |
1384 | .Vb 1 | |
1385 | \& char* form(const char* pat, ...) | |
1386 | .Ve | |
1387 | .IP "getcwd_sv" 8 | |
1388 | .IX Item "getcwd_sv" | |
1389 | Fill the sv with current working directory | |
1390 | .Sp | |
1391 | .Vb 1 | |
1392 | \& int getcwd_sv(SV* sv) | |
1393 | .Ve | |
1394 | .IP "strEQ" 8 | |
1395 | .IX Item "strEQ" | |
1396 | Test two strings to see if they are equal. Returns true or false. | |
1397 | .Sp | |
1398 | .Vb 1 | |
1399 | \& bool strEQ(char* s1, char* s2) | |
1400 | .Ve | |
1401 | .IP "strGE" 8 | |
1402 | .IX Item "strGE" | |
1403 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than or equal to | |
1404 | the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1405 | .Sp | |
1406 | .Vb 1 | |
1407 | \& bool strGE(char* s1, char* s2) | |
1408 | .Ve | |
1409 | .IP "strGT" 8 | |
1410 | .IX Item "strGT" | |
1411 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than the second, | |
1412 | \&\f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1413 | .Sp | |
1414 | .Vb 1 | |
1415 | \& bool strGT(char* s1, char* s2) | |
1416 | .Ve | |
1417 | .IP "strLE" 8 | |
1418 | .IX Item "strLE" | |
1419 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than or equal to the | |
1420 | second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1421 | .Sp | |
1422 | .Vb 1 | |
1423 | \& bool strLE(char* s1, char* s2) | |
1424 | .Ve | |
1425 | .IP "strLT" 8 | |
1426 | .IX Item "strLT" | |
1427 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than the second, | |
1428 | \&\f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1429 | .Sp | |
1430 | .Vb 1 | |
1431 | \& bool strLT(char* s1, char* s2) | |
1432 | .Ve | |
1433 | .IP "strNE" 8 | |
1434 | .IX Item "strNE" | |
1435 | Test two strings to see if they are different. Returns true or | |
1436 | false. | |
1437 | .Sp | |
1438 | .Vb 1 | |
1439 | \& bool strNE(char* s1, char* s2) | |
1440 | .Ve | |
1441 | .IP "strnEQ" 8 | |
1442 | .IX Item "strnEQ" | |
1443 | Test two strings to see if they are equal. The \f(CW\*(C`len\*(C'\fR parameter indicates | |
1444 | the number of bytes to compare. Returns true or false. (A wrapper for | |
1445 | \&\f(CW\*(C`strncmp\*(C'\fR). | |
1446 | .Sp | |
1447 | .Vb 1 | |
1448 | \& bool strnEQ(char* s1, char* s2, STRLEN len) | |
1449 | .Ve | |
1450 | .IP "strnNE" 8 | |
1451 | .IX Item "strnNE" | |
1452 | Test two strings to see if they are different. The \f(CW\*(C`len\*(C'\fR parameter | |
1453 | indicates the number of bytes to compare. Returns true or false. (A | |
1454 | wrapper for \f(CW\*(C`strncmp\*(C'\fR). | |
1455 | .Sp | |
1456 | .Vb 1 | |
1457 | \& bool strnNE(char* s1, char* s2, STRLEN len) | |
1458 | .Ve | |
1459 | .SH "Numeric functions" | |
1460 | .IX Header "Numeric functions" | |
1461 | .IP "grok_bin" 8 | |
1462 | .IX Item "grok_bin" | |
1463 | converts a string representing a binary number to numeric form. | |
1464 | .Sp | |
1465 | On entry \fIstart\fR and \fI*len\fR give the string to scan, \fI*flags\fR gives | |
1466 | conversion flags, and \fIresult\fR should be \s-1NULL\s0 or a pointer to an \s-1NV\s0. | |
1467 | The scan stops at the end of the string, or the first invalid character. | |
1468 | On return \fI*len\fR is set to the length scanned string, and \fI*flags\fR gives | |
1469 | output flags. | |
1470 | .Sp | |
1471 | If the value is <= \s-1UV_MAX\s0 it is returned as a \s-1UV\s0, the output flags are clear, | |
1472 | and nothing is written to \fI*result\fR. If the value is > \s-1UV_MAX\s0 \f(CW\*(C`grok_bin\*(C'\fR | |
1473 | returns \s-1UV_MAX\s0, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, | |
1474 | and writes the value to \fI*result\fR (or the value is discarded if \fIresult\fR | |
1475 | is \s-1NULL\s0). | |
1476 | .Sp | |
1477 | The hex number may optionally be prefixed with \*(L"0b\*(R" or \*(L"b\*(R" unless | |
1478 | \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \fI*flags\fR on entry. If | |
1479 | \&\f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \fI*flags\fR then the binary | |
1480 | number may use '_' characters to separate digits. | |
1481 | .Sp | |
1482 | .Vb 1 | |
1483 | \& UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) | |
1484 | .Ve | |
1485 | .IP "grok_hex" 8 | |
1486 | .IX Item "grok_hex" | |
1487 | converts a string representing a hex number to numeric form. | |
1488 | .Sp | |
1489 | On entry \fIstart\fR and \fI*len\fR give the string to scan, \fI*flags\fR gives | |
1490 | conversion flags, and \fIresult\fR should be \s-1NULL\s0 or a pointer to an \s-1NV\s0. | |
1491 | The scan stops at the end of the string, or the first non-hex-digit character. | |
1492 | On return \fI*len\fR is set to the length scanned string, and \fI*flags\fR gives | |
1493 | output flags. | |
1494 | .Sp | |
1495 | If the value is <= \s-1UV_MAX\s0 it is returned as a \s-1UV\s0, the output flags are clear, | |
1496 | and nothing is written to \fI*result\fR. If the value is > \s-1UV_MAX\s0 \f(CW\*(C`grok_hex\*(C'\fR | |
1497 | returns \s-1UV_MAX\s0, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, | |
1498 | and writes the value to \fI*result\fR (or the value is discarded if \fIresult\fR | |
1499 | is \s-1NULL\s0). | |
1500 | .Sp | |
1501 | The hex number may optionally be prefixed with \*(L"0x\*(R" or \*(L"x\*(R" unless | |
1502 | \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \fI*flags\fR on entry. If | |
1503 | \&\f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \fI*flags\fR then the hex | |
1504 | number may use '_' characters to separate digits. | |
1505 | .Sp | |
1506 | .Vb 1 | |
1507 | \& UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) | |
1508 | .Ve | |
1509 | .IP "grok_number" 8 | |
1510 | .IX Item "grok_number" | |
1511 | Recognise (or not) a number. The type of the number is returned | |
1512 | (0 if unrecognised), otherwise it is a bit-ORed combination of | |
1513 | \&\s-1IS_NUMBER_IN_UV\s0, \s-1IS_NUMBER_GREATER_THAN_UV_MAX\s0, \s-1IS_NUMBER_NOT_INT\s0, | |
1514 | \&\s-1IS_NUMBER_NEG\s0, \s-1IS_NUMBER_INFINITY\s0, \s-1IS_NUMBER_NAN\s0 (defined in perl.h). | |
1515 | .Sp | |
1516 | If the value of the number can fit an in \s-1UV\s0, it is returned in the *valuep | |
1517 | \&\s-1IS_NUMBER_IN_UV\s0 will be set to indicate that *valuep is valid, \s-1IS_NUMBER_IN_UV\s0 | |
1518 | will never be set unless *valuep is valid, but *valuep may have been assigned | |
1519 | to during processing even though \s-1IS_NUMBER_IN_UV\s0 is not set on return. | |
1520 | If valuep is \s-1NULL\s0, \s-1IS_NUMBER_IN_UV\s0 will be set for the same cases as when | |
1521 | valuep is non\-NULL, but no actual assignment (or \s-1SEGV\s0) will occur. | |
1522 | .Sp | |
1523 | \&\s-1IS_NUMBER_NOT_INT\s0 will be set with \s-1IS_NUMBER_IN_UV\s0 if trailing decimals were | |
1524 | seen (in which case *valuep gives the true value truncated to an integer), and | |
1525 | \&\s-1IS_NUMBER_NEG\s0 if the number is negative (in which case *valuep holds the | |
1526 | absolute value). \s-1IS_NUMBER_IN_UV\s0 is not set if e notation was used or the | |
1527 | number is larger than a \s-1UV\s0. | |
1528 | .Sp | |
1529 | .Vb 1 | |
1530 | \& int grok_number(const char *pv, STRLEN len, UV *valuep) | |
1531 | .Ve | |
1532 | .IP "grok_numeric_radix" 8 | |
1533 | .IX Item "grok_numeric_radix" | |
1534 | Scan and skip for a numeric decimal separator (radix). | |
1535 | .Sp | |
1536 | .Vb 1 | |
1537 | \& bool grok_numeric_radix(const char **sp, const char *send) | |
1538 | .Ve | |
1539 | .IP "grok_oct" 8 | |
1540 | .IX Item "grok_oct" | |
1541 | .Vb 1 | |
1542 | \& UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) | |
1543 | .Ve | |
1544 | .IP "scan_bin" 8 | |
1545 | .IX Item "scan_bin" | |
1546 | For backwards compatibility. Use \f(CW\*(C`grok_bin\*(C'\fR instead. | |
1547 | .Sp | |
1548 | .Vb 1 | |
1549 | \& NV scan_bin(char* start, STRLEN len, STRLEN* retlen) | |
1550 | .Ve | |
1551 | .IP "scan_hex" 8 | |
1552 | .IX Item "scan_hex" | |
1553 | For backwards compatibility. Use \f(CW\*(C`grok_hex\*(C'\fR instead. | |
1554 | .Sp | |
1555 | .Vb 1 | |
1556 | \& NV scan_hex(char* start, STRLEN len, STRLEN* retlen) | |
1557 | .Ve | |
1558 | .IP "scan_oct" 8 | |
1559 | .IX Item "scan_oct" | |
1560 | For backwards compatibility. Use \f(CW\*(C`grok_oct\*(C'\fR instead. | |
1561 | .Sp | |
1562 | .Vb 1 | |
1563 | \& NV scan_oct(char* start, STRLEN len, STRLEN* retlen) | |
1564 | .Ve | |
1565 | .SH "Optree Manipulation Functions" | |
1566 | .IX Header "Optree Manipulation Functions" | |
1567 | .IP "cv_const_sv" 8 | |
1568 | .IX Item "cv_const_sv" | |
1569 | If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining. returns the constant | |
1570 | value returned by the sub. Otherwise, returns \s-1NULL\s0. | |
1571 | .Sp | |
1572 | Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in | |
1573 | \&\*(L"Constant Functions\*(R" in perlsub. | |
1574 | .Sp | |
1575 | .Vb 1 | |
1576 | \& SV* cv_const_sv(CV* cv) | |
1577 | .Ve | |
1578 | .IP "newCONSTSUB" 8 | |
1579 | .IX Item "newCONSTSUB" | |
1580 | Creates a constant sub equivalent to Perl \f(CW\*(C`sub FOO () { 123 }\*(C'\fR which is | |
1581 | eligible for inlining at compile\-time. | |
1582 | .Sp | |
1583 | .Vb 1 | |
1584 | \& CV* newCONSTSUB(HV* stash, char* name, SV* sv) | |
1585 | .Ve | |
1586 | .IP "newXS" 8 | |
1587 | .IX Item "newXS" | |
1588 | Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. | |
1589 | .SH "Stack Manipulation Macros" | |
1590 | .IX Header "Stack Manipulation Macros" | |
1591 | .IP "dMARK" 8 | |
1592 | .IX Item "dMARK" | |
1593 | Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the \s-1XSUB\s0. See \f(CW\*(C`MARK\*(C'\fR and | |
1594 | \&\f(CW\*(C`dORIGMARK\*(C'\fR. | |
1595 | .Sp | |
1596 | .Vb 1 | |
1597 | \& dMARK; | |
1598 | .Ve | |
1599 | .IP "dORIGMARK" 8 | |
1600 | .IX Item "dORIGMARK" | |
1601 | Saves the original stack mark for the \s-1XSUB\s0. See \f(CW\*(C`ORIGMARK\*(C'\fR. | |
1602 | .Sp | |
1603 | .Vb 1 | |
1604 | \& dORIGMARK; | |
1605 | .Ve | |
1606 | .IP "dSP" 8 | |
1607 | .IX Item "dSP" | |
1608 | Declares a local copy of perl's stack pointer for the \s-1XSUB\s0, available via | |
1609 | the \f(CW\*(C`SP\*(C'\fR macro. See \f(CW\*(C`SP\*(C'\fR. | |
1610 | .Sp | |
1611 | .Vb 1 | |
1612 | \& dSP; | |
1613 | .Ve | |
1614 | .IP "\s-1EXTEND\s0" 8 | |
1615 | .IX Item "EXTEND" | |
1616 | Used to extend the argument stack for an \s-1XSUB\s0's return values. Once | |
1617 | used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed | |
1618 | onto the stack. | |
1619 | .Sp | |
1620 | .Vb 1 | |
1621 | \& void EXTEND(SP, int nitems) | |
1622 | .Ve | |
1623 | .IP "\s-1MARK\s0" 8 | |
1624 | .IX Item "MARK" | |
1625 | Stack marker variable for the \s-1XSUB\s0. See \f(CW\*(C`dMARK\*(C'\fR. | |
1626 | .IP "\s-1ORIGMARK\s0" 8 | |
1627 | .IX Item "ORIGMARK" | |
1628 | The original stack mark for the \s-1XSUB\s0. See \f(CW\*(C`dORIGMARK\*(C'\fR. | |
1629 | .IP "POPi" 8 | |
1630 | .IX Item "POPi" | |
1631 | Pops an integer off the stack. | |
1632 | .Sp | |
1633 | .Vb 1 | |
1634 | \& IV POPi | |
1635 | .Ve | |
1636 | .IP "POPl" 8 | |
1637 | .IX Item "POPl" | |
1638 | Pops a long off the stack. | |
1639 | .Sp | |
1640 | .Vb 1 | |
1641 | \& long POPl | |
1642 | .Ve | |
1643 | .IP "POPn" 8 | |
1644 | .IX Item "POPn" | |
1645 | Pops a double off the stack. | |
1646 | .Sp | |
1647 | .Vb 1 | |
1648 | \& NV POPn | |
1649 | .Ve | |
1650 | .IP "POPp" 8 | |
1651 | .IX Item "POPp" | |
1652 | Pops a string off the stack. Deprecated. New code should provide | |
1653 | a \s-1STRLEN\s0 n_a and use POPpx. | |
1654 | .Sp | |
1655 | .Vb 1 | |
1656 | \& char* POPp | |
1657 | .Ve | |
1658 | .IP "POPpbytex" 8 | |
1659 | .IX Item "POPpbytex" | |
1660 | Pops a string off the stack which must consist of bytes i.e. characters < 256. | |
1661 | Requires a variable \s-1STRLEN\s0 n_a in scope. | |
1662 | .Sp | |
1663 | .Vb 1 | |
1664 | \& char* POPpbytex | |
1665 | .Ve | |
1666 | .IP "POPpx" 8 | |
1667 | .IX Item "POPpx" | |
1668 | Pops a string off the stack. | |
1669 | Requires a variable \s-1STRLEN\s0 n_a in scope. | |
1670 | .Sp | |
1671 | .Vb 1 | |
1672 | \& char* POPpx | |
1673 | .Ve | |
1674 | .IP "POPs" 8 | |
1675 | .IX Item "POPs" | |
1676 | Pops an \s-1SV\s0 off the stack. | |
1677 | .Sp | |
1678 | .Vb 1 | |
1679 | \& SV* POPs | |
1680 | .Ve | |
1681 | .IP "PUSHi" 8 | |
1682 | .IX Item "PUSHi" | |
1683 | Push an integer onto the stack. The stack must have room for this element. | |
1684 | Handles 'set' magic. See \f(CW\*(C`XPUSHi\*(C'\fR. | |
1685 | .Sp | |
1686 | .Vb 1 | |
1687 | \& void PUSHi(IV iv) | |
1688 | .Ve | |
1689 | .IP "\s-1PUSHMARK\s0" 8 | |
1690 | .IX Item "PUSHMARK" | |
1691 | Opening bracket for arguments on a callback. See \f(CW\*(C`PUTBACK\*(C'\fR and | |
1692 | perlcall. | |
1693 | .Sp | |
1694 | .Vb 1 | |
1695 | \& PUSHMARK; | |
1696 | .Ve | |
1697 | .IP "PUSHn" 8 | |
1698 | .IX Item "PUSHn" | |
1699 | Push a double onto the stack. The stack must have room for this element. | |
1700 | Handles 'set' magic. See \f(CW\*(C`XPUSHn\*(C'\fR. | |
1701 | .Sp | |
1702 | .Vb 1 | |
1703 | \& void PUSHn(NV nv) | |
1704 | .Ve | |
1705 | .IP "PUSHp" 8 | |
1706 | .IX Item "PUSHp" | |
1707 | Push a string onto the stack. The stack must have room for this element. | |
1708 | The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles 'set' magic. See | |
1709 | \&\f(CW\*(C`XPUSHp\*(C'\fR. | |
1710 | .Sp | |
1711 | .Vb 1 | |
1712 | \& void PUSHp(char* str, STRLEN len) | |
1713 | .Ve | |
1714 | .IP "PUSHs" 8 | |
1715 | .IX Item "PUSHs" | |
1716 | Push an \s-1SV\s0 onto the stack. The stack must have room for this element. | |
1717 | Does not handle 'set' magic. See \f(CW\*(C`XPUSHs\*(C'\fR. | |
1718 | .Sp | |
1719 | .Vb 1 | |
1720 | \& void PUSHs(SV* sv) | |
1721 | .Ve | |
1722 | .IP "PUSHu" 8 | |
1723 | .IX Item "PUSHu" | |
1724 | Push an unsigned integer onto the stack. The stack must have room for this | |
1725 | element. See \f(CW\*(C`XPUSHu\*(C'\fR. | |
1726 | .Sp | |
1727 | .Vb 1 | |
1728 | \& void PUSHu(UV uv) | |
1729 | .Ve | |
1730 | .IP "\s-1PUTBACK\s0" 8 | |
1731 | .IX Item "PUTBACK" | |
1732 | Closing bracket for \s-1XSUB\s0 arguments. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. | |
1733 | See \f(CW\*(C`PUSHMARK\*(C'\fR and perlcall for other uses. | |
1734 | .Sp | |
1735 | .Vb 1 | |
1736 | \& PUTBACK; | |
1737 | .Ve | |
1738 | .IP "\s-1SP\s0" 8 | |
1739 | .IX Item "SP" | |
1740 | Stack pointer. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. See \f(CW\*(C`dSP\*(C'\fR and | |
1741 | \&\f(CW\*(C`SPAGAIN\*(C'\fR. | |
1742 | .IP "\s-1SPAGAIN\s0" 8 | |
1743 | .IX Item "SPAGAIN" | |
1744 | Refetch the stack pointer. Used after a callback. See perlcall. | |
1745 | .Sp | |
1746 | .Vb 1 | |
1747 | \& SPAGAIN; | |
1748 | .Ve | |
1749 | .IP "XPUSHi" 8 | |
1750 | .IX Item "XPUSHi" | |
1751 | Push an integer onto the stack, extending the stack if necessary. Handles | |
1752 | \&'set' magic. See \f(CW\*(C`PUSHi\*(C'\fR. | |
1753 | .Sp | |
1754 | .Vb 1 | |
1755 | \& void XPUSHi(IV iv) | |
1756 | .Ve | |
1757 | .IP "XPUSHn" 8 | |
1758 | .IX Item "XPUSHn" | |
1759 | Push a double onto the stack, extending the stack if necessary. Handles | |
1760 | \&'set' magic. See \f(CW\*(C`PUSHn\*(C'\fR. | |
1761 | .Sp | |
1762 | .Vb 1 | |
1763 | \& void XPUSHn(NV nv) | |
1764 | .Ve | |
1765 | .IP "XPUSHp" 8 | |
1766 | .IX Item "XPUSHp" | |
1767 | Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR | |
1768 | indicates the length of the string. Handles 'set' magic. See | |
1769 | \&\f(CW\*(C`PUSHp\*(C'\fR. | |
1770 | .Sp | |
1771 | .Vb 1 | |
1772 | \& void XPUSHp(char* str, STRLEN len) | |
1773 | .Ve | |
1774 | .IP "XPUSHs" 8 | |
1775 | .IX Item "XPUSHs" | |
1776 | Push an \s-1SV\s0 onto the stack, extending the stack if necessary. Does not | |
1777 | handle 'set' magic. See \f(CW\*(C`PUSHs\*(C'\fR. | |
1778 | .Sp | |
1779 | .Vb 1 | |
1780 | \& void XPUSHs(SV* sv) | |
1781 | .Ve | |
1782 | .IP "XPUSHu" 8 | |
1783 | .IX Item "XPUSHu" | |
1784 | Push an unsigned integer onto the stack, extending the stack if necessary. | |
1785 | See \f(CW\*(C`PUSHu\*(C'\fR. | |
1786 | .Sp | |
1787 | .Vb 1 | |
1788 | \& void XPUSHu(UV uv) | |
1789 | .Ve | |
1790 | .IP "\s-1XSRETURN\s0" 8 | |
1791 | .IX Item "XSRETURN" | |
1792 | Return from \s-1XSUB\s0, indicating number of items on the stack. This is usually | |
1793 | handled by \f(CW\*(C`xsubpp\*(C'\fR. | |
1794 | .Sp | |
1795 | .Vb 1 | |
1796 | \& void XSRETURN(int nitems) | |
1797 | .Ve | |
1798 | .IP "\s-1XSRETURN_IV\s0" 8 | |
1799 | .IX Item "XSRETURN_IV" | |
1800 | Return an integer from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mIV\*(C'\fR. | |
1801 | .Sp | |
1802 | .Vb 1 | |
1803 | \& void XSRETURN_IV(IV iv) | |
1804 | .Ve | |
1805 | .IP "\s-1XSRETURN_NO\s0" 8 | |
1806 | .IX Item "XSRETURN_NO" | |
1807 | Return \f(CW&PL_sv_no\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mNO\*(C'\fR. | |
1808 | .Sp | |
1809 | .Vb 1 | |
1810 | \& XSRETURN_NO; | |
1811 | .Ve | |
1812 | .IP "\s-1XSRETURN_NV\s0" 8 | |
1813 | .IX Item "XSRETURN_NV" | |
1814 | Return a double from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mNV\*(C'\fR. | |
1815 | .Sp | |
1816 | .Vb 1 | |
1817 | \& void XSRETURN_NV(NV nv) | |
1818 | .Ve | |
1819 | .IP "\s-1XSRETURN_PV\s0" 8 | |
1820 | .IX Item "XSRETURN_PV" | |
1821 | Return a copy of a string from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mPV\*(C'\fR. | |
1822 | .Sp | |
1823 | .Vb 1 | |
1824 | \& void XSRETURN_PV(char* str) | |
1825 | .Ve | |
1826 | .IP "\s-1XSRETURN_UNDEF\s0" 8 | |
1827 | .IX Item "XSRETURN_UNDEF" | |
1828 | Return \f(CW&PL_sv_undef\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR. | |
1829 | .Sp | |
1830 | .Vb 1 | |
1831 | \& XSRETURN_UNDEF; | |
1832 | .Ve | |
1833 | .IP "\s-1XSRETURN_YES\s0" 8 | |
1834 | .IX Item "XSRETURN_YES" | |
1835 | Return \f(CW&PL_sv_yes\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mYES\*(C'\fR. | |
1836 | .Sp | |
1837 | .Vb 1 | |
1838 | \& XSRETURN_YES; | |
1839 | .Ve | |
1840 | .IP "XST_mIV" 8 | |
1841 | .IX Item "XST_mIV" | |
1842 | Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The | |
1843 | value is stored in a new mortal \s-1SV\s0. | |
1844 | .Sp | |
1845 | .Vb 1 | |
1846 | \& void XST_mIV(int pos, IV iv) | |
1847 | .Ve | |
1848 | .IP "XST_mNO" 8 | |
1849 | .IX Item "XST_mNO" | |
1850 | Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
1851 | stack. | |
1852 | .Sp | |
1853 | .Vb 1 | |
1854 | \& void XST_mNO(int pos) | |
1855 | .Ve | |
1856 | .IP "XST_mNV" 8 | |
1857 | .IX Item "XST_mNV" | |
1858 | Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The value | |
1859 | is stored in a new mortal \s-1SV\s0. | |
1860 | .Sp | |
1861 | .Vb 1 | |
1862 | \& void XST_mNV(int pos, NV nv) | |
1863 | .Ve | |
1864 | .IP "XST_mPV" 8 | |
1865 | .IX Item "XST_mPV" | |
1866 | Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. | |
1867 | The value is stored in a new mortal \s-1SV\s0. | |
1868 | .Sp | |
1869 | .Vb 1 | |
1870 | \& void XST_mPV(int pos, char* str) | |
1871 | .Ve | |
1872 | .IP "XST_mUNDEF" 8 | |
1873 | .IX Item "XST_mUNDEF" | |
1874 | Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
1875 | stack. | |
1876 | .Sp | |
1877 | .Vb 1 | |
1878 | \& void XST_mUNDEF(int pos) | |
1879 | .Ve | |
1880 | .IP "XST_mYES" 8 | |
1881 | .IX Item "XST_mYES" | |
1882 | Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
1883 | stack. | |
1884 | .Sp | |
1885 | .Vb 1 | |
1886 | \& void XST_mYES(int pos) | |
1887 | .Ve | |
1888 | .SH "SV Flags" | |
1889 | .IX Header "SV Flags" | |
1890 | .IP "svtype" 8 | |
1891 | .IX Item "svtype" | |
1892 | An enum of flags for Perl types. These are found in the file \fBsv.h\fR | |
1893 | in the \f(CW\*(C`svtype\*(C'\fR enum. Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro. | |
1894 | .IP "SVt_IV" 8 | |
1895 | .IX Item "SVt_IV" | |
1896 | Integer type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
1897 | .IP "SVt_NV" 8 | |
1898 | .IX Item "SVt_NV" | |
1899 | Double type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
1900 | .IP "SVt_PV" 8 | |
1901 | .IX Item "SVt_PV" | |
1902 | Pointer type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
1903 | .IP "SVt_PVAV" 8 | |
1904 | .IX Item "SVt_PVAV" | |
1905 | Type flag for arrays. See \f(CW\*(C`svtype\*(C'\fR. | |
1906 | .IP "SVt_PVCV" 8 | |
1907 | .IX Item "SVt_PVCV" | |
1908 | Type flag for code refs. See \f(CW\*(C`svtype\*(C'\fR. | |
1909 | .IP "SVt_PVHV" 8 | |
1910 | .IX Item "SVt_PVHV" | |
1911 | Type flag for hashes. See \f(CW\*(C`svtype\*(C'\fR. | |
1912 | .IP "SVt_PVMG" 8 | |
1913 | .IX Item "SVt_PVMG" | |
1914 | Type flag for blessed scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
1915 | .SH "SV Manipulation Functions" | |
1916 | .IX Header "SV Manipulation Functions" | |
1917 | .IP "get_sv" 8 | |
1918 | .IX Item "get_sv" | |
1919 | Returns the \s-1SV\s0 of the specified Perl scalar. If \f(CW\*(C`create\*(C'\fR is set and the | |
1920 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
1921 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
1922 | .Sp | |
1923 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
1924 | .Sp | |
1925 | .Vb 1 | |
1926 | \& SV* get_sv(const char* name, I32 create) | |
1927 | .Ve | |
1928 | .IP "looks_like_number" 8 | |
1929 | .IX Item "looks_like_number" | |
1930 | Test if the content of an \s-1SV\s0 looks like a number (or is a number). | |
1931 | \&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a | |
1932 | non-numeric warning), even if your \fIatof()\fR doesn't grok them. | |
1933 | .Sp | |
1934 | .Vb 1 | |
1935 | \& I32 looks_like_number(SV* sv) | |
1936 | .Ve | |
1937 | .IP "newRV_inc" 8 | |
1938 | .IX Item "newRV_inc" | |
1939 | Creates an \s-1RV\s0 wrapper for an \s-1SV\s0. The reference count for the original \s-1SV\s0 is | |
1940 | incremented. | |
1941 | .Sp | |
1942 | .Vb 1 | |
1943 | \& SV* newRV_inc(SV* sv) | |
1944 | .Ve | |
1945 | .IP "newRV_noinc" 8 | |
1946 | .IX Item "newRV_noinc" | |
1947 | Creates an \s-1RV\s0 wrapper for an \s-1SV\s0. The reference count for the original | |
1948 | \&\s-1SV\s0 is \fBnot\fR incremented. | |
1949 | .Sp | |
1950 | .Vb 1 | |
1951 | \& SV* newRV_noinc(SV *sv) | |
1952 | .Ve | |
1953 | .IP "newSV" 8 | |
1954 | .IX Item "newSV" | |
1955 | Create a new null \s-1SV\s0, or if len > 0, create a new empty SVt_PV type \s-1SV\s0 | |
1956 | with an initial \s-1PV\s0 allocation of len+1. Normally accessed via the \f(CW\*(C`NEWSV\*(C'\fR | |
1957 | macro. | |
1958 | .Sp | |
1959 | .Vb 1 | |
1960 | \& SV* newSV(STRLEN len) | |
1961 | .Ve | |
1962 | .IP "newSViv" 8 | |
1963 | .IX Item "newSViv" | |
1964 | Creates a new \s-1SV\s0 and copies an integer into it. The reference count for the | |
1965 | \&\s-1SV\s0 is set to 1. | |
1966 | .Sp | |
1967 | .Vb 1 | |
1968 | \& SV* newSViv(IV i) | |
1969 | .Ve | |
1970 | .IP "newSVnv" 8 | |
1971 | .IX Item "newSVnv" | |
1972 | Creates a new \s-1SV\s0 and copies a floating point value into it. | |
1973 | The reference count for the \s-1SV\s0 is set to 1. | |
1974 | .Sp | |
1975 | .Vb 1 | |
1976 | \& SV* newSVnv(NV n) | |
1977 | .Ve | |
1978 | .IP "newSVpv" 8 | |
1979 | .IX Item "newSVpv" | |
1980 | Creates a new \s-1SV\s0 and copies a string into it. The reference count for the | |
1981 | \&\s-1SV\s0 is set to 1. If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using | |
1982 | \&\fIstrlen()\fR. For efficiency, consider using \f(CW\*(C`newSVpvn\*(C'\fR instead. | |
1983 | .Sp | |
1984 | .Vb 1 | |
1985 | \& SV* newSVpv(const char* s, STRLEN len) | |
1986 | .Ve | |
1987 | .IP "newSVpvf" 8 | |
1988 | .IX Item "newSVpvf" | |
1989 | Creates a new \s-1SV\s0 and initializes it with the string formatted like | |
1990 | \&\f(CW\*(C`sprintf\*(C'\fR. | |
1991 | .Sp | |
1992 | .Vb 1 | |
1993 | \& SV* newSVpvf(const char* pat, ...) | |
1994 | .Ve | |
1995 | .IP "newSVpvn" 8 | |
1996 | .IX Item "newSVpvn" | |
1997 | Creates a new \s-1SV\s0 and copies a string into it. The reference count for the | |
1998 | \&\s-1SV\s0 is set to 1. Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length | |
1999 | string. You are responsible for ensuring that the source string is at least | |
2000 | \&\f(CW\*(C`len\*(C'\fR bytes long. | |
2001 | .Sp | |
2002 | .Vb 1 | |
2003 | \& SV* newSVpvn(const char* s, STRLEN len) | |
2004 | .Ve | |
2005 | .IP "newSVpvn_share" 8 | |
2006 | .IX Item "newSVpvn_share" | |
2007 | Creates a new \s-1SV\s0 with its SvPVX pointing to a shared string in the string | |
2008 | table. If the string does not already exist in the table, it is created | |
2009 | first. Turns on \s-1READONLY\s0 and \s-1FAKE\s0. The string's hash is stored in the \s-1UV\s0 | |
2010 | slot of the \s-1SV\s0; if the \f(CW\*(C`hash\*(C'\fR parameter is non\-zero, that value is used; | |
2011 | otherwise the hash is computed. The idea here is that as the string table | |
2012 | is used for shared hash keys these strings will have SvPVX == HeKEY and | |
2013 | hash lookup will avoid string compare. | |
2014 | .Sp | |
2015 | .Vb 1 | |
2016 | \& SV* newSVpvn_share(const char* s, I32 len, U32 hash) | |
2017 | .Ve | |
2018 | .IP "newSVrv" 8 | |
2019 | .IX Item "newSVrv" | |
2020 | Creates a new \s-1SV\s0 for the \s-1RV\s0, \f(CW\*(C`rv\*(C'\fR, to point to. If \f(CW\*(C`rv\*(C'\fR is not an \s-1RV\s0 then | |
2021 | it will be upgraded to one. If \f(CW\*(C`classname\*(C'\fR is non-null then the new \s-1SV\s0 will | |
2022 | be blessed in the specified package. The new \s-1SV\s0 is returned and its | |
2023 | reference count is 1. | |
2024 | .Sp | |
2025 | .Vb 1 | |
2026 | \& SV* newSVrv(SV* rv, const char* classname) | |
2027 | .Ve | |
2028 | .IP "newSVsv" 8 | |
2029 | .IX Item "newSVsv" | |
2030 | Creates a new \s-1SV\s0 which is an exact duplicate of the original \s-1SV\s0. | |
2031 | (Uses \f(CW\*(C`sv_setsv\*(C'\fR). | |
2032 | .Sp | |
2033 | .Vb 1 | |
2034 | \& SV* newSVsv(SV* old) | |
2035 | .Ve | |
2036 | .IP "newSVuv" 8 | |
2037 | .IX Item "newSVuv" | |
2038 | Creates a new \s-1SV\s0 and copies an unsigned integer into it. | |
2039 | The reference count for the \s-1SV\s0 is set to 1. | |
2040 | .Sp | |
2041 | .Vb 1 | |
2042 | \& SV* newSVuv(UV u) | |
2043 | .Ve | |
2044 | .IP "new_vstring" 8 | |
2045 | .IX Item "new_vstring" | |
2046 | Returns a pointer to the next character after the parsed | |
2047 | vstring, as well as updating the passed in sv. | |
2048 | .Sp | |
2049 | Function must be called like | |
2050 | .Sp | |
2051 | .Vb 2 | |
2052 | \& sv = NEWSV(92,5); | |
2053 | \& s = new_vstring(s,sv); | |
2054 | .Ve | |
2055 | .Sp | |
2056 | The sv must already be large enough to store the vstring | |
2057 | passed in. | |
2058 | .Sp | |
2059 | .Vb 1 | |
2060 | \& char* new_vstring(char *vstr, SV *sv) | |
2061 | .Ve | |
2062 | .IP "SvCUR" 8 | |
2063 | .IX Item "SvCUR" | |
2064 | Returns the length of the string which is in the \s-1SV\s0. See \f(CW\*(C`SvLEN\*(C'\fR. | |
2065 | .Sp | |
2066 | .Vb 1 | |
2067 | \& STRLEN SvCUR(SV* sv) | |
2068 | .Ve | |
2069 | .IP "SvCUR_set" 8 | |
2070 | .IX Item "SvCUR_set" | |
2071 | Set the length of the string which is in the \s-1SV\s0. See \f(CW\*(C`SvCUR\*(C'\fR. | |
2072 | .Sp | |
2073 | .Vb 1 | |
2074 | \& void SvCUR_set(SV* sv, STRLEN len) | |
2075 | .Ve | |
2076 | .IP "SvEND" 8 | |
2077 | .IX Item "SvEND" | |
2078 | Returns a pointer to the last character in the string which is in the \s-1SV\s0. | |
2079 | See \f(CW\*(C`SvCUR\*(C'\fR. Access the character as *(SvEND(sv)). | |
2080 | .Sp | |
2081 | .Vb 1 | |
2082 | \& char* SvEND(SV* sv) | |
2083 | .Ve | |
2084 | .IP "SvGROW" 8 | |
2085 | .IX Item "SvGROW" | |
2086 | Expands the character buffer in the \s-1SV\s0 so that it has room for the | |
2087 | indicated number of bytes (remember to reserve space for an extra trailing | |
2088 | \&\s-1NUL\s0 character). Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary. | |
2089 | Returns a pointer to the character buffer. | |
2090 | .Sp | |
2091 | .Vb 1 | |
2092 | \& char * SvGROW(SV* sv, STRLEN len) | |
2093 | .Ve | |
2094 | .IP "SvIOK" 8 | |
2095 | .IX Item "SvIOK" | |
2096 | Returns a boolean indicating whether the \s-1SV\s0 contains an integer. | |
2097 | .Sp | |
2098 | .Vb 1 | |
2099 | \& bool SvIOK(SV* sv) | |
2100 | .Ve | |
2101 | .IP "SvIOKp" 8 | |
2102 | .IX Item "SvIOKp" | |
2103 | Returns a boolean indicating whether the \s-1SV\s0 contains an integer. Checks | |
2104 | the \fBprivate\fR setting. Use \f(CW\*(C`SvIOK\*(C'\fR. | |
2105 | .Sp | |
2106 | .Vb 1 | |
2107 | \& bool SvIOKp(SV* sv) | |
2108 | .Ve | |
2109 | .IP "SvIOK_notUV" 8 | |
2110 | .IX Item "SvIOK_notUV" | |
2111 | Returns a boolean indicating whether the \s-1SV\s0 contains a signed integer. | |
2112 | .Sp | |
2113 | .Vb 1 | |
2114 | \& void SvIOK_notUV(SV* sv) | |
2115 | .Ve | |
2116 | .IP "SvIOK_off" 8 | |
2117 | .IX Item "SvIOK_off" | |
2118 | Unsets the \s-1IV\s0 status of an \s-1SV\s0. | |
2119 | .Sp | |
2120 | .Vb 1 | |
2121 | \& void SvIOK_off(SV* sv) | |
2122 | .Ve | |
2123 | .IP "SvIOK_on" 8 | |
2124 | .IX Item "SvIOK_on" | |
2125 | Tells an \s-1SV\s0 that it is an integer. | |
2126 | .Sp | |
2127 | .Vb 1 | |
2128 | \& void SvIOK_on(SV* sv) | |
2129 | .Ve | |
2130 | .IP "SvIOK_only" 8 | |
2131 | .IX Item "SvIOK_only" | |
2132 | Tells an \s-1SV\s0 that it is an integer and disables all other \s-1OK\s0 bits. | |
2133 | .Sp | |
2134 | .Vb 1 | |
2135 | \& void SvIOK_only(SV* sv) | |
2136 | .Ve | |
2137 | .IP "SvIOK_only_UV" 8 | |
2138 | .IX Item "SvIOK_only_UV" | |
2139 | Tells and \s-1SV\s0 that it is an unsigned integer and disables all other \s-1OK\s0 bits. | |
2140 | .Sp | |
2141 | .Vb 1 | |
2142 | \& void SvIOK_only_UV(SV* sv) | |
2143 | .Ve | |
2144 | .IP "SvIOK_UV" 8 | |
2145 | .IX Item "SvIOK_UV" | |
2146 | Returns a boolean indicating whether the \s-1SV\s0 contains an unsigned integer. | |
2147 | .Sp | |
2148 | .Vb 1 | |
2149 | \& void SvIOK_UV(SV* sv) | |
2150 | .Ve | |
2151 | .IP "SvIV" 8 | |
2152 | .IX Item "SvIV" | |
2153 | Coerces the given \s-1SV\s0 to an integer and returns it. See \f(CW\*(C`SvIVx\*(C'\fR for a | |
2154 | version which guarantees to evaluate sv only once. | |
2155 | .Sp | |
2156 | .Vb 1 | |
2157 | \& IV SvIV(SV* sv) | |
2158 | .Ve | |
2159 | .IP "SvIVx" 8 | |
2160 | .IX Item "SvIVx" | |
2161 | Coerces the given \s-1SV\s0 to an integer and returns it. Guarantees to evaluate | |
2162 | sv only once. Use the more efficient \f(CW\*(C`SvIV\*(C'\fR otherwise. | |
2163 | .Sp | |
2164 | .Vb 1 | |
2165 | \& IV SvIVx(SV* sv) | |
2166 | .Ve | |
2167 | .IP "SvIVX" 8 | |
2168 | .IX Item "SvIVX" | |
2169 | Returns the raw value in the \s-1SV\s0's \s-1IV\s0 slot, without checks or conversions. | |
2170 | Only use when you are sure SvIOK is true. See also \f(CW\*(C`SvIV()\*(C'\fR. | |
2171 | .Sp | |
2172 | .Vb 1 | |
2173 | \& IV SvIVX(SV* sv) | |
2174 | .Ve | |
2175 | .IP "SvLEN" 8 | |
2176 | .IX Item "SvLEN" | |
2177 | Returns the size of the string buffer in the \s-1SV\s0, not including any part | |
2178 | attributable to \f(CW\*(C`SvOOK\*(C'\fR. See \f(CW\*(C`SvCUR\*(C'\fR. | |
2179 | .Sp | |
2180 | .Vb 1 | |
2181 | \& STRLEN SvLEN(SV* sv) | |
2182 | .Ve | |
2183 | .IP "SvNIOK" 8 | |
2184 | .IX Item "SvNIOK" | |
2185 | Returns a boolean indicating whether the \s-1SV\s0 contains a number, integer or | |
2186 | double. | |
2187 | .Sp | |
2188 | .Vb 1 | |
2189 | \& bool SvNIOK(SV* sv) | |
2190 | .Ve | |
2191 | .IP "SvNIOKp" 8 | |
2192 | .IX Item "SvNIOKp" | |
2193 | Returns a boolean indicating whether the \s-1SV\s0 contains a number, integer or | |
2194 | double. Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvNIOK\*(C'\fR. | |
2195 | .Sp | |
2196 | .Vb 1 | |
2197 | \& bool SvNIOKp(SV* sv) | |
2198 | .Ve | |
2199 | .IP "SvNIOK_off" 8 | |
2200 | .IX Item "SvNIOK_off" | |
2201 | Unsets the \s-1NV/IV\s0 status of an \s-1SV\s0. | |
2202 | .Sp | |
2203 | .Vb 1 | |
2204 | \& void SvNIOK_off(SV* sv) | |
2205 | .Ve | |
2206 | .IP "SvNOK" 8 | |
2207 | .IX Item "SvNOK" | |
2208 | Returns a boolean indicating whether the \s-1SV\s0 contains a double. | |
2209 | .Sp | |
2210 | .Vb 1 | |
2211 | \& bool SvNOK(SV* sv) | |
2212 | .Ve | |
2213 | .IP "SvNOKp" 8 | |
2214 | .IX Item "SvNOKp" | |
2215 | Returns a boolean indicating whether the \s-1SV\s0 contains a double. Checks the | |
2216 | \&\fBprivate\fR setting. Use \f(CW\*(C`SvNOK\*(C'\fR. | |
2217 | .Sp | |
2218 | .Vb 1 | |
2219 | \& bool SvNOKp(SV* sv) | |
2220 | .Ve | |
2221 | .IP "SvNOK_off" 8 | |
2222 | .IX Item "SvNOK_off" | |
2223 | Unsets the \s-1NV\s0 status of an \s-1SV\s0. | |
2224 | .Sp | |
2225 | .Vb 1 | |
2226 | \& void SvNOK_off(SV* sv) | |
2227 | .Ve | |
2228 | .IP "SvNOK_on" 8 | |
2229 | .IX Item "SvNOK_on" | |
2230 | Tells an \s-1SV\s0 that it is a double. | |
2231 | .Sp | |
2232 | .Vb 1 | |
2233 | \& void SvNOK_on(SV* sv) | |
2234 | .Ve | |
2235 | .IP "SvNOK_only" 8 | |
2236 | .IX Item "SvNOK_only" | |
2237 | Tells an \s-1SV\s0 that it is a double and disables all other \s-1OK\s0 bits. | |
2238 | .Sp | |
2239 | .Vb 1 | |
2240 | \& void SvNOK_only(SV* sv) | |
2241 | .Ve | |
2242 | .IP "SvNV" 8 | |
2243 | .IX Item "SvNV" | |
2244 | Coerce the given \s-1SV\s0 to a double and return it. See \f(CW\*(C`SvNVx\*(C'\fR for a version | |
2245 | which guarantees to evaluate sv only once. | |
2246 | .Sp | |
2247 | .Vb 1 | |
2248 | \& NV SvNV(SV* sv) | |
2249 | .Ve | |
2250 | .IP "SvNVX" 8 | |
2251 | .IX Item "SvNVX" | |
2252 | Returns the raw value in the \s-1SV\s0's \s-1NV\s0 slot, without checks or conversions. | |
2253 | Only use when you are sure SvNOK is true. See also \f(CW\*(C`SvNV()\*(C'\fR. | |
2254 | .Sp | |
2255 | .Vb 1 | |
2256 | \& NV SvNVX(SV* sv) | |
2257 | .Ve | |
2258 | .IP "SvNVx" 8 | |
2259 | .IX Item "SvNVx" | |
2260 | Coerces the given \s-1SV\s0 to a double and returns it. Guarantees to evaluate | |
2261 | sv only once. Use the more efficient \f(CW\*(C`SvNV\*(C'\fR otherwise. | |
2262 | .Sp | |
2263 | .Vb 1 | |
2264 | \& NV SvNVx(SV* sv) | |
2265 | .Ve | |
2266 | .IP "SvOK" 8 | |
2267 | .IX Item "SvOK" | |
2268 | Returns a boolean indicating whether the value is an \s-1SV\s0. | |
2269 | .Sp | |
2270 | .Vb 1 | |
2271 | \& bool SvOK(SV* sv) | |
2272 | .Ve | |
2273 | .IP "SvOOK" 8 | |
2274 | .IX Item "SvOOK" | |
2275 | Returns a boolean indicating whether the SvIVX is a valid offset value for | |
2276 | the SvPVX. This hack is used internally to speed up removal of characters | |
2277 | from the beginning of a SvPV. When SvOOK is true, then the start of the | |
2278 | allocated string buffer is really (SvPVX \- SvIVX). | |
2279 | .Sp | |
2280 | .Vb 1 | |
2281 | \& bool SvOOK(SV* sv) | |
2282 | .Ve | |
2283 | .IP "SvPOK" 8 | |
2284 | .IX Item "SvPOK" | |
2285 | Returns a boolean indicating whether the \s-1SV\s0 contains a character | |
2286 | string. | |
2287 | .Sp | |
2288 | .Vb 1 | |
2289 | \& bool SvPOK(SV* sv) | |
2290 | .Ve | |
2291 | .IP "SvPOKp" 8 | |
2292 | .IX Item "SvPOKp" | |
2293 | Returns a boolean indicating whether the \s-1SV\s0 contains a character string. | |
2294 | Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvPOK\*(C'\fR. | |
2295 | .Sp | |
2296 | .Vb 1 | |
2297 | \& bool SvPOKp(SV* sv) | |
2298 | .Ve | |
2299 | .IP "SvPOK_off" 8 | |
2300 | .IX Item "SvPOK_off" | |
2301 | Unsets the \s-1PV\s0 status of an \s-1SV\s0. | |
2302 | .Sp | |
2303 | .Vb 1 | |
2304 | \& void SvPOK_off(SV* sv) | |
2305 | .Ve | |
2306 | .IP "SvPOK_on" 8 | |
2307 | .IX Item "SvPOK_on" | |
2308 | Tells an \s-1SV\s0 that it is a string. | |
2309 | .Sp | |
2310 | .Vb 1 | |
2311 | \& void SvPOK_on(SV* sv) | |
2312 | .Ve | |
2313 | .IP "SvPOK_only" 8 | |
2314 | .IX Item "SvPOK_only" | |
2315 | Tells an \s-1SV\s0 that it is a string and disables all other \s-1OK\s0 bits. | |
2316 | Will also turn off the \s-1UTF8\s0 status. | |
2317 | .Sp | |
2318 | .Vb 1 | |
2319 | \& void SvPOK_only(SV* sv) | |
2320 | .Ve | |
2321 | .IP "SvPOK_only_UTF8" 8 | |
2322 | .IX Item "SvPOK_only_UTF8" | |
2323 | Tells an \s-1SV\s0 that it is a string and disables all other \s-1OK\s0 bits, | |
2324 | and leaves the \s-1UTF8\s0 status as it was. | |
2325 | .Sp | |
2326 | .Vb 1 | |
2327 | \& void SvPOK_only_UTF8(SV* sv) | |
2328 | .Ve | |
2329 | .IP "SvPV" 8 | |
2330 | .IX Item "SvPV" | |
2331 | Returns a pointer to the string in the \s-1SV\s0, or a stringified form of | |
2332 | the \s-1SV\s0 if the \s-1SV\s0 does not contain a string. The \s-1SV\s0 may cache the | |
2333 | stringified version becoming \f(CW\*(C`SvPOK\*(C'\fR. Handles 'get' magic. See also | |
2334 | \&\f(CW\*(C`SvPVx\*(C'\fR for a version which guarantees to evaluate sv only once. | |
2335 | .Sp | |
2336 | .Vb 1 | |
2337 | \& char* SvPV(SV* sv, STRLEN len) | |
2338 | .Ve | |
2339 | .IP "SvPVbyte" 8 | |
2340 | .IX Item "SvPVbyte" | |
2341 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to byte representation first if necessary. | |
2342 | .Sp | |
2343 | .Vb 1 | |
2344 | \& char* SvPVbyte(SV* sv, STRLEN len) | |
2345 | .Ve | |
2346 | .IP "SvPVbytex" 8 | |
2347 | .IX Item "SvPVbytex" | |
2348 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to byte representation first if necessary. | |
2349 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVbyte\*(C'\fR | |
2350 | otherwise. | |
2351 | .Sp | |
2352 | .Vb 1 | |
2353 | \& char* SvPVbytex(SV* sv, STRLEN len) | |
2354 | .Ve | |
2355 | .IP "SvPVbytex_force" 8 | |
2356 | .IX Item "SvPVbytex_force" | |
2357 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to byte representation first if necessary. | |
2358 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR | |
2359 | otherwise. | |
2360 | .Sp | |
2361 | .Vb 1 | |
2362 | \& char* SvPVbytex_force(SV* sv, STRLEN len) | |
2363 | .Ve | |
2364 | .IP "SvPVbyte_force" 8 | |
2365 | .IX Item "SvPVbyte_force" | |
2366 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to byte representation first if necessary. | |
2367 | .Sp | |
2368 | .Vb 1 | |
2369 | \& char* SvPVbyte_force(SV* sv, STRLEN len) | |
2370 | .Ve | |
2371 | .IP "SvPVbyte_nolen" 8 | |
2372 | .IX Item "SvPVbyte_nolen" | |
2373 | Like \f(CW\*(C`SvPV_nolen\*(C'\fR, but converts sv to byte representation first if necessary. | |
2374 | .Sp | |
2375 | .Vb 1 | |
2376 | \& char* SvPVbyte_nolen(SV* sv) | |
2377 | .Ve | |
2378 | .IP "SvPVutf8" 8 | |
2379 | .IX Item "SvPVutf8" | |
2380 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to utf8 first if necessary. | |
2381 | .Sp | |
2382 | .Vb 1 | |
2383 | \& char* SvPVutf8(SV* sv, STRLEN len) | |
2384 | .Ve | |
2385 | .IP "SvPVutf8x" 8 | |
2386 | .IX Item "SvPVutf8x" | |
2387 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to utf8 first if necessary. | |
2388 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVutf8\*(C'\fR | |
2389 | otherwise. | |
2390 | .Sp | |
2391 | .Vb 1 | |
2392 | \& char* SvPVutf8x(SV* sv, STRLEN len) | |
2393 | .Ve | |
2394 | .IP "SvPVutf8x_force" 8 | |
2395 | .IX Item "SvPVutf8x_force" | |
2396 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to utf8 first if necessary. | |
2397 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR | |
2398 | otherwise. | |
2399 | .Sp | |
2400 | .Vb 1 | |
2401 | \& char* SvPVutf8x_force(SV* sv, STRLEN len) | |
2402 | .Ve | |
2403 | .IP "SvPVutf8_force" 8 | |
2404 | .IX Item "SvPVutf8_force" | |
2405 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to utf8 first if necessary. | |
2406 | .Sp | |
2407 | .Vb 1 | |
2408 | \& char* SvPVutf8_force(SV* sv, STRLEN len) | |
2409 | .Ve | |
2410 | .IP "SvPVutf8_nolen" 8 | |
2411 | .IX Item "SvPVutf8_nolen" | |
2412 | Like \f(CW\*(C`SvPV_nolen\*(C'\fR, but converts sv to utf8 first if necessary. | |
2413 | .Sp | |
2414 | .Vb 1 | |
2415 | \& char* SvPVutf8_nolen(SV* sv) | |
2416 | .Ve | |
2417 | .IP "SvPVx" 8 | |
2418 | .IX Item "SvPVx" | |
2419 | A version of \f(CW\*(C`SvPV\*(C'\fR which guarantees to evaluate sv only once. | |
2420 | .Sp | |
2421 | .Vb 1 | |
2422 | \& char* SvPVx(SV* sv, STRLEN len) | |
2423 | .Ve | |
2424 | .IP "SvPVX" 8 | |
2425 | .IX Item "SvPVX" | |
2426 | Returns a pointer to the physical string in the \s-1SV\s0. The \s-1SV\s0 must contain a | |
2427 | string. | |
2428 | .Sp | |
2429 | .Vb 1 | |
2430 | \& char* SvPVX(SV* sv) | |
2431 | .Ve | |
2432 | .IP "SvPV_force" 8 | |
2433 | .IX Item "SvPV_force" | |
2434 | Like \f(CW\*(C`SvPV\*(C'\fR but will force the \s-1SV\s0 into containing just a string | |
2435 | (\f(CW\*(C`SvPOK_only\*(C'\fR). You want force if you are going to update the \f(CW\*(C`SvPVX\*(C'\fR | |
2436 | directly. | |
2437 | .Sp | |
2438 | .Vb 1 | |
2439 | \& char* SvPV_force(SV* sv, STRLEN len) | |
2440 | .Ve | |
2441 | .IP "SvPV_force_nomg" 8 | |
2442 | .IX Item "SvPV_force_nomg" | |
2443 | Like \f(CW\*(C`SvPV\*(C'\fR but will force the \s-1SV\s0 into containing just a string | |
2444 | (\f(CW\*(C`SvPOK_only\*(C'\fR). You want force if you are going to update the \f(CW\*(C`SvPVX\*(C'\fR | |
2445 | directly. Doesn't process magic. | |
2446 | .Sp | |
2447 | .Vb 1 | |
2448 | \& char* SvPV_force_nomg(SV* sv, STRLEN len) | |
2449 | .Ve | |
2450 | .IP "SvPV_nolen" 8 | |
2451 | .IX Item "SvPV_nolen" | |
2452 | Returns a pointer to the string in the \s-1SV\s0, or a stringified form of | |
2453 | the \s-1SV\s0 if the \s-1SV\s0 does not contain a string. The \s-1SV\s0 may cache the | |
2454 | stringified form becoming \f(CW\*(C`SvPOK\*(C'\fR. Handles 'get' magic. | |
2455 | .Sp | |
2456 | .Vb 1 | |
2457 | \& char* SvPV_nolen(SV* sv) | |
2458 | .Ve | |
2459 | .IP "SvREFCNT" 8 | |
2460 | .IX Item "SvREFCNT" | |
2461 | Returns the value of the object's reference count. | |
2462 | .Sp | |
2463 | .Vb 1 | |
2464 | \& U32 SvREFCNT(SV* sv) | |
2465 | .Ve | |
2466 | .IP "SvREFCNT_dec" 8 | |
2467 | .IX Item "SvREFCNT_dec" | |
2468 | Decrements the reference count of the given \s-1SV\s0. | |
2469 | .Sp | |
2470 | .Vb 1 | |
2471 | \& void SvREFCNT_dec(SV* sv) | |
2472 | .Ve | |
2473 | .IP "SvREFCNT_inc" 8 | |
2474 | .IX Item "SvREFCNT_inc" | |
2475 | Increments the reference count of the given \s-1SV\s0. | |
2476 | .Sp | |
2477 | .Vb 1 | |
2478 | \& SV* SvREFCNT_inc(SV* sv) | |
2479 | .Ve | |
2480 | .IP "SvROK" 8 | |
2481 | .IX Item "SvROK" | |
2482 | Tests if the \s-1SV\s0 is an \s-1RV\s0. | |
2483 | .Sp | |
2484 | .Vb 1 | |
2485 | \& bool SvROK(SV* sv) | |
2486 | .Ve | |
2487 | .IP "SvROK_off" 8 | |
2488 | .IX Item "SvROK_off" | |
2489 | Unsets the \s-1RV\s0 status of an \s-1SV\s0. | |
2490 | .Sp | |
2491 | .Vb 1 | |
2492 | \& void SvROK_off(SV* sv) | |
2493 | .Ve | |
2494 | .IP "SvROK_on" 8 | |
2495 | .IX Item "SvROK_on" | |
2496 | Tells an \s-1SV\s0 that it is an \s-1RV\s0. | |
2497 | .Sp | |
2498 | .Vb 1 | |
2499 | \& void SvROK_on(SV* sv) | |
2500 | .Ve | |
2501 | .IP "SvRV" 8 | |
2502 | .IX Item "SvRV" | |
2503 | Dereferences an \s-1RV\s0 to return the \s-1SV\s0. | |
2504 | .Sp | |
2505 | .Vb 1 | |
2506 | \& SV* SvRV(SV* sv) | |
2507 | .Ve | |
2508 | .IP "SvSTASH" 8 | |
2509 | .IX Item "SvSTASH" | |
2510 | Returns the stash of the \s-1SV\s0. | |
2511 | .Sp | |
2512 | .Vb 1 | |
2513 | \& HV* SvSTASH(SV* sv) | |
2514 | .Ve | |
2515 | .IP "SvTAINT" 8 | |
2516 | .IX Item "SvTAINT" | |
2517 | Taints an \s-1SV\s0 if tainting is enabled | |
2518 | .Sp | |
2519 | .Vb 1 | |
2520 | \& void SvTAINT(SV* sv) | |
2521 | .Ve | |
2522 | .IP "SvTAINTED" 8 | |
2523 | .IX Item "SvTAINTED" | |
2524 | Checks to see if an \s-1SV\s0 is tainted. Returns \s-1TRUE\s0 if it is, \s-1FALSE\s0 if | |
2525 | not. | |
2526 | .Sp | |
2527 | .Vb 1 | |
2528 | \& bool SvTAINTED(SV* sv) | |
2529 | .Ve | |
2530 | .IP "SvTAINTED_off" 8 | |
2531 | .IX Item "SvTAINTED_off" | |
2532 | Untaints an \s-1SV\s0. Be \fIvery\fR careful with this routine, as it short-circuits | |
2533 | some of Perl's fundamental security features. \s-1XS\s0 module authors should not | |
2534 | use this function unless they fully understand all the implications of | |
2535 | unconditionally untainting the value. Untainting should be done in the | |
2536 | standard perl fashion, via a carefully crafted regexp, rather than directly | |
2537 | untainting variables. | |
2538 | .Sp | |
2539 | .Vb 1 | |
2540 | \& void SvTAINTED_off(SV* sv) | |
2541 | .Ve | |
2542 | .IP "SvTAINTED_on" 8 | |
2543 | .IX Item "SvTAINTED_on" | |
2544 | Marks an \s-1SV\s0 as tainted. | |
2545 | .Sp | |
2546 | .Vb 1 | |
2547 | \& void SvTAINTED_on(SV* sv) | |
2548 | .Ve | |
2549 | .IP "SvTRUE" 8 | |
2550 | .IX Item "SvTRUE" | |
2551 | Returns a boolean indicating whether Perl would evaluate the \s-1SV\s0 as true or | |
2552 | false, defined or undefined. Does not handle 'get' magic. | |
2553 | .Sp | |
2554 | .Vb 1 | |
2555 | \& bool SvTRUE(SV* sv) | |
2556 | .Ve | |
2557 | .IP "SvTYPE" 8 | |
2558 | .IX Item "SvTYPE" | |
2559 | Returns the type of the \s-1SV\s0. See \f(CW\*(C`svtype\*(C'\fR. | |
2560 | .Sp | |
2561 | .Vb 1 | |
2562 | \& svtype SvTYPE(SV* sv) | |
2563 | .Ve | |
2564 | .IP "SvUNLOCK" 8 | |
2565 | .IX Item "SvUNLOCK" | |
2566 | Releases a mutual exclusion lock on sv if a suitable module | |
2567 | has been loaded. | |
2568 | .Sp | |
2569 | .Vb 1 | |
2570 | \& void SvUNLOCK(SV* sv) | |
2571 | .Ve | |
2572 | .IP "SvUOK" 8 | |
2573 | .IX Item "SvUOK" | |
2574 | Returns a boolean indicating whether the \s-1SV\s0 contains an unsigned integer. | |
2575 | .Sp | |
2576 | .Vb 1 | |
2577 | \& void SvUOK(SV* sv) | |
2578 | .Ve | |
2579 | .IP "SvUPGRADE" 8 | |
2580 | .IX Item "SvUPGRADE" | |
2581 | Used to upgrade an \s-1SV\s0 to a more complex form. Uses \f(CW\*(C`sv_upgrade\*(C'\fR to | |
2582 | perform the upgrade if necessary. See \f(CW\*(C`svtype\*(C'\fR. | |
2583 | .Sp | |
2584 | .Vb 1 | |
2585 | \& void SvUPGRADE(SV* sv, svtype type) | |
2586 | .Ve | |
2587 | .IP "SvUTF8" 8 | |
2588 | .IX Item "SvUTF8" | |
2589 | Returns a boolean indicating whether the \s-1SV\s0 contains \s-1UTF\-8\s0 encoded data. | |
2590 | .Sp | |
2591 | .Vb 1 | |
2592 | \& void SvUTF8(SV* sv) | |
2593 | .Ve | |
2594 | .IP "SvUTF8_off" 8 | |
2595 | .IX Item "SvUTF8_off" | |
2596 | Unsets the \s-1UTF8\s0 status of an \s-1SV\s0. | |
2597 | .Sp | |
2598 | .Vb 1 | |
2599 | \& void SvUTF8_off(SV *sv) | |
2600 | .Ve | |
2601 | .IP "SvUTF8_on" 8 | |
2602 | .IX Item "SvUTF8_on" | |
2603 | Turn on the \s-1UTF8\s0 status of an \s-1SV\s0 (the data is not changed, just the flag). | |
2604 | Do not use frivolously. | |
2605 | .Sp | |
2606 | .Vb 1 | |
2607 | \& void SvUTF8_on(SV *sv) | |
2608 | .Ve | |
2609 | .IP "SvUV" 8 | |
2610 | .IX Item "SvUV" | |
2611 | Coerces the given \s-1SV\s0 to an unsigned integer and returns it. See \f(CW\*(C`SvUVx\*(C'\fR | |
2612 | for a version which guarantees to evaluate sv only once. | |
2613 | .Sp | |
2614 | .Vb 1 | |
2615 | \& UV SvUV(SV* sv) | |
2616 | .Ve | |
2617 | .IP "SvUVX" 8 | |
2618 | .IX Item "SvUVX" | |
2619 | Returns the raw value in the \s-1SV\s0's \s-1UV\s0 slot, without checks or conversions. | |
2620 | Only use when you are sure SvIOK is true. See also \f(CW\*(C`SvUV()\*(C'\fR. | |
2621 | .Sp | |
2622 | .Vb 1 | |
2623 | \& UV SvUVX(SV* sv) | |
2624 | .Ve | |
2625 | .IP "SvUVx" 8 | |
2626 | .IX Item "SvUVx" | |
2627 | Coerces the given \s-1SV\s0 to an unsigned integer and returns it. Guarantees to | |
2628 | evaluate sv only once. Use the more efficient \f(CW\*(C`SvUV\*(C'\fR otherwise. | |
2629 | .Sp | |
2630 | .Vb 1 | |
2631 | \& UV SvUVx(SV* sv) | |
2632 | .Ve | |
2633 | .IP "sv_2bool" 8 | |
2634 | .IX Item "sv_2bool" | |
2635 | This function is only called on magical items, and is only used by | |
2636 | \&\fIsv_true()\fR or its macro equivalent. | |
2637 | .Sp | |
2638 | .Vb 1 | |
2639 | \& bool sv_2bool(SV* sv) | |
2640 | .Ve | |
2641 | .IP "sv_2cv" 8 | |
2642 | .IX Item "sv_2cv" | |
2643 | Using various gambits, try to get a \s-1CV\s0 from an \s-1SV\s0; in addition, try if | |
2644 | possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and \s-1GV\s0 associated with it. | |
2645 | .Sp | |
2646 | .Vb 1 | |
2647 | \& CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) | |
2648 | .Ve | |
2649 | .IP "sv_2io" 8 | |
2650 | .IX Item "sv_2io" | |
2651 | Using various gambits, try to get an \s-1IO\s0 from an \s-1SV:\s0 the \s-1IO\s0 slot if its a | |
2652 | \&\s-1GV\s0; or the recursive result if we're an \s-1RV\s0; or the \s-1IO\s0 slot of the symbol | |
2653 | named after the \s-1PV\s0 if we're a string. | |
2654 | .Sp | |
2655 | .Vb 1 | |
2656 | \& IO* sv_2io(SV* sv) | |
2657 | .Ve | |
2658 | .IP "sv_2iv" 8 | |
2659 | .IX Item "sv_2iv" | |
2660 | Return the integer value of an \s-1SV\s0, doing any necessary string conversion, | |
2661 | magic etc. Normally used via the \f(CW\*(C`SvIV(sv)\*(C'\fR and \f(CW\*(C`SvIVx(sv)\*(C'\fR macros. | |
2662 | .Sp | |
2663 | .Vb 1 | |
2664 | \& IV sv_2iv(SV* sv) | |
2665 | .Ve | |
2666 | .IP "sv_2mortal" 8 | |
2667 | .IX Item "sv_2mortal" | |
2668 | Marks an existing \s-1SV\s0 as mortal. The \s-1SV\s0 will be destroyed \*(L"soon\*(R", either | |
2669 | by an explicit call to \s-1FREETMPS\s0, or by an implicit call at places such as | |
2670 | statement boundaries. See also \f(CW\*(C`sv_newmortal\*(C'\fR and \f(CW\*(C`sv_mortalcopy\*(C'\fR. | |
2671 | .Sp | |
2672 | .Vb 1 | |
2673 | \& SV* sv_2mortal(SV* sv) | |
2674 | .Ve | |
2675 | .IP "sv_2nv" 8 | |
2676 | .IX Item "sv_2nv" | |
2677 | Return the num value of an \s-1SV\s0, doing any necessary string or integer | |
2678 | conversion, magic etc. Normally used via the \f(CW\*(C`SvNV(sv)\*(C'\fR and \f(CW\*(C`SvNVx(sv)\*(C'\fR | |
2679 | macros. | |
2680 | .Sp | |
2681 | .Vb 1 | |
2682 | \& NV sv_2nv(SV* sv) | |
2683 | .Ve | |
2684 | .IP "sv_2pvbyte" 8 | |
2685 | .IX Item "sv_2pvbyte" | |
2686 | Return a pointer to the byte-encoded representation of the \s-1SV\s0, and set *lp | |
2687 | to its length. May cause the \s-1SV\s0 to be downgraded from \s-1UTF8\s0 as a | |
2688 | side\-effect. | |
2689 | .Sp | |
2690 | Usually accessed via the \f(CW\*(C`SvPVbyte\*(C'\fR macro. | |
2691 | .Sp | |
2692 | .Vb 1 | |
2693 | \& char* sv_2pvbyte(SV* sv, STRLEN* lp) | |
2694 | .Ve | |
2695 | .IP "sv_2pvbyte_nolen" 8 | |
2696 | .IX Item "sv_2pvbyte_nolen" | |
2697 | Return a pointer to the byte-encoded representation of the \s-1SV\s0. | |
2698 | May cause the \s-1SV\s0 to be downgraded from \s-1UTF8\s0 as a side\-effect. | |
2699 | .Sp | |
2700 | Usually accessed via the \f(CW\*(C`SvPVbyte_nolen\*(C'\fR macro. | |
2701 | .Sp | |
2702 | .Vb 1 | |
2703 | \& char* sv_2pvbyte_nolen(SV* sv) | |
2704 | .Ve | |
2705 | .IP "sv_2pvutf8" 8 | |
2706 | .IX Item "sv_2pvutf8" | |
2707 | Return a pointer to the UTF8\-encoded representation of the \s-1SV\s0, and set *lp | |
2708 | to its length. May cause the \s-1SV\s0 to be upgraded to \s-1UTF8\s0 as a side\-effect. | |
2709 | .Sp | |
2710 | Usually accessed via the \f(CW\*(C`SvPVutf8\*(C'\fR macro. | |
2711 | .Sp | |
2712 | .Vb 1 | |
2713 | \& char* sv_2pvutf8(SV* sv, STRLEN* lp) | |
2714 | .Ve | |
2715 | .IP "sv_2pvutf8_nolen" 8 | |
2716 | .IX Item "sv_2pvutf8_nolen" | |
2717 | Return a pointer to the UTF8\-encoded representation of the \s-1SV\s0. | |
2718 | May cause the \s-1SV\s0 to be upgraded to \s-1UTF8\s0 as a side\-effect. | |
2719 | .Sp | |
2720 | Usually accessed via the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro. | |
2721 | .Sp | |
2722 | .Vb 1 | |
2723 | \& char* sv_2pvutf8_nolen(SV* sv) | |
2724 | .Ve | |
2725 | .IP "sv_2pv_flags" 8 | |
2726 | .IX Item "sv_2pv_flags" | |
2727 | Returns a pointer to the string value of an \s-1SV\s0, and sets *lp to its length. | |
2728 | If flags includes \s-1SV_GMAGIC\s0, does an \fImg_get()\fR first. Coerces sv to a string | |
2729 | if necessary. | |
2730 | Normally invoked via the \f(CW\*(C`SvPV_flags\*(C'\fR macro. \f(CW\*(C`sv_2pv()\*(C'\fR and \f(CW\*(C`sv_2pv_nomg\*(C'\fR | |
2731 | usually end up here too. | |
2732 | .Sp | |
2733 | .Vb 1 | |
2734 | \& char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags) | |
2735 | .Ve | |
2736 | .IP "sv_2pv_nolen" 8 | |
2737 | .IX Item "sv_2pv_nolen" | |
2738 | Like \f(CW\*(C`sv_2pv()\*(C'\fR, but doesn't return the length too. You should usually | |
2739 | use the macro wrapper \f(CW\*(C`SvPV_nolen(sv)\*(C'\fR instead. | |
2740 | char* sv_2pv_nolen(SV* sv) | |
2741 | .IP "sv_2uv" 8 | |
2742 | .IX Item "sv_2uv" | |
2743 | Return the unsigned integer value of an \s-1SV\s0, doing any necessary string | |
2744 | conversion, magic etc. Normally used via the \f(CW\*(C`SvUV(sv)\*(C'\fR and \f(CW\*(C`SvUVx(sv)\*(C'\fR | |
2745 | macros. | |
2746 | .Sp | |
2747 | .Vb 1 | |
2748 | \& UV sv_2uv(SV* sv) | |
2749 | .Ve | |
2750 | .IP "sv_backoff" 8 | |
2751 | .IX Item "sv_backoff" | |
2752 | Remove any string offset. You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro | |
2753 | wrapper instead. | |
2754 | .Sp | |
2755 | .Vb 1 | |
2756 | \& int sv_backoff(SV* sv) | |
2757 | .Ve | |
2758 | .IP "sv_bless" 8 | |
2759 | .IX Item "sv_bless" | |
2760 | Blesses an \s-1SV\s0 into a specified package. The \s-1SV\s0 must be an \s-1RV\s0. The package | |
2761 | must be designated by its stash (see \f(CW\*(C`gv_stashpv()\*(C'\fR). The reference count | |
2762 | of the \s-1SV\s0 is unaffected. | |
2763 | .Sp | |
2764 | .Vb 1 | |
2765 | \& SV* sv_bless(SV* sv, HV* stash) | |
2766 | .Ve | |
2767 | .IP "sv_catpv" 8 | |
2768 | .IX Item "sv_catpv" | |
2769 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. | |
2770 | If the \s-1SV\s0 has the \s-1UTF8\s0 status set, then the bytes appended should be | |
2771 | valid \s-1UTF8\s0. Handles 'get' magic, but not 'set' magic. See \f(CW\*(C`sv_catpv_mg\*(C'\fR. | |
2772 | .Sp | |
2773 | .Vb 1 | |
2774 | \& void sv_catpv(SV* sv, const char* ptr) | |
2775 | .Ve | |
2776 | .IP "sv_catpvf" 8 | |
2777 | .IX Item "sv_catpvf" | |
2778 | Processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and appends the formatted | |
2779 | output to an \s-1SV\s0. If the appended data contains \*(L"wide\*(R" characters | |
2780 | (including, but not limited to, SVs with a \s-1UTF\-8\s0 \s-1PV\s0 formatted with \f(CW%s\fR, | |
2781 | and characters >255 formatted with \f(CW%c\fR), the original \s-1SV\s0 might get | |
2782 | upgraded to \s-1UTF\-8\s0. Handles 'get' magic, but not 'set' magic. | |
2783 | \&\f(CW\*(C`SvSETMAGIC()\*(C'\fR must typically be called after calling this function | |
2784 | to handle 'set' magic. | |
2785 | .Sp | |
2786 | .Vb 1 | |
2787 | \& void sv_catpvf(SV* sv, const char* pat, ...) | |
2788 | .Ve | |
2789 | .IP "sv_catpvf_mg" 8 | |
2790 | .IX Item "sv_catpvf_mg" | |
2791 | Like \f(CW\*(C`sv_catpvf\*(C'\fR, but also handles 'set' magic. | |
2792 | .Sp | |
2793 | .Vb 1 | |
2794 | \& void sv_catpvf_mg(SV *sv, const char* pat, ...) | |
2795 | .Ve | |
2796 | .IP "sv_catpvn" 8 | |
2797 | .IX Item "sv_catpvn" | |
2798 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. The | |
2799 | \&\f(CW\*(C`len\*(C'\fR indicates number of bytes to copy. If the \s-1SV\s0 has the \s-1UTF8\s0 | |
2800 | status set, then the bytes appended should be valid \s-1UTF8\s0. | |
2801 | Handles 'get' magic, but not 'set' magic. See \f(CW\*(C`sv_catpvn_mg\*(C'\fR. | |
2802 | .Sp | |
2803 | .Vb 1 | |
2804 | \& void sv_catpvn(SV* sv, const char* ptr, STRLEN len) | |
2805 | .Ve | |
2806 | .IP "sv_catpvn_flags" 8 | |
2807 | .IX Item "sv_catpvn_flags" | |
2808 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. The | |
2809 | \&\f(CW\*(C`len\*(C'\fR indicates number of bytes to copy. If the \s-1SV\s0 has the \s-1UTF8\s0 | |
2810 | status set, then the bytes appended should be valid \s-1UTF8\s0. | |
2811 | If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`dsv\*(C'\fR if | |
2812 | appropriate, else not. \f(CW\*(C`sv_catpvn\*(C'\fR and \f(CW\*(C`sv_catpvn_nomg\*(C'\fR are implemented | |
2813 | in terms of this function. | |
2814 | .Sp | |
2815 | .Vb 1 | |
2816 | \& void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags) | |
2817 | .Ve | |
2818 | .IP "sv_catpvn_mg" 8 | |
2819 | .IX Item "sv_catpvn_mg" | |
2820 | Like \f(CW\*(C`sv_catpvn\*(C'\fR, but also handles 'set' magic. | |
2821 | .Sp | |
2822 | .Vb 1 | |
2823 | \& void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) | |
2824 | .Ve | |
2825 | .IP "sv_catpv_mg" 8 | |
2826 | .IX Item "sv_catpv_mg" | |
2827 | Like \f(CW\*(C`sv_catpv\*(C'\fR, but also handles 'set' magic. | |
2828 | .Sp | |
2829 | .Vb 1 | |
2830 | \& void sv_catpv_mg(SV *sv, const char *ptr) | |
2831 | .Ve | |
2832 | .IP "sv_catsv" 8 | |
2833 | .IX Item "sv_catsv" | |
2834 | Concatenates the string from \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR onto the end of the string in | |
2835 | \&\s-1SV\s0 \f(CW\*(C`dsv\*(C'\fR. Modifies \f(CW\*(C`dsv\*(C'\fR but not \f(CW\*(C`ssv\*(C'\fR. Handles 'get' magic, but | |
2836 | not 'set' magic. See \f(CW\*(C`sv_catsv_mg\*(C'\fR. | |
2837 | .Sp | |
2838 | .Vb 1 | |
2839 | \& void sv_catsv(SV* dsv, SV* ssv) | |
2840 | .Ve | |
2841 | .IP "sv_catsv_flags" 8 | |
2842 | .IX Item "sv_catsv_flags" | |
2843 | Concatenates the string from \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR onto the end of the string in | |
2844 | \&\s-1SV\s0 \f(CW\*(C`dsv\*(C'\fR. Modifies \f(CW\*(C`dsv\*(C'\fR but not \f(CW\*(C`ssv\*(C'\fR. If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR | |
2845 | bit set, will \f(CW\*(C`mg_get\*(C'\fR on the SVs if appropriate, else not. \f(CW\*(C`sv_catsv\*(C'\fR | |
2846 | and \f(CW\*(C`sv_catsv_nomg\*(C'\fR are implemented in terms of this function. | |
2847 | .Sp | |
2848 | .Vb 1 | |
2849 | \& void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags) | |
2850 | .Ve | |
2851 | .IP "sv_catsv_mg" 8 | |
2852 | .IX Item "sv_catsv_mg" | |
2853 | Like \f(CW\*(C`sv_catsv\*(C'\fR, but also handles 'set' magic. | |
2854 | .Sp | |
2855 | .Vb 1 | |
2856 | \& void sv_catsv_mg(SV *dstr, SV *sstr) | |
2857 | .Ve | |
2858 | .IP "sv_chop" 8 | |
2859 | .IX Item "sv_chop" | |
2860 | Efficient removal of characters from the beginning of the string buffer. | |
2861 | SvPOK(sv) must be true and the \f(CW\*(C`ptr\*(C'\fR must be a pointer to somewhere inside | |
2862 | the string buffer. The \f(CW\*(C`ptr\*(C'\fR becomes the first character of the adjusted | |
2863 | string. Uses the \*(L"\s-1OOK\s0 hack\*(R". | |
2864 | .Sp | |
2865 | .Vb 1 | |
2866 | \& void sv_chop(SV* sv, char* ptr) | |
2867 | .Ve | |
2868 | .IP "sv_clear" 8 | |
2869 | .IX Item "sv_clear" | |
2870 | Clear an \s-1SV:\s0 call any destructors, free up any memory used by the body, | |
2871 | and free the body itself. The \s-1SV\s0's head is \fInot\fR freed, although | |
2872 | its type is set to all 1's so that it won't inadvertently be assumed | |
2873 | to be live during global destruction etc. | |
2874 | This function should only be called when \s-1REFCNT\s0 is zero. Most of the time | |
2875 | you'll want to call \f(CW\*(C`sv_free()\*(C'\fR (or its macro wrapper \f(CW\*(C`SvREFCNT_dec\*(C'\fR) | |
2876 | instead. | |
2877 | .Sp | |
2878 | .Vb 1 | |
2879 | \& void sv_clear(SV* sv) | |
2880 | .Ve | |
2881 | .IP "sv_cmp" 8 | |
2882 | .IX Item "sv_cmp" | |
2883 | Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the | |
2884 | string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in | |
2885 | \&\f(CW\*(C`sv2\*(C'\fR. Is \s-1UTF\-8\s0 and 'use bytes' aware, handles get magic, and will | |
2886 | coerce its args to strings if necessary. See also \f(CW\*(C`sv_cmp_locale\*(C'\fR. | |
2887 | .Sp | |
2888 | .Vb 1 | |
2889 | \& I32 sv_cmp(SV* sv1, SV* sv2) | |
2890 | .Ve | |
2891 | .IP "sv_cmp_locale" 8 | |
2892 | .IX Item "sv_cmp_locale" | |
2893 | Compares the strings in two SVs in a locale-aware manner. Is \s-1UTF\-8\s0 and | |
2894 | \&'use bytes' aware, handles get magic, and will coerce its args to strings | |
2895 | if necessary. See also \f(CW\*(C`sv_cmp_locale\*(C'\fR. See also \f(CW\*(C`sv_cmp\*(C'\fR. | |
2896 | .Sp | |
2897 | .Vb 1 | |
2898 | \& I32 sv_cmp_locale(SV* sv1, SV* sv2) | |
2899 | .Ve | |
2900 | .IP "sv_collxfrm" 8 | |
2901 | .IX Item "sv_collxfrm" | |
2902 | Add Collate Transform magic to an \s-1SV\s0 if it doesn't already have it. | |
2903 | .Sp | |
2904 | Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the | |
2905 | scalar data of the variable, but transformed to such a format that a normal | |
2906 | memory comparison can be used to compare the data according to the locale | |
2907 | settings. | |
2908 | .Sp | |
2909 | .Vb 1 | |
2910 | \& char* sv_collxfrm(SV* sv, STRLEN* nxp) | |
2911 | .Ve | |
2912 | .IP "sv_copypv" 8 | |
2913 | .IX Item "sv_copypv" | |
2914 | Copies a stringified representation of the source \s-1SV\s0 into the | |
2915 | destination \s-1SV\s0. Automatically performs any necessary mg_get and | |
2916 | coercion of numeric values into strings. Guaranteed to preserve | |
2917 | \&\s-1UTF\-8\s0 flag even from overloaded objects. Similar in nature to | |
2918 | sv_2pv[_flags] but operates directly on an \s-1SV\s0 instead of just the | |
2919 | string. Mostly uses sv_2pv_flags to do its work, except when that | |
2920 | would lose the \s-1UTF\-8\s0'ness of the \s-1PV\s0. | |
2921 | .Sp | |
2922 | .Vb 1 | |
2923 | \& void sv_copypv(SV* dsv, SV* ssv) | |
2924 | .Ve | |
2925 | .IP "sv_dec" 8 | |
2926 | .IX Item "sv_dec" | |
2927 | Auto-decrement of the value in the \s-1SV\s0, doing string to numeric conversion | |
2928 | if necessary. Handles 'get' magic. | |
2929 | .Sp | |
2930 | .Vb 1 | |
2931 | \& void sv_dec(SV* sv) | |
2932 | .Ve | |
2933 | .IP "sv_derived_from" 8 | |
2934 | .IX Item "sv_derived_from" | |
2935 | Returns a boolean indicating whether the \s-1SV\s0 is derived from the specified | |
2936 | class. This is the function that implements \f(CW\*(C`UNIVERSAL::isa\*(C'\fR. It works | |
2937 | for class names as well as for objects. | |
2938 | .Sp | |
2939 | .Vb 1 | |
2940 | \& bool sv_derived_from(SV* sv, const char* name) | |
2941 | .Ve | |
2942 | .IP "sv_eq" 8 | |
2943 | .IX Item "sv_eq" | |
2944 | Returns a boolean indicating whether the strings in the two SVs are | |
2945 | identical. Is \s-1UTF\-8\s0 and 'use bytes' aware, handles get magic, and will | |
2946 | coerce its args to strings if necessary. | |
2947 | .Sp | |
2948 | .Vb 1 | |
2949 | \& I32 sv_eq(SV* sv1, SV* sv2) | |
2950 | .Ve | |
2951 | .IP "sv_force_normal" 8 | |
2952 | .IX Item "sv_force_normal" | |
2953 | Undo various types of fakery on an \s-1SV:\s0 if the \s-1PV\s0 is a shared string, make | |
2954 | a private copy; if we're a ref, stop refing; if we're a glob, downgrade to | |
2955 | an xpvmg. See also \f(CW\*(C`sv_force_normal_flags\*(C'\fR. | |
2956 | .Sp | |
2957 | .Vb 1 | |
2958 | \& void sv_force_normal(SV *sv) | |
2959 | .Ve | |
2960 | .IP "sv_force_normal_flags" 8 | |
2961 | .IX Item "sv_force_normal_flags" | |
2962 | Undo various types of fakery on an \s-1SV:\s0 if the \s-1PV\s0 is a shared string, make | |
2963 | a private copy; if we're a ref, stop refing; if we're a glob, downgrade to | |
2964 | an xpvmg. The \f(CW\*(C`flags\*(C'\fR parameter gets passed to \f(CW\*(C`sv_unref_flags()\*(C'\fR | |
2965 | when unrefing. \f(CW\*(C`sv_force_normal\*(C'\fR calls this function with flags set to 0. | |
2966 | .Sp | |
2967 | .Vb 1 | |
2968 | \& void sv_force_normal_flags(SV *sv, U32 flags) | |
2969 | .Ve | |
2970 | .IP "sv_free" 8 | |
2971 | .IX Item "sv_free" | |
2972 | Decrement an \s-1SV\s0's reference count, and if it drops to zero, call | |
2973 | \&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by | |
2974 | the body; finally, deallocate the \s-1SV\s0's head itself. | |
2975 | Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR. | |
2976 | .Sp | |
2977 | .Vb 1 | |
2978 | \& void sv_free(SV* sv) | |
2979 | .Ve | |
2980 | .IP "sv_gets" 8 | |
2981 | .IX Item "sv_gets" | |
2982 | Get a line from the filehandle and store it into the \s-1SV\s0, optionally | |
2983 | appending to the currently-stored string. | |
2984 | .Sp | |
2985 | .Vb 1 | |
2986 | \& char* sv_gets(SV* sv, PerlIO* fp, I32 append) | |
2987 | .Ve | |
2988 | .IP "sv_grow" 8 | |
2989 | .IX Item "sv_grow" | |
2990 | Expands the character buffer in the \s-1SV\s0. If necessary, uses \f(CW\*(C`sv_unref\*(C'\fR and | |
2991 | upgrades the \s-1SV\s0 to \f(CW\*(C`SVt_PV\*(C'\fR. Returns a pointer to the character buffer. | |
2992 | Use the \f(CW\*(C`SvGROW\*(C'\fR wrapper instead. | |
2993 | .Sp | |
2994 | .Vb 1 | |
2995 | \& char* sv_grow(SV* sv, STRLEN newlen) | |
2996 | .Ve | |
2997 | .IP "sv_inc" 8 | |
2998 | .IX Item "sv_inc" | |
2999 | Auto-increment of the value in the \s-1SV\s0, doing string to numeric conversion | |
3000 | if necessary. Handles 'get' magic. | |
3001 | .Sp | |
3002 | .Vb 1 | |
3003 | \& void sv_inc(SV* sv) | |
3004 | .Ve | |
3005 | .IP "sv_insert" 8 | |
3006 | .IX Item "sv_insert" | |
3007 | Inserts a string at the specified offset/length within the \s-1SV\s0. Similar to | |
3008 | the Perl \fIsubstr()\fR function. | |
3009 | .Sp | |
3010 | .Vb 1 | |
3011 | \& void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) | |
3012 | .Ve | |
3013 | .IP "sv_isa" 8 | |
3014 | .IX Item "sv_isa" | |
3015 | Returns a boolean indicating whether the \s-1SV\s0 is blessed into the specified | |
3016 | class. This does not check for subtypes; use \f(CW\*(C`sv_derived_from\*(C'\fR to verify | |
3017 | an inheritance relationship. | |
3018 | .Sp | |
3019 | .Vb 1 | |
3020 | \& int sv_isa(SV* sv, const char* name) | |
3021 | .Ve | |
3022 | .IP "sv_isobject" 8 | |
3023 | .IX Item "sv_isobject" | |
3024 | Returns a boolean indicating whether the \s-1SV\s0 is an \s-1RV\s0 pointing to a blessed | |
3025 | object. If the \s-1SV\s0 is not an \s-1RV\s0, or if the object is not blessed, then this | |
3026 | will return false. | |
3027 | .Sp | |
3028 | .Vb 1 | |
3029 | \& int sv_isobject(SV* sv) | |
3030 | .Ve | |
3031 | .IP "sv_iv" 8 | |
3032 | .IX Item "sv_iv" | |
3033 | A private implementation of the \f(CW\*(C`SvIVx\*(C'\fR macro for compilers which can't | |
3034 | cope with complex macro expressions. Always use the macro instead. | |
3035 | .Sp | |
3036 | .Vb 1 | |
3037 | \& IV sv_iv(SV* sv) | |
3038 | .Ve | |
3039 | .IP "sv_len" 8 | |
3040 | .IX Item "sv_len" | |
3041 | Returns the length of the string in the \s-1SV\s0. Handles magic and type | |
3042 | coercion. See also \f(CW\*(C`SvCUR\*(C'\fR, which gives raw access to the xpv_cur slot. | |
3043 | .Sp | |
3044 | .Vb 1 | |
3045 | \& STRLEN sv_len(SV* sv) | |
3046 | .Ve | |
3047 | .IP "sv_len_utf8" 8 | |
3048 | .IX Item "sv_len_utf8" | |
3049 | Returns the number of characters in the string in an \s-1SV\s0, counting wide | |
3050 | \&\s-1UTF8\s0 bytes as a single character. Handles magic and type coercion. | |
3051 | .Sp | |
3052 | .Vb 1 | |
3053 | \& STRLEN sv_len_utf8(SV* sv) | |
3054 | .Ve | |
3055 | .IP "sv_magic" 8 | |
3056 | .IX Item "sv_magic" | |
3057 | Adds magic to an \s-1SV\s0. First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if necessary, | |
3058 | then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the magic list. | |
3059 | .Sp | |
3060 | .Vb 1 | |
3061 | \& void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) | |
3062 | .Ve | |
3063 | .IP "sv_magicext" 8 | |
3064 | .IX Item "sv_magicext" | |
3065 | Adds magic to an \s-1SV\s0, upgrading it if necessary. Applies the | |
3066 | supplied vtable and returns pointer to the magic added. | |
3067 | .Sp | |
3068 | Note that sv_magicext will allow things that sv_magic will not. | |
3069 | In particular you can add magic to SvREADONLY SVs and and more than | |
3070 | one instance of the same 'how' | |
3071 | .Sp | |
3072 | I \f(CW\*(C`namelen\*(C'\fR is greater then zero then a \fIsavepvn()\fR \fIcopy\fR of \f(CW\*(C`name\*(C'\fR is stored, | |
3073 | if \f(CW\*(C`namelen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as-is and \- as another special | |
3074 | case \- if \f(CW\*(C`(name && namelen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed to contain | |
3075 | an \f(CW\*(C`SV*\*(C'\fR and has its \s-1REFCNT\s0 incremented | |
3076 | .Sp | |
3077 | (This is now used as a subroutine by sv_magic.) | |
3078 | .Sp | |
3079 | .Vb 1 | |
3080 | \& MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) | |
3081 | .Ve | |
3082 | .IP "sv_mortalcopy" 8 | |
3083 | .IX Item "sv_mortalcopy" | |
3084 | Creates a new \s-1SV\s0 which is a copy of the original \s-1SV\s0 (using \f(CW\*(C`sv_setsv\*(C'\fR). | |
3085 | The new \s-1SV\s0 is marked as mortal. It will be destroyed \*(L"soon\*(R", either by an | |
3086 | explicit call to \s-1FREETMPS\s0, or by an implicit call at places such as | |
3087 | statement boundaries. See also \f(CW\*(C`sv_newmortal\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR. | |
3088 | .Sp | |
3089 | .Vb 1 | |
3090 | \& SV* sv_mortalcopy(SV* oldsv) | |
3091 | .Ve | |
3092 | .IP "sv_newmortal" 8 | |
3093 | .IX Item "sv_newmortal" | |
3094 | Creates a new null \s-1SV\s0 which is mortal. The reference count of the \s-1SV\s0 is | |
3095 | set to 1. It will be destroyed \*(L"soon\*(R", either by an explicit call to | |
3096 | \&\s-1FREETMPS\s0, or by an implicit call at places such as statement boundaries. | |
3097 | See also \f(CW\*(C`sv_mortalcopy\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR. | |
3098 | .Sp | |
3099 | .Vb 1 | |
3100 | \& SV* sv_newmortal() | |
3101 | .Ve | |
3102 | .IP "sv_newref" 8 | |
3103 | .IX Item "sv_newref" | |
3104 | Increment an \s-1SV\s0's reference count. Use the \f(CW\*(C`SvREFCNT_inc()\*(C'\fR wrapper | |
3105 | instead. | |
3106 | .Sp | |
3107 | .Vb 1 | |
3108 | \& SV* sv_newref(SV* sv) | |
3109 | .Ve | |
3110 | .IP "sv_nolocking" 8 | |
3111 | .IX Item "sv_nolocking" | |
3112 | Dummy routine which \*(L"locks\*(R" an \s-1SV\s0 when there is no locking module present. | |
3113 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
3114 | some level of strict\-ness. | |
3115 | .Sp | |
3116 | .Vb 1 | |
3117 | \& void sv_nolocking(SV *) | |
3118 | .Ve | |
3119 | .IP "sv_nosharing" 8 | |
3120 | .IX Item "sv_nosharing" | |
3121 | Dummy routine which \*(L"shares\*(R" an \s-1SV\s0 when there is no sharing module present. | |
3122 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
3123 | some level of strict\-ness. | |
3124 | .Sp | |
3125 | .Vb 1 | |
3126 | \& void sv_nosharing(SV *) | |
3127 | .Ve | |
3128 | .IP "sv_nounlocking" 8 | |
3129 | .IX Item "sv_nounlocking" | |
3130 | Dummy routine which \*(L"unlocks\*(R" an \s-1SV\s0 when there is no locking module present. | |
3131 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
3132 | some level of strict\-ness. | |
3133 | .Sp | |
3134 | .Vb 1 | |
3135 | \& void sv_nounlocking(SV *) | |
3136 | .Ve | |
3137 | .IP "sv_nv" 8 | |
3138 | .IX Item "sv_nv" | |
3139 | A private implementation of the \f(CW\*(C`SvNVx\*(C'\fR macro for compilers which can't | |
3140 | cope with complex macro expressions. Always use the macro instead. | |
3141 | .Sp | |
3142 | .Vb 1 | |
3143 | \& NV sv_nv(SV* sv) | |
3144 | .Ve | |
3145 | .IP "sv_pos_b2u" 8 | |
3146 | .IX Item "sv_pos_b2u" | |
3147 | Converts the value pointed to by offsetp from a count of bytes from the | |
3148 | start of the string, to a count of the equivalent number of \s-1UTF8\s0 chars. | |
3149 | Handles magic and type coercion. | |
3150 | .Sp | |
3151 | .Vb 1 | |
3152 | \& void sv_pos_b2u(SV* sv, I32* offsetp) | |
3153 | .Ve | |
3154 | .IP "sv_pos_u2b" 8 | |
3155 | .IX Item "sv_pos_u2b" | |
3156 | Converts the value pointed to by offsetp from a count of \s-1UTF8\s0 chars from | |
3157 | the start of the string, to a count of the equivalent number of bytes; if | |
3158 | lenp is non\-zero, it does the same to lenp, but this time starting from | |
3159 | the offset, rather than from the start of the string. Handles magic and | |
3160 | type coercion. | |
3161 | .Sp | |
3162 | .Vb 1 | |
3163 | \& void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp) | |
3164 | .Ve | |
3165 | .IP "sv_pv" 8 | |
3166 | .IX Item "sv_pv" | |
3167 | Use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro instead | |
3168 | .Sp | |
3169 | .Vb 1 | |
3170 | \& char* sv_pv(SV *sv) | |
3171 | .Ve | |
3172 | .IP "sv_pvbyte" 8 | |
3173 | .IX Item "sv_pvbyte" | |
3174 | Use \f(CW\*(C`SvPVbyte_nolen\*(C'\fR instead. | |
3175 | .Sp | |
3176 | .Vb 1 | |
3177 | \& char* sv_pvbyte(SV *sv) | |
3178 | .Ve | |
3179 | .IP "sv_pvbyten" 8 | |
3180 | .IX Item "sv_pvbyten" | |
3181 | A private implementation of the \f(CW\*(C`SvPVbyte\*(C'\fR macro for compilers | |
3182 | which can't cope with complex macro expressions. Always use the macro | |
3183 | instead. | |
3184 | .Sp | |
3185 | .Vb 1 | |
3186 | \& char* sv_pvbyten(SV *sv, STRLEN *len) | |
3187 | .Ve | |
3188 | .IP "sv_pvbyten_force" 8 | |
3189 | .IX Item "sv_pvbyten_force" | |
3190 | A private implementation of the \f(CW\*(C`SvPVbytex_force\*(C'\fR macro for compilers | |
3191 | which can't cope with complex macro expressions. Always use the macro | |
3192 | instead. | |
3193 | .Sp | |
3194 | .Vb 1 | |
3195 | \& char* sv_pvbyten_force(SV* sv, STRLEN* lp) | |
3196 | .Ve | |
3197 | .IP "sv_pvn" 8 | |
3198 | .IX Item "sv_pvn" | |
3199 | A private implementation of the \f(CW\*(C`SvPV\*(C'\fR macro for compilers which can't | |
3200 | cope with complex macro expressions. Always use the macro instead. | |
3201 | .Sp | |
3202 | .Vb 1 | |
3203 | \& char* sv_pvn(SV *sv, STRLEN *len) | |
3204 | .Ve | |
3205 | .IP "sv_pvn_force" 8 | |
3206 | .IX Item "sv_pvn_force" | |
3207 | Get a sensible string out of the \s-1SV\s0 somehow. | |
3208 | A private implementation of the \f(CW\*(C`SvPV_force\*(C'\fR macro for compilers which | |
3209 | can't cope with complex macro expressions. Always use the macro instead. | |
3210 | .Sp | |
3211 | .Vb 1 | |
3212 | \& char* sv_pvn_force(SV* sv, STRLEN* lp) | |
3213 | .Ve | |
3214 | .IP "sv_pvn_force_flags" 8 | |
3215 | .IX Item "sv_pvn_force_flags" | |
3216 | Get a sensible string out of the \s-1SV\s0 somehow. | |
3217 | If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`sv\*(C'\fR if | |
3218 | appropriate, else not. \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are | |
3219 | implemented in terms of this function. | |
3220 | You normally want to use the various wrapper macros instead: see | |
3221 | \&\f(CW\*(C`SvPV_force\*(C'\fR and \f(CW\*(C`SvPV_force_nomg\*(C'\fR | |
3222 | .Sp | |
3223 | .Vb 1 | |
3224 | \& char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags) | |
3225 | .Ve | |
3226 | .IP "sv_pvutf8" 8 | |
3227 | .IX Item "sv_pvutf8" | |
3228 | Use the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro instead | |
3229 | .Sp | |
3230 | .Vb 1 | |
3231 | \& char* sv_pvutf8(SV *sv) | |
3232 | .Ve | |
3233 | .IP "sv_pvutf8n" 8 | |
3234 | .IX Item "sv_pvutf8n" | |
3235 | A private implementation of the \f(CW\*(C`SvPVutf8\*(C'\fR macro for compilers | |
3236 | which can't cope with complex macro expressions. Always use the macro | |
3237 | instead. | |
3238 | .Sp | |
3239 | .Vb 1 | |
3240 | \& char* sv_pvutf8n(SV *sv, STRLEN *len) | |
3241 | .Ve | |
3242 | .IP "sv_pvutf8n_force" 8 | |
3243 | .IX Item "sv_pvutf8n_force" | |
3244 | A private implementation of the \f(CW\*(C`SvPVutf8_force\*(C'\fR macro for compilers | |
3245 | which can't cope with complex macro expressions. Always use the macro | |
3246 | instead. | |
3247 | .Sp | |
3248 | .Vb 1 | |
3249 | \& char* sv_pvutf8n_force(SV* sv, STRLEN* lp) | |
3250 | .Ve | |
3251 | .IP "sv_reftype" 8 | |
3252 | .IX Item "sv_reftype" | |
3253 | Returns a string describing what the \s-1SV\s0 is a reference to. | |
3254 | .Sp | |
3255 | .Vb 1 | |
3256 | \& char* sv_reftype(SV* sv, int ob) | |
3257 | .Ve | |
3258 | .IP "sv_replace" 8 | |
3259 | .IX Item "sv_replace" | |
3260 | Make the first argument a copy of the second, then delete the original. | |
3261 | The target \s-1SV\s0 physically takes over ownership of the body of the source \s-1SV\s0 | |
3262 | and inherits its flags; however, the target keeps any magic it owns, | |
3263 | and any magic in the source is discarded. | |
3264 | Note that this is a rather specialist \s-1SV\s0 copying operation; most of the | |
3265 | time you'll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front\-ends. | |
3266 | .Sp | |
3267 | .Vb 1 | |
3268 | \& void sv_replace(SV* sv, SV* nsv) | |
3269 | .Ve | |
3270 | .IP "sv_report_used" 8 | |
3271 | .IX Item "sv_report_used" | |
3272 | Dump the contents of all SVs not yet freed. (Debugging aid). | |
3273 | .Sp | |
3274 | .Vb 1 | |
3275 | \& void sv_report_used() | |
3276 | .Ve | |
3277 | .IP "sv_reset" 8 | |
3278 | .IX Item "sv_reset" | |
3279 | Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function. | |
3280 | Note that the perl-level function is vaguely deprecated. | |
3281 | .Sp | |
3282 | .Vb 1 | |
3283 | \& void sv_reset(char* s, HV* stash) | |
3284 | .Ve | |
3285 | .IP "sv_rvweaken" 8 | |
3286 | .IX Item "sv_rvweaken" | |
3287 | Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this \s-1RV\s0; give the | |
3288 | referred-to \s-1SV\s0 \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn't already; and | |
3289 | push a back-reference to this \s-1RV\s0 onto the array of backreferences | |
3290 | associated with that magic. | |
3291 | .Sp | |
3292 | .Vb 1 | |
3293 | \& SV* sv_rvweaken(SV *sv) | |
3294 | .Ve | |
3295 | .IP "sv_setiv" 8 | |
3296 | .IX Item "sv_setiv" | |
3297 | Copies an integer into the given \s-1SV\s0, upgrading first if necessary. | |
3298 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setiv_mg\*(C'\fR. | |
3299 | .Sp | |
3300 | .Vb 1 | |
3301 | \& void sv_setiv(SV* sv, IV num) | |
3302 | .Ve | |
3303 | .IP "sv_setiv_mg" 8 | |
3304 | .IX Item "sv_setiv_mg" | |
3305 | Like \f(CW\*(C`sv_setiv\*(C'\fR, but also handles 'set' magic. | |
3306 | .Sp | |
3307 | .Vb 1 | |
3308 | \& void sv_setiv_mg(SV *sv, IV i) | |
3309 | .Ve | |
3310 | .IP "sv_setnv" 8 | |
3311 | .IX Item "sv_setnv" | |
3312 | Copies a double into the given \s-1SV\s0, upgrading first if necessary. | |
3313 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setnv_mg\*(C'\fR. | |
3314 | .Sp | |
3315 | .Vb 1 | |
3316 | \& void sv_setnv(SV* sv, NV num) | |
3317 | .Ve | |
3318 | .IP "sv_setnv_mg" 8 | |
3319 | .IX Item "sv_setnv_mg" | |
3320 | Like \f(CW\*(C`sv_setnv\*(C'\fR, but also handles 'set' magic. | |
3321 | .Sp | |
3322 | .Vb 1 | |
3323 | \& void sv_setnv_mg(SV *sv, NV num) | |
3324 | .Ve | |
3325 | .IP "sv_setpv" 8 | |
3326 | .IX Item "sv_setpv" | |
3327 | Copies a string into an \s-1SV\s0. The string must be null\-terminated. Does not | |
3328 | handle 'set' magic. See \f(CW\*(C`sv_setpv_mg\*(C'\fR. | |
3329 | .Sp | |
3330 | .Vb 1 | |
3331 | \& void sv_setpv(SV* sv, const char* ptr) | |
3332 | .Ve | |
3333 | .IP "sv_setpvf" 8 | |
3334 | .IX Item "sv_setpvf" | |
3335 | Processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and sets an \s-1SV\s0 to the formatted | |
3336 | output. Does not handle 'set' magic. See \f(CW\*(C`sv_setpvf_mg\*(C'\fR. | |
3337 | .Sp | |
3338 | .Vb 1 | |
3339 | \& void sv_setpvf(SV* sv, const char* pat, ...) | |
3340 | .Ve | |
3341 | .IP "sv_setpvf_mg" 8 | |
3342 | .IX Item "sv_setpvf_mg" | |
3343 | Like \f(CW\*(C`sv_setpvf\*(C'\fR, but also handles 'set' magic. | |
3344 | .Sp | |
3345 | .Vb 1 | |
3346 | \& void sv_setpvf_mg(SV *sv, const char* pat, ...) | |
3347 | .Ve | |
3348 | .IP "sv_setpvn" 8 | |
3349 | .IX Item "sv_setpvn" | |
3350 | Copies a string into an \s-1SV\s0. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of | |
3351 | bytes to be copied. Does not handle 'set' magic. See \f(CW\*(C`sv_setpvn_mg\*(C'\fR. | |
3352 | .Sp | |
3353 | .Vb 1 | |
3354 | \& void sv_setpvn(SV* sv, const char* ptr, STRLEN len) | |
3355 | .Ve | |
3356 | .IP "sv_setpvn_mg" 8 | |
3357 | .IX Item "sv_setpvn_mg" | |
3358 | Like \f(CW\*(C`sv_setpvn\*(C'\fR, but also handles 'set' magic. | |
3359 | .Sp | |
3360 | .Vb 1 | |
3361 | \& void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len) | |
3362 | .Ve | |
3363 | .IP "sv_setpv_mg" 8 | |
3364 | .IX Item "sv_setpv_mg" | |
3365 | Like \f(CW\*(C`sv_setpv\*(C'\fR, but also handles 'set' magic. | |
3366 | .Sp | |
3367 | .Vb 1 | |
3368 | \& void sv_setpv_mg(SV *sv, const char *ptr) | |
3369 | .Ve | |
3370 | .IP "sv_setref_iv" 8 | |
3371 | .IX Item "sv_setref_iv" | |
3372 | Copies an integer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
3373 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
3374 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
3375 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
3376 | will be returned and will have a reference count of 1. | |
3377 | .Sp | |
3378 | .Vb 1 | |
3379 | \& SV* sv_setref_iv(SV* rv, const char* classname, IV iv) | |
3380 | .Ve | |
3381 | .IP "sv_setref_nv" 8 | |
3382 | .IX Item "sv_setref_nv" | |
3383 | Copies a double into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
3384 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
3385 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
3386 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
3387 | will be returned and will have a reference count of 1. | |
3388 | .Sp | |
3389 | .Vb 1 | |
3390 | \& SV* sv_setref_nv(SV* rv, const char* classname, NV nv) | |
3391 | .Ve | |
3392 | .IP "sv_setref_pv" 8 | |
3393 | .IX Item "sv_setref_pv" | |
3394 | Copies a pointer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
3395 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
3396 | the new \s-1SV\s0. If the \f(CW\*(C`pv\*(C'\fR argument is \s-1NULL\s0 then \f(CW\*(C`PL_sv_undef\*(C'\fR will be placed | |
3397 | into the \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
3398 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
3399 | will be returned and will have a reference count of 1. | |
3400 | .Sp | |
3401 | Do not use with other Perl types such as \s-1HV\s0, \s-1AV\s0, \s-1SV\s0, \s-1CV\s0, because those | |
3402 | objects will become corrupted by the pointer copy process. | |
3403 | .Sp | |
3404 | Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer. | |
3405 | .Sp | |
3406 | .Vb 1 | |
3407 | \& SV* sv_setref_pv(SV* rv, const char* classname, void* pv) | |
3408 | .Ve | |
3409 | .IP "sv_setref_pvn" 8 | |
3410 | .IX Item "sv_setref_pvn" | |
3411 | Copies a string into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The length of the | |
3412 | string must be specified with \f(CW\*(C`n\*(C'\fR. The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to | |
3413 | an \s-1RV\s0. That \s-1RV\s0 will be modified to point to the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR | |
3414 | argument indicates the package for the blessing. Set \f(CW\*(C`classname\*(C'\fR to | |
3415 | \&\f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 will be returned and will have | |
3416 | a reference count of 1. | |
3417 | .Sp | |
3418 | Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string. | |
3419 | .Sp | |
3420 | .Vb 1 | |
3421 | \& SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) | |
3422 | .Ve | |
3423 | .IP "sv_setref_uv" 8 | |
3424 | .IX Item "sv_setref_uv" | |
3425 | Copies an unsigned integer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
3426 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
3427 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
3428 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
3429 | will be returned and will have a reference count of 1. | |
3430 | .Sp | |
3431 | .Vb 1 | |
3432 | \& SV* sv_setref_uv(SV* rv, const char* classname, UV uv) | |
3433 | .Ve | |
3434 | .IP "sv_setsv" 8 | |
3435 | .IX Item "sv_setsv" | |
3436 | Copies the contents of the source \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR into the destination \s-1SV\s0 | |
3437 | \&\f(CW\*(C`dsv\*(C'\fR. The source \s-1SV\s0 may be destroyed if it is mortal, so don't use this | |
3438 | function if the source \s-1SV\s0 needs to be reused. Does not handle 'set' magic. | |
3439 | Loosely speaking, it performs a copy\-by\-value, obliterating any previous | |
3440 | content of the destination. | |
3441 | .Sp | |
3442 | You probably want to use one of the assortment of wrappers, such as | |
3443 | \&\f(CW\*(C`SvSetSV\*(C'\fR, \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, \f(CW\*(C`SvSetMagicSV\*(C'\fR and | |
3444 | \&\f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR. | |
3445 | .Sp | |
3446 | .Vb 1 | |
3447 | \& void sv_setsv(SV* dsv, SV* ssv) | |
3448 | .Ve | |
3449 | .IP "sv_setsv_flags" 8 | |
3450 | .IX Item "sv_setsv_flags" | |
3451 | Copies the contents of the source \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR into the destination \s-1SV\s0 | |
3452 | \&\f(CW\*(C`dsv\*(C'\fR. The source \s-1SV\s0 may be destroyed if it is mortal, so don't use this | |
3453 | function if the source \s-1SV\s0 needs to be reused. Does not handle 'set' magic. | |
3454 | Loosely speaking, it performs a copy\-by\-value, obliterating any previous | |
3455 | content of the destination. | |
3456 | If the \f(CW\*(C`flags\*(C'\fR parameter has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on | |
3457 | \&\f(CW\*(C`ssv\*(C'\fR if appropriate, else not. \f(CW\*(C`sv_setsv\*(C'\fR and \f(CW\*(C`sv_setsv_nomg\*(C'\fR are | |
3458 | implemented in terms of this function. | |
3459 | .Sp | |
3460 | You probably want to use one of the assortment of wrappers, such as | |
3461 | \&\f(CW\*(C`SvSetSV\*(C'\fR, \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, \f(CW\*(C`SvSetMagicSV\*(C'\fR and | |
3462 | \&\f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR. | |
3463 | .Sp | |
3464 | This is the primary function for copying scalars, and most other | |
3465 | copy-ish functions and macros use this underneath. | |
3466 | .Sp | |
3467 | .Vb 1 | |
3468 | \& void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags) | |
3469 | .Ve | |
3470 | .IP "sv_setsv_mg" 8 | |
3471 | .IX Item "sv_setsv_mg" | |
3472 | Like \f(CW\*(C`sv_setsv\*(C'\fR, but also handles 'set' magic. | |
3473 | .Sp | |
3474 | .Vb 1 | |
3475 | \& void sv_setsv_mg(SV *dstr, SV *sstr) | |
3476 | .Ve | |
3477 | .IP "sv_setuv" 8 | |
3478 | .IX Item "sv_setuv" | |
3479 | Copies an unsigned integer into the given \s-1SV\s0, upgrading first if necessary. | |
3480 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setuv_mg\*(C'\fR. | |
3481 | .Sp | |
3482 | .Vb 1 | |
3483 | \& void sv_setuv(SV* sv, UV num) | |
3484 | .Ve | |
3485 | .IP "sv_setuv_mg" 8 | |
3486 | .IX Item "sv_setuv_mg" | |
3487 | Like \f(CW\*(C`sv_setuv\*(C'\fR, but also handles 'set' magic. | |
3488 | .Sp | |
3489 | .Vb 1 | |
3490 | \& void sv_setuv_mg(SV *sv, UV u) | |
3491 | .Ve | |
3492 | .IP "sv_taint" 8 | |
3493 | .IX Item "sv_taint" | |
3494 | Taint an \s-1SV\s0. Use \f(CW\*(C`SvTAINTED_on\*(C'\fR instead. | |
3495 | void sv_taint(SV* sv) | |
3496 | .IP "sv_tainted" 8 | |
3497 | .IX Item "sv_tainted" | |
3498 | Test an \s-1SV\s0 for taintedness. Use \f(CW\*(C`SvTAINTED\*(C'\fR instead. | |
3499 | bool sv_tainted(SV* sv) | |
3500 | .IP "sv_true" 8 | |
3501 | .IX Item "sv_true" | |
3502 | Returns true if the \s-1SV\s0 has a true value by Perl's rules. | |
3503 | Use the \f(CW\*(C`SvTRUE\*(C'\fR macro instead, which may call \f(CW\*(C`sv_true()\*(C'\fR or may | |
3504 | instead use an in-line version. | |
3505 | .Sp | |
3506 | .Vb 1 | |
3507 | \& I32 sv_true(SV *sv) | |
3508 | .Ve | |
3509 | .IP "sv_unmagic" 8 | |
3510 | .IX Item "sv_unmagic" | |
3511 | Removes all magic of type \f(CW\*(C`type\*(C'\fR from an \s-1SV\s0. | |
3512 | .Sp | |
3513 | .Vb 1 | |
3514 | \& int sv_unmagic(SV* sv, int type) | |
3515 | .Ve | |
3516 | .IP "sv_unref" 8 | |
3517 | .IX Item "sv_unref" | |
3518 | Unsets the \s-1RV\s0 status of the \s-1SV\s0, and decrements the reference count of | |
3519 | whatever was being referenced by the \s-1RV\s0. This can almost be thought of | |
3520 | 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 | |
3521 | being zero. See \f(CW\*(C`SvROK_off\*(C'\fR. | |
3522 | .Sp | |
3523 | .Vb 1 | |
3524 | \& void sv_unref(SV* sv) | |
3525 | .Ve | |
3526 | .IP "sv_unref_flags" 8 | |
3527 | .IX Item "sv_unref_flags" | |
3528 | Unsets the \s-1RV\s0 status of the \s-1SV\s0, and decrements the reference count of | |
3529 | whatever was being referenced by the \s-1RV\s0. This can almost be thought of | |
3530 | as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. The \f(CW\*(C`cflags\*(C'\fR argument can contain | |
3531 | \&\f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR to force the reference count to be decremented | |
3532 | (otherwise the decrementing is conditional on the reference count being | |
3533 | different from one or the reference being a readonly \s-1SV\s0). | |
3534 | See \f(CW\*(C`SvROK_off\*(C'\fR. | |
3535 | .Sp | |
3536 | .Vb 1 | |
3537 | \& void sv_unref_flags(SV* sv, U32 flags) | |
3538 | .Ve | |
3539 | .IP "sv_untaint" 8 | |
3540 | .IX Item "sv_untaint" | |
3541 | Untaint an \s-1SV\s0. Use \f(CW\*(C`SvTAINTED_off\*(C'\fR instead. | |
3542 | void sv_untaint(SV* sv) | |
3543 | .IP "sv_upgrade" 8 | |
3544 | .IX Item "sv_upgrade" | |
3545 | Upgrade an \s-1SV\s0 to a more complex form. Generally adds a new body type to the | |
3546 | \&\s-1SV\s0, then copies across as much information as possible from the old body. | |
3547 | You generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper. See also \f(CW\*(C`svtype\*(C'\fR. | |
3548 | .Sp | |
3549 | .Vb 1 | |
3550 | \& bool sv_upgrade(SV* sv, U32 mt) | |
3551 | .Ve | |
3552 | .IP "sv_usepvn" 8 | |
3553 | .IX Item "sv_usepvn" | |
3554 | Tells an \s-1SV\s0 to use \f(CW\*(C`ptr\*(C'\fR to find its string value. Normally the string is | |
3555 | stored inside the \s-1SV\s0 but sv_usepvn allows the \s-1SV\s0 to use an outside string. | |
3556 | The \f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated by \f(CW\*(C`malloc\*(C'\fR. The | |
3557 | string length, \f(CW\*(C`len\*(C'\fR, must be supplied. This function will realloc the | |
3558 | memory pointed to by \f(CW\*(C`ptr\*(C'\fR, so that pointer should not be freed or used by | |
3559 | the programmer after giving it to sv_usepvn. Does not handle 'set' magic. | |
3560 | See \f(CW\*(C`sv_usepvn_mg\*(C'\fR. | |
3561 | .Sp | |
3562 | .Vb 1 | |
3563 | \& void sv_usepvn(SV* sv, char* ptr, STRLEN len) | |
3564 | .Ve | |
3565 | .IP "sv_usepvn_mg" 8 | |
3566 | .IX Item "sv_usepvn_mg" | |
3567 | Like \f(CW\*(C`sv_usepvn\*(C'\fR, but also handles 'set' magic. | |
3568 | .Sp | |
3569 | .Vb 1 | |
3570 | \& void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) | |
3571 | .Ve | |
3572 | .IP "sv_utf8_decode" 8 | |
3573 | .IX Item "sv_utf8_decode" | |
3574 | Convert the octets in the \s-1PV\s0 from \s-1UTF\-8\s0 to chars. Scan for validity and then | |
3575 | turn off SvUTF8 if needed so that we see characters. Used as a building block | |
3576 | for decode_utf8 in Encode.xs | |
3577 | .Sp | |
3578 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
3579 | removed without notice. | |
3580 | .Sp | |
3581 | .Vb 1 | |
3582 | \& bool sv_utf8_decode(SV *sv) | |
3583 | .Ve | |
3584 | .IP "sv_utf8_downgrade" 8 | |
3585 | .IX Item "sv_utf8_downgrade" | |
3586 | Attempt to convert the \s-1PV\s0 of an \s-1SV\s0 from UTF8\-encoded to byte encoding. | |
3587 | This may not be possible if the \s-1PV\s0 contains non-byte encoding characters; | |
3588 | if this is the case, either returns false or, if \f(CW\*(C`fail_ok\*(C'\fR is not | |
3589 | true, croaks. | |
3590 | .Sp | |
3591 | This is not as a general purpose Unicode to byte encoding interface: | |
3592 | use the Encode extension for that. | |
3593 | .Sp | |
3594 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
3595 | removed without notice. | |
3596 | .Sp | |
3597 | .Vb 1 | |
3598 | \& bool sv_utf8_downgrade(SV *sv, bool fail_ok) | |
3599 | .Ve | |
3600 | .IP "sv_utf8_encode" 8 | |
3601 | .IX Item "sv_utf8_encode" | |
3602 | Convert the \s-1PV\s0 of an \s-1SV\s0 to UTF8\-encoded, but then turn off the \f(CW\*(C`SvUTF8\*(C'\fR | |
3603 | flag so that it looks like octets again. Used as a building block | |
3604 | for encode_utf8 in Encode.xs | |
3605 | .Sp | |
3606 | .Vb 1 | |
3607 | \& void sv_utf8_encode(SV *sv) | |
3608 | .Ve | |
3609 | .IP "sv_utf8_upgrade" 8 | |
3610 | .IX Item "sv_utf8_upgrade" | |
3611 | Convert the \s-1PV\s0 of an \s-1SV\s0 to its UTF8\-encoded form. | |
3612 | Forces the \s-1SV\s0 to string form if it is not already. | |
3613 | Always sets the SvUTF8 flag to avoid future validity checks even | |
3614 | if all the bytes have hibit clear. | |
3615 | .Sp | |
3616 | This is not as a general purpose byte encoding to Unicode interface: | |
3617 | use the Encode extension for that. | |
3618 | .Sp | |
3619 | .Vb 1 | |
3620 | \& STRLEN sv_utf8_upgrade(SV *sv) | |
3621 | .Ve | |
3622 | .IP "sv_utf8_upgrade_flags" 8 | |
3623 | .IX Item "sv_utf8_upgrade_flags" | |
3624 | Convert the \s-1PV\s0 of an \s-1SV\s0 to its UTF8\-encoded form. | |
3625 | Forces the \s-1SV\s0 to string form if it is not already. | |
3626 | Always sets the SvUTF8 flag to avoid future validity checks even | |
3627 | if all the bytes have hibit clear. If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, | |
3628 | will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`sv\*(C'\fR if appropriate, else not. \f(CW\*(C`sv_utf8_upgrade\*(C'\fR and | |
3629 | \&\f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR are implemented in terms of this function. | |
3630 | .Sp | |
3631 | This is not as a general purpose byte encoding to Unicode interface: | |
3632 | use the Encode extension for that. | |
3633 | .Sp | |
3634 | .Vb 1 | |
3635 | \& STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) | |
3636 | .Ve | |
3637 | .IP "sv_uv" 8 | |
3638 | .IX Item "sv_uv" | |
3639 | A private implementation of the \f(CW\*(C`SvUVx\*(C'\fR macro for compilers which can't | |
3640 | cope with complex macro expressions. Always use the macro instead. | |
3641 | .Sp | |
3642 | .Vb 1 | |
3643 | \& UV sv_uv(SV* sv) | |
3644 | .Ve | |
3645 | .IP "sv_vcatpvfn" 8 | |
3646 | .IX Item "sv_vcatpvfn" | |
3647 | Processes its arguments like \f(CW\*(C`vsprintf\*(C'\fR and appends the formatted output | |
3648 | to an \s-1SV\s0. Uses an array of SVs if the C style variable argument list is | |
3649 | missing (\s-1NULL\s0). When running with taint checks enabled, indicates via | |
3650 | \&\f(CW\*(C`maybe_tainted\*(C'\fR if results are untrustworthy (often due to the use of | |
3651 | locales). | |
3652 | .Sp | |
3653 | Usually used via one of its frontends \f(CW\*(C`sv_catpvf\*(C'\fR and \f(CW\*(C`sv_catpvf_mg\*(C'\fR. | |
3654 | .Sp | |
3655 | .Vb 1 | |
3656 | \& void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) | |
3657 | .Ve | |
3658 | .IP "sv_vsetpvfn" 8 | |
3659 | .IX Item "sv_vsetpvfn" | |
3660 | Works like \f(CW\*(C`vcatpvfn\*(C'\fR but copies the text into the \s-1SV\s0 instead of | |
3661 | appending it. | |
3662 | .Sp | |
3663 | Usually used via one of its frontends \f(CW\*(C`sv_setpvf\*(C'\fR and \f(CW\*(C`sv_setpvf_mg\*(C'\fR. | |
3664 | .Sp | |
3665 | .Vb 1 | |
3666 | \& void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) | |
3667 | .Ve | |
3668 | .SH "Unicode Support" | |
3669 | .IX Header "Unicode Support" | |
3670 | .IP "bytes_from_utf8" 8 | |
3671 | .IX Item "bytes_from_utf8" | |
3672 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1UTF8\s0 into byte encoding. | |
3673 | Unlike <utf8_to_bytes> but like \f(CW\*(C`bytes_to_utf8\*(C'\fR, returns a pointer to | |
3674 | the newly-created string, and updates \f(CW\*(C`len\*(C'\fR to contain the new | |
3675 | length. Returns the original string if no conversion occurs, \f(CW\*(C`len\*(C'\fR | |
3676 | is unchanged. Do nothing if \f(CW\*(C`is_utf8\*(C'\fR points to 0. Sets \f(CW\*(C`is_utf8\*(C'\fR to | |
3677 | 0 if \f(CW\*(C`s\*(C'\fR is converted or contains all 7bit characters. | |
3678 | .Sp | |
3679 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
3680 | removed without notice. | |
3681 | .Sp | |
3682 | .Vb 1 | |
3683 | \& U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) | |
3684 | .Ve | |
3685 | .IP "bytes_to_utf8" 8 | |
3686 | .IX Item "bytes_to_utf8" | |
3687 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1ASCII\s0 into \s-1UTF8\s0 encoding. | |
3688 | Returns a pointer to the newly-created string, and sets \f(CW\*(C`len\*(C'\fR to | |
3689 | reflect the new length. | |
3690 | .Sp | |
3691 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
3692 | removed without notice. | |
3693 | .Sp | |
3694 | .Vb 1 | |
3695 | \& U8* bytes_to_utf8(U8 *s, STRLEN *len) | |
3696 | .Ve | |
3697 | .IP "ibcmp_utf8" 8 | |
3698 | .IX Item "ibcmp_utf8" | |
3699 | Return true if the strings s1 and s2 differ case\-insensitively, false | |
3700 | if not (if they are equal case\-insensitively). If u1 is true, the | |
3701 | string s1 is assumed to be in UTF\-8\-encoded Unicode. If u2 is true, | |
3702 | the string s2 is assumed to be in UTF\-8\-encoded Unicode. If u1 or u2 | |
3703 | are false, the respective string is assumed to be in native 8\-bit | |
3704 | encoding. | |
3705 | .Sp | |
3706 | If the pe1 and pe2 are non\-NULL, the scanning pointers will be copied | |
3707 | in there (they will point at the beginning of the \fInext\fR character). | |
3708 | If the pointers behind pe1 or pe2 are non\-NULL, they are the end | |
3709 | pointers beyond which scanning will not continue under any | |
3710 | circustances. If the byte lengths l1 and l2 are non\-zero, s1+l1 and | |
3711 | s2+l2 will be used as goal end pointers that will also stop the scan, | |
3712 | and which qualify towards defining a successful match: all the scans | |
3713 | that define an explicit length must reach their goal pointers for | |
3714 | a match to succeed). | |
3715 | .Sp | |
3716 | For case\-insensitiveness, the \*(L"casefolding\*(R" of Unicode is used | |
3717 | instead of upper/lowercasing both the characters, see | |
3718 | http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). | |
3719 | .Sp | |
3720 | .Vb 1 | |
3721 | \& I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2) | |
3722 | .Ve | |
3723 | .IP "is_utf8_char" 8 | |
3724 | .IX Item "is_utf8_char" | |
3725 | Tests if some arbitrary number of bytes begins in a valid \s-1UTF\-8\s0 | |
3726 | character. Note that an \s-1INVARIANT\s0 (i.e. \s-1ASCII\s0) character is a valid | |
3727 | \&\s-1UTF\-8\s0 character. The actual number of bytes in the \s-1UTF\-8\s0 character | |
3728 | will be returned if it is valid, otherwise 0. | |
3729 | .Sp | |
3730 | .Vb 1 | |
3731 | \& STRLEN is_utf8_char(U8 *p) | |
3732 | .Ve | |
3733 | .IP "is_utf8_string" 8 | |
3734 | .IX Item "is_utf8_string" | |
3735 | Returns true if first \f(CW\*(C`len\*(C'\fR bytes of the given string form a valid \s-1UTF8\s0 | |
3736 | string, false otherwise. Note that 'a valid \s-1UTF8\s0 string' does not mean | |
3737 | \&'a string that contains \s-1UTF8\s0' because a valid \s-1ASCII\s0 string is a valid | |
3738 | \&\s-1UTF8\s0 string. | |
3739 | .Sp | |
3740 | .Vb 1 | |
3741 | \& bool is_utf8_string(U8 *s, STRLEN len) | |
3742 | .Ve | |
3743 | .IP "pv_uni_display" 8 | |
3744 | .IX Item "pv_uni_display" | |
3745 | Build to the scalar dsv a displayable version of the string spv, | |
3746 | length len, the displayable version being at most pvlim bytes long | |
3747 | (if longer, the rest is truncated and \*(L"...\*(R" will be appended). | |
3748 | .Sp | |
3749 | The flags argument can have \s-1UNI_DISPLAY_ISPRINT\s0 set to display | |
3750 | \&\fIisPRINT()\fRable characters as themselves, \s-1UNI_DISPLAY_BACKSLASH\s0 | |
3751 | to display the \e\e[nrfta\e\e] as the backslashed versions (like '\en') | |
3752 | (\s-1UNI_DISPLAY_BACKSLASH\s0 is preferred over \s-1UNI_DISPLAY_ISPRINT\s0 for \e\e). | |
3753 | \&\s-1UNI_DISPLAY_QQ\s0 (and its alias \s-1UNI_DISPLAY_REGEX\s0) have both | |
3754 | \&\s-1UNI_DISPLAY_BACKSLASH\s0 and \s-1UNI_DISPLAY_ISPRINT\s0 turned on. | |
3755 | .Sp | |
3756 | The pointer to the \s-1PV\s0 of the dsv is returned. | |
3757 | .Sp | |
3758 | .Vb 1 | |
3759 | \& char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) | |
3760 | .Ve | |
3761 | .IP "sv_recode_to_utf8" 8 | |
3762 | .IX Item "sv_recode_to_utf8" | |
3763 | The encoding is assumed to be an Encode object, on entry the \s-1PV\s0 | |
3764 | of the sv is assumed to be octets in that encoding, and the sv | |
3765 | will be converted into Unicode (and \s-1UTF\-8\s0). | |
3766 | .Sp | |
3767 | If the sv already is \s-1UTF\-8\s0 (or if it is not \s-1POK\s0), or if the encoding | |
3768 | is not a reference, nothing is done to the sv. If the encoding is not | |
3769 | an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen. | |
3770 | (See \fIlib/encoding.pm\fR and Encode). | |
3771 | .Sp | |
3772 | The \s-1PV\s0 of the sv is returned. | |
3773 | .Sp | |
3774 | .Vb 1 | |
3775 | \& char* sv_recode_to_utf8(SV* sv, SV *encoding) | |
3776 | .Ve | |
3777 | .IP "sv_uni_display" 8 | |
3778 | .IX Item "sv_uni_display" | |
3779 | Build to the scalar dsv a displayable version of the scalar sv, | |
3780 | the displayable version being at most pvlim bytes long | |
3781 | (if longer, the rest is truncated and \*(L"...\*(R" will be appended). | |
3782 | .Sp | |
3783 | The flags argument is as in \fIpv_uni_display()\fR. | |
3784 | .Sp | |
3785 | The pointer to the \s-1PV\s0 of the dsv is returned. | |
3786 | .Sp | |
3787 | .Vb 1 | |
3788 | \& char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) | |
3789 | .Ve | |
3790 | .IP "to_utf8_case" 8 | |
3791 | .IX Item "to_utf8_case" | |
3792 | The \*(L"p\*(R" contains the pointer to the \s-1UTF\-8\s0 string encoding | |
3793 | the character that is being converted. | |
3794 | .Sp | |
3795 | The \*(L"ustrp\*(R" is a pointer to the character buffer to put the | |
3796 | conversion result to. The \*(L"lenp\*(R" is a pointer to the length | |
3797 | of the result. | |
3798 | .Sp | |
3799 | The \*(L"swashp\*(R" is a pointer to the swash to use. | |
3800 | .Sp | |
3801 | Both the special and normal mappings are stored lib/unicore/To/Foo.pl, | |
3802 | and loaded by \s-1SWASHGET\s0, using lib/utf8_heavy.pl. The special (usually, | |
3803 | but not always, a multicharacter mapping), is tried first. | |
3804 | .Sp | |
3805 | The \*(L"special\*(R" is a string like \*(L"utf8::ToSpecLower\*(R", which means the | |
3806 | hash \f(CW%utf8::ToSpecLower\fR. The access to the hash is through | |
3807 | \&\fIPerl_to_utf8_case()\fR. | |
3808 | .Sp | |
3809 | The \*(L"normal\*(R" is a string like \*(L"ToLower\*(R" which means the swash | |
3810 | \&\f(CW%utf8::ToLower\fR. | |
3811 | .Sp | |
3812 | .Vb 1 | |
3813 | \& UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special) | |
3814 | .Ve | |
3815 | .IP "to_utf8_fold" 8 | |
3816 | .IX Item "to_utf8_fold" | |
3817 | Convert the \s-1UTF\-8\s0 encoded character at p to its foldcase version and | |
3818 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
3819 | that the ustrp needs to be at least \s-1UTF8_MAXLEN_FOLD+1\s0 bytes since the | |
3820 | foldcase version may be longer than the original character (up to | |
3821 | three characters). | |
3822 | .Sp | |
3823 | The first character of the foldcased version is returned | |
3824 | (but note, as explained above, that there may be more.) | |
3825 | .Sp | |
3826 | .Vb 1 | |
3827 | \& UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp) | |
3828 | .Ve | |
3829 | .IP "to_utf8_lower" 8 | |
3830 | .IX Item "to_utf8_lower" | |
3831 | Convert the \s-1UTF\-8\s0 encoded character at p to its lowercase version and | |
3832 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
3833 | that the ustrp needs to be at least \s-1UTF8_MAXLEN_UCLC+1\s0 bytes since the | |
3834 | lowercase version may be longer than the original character (up to two | |
3835 | characters). | |
3836 | .Sp | |
3837 | The first character of the lowercased version is returned | |
3838 | (but note, as explained above, that there may be more.) | |
3839 | .Sp | |
3840 | .Vb 1 | |
3841 | \& UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp) | |
3842 | .Ve | |
3843 | .IP "to_utf8_title" 8 | |
3844 | .IX Item "to_utf8_title" | |
3845 | Convert the \s-1UTF\-8\s0 encoded character at p to its titlecase version and | |
3846 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
3847 | that the ustrp needs to be at least \s-1UTF8_MAXLEN_UCLC+1\s0 bytes since the | |
3848 | titlecase version may be longer than the original character (up to two | |
3849 | characters). | |
3850 | .Sp | |
3851 | The first character of the titlecased version is returned | |
3852 | (but note, as explained above, that there may be more.) | |
3853 | .Sp | |
3854 | .Vb 1 | |
3855 | \& UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp) | |
3856 | .Ve | |
3857 | .IP "to_utf8_upper" 8 | |
3858 | .IX Item "to_utf8_upper" | |
3859 | Convert the \s-1UTF\-8\s0 encoded character at p to its uppercase version and | |
3860 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
3861 | that the ustrp needs to be at least \s-1UTF8_MAXLEN_UCLC+1\s0 bytes since the | |
3862 | uppercase version may be longer than the original character (up to two | |
3863 | characters). | |
3864 | .Sp | |
3865 | The first character of the uppercased version is returned | |
3866 | (but note, as explained above, that there may be more.) | |
3867 | .Sp | |
3868 | .Vb 1 | |
3869 | \& UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp) | |
3870 | .Ve | |
3871 | .IP "utf8n_to_uvchr" 8 | |
3872 | .IX Item "utf8n_to_uvchr" | |
3873 | Returns the native character value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
3874 | which is assumed to be in \s-1UTF8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
3875 | length, in bytes, of that character. | |
3876 | .Sp | |
3877 | Allows length and flags to be passed to low level routine. | |
3878 | .Sp | |
3879 | .Vb 1 | |
3880 | \& UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) | |
3881 | .Ve | |
3882 | .IP "utf8n_to_uvuni" 8 | |
3883 | .IX Item "utf8n_to_uvuni" | |
3884 | Bottom level \s-1UTF\-8\s0 decode routine. | |
3885 | Returns the unicode code point value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
3886 | which is assumed to be in \s-1UTF8\s0 encoding and no longer than \f(CW\*(C`curlen\*(C'\fR; | |
3887 | \&\f(CW\*(C`retlen\*(C'\fR will be set to the length, in bytes, of that character. | |
3888 | .Sp | |
3889 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF8\s0 character, the behaviour | |
3890 | is dependent on the value of \f(CW\*(C`flags\*(C'\fR: if it contains \s-1UTF8_CHECK_ONLY\s0, | |
3891 | it is assumed that the caller will raise a warning, and this function | |
3892 | will silently just set \f(CW\*(C`retlen\*(C'\fR to \f(CW\*(C`\-1\*(C'\fR and return zero. If the | |
3893 | \&\f(CW\*(C`flags\*(C'\fR does not contain \s-1UTF8_CHECK_ONLY\s0, warnings about | |
3894 | malformations will be given, \f(CW\*(C`retlen\*(C'\fR will be set to the expected | |
3895 | length of the \s-1UTF\-8\s0 character in bytes, and zero will be returned. | |
3896 | .Sp | |
3897 | The \f(CW\*(C`flags\*(C'\fR can also contain various flags to allow deviations from | |
3898 | the strict \s-1UTF\-8\s0 encoding (see \fIutf8.h\fR). | |
3899 | .Sp | |
3900 | Most code should use \fIutf8_to_uvchr()\fR rather than call this directly. | |
3901 | .Sp | |
3902 | .Vb 1 | |
3903 | \& UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) | |
3904 | .Ve | |
3905 | .IP "utf8_distance" 8 | |
3906 | .IX Item "utf8_distance" | |
3907 | Returns the number of \s-1UTF8\s0 characters between the \s-1UTF\-8\s0 pointers \f(CW\*(C`a\*(C'\fR | |
3908 | and \f(CW\*(C`b\*(C'\fR. | |
3909 | .Sp | |
3910 | \&\s-1WARNING:\s0 use only if you *know* that the pointers point inside the | |
3911 | same \s-1UTF\-8\s0 buffer. | |
3912 | .Sp | |
3913 | .Vb 1 | |
3914 | \& IV utf8_distance(U8 *a, U8 *b) | |
3915 | .Ve | |
3916 | .IP "utf8_hop" 8 | |
3917 | .IX Item "utf8_hop" | |
3918 | Return the \s-1UTF\-8\s0 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either | |
3919 | forward or backward. | |
3920 | .Sp | |
3921 | \&\s-1WARNING:\s0 do not use the following unless you *know* \f(CW\*(C`off\*(C'\fR is within | |
3922 | the \s-1UTF\-8\s0 data pointed to by \f(CW\*(C`s\*(C'\fR *and* that on entry \f(CW\*(C`s\*(C'\fR is aligned | |
3923 | on the first byte of character or just after the last byte of a character. | |
3924 | .Sp | |
3925 | .Vb 1 | |
3926 | \& U8* utf8_hop(U8 *s, I32 off) | |
3927 | .Ve | |
3928 | .IP "utf8_length" 8 | |
3929 | .IX Item "utf8_length" | |
3930 | Return the length of the \s-1UTF\-8\s0 char encoded string \f(CW\*(C`s\*(C'\fR in characters. | |
3931 | Stops at \f(CW\*(C`e\*(C'\fR (inclusive). If \f(CW\*(C`e < s\*(C'\fR or if the scan would end | |
3932 | up past \f(CW\*(C`e\*(C'\fR, croaks. | |
3933 | .Sp | |
3934 | .Vb 1 | |
3935 | \& STRLEN utf8_length(U8* s, U8 *e) | |
3936 | .Ve | |
3937 | .IP "utf8_to_bytes" 8 | |
3938 | .IX Item "utf8_to_bytes" | |
3939 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1UTF8\s0 into byte encoding. | |
3940 | Unlike \f(CW\*(C`bytes_to_utf8\*(C'\fR, this over-writes the original string, and | |
3941 | updates len to contain the new length. | |
3942 | Returns zero on failure, setting \f(CW\*(C`len\*(C'\fR to \-1. | |
3943 | .Sp | |
3944 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
3945 | removed without notice. | |
3946 | .Sp | |
3947 | .Vb 1 | |
3948 | \& U8* utf8_to_bytes(U8 *s, STRLEN *len) | |
3949 | .Ve | |
3950 | .IP "utf8_to_uvchr" 8 | |
3951 | .IX Item "utf8_to_uvchr" | |
3952 | Returns the native character value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
3953 | which is assumed to be in \s-1UTF8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
3954 | length, in bytes, of that character. | |
3955 | .Sp | |
3956 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF8\s0 character, zero is | |
3957 | returned and retlen is set, if possible, to \-1. | |
3958 | .Sp | |
3959 | .Vb 1 | |
3960 | \& UV utf8_to_uvchr(U8 *s, STRLEN* retlen) | |
3961 | .Ve | |
3962 | .IP "utf8_to_uvuni" 8 | |
3963 | .IX Item "utf8_to_uvuni" | |
3964 | Returns the Unicode code point of the first character in the string \f(CW\*(C`s\*(C'\fR | |
3965 | which is assumed to be in \s-1UTF8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
3966 | length, in bytes, of that character. | |
3967 | .Sp | |
3968 | This function should only be used when returned \s-1UV\s0 is considered | |
3969 | an index into the Unicode semantic tables (e.g. swashes). | |
3970 | .Sp | |
3971 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF8\s0 character, zero is | |
3972 | returned and retlen is set, if possible, to \-1. | |
3973 | .Sp | |
3974 | .Vb 1 | |
3975 | \& UV utf8_to_uvuni(U8 *s, STRLEN* retlen) | |
3976 | .Ve | |
3977 | .IP "uvchr_to_utf8" 8 | |
3978 | .IX Item "uvchr_to_utf8" | |
3979 | Adds the \s-1UTF8\s0 representation of the Native codepoint \f(CW\*(C`uv\*(C'\fR to the end | |
3980 | of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should be have at least \f(CW\*(C`UTF8_MAXLEN+1\*(C'\fR free | |
3981 | bytes available. The return value is the pointer to the byte after the | |
3982 | end of the new character. In other words, | |
3983 | .Sp | |
3984 | .Vb 1 | |
3985 | \& d = uvchr_to_utf8(d, uv); | |
3986 | .Ve | |
3987 | .Sp | |
3988 | is the recommended wide native character-aware way of saying | |
3989 | .Sp | |
3990 | .Vb 1 | |
3991 | \& *(d++) = uv; | |
3992 | .Ve | |
3993 | .Sp | |
3994 | .Vb 1 | |
3995 | \& U8* uvchr_to_utf8(U8 *d, UV uv) | |
3996 | .Ve | |
3997 | .IP "uvuni_to_utf8_flags" 8 | |
3998 | .IX Item "uvuni_to_utf8_flags" | |
3999 | Adds the \s-1UTF8\s0 representation of the Unicode codepoint \f(CW\*(C`uv\*(C'\fR to the end | |
4000 | of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should be have at least \f(CW\*(C`UTF8_MAXLEN+1\*(C'\fR free | |
4001 | bytes available. The return value is the pointer to the byte after the | |
4002 | end of the new character. In other words, | |
4003 | .Sp | |
4004 | .Vb 1 | |
4005 | \& d = uvuni_to_utf8_flags(d, uv, flags); | |
4006 | .Ve | |
4007 | .Sp | |
4008 | or, in most cases, | |
4009 | .Sp | |
4010 | .Vb 1 | |
4011 | \& d = uvuni_to_utf8(d, uv); | |
4012 | .Ve | |
4013 | .Sp | |
4014 | (which is equivalent to) | |
4015 | .Sp | |
4016 | .Vb 1 | |
4017 | \& d = uvuni_to_utf8_flags(d, uv, 0); | |
4018 | .Ve | |
4019 | .Sp | |
4020 | is the recommended Unicode-aware way of saying | |
4021 | .Sp | |
4022 | .Vb 1 | |
4023 | \& *(d++) = uv; | |
4024 | .Ve | |
4025 | .Sp | |
4026 | .Vb 1 | |
4027 | \& U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) | |
4028 | .Ve | |
4029 | .ie n .SH "Variables created by ""xsubpp""\fP and \f(CW""xsubpp"" internal functions" | |
4030 | .el .SH "Variables created by \f(CWxsubpp\fP and \f(CWxsubpp\fP internal functions" | |
4031 | .IX Header "Variables created by xsubpp and xsubpp internal functions" | |
4032 | .IP "ax" 8 | |
4033 | .IX Item "ax" | |
4034 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset, | |
4035 | 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 | |
4036 | must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable. | |
4037 | .Sp | |
4038 | .Vb 1 | |
4039 | \& I32 ax | |
4040 | .Ve | |
4041 | .IP "\s-1CLASS\s0" 8 | |
4042 | .IX Item "CLASS" | |
4043 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the | |
4044 | class name for a \*(C+ \s-1XS\s0 constructor. This is always a \f(CW\*(C`char*\*(C'\fR. See \f(CW\*(C`THIS\*(C'\fR. | |
4045 | .Sp | |
4046 | .Vb 1 | |
4047 | \& char* CLASS | |
4048 | .Ve | |
4049 | .IP "dAX" 8 | |
4050 | .IX Item "dAX" | |
4051 | Sets up the \f(CW\*(C`ax\*(C'\fR variable. | |
4052 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. | |
4053 | .Sp | |
4054 | .Vb 1 | |
4055 | \& dAX; | |
4056 | .Ve | |
4057 | .IP "dITEMS" 8 | |
4058 | .IX Item "dITEMS" | |
4059 | Sets up the \f(CW\*(C`items\*(C'\fR variable. | |
4060 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. | |
4061 | .Sp | |
4062 | .Vb 1 | |
4063 | \& dITEMS; | |
4064 | .Ve | |
4065 | .IP "dXSARGS" 8 | |
4066 | .IX Item "dXSARGS" | |
4067 | Sets up stack and mark pointers for an \s-1XSUB\s0, calling dSP and dMARK. | |
4068 | 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. | |
4069 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. | |
4070 | .Sp | |
4071 | .Vb 1 | |
4072 | \& dXSARGS; | |
4073 | .Ve | |
4074 | .IP "dXSI32" 8 | |
4075 | .IX Item "dXSI32" | |
4076 | Sets up the \f(CW\*(C`ix\*(C'\fR variable for an \s-1XSUB\s0 which has aliases. This is usually | |
4077 | handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. | |
4078 | .Sp | |
4079 | .Vb 1 | |
4080 | \& dXSI32; | |
4081 | .Ve | |
4082 | .IP "items" 8 | |
4083 | .IX Item "items" | |
4084 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of | |
4085 | items on the stack. See \*(L"Variable\-length Parameter Lists\*(R" in perlxs. | |
4086 | .Sp | |
4087 | .Vb 1 | |
4088 | \& I32 items | |
4089 | .Ve | |
4090 | .IP "ix" 8 | |
4091 | .IX Item "ix" | |
4092 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an | |
4093 | \&\s-1XSUB\s0's aliases was used to invoke it. See \*(L"The \s-1ALIAS:\s0 Keyword\*(R" in perlxs. | |
4094 | .Sp | |
4095 | .Vb 1 | |
4096 | \& I32 ix | |
4097 | .Ve | |
4098 | .IP "newXSproto" 8 | |
4099 | .IX Item "newXSproto" | |
4100 | Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. Adds Perl prototypes to | |
4101 | the subs. | |
4102 | .IP "\s-1RETVAL\s0" 8 | |
4103 | .IX Item "RETVAL" | |
4104 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an | |
4105 | \&\s-1XSUB\s0. This is always the proper type for the \s-1XSUB\s0. See | |
4106 | \&\*(L"The \s-1RETVAL\s0 Variable\*(R" in perlxs. | |
4107 | .Sp | |
4108 | .Vb 1 | |
4109 | \& (whatever) RETVAL | |
4110 | .Ve | |
4111 | .IP "\s-1ST\s0" 8 | |
4112 | .IX Item "ST" | |
4113 | Used to access elements on the \s-1XSUB\s0's stack. | |
4114 | .Sp | |
4115 | .Vb 1 | |
4116 | \& SV* ST(int ix) | |
4117 | .Ve | |
4118 | .IP "\s-1THIS\s0" 8 | |
4119 | .IX Item "THIS" | |
4120 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a \*(C+ | |
4121 | \&\s-1XSUB\s0. This is always the proper type for the \*(C+ object. See \f(CW\*(C`CLASS\*(C'\fR and | |
4122 | \&\*(L"Using \s-1XS\s0 With \*(C+\*(R" in perlxs. | |
4123 | .Sp | |
4124 | .Vb 1 | |
4125 | \& (whatever) THIS | |
4126 | .Ve | |
4127 | .IP "\s-1XS\s0" 8 | |
4128 | .IX Item "XS" | |
4129 | Macro to declare an \s-1XSUB\s0 and its C parameter list. This is handled by | |
4130 | \&\f(CW\*(C`xsubpp\*(C'\fR. | |
4131 | .IP "\s-1XSRETURN_EMPTY\s0" 8 | |
4132 | .IX Item "XSRETURN_EMPTY" | |
4133 | Return an empty list from an \s-1XSUB\s0 immediately. | |
4134 | .Sp | |
4135 | .Vb 1 | |
4136 | \& XSRETURN_EMPTY; | |
4137 | .Ve | |
4138 | .IP "\s-1XS_VERSION\s0" 8 | |
4139 | .IX Item "XS_VERSION" | |
4140 | The version identifier for an \s-1XS\s0 module. This is usually | |
4141 | handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. See \f(CW\*(C`XS_VERSION_BOOTCHECK\*(C'\fR. | |
4142 | .IP "\s-1XS_VERSION_BOOTCHECK\s0" 8 | |
4143 | .IX Item "XS_VERSION_BOOTCHECK" | |
4144 | Macro to verify that a \s-1PM\s0 module's \f(CW$VERSION\fR variable matches the \s-1XS\s0 | |
4145 | module's \f(CW\*(C`XS_VERSION\*(C'\fR variable. This is usually handled automatically by | |
4146 | \&\f(CW\*(C`xsubpp\*(C'\fR. See \*(L"The \s-1VERSIONCHECK:\s0 Keyword\*(R" in perlxs. | |
4147 | .Sp | |
4148 | .Vb 1 | |
4149 | \& XS_VERSION_BOOTCHECK; | |
4150 | .Ve | |
4151 | .SH "Warning and Dieing" | |
4152 | .IX Header "Warning and Dieing" | |
4153 | .IP "croak" 8 | |
4154 | .IX Item "croak" | |
4155 | This is the XSUB\-writer's interface to Perl's \f(CW\*(C`die\*(C'\fR function. | |
4156 | Normally use this function the same way you use the C \f(CW\*(C`printf\*(C'\fR | |
4157 | function. See \f(CW\*(C`warn\*(C'\fR. | |
4158 | .Sp | |
4159 | If you want to throw an exception object, assign the object to | |
4160 | \&\f(CW$@\fR and then pass \f(CW\*(C`Nullch\*(C'\fR to \fIcroak()\fR: | |
4161 | .Sp | |
4162 | .Vb 3 | |
4163 | \& errsv = get_sv("@", TRUE); | |
4164 | \& sv_setsv(errsv, exception_object); | |
4165 | \& croak(Nullch); | |
4166 | .Ve | |
4167 | .Sp | |
4168 | .Vb 1 | |
4169 | \& void croak(const char* pat, ...) | |
4170 | .Ve | |
4171 | .IP "warn" 8 | |
4172 | .IX Item "warn" | |
4173 | This is the XSUB\-writer's interface to Perl's \f(CW\*(C`warn\*(C'\fR function. Use this | |
4174 | function the same way you use the C \f(CW\*(C`printf\*(C'\fR function. See | |
4175 | \&\f(CW\*(C`croak\*(C'\fR. | |
4176 | .Sp | |
4177 | .Vb 1 | |
4178 | \& void warn(const char* pat, ...) | |
4179 | .Ve | |
4180 | .SH "AUTHORS" | |
4181 | .IX Header "AUTHORS" | |
4182 | Until May 1997, this document was maintained by Jeff Okamoto | |
4183 | <okamoto@corp.hp.com>. It is now maintained as part of Perl itself. | |
4184 | .PP | |
4185 | With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, | |
4186 | Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil | |
4187 | Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, | |
4188 | Stephen McCamant, and Gurusamy Sarathy. | |
4189 | .PP | |
4190 | \&\s-1API\s0 Listing originally by Dean Roehrich <roehrich@cray.com>. | |
4191 | .PP | |
4192 | Updated to be autogenerated from comments in the source by Benjamin Stuhl. | |
4193 | .SH "SEE ALSO" | |
4194 | .IX Header "SEE ALSO" | |
4195 | \&\fIperlguts\fR\|(1), \fIperlxs\fR\|(1), \fIperlxstut\fR\|(1), \fIperlintern\fR\|(1) |