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 "PERLGUTS 1" | |
132 | .TH PERLGUTS 1 "2002-06-08" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlguts \- Introduction to the Perl API | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | This document attempts to describe how to use the Perl \s-1API\s0, as well as | |
138 | containing some info on the basic workings of the Perl core. It is far | |
139 | from complete and probably contains many errors. Please refer any | |
140 | questions or comments to the author below. | |
141 | .SH "Variables" | |
142 | .IX Header "Variables" | |
143 | .Sh "Datatypes" | |
144 | .IX Subsection "Datatypes" | |
145 | Perl has three typedefs that handle Perl's three main data types: | |
146 | .PP | |
147 | .Vb 3 | |
148 | \& SV Scalar Value | |
149 | \& AV Array Value | |
150 | \& HV Hash Value | |
151 | .Ve | |
152 | .PP | |
153 | Each typedef has specific routines that manipulate the various data types. | |
154 | .ie n .Sh "What is an ""\s-1IV\s0""?" | |
155 | .el .Sh "What is an ``\s-1IV\s0''?" | |
156 | .IX Subsection "What is an IV?" | |
157 | Perl uses a special typedef \s-1IV\s0 which is a simple signed integer type that is | |
158 | guaranteed to be large enough to hold a pointer (as well as an integer). | |
159 | Additionally, there is the \s-1UV\s0, which is simply an unsigned \s-1IV\s0. | |
160 | .PP | |
161 | Perl also uses two special typedefs, I32 and I16, which will always be at | |
162 | least 32\-bits and 16\-bits long, respectively. (Again, there are U32 and U16, | |
163 | as well.) They will usually be exactly 32 and 16 bits long, but on Crays | |
164 | they will both be 64 bits. | |
165 | .Sh "Working with SVs" | |
166 | .IX Subsection "Working with SVs" | |
167 | An \s-1SV\s0 can be created and loaded with one command. There are five types of | |
168 | values that can be loaded: an integer value (\s-1IV\s0), an unsigned integer | |
169 | value (\s-1UV\s0), a double (\s-1NV\s0), a string (\s-1PV\s0), and another scalar (\s-1SV\s0). | |
170 | .PP | |
171 | The seven routines are: | |
172 | .PP | |
173 | .Vb 7 | |
174 | \& SV* newSViv(IV); | |
175 | \& SV* newSVuv(UV); | |
176 | \& SV* newSVnv(double); | |
177 | \& SV* newSVpv(const char*, int); | |
178 | \& SV* newSVpvn(const char*, int); | |
179 | \& SV* newSVpvf(const char*, ...); | |
180 | \& SV* newSVsv(SV*); | |
181 | .Ve | |
182 | .PP | |
183 | If you require more complex initialisation you can create an empty \s-1SV\s0 with | |
184 | newSV(len). If \f(CW\*(C`len\*(C'\fR is 0 an empty \s-1SV\s0 of type \s-1NULL\s0 is returned, else an | |
185 | \&\s-1SV\s0 of type \s-1PV\s0 is returned with len + 1 (for the \s-1NUL\s0) bytes of storage | |
186 | allocated, accessible via SvPVX. In both cases the \s-1SV\s0 has value undef. | |
187 | .PP | |
188 | .Vb 2 | |
189 | \& SV* newSV(0); /* no storage allocated */ | |
190 | \& SV* newSV(10); /* 10 (+1) bytes of uninitialised storage allocated */ | |
191 | .Ve | |
192 | .PP | |
193 | To change the value of an *already\-existing* \s-1SV\s0, there are eight routines: | |
194 | .PP | |
195 | .Vb 8 | |
196 | \& void sv_setiv(SV*, IV); | |
197 | \& void sv_setuv(SV*, UV); | |
198 | \& void sv_setnv(SV*, double); | |
199 | \& void sv_setpv(SV*, const char*); | |
200 | \& void sv_setpvn(SV*, const char*, int) | |
201 | \& void sv_setpvf(SV*, const char*, ...); | |
202 | \& void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *); | |
203 | \& void sv_setsv(SV*, SV*); | |
204 | .Ve | |
205 | .PP | |
206 | Notice that you can choose to specify the length of the string to be | |
207 | assigned by using \f(CW\*(C`sv_setpvn\*(C'\fR, \f(CW\*(C`newSVpvn\*(C'\fR, or \f(CW\*(C`newSVpv\*(C'\fR, or you may | |
208 | allow Perl to calculate the length by using \f(CW\*(C`sv_setpv\*(C'\fR or by specifying | |
209 | 0 as the second argument to \f(CW\*(C`newSVpv\*(C'\fR. Be warned, though, that Perl will | |
210 | determine the string's length by using \f(CW\*(C`strlen\*(C'\fR, which depends on the | |
211 | string terminating with a \s-1NUL\s0 character. | |
212 | .PP | |
213 | The arguments of \f(CW\*(C`sv_setpvf\*(C'\fR are processed like \f(CW\*(C`sprintf\*(C'\fR, and the | |
214 | formatted output becomes the value. | |
215 | .PP | |
216 | \&\f(CW\*(C`sv_vsetpvfn\*(C'\fR is an analogue of \f(CW\*(C`vsprintf\*(C'\fR, but it allows you to specify | |
217 | either a pointer to a variable argument list or the address and length of | |
218 | an array of SVs. The last argument points to a boolean; on return, if that | |
219 | boolean is true, then locale-specific information has been used to format | |
220 | the string, and the string's contents are therefore untrustworthy (see | |
221 | perlsec). This pointer may be \s-1NULL\s0 if that information is not | |
222 | important. Note that this function requires you to specify the length of | |
223 | the format. | |
224 | .PP | |
225 | \&\s-1STRLEN\s0 is an integer type (Size_t, usually defined as size_t in | |
226 | config.h) guaranteed to be large enough to represent the size of | |
227 | any string that perl can handle. | |
228 | .PP | |
229 | The \f(CW\*(C`sv_set*()\*(C'\fR functions are not generic enough to operate on values | |
230 | that have \*(L"magic\*(R". See \*(L"Magic Virtual Tables\*(R" later in this document. | |
231 | .PP | |
232 | All SVs that contain strings should be terminated with a \s-1NUL\s0 character. | |
233 | If it is not NUL-terminated there is a risk of | |
234 | core dumps and corruptions from code which passes the string to C | |
235 | functions or system calls which expect a NUL-terminated string. | |
236 | Perl's own functions typically add a trailing \s-1NUL\s0 for this reason. | |
237 | Nevertheless, you should be very careful when you pass a string stored | |
238 | in an \s-1SV\s0 to a C function or system call. | |
239 | .PP | |
240 | To access the actual value that an \s-1SV\s0 points to, you can use the macros: | |
241 | .PP | |
242 | .Vb 5 | |
243 | \& SvIV(SV*) | |
244 | \& SvUV(SV*) | |
245 | \& SvNV(SV*) | |
246 | \& SvPV(SV*, STRLEN len) | |
247 | \& SvPV_nolen(SV*) | |
248 | .Ve | |
249 | .PP | |
250 | which will automatically coerce the actual scalar type into an \s-1IV\s0, \s-1UV\s0, double, | |
251 | or string. | |
252 | .PP | |
253 | In the \f(CW\*(C`SvPV\*(C'\fR macro, the length of the string returned is placed into the | |
254 | variable \f(CW\*(C`len\*(C'\fR (this is a macro, so you do \fInot\fR use \f(CW&len\fR). If you do | |
255 | not care what the length of the data is, use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro. | |
256 | Historically the \f(CW\*(C`SvPV\*(C'\fR macro with the global variable \f(CW\*(C`PL_na\*(C'\fR has been | |
257 | used in this case. But that can be quite inefficient because \f(CW\*(C`PL_na\*(C'\fR must | |
258 | be accessed in thread-local storage in threaded Perl. In any case, remember | |
259 | that Perl allows arbitrary strings of data that may both contain NULs and | |
260 | might not be terminated by a \s-1NUL\s0. | |
261 | .PP | |
262 | Also remember that C doesn't allow you to safely say \f(CW\*(C`foo(SvPV(s, len), | |
263 | len);\*(C'\fR. It might work with your compiler, but it won't work for everyone. | |
264 | Break this sort of statement up into separate assignments: | |
265 | .PP | |
266 | .Vb 5 | |
267 | \& SV *s; | |
268 | \& STRLEN len; | |
269 | \& char * ptr; | |
270 | \& ptr = SvPV(s, len); | |
271 | \& foo(ptr, len); | |
272 | .Ve | |
273 | .PP | |
274 | If you want to know if the scalar value is \s-1TRUE\s0, you can use: | |
275 | .PP | |
276 | .Vb 1 | |
277 | \& SvTRUE(SV*) | |
278 | .Ve | |
279 | .PP | |
280 | Although Perl will automatically grow strings for you, if you need to force | |
281 | Perl to allocate more memory for your \s-1SV\s0, you can use the macro | |
282 | .PP | |
283 | .Vb 1 | |
284 | \& SvGROW(SV*, STRLEN newlen) | |
285 | .Ve | |
286 | .PP | |
287 | which will determine if more memory needs to be allocated. If so, it will | |
288 | call the function \f(CW\*(C`sv_grow\*(C'\fR. Note that \f(CW\*(C`SvGROW\*(C'\fR can only increase, not | |
289 | decrease, the allocated memory of an \s-1SV\s0 and that it does not automatically | |
290 | add a byte for the a trailing \s-1NUL\s0 (perl's own string functions typically do | |
291 | \&\f(CW\*(C`SvGROW(sv, len + 1)\*(C'\fR). | |
292 | .PP | |
293 | If you have an \s-1SV\s0 and want to know what kind of data Perl thinks is stored | |
294 | in it, you can use the following macros to check the type of \s-1SV\s0 you have. | |
295 | .PP | |
296 | .Vb 3 | |
297 | \& SvIOK(SV*) | |
298 | \& SvNOK(SV*) | |
299 | \& SvPOK(SV*) | |
300 | .Ve | |
301 | .PP | |
302 | You can get and set the current length of the string stored in an \s-1SV\s0 with | |
303 | the following macros: | |
304 | .PP | |
305 | .Vb 2 | |
306 | \& SvCUR(SV*) | |
307 | \& SvCUR_set(SV*, I32 val) | |
308 | .Ve | |
309 | .PP | |
310 | You can also get a pointer to the end of the string stored in the \s-1SV\s0 | |
311 | with the macro: | |
312 | .PP | |
313 | .Vb 1 | |
314 | \& SvEND(SV*) | |
315 | .Ve | |
316 | .PP | |
317 | But note that these last three macros are valid only if \f(CW\*(C`SvPOK()\*(C'\fR is true. | |
318 | .PP | |
319 | If you want to append something to the end of string stored in an \f(CW\*(C`SV*\*(C'\fR, | |
320 | you can use the following functions: | |
321 | .PP | |
322 | .Vb 5 | |
323 | \& void sv_catpv(SV*, const char*); | |
324 | \& void sv_catpvn(SV*, const char*, STRLEN); | |
325 | \& void sv_catpvf(SV*, const char*, ...); | |
326 | \& void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); | |
327 | \& void sv_catsv(SV*, SV*); | |
328 | .Ve | |
329 | .PP | |
330 | The first function calculates the length of the string to be appended by | |
331 | using \f(CW\*(C`strlen\*(C'\fR. In the second, you specify the length of the string | |
332 | yourself. The third function processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and | |
333 | appends the formatted output. The fourth function works like \f(CW\*(C`vsprintf\*(C'\fR. | |
334 | You can specify the address and length of an array of SVs instead of the | |
335 | va_list argument. The fifth function extends the string stored in the first | |
336 | \&\s-1SV\s0 with the string stored in the second \s-1SV\s0. It also forces the second \s-1SV\s0 | |
337 | to be interpreted as a string. | |
338 | .PP | |
339 | The \f(CW\*(C`sv_cat*()\*(C'\fR functions are not generic enough to operate on values that | |
340 | have \*(L"magic\*(R". See \*(L"Magic Virtual Tables\*(R" later in this document. | |
341 | .PP | |
342 | If you know the name of a scalar variable, you can get a pointer to its \s-1SV\s0 | |
343 | by using the following: | |
344 | .PP | |
345 | .Vb 1 | |
346 | \& SV* get_sv("package::varname", FALSE); | |
347 | .Ve | |
348 | .PP | |
349 | This returns \s-1NULL\s0 if the variable does not exist. | |
350 | .PP | |
351 | If you want to know if this variable (or any other \s-1SV\s0) is actually \f(CW\*(C`defined\*(C'\fR, | |
352 | you can call: | |
353 | .PP | |
354 | .Vb 1 | |
355 | \& SvOK(SV*) | |
356 | .Ve | |
357 | .PP | |
358 | The scalar \f(CW\*(C`undef\*(C'\fR value is stored in an \s-1SV\s0 instance called \f(CW\*(C`PL_sv_undef\*(C'\fR. Its | |
359 | address can be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed. | |
360 | .PP | |
361 | There are also the two values \f(CW\*(C`PL_sv_yes\*(C'\fR and \f(CW\*(C`PL_sv_no\*(C'\fR, which contain Boolean | |
362 | \&\s-1TRUE\s0 and \s-1FALSE\s0 values, respectively. Like \f(CW\*(C`PL_sv_undef\*(C'\fR, their addresses can | |
363 | be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed. | |
364 | .PP | |
365 | Do not be fooled into thinking that \f(CW\*(C`(SV *) 0\*(C'\fR is the same as \f(CW&PL_sv_undef\fR. | |
366 | Take this code: | |
367 | .PP | |
368 | .Vb 5 | |
369 | \& SV* sv = (SV*) 0; | |
370 | \& if (I-am-to-return-a-real-value) { | |
371 | \& sv = sv_2mortal(newSViv(42)); | |
372 | \& } | |
373 | \& sv_setsv(ST(0), sv); | |
374 | .Ve | |
375 | .PP | |
376 | This code tries to return a new \s-1SV\s0 (which contains the value 42) if it should | |
377 | return a real value, or undef otherwise. Instead it has returned a \s-1NULL\s0 | |
378 | pointer which, somewhere down the line, will cause a segmentation violation, | |
379 | bus error, or just weird results. Change the zero to \f(CW&PL_sv_undef\fR in the first | |
380 | line and all will be well. | |
381 | .PP | |
382 | To free an \s-1SV\s0 that you've created, call \f(CW\*(C`SvREFCNT_dec(SV*)\*(C'\fR. Normally this | |
383 | call is not necessary (see \*(L"Reference Counts and Mortality\*(R"). | |
384 | .Sh "Offsets" | |
385 | .IX Subsection "Offsets" | |
386 | Perl provides the function \f(CW\*(C`sv_chop\*(C'\fR to efficiently remove characters | |
387 | from the beginning of a string; you give it an \s-1SV\s0 and a pointer to | |
388 | somewhere inside the \s-1PV\s0, and it discards everything before the | |
389 | pointer. The efficiency comes by means of a little hack: instead of | |
390 | actually removing the characters, \f(CW\*(C`sv_chop\*(C'\fR sets the flag \f(CW\*(C`OOK\*(C'\fR | |
391 | (offset \s-1OK\s0) to signal to other functions that the offset hack is in | |
392 | effect, and it puts the number of bytes chopped off into the \s-1IV\s0 field | |
393 | of the \s-1SV\s0. It then moves the \s-1PV\s0 pointer (called \f(CW\*(C`SvPVX\*(C'\fR) forward that | |
394 | many bytes, and adjusts \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR. | |
395 | .PP | |
396 | Hence, at this point, the start of the buffer that we allocated lives | |
397 | at \f(CW\*(C`SvPVX(sv) \- SvIV(sv)\*(C'\fR in memory and the \s-1PV\s0 pointer is pointing | |
398 | into the middle of this allocated storage. | |
399 | .PP | |
400 | This is best demonstrated by example: | |
401 | .PP | |
402 | .Vb 8 | |
403 | \& % ./perl -Ilib -MDevel::Peek -le '$a="12345"; $a=~s/.//; Dump($a)' | |
404 | \& SV = PVIV(0x8128450) at 0x81340f0 | |
405 | \& REFCNT = 1 | |
406 | \& FLAGS = (POK,OOK,pPOK) | |
407 | \& IV = 1 (OFFSET) | |
408 | \& PV = 0x8135781 ( "1" . ) "2345"\e0 | |
409 | \& CUR = 4 | |
410 | \& LEN = 5 | |
411 | .Ve | |
412 | .PP | |
413 | Here the number of bytes chopped off (1) is put into \s-1IV\s0, and | |
414 | \&\f(CW\*(C`Devel::Peek::Dump\*(C'\fR helpfully reminds us that this is an offset. The | |
415 | portion of the string between the \*(L"real\*(R" and the \*(L"fake\*(R" beginnings is | |
416 | shown in parentheses, and the values of \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR reflect | |
417 | the fake beginning, not the real one. | |
418 | .PP | |
419 | Something similar to the offset hack is performed on AVs to enable | |
420 | efficient shifting and splicing off the beginning of the array; while | |
421 | \&\f(CW\*(C`AvARRAY\*(C'\fR points to the first element in the array that is visible from | |
422 | Perl, \f(CW\*(C`AvALLOC\*(C'\fR points to the real start of the C array. These are | |
423 | usually the same, but a \f(CW\*(C`shift\*(C'\fR operation can be carried out by | |
424 | increasing \f(CW\*(C`AvARRAY\*(C'\fR by one and decreasing \f(CW\*(C`AvFILL\*(C'\fR and \f(CW\*(C`AvLEN\*(C'\fR. | |
425 | Again, the location of the real start of the C array only comes into | |
426 | play when freeing the array. See \f(CW\*(C`av_shift\*(C'\fR in \fIav.c\fR. | |
427 | .Sh "What's Really Stored in an \s-1SV\s0?" | |
428 | .IX Subsection "What's Really Stored in an SV?" | |
429 | Recall that the usual method of determining the type of scalar you have is | |
430 | to use \f(CW\*(C`Sv*OK\*(C'\fR macros. Because a scalar can be both a number and a string, | |
431 | usually these macros will always return \s-1TRUE\s0 and calling the \f(CW\*(C`Sv*V\*(C'\fR | |
432 | macros will do the appropriate conversion of string to integer/double or | |
433 | integer/double to string. | |
434 | .PP | |
435 | If you \fIreally\fR need to know if you have an integer, double, or string | |
436 | pointer in an \s-1SV\s0, you can use the following three macros instead: | |
437 | .PP | |
438 | .Vb 3 | |
439 | \& SvIOKp(SV*) | |
440 | \& SvNOKp(SV*) | |
441 | \& SvPOKp(SV*) | |
442 | .Ve | |
443 | .PP | |
444 | These will tell you if you truly have an integer, double, or string pointer | |
445 | stored in your \s-1SV\s0. The \*(L"p\*(R" stands for private. | |
446 | .PP | |
447 | The are various ways in which the private and public flags may differ. | |
448 | For example, a tied \s-1SV\s0 may have a valid underlying value in the \s-1IV\s0 slot | |
449 | (so SvIOKp is true), but the data should be accessed via the \s-1FETCH\s0 | |
450 | routine rather than directly, so SvIOK is false. Another is when | |
451 | numeric conversion has occured and precision has been lost: only the | |
452 | private flag is set on 'lossy' values. So when an \s-1NV\s0 is converted to an | |
453 | \&\s-1IV\s0 with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be. | |
454 | .PP | |
455 | In general, though, it's best to use the \f(CW\*(C`Sv*V\*(C'\fR macros. | |
456 | .Sh "Working with AVs" | |
457 | .IX Subsection "Working with AVs" | |
458 | There are two ways to create and load an \s-1AV\s0. The first method creates an | |
459 | empty \s-1AV:\s0 | |
460 | .PP | |
461 | .Vb 1 | |
462 | \& AV* newAV(); | |
463 | .Ve | |
464 | .PP | |
465 | The second method both creates the \s-1AV\s0 and initially populates it with SVs: | |
466 | .PP | |
467 | .Vb 1 | |
468 | \& AV* av_make(I32 num, SV **ptr); | |
469 | .Ve | |
470 | .PP | |
471 | The second argument points to an array containing \f(CW\*(C`num\*(C'\fR \f(CW\*(C`SV*\*(C'\fR's. Once the | |
472 | \&\s-1AV\s0 has been created, the SVs can be destroyed, if so desired. | |
473 | .PP | |
474 | Once the \s-1AV\s0 has been created, the following operations are possible on AVs: | |
475 | .PP | |
476 | .Vb 4 | |
477 | \& void av_push(AV*, SV*); | |
478 | \& SV* av_pop(AV*); | |
479 | \& SV* av_shift(AV*); | |
480 | \& void av_unshift(AV*, I32 num); | |
481 | .Ve | |
482 | .PP | |
483 | These should be familiar operations, with the exception of \f(CW\*(C`av_unshift\*(C'\fR. | |
484 | This routine adds \f(CW\*(C`num\*(C'\fR elements at the front of the array with the \f(CW\*(C`undef\*(C'\fR | |
485 | value. You must then use \f(CW\*(C`av_store\*(C'\fR (described below) to assign values | |
486 | to these new elements. | |
487 | .PP | |
488 | Here are some other functions: | |
489 | .PP | |
490 | .Vb 3 | |
491 | \& I32 av_len(AV*); | |
492 | \& SV** av_fetch(AV*, I32 key, I32 lval); | |
493 | \& SV** av_store(AV*, I32 key, SV* val); | |
494 | .Ve | |
495 | .PP | |
496 | The \f(CW\*(C`av_len\*(C'\fR function returns the highest index value in array (just | |
497 | like $#array in Perl). If the array is empty, \-1 is returned. The | |
498 | \&\f(CW\*(C`av_fetch\*(C'\fR function returns the value at index \f(CW\*(C`key\*(C'\fR, but if \f(CW\*(C`lval\*(C'\fR | |
499 | is non\-zero, then \f(CW\*(C`av_fetch\*(C'\fR will store an undef value at that index. | |
500 | The \f(CW\*(C`av_store\*(C'\fR function stores the value \f(CW\*(C`val\*(C'\fR at index \f(CW\*(C`key\*(C'\fR, and does | |
501 | not increment the reference count of \f(CW\*(C`val\*(C'\fR. Thus the caller is responsible | |
502 | for taking care of that, and if \f(CW\*(C`av_store\*(C'\fR returns \s-1NULL\s0, the caller will | |
503 | have to decrement the reference count to avoid a memory leak. Note that | |
504 | \&\f(CW\*(C`av_fetch\*(C'\fR and \f(CW\*(C`av_store\*(C'\fR both return \f(CW\*(C`SV**\*(C'\fR's, not \f(CW\*(C`SV*\*(C'\fR's as their | |
505 | return value. | |
506 | .PP | |
507 | .Vb 3 | |
508 | \& void av_clear(AV*); | |
509 | \& void av_undef(AV*); | |
510 | \& void av_extend(AV*, I32 key); | |
511 | .Ve | |
512 | .PP | |
513 | The \f(CW\*(C`av_clear\*(C'\fR function deletes all the elements in the AV* array, but | |
514 | does not actually delete the array itself. The \f(CW\*(C`av_undef\*(C'\fR function will | |
515 | delete all the elements in the array plus the array itself. The | |
516 | \&\f(CW\*(C`av_extend\*(C'\fR function extends the array so that it contains at least \f(CW\*(C`key+1\*(C'\fR | |
517 | elements. If \f(CW\*(C`key+1\*(C'\fR is less than the currently allocated length of the array, | |
518 | then nothing is done. | |
519 | .PP | |
520 | If you know the name of an array variable, you can get a pointer to its \s-1AV\s0 | |
521 | by using the following: | |
522 | .PP | |
523 | .Vb 1 | |
524 | \& AV* get_av("package::varname", FALSE); | |
525 | .Ve | |
526 | .PP | |
527 | This returns \s-1NULL\s0 if the variable does not exist. | |
528 | .PP | |
529 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" for more | |
530 | information on how to use the array access functions on tied arrays. | |
531 | .Sh "Working with HVs" | |
532 | .IX Subsection "Working with HVs" | |
533 | To create an \s-1HV\s0, you use the following routine: | |
534 | .PP | |
535 | .Vb 1 | |
536 | \& HV* newHV(); | |
537 | .Ve | |
538 | .PP | |
539 | Once the \s-1HV\s0 has been created, the following operations are possible on HVs: | |
540 | .PP | |
541 | .Vb 2 | |
542 | \& SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash); | |
543 | \& SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval); | |
544 | .Ve | |
545 | .PP | |
546 | The \f(CW\*(C`klen\*(C'\fR parameter is the length of the key being passed in (Note that | |
547 | you cannot pass 0 in as a value of \f(CW\*(C`klen\*(C'\fR to tell Perl to measure the | |
548 | length of the key). The \f(CW\*(C`val\*(C'\fR argument contains the \s-1SV\s0 pointer to the | |
549 | scalar being stored, and \f(CW\*(C`hash\*(C'\fR is the precomputed hash value (zero if | |
550 | you want \f(CW\*(C`hv_store\*(C'\fR to calculate it for you). The \f(CW\*(C`lval\*(C'\fR parameter | |
551 | indicates whether this fetch is actually a part of a store operation, in | |
552 | which case a new undefined value will be added to the \s-1HV\s0 with the supplied | |
553 | key and \f(CW\*(C`hv_fetch\*(C'\fR will return as if the value had already existed. | |
554 | .PP | |
555 | Remember that \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_fetch\*(C'\fR return \f(CW\*(C`SV**\*(C'\fR's and not just | |
556 | \&\f(CW\*(C`SV*\*(C'\fR. To access the scalar value, you must first dereference the return | |
557 | value. However, you should check to make sure that the return value is | |
558 | not \s-1NULL\s0 before dereferencing it. | |
559 | .PP | |
560 | These two functions check if a hash table entry exists, and deletes it. | |
561 | .PP | |
562 | .Vb 2 | |
563 | \& bool hv_exists(HV*, const char* key, U32 klen); | |
564 | \& SV* hv_delete(HV*, const char* key, U32 klen, I32 flags); | |
565 | .Ve | |
566 | .PP | |
567 | If \f(CW\*(C`flags\*(C'\fR does not include the \f(CW\*(C`G_DISCARD\*(C'\fR flag then \f(CW\*(C`hv_delete\*(C'\fR will | |
568 | create and return a mortal copy of the deleted value. | |
569 | .PP | |
570 | And more miscellaneous functions: | |
571 | .PP | |
572 | .Vb 2 | |
573 | \& void hv_clear(HV*); | |
574 | \& void hv_undef(HV*); | |
575 | .Ve | |
576 | .PP | |
577 | Like their \s-1AV\s0 counterparts, \f(CW\*(C`hv_clear\*(C'\fR deletes all the entries in the hash | |
578 | table but does not actually delete the hash table. The \f(CW\*(C`hv_undef\*(C'\fR deletes | |
579 | both the entries and the hash table itself. | |
580 | .PP | |
581 | Perl keeps the actual data in linked list of structures with a typedef of \s-1HE\s0. | |
582 | These contain the actual key and value pointers (plus extra administrative | |
583 | overhead). The key is a string pointer; the value is an \f(CW\*(C`SV*\*(C'\fR. However, | |
584 | once you have an \f(CW\*(C`HE*\*(C'\fR, to get the actual key and value, use the routines | |
585 | specified below. | |
586 | .PP | |
587 | .Vb 16 | |
588 | \& I32 hv_iterinit(HV*); | |
589 | \& /* Prepares starting point to traverse hash table */ | |
590 | \& HE* hv_iternext(HV*); | |
591 | \& /* Get the next entry, and return a pointer to a | |
592 | \& structure that has both the key and value */ | |
593 | \& char* hv_iterkey(HE* entry, I32* retlen); | |
594 | \& /* Get the key from an HE structure and also return | |
595 | \& the length of the key string */ | |
596 | \& SV* hv_iterval(HV*, HE* entry); | |
597 | \& /* Return an SV pointer to the value of the HE | |
598 | \& structure */ | |
599 | \& SV* hv_iternextsv(HV*, char** key, I32* retlen); | |
600 | \& /* This convenience routine combines hv_iternext, | |
601 | \& hv_iterkey, and hv_iterval. The key and retlen | |
602 | \& arguments are return values for the key and its | |
603 | \& length. The value is returned in the SV* argument */ | |
604 | .Ve | |
605 | .PP | |
606 | If you know the name of a hash variable, you can get a pointer to its \s-1HV\s0 | |
607 | by using the following: | |
608 | .PP | |
609 | .Vb 1 | |
610 | \& HV* get_hv("package::varname", FALSE); | |
611 | .Ve | |
612 | .PP | |
613 | This returns \s-1NULL\s0 if the variable does not exist. | |
614 | .PP | |
615 | The hash algorithm is defined in the \f(CW\*(C`PERL_HASH(hash, key, klen)\*(C'\fR macro: | |
616 | .PP | |
617 | .Vb 4 | |
618 | \& hash = 0; | |
619 | \& while (klen--) | |
620 | \& hash = (hash * 33) + *key++; | |
621 | \& hash = hash + (hash >> 5); /* after 5.6 */ | |
622 | .Ve | |
623 | .PP | |
624 | The last step was added in version 5.6 to improve distribution of | |
625 | lower bits in the resulting hash value. | |
626 | .PP | |
627 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" for more | |
628 | information on how to use the hash access functions on tied hashes. | |
629 | .Sh "Hash \s-1API\s0 Extensions" | |
630 | .IX Subsection "Hash API Extensions" | |
631 | Beginning with version 5.004, the following functions are also supported: | |
632 | .PP | |
633 | .Vb 2 | |
634 | \& HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash); | |
635 | \& HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash); | |
636 | .Ve | |
637 | .PP | |
638 | .Vb 2 | |
639 | \& bool hv_exists_ent (HV* tb, SV* key, U32 hash); | |
640 | \& SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash); | |
641 | .Ve | |
642 | .PP | |
643 | .Vb 1 | |
644 | \& SV* hv_iterkeysv (HE* entry); | |
645 | .Ve | |
646 | .PP | |
647 | Note that these functions take \f(CW\*(C`SV*\*(C'\fR keys, which simplifies writing | |
648 | of extension code that deals with hash structures. These functions | |
649 | also allow passing of \f(CW\*(C`SV*\*(C'\fR keys to \f(CW\*(C`tie\*(C'\fR functions without forcing | |
650 | you to stringify the keys (unlike the previous set of functions). | |
651 | .PP | |
652 | They also return and accept whole hash entries (\f(CW\*(C`HE*\*(C'\fR), making their | |
653 | use more efficient (since the hash number for a particular string | |
654 | doesn't have to be recomputed every time). See perlapi for detailed | |
655 | descriptions. | |
656 | .PP | |
657 | The following macros must always be used to access the contents of hash | |
658 | entries. Note that the arguments to these macros must be simple | |
659 | variables, since they may get evaluated more than once. See | |
660 | perlapi for detailed descriptions of these macros. | |
661 | .PP | |
662 | .Vb 6 | |
663 | \& HePV(HE* he, STRLEN len) | |
664 | \& HeVAL(HE* he) | |
665 | \& HeHASH(HE* he) | |
666 | \& HeSVKEY(HE* he) | |
667 | \& HeSVKEY_force(HE* he) | |
668 | \& HeSVKEY_set(HE* he, SV* sv) | |
669 | .Ve | |
670 | .PP | |
671 | These two lower level macros are defined, but must only be used when | |
672 | dealing with keys that are not \f(CW\*(C`SV*\*(C'\fRs: | |
673 | .PP | |
674 | .Vb 2 | |
675 | \& HeKEY(HE* he) | |
676 | \& HeKLEN(HE* he) | |
677 | .Ve | |
678 | .PP | |
679 | Note that both \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_store_ent\*(C'\fR do not increment the | |
680 | reference count of the stored \f(CW\*(C`val\*(C'\fR, which is the caller's responsibility. | |
681 | If these functions return a \s-1NULL\s0 value, the caller will usually have to | |
682 | decrement the reference count of \f(CW\*(C`val\*(C'\fR to avoid a memory leak. | |
683 | .Sh "References" | |
684 | .IX Subsection "References" | |
685 | References are a special type of scalar that point to other data types | |
686 | (including references). | |
687 | .PP | |
688 | To create a reference, use either of the following functions: | |
689 | .PP | |
690 | .Vb 2 | |
691 | \& SV* newRV_inc((SV*) thing); | |
692 | \& SV* newRV_noinc((SV*) thing); | |
693 | .Ve | |
694 | .PP | |
695 | The \f(CW\*(C`thing\*(C'\fR argument can be any of an \f(CW\*(C`SV*\*(C'\fR, \f(CW\*(C`AV*\*(C'\fR, or \f(CW\*(C`HV*\*(C'\fR. The | |
696 | functions are identical except that \f(CW\*(C`newRV_inc\*(C'\fR increments the reference | |
697 | count of the \f(CW\*(C`thing\*(C'\fR, while \f(CW\*(C`newRV_noinc\*(C'\fR does not. For historical | |
698 | reasons, \f(CW\*(C`newRV\*(C'\fR is a synonym for \f(CW\*(C`newRV_inc\*(C'\fR. | |
699 | .PP | |
700 | Once you have a reference, you can use the following macro to dereference | |
701 | the reference: | |
702 | .PP | |
703 | .Vb 1 | |
704 | \& SvRV(SV*) | |
705 | .Ve | |
706 | .PP | |
707 | then call the appropriate routines, casting the returned \f(CW\*(C`SV*\*(C'\fR to either an | |
708 | \&\f(CW\*(C`AV*\*(C'\fR or \f(CW\*(C`HV*\*(C'\fR, if required. | |
709 | .PP | |
710 | To determine if an \s-1SV\s0 is a reference, you can use the following macro: | |
711 | .PP | |
712 | .Vb 1 | |
713 | \& SvROK(SV*) | |
714 | .Ve | |
715 | .PP | |
716 | To discover what type of value the reference refers to, use the following | |
717 | macro and then check the return value. | |
718 | .PP | |
719 | .Vb 1 | |
720 | \& SvTYPE(SvRV(SV*)) | |
721 | .Ve | |
722 | .PP | |
723 | The most useful types that will be returned are: | |
724 | .PP | |
725 | .Vb 9 | |
726 | \& SVt_IV Scalar | |
727 | \& SVt_NV Scalar | |
728 | \& SVt_PV Scalar | |
729 | \& SVt_RV Scalar | |
730 | \& SVt_PVAV Array | |
731 | \& SVt_PVHV Hash | |
732 | \& SVt_PVCV Code | |
733 | \& SVt_PVGV Glob (possible a file handle) | |
734 | \& SVt_PVMG Blessed or Magical Scalar | |
735 | .Ve | |
736 | .PP | |
737 | .Vb 1 | |
738 | \& See the sv.h header file for more details. | |
739 | .Ve | |
740 | .Sh "Blessed References and Class Objects" | |
741 | .IX Subsection "Blessed References and Class Objects" | |
742 | References are also used to support object-oriented programming. In the | |
743 | \&\s-1OO\s0 lexicon, an object is simply a reference that has been blessed into a | |
744 | package (or class). Once blessed, the programmer may now use the reference | |
745 | to access the various methods in the class. | |
746 | .PP | |
747 | A reference can be blessed into a package with the following function: | |
748 | .PP | |
749 | .Vb 1 | |
750 | \& SV* sv_bless(SV* sv, HV* stash); | |
751 | .Ve | |
752 | .PP | |
753 | The \f(CW\*(C`sv\*(C'\fR argument must be a reference. The \f(CW\*(C`stash\*(C'\fR argument specifies | |
754 | which class the reference will belong to. See | |
755 | \&\*(L"Stashes and Globs\*(R" for information on converting class names into stashes. | |
756 | .PP | |
757 | /* Still under construction */ | |
758 | .PP | |
759 | Upgrades rv to reference if not already one. Creates new \s-1SV\s0 for rv to | |
760 | point to. If \f(CW\*(C`classname\*(C'\fR is non\-null, the \s-1SV\s0 is blessed into the specified | |
761 | class. \s-1SV\s0 is returned. | |
762 | .PP | |
763 | .Vb 1 | |
764 | \& SV* newSVrv(SV* rv, const char* classname); | |
765 | .Ve | |
766 | .PP | |
767 | Copies integer, unsigned integer or double into an \s-1SV\s0 whose reference is \f(CW\*(C`rv\*(C'\fR. \s-1SV\s0 is blessed | |
768 | if \f(CW\*(C`classname\*(C'\fR is non\-null. | |
769 | .PP | |
770 | .Vb 3 | |
771 | \& SV* sv_setref_iv(SV* rv, const char* classname, IV iv); | |
772 | \& SV* sv_setref_uv(SV* rv, const char* classname, UV uv); | |
773 | \& SV* sv_setref_nv(SV* rv, const char* classname, NV iv); | |
774 | .Ve | |
775 | .PP | |
776 | Copies the pointer value (\fIthe address, not the string!\fR) into an \s-1SV\s0 whose | |
777 | reference is rv. \s-1SV\s0 is blessed if \f(CW\*(C`classname\*(C'\fR is non\-null. | |
778 | .PP | |
779 | .Vb 1 | |
780 | \& SV* sv_setref_pv(SV* rv, const char* classname, PV iv); | |
781 | .Ve | |
782 | .PP | |
783 | Copies string into an \s-1SV\s0 whose reference is \f(CW\*(C`rv\*(C'\fR. Set length to 0 to let | |
784 | Perl calculate the string length. \s-1SV\s0 is blessed if \f(CW\*(C`classname\*(C'\fR is non\-null. | |
785 | .PP | |
786 | .Vb 1 | |
787 | \& SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length); | |
788 | .Ve | |
789 | .PP | |
790 | Tests whether the \s-1SV\s0 is blessed into the specified class. It does not | |
791 | check inheritance relationships. | |
792 | .PP | |
793 | .Vb 1 | |
794 | \& int sv_isa(SV* sv, const char* name); | |
795 | .Ve | |
796 | .PP | |
797 | Tests whether the \s-1SV\s0 is a reference to a blessed object. | |
798 | .PP | |
799 | .Vb 1 | |
800 | \& int sv_isobject(SV* sv); | |
801 | .Ve | |
802 | .PP | |
803 | Tests whether the \s-1SV\s0 is derived from the specified class. \s-1SV\s0 can be either | |
804 | a reference to a blessed object or a string containing a class name. This | |
805 | is the function implementing the \f(CW\*(C`UNIVERSAL::isa\*(C'\fR functionality. | |
806 | .PP | |
807 | .Vb 1 | |
808 | \& bool sv_derived_from(SV* sv, const char* name); | |
809 | .Ve | |
810 | .PP | |
811 | To check if you've got an object derived from a specific class you have | |
812 | to write: | |
813 | .PP | |
814 | .Vb 1 | |
815 | \& if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... } | |
816 | .Ve | |
817 | .Sh "Creating New Variables" | |
818 | .IX Subsection "Creating New Variables" | |
819 | To create a new Perl variable with an undef value which can be accessed from | |
820 | your Perl script, use the following routines, depending on the variable type. | |
821 | .PP | |
822 | .Vb 3 | |
823 | \& SV* get_sv("package::varname", TRUE); | |
824 | \& AV* get_av("package::varname", TRUE); | |
825 | \& HV* get_hv("package::varname", TRUE); | |
826 | .Ve | |
827 | .PP | |
828 | Notice the use of \s-1TRUE\s0 as the second parameter. The new variable can now | |
829 | be set, using the routines appropriate to the data type. | |
830 | .PP | |
831 | There are additional macros whose values may be bitwise \s-1OR\s0'ed with the | |
832 | \&\f(CW\*(C`TRUE\*(C'\fR argument to enable certain extra features. Those bits are: | |
833 | .IP "\s-1GV_ADDMULTI\s0" 4 | |
834 | .IX Item "GV_ADDMULTI" | |
835 | Marks the variable as multiply defined, thus preventing the: | |
836 | .Sp | |
837 | .Vb 1 | |
838 | \& Name <varname> used only once: possible typo | |
839 | .Ve | |
840 | .Sp | |
841 | warning. | |
842 | .IP "\s-1GV_ADDWARN\s0" 4 | |
843 | .IX Item "GV_ADDWARN" | |
844 | Issues the warning: | |
845 | .Sp | |
846 | .Vb 1 | |
847 | \& Had to create <varname> unexpectedly | |
848 | .Ve | |
849 | .Sp | |
850 | if the variable did not exist before the function was called. | |
851 | .PP | |
852 | If you do not specify a package name, the variable is created in the current | |
853 | package. | |
854 | .Sh "Reference Counts and Mortality" | |
855 | .IX Subsection "Reference Counts and Mortality" | |
856 | Perl uses a reference count-driven garbage collection mechanism. SVs, | |
857 | AVs, or HVs (xV for short in the following) start their life with a | |
858 | reference count of 1. If the reference count of an xV ever drops to 0, | |
859 | then it will be destroyed and its memory made available for reuse. | |
860 | .PP | |
861 | This normally doesn't happen at the Perl level unless a variable is | |
862 | undef'ed or the last variable holding a reference to it is changed or | |
863 | overwritten. At the internal level, however, reference counts can be | |
864 | manipulated with the following macros: | |
865 | .PP | |
866 | .Vb 3 | |
867 | \& int SvREFCNT(SV* sv); | |
868 | \& SV* SvREFCNT_inc(SV* sv); | |
869 | \& void SvREFCNT_dec(SV* sv); | |
870 | .Ve | |
871 | .PP | |
872 | However, there is one other function which manipulates the reference | |
873 | count of its argument. The \f(CW\*(C`newRV_inc\*(C'\fR function, you will recall, | |
874 | creates a reference to the specified argument. As a side effect, | |
875 | it increments the argument's reference count. If this is not what | |
876 | you want, use \f(CW\*(C`newRV_noinc\*(C'\fR instead. | |
877 | .PP | |
878 | For example, imagine you want to return a reference from an \s-1XSUB\s0 function. | |
879 | Inside the \s-1XSUB\s0 routine, you create an \s-1SV\s0 which initially has a reference | |
880 | count of one. Then you call \f(CW\*(C`newRV_inc\*(C'\fR, passing it the just-created \s-1SV\s0. | |
881 | This returns the reference as a new \s-1SV\s0, but the reference count of the | |
882 | \&\s-1SV\s0 you passed to \f(CW\*(C`newRV_inc\*(C'\fR has been incremented to two. Now you | |
883 | return the reference from the \s-1XSUB\s0 routine and forget about the \s-1SV\s0. | |
884 | But Perl hasn't! Whenever the returned reference is destroyed, the | |
885 | reference count of the original \s-1SV\s0 is decreased to one and nothing happens. | |
886 | The \s-1SV\s0 will hang around without any way to access it until Perl itself | |
887 | terminates. This is a memory leak. | |
888 | .PP | |
889 | The correct procedure, then, is to use \f(CW\*(C`newRV_noinc\*(C'\fR instead of | |
890 | \&\f(CW\*(C`newRV_inc\*(C'\fR. Then, if and when the last reference is destroyed, | |
891 | the reference count of the \s-1SV\s0 will go to zero and it will be destroyed, | |
892 | stopping any memory leak. | |
893 | .PP | |
894 | There are some convenience functions available that can help with the | |
895 | destruction of xVs. These functions introduce the concept of \*(L"mortality\*(R". | |
896 | An xV that is mortal has had its reference count marked to be decremented, | |
897 | but not actually decremented, until \*(L"a short time later\*(R". Generally the | |
898 | term \*(L"short time later\*(R" means a single Perl statement, such as a call to | |
899 | an \s-1XSUB\s0 function. The actual determinant for when mortal xVs have their | |
900 | reference count decremented depends on two macros, \s-1SAVETMPS\s0 and \s-1FREETMPS\s0. | |
901 | See perlcall and perlxs for more details on these macros. | |
902 | .PP | |
903 | \&\*(L"Mortalization\*(R" then is at its simplest a deferred \f(CW\*(C`SvREFCNT_dec\*(C'\fR. | |
904 | However, if you mortalize a variable twice, the reference count will | |
905 | later be decremented twice. | |
906 | .PP | |
907 | \&\*(L"Mortal\*(R" SVs are mainly used for SVs that are placed on perl's stack. | |
908 | For example an \s-1SV\s0 which is created just to pass a number to a called sub | |
909 | is made mortal to have it cleaned up automatically when stack is popped. | |
910 | Similarly results returned by XSUBs (which go in the stack) are often | |
911 | made mortal. | |
912 | .PP | |
913 | To create a mortal variable, use the functions: | |
914 | .PP | |
915 | .Vb 3 | |
916 | \& SV* sv_newmortal() | |
917 | \& SV* sv_2mortal(SV*) | |
918 | \& SV* sv_mortalcopy(SV*) | |
919 | .Ve | |
920 | .PP | |
921 | The first call creates a mortal \s-1SV\s0 (with no value), the second converts an existing | |
922 | \&\s-1SV\s0 to a mortal \s-1SV\s0 (and thus defers a call to \f(CW\*(C`SvREFCNT_dec\*(C'\fR), and the | |
923 | third creates a mortal copy of an existing \s-1SV\s0. | |
924 | Because \f(CW\*(C`sv_newmortal\*(C'\fR gives the new \s-1SV\s0 no value,it must normally be given one | |
925 | via \f(CW\*(C`sv_setpv\*(C'\fR, \f(CW\*(C`sv_setiv\*(C'\fR, etc. : | |
926 | .PP | |
927 | .Vb 2 | |
928 | \& SV *tmp = sv_newmortal(); | |
929 | \& sv_setiv(tmp, an_integer); | |
930 | .Ve | |
931 | .PP | |
932 | As that is multiple C statements it is quite common so see this idiom instead: | |
933 | .PP | |
934 | .Vb 1 | |
935 | \& SV *tmp = sv_2mortal(newSViv(an_integer)); | |
936 | .Ve | |
937 | .PP | |
938 | You should be careful about creating mortal variables. Strange things | |
939 | can happen if you make the same value mortal within multiple contexts, | |
940 | or if you make a variable mortal multiple times. Thinking of \*(L"Mortalization\*(R" | |
941 | as deferred \f(CW\*(C`SvREFCNT_dec\*(C'\fR should help to minimize such problems. | |
942 | For example if you are passing an \s-1SV\s0 which you \fIknow\fR has high enough \s-1REFCNT\s0 | |
943 | to survive its use on the stack you need not do any mortalization. | |
944 | If you are not sure then doing an \f(CW\*(C`SvREFCNT_inc\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR, or | |
945 | making a \f(CW\*(C`sv_mortalcopy\*(C'\fR is safer. | |
946 | .PP | |
947 | The mortal routines are not just for SVs \*(-- AVs and HVs can be | |
948 | made mortal by passing their address (type\-casted to \f(CW\*(C`SV*\*(C'\fR) to the | |
949 | \&\f(CW\*(C`sv_2mortal\*(C'\fR or \f(CW\*(C`sv_mortalcopy\*(C'\fR routines. | |
950 | .Sh "Stashes and Globs" | |
951 | .IX Subsection "Stashes and Globs" | |
952 | A \*(L"stash\*(R" is a hash that contains all of the different objects that | |
953 | are contained within a package. Each key of the stash is a symbol | |
954 | name (shared by all the different types of objects that have the same | |
955 | name), and each value in the hash table is a \s-1GV\s0 (Glob Value). This \s-1GV\s0 | |
956 | in turn contains references to the various objects of that name, | |
957 | including (but not limited to) the following: | |
958 | .PP | |
959 | .Vb 6 | |
960 | \& Scalar Value | |
961 | \& Array Value | |
962 | \& Hash Value | |
963 | \& I/O Handle | |
964 | \& Format | |
965 | \& Subroutine | |
966 | .Ve | |
967 | .PP | |
968 | There is a single stash called \*(L"PL_defstash\*(R" that holds the items that exist | |
969 | in the \*(L"main\*(R" package. To get at the items in other packages, append the | |
970 | string \*(L"::\*(R" to the package name. The items in the \*(L"Foo\*(R" package are in | |
971 | the stash \*(L"Foo::\*(R" in PL_defstash. The items in the \*(L"Bar::Baz\*(R" package are | |
972 | in the stash \*(L"Baz::\*(R" in \*(L"Bar::\*(R"'s stash. | |
973 | .PP | |
974 | To get the stash pointer for a particular package, use the function: | |
975 | .PP | |
976 | .Vb 2 | |
977 | \& HV* gv_stashpv(const char* name, I32 create) | |
978 | \& HV* gv_stashsv(SV*, I32 create) | |
979 | .Ve | |
980 | .PP | |
981 | The first function takes a literal string, the second uses the string stored | |
982 | in the \s-1SV\s0. Remember that a stash is just a hash table, so you get back an | |
983 | \&\f(CW\*(C`HV*\*(C'\fR. The \f(CW\*(C`create\*(C'\fR flag will create a new package if it is set. | |
984 | .PP | |
985 | The name that \f(CW\*(C`gv_stash*v\*(C'\fR wants is the name of the package whose symbol table | |
986 | you want. The default package is called \f(CW\*(C`main\*(C'\fR. If you have multiply nested | |
987 | packages, pass their names to \f(CW\*(C`gv_stash*v\*(C'\fR, separated by \f(CW\*(C`::\*(C'\fR as in the Perl | |
988 | language itself. | |
989 | .PP | |
990 | Alternately, if you have an \s-1SV\s0 that is a blessed reference, you can find | |
991 | out the stash pointer by using: | |
992 | .PP | |
993 | .Vb 1 | |
994 | \& HV* SvSTASH(SvRV(SV*)); | |
995 | .Ve | |
996 | .PP | |
997 | then use the following to get the package name itself: | |
998 | .PP | |
999 | .Vb 1 | |
1000 | \& char* HvNAME(HV* stash); | |
1001 | .Ve | |
1002 | .PP | |
1003 | If you need to bless or re-bless an object you can use the following | |
1004 | function: | |
1005 | .PP | |
1006 | .Vb 1 | |
1007 | \& SV* sv_bless(SV*, HV* stash) | |
1008 | .Ve | |
1009 | .PP | |
1010 | where the first argument, an \f(CW\*(C`SV*\*(C'\fR, must be a reference, and the second | |
1011 | argument is a stash. The returned \f(CW\*(C`SV*\*(C'\fR can now be used in the same way | |
1012 | as any other \s-1SV\s0. | |
1013 | .PP | |
1014 | For more information on references and blessings, consult perlref. | |
1015 | .Sh "Double-Typed SVs" | |
1016 | .IX Subsection "Double-Typed SVs" | |
1017 | Scalar variables normally contain only one type of value, an integer, | |
1018 | double, pointer, or reference. Perl will automatically convert the | |
1019 | actual scalar data from the stored type into the requested type. | |
1020 | .PP | |
1021 | Some scalar variables contain more than one type of scalar data. For | |
1022 | example, the variable \f(CW$!\fR contains either the numeric value of \f(CW\*(C`errno\*(C'\fR | |
1023 | or its string equivalent from either \f(CW\*(C`strerror\*(C'\fR or \f(CW\*(C`sys_errlist[]\*(C'\fR. | |
1024 | .PP | |
1025 | To force multiple data values into an \s-1SV\s0, you must do two things: use the | |
1026 | \&\f(CW\*(C`sv_set*v\*(C'\fR routines to add the additional scalar type, then set a flag | |
1027 | so that Perl will believe it contains more than one type of data. The | |
1028 | four macros to set the flags are: | |
1029 | .PP | |
1030 | .Vb 4 | |
1031 | \& SvIOK_on | |
1032 | \& SvNOK_on | |
1033 | \& SvPOK_on | |
1034 | \& SvROK_on | |
1035 | .Ve | |
1036 | .PP | |
1037 | The particular macro you must use depends on which \f(CW\*(C`sv_set*v\*(C'\fR routine | |
1038 | you called first. This is because every \f(CW\*(C`sv_set*v\*(C'\fR routine turns on | |
1039 | only the bit for the particular type of data being set, and turns off | |
1040 | all the rest. | |
1041 | .PP | |
1042 | For example, to create a new Perl variable called \*(L"dberror\*(R" that contains | |
1043 | both the numeric and descriptive string error values, you could use the | |
1044 | following code: | |
1045 | .PP | |
1046 | .Vb 2 | |
1047 | \& extern int dberror; | |
1048 | \& extern char *dberror_list; | |
1049 | .Ve | |
1050 | .PP | |
1051 | .Vb 4 | |
1052 | \& SV* sv = get_sv("dberror", TRUE); | |
1053 | \& sv_setiv(sv, (IV) dberror); | |
1054 | \& sv_setpv(sv, dberror_list[dberror]); | |
1055 | \& SvIOK_on(sv); | |
1056 | .Ve | |
1057 | .PP | |
1058 | If the order of \f(CW\*(C`sv_setiv\*(C'\fR and \f(CW\*(C`sv_setpv\*(C'\fR had been reversed, then the | |
1059 | macro \f(CW\*(C`SvPOK_on\*(C'\fR would need to be called instead of \f(CW\*(C`SvIOK_on\*(C'\fR. | |
1060 | .Sh "Magic Variables" | |
1061 | .IX Subsection "Magic Variables" | |
1062 | [This section still under construction. Ignore everything here. Post no | |
1063 | bills. Everything not permitted is forbidden.] | |
1064 | .PP | |
1065 | Any \s-1SV\s0 may be magical, that is, it has special features that a normal | |
1066 | \&\s-1SV\s0 does not have. These features are stored in the \s-1SV\s0 structure in a | |
1067 | linked list of \f(CW\*(C`struct magic\*(C'\fR's, typedef'ed to \f(CW\*(C`MAGIC\*(C'\fR. | |
1068 | .PP | |
1069 | .Vb 10 | |
1070 | \& struct magic { | |
1071 | \& MAGIC* mg_moremagic; | |
1072 | \& MGVTBL* mg_virtual; | |
1073 | \& U16 mg_private; | |
1074 | \& char mg_type; | |
1075 | \& U8 mg_flags; | |
1076 | \& SV* mg_obj; | |
1077 | \& char* mg_ptr; | |
1078 | \& I32 mg_len; | |
1079 | \& }; | |
1080 | .Ve | |
1081 | .PP | |
1082 | Note this is current as of patchlevel 0, and could change at any time. | |
1083 | .Sh "Assigning Magic" | |
1084 | .IX Subsection "Assigning Magic" | |
1085 | Perl adds magic to an \s-1SV\s0 using the sv_magic function: | |
1086 | .PP | |
1087 | .Vb 1 | |
1088 | \& void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen); | |
1089 | .Ve | |
1090 | .PP | |
1091 | The \f(CW\*(C`sv\*(C'\fR argument is a pointer to the \s-1SV\s0 that is to acquire a new magical | |
1092 | feature. | |
1093 | .PP | |
1094 | If \f(CW\*(C`sv\*(C'\fR is not already magical, Perl uses the \f(CW\*(C`SvUPGRADE\*(C'\fR macro to | |
1095 | convert \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR. Perl then continues by adding new magic | |
1096 | to the beginning of the linked list of magical features. Any prior entry | |
1097 | of the same type of magic is deleted. Note that this can be overridden, | |
1098 | and multiple instances of the same type of magic can be associated with an | |
1099 | \&\s-1SV\s0. | |
1100 | .PP | |
1101 | The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments are used to associate a string with | |
1102 | the magic, typically the name of a variable. \f(CW\*(C`namlen\*(C'\fR is stored in the | |
1103 | \&\f(CW\*(C`mg_len\*(C'\fR field and if \f(CW\*(C`name\*(C'\fR is non-null and \f(CW\*(C`namlen\*(C'\fR >= 0 a malloc'd | |
1104 | copy of the name is stored in \f(CW\*(C`mg_ptr\*(C'\fR field. | |
1105 | .PP | |
1106 | The sv_magic function uses \f(CW\*(C`how\*(C'\fR to determine which, if any, predefined | |
1107 | \&\*(L"Magic Virtual Table\*(R" should be assigned to the \f(CW\*(C`mg_virtual\*(C'\fR field. | |
1108 | See the \*(L"Magic Virtual Table\*(R" section below. The \f(CW\*(C`how\*(C'\fR argument is also | |
1109 | stored in the \f(CW\*(C`mg_type\*(C'\fR field. The value of \f(CW\*(C`how\*(C'\fR should be chosen | |
1110 | from the set of macros \f(CW\*(C`PERL_MAGIC_foo\*(C'\fR found perl.h. Note that before | |
1111 | these macros were added, Perl internals used to directly use character | |
1112 | literals, so you may occasionally come across old code or documentation | |
1113 | referring to 'U' magic rather than \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR for example. | |
1114 | .PP | |
1115 | The \f(CW\*(C`obj\*(C'\fR argument is stored in the \f(CW\*(C`mg_obj\*(C'\fR field of the \f(CW\*(C`MAGIC\*(C'\fR | |
1116 | structure. If it is not the same as the \f(CW\*(C`sv\*(C'\fR argument, the reference | |
1117 | count of the \f(CW\*(C`obj\*(C'\fR object is incremented. If it is the same, or if | |
1118 | the \f(CW\*(C`how\*(C'\fR argument is \f(CW\*(C`PERL_MAGIC_arylen\*(C'\fR, or if it is a \s-1NULL\s0 pointer, | |
1119 | then \f(CW\*(C`obj\*(C'\fR is merely stored, without the reference count being incremented. | |
1120 | .PP | |
1121 | There is also a function to add magic to an \f(CW\*(C`HV\*(C'\fR: | |
1122 | .PP | |
1123 | .Vb 1 | |
1124 | \& void hv_magic(HV *hv, GV *gv, int how); | |
1125 | .Ve | |
1126 | .PP | |
1127 | This simply calls \f(CW\*(C`sv_magic\*(C'\fR and coerces the \f(CW\*(C`gv\*(C'\fR argument into an \f(CW\*(C`SV\*(C'\fR. | |
1128 | .PP | |
1129 | To remove the magic from an \s-1SV\s0, call the function sv_unmagic: | |
1130 | .PP | |
1131 | .Vb 1 | |
1132 | \& void sv_unmagic(SV *sv, int type); | |
1133 | .Ve | |
1134 | .PP | |
1135 | The \f(CW\*(C`type\*(C'\fR argument should be equal to the \f(CW\*(C`how\*(C'\fR value when the \f(CW\*(C`SV\*(C'\fR | |
1136 | was initially made magical. | |
1137 | .Sh "Magic Virtual Tables" | |
1138 | .IX Subsection "Magic Virtual Tables" | |
1139 | The \f(CW\*(C`mg_virtual\*(C'\fR field in the \f(CW\*(C`MAGIC\*(C'\fR structure is a pointer to an | |
1140 | \&\f(CW\*(C`MGVTBL\*(C'\fR, which is a structure of function pointers and stands for | |
1141 | \&\*(L"Magic Virtual Table\*(R" to handle the various operations that might be | |
1142 | applied to that variable. | |
1143 | .PP | |
1144 | The \f(CW\*(C`MGVTBL\*(C'\fR has five pointers to the following routine types: | |
1145 | .PP | |
1146 | .Vb 5 | |
1147 | \& int (*svt_get)(SV* sv, MAGIC* mg); | |
1148 | \& int (*svt_set)(SV* sv, MAGIC* mg); | |
1149 | \& U32 (*svt_len)(SV* sv, MAGIC* mg); | |
1150 | \& int (*svt_clear)(SV* sv, MAGIC* mg); | |
1151 | \& int (*svt_free)(SV* sv, MAGIC* mg); | |
1152 | .Ve | |
1153 | .PP | |
1154 | This \s-1MGVTBL\s0 structure is set at compile-time in \f(CW\*(C`perl.h\*(C'\fR and there are | |
1155 | currently 19 types (or 21 with overloading turned on). These different | |
1156 | structures contain pointers to various routines that perform additional | |
1157 | actions depending on which function is being called. | |
1158 | .PP | |
1159 | .Vb 7 | |
1160 | \& Function pointer Action taken | |
1161 | \& ---------------- ------------ | |
1162 | \& svt_get Do something before the value of the SV is retrieved. | |
1163 | \& svt_set Do something after the SV is assigned a value. | |
1164 | \& svt_len Report on the SV's length. | |
1165 | \& svt_clear Clear something the SV represents. | |
1166 | \& svt_free Free any extra storage associated with the SV. | |
1167 | .Ve | |
1168 | .PP | |
1169 | For instance, the \s-1MGVTBL\s0 structure called \f(CW\*(C`vtbl_sv\*(C'\fR (which corresponds | |
1170 | to an \f(CW\*(C`mg_type\*(C'\fR of \f(CW\*(C`PERL_MAGIC_sv\*(C'\fR) contains: | |
1171 | .PP | |
1172 | .Vb 1 | |
1173 | \& { magic_get, magic_set, magic_len, 0, 0 } | |
1174 | .Ve | |
1175 | .PP | |
1176 | Thus, when an \s-1SV\s0 is determined to be magical and of type \f(CW\*(C`PERL_MAGIC_sv\*(C'\fR, | |
1177 | if a get operation is being performed, the routine \f(CW\*(C`magic_get\*(C'\fR is | |
1178 | called. All the various routines for the various magical types begin | |
1179 | with \f(CW\*(C`magic_\*(C'\fR. \s-1NOTE:\s0 the magic routines are not considered part of | |
1180 | the Perl \s-1API\s0, and may not be exported by the Perl library. | |
1181 | .PP | |
1182 | The current kinds of Magic Virtual Tables are: | |
1183 | .PP | |
1184 | .Vb 42 | |
1185 | \& mg_type | |
1186 | \& (old-style char and macro) MGVTBL Type of magic | |
1187 | \& -------------------------- ------ ---------------------------- | |
1188 | \& \e0 PERL_MAGIC_sv vtbl_sv Special scalar variable | |
1189 | \& A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash | |
1190 | \& a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element | |
1191 | \& c PERL_MAGIC_overload_table (none) Holds overload table (AMT) | |
1192 | \& on stash | |
1193 | \& B PERL_MAGIC_bm vtbl_bm Boyer-Moore (fast string search) | |
1194 | \& D PERL_MAGIC_regdata vtbl_regdata Regex match position data | |
1195 | \& (@+ and @- vars) | |
1196 | \& d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data | |
1197 | \& element | |
1198 | \& E PERL_MAGIC_env vtbl_env %ENV hash | |
1199 | \& e PERL_MAGIC_envelem vtbl_envelem %ENV hash element | |
1200 | \& f PERL_MAGIC_fm vtbl_fm Formline ('compiled' format) | |
1201 | \& g PERL_MAGIC_regex_global vtbl_mglob m//g target / study()ed string | |
1202 | \& I PERL_MAGIC_isa vtbl_isa @ISA array | |
1203 | \& i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element | |
1204 | \& k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue | |
1205 | \& L PERL_MAGIC_dbfile (none) Debugger %_<filename | |
1206 | \& l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename element | |
1207 | \& m PERL_MAGIC_mutex vtbl_mutex ??? | |
1208 | \& o PERL_MAGIC_collxfrm vtbl_collxfrm Locale collate transformation | |
1209 | \& P PERL_MAGIC_tied vtbl_pack Tied array or hash | |
1210 | \& p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element | |
1211 | \& q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle | |
1212 | \& r PERL_MAGIC_qr vtbl_qr precompiled qr// regex | |
1213 | \& S PERL_MAGIC_sig vtbl_sig %SIG hash | |
1214 | \& s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element | |
1215 | \& t PERL_MAGIC_taint vtbl_taint Taintedness | |
1216 | \& U PERL_MAGIC_uvar vtbl_uvar Available for use by extensions | |
1217 | \& v PERL_MAGIC_vec vtbl_vec vec() lvalue | |
1218 | \& x PERL_MAGIC_substr vtbl_substr substr() lvalue | |
1219 | \& y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator | |
1220 | \& variable / smart parameter | |
1221 | \& vivification | |
1222 | \& * PERL_MAGIC_glob vtbl_glob GV (typeglob) | |
1223 | \& # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary) | |
1224 | \& . PERL_MAGIC_pos vtbl_pos pos() lvalue | |
1225 | \& < PERL_MAGIC_backref vtbl_backref ??? | |
1226 | \& ~ PERL_MAGIC_ext (none) Available for use by extensions | |
1227 | .Ve | |
1228 | .PP | |
1229 | When an uppercase and lowercase letter both exist in the table, then the | |
1230 | uppercase letter is used to represent some kind of composite type (a list | |
1231 | or a hash), and the lowercase letter is used to represent an element of | |
1232 | that composite type. Some internals code makes use of this case | |
1233 | relationship. | |
1234 | .PP | |
1235 | The \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR and \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic types are defined | |
1236 | specifically for use by extensions and will not be used by perl itself. | |
1237 | Extensions can use \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR magic to 'attach' private information | |
1238 | to variables (typically objects). This is especially useful because | |
1239 | there is no way for normal perl code to corrupt this private information | |
1240 | (unlike using extra elements of a hash object). | |
1241 | .PP | |
1242 | Similarly, \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic can be used much like \fItie()\fR to call a | |
1243 | C function any time a scalar's value is used or changed. The \f(CW\*(C`MAGIC\*(C'\fR's | |
1244 | \&\f(CW\*(C`mg_ptr\*(C'\fR field points to a \f(CW\*(C`ufuncs\*(C'\fR structure: | |
1245 | .PP | |
1246 | .Vb 5 | |
1247 | \& struct ufuncs { | |
1248 | \& I32 (*uf_val)(pTHX_ IV, SV*); | |
1249 | \& I32 (*uf_set)(pTHX_ IV, SV*); | |
1250 | \& IV uf_index; | |
1251 | \& }; | |
1252 | .Ve | |
1253 | .PP | |
1254 | When the \s-1SV\s0 is read from or written to, the \f(CW\*(C`uf_val\*(C'\fR or \f(CW\*(C`uf_set\*(C'\fR | |
1255 | function will be called with \f(CW\*(C`uf_index\*(C'\fR as the first arg and a pointer to | |
1256 | the \s-1SV\s0 as the second. A simple example of how to add \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR | |
1257 | magic is shown below. Note that the ufuncs structure is copied by | |
1258 | sv_magic, so you can safely allocate it on the stack. | |
1259 | .PP | |
1260 | .Vb 10 | |
1261 | \& void | |
1262 | \& Umagic(sv) | |
1263 | \& SV *sv; | |
1264 | \& PREINIT: | |
1265 | \& struct ufuncs uf; | |
1266 | \& CODE: | |
1267 | \& uf.uf_val = &my_get_fn; | |
1268 | \& uf.uf_set = &my_set_fn; | |
1269 | \& uf.uf_index = 0; | |
1270 | \& sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf)); | |
1271 | .Ve | |
1272 | .PP | |
1273 | Note that because multiple extensions may be using \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR | |
1274 | or \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR magic, it is important for extensions to take | |
1275 | extra care to avoid conflict. Typically only using the magic on | |
1276 | objects blessed into the same class as the extension is sufficient. | |
1277 | For \f(CW\*(C`PERL_MAGIC_ext\*(C'\fR magic, it may also be appropriate to add an I32 | |
1278 | \&'signature' at the top of the private data area and check that. | |
1279 | .PP | |
1280 | Also note that the \f(CW\*(C`sv_set*()\*(C'\fR and \f(CW\*(C`sv_cat*()\*(C'\fR functions described | |
1281 | earlier do \fBnot\fR invoke 'set' magic on their targets. This must | |
1282 | be done by the user either by calling the \f(CW\*(C`SvSETMAGIC()\*(C'\fR macro after | |
1283 | calling these functions, or by using one of the \f(CW\*(C`sv_set*_mg()\*(C'\fR or | |
1284 | \&\f(CW\*(C`sv_cat*_mg()\*(C'\fR functions. Similarly, generic C code must call the | |
1285 | \&\f(CW\*(C`SvGETMAGIC()\*(C'\fR macro to invoke any 'get' magic if they use an \s-1SV\s0 | |
1286 | obtained from external sources in functions that don't handle magic. | |
1287 | See perlapi for a description of these functions. | |
1288 | For example, calls to the \f(CW\*(C`sv_cat*()\*(C'\fR functions typically need to be | |
1289 | followed by \f(CW\*(C`SvSETMAGIC()\*(C'\fR, but they don't need a prior \f(CW\*(C`SvGETMAGIC()\*(C'\fR | |
1290 | since their implementation handles 'get' magic. | |
1291 | .Sh "Finding Magic" | |
1292 | .IX Subsection "Finding Magic" | |
1293 | .Vb 1 | |
1294 | \& MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */ | |
1295 | .Ve | |
1296 | .PP | |
1297 | This routine returns a pointer to the \f(CW\*(C`MAGIC\*(C'\fR structure stored in the \s-1SV\s0. | |
1298 | If the \s-1SV\s0 does not have that magical feature, \f(CW\*(C`NULL\*(C'\fR is returned. Also, | |
1299 | if the \s-1SV\s0 is not of type SVt_PVMG, Perl may core dump. | |
1300 | .PP | |
1301 | .Vb 1 | |
1302 | \& int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen); | |
1303 | .Ve | |
1304 | .PP | |
1305 | This routine checks to see what types of magic \f(CW\*(C`sv\*(C'\fR has. If the mg_type | |
1306 | field is an uppercase letter, then the mg_obj is copied to \f(CW\*(C`nsv\*(C'\fR, but | |
1307 | the mg_type field is changed to be the lowercase letter. | |
1308 | .Sh "Understanding the Magic of Tied Hashes and Arrays" | |
1309 | .IX Subsection "Understanding the Magic of Tied Hashes and Arrays" | |
1310 | Tied hashes and arrays are magical beasts of the \f(CW\*(C`PERL_MAGIC_tied\*(C'\fR | |
1311 | magic type. | |
1312 | .PP | |
1313 | \&\s-1WARNING:\s0 As of the 5.004 release, proper usage of the array and hash | |
1314 | access functions requires understanding a few caveats. Some | |
1315 | of these caveats are actually considered bugs in the \s-1API\s0, to be fixed | |
1316 | in later releases, and are bracketed with [\s-1MAYCHANGE\s0] below. If | |
1317 | you find yourself actually applying such information in this section, be | |
1318 | aware that the behavior may change in the future, umm, without warning. | |
1319 | .PP | |
1320 | The perl tie function associates a variable with an object that implements | |
1321 | the various \s-1GET\s0, \s-1SET\s0, etc methods. To perform the equivalent of the perl | |
1322 | tie function from an \s-1XSUB\s0, you must mimic this behaviour. The code below | |
1323 | carries out the necessary steps \- firstly it creates a new hash, and then | |
1324 | creates a second hash which it blesses into the class which will implement | |
1325 | the tie methods. Lastly it ties the two hashes together, and returns a | |
1326 | reference to the new tied hash. Note that the code below does \s-1NOT\s0 call the | |
1327 | \&\s-1TIEHASH\s0 method in the MyTie class \- | |
1328 | see \*(L"Calling Perl Routines from within C Programs\*(R" for details on how | |
1329 | to do this. | |
1330 | .PP | |
1331 | .Vb 15 | |
1332 | \& SV* | |
1333 | \& mytie() | |
1334 | \& PREINIT: | |
1335 | \& HV *hash; | |
1336 | \& HV *stash; | |
1337 | \& SV *tie; | |
1338 | \& CODE: | |
1339 | \& hash = newHV(); | |
1340 | \& tie = newRV_noinc((SV*)newHV()); | |
1341 | \& stash = gv_stashpv("MyTie", TRUE); | |
1342 | \& sv_bless(tie, stash); | |
1343 | \& hv_magic(hash, (GV*)tie, PERL_MAGIC_tied); | |
1344 | \& RETVAL = newRV_noinc(hash); | |
1345 | \& OUTPUT: | |
1346 | \& RETVAL | |
1347 | .Ve | |
1348 | .PP | |
1349 | The \f(CW\*(C`av_store\*(C'\fR function, when given a tied array argument, merely | |
1350 | copies the magic of the array onto the value to be \*(L"stored\*(R", using | |
1351 | \&\f(CW\*(C`mg_copy\*(C'\fR. It may also return \s-1NULL\s0, indicating that the value did not | |
1352 | actually need to be stored in the array. [\s-1MAYCHANGE\s0] After a call to | |
1353 | \&\f(CW\*(C`av_store\*(C'\fR on a tied array, the caller will usually need to call | |
1354 | \&\f(CW\*(C`mg_set(val)\*(C'\fR to actually invoke the perl level \*(L"\s-1STORE\s0\*(R" method on the | |
1355 | \&\s-1TIEARRAY\s0 object. If \f(CW\*(C`av_store\*(C'\fR did return \s-1NULL\s0, a call to | |
1356 | \&\f(CW\*(C`SvREFCNT_dec(val)\*(C'\fR will also be usually necessary to avoid a memory | |
1357 | leak. [/MAYCHANGE] | |
1358 | .PP | |
1359 | The previous paragraph is applicable verbatim to tied hash access using the | |
1360 | \&\f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_store_ent\*(C'\fR functions as well. | |
1361 | .PP | |
1362 | \&\f(CW\*(C`av_fetch\*(C'\fR and the corresponding hash functions \f(CW\*(C`hv_fetch\*(C'\fR and | |
1363 | \&\f(CW\*(C`hv_fetch_ent\*(C'\fR actually return an undefined mortal value whose magic | |
1364 | has been initialized using \f(CW\*(C`mg_copy\*(C'\fR. Note the value so returned does not | |
1365 | need to be deallocated, as it is already mortal. [\s-1MAYCHANGE\s0] But you will | |
1366 | need to call \f(CW\*(C`mg_get()\*(C'\fR on the returned value in order to actually invoke | |
1367 | the perl level \*(L"\s-1FETCH\s0\*(R" method on the underlying \s-1TIE\s0 object. Similarly, | |
1368 | you may also call \f(CW\*(C`mg_set()\*(C'\fR on the return value after possibly assigning | |
1369 | a suitable value to it using \f(CW\*(C`sv_setsv\*(C'\fR, which will invoke the \*(L"\s-1STORE\s0\*(R" | |
1370 | method on the \s-1TIE\s0 object. [/MAYCHANGE] | |
1371 | .PP | |
1372 | [\s-1MAYCHANGE\s0] | |
1373 | In other words, the array or hash fetch/store functions don't really | |
1374 | fetch and store actual values in the case of tied arrays and hashes. They | |
1375 | merely call \f(CW\*(C`mg_copy\*(C'\fR to attach magic to the values that were meant to be | |
1376 | \&\*(L"stored\*(R" or \*(L"fetched\*(R". Later calls to \f(CW\*(C`mg_get\*(C'\fR and \f(CW\*(C`mg_set\*(C'\fR actually | |
1377 | do the job of invoking the \s-1TIE\s0 methods on the underlying objects. Thus | |
1378 | the magic mechanism currently implements a kind of lazy access to arrays | |
1379 | and hashes. | |
1380 | .PP | |
1381 | Currently (as of perl version 5.004), use of the hash and array access | |
1382 | functions requires the user to be aware of whether they are operating on | |
1383 | \&\*(L"normal\*(R" hashes and arrays, or on their tied variants. The \s-1API\s0 may be | |
1384 | changed to provide more transparent access to both tied and normal data | |
1385 | types in future versions. | |
1386 | [/MAYCHANGE] | |
1387 | .PP | |
1388 | You would do well to understand that the \s-1TIEARRAY\s0 and \s-1TIEHASH\s0 interfaces | |
1389 | are mere sugar to invoke some perl method calls while using the uniform hash | |
1390 | and array syntax. The use of this sugar imposes some overhead (typically | |
1391 | about two to four extra opcodes per \s-1FETCH/STORE\s0 operation, in addition to | |
1392 | the creation of all the mortal variables required to invoke the methods). | |
1393 | This overhead will be comparatively small if the \s-1TIE\s0 methods are themselves | |
1394 | substantial, but if they are only a few statements long, the overhead | |
1395 | will not be insignificant. | |
1396 | .Sh "Localizing changes" | |
1397 | .IX Subsection "Localizing changes" | |
1398 | Perl has a very handy construction | |
1399 | .PP | |
1400 | .Vb 4 | |
1401 | \& { | |
1402 | \& local $var = 2; | |
1403 | \& ... | |
1404 | \& } | |
1405 | .Ve | |
1406 | .PP | |
1407 | This construction is \fIapproximately\fR equivalent to | |
1408 | .PP | |
1409 | .Vb 6 | |
1410 | \& { | |
1411 | \& my $oldvar = $var; | |
1412 | \& $var = 2; | |
1413 | \& ... | |
1414 | \& $var = $oldvar; | |
1415 | \& } | |
1416 | .Ve | |
1417 | .PP | |
1418 | The biggest difference is that the first construction would | |
1419 | reinstate the initial value of \f(CW$var\fR, irrespective of how control exits | |
1420 | the block: \f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`die\*(C'\fR/\f(CW\*(C`eval\*(C'\fR, etc. It is a little bit | |
1421 | more efficient as well. | |
1422 | .PP | |
1423 | There is a way to achieve a similar task from C via Perl \s-1API:\s0 create a | |
1424 | \&\fIpseudo-block\fR, and arrange for some changes to be automatically | |
1425 | undone at the end of it, either explicit, or via a non-local exit (via | |
1426 | \&\fIdie()\fR). A \fIblock\fR\-like construct is created by a pair of | |
1427 | \&\f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR macros (see \*(L"Returning a Scalar\*(R" in perlcall). | |
1428 | Such a construct may be created specially for some important localized | |
1429 | task, or an existing one (like boundaries of enclosing Perl | |
1430 | subroutine/block, or an existing pair for freeing TMPs) may be | |
1431 | used. (In the second case the overhead of additional localization must | |
1432 | be almost negligible.) Note that any \s-1XSUB\s0 is automatically enclosed in | |
1433 | an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair. | |
1434 | .PP | |
1435 | Inside such a \fIpseudo-block\fR the following service is available: | |
1436 | .ie n .IP """SAVEINT(int i)""" 4 | |
1437 | .el .IP "\f(CWSAVEINT(int i)\fR" 4 | |
1438 | .IX Item "SAVEINT(int i)" | |
1439 | .PD 0 | |
1440 | .ie n .IP """SAVEIV(IV i)""" 4 | |
1441 | .el .IP "\f(CWSAVEIV(IV i)\fR" 4 | |
1442 | .IX Item "SAVEIV(IV i)" | |
1443 | .ie n .IP """SAVEI32(I32 i)""" 4 | |
1444 | .el .IP "\f(CWSAVEI32(I32 i)\fR" 4 | |
1445 | .IX Item "SAVEI32(I32 i)" | |
1446 | .ie n .IP """SAVELONG(long i)""" 4 | |
1447 | .el .IP "\f(CWSAVELONG(long i)\fR" 4 | |
1448 | .IX Item "SAVELONG(long i)" | |
1449 | .PD | |
1450 | These macros arrange things to restore the value of integer variable | |
1451 | \&\f(CW\*(C`i\*(C'\fR at the end of enclosing \fIpseudo-block\fR. | |
1452 | .ie n .IP "SAVESPTR(s)" 4 | |
1453 | .el .IP "\f(CWSAVESPTR(s)\fR" 4 | |
1454 | .IX Item "SAVESPTR(s)" | |
1455 | .PD 0 | |
1456 | .ie n .IP "SAVEPPTR(p)" 4 | |
1457 | .el .IP "\f(CWSAVEPPTR(p)\fR" 4 | |
1458 | .IX Item "SAVEPPTR(p)" | |
1459 | .PD | |
1460 | These macros arrange things to restore the value of pointers \f(CW\*(C`s\*(C'\fR and | |
1461 | \&\f(CW\*(C`p\*(C'\fR. \f(CW\*(C`s\*(C'\fR must be a pointer of a type which survives conversion to | |
1462 | \&\f(CW\*(C`SV*\*(C'\fR and back, \f(CW\*(C`p\*(C'\fR should be able to survive conversion to \f(CW\*(C`char*\*(C'\fR | |
1463 | and back. | |
1464 | .ie n .IP """SAVEFREESV(SV *sv)""" 4 | |
1465 | .el .IP "\f(CWSAVEFREESV(SV *sv)\fR" 4 | |
1466 | .IX Item "SAVEFREESV(SV *sv)" | |
1467 | The refcount of \f(CW\*(C`sv\*(C'\fR would be decremented at the end of | |
1468 | \&\fIpseudo-block\fR. This is similar to \f(CW\*(C`sv_2mortal\*(C'\fR in that it is also a | |
1469 | mechanism for doing a delayed \f(CW\*(C`SvREFCNT_dec\*(C'\fR. However, while \f(CW\*(C`sv_2mortal\*(C'\fR | |
1470 | extends the lifetime of \f(CW\*(C`sv\*(C'\fR until the beginning of the next statement, | |
1471 | \&\f(CW\*(C`SAVEFREESV\*(C'\fR extends it until the end of the enclosing scope. These | |
1472 | lifetimes can be wildly different. | |
1473 | .Sp | |
1474 | Also compare \f(CW\*(C`SAVEMORTALIZESV\*(C'\fR. | |
1475 | .ie n .IP """SAVEMORTALIZESV(SV *sv)""" 4 | |
1476 | .el .IP "\f(CWSAVEMORTALIZESV(SV *sv)\fR" 4 | |
1477 | .IX Item "SAVEMORTALIZESV(SV *sv)" | |
1478 | Just like \f(CW\*(C`SAVEFREESV\*(C'\fR, but mortalizes \f(CW\*(C`sv\*(C'\fR at the end of the current | |
1479 | scope instead of decrementing its reference count. This usually has the | |
1480 | effect of keeping \f(CW\*(C`sv\*(C'\fR alive until the statement that called the currently | |
1481 | live scope has finished executing. | |
1482 | .ie n .IP """SAVEFREEOP(OP *op)""" 4 | |
1483 | .el .IP "\f(CWSAVEFREEOP(OP *op)\fR" 4 | |
1484 | .IX Item "SAVEFREEOP(OP *op)" | |
1485 | The \f(CW\*(C`OP *\*(C'\fR is \fIop_free()\fRed at the end of \fIpseudo-block\fR. | |
1486 | .ie n .IP "SAVEFREEPV(p)" 4 | |
1487 | .el .IP "\f(CWSAVEFREEPV(p)\fR" 4 | |
1488 | .IX Item "SAVEFREEPV(p)" | |
1489 | The chunk of memory which is pointed to by \f(CW\*(C`p\*(C'\fR is \fISafefree()\fRed at the | |
1490 | end of \fIpseudo-block\fR. | |
1491 | .ie n .IP """SAVECLEARSV(SV *sv)""" 4 | |
1492 | .el .IP "\f(CWSAVECLEARSV(SV *sv)\fR" 4 | |
1493 | .IX Item "SAVECLEARSV(SV *sv)" | |
1494 | Clears a slot in the current scratchpad which corresponds to \f(CW\*(C`sv\*(C'\fR at | |
1495 | the end of \fIpseudo-block\fR. | |
1496 | .ie n .IP """SAVEDELETE(HV *hv, char *key, I32 length)""" 4 | |
1497 | .el .IP "\f(CWSAVEDELETE(HV *hv, char *key, I32 length)\fR" 4 | |
1498 | .IX Item "SAVEDELETE(HV *hv, char *key, I32 length)" | |
1499 | The key \f(CW\*(C`key\*(C'\fR of \f(CW\*(C`hv\*(C'\fR is deleted at the end of \fIpseudo-block\fR. The | |
1500 | string pointed to by \f(CW\*(C`key\*(C'\fR is \fISafefree()\fRed. If one has a \fIkey\fR in | |
1501 | short-lived storage, the corresponding string may be reallocated like | |
1502 | this: | |
1503 | .Sp | |
1504 | .Vb 1 | |
1505 | \& SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf)); | |
1506 | .Ve | |
1507 | .ie n .IP """SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)""" 4 | |
1508 | .el .IP "\f(CWSAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)\fR" 4 | |
1509 | .IX Item "SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)" | |
1510 | At the end of \fIpseudo-block\fR the function \f(CW\*(C`f\*(C'\fR is called with the | |
1511 | only argument \f(CW\*(C`p\*(C'\fR. | |
1512 | .ie n .IP """SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)""" 4 | |
1513 | .el .IP "\f(CWSAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)\fR" 4 | |
1514 | .IX Item "SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)" | |
1515 | At the end of \fIpseudo-block\fR the function \f(CW\*(C`f\*(C'\fR is called with the | |
1516 | implicit context argument (if any), and \f(CW\*(C`p\*(C'\fR. | |
1517 | .ie n .IP """SAVESTACK_POS()""" 4 | |
1518 | .el .IP "\f(CWSAVESTACK_POS()\fR" 4 | |
1519 | .IX Item "SAVESTACK_POS()" | |
1520 | The current offset on the Perl internal stack (cf. \f(CW\*(C`SP\*(C'\fR) is restored | |
1521 | at the end of \fIpseudo-block\fR. | |
1522 | .PP | |
1523 | The following \s-1API\s0 list contains functions, thus one needs to | |
1524 | provide pointers to the modifiable data explicitly (either C pointers, | |
1525 | or Perlish \f(CW\*(C`GV *\*(C'\fRs). Where the above macros take \f(CW\*(C`int\*(C'\fR, a similar | |
1526 | function takes \f(CW\*(C`int *\*(C'\fR. | |
1527 | .ie n .IP """SV* save_scalar(GV *gv)""" 4 | |
1528 | .el .IP "\f(CWSV* save_scalar(GV *gv)\fR" 4 | |
1529 | .IX Item "SV* save_scalar(GV *gv)" | |
1530 | Equivalent to Perl code \f(CW\*(C`local $gv\*(C'\fR. | |
1531 | .ie n .IP """AV* save_ary(GV *gv)""" 4 | |
1532 | .el .IP "\f(CWAV* save_ary(GV *gv)\fR" 4 | |
1533 | .IX Item "AV* save_ary(GV *gv)" | |
1534 | .PD 0 | |
1535 | .ie n .IP """HV* save_hash(GV *gv)""" 4 | |
1536 | .el .IP "\f(CWHV* save_hash(GV *gv)\fR" 4 | |
1537 | .IX Item "HV* save_hash(GV *gv)" | |
1538 | .PD | |
1539 | Similar to \f(CW\*(C`save_scalar\*(C'\fR, but localize \f(CW@gv\fR and \f(CW%gv\fR. | |
1540 | .ie n .IP """void save_item(SV *item)""" 4 | |
1541 | .el .IP "\f(CWvoid save_item(SV *item)\fR" 4 | |
1542 | .IX Item "void save_item(SV *item)" | |
1543 | Duplicates the current value of \f(CW\*(C`SV\*(C'\fR, on the exit from the current | |
1544 | \&\f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR \fIpseudo-block\fR will restore the value of \f(CW\*(C`SV\*(C'\fR | |
1545 | using the stored value. | |
1546 | .ie n .IP """void save_list(SV **sarg, I32 maxsarg)""" 4 | |
1547 | .el .IP "\f(CWvoid save_list(SV **sarg, I32 maxsarg)\fR" 4 | |
1548 | .IX Item "void save_list(SV **sarg, I32 maxsarg)" | |
1549 | A variant of \f(CW\*(C`save_item\*(C'\fR which takes multiple arguments via an array | |
1550 | \&\f(CW\*(C`sarg\*(C'\fR of \f(CW\*(C`SV*\*(C'\fR of length \f(CW\*(C`maxsarg\*(C'\fR. | |
1551 | .ie n .IP """SV* save_svref(SV **sptr)""" 4 | |
1552 | .el .IP "\f(CWSV* save_svref(SV **sptr)\fR" 4 | |
1553 | .IX Item "SV* save_svref(SV **sptr)" | |
1554 | Similar to \f(CW\*(C`save_scalar\*(C'\fR, but will reinstate an \f(CW\*(C`SV *\*(C'\fR. | |
1555 | .ie n .IP """void save_aptr(AV **aptr)""" 4 | |
1556 | .el .IP "\f(CWvoid save_aptr(AV **aptr)\fR" 4 | |
1557 | .IX Item "void save_aptr(AV **aptr)" | |
1558 | .PD 0 | |
1559 | .ie n .IP """void save_hptr(HV **hptr)""" 4 | |
1560 | .el .IP "\f(CWvoid save_hptr(HV **hptr)\fR" 4 | |
1561 | .IX Item "void save_hptr(HV **hptr)" | |
1562 | .PD | |
1563 | Similar to \f(CW\*(C`save_svref\*(C'\fR, but localize \f(CW\*(C`AV *\*(C'\fR and \f(CW\*(C`HV *\*(C'\fR. | |
1564 | .PP | |
1565 | The \f(CW\*(C`Alias\*(C'\fR module implements localization of the basic types within the | |
1566 | \&\fIcaller's scope\fR. People who are interested in how to localize things in | |
1567 | the containing scope should take a look there too. | |
1568 | .SH "Subroutines" | |
1569 | .IX Header "Subroutines" | |
1570 | .Sh "XSUBs and the Argument Stack" | |
1571 | .IX Subsection "XSUBs and the Argument Stack" | |
1572 | The \s-1XSUB\s0 mechanism is a simple way for Perl programs to access C subroutines. | |
1573 | An \s-1XSUB\s0 routine will have a stack that contains the arguments from the Perl | |
1574 | program, and a way to map from the Perl data structures to a C equivalent. | |
1575 | .PP | |
1576 | The stack arguments are accessible through the \f(CWST(n)\fR macro, which returns | |
1577 | the \f(CW\*(C`n\*(C'\fR'th stack argument. Argument 0 is the first argument passed in the | |
1578 | Perl subroutine call. These arguments are \f(CW\*(C`SV*\*(C'\fR, and can be used anywhere | |
1579 | an \f(CW\*(C`SV*\*(C'\fR is used. | |
1580 | .PP | |
1581 | Most of the time, output from the C routine can be handled through use of | |
1582 | the \s-1RETVAL\s0 and \s-1OUTPUT\s0 directives. However, there are some cases where the | |
1583 | argument stack is not already long enough to handle all the return values. | |
1584 | An example is the \s-1POSIX\s0 \fItzname()\fR call, which takes no arguments, but returns | |
1585 | two, the local time zone's standard and summer time abbreviations. | |
1586 | .PP | |
1587 | To handle this situation, the \s-1PPCODE\s0 directive is used and the stack is | |
1588 | extended using the macro: | |
1589 | .PP | |
1590 | .Vb 1 | |
1591 | \& EXTEND(SP, num); | |
1592 | .Ve | |
1593 | .PP | |
1594 | where \f(CW\*(C`SP\*(C'\fR is the macro that represents the local copy of the stack pointer, | |
1595 | and \f(CW\*(C`num\*(C'\fR is the number of elements the stack should be extended by. | |
1596 | .PP | |
1597 | Now that there is room on the stack, values can be pushed on it using \f(CW\*(C`PUSHs\*(C'\fR | |
1598 | macro. The values pushed will often need to be \*(L"mortal\*(R" (See \*(L"Reference Counts and Mortality\*(R"). | |
1599 | .PP | |
1600 | .Vb 3 | |
1601 | \& PUSHs(sv_2mortal(newSViv(an_integer))) | |
1602 | \& PUSHs(sv_2mortal(newSVpv("Some String",0))) | |
1603 | \& PUSHs(sv_2mortal(newSVnv(3.141592))) | |
1604 | .Ve | |
1605 | .PP | |
1606 | And now the Perl program calling \f(CW\*(C`tzname\*(C'\fR, the two values will be assigned | |
1607 | as in: | |
1608 | .PP | |
1609 | .Vb 1 | |
1610 | \& ($standard_abbrev, $summer_abbrev) = POSIX::tzname; | |
1611 | .Ve | |
1612 | .PP | |
1613 | An alternate (and possibly simpler) method to pushing values on the stack is | |
1614 | to use the macro: | |
1615 | .PP | |
1616 | .Vb 1 | |
1617 | \& XPUSHs(SV*) | |
1618 | .Ve | |
1619 | .PP | |
1620 | This macro automatically adjust the stack for you, if needed. Thus, you | |
1621 | do not need to call \f(CW\*(C`EXTEND\*(C'\fR to extend the stack. | |
1622 | .PP | |
1623 | Despite their suggestions in earlier versions of this document the macros | |
1624 | \&\f(CW\*(C`PUSHi\*(C'\fR, \f(CW\*(C`PUSHn\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR are \fInot\fR suited to XSUBs which return | |
1625 | multiple results, see \*(L"Putting a C value on Perl stack\*(R". | |
1626 | .PP | |
1627 | For more information, consult perlxs and perlxstut. | |
1628 | .Sh "Calling Perl Routines from within C Programs" | |
1629 | .IX Subsection "Calling Perl Routines from within C Programs" | |
1630 | There are four routines that can be used to call a Perl subroutine from | |
1631 | within a C program. These four are: | |
1632 | .PP | |
1633 | .Vb 4 | |
1634 | \& I32 call_sv(SV*, I32); | |
1635 | \& I32 call_pv(const char*, I32); | |
1636 | \& I32 call_method(const char*, I32); | |
1637 | \& I32 call_argv(const char*, I32, register char**); | |
1638 | .Ve | |
1639 | .PP | |
1640 | The routine most often used is \f(CW\*(C`call_sv\*(C'\fR. The \f(CW\*(C`SV*\*(C'\fR argument | |
1641 | contains either the name of the Perl subroutine to be called, or a | |
1642 | reference to the subroutine. The second argument consists of flags | |
1643 | that control the context in which the subroutine is called, whether | |
1644 | or not the subroutine is being passed arguments, how errors should be | |
1645 | trapped, and how to treat return values. | |
1646 | .PP | |
1647 | All four routines return the number of arguments that the subroutine returned | |
1648 | on the Perl stack. | |
1649 | .PP | |
1650 | These routines used to be called \f(CW\*(C`perl_call_sv\*(C'\fR, etc., before Perl v5.6.0, | |
1651 | but those names are now deprecated; macros of the same name are provided for | |
1652 | compatibility. | |
1653 | .PP | |
1654 | When using any of these routines (except \f(CW\*(C`call_argv\*(C'\fR), the programmer | |
1655 | must manipulate the Perl stack. These include the following macros and | |
1656 | functions: | |
1657 | .PP | |
1658 | .Vb 11 | |
1659 | \& dSP | |
1660 | \& SP | |
1661 | \& PUSHMARK() | |
1662 | \& PUTBACK | |
1663 | \& SPAGAIN | |
1664 | \& ENTER | |
1665 | \& SAVETMPS | |
1666 | \& FREETMPS | |
1667 | \& LEAVE | |
1668 | \& XPUSH*() | |
1669 | \& POP*() | |
1670 | .Ve | |
1671 | .PP | |
1672 | For a detailed description of calling conventions from C to Perl, | |
1673 | consult perlcall. | |
1674 | .Sh "Memory Allocation" | |
1675 | .IX Subsection "Memory Allocation" | |
1676 | All memory meant to be used with the Perl \s-1API\s0 functions should be manipulated | |
1677 | using the macros described in this section. The macros provide the necessary | |
1678 | transparency between differences in the actual malloc implementation that is | |
1679 | used within perl. | |
1680 | .PP | |
1681 | It is suggested that you enable the version of malloc that is distributed | |
1682 | with Perl. It keeps pools of various sizes of unallocated memory in | |
1683 | order to satisfy allocation requests more quickly. However, on some | |
1684 | platforms, it may cause spurious malloc or free errors. | |
1685 | .PP | |
1686 | .Vb 3 | |
1687 | \& New(x, pointer, number, type); | |
1688 | \& Newc(x, pointer, number, type, cast); | |
1689 | \& Newz(x, pointer, number, type); | |
1690 | .Ve | |
1691 | .PP | |
1692 | These three macros are used to initially allocate memory. | |
1693 | .PP | |
1694 | The first argument \f(CW\*(C`x\*(C'\fR was a \*(L"magic cookie\*(R" that was used to keep track | |
1695 | of who called the macro, to help when debugging memory problems. However, | |
1696 | the current code makes no use of this feature (most Perl developers now | |
1697 | use run-time memory checkers), so this argument can be any number. | |
1698 | .PP | |
1699 | The second argument \f(CW\*(C`pointer\*(C'\fR should be the name of a variable that will | |
1700 | point to the newly allocated memory. | |
1701 | .PP | |
1702 | The third and fourth arguments \f(CW\*(C`number\*(C'\fR and \f(CW\*(C`type\*(C'\fR specify how many of | |
1703 | the specified type of data structure should be allocated. The argument | |
1704 | \&\f(CW\*(C`type\*(C'\fR is passed to \f(CW\*(C`sizeof\*(C'\fR. The final argument to \f(CW\*(C`Newc\*(C'\fR, \f(CW\*(C`cast\*(C'\fR, | |
1705 | should be used if the \f(CW\*(C`pointer\*(C'\fR argument is different from the \f(CW\*(C`type\*(C'\fR | |
1706 | argument. | |
1707 | .PP | |
1708 | Unlike the \f(CW\*(C`New\*(C'\fR and \f(CW\*(C`Newc\*(C'\fR macros, the \f(CW\*(C`Newz\*(C'\fR macro calls \f(CW\*(C`memzero\*(C'\fR | |
1709 | to zero out all the newly allocated memory. | |
1710 | .PP | |
1711 | .Vb 3 | |
1712 | \& Renew(pointer, number, type); | |
1713 | \& Renewc(pointer, number, type, cast); | |
1714 | \& Safefree(pointer) | |
1715 | .Ve | |
1716 | .PP | |
1717 | These three macros are used to change a memory buffer size or to free a | |
1718 | piece of memory no longer needed. The arguments to \f(CW\*(C`Renew\*(C'\fR and \f(CW\*(C`Renewc\*(C'\fR | |
1719 | match those of \f(CW\*(C`New\*(C'\fR and \f(CW\*(C`Newc\*(C'\fR with the exception of not needing the | |
1720 | \&\*(L"magic cookie\*(R" argument. | |
1721 | .PP | |
1722 | .Vb 3 | |
1723 | \& Move(source, dest, number, type); | |
1724 | \& Copy(source, dest, number, type); | |
1725 | \& Zero(dest, number, type); | |
1726 | .Ve | |
1727 | .PP | |
1728 | These three macros are used to move, copy, or zero out previously allocated | |
1729 | memory. The \f(CW\*(C`source\*(C'\fR and \f(CW\*(C`dest\*(C'\fR arguments point to the source and | |
1730 | destination starting points. Perl will move, copy, or zero out \f(CW\*(C`number\*(C'\fR | |
1731 | instances of the size of the \f(CW\*(C`type\*(C'\fR data structure (using the \f(CW\*(C`sizeof\*(C'\fR | |
1732 | function). | |
1733 | .Sh "PerlIO" | |
1734 | .IX Subsection "PerlIO" | |
1735 | The most recent development releases of Perl has been experimenting with | |
1736 | removing Perl's dependency on the \*(L"normal\*(R" standard I/O suite and allowing | |
1737 | other stdio implementations to be used. This involves creating a new | |
1738 | abstraction layer that then calls whichever implementation of stdio Perl | |
1739 | was compiled with. All XSUBs should now use the functions in the PerlIO | |
1740 | abstraction layer and not make any assumptions about what kind of stdio | |
1741 | is being used. | |
1742 | .PP | |
1743 | For a complete description of the PerlIO abstraction, consult perlapio. | |
1744 | .Sh "Putting a C value on Perl stack" | |
1745 | .IX Subsection "Putting a C value on Perl stack" | |
1746 | A lot of opcodes (this is an elementary operation in the internal perl | |
1747 | stack machine) put an SV* on the stack. However, as an optimization | |
1748 | the corresponding \s-1SV\s0 is (usually) not recreated each time. The opcodes | |
1749 | reuse specially assigned SVs (\fItarget\fRs) which are (as a corollary) | |
1750 | not constantly freed/created. | |
1751 | .PP | |
1752 | Each of the targets is created only once (but see | |
1753 | \&\*(L"Scratchpads and recursion\*(R" below), and when an opcode needs to put | |
1754 | an integer, a double, or a string on stack, it just sets the | |
1755 | corresponding parts of its \fItarget\fR and puts the \fItarget\fR on stack. | |
1756 | .PP | |
1757 | The macro to put this target on stack is \f(CW\*(C`PUSHTARG\*(C'\fR, and it is | |
1758 | directly used in some opcodes, as well as indirectly in zillions of | |
1759 | others, which use it via \f(CW\*(C`(X)PUSH[pni]\*(C'\fR. | |
1760 | .PP | |
1761 | Because the target is reused, you must be careful when pushing multiple | |
1762 | values on the stack. The following code will not do what you think: | |
1763 | .PP | |
1764 | .Vb 2 | |
1765 | \& XPUSHi(10); | |
1766 | \& XPUSHi(20); | |
1767 | .Ve | |
1768 | .PP | |
1769 | This translates as "set \f(CW\*(C`TARG\*(C'\fR to 10, push a pointer to \f(CW\*(C`TARG\*(C'\fR onto | |
1770 | the stack; set \f(CW\*(C`TARG\*(C'\fR to 20, push a pointer to \f(CW\*(C`TARG\*(C'\fR onto the stack". | |
1771 | At the end of the operation, the stack does not contain the values 10 | |
1772 | and 20, but actually contains two pointers to \f(CW\*(C`TARG\*(C'\fR, which we have set | |
1773 | to 20. If you need to push multiple different values, use \f(CW\*(C`XPUSHs\*(C'\fR, | |
1774 | which bypasses \f(CW\*(C`TARG\*(C'\fR. | |
1775 | .PP | |
1776 | On a related note, if you do use \f(CW\*(C`(X)PUSH[npi]\*(C'\fR, then you're going to | |
1777 | need a \f(CW\*(C`dTARG\*(C'\fR in your variable declarations so that the \f(CW\*(C`*PUSH*\*(C'\fR | |
1778 | macros can make use of the local variable \f(CW\*(C`TARG\*(C'\fR. | |
1779 | .Sh "Scratchpads" | |
1780 | .IX Subsection "Scratchpads" | |
1781 | The question remains on when the SVs which are \fItarget\fRs for opcodes | |
1782 | are created. The answer is that they are created when the current unit \*(-- | |
1783 | a subroutine or a file (for opcodes for statements outside of | |
1784 | subroutines) \*(-- is compiled. During this time a special anonymous Perl | |
1785 | array is created, which is called a scratchpad for the current | |
1786 | unit. | |
1787 | .PP | |
1788 | A scratchpad keeps SVs which are lexicals for the current unit and are | |
1789 | targets for opcodes. One can deduce that an \s-1SV\s0 lives on a scratchpad | |
1790 | by looking on its flags: lexicals have \f(CW\*(C`SVs_PADMY\*(C'\fR set, and | |
1791 | \&\fItarget\fRs have \f(CW\*(C`SVs_PADTMP\*(C'\fR set. | |
1792 | .PP | |
1793 | The correspondence between OPs and \fItarget\fRs is not 1\-to\-1. Different | |
1794 | OPs in the compile tree of the unit can use the same target, if this | |
1795 | would not conflict with the expected life of the temporary. | |
1796 | .Sh "Scratchpads and recursion" | |
1797 | .IX Subsection "Scratchpads and recursion" | |
1798 | In fact it is not 100% true that a compiled unit contains a pointer to | |
1799 | the scratchpad \s-1AV\s0. In fact it contains a pointer to an \s-1AV\s0 of | |
1800 | (initially) one element, and this element is the scratchpad \s-1AV\s0. Why do | |
1801 | we need an extra level of indirection? | |
1802 | .PP | |
1803 | The answer is \fBrecursion\fR, and maybe \fBthreads\fR. Both | |
1804 | these can create several execution pointers going into the same | |
1805 | subroutine. For the subroutine-child not write over the temporaries | |
1806 | for the subroutine-parent (lifespan of which covers the call to the | |
1807 | child), the parent and the child should have different | |
1808 | scratchpads. (\fIAnd\fR the lexicals should be separate anyway!) | |
1809 | .PP | |
1810 | So each subroutine is born with an array of scratchpads (of length 1). | |
1811 | On each entry to the subroutine it is checked that the current | |
1812 | depth of the recursion is not more than the length of this array, and | |
1813 | if it is, new scratchpad is created and pushed into the array. | |
1814 | .PP | |
1815 | The \fItarget\fRs on this scratchpad are \f(CW\*(C`undef\*(C'\fRs, but they are already | |
1816 | marked with correct flags. | |
1817 | .SH "Compiled code" | |
1818 | .IX Header "Compiled code" | |
1819 | .Sh "Code tree" | |
1820 | .IX Subsection "Code tree" | |
1821 | Here we describe the internal form your code is converted to by | |
1822 | Perl. Start with a simple example: | |
1823 | .PP | |
1824 | .Vb 1 | |
1825 | \& $a = $b + $c; | |
1826 | .Ve | |
1827 | .PP | |
1828 | This is converted to a tree similar to this one: | |
1829 | .PP | |
1830 | .Vb 5 | |
1831 | \& assign-to | |
1832 | \& / \e | |
1833 | \& + $a | |
1834 | \& / \e | |
1835 | \& $b $c | |
1836 | .Ve | |
1837 | .PP | |
1838 | (but slightly more complicated). This tree reflects the way Perl | |
1839 | parsed your code, but has nothing to do with the execution order. | |
1840 | There is an additional \*(L"thread\*(R" going through the nodes of the tree | |
1841 | which shows the order of execution of the nodes. In our simplified | |
1842 | example above it looks like: | |
1843 | .PP | |
1844 | .Vb 1 | |
1845 | \& $b ---> $c ---> + ---> $a ---> assign-to | |
1846 | .Ve | |
1847 | .PP | |
1848 | But with the actual compile tree for \f(CW\*(C`$a = $b + $c\*(C'\fR it is different: | |
1849 | some nodes \fIoptimized away\fR. As a corollary, though the actual tree | |
1850 | contains more nodes than our simplified example, the execution order | |
1851 | is the same as in our example. | |
1852 | .Sh "Examining the tree" | |
1853 | .IX Subsection "Examining the tree" | |
1854 | If you have your perl compiled for debugging (usually done with \f(CW\*(C`\-D | |
1855 | optimize=\-g\*(C'\fR on \f(CW\*(C`Configure\*(C'\fR command line), you may examine the | |
1856 | compiled tree by specifying \f(CW\*(C`\-Dx\*(C'\fR on the Perl command line. The | |
1857 | output takes several lines per node, and for \f(CW\*(C`$b+$c\*(C'\fR it looks like | |
1858 | this: | |
1859 | .PP | |
1860 | .Vb 23 | |
1861 | \& 5 TYPE = add ===> 6 | |
1862 | \& TARG = 1 | |
1863 | \& FLAGS = (SCALAR,KIDS) | |
1864 | \& { | |
1865 | \& TYPE = null ===> (4) | |
1866 | \& (was rv2sv) | |
1867 | \& FLAGS = (SCALAR,KIDS) | |
1868 | \& { | |
1869 | \& 3 TYPE = gvsv ===> 4 | |
1870 | \& FLAGS = (SCALAR) | |
1871 | \& GV = main::b | |
1872 | \& } | |
1873 | \& } | |
1874 | \& { | |
1875 | \& TYPE = null ===> (5) | |
1876 | \& (was rv2sv) | |
1877 | \& FLAGS = (SCALAR,KIDS) | |
1878 | \& { | |
1879 | \& 4 TYPE = gvsv ===> 5 | |
1880 | \& FLAGS = (SCALAR) | |
1881 | \& GV = main::c | |
1882 | \& } | |
1883 | \& } | |
1884 | .Ve | |
1885 | .PP | |
1886 | This tree has 5 nodes (one per \f(CW\*(C`TYPE\*(C'\fR specifier), only 3 of them are | |
1887 | not optimized away (one per number in the left column). The immediate | |
1888 | children of the given node correspond to \f(CW\*(C`{}\*(C'\fR pairs on the same level | |
1889 | of indentation, thus this listing corresponds to the tree: | |
1890 | .PP | |
1891 | .Vb 5 | |
1892 | \& add | |
1893 | \& / \e | |
1894 | \& null null | |
1895 | \& | | | |
1896 | \& gvsv gvsv | |
1897 | .Ve | |
1898 | .PP | |
1899 | The execution order is indicated by \f(CW\*(C`===>\*(C'\fR marks, thus it is \f(CW\*(C`3 | |
1900 | 4 5 6\*(C'\fR (node \f(CW6\fR is not included into above listing), i.e., | |
1901 | \&\f(CW\*(C`gvsv gvsv add whatever\*(C'\fR. | |
1902 | .PP | |
1903 | Each of these nodes represents an op, a fundamental operation inside the | |
1904 | Perl core. The code which implements each operation can be found in the | |
1905 | \&\fIpp*.c\fR files; the function which implements the op with type \f(CW\*(C`gvsv\*(C'\fR | |
1906 | is \f(CW\*(C`pp_gvsv\*(C'\fR, and so on. As the tree above shows, different ops have | |
1907 | different numbers of children: \f(CW\*(C`add\*(C'\fR is a binary operator, as one would | |
1908 | expect, and so has two children. To accommodate the various different | |
1909 | numbers of children, there are various types of op data structure, and | |
1910 | they link together in different ways. | |
1911 | .PP | |
1912 | The simplest type of op structure is \f(CW\*(C`OP\*(C'\fR: this has no children. Unary | |
1913 | operators, \f(CW\*(C`UNOP\*(C'\fRs, have one child, and this is pointed to by the | |
1914 | \&\f(CW\*(C`op_first\*(C'\fR field. Binary operators (\f(CW\*(C`BINOP\*(C'\fRs) have not only an | |
1915 | \&\f(CW\*(C`op_first\*(C'\fR field but also an \f(CW\*(C`op_last\*(C'\fR field. The most complex type of | |
1916 | op is a \f(CW\*(C`LISTOP\*(C'\fR, which has any number of children. In this case, the | |
1917 | first child is pointed to by \f(CW\*(C`op_first\*(C'\fR and the last child by | |
1918 | \&\f(CW\*(C`op_last\*(C'\fR. The children in between can be found by iteratively | |
1919 | following the \f(CW\*(C`op_sibling\*(C'\fR pointer from the first child to the last. | |
1920 | .PP | |
1921 | There are also two other op types: a \f(CW\*(C`PMOP\*(C'\fR holds a regular expression, | |
1922 | and has no children, and a \f(CW\*(C`LOOP\*(C'\fR may or may not have children. If the | |
1923 | \&\f(CW\*(C`op_children\*(C'\fR field is non\-zero, it behaves like a \f(CW\*(C`LISTOP\*(C'\fR. To | |
1924 | complicate matters, if a \f(CW\*(C`UNOP\*(C'\fR is actually a \f(CW\*(C`null\*(C'\fR op after | |
1925 | optimization (see \*(L"Compile pass 2: context propagation\*(R") it will still | |
1926 | have children in accordance with its former type. | |
1927 | .Sh "Compile pass 1: check routines" | |
1928 | .IX Subsection "Compile pass 1: check routines" | |
1929 | The tree is created by the compiler while \fIyacc\fR code feeds it | |
1930 | the constructions it recognizes. Since \fIyacc\fR works bottom\-up, so does | |
1931 | the first pass of perl compilation. | |
1932 | .PP | |
1933 | What makes this pass interesting for perl developers is that some | |
1934 | optimization may be performed on this pass. This is optimization by | |
1935 | so-called \*(L"check routines\*(R". The correspondence between node names | |
1936 | and corresponding check routines is described in \fIopcode.pl\fR (do not | |
1937 | forget to run \f(CW\*(C`make regen_headers\*(C'\fR if you modify this file). | |
1938 | .PP | |
1939 | A check routine is called when the node is fully constructed except | |
1940 | for the execution-order thread. Since at this time there are no | |
1941 | back-links to the currently constructed node, one can do most any | |
1942 | operation to the top-level node, including freeing it and/or creating | |
1943 | new nodes above/below it. | |
1944 | .PP | |
1945 | The check routine returns the node which should be inserted into the | |
1946 | tree (if the top-level node was not modified, check routine returns | |
1947 | its argument). | |
1948 | .PP | |
1949 | By convention, check routines have names \f(CW\*(C`ck_*\*(C'\fR. They are usually | |
1950 | called from \f(CW\*(C`new*OP\*(C'\fR subroutines (or \f(CW\*(C`convert\*(C'\fR) (which in turn are | |
1951 | called from \fIperly.y\fR). | |
1952 | .Sh "Compile pass 1a: constant folding" | |
1953 | .IX Subsection "Compile pass 1a: constant folding" | |
1954 | Immediately after the check routine is called the returned node is | |
1955 | checked for being compile-time executable. If it is (the value is | |
1956 | judged to be constant) it is immediately executed, and a \fIconstant\fR | |
1957 | node with the \*(L"return value\*(R" of the corresponding subtree is | |
1958 | substituted instead. The subtree is deleted. | |
1959 | .PP | |
1960 | If constant folding was not performed, the execution-order thread is | |
1961 | created. | |
1962 | .Sh "Compile pass 2: context propagation" | |
1963 | .IX Subsection "Compile pass 2: context propagation" | |
1964 | When a context for a part of compile tree is known, it is propagated | |
1965 | down through the tree. At this time the context can have 5 values | |
1966 | (instead of 2 for runtime context): void, boolean, scalar, list, and | |
1967 | lvalue. In contrast with the pass 1 this pass is processed from top | |
1968 | to bottom: a node's context determines the context for its children. | |
1969 | .PP | |
1970 | Additional context-dependent optimizations are performed at this time. | |
1971 | Since at this moment the compile tree contains back-references (via | |
1972 | \&\*(L"thread\*(R" pointers), nodes cannot be \fIfree()\fRd now. To allow | |
1973 | optimized-away nodes at this stage, such nodes are \fInull()\fRified instead | |
1974 | of \fIfree()\fRing (i.e. their type is changed to \s-1OP_NULL\s0). | |
1975 | .Sh "Compile pass 3: peephole optimization" | |
1976 | .IX Subsection "Compile pass 3: peephole optimization" | |
1977 | After the compile tree for a subroutine (or for an \f(CW\*(C`eval\*(C'\fR or a file) | |
1978 | is created, an additional pass over the code is performed. This pass | |
1979 | is neither top-down or bottom\-up, but in the execution order (with | |
1980 | additional complications for conditionals). These optimizations are | |
1981 | done in the subroutine \fIpeep()\fR. Optimizations performed at this stage | |
1982 | are subject to the same restrictions as in the pass 2. | |
1983 | .Sh "Pluggable runops" | |
1984 | .IX Subsection "Pluggable runops" | |
1985 | The compile tree is executed in a runops function. There are two runops | |
1986 | functions in \fIrun.c\fR. \f(CW\*(C`Perl_runops_debug\*(C'\fR is used with \s-1DEBUGGING\s0 and | |
1987 | \&\f(CW\*(C`Perl_runops_standard\*(C'\fR is used otherwise. For fine control over the | |
1988 | execution of the compile tree it is possible to provide your own runops | |
1989 | function. | |
1990 | .PP | |
1991 | It's probably best to copy one of the existing runops functions and | |
1992 | change it to suit your needs. Then, in the \s-1BOOT\s0 section of your \s-1XS\s0 | |
1993 | file, add the line: | |
1994 | .PP | |
1995 | .Vb 1 | |
1996 | \& PL_runops = my_runops; | |
1997 | .Ve | |
1998 | .PP | |
1999 | This function should be as efficient as possible to keep your programs | |
2000 | running as fast as possible. | |
2001 | .ie n .SH "Examining internal data structures with the ""dump"" functions" | |
2002 | .el .SH "Examining internal data structures with the \f(CWdump\fP functions" | |
2003 | .IX Header "Examining internal data structures with the dump functions" | |
2004 | To aid debugging, the source file \fIdump.c\fR contains a number of | |
2005 | functions which produce formatted output of internal data structures. | |
2006 | .PP | |
2007 | The most commonly used of these functions is \f(CW\*(C`Perl_sv_dump\*(C'\fR; it's used | |
2008 | for dumping SVs, AVs, HVs, and CVs. The \f(CW\*(C`Devel::Peek\*(C'\fR module calls | |
2009 | \&\f(CW\*(C`sv_dump\*(C'\fR to produce debugging output from Perl\-space, so users of that | |
2010 | module should already be familiar with its format. | |
2011 | .PP | |
2012 | \&\f(CW\*(C`Perl_op_dump\*(C'\fR can be used to dump an \f(CW\*(C`OP\*(C'\fR structure or any of its | |
2013 | derivatives, and produces output similar to \f(CW\*(C`perl \-Dx\*(C'\fR; in fact, | |
2014 | \&\f(CW\*(C`Perl_dump_eval\*(C'\fR will dump the main root of the code being evaluated, | |
2015 | exactly like \f(CW\*(C`\-Dx\*(C'\fR. | |
2016 | .PP | |
2017 | Other useful functions are \f(CW\*(C`Perl_dump_sub\*(C'\fR, which turns a \f(CW\*(C`GV\*(C'\fR into an | |
2018 | op tree, \f(CW\*(C`Perl_dump_packsubs\*(C'\fR which calls \f(CW\*(C`Perl_dump_sub\*(C'\fR on all the | |
2019 | subroutines in a package like so: (Thankfully, these are all xsubs, so | |
2020 | there is no op tree) | |
2021 | .PP | |
2022 | .Vb 1 | |
2023 | \& (gdb) print Perl_dump_packsubs(PL_defstash) | |
2024 | .Ve | |
2025 | .PP | |
2026 | .Vb 1 | |
2027 | \& SUB attributes::bootstrap = (xsub 0x811fedc 0) | |
2028 | .Ve | |
2029 | .PP | |
2030 | .Vb 1 | |
2031 | \& SUB UNIVERSAL::can = (xsub 0x811f50c 0) | |
2032 | .Ve | |
2033 | .PP | |
2034 | .Vb 1 | |
2035 | \& SUB UNIVERSAL::isa = (xsub 0x811f304 0) | |
2036 | .Ve | |
2037 | .PP | |
2038 | .Vb 1 | |
2039 | \& SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0) | |
2040 | .Ve | |
2041 | .PP | |
2042 | .Vb 1 | |
2043 | \& SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0) | |
2044 | .Ve | |
2045 | .PP | |
2046 | and \f(CW\*(C`Perl_dump_all\*(C'\fR, which dumps all the subroutines in the stash and | |
2047 | the op tree of the main root. | |
2048 | .SH "How multiple interpreters and concurrency are supported" | |
2049 | .IX Header "How multiple interpreters and concurrency are supported" | |
2050 | .Sh "Background and \s-1PERL_IMPLICIT_CONTEXT\s0" | |
2051 | .IX Subsection "Background and PERL_IMPLICIT_CONTEXT" | |
2052 | The Perl interpreter can be regarded as a closed box: it has an \s-1API\s0 | |
2053 | for feeding it code or otherwise making it do things, but it also has | |
2054 | functions for its own use. This smells a lot like an object, and | |
2055 | there are ways for you to build Perl so that you can have multiple | |
2056 | interpreters, with one interpreter represented either as a C structure, | |
2057 | or inside a thread-specific structure. These structures contain all | |
2058 | the context, the state of that interpreter. | |
2059 | .PP | |
2060 | Two macros control the major Perl build flavors: \s-1MULTIPLICITY\s0 and | |
2061 | \&\s-1USE_5005THREADS\s0. The \s-1MULTIPLICITY\s0 build has a C structure | |
2062 | that packages all the interpreter state, and there is a similar thread-specific | |
2063 | data structure under \s-1USE_5005THREADS\s0. In both cases, | |
2064 | \&\s-1PERL_IMPLICIT_CONTEXT\s0 is also normally defined, and enables the | |
2065 | support for passing in a \*(L"hidden\*(R" first argument that represents all three | |
2066 | data structures. | |
2067 | .PP | |
2068 | All this obviously requires a way for the Perl internal functions to be | |
2069 | either subroutines taking some kind of structure as the first | |
2070 | argument, or subroutines taking nothing as the first argument. To | |
2071 | enable these two very different ways of building the interpreter, | |
2072 | the Perl source (as it does in so many other situations) makes heavy | |
2073 | use of macros and subroutine naming conventions. | |
2074 | .PP | |
2075 | First problem: deciding which functions will be public \s-1API\s0 functions and | |
2076 | which will be private. All functions whose names begin \f(CW\*(C`S_\*(C'\fR are private | |
2077 | (think \*(L"S\*(R" for \*(L"secret\*(R" or \*(L"static\*(R"). All other functions begin with | |
2078 | \&\*(L"Perl_\*(R", but just because a function begins with \*(L"Perl_\*(R" does not mean it is | |
2079 | part of the \s-1API\s0. (See \*(L"Internal Functions\*(R".) The easiest way to be \fBsure\fR a | |
2080 | function is part of the \s-1API\s0 is to find its entry in perlapi. | |
2081 | If it exists in perlapi, it's part of the \s-1API\s0. If it doesn't, and you | |
2082 | think it should be (i.e., you need it for your extension), send mail via | |
2083 | perlbug explaining why you think it should be. | |
2084 | .PP | |
2085 | Second problem: there must be a syntax so that the same subroutine | |
2086 | declarations and calls can pass a structure as their first argument, | |
2087 | or pass nothing. To solve this, the subroutines are named and | |
2088 | declared in a particular way. Here's a typical start of a static | |
2089 | function used within the Perl guts: | |
2090 | .PP | |
2091 | .Vb 2 | |
2092 | \& STATIC void | |
2093 | \& S_incline(pTHX_ char *s) | |
2094 | .Ve | |
2095 | .PP | |
2096 | \&\s-1STATIC\s0 becomes \*(L"static\*(R" in C, and may be #define'd to nothing in some | |
2097 | configurations in future. | |
2098 | .PP | |
2099 | A public function (i.e. part of the internal \s-1API\s0, but not necessarily | |
2100 | sanctioned for use in extensions) begins like this: | |
2101 | .PP | |
2102 | .Vb 2 | |
2103 | \& void | |
2104 | \& Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv) | |
2105 | .Ve | |
2106 | .PP | |
2107 | \&\f(CW\*(C`pTHX_\*(C'\fR is one of a number of macros (in perl.h) that hide the | |
2108 | details of the interpreter's context. \s-1THX\s0 stands for \*(L"thread\*(R", \*(L"this\*(R", | |
2109 | or \*(L"thingy\*(R", as the case may be. (And no, George Lucas is not involved. :\-) | |
2110 | The first character could be 'p' for a \fBp\fRrototype, 'a' for \fBa\fRrgument, | |
2111 | or 'd' for \fBd\fReclaration, so we have \f(CW\*(C`pTHX\*(C'\fR, \f(CW\*(C`aTHX\*(C'\fR and \f(CW\*(C`dTHX\*(C'\fR, and | |
2112 | their variants. | |
2113 | .PP | |
2114 | When Perl is built without options that set \s-1PERL_IMPLICIT_CONTEXT\s0, there is no | |
2115 | first argument containing the interpreter's context. The trailing underscore | |
2116 | in the pTHX_ macro indicates that the macro expansion needs a comma | |
2117 | after the context argument because other arguments follow it. If | |
2118 | \&\s-1PERL_IMPLICIT_CONTEXT\s0 is not defined, pTHX_ will be ignored, and the | |
2119 | subroutine is not prototyped to take the extra argument. The form of the | |
2120 | macro without the trailing underscore is used when there are no additional | |
2121 | explicit arguments. | |
2122 | .PP | |
2123 | When a core function calls another, it must pass the context. This | |
2124 | is normally hidden via macros. Consider \f(CW\*(C`sv_setsv\*(C'\fR. It expands into | |
2125 | something like this: | |
2126 | .PP | |
2127 | .Vb 6 | |
2128 | \& ifdef PERL_IMPLICIT_CONTEXT | |
2129 | \& define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b) | |
2130 | \& /* can't do this for vararg functions, see below */ | |
2131 | \& else | |
2132 | \& define sv_setsv Perl_sv_setsv | |
2133 | \& endif | |
2134 | .Ve | |
2135 | .PP | |
2136 | This works well, and means that \s-1XS\s0 authors can gleefully write: | |
2137 | .PP | |
2138 | .Vb 1 | |
2139 | \& sv_setsv(foo, bar); | |
2140 | .Ve | |
2141 | .PP | |
2142 | and still have it work under all the modes Perl could have been | |
2143 | compiled with. | |
2144 | .PP | |
2145 | This doesn't work so cleanly for varargs functions, though, as macros | |
2146 | imply that the number of arguments is known in advance. Instead we | |
2147 | either need to spell them out fully, passing \f(CW\*(C`aTHX_\*(C'\fR as the first | |
2148 | argument (the Perl core tends to do this with functions like | |
2149 | Perl_warner), or use a context-free version. | |
2150 | .PP | |
2151 | The context-free version of Perl_warner is called | |
2152 | Perl_warner_nocontext, and does not take the extra argument. Instead | |
2153 | it does dTHX; to get the context from thread-local storage. We | |
2154 | \&\f(CW\*(C`#define warner Perl_warner_nocontext\*(C'\fR so that extensions get source | |
2155 | compatibility at the expense of performance. (Passing an arg is | |
2156 | cheaper than grabbing it from thread-local storage.) | |
2157 | .PP | |
2158 | You can ignore [pad]THXx when browsing the Perl headers/sources. | |
2159 | Those are strictly for use within the core. Extensions and embedders | |
2160 | need only be aware of [pad]THX. | |
2161 | .Sh "So what happened to dTHR?" | |
2162 | .IX Subsection "So what happened to dTHR?" | |
2163 | \&\f(CW\*(C`dTHR\*(C'\fR was introduced in perl 5.005 to support the older thread model. | |
2164 | The older thread model now uses the \f(CW\*(C`THX\*(C'\fR mechanism to pass context | |
2165 | pointers around, so \f(CW\*(C`dTHR\*(C'\fR is not useful any more. Perl 5.6.0 and | |
2166 | later still have it for backward source compatibility, but it is defined | |
2167 | to be a no\-op. | |
2168 | .Sh "How do I use all this in extensions?" | |
2169 | .IX Subsection "How do I use all this in extensions?" | |
2170 | When Perl is built with \s-1PERL_IMPLICIT_CONTEXT\s0, extensions that call | |
2171 | any functions in the Perl \s-1API\s0 will need to pass the initial context | |
2172 | argument somehow. The kicker is that you will need to write it in | |
2173 | such a way that the extension still compiles when Perl hasn't been | |
2174 | built with \s-1PERL_IMPLICIT_CONTEXT\s0 enabled. | |
2175 | .PP | |
2176 | There are three ways to do this. First, the easy but inefficient way, | |
2177 | which is also the default, in order to maintain source compatibility | |
2178 | with extensions: whenever \s-1XSUB\s0.h is #included, it redefines the aTHX | |
2179 | and aTHX_ macros to call a function that will return the context. | |
2180 | Thus, something like: | |
2181 | .PP | |
2182 | .Vb 1 | |
2183 | \& sv_setsv(asv, bsv); | |
2184 | .Ve | |
2185 | .PP | |
2186 | in your extension will translate to this when \s-1PERL_IMPLICIT_CONTEXT\s0 is | |
2187 | in effect: | |
2188 | .PP | |
2189 | .Vb 1 | |
2190 | \& Perl_sv_setsv(Perl_get_context(), asv, bsv); | |
2191 | .Ve | |
2192 | .PP | |
2193 | or to this otherwise: | |
2194 | .PP | |
2195 | .Vb 1 | |
2196 | \& Perl_sv_setsv(asv, bsv); | |
2197 | .Ve | |
2198 | .PP | |
2199 | You have to do nothing new in your extension to get this; since | |
2200 | the Perl library provides \fIPerl_get_context()\fR, it will all just | |
2201 | work. | |
2202 | .PP | |
2203 | The second, more efficient way is to use the following template for | |
2204 | your Foo.xs: | |
2205 | .PP | |
2206 | .Vb 4 | |
2207 | \& #define PERL_NO_GET_CONTEXT /* we want efficiency */ | |
2208 | \& #include "EXTERN.h" | |
2209 | \& #include "perl.h" | |
2210 | \& #include "XSUB.h" | |
2211 | .Ve | |
2212 | .PP | |
2213 | .Vb 1 | |
2214 | \& static my_private_function(int arg1, int arg2); | |
2215 | .Ve | |
2216 | .PP | |
2217 | .Vb 6 | |
2218 | \& static SV * | |
2219 | \& my_private_function(int arg1, int arg2) | |
2220 | \& { | |
2221 | \& dTHX; /* fetch context */ | |
2222 | \& ... call many Perl API functions ... | |
2223 | \& } | |
2224 | .Ve | |
2225 | .PP | |
2226 | .Vb 1 | |
2227 | \& [... etc ...] | |
2228 | .Ve | |
2229 | .PP | |
2230 | .Vb 1 | |
2231 | \& MODULE = Foo PACKAGE = Foo | |
2232 | .Ve | |
2233 | .PP | |
2234 | .Vb 1 | |
2235 | \& /* typical XSUB */ | |
2236 | .Ve | |
2237 | .PP | |
2238 | .Vb 5 | |
2239 | \& void | |
2240 | \& my_xsub(arg) | |
2241 | \& int arg | |
2242 | \& CODE: | |
2243 | \& my_private_function(arg, 10); | |
2244 | .Ve | |
2245 | .PP | |
2246 | Note that the only two changes from the normal way of writing an | |
2247 | extension is the addition of a \f(CW\*(C`#define PERL_NO_GET_CONTEXT\*(C'\fR before | |
2248 | including the Perl headers, followed by a \f(CW\*(C`dTHX;\*(C'\fR declaration at | |
2249 | the start of every function that will call the Perl \s-1API\s0. (You'll | |
2250 | know which functions need this, because the C compiler will complain | |
2251 | that there's an undeclared identifier in those functions.) No changes | |
2252 | are needed for the XSUBs themselves, because the \s-1\fIXS\s0()\fR macro is | |
2253 | correctly defined to pass in the implicit context if needed. | |
2254 | .PP | |
2255 | The third, even more efficient way is to ape how it is done within | |
2256 | the Perl guts: | |
2257 | .PP | |
2258 | .Vb 4 | |
2259 | \& #define PERL_NO_GET_CONTEXT /* we want efficiency */ | |
2260 | \& #include "EXTERN.h" | |
2261 | \& #include "perl.h" | |
2262 | \& #include "XSUB.h" | |
2263 | .Ve | |
2264 | .PP | |
2265 | .Vb 2 | |
2266 | \& /* pTHX_ only needed for functions that call Perl API */ | |
2267 | \& static my_private_function(pTHX_ int arg1, int arg2); | |
2268 | .Ve | |
2269 | .PP | |
2270 | .Vb 6 | |
2271 | \& static SV * | |
2272 | \& my_private_function(pTHX_ int arg1, int arg2) | |
2273 | \& { | |
2274 | \& /* dTHX; not needed here, because THX is an argument */ | |
2275 | \& ... call Perl API functions ... | |
2276 | \& } | |
2277 | .Ve | |
2278 | .PP | |
2279 | .Vb 1 | |
2280 | \& [... etc ...] | |
2281 | .Ve | |
2282 | .PP | |
2283 | .Vb 1 | |
2284 | \& MODULE = Foo PACKAGE = Foo | |
2285 | .Ve | |
2286 | .PP | |
2287 | .Vb 1 | |
2288 | \& /* typical XSUB */ | |
2289 | .Ve | |
2290 | .PP | |
2291 | .Vb 5 | |
2292 | \& void | |
2293 | \& my_xsub(arg) | |
2294 | \& int arg | |
2295 | \& CODE: | |
2296 | \& my_private_function(aTHX_ arg, 10); | |
2297 | .Ve | |
2298 | .PP | |
2299 | This implementation never has to fetch the context using a function | |
2300 | call, since it is always passed as an extra argument. Depending on | |
2301 | your needs for simplicity or efficiency, you may mix the previous | |
2302 | two approaches freely. | |
2303 | .PP | |
2304 | Never add a comma after \f(CW\*(C`pTHX\*(C'\fR yourself\*(--always use the form of the | |
2305 | macro with the underscore for functions that take explicit arguments, | |
2306 | or the form without the argument for functions with no explicit arguments. | |
2307 | .Sh "Should I do anything special if I call perl from multiple threads?" | |
2308 | .IX Subsection "Should I do anything special if I call perl from multiple threads?" | |
2309 | If you create interpreters in one thread and then proceed to call them in | |
2310 | another, you need to make sure perl's own Thread Local Storage (\s-1TLS\s0) slot is | |
2311 | initialized correctly in each of those threads. | |
2312 | .PP | |
2313 | The \f(CW\*(C`perl_alloc\*(C'\fR and \f(CW\*(C`perl_clone\*(C'\fR \s-1API\s0 functions will automatically set | |
2314 | the \s-1TLS\s0 slot to the interpreter they created, so that there is no need to do | |
2315 | anything special if the interpreter is always accessed in the same thread that | |
2316 | created it, and that thread did not create or call any other interpreters | |
2317 | afterwards. If that is not the case, you have to set the \s-1TLS\s0 slot of the | |
2318 | thread before calling any functions in the Perl \s-1API\s0 on that particular | |
2319 | interpreter. This is done by calling the \f(CW\*(C`PERL_SET_CONTEXT\*(C'\fR macro in that | |
2320 | thread as the first thing you do: | |
2321 | .PP | |
2322 | .Vb 2 | |
2323 | \& /* do this before doing anything else with some_perl */ | |
2324 | \& PERL_SET_CONTEXT(some_perl); | |
2325 | .Ve | |
2326 | .PP | |
2327 | .Vb 1 | |
2328 | \& ... other Perl API calls on some_perl go here ... | |
2329 | .Ve | |
2330 | .Sh "Future Plans and \s-1PERL_IMPLICIT_SYS\s0" | |
2331 | .IX Subsection "Future Plans and PERL_IMPLICIT_SYS" | |
2332 | Just as \s-1PERL_IMPLICIT_CONTEXT\s0 provides a way to bundle up everything | |
2333 | that the interpreter knows about itself and pass it around, so too are | |
2334 | there plans to allow the interpreter to bundle up everything it knows | |
2335 | about the environment it's running on. This is enabled with the | |
2336 | \&\s-1PERL_IMPLICIT_SYS\s0 macro. Currently it only works with \s-1USE_ITHREADS\s0 | |
2337 | and \s-1USE_5005THREADS\s0 on Windows (see inside iperlsys.h). | |
2338 | .PP | |
2339 | This allows the ability to provide an extra pointer (called the \*(L"host\*(R" | |
2340 | environment) for all the system calls. This makes it possible for | |
2341 | all the system stuff to maintain their own state, broken down into | |
2342 | seven C structures. These are thin wrappers around the usual system | |
2343 | calls (see win32/perllib.c) for the default perl executable, but for a | |
2344 | more ambitious host (like the one that would do \fIfork()\fR emulation) all | |
2345 | the extra work needed to pretend that different interpreters are | |
2346 | actually different \*(L"processes\*(R", would be done here. | |
2347 | .PP | |
2348 | The Perl engine/interpreter and the host are orthogonal entities. | |
2349 | There could be one or more interpreters in a process, and one or | |
2350 | more \*(L"hosts\*(R", with free association between them. | |
2351 | .SH "Internal Functions" | |
2352 | .IX Header "Internal Functions" | |
2353 | All of Perl's internal functions which will be exposed to the outside | |
2354 | world are be prefixed by \f(CW\*(C`Perl_\*(C'\fR so that they will not conflict with \s-1XS\s0 | |
2355 | functions or functions used in a program in which Perl is embedded. | |
2356 | Similarly, all global variables begin with \f(CW\*(C`PL_\*(C'\fR. (By convention, | |
2357 | static functions start with \f(CW\*(C`S_\*(C'\fR) | |
2358 | .PP | |
2359 | Inside the Perl core, you can get at the functions either with or | |
2360 | without the \f(CW\*(C`Perl_\*(C'\fR prefix, thanks to a bunch of defines that live in | |
2361 | \&\fIembed.h\fR. This header file is generated automatically from | |
2362 | \&\fIembed.pl\fR. \fIembed.pl\fR also creates the prototyping header files for | |
2363 | the internal functions, generates the documentation and a lot of other | |
2364 | bits and pieces. It's important that when you add a new function to the | |
2365 | core or change an existing one, you change the data in the table at the | |
2366 | end of \fIembed.pl\fR as well. Here's a sample entry from that table: | |
2367 | .PP | |
2368 | .Vb 1 | |
2369 | \& Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval | |
2370 | .Ve | |
2371 | .PP | |
2372 | The second column is the return type, the third column the name. Columns | |
2373 | after that are the arguments. The first column is a set of flags: | |
2374 | .IP "A" 3 | |
2375 | .IX Item "A" | |
2376 | This function is a part of the public \s-1API\s0. | |
2377 | .IP "p" 3 | |
2378 | .IX Item "p" | |
2379 | This function has a \f(CW\*(C`Perl_\*(C'\fR prefix; ie, it is defined as \f(CW\*(C`Perl_av_fetch\*(C'\fR | |
2380 | .IP "d" 3 | |
2381 | .IX Item "d" | |
2382 | This function has documentation using the \f(CW\*(C`apidoc\*(C'\fR feature which we'll | |
2383 | look at in a second. | |
2384 | .PP | |
2385 | Other available flags are: | |
2386 | .IP "s" 3 | |
2387 | .IX Item "s" | |
2388 | This is a static function and is defined as \f(CW\*(C`S_whatever\*(C'\fR, and usually | |
2389 | called within the sources as \f(CW\*(C`whatever(...)\*(C'\fR. | |
2390 | .IP "n" 3 | |
2391 | .IX Item "n" | |
2392 | This does not use \f(CW\*(C`aTHX_\*(C'\fR and \f(CW\*(C`pTHX\*(C'\fR to pass interpreter context. (See | |
2393 | \&\*(L"Background and \s-1PERL_IMPLICIT_CONTEXT\s0\*(R" in perlguts.) | |
2394 | .IP "r" 3 | |
2395 | .IX Item "r" | |
2396 | This function never returns; \f(CW\*(C`croak\*(C'\fR, \f(CW\*(C`exit\*(C'\fR and friends. | |
2397 | .IP "f" 3 | |
2398 | .IX Item "f" | |
2399 | This function takes a variable number of arguments, \f(CW\*(C`printf\*(C'\fR style. | |
2400 | The argument list should end with \f(CW\*(C`...\*(C'\fR, like this: | |
2401 | .Sp | |
2402 | .Vb 1 | |
2403 | \& Afprd |void |croak |const char* pat|... | |
2404 | .Ve | |
2405 | .IP "M" 3 | |
2406 | .IX Item "M" | |
2407 | This function is part of the experimental development \s-1API\s0, and may change | |
2408 | or disappear without notice. | |
2409 | .IP "o" 3 | |
2410 | This function should not have a compatibility macro to define, say, | |
2411 | \&\f(CW\*(C`Perl_parse\*(C'\fR to \f(CW\*(C`parse\*(C'\fR. It must be called as \f(CW\*(C`Perl_parse\*(C'\fR. | |
2412 | .IP "j" 3 | |
2413 | .IX Item "j" | |
2414 | This function is not a member of \f(CW\*(C`CPerlObj\*(C'\fR. If you don't know | |
2415 | what this means, don't use it. | |
2416 | .IP "x" 3 | |
2417 | .IX Item "x" | |
2418 | This function isn't exported out of the Perl core. | |
2419 | .PP | |
2420 | If you edit \fIembed.pl\fR, you will need to run \f(CW\*(C`make regen_headers\*(C'\fR to | |
2421 | force a rebuild of \fIembed.h\fR and other auto-generated files. | |
2422 | .Sh "Formatted Printing of IVs, UVs, and NVs" | |
2423 | .IX Subsection "Formatted Printing of IVs, UVs, and NVs" | |
2424 | If you are printing IVs, UVs, or \s-1NVS\s0 instead of the \fIstdio\fR\|(3) style | |
2425 | formatting codes like \f(CW%d\fR, \f(CW%ld\fR, \f(CW%f\fR, you should use the | |
2426 | following macros for portability | |
2427 | .PP | |
2428 | .Vb 7 | |
2429 | \& IVdf IV in decimal | |
2430 | \& UVuf UV in decimal | |
2431 | \& UVof UV in octal | |
2432 | \& UVxf UV in hexadecimal | |
2433 | \& NVef NV %e-like | |
2434 | \& NVff NV %f-like | |
2435 | \& NVgf NV %g-like | |
2436 | .Ve | |
2437 | .PP | |
2438 | These will take care of 64\-bit integers and long doubles. | |
2439 | For example: | |
2440 | .PP | |
2441 | .Vb 1 | |
2442 | \& printf("IV is %"IVdf"\en", iv); | |
2443 | .Ve | |
2444 | .PP | |
2445 | The IVdf will expand to whatever is the correct format for the IVs. | |
2446 | .PP | |
2447 | If you are printing addresses of pointers, use UVxf combined | |
2448 | with \s-1\fIPTR2UV\s0()\fR, do not use \f(CW%lx\fR or \f(CW%p\fR. | |
2449 | .Sh "Pointer-To-Integer and Integer-To-Pointer" | |
2450 | .IX Subsection "Pointer-To-Integer and Integer-To-Pointer" | |
2451 | Because pointer size does not necessarily equal integer size, | |
2452 | use the follow macros to do it right. | |
2453 | .PP | |
2454 | .Vb 4 | |
2455 | \& PTR2UV(pointer) | |
2456 | \& PTR2IV(pointer) | |
2457 | \& PTR2NV(pointer) | |
2458 | \& INT2PTR(pointertotype, integer) | |
2459 | .Ve | |
2460 | .PP | |
2461 | For example: | |
2462 | .PP | |
2463 | .Vb 2 | |
2464 | \& IV iv = ...; | |
2465 | \& SV *sv = INT2PTR(SV*, iv); | |
2466 | .Ve | |
2467 | .PP | |
2468 | and | |
2469 | .PP | |
2470 | .Vb 2 | |
2471 | \& AV *av = ...; | |
2472 | \& UV uv = PTR2UV(av); | |
2473 | .Ve | |
2474 | .Sh "Source Documentation" | |
2475 | .IX Subsection "Source Documentation" | |
2476 | There's an effort going on to document the internal functions and | |
2477 | automatically produce reference manuals from them \- perlapi is one | |
2478 | such manual which details all the functions which are available to \s-1XS\s0 | |
2479 | writers. perlintern is the autogenerated manual for the functions | |
2480 | which are not part of the \s-1API\s0 and are supposedly for internal use only. | |
2481 | .PP | |
2482 | Source documentation is created by putting \s-1POD\s0 comments into the C | |
2483 | source, like this: | |
2484 | .PP | |
2485 | .Vb 2 | |
2486 | \& /* | |
2487 | \& =for apidoc sv_setiv | |
2488 | .Ve | |
2489 | .PP | |
2490 | .Vb 2 | |
2491 | \& Copies an integer into the given SV. Does not handle 'set' magic. See | |
2492 | \& C<sv_setiv_mg>. | |
2493 | .Ve | |
2494 | .PP | |
2495 | .Vb 2 | |
2496 | \& =cut | |
2497 | \& */ | |
2498 | .Ve | |
2499 | .PP | |
2500 | Please try and supply some documentation if you add functions to the | |
2501 | Perl core. | |
2502 | .SH "Unicode Support" | |
2503 | .IX Header "Unicode Support" | |
2504 | Perl 5.6.0 introduced Unicode support. It's important for porters and \s-1XS\s0 | |
2505 | writers to understand this support and make sure that the code they | |
2506 | write does not corrupt Unicode data. | |
2507 | .Sh "What \fBis\fP Unicode, anyway?" | |
2508 | .IX Subsection "What is Unicode, anyway?" | |
2509 | In the olden, less enlightened times, we all used to use \s-1ASCII\s0. Most of | |
2510 | us did, anyway. The big problem with \s-1ASCII\s0 is that it's American. Well, | |
2511 | no, that's not actually the problem; the problem is that it's not | |
2512 | particularly useful for people who don't use the Roman alphabet. What | |
2513 | used to happen was that particular languages would stick their own | |
2514 | alphabet in the upper range of the sequence, between 128 and 255. Of | |
2515 | course, we then ended up with plenty of variants that weren't quite | |
2516 | \&\s-1ASCII\s0, and the whole point of it being a standard was lost. | |
2517 | .PP | |
2518 | Worse still, if you've got a language like Chinese or | |
2519 | Japanese that has hundreds or thousands of characters, then you really | |
2520 | can't fit them into a mere 256, so they had to forget about \s-1ASCII\s0 | |
2521 | altogether, and build their own systems using pairs of numbers to refer | |
2522 | to one character. | |
2523 | .PP | |
2524 | To fix this, some people formed Unicode, Inc. and | |
2525 | produced a new character set containing all the characters you can | |
2526 | possibly think of and more. There are several ways of representing these | |
2527 | characters, and the one Perl uses is called \s-1UTF8\s0. \s-1UTF8\s0 uses | |
2528 | a variable number of bytes to represent a character, instead of just | |
2529 | one. You can learn more about Unicode at http://www.unicode.org/ | |
2530 | .Sh "How can I recognise a \s-1UTF8\s0 string?" | |
2531 | .IX Subsection "How can I recognise a UTF8 string?" | |
2532 | You can't. This is because \s-1UTF8\s0 data is stored in bytes just like | |
2533 | non\-UTF8 data. The Unicode character 200, (\f(CW0xC8\fR for you hex types) | |
2534 | capital E with a grave accent, is represented by the two bytes | |
2535 | \&\f(CW\*(C`v196.172\*(C'\fR. Unfortunately, the non-Unicode string \f(CW\*(C`chr(196).chr(172)\*(C'\fR | |
2536 | has that byte sequence as well. So you can't tell just by looking \- this | |
2537 | is what makes Unicode input an interesting problem. | |
2538 | .PP | |
2539 | The \s-1API\s0 function \f(CW\*(C`is_utf8_string\*(C'\fR can help; it'll tell you if a string | |
2540 | contains only valid \s-1UTF8\s0 characters. However, it can't do the work for | |
2541 | you. On a character-by-character basis, \f(CW\*(C`is_utf8_char\*(C'\fR will tell you | |
2542 | whether the current character in a string is valid \s-1UTF8\s0. | |
2543 | .Sh "How does \s-1UTF8\s0 represent Unicode characters?" | |
2544 | .IX Subsection "How does UTF8 represent Unicode characters?" | |
2545 | As mentioned above, \s-1UTF8\s0 uses a variable number of bytes to store a | |
2546 | character. Characters with values 1...128 are stored in one byte, just | |
2547 | like good ol' \s-1ASCII\s0. Character 129 is stored as \f(CW\*(C`v194.129\*(C'\fR; this | |
2548 | continues up to character 191, which is \f(CW\*(C`v194.191\*(C'\fR. Now we've run out of | |
2549 | bits (191 is binary \f(CW10111111\fR) so we move on; 192 is \f(CW\*(C`v195.128\*(C'\fR. And | |
2550 | so it goes on, moving to three bytes at character 2048. | |
2551 | .PP | |
2552 | Assuming you know you're dealing with a \s-1UTF8\s0 string, you can find out | |
2553 | how long the first character in it is with the \f(CW\*(C`UTF8SKIP\*(C'\fR macro: | |
2554 | .PP | |
2555 | .Vb 2 | |
2556 | \& char *utf = "\e305\e233\e340\e240\e201"; | |
2557 | \& I32 len; | |
2558 | .Ve | |
2559 | .PP | |
2560 | .Vb 3 | |
2561 | \& len = UTF8SKIP(utf); /* len is 2 here */ | |
2562 | \& utf += len; | |
2563 | \& len = UTF8SKIP(utf); /* len is 3 here */ | |
2564 | .Ve | |
2565 | .PP | |
2566 | Another way to skip over characters in a \s-1UTF8\s0 string is to use | |
2567 | \&\f(CW\*(C`utf8_hop\*(C'\fR, which takes a string and a number of characters to skip | |
2568 | over. You're on your own about bounds checking, though, so don't use it | |
2569 | lightly. | |
2570 | .PP | |
2571 | All bytes in a multi-byte \s-1UTF8\s0 character will have the high bit set, so | |
2572 | you can test if you need to do something special with this character | |
2573 | like this: | |
2574 | .PP | |
2575 | .Vb 1 | |
2576 | \& UV uv; | |
2577 | .Ve | |
2578 | .PP | |
2579 | .Vb 6 | |
2580 | \& if (utf & 0x80) | |
2581 | \& /* Must treat this as UTF8 */ | |
2582 | \& uv = utf8_to_uv(utf); | |
2583 | \& else | |
2584 | \& /* OK to treat this character as a byte */ | |
2585 | \& uv = *utf; | |
2586 | .Ve | |
2587 | .PP | |
2588 | You can also see in that example that we use \f(CW\*(C`utf8_to_uv\*(C'\fR to get the | |
2589 | value of the character; the inverse function \f(CW\*(C`uv_to_utf8\*(C'\fR is available | |
2590 | for putting a \s-1UV\s0 into \s-1UTF8:\s0 | |
2591 | .PP | |
2592 | .Vb 6 | |
2593 | \& if (uv > 0x80) | |
2594 | \& /* Must treat this as UTF8 */ | |
2595 | \& utf8 = uv_to_utf8(utf8, uv); | |
2596 | \& else | |
2597 | \& /* OK to treat this character as a byte */ | |
2598 | \& *utf8++ = uv; | |
2599 | .Ve | |
2600 | .PP | |
2601 | You \fBmust\fR convert characters to UVs using the above functions if | |
2602 | you're ever in a situation where you have to match \s-1UTF8\s0 and non\-UTF8 | |
2603 | characters. You may not skip over \s-1UTF8\s0 characters in this case. If you | |
2604 | do this, you'll lose the ability to match hi-bit non\-UTF8 characters; | |
2605 | for instance, if your \s-1UTF8\s0 string contains \f(CW\*(C`v196.172\*(C'\fR, and you skip | |
2606 | that character, you can never match a \f(CW\*(C`chr(200)\*(C'\fR in a non\-UTF8 string. | |
2607 | So don't do that! | |
2608 | .Sh "How does Perl store \s-1UTF8\s0 strings?" | |
2609 | .IX Subsection "How does Perl store UTF8 strings?" | |
2610 | Currently, Perl deals with Unicode strings and non-Unicode strings | |
2611 | slightly differently. If a string has been identified as being \s-1UTF\-8\s0 | |
2612 | encoded, Perl will set a flag in the \s-1SV\s0, \f(CW\*(C`SVf_UTF8\*(C'\fR. You can check and | |
2613 | manipulate this flag with the following macros: | |
2614 | .PP | |
2615 | .Vb 3 | |
2616 | \& SvUTF8(sv) | |
2617 | \& SvUTF8_on(sv) | |
2618 | \& SvUTF8_off(sv) | |
2619 | .Ve | |
2620 | .PP | |
2621 | This flag has an important effect on Perl's treatment of the string: if | |
2622 | Unicode data is not properly distinguished, regular expressions, | |
2623 | \&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`substr\*(C'\fR and other string handling operations will have | |
2624 | undesirable results. | |
2625 | .PP | |
2626 | The problem comes when you have, for instance, a string that isn't | |
2627 | flagged is \s-1UTF8\s0, and contains a byte sequence that could be \s-1UTF8\s0 \- | |
2628 | especially when combining non\-UTF8 and \s-1UTF8\s0 strings. | |
2629 | .PP | |
2630 | Never forget that the \f(CW\*(C`SVf_UTF8\*(C'\fR flag is separate to the \s-1PV\s0 value; you | |
2631 | need be sure you don't accidentally knock it off while you're | |
2632 | manipulating SVs. More specifically, you cannot expect to do this: | |
2633 | .PP | |
2634 | .Vb 4 | |
2635 | \& SV *sv; | |
2636 | \& SV *nsv; | |
2637 | \& STRLEN len; | |
2638 | \& char *p; | |
2639 | .Ve | |
2640 | .PP | |
2641 | .Vb 3 | |
2642 | \& p = SvPV(sv, len); | |
2643 | \& frobnicate(p); | |
2644 | \& nsv = newSVpvn(p, len); | |
2645 | .Ve | |
2646 | .PP | |
2647 | The \f(CW\*(C`char*\*(C'\fR string does not tell you the whole story, and you can't | |
2648 | copy or reconstruct an \s-1SV\s0 just by copying the string value. Check if the | |
2649 | old \s-1SV\s0 has the \s-1UTF8\s0 flag set, and act accordingly: | |
2650 | .PP | |
2651 | .Vb 5 | |
2652 | \& p = SvPV(sv, len); | |
2653 | \& frobnicate(p); | |
2654 | \& nsv = newSVpvn(p, len); | |
2655 | \& if (SvUTF8(sv)) | |
2656 | \& SvUTF8_on(nsv); | |
2657 | .Ve | |
2658 | .PP | |
2659 | In fact, your \f(CW\*(C`frobnicate\*(C'\fR function should be made aware of whether or | |
2660 | not it's dealing with \s-1UTF8\s0 data, so that it can handle the string | |
2661 | appropriately. | |
2662 | .Sh "How do I convert a string to \s-1UTF8\s0?" | |
2663 | .IX Subsection "How do I convert a string to UTF8?" | |
2664 | If you're mixing \s-1UTF8\s0 and non\-UTF8 strings, you might find it necessary | |
2665 | to upgrade one of the strings to \s-1UTF8\s0. If you've got an \s-1SV\s0, the easiest | |
2666 | way to do this is: | |
2667 | .PP | |
2668 | .Vb 1 | |
2669 | \& sv_utf8_upgrade(sv); | |
2670 | .Ve | |
2671 | .PP | |
2672 | However, you must not do this, for example: | |
2673 | .PP | |
2674 | .Vb 2 | |
2675 | \& if (!SvUTF8(left)) | |
2676 | \& sv_utf8_upgrade(left); | |
2677 | .Ve | |
2678 | .PP | |
2679 | If you do this in a binary operator, you will actually change one of the | |
2680 | strings that came into the operator, and, while it shouldn't be noticeable | |
2681 | by the end user, it can cause problems. | |
2682 | .PP | |
2683 | Instead, \f(CW\*(C`bytes_to_utf8\*(C'\fR will give you a UTF8\-encoded \fBcopy\fR of its | |
2684 | string argument. This is useful for having the data available for | |
2685 | comparisons and so on, without harming the original \s-1SV\s0. There's also | |
2686 | \&\f(CW\*(C`utf8_to_bytes\*(C'\fR to go the other way, but naturally, this will fail if | |
2687 | the string contains any characters above 255 that can't be represented | |
2688 | in a single byte. | |
2689 | .Sh "Is there anything else I need to know?" | |
2690 | .IX Subsection "Is there anything else I need to know?" | |
2691 | Not really. Just remember these things: | |
2692 | .IP "\(bu" 3 | |
2693 | There's no way to tell if a string is \s-1UTF8\s0 or not. You can tell if an \s-1SV\s0 | |
2694 | is \s-1UTF8\s0 by looking at is \f(CW\*(C`SvUTF8\*(C'\fR flag. Don't forget to set the flag if | |
2695 | something should be \s-1UTF8\s0. Treat the flag as part of the \s-1PV\s0, even though | |
2696 | it's not \- if you pass on the \s-1PV\s0 to somewhere, pass on the flag too. | |
2697 | .IP "\(bu" 3 | |
2698 | If a string is \s-1UTF8\s0, \fBalways\fR use \f(CW\*(C`utf8_to_uv\*(C'\fR to get at the value, | |
2699 | unless \f(CW\*(C`!(*s & 0x80)\*(C'\fR in which case you can use \f(CW*s\fR. | |
2700 | .IP "\(bu" 3 | |
2701 | When writing to a \s-1UTF8\s0 string, \fBalways\fR use \f(CW\*(C`uv_to_utf8\*(C'\fR, unless | |
2702 | \&\f(CW\*(C`uv < 0x80\*(C'\fR in which case you can use \f(CW\*(C`*s = uv\*(C'\fR. | |
2703 | .IP "\(bu" 3 | |
2704 | Mixing \s-1UTF8\s0 and non\-UTF8 strings is tricky. Use \f(CW\*(C`bytes_to_utf8\*(C'\fR to get | |
2705 | a new string which is \s-1UTF8\s0 encoded. There are tricks you can use to | |
2706 | delay deciding whether you need to use a \s-1UTF8\s0 string until you get to a | |
2707 | high character \- \f(CW\*(C`HALF_UPGRADE\*(C'\fR is one of those. | |
2708 | .SH "Custom Operators" | |
2709 | .IX Header "Custom Operators" | |
2710 | Custom operator support is a new experimental feature that allows you to | |
2711 | define your own ops. This is primarily to allow the building of | |
2712 | interpreters for other languages in the Perl core, but it also allows | |
2713 | optimizations through the creation of \*(L"macro\-ops\*(R" (ops which perform the | |
2714 | functions of multiple ops which are usually executed together, such as | |
2715 | \&\f(CW\*(C`gvsv, gvsv, add\*(C'\fR.) | |
2716 | .PP | |
2717 | This feature is implemented as a new op type, \f(CW\*(C`OP_CUSTOM\*(C'\fR. The Perl | |
2718 | core does not \*(L"know\*(R" anything special about this op type, and so it will | |
2719 | not be involved in any optimizations. This also means that you can | |
2720 | define your custom ops to be any op structure \- unary, binary, list and | |
2721 | so on \- you like. | |
2722 | .PP | |
2723 | It's important to know what custom operators won't do for you. They | |
2724 | won't let you add new syntax to Perl, directly. They won't even let you | |
2725 | add new keywords, directly. In fact, they won't change the way Perl | |
2726 | compiles a program at all. You have to do those changes yourself, after | |
2727 | Perl has compiled the program. You do this either by manipulating the op | |
2728 | tree using a \f(CW\*(C`CHECK\*(C'\fR block and the \f(CW\*(C`B::Generate\*(C'\fR module, or by adding | |
2729 | a custom peephole optimizer with the \f(CW\*(C`optimize\*(C'\fR module. | |
2730 | .PP | |
2731 | When you do this, you replace ordinary Perl ops with custom ops by | |
2732 | creating ops with the type \f(CW\*(C`OP_CUSTOM\*(C'\fR and the \f(CW\*(C`pp_addr\*(C'\fR of your own | |
2733 | \&\s-1PP\s0 function. This should be defined in \s-1XS\s0 code, and should look like | |
2734 | the \s-1PP\s0 ops in \f(CW\*(C`pp_*.c\*(C'\fR. You are responsible for ensuring that your op | |
2735 | takes the appropriate number of values from the stack, and you are | |
2736 | responsible for adding stack marks if necessary. | |
2737 | .PP | |
2738 | You should also \*(L"register\*(R" your op with the Perl interpreter so that it | |
2739 | can produce sensible error and warning messages. Since it is possible to | |
2740 | have multiple custom ops within the one \*(L"logical\*(R" op type \f(CW\*(C`OP_CUSTOM\*(C'\fR, | |
2741 | Perl uses the value of \f(CW\*(C`o\->op_ppaddr\*(C'\fR as a key into the | |
2742 | \&\f(CW\*(C`PL_custom_op_descs\*(C'\fR and \f(CW\*(C`PL_custom_op_names\*(C'\fR hashes. This means you | |
2743 | need to enter a name and description for your op at the appropriate | |
2744 | place in the \f(CW\*(C`PL_custom_op_names\*(C'\fR and \f(CW\*(C`PL_custom_op_descs\*(C'\fR hashes. | |
2745 | .PP | |
2746 | Forthcoming versions of \f(CW\*(C`B::Generate\*(C'\fR (version 1.0 and above) should | |
2747 | directly support the creation of custom ops by name; \f(CW\*(C`Opcodes::Custom\*(C'\fR | |
2748 | will provide functions which make it trivial to \*(L"register\*(R" custom ops to | |
2749 | the Perl interpreter. | |
2750 | .SH "AUTHORS" | |
2751 | .IX Header "AUTHORS" | |
2752 | Until May 1997, this document was maintained by Jeff Okamoto | |
2753 | <okamoto@corp.hp.com>. It is now maintained as part of Perl | |
2754 | itself by the Perl 5 Porters <perl5\-porters@perl.org>. | |
2755 | .PP | |
2756 | With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, | |
2757 | Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil | |
2758 | Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, | |
2759 | Stephen McCamant, and Gurusamy Sarathy. | |
2760 | .PP | |
2761 | \&\s-1API\s0 Listing originally by Dean Roehrich <roehrich@cray.com>. | |
2762 | .PP | |
2763 | Modifications to autogenerate the \s-1API\s0 listing (perlapi) by Benjamin | |
2764 | Stuhl. | |
2765 | .SH "SEE ALSO" | |
2766 | .IX Header "SEE ALSO" | |
2767 | \&\fIperlapi\fR\|(1), \fIperlintern\fR\|(1), \fIperlxs\fR\|(1), \fIperlembed\fR\|(1) |