Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlguts - Perl's Internal Functions |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This document attempts to describe some of the internal functions of the |
8 | Perl executable. It is far from complete and probably contains many errors. |
9 | Please refer any questions or comments to the author below. |
10 | |
11 | =head1 Datatypes |
12 | |
13 | Perl has three typedefs that handle Perl's three main data types: |
14 | |
15 | SV Scalar Value |
16 | AV Array Value |
17 | HV Hash Value |
18 | |
d1b91892 |
19 | Each typedef has specific routines that manipulate the various data types. |
a0d0e21e |
20 | |
21 | =head2 What is an "IV"? |
22 | |
23 | Perl uses a special typedef IV which is large enough to hold either an |
24 | integer or a pointer. |
25 | |
d1b91892 |
26 | Perl also uses two special typedefs, I32 and I16, which will always be at |
27 | least 32-bits and 16-bits long, respectively. |
a0d0e21e |
28 | |
29 | =head2 Working with SV's |
30 | |
31 | An SV can be created and loaded with one command. There are four types of |
32 | values that can be loaded: an integer value (IV), a double (NV), a string, |
33 | (PV), and another scalar (SV). |
34 | |
35 | The four routines are: |
36 | |
37 | SV* newSViv(IV); |
38 | SV* newSVnv(double); |
39 | SV* newSVpv(char*, int); |
40 | SV* newSVsv(SV*); |
41 | |
42 | To change the value of an *already-existing* scalar, there are five routines: |
43 | |
44 | void sv_setiv(SV*, IV); |
45 | void sv_setnv(SV*, double); |
46 | void sv_setpvn(SV*, char*, int) |
47 | void sv_setpv(SV*, char*); |
48 | void sv_setsv(SV*, SV*); |
49 | |
50 | Notice that you can choose to specify the length of the string to be |
d1b91892 |
51 | assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to |
52 | calculate the length by using C<sv_setpv> or specifying 0 as the second |
53 | argument to C<newSVpv>. Be warned, though, that Perl will determine the |
a0d0e21e |
54 | string's length by using C<strlen>, which depends on the string terminating |
55 | with a NUL character. |
56 | |
57 | To access the actual value that an SV points to, you can use the macros: |
58 | |
59 | SvIV(SV*) |
60 | SvNV(SV*) |
61 | SvPV(SV*, STRLEN len) |
62 | |
63 | which will automatically coerce the actual scalar type into an IV, double, |
64 | or string. |
65 | |
66 | In the C<SvPV> macro, the length of the string returned is placed into the |
67 | variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not |
68 | care what the length of the data is, use the global variable C<na>. Remember, |
69 | however, that Perl allows arbitrary strings of data that may both contain |
70 | NUL's and not be terminated by a NUL. |
71 | |
72 | If you simply want to know if the scalar value is TRUE, you can use: |
73 | |
74 | SvTRUE(SV*) |
75 | |
76 | Although Perl will automatically grow strings for you, if you need to force |
77 | Perl to allocate more memory for your SV, you can use the macro |
78 | |
79 | SvGROW(SV*, STRLEN newlen) |
80 | |
81 | which will determine if more memory needs to be allocated. If so, it will |
82 | call the function C<sv_grow>. Note that C<SvGROW> can only increase, not |
83 | decrease, the allocated memory of an SV. |
84 | |
85 | If you have an SV and want to know what kind of data Perl thinks is stored |
86 | in it, you can use the following macros to check the type of SV you have. |
87 | |
88 | SvIOK(SV*) |
89 | SvNOK(SV*) |
90 | SvPOK(SV*) |
91 | |
92 | You can get and set the current length of the string stored in an SV with |
93 | the following macros: |
94 | |
95 | SvCUR(SV*) |
96 | SvCUR_set(SV*, I32 val) |
97 | |
98 | But note that these are valid only if C<SvPOK()> is true. |
99 | |
d1b91892 |
100 | If you want to append something to the end of string stored in an C<SV*>, |
101 | you can use the following functions: |
102 | |
103 | void sv_catpv(SV*, char*); |
104 | void sv_catpvn(SV*, char*, int); |
105 | void sv_catsv(SV*, SV*); |
106 | |
107 | The first function calculates the length of the string to be appended by |
108 | using C<strlen>. In the second, you specify the length of the string |
109 | yourself. The third function extends the string stored in the first SV |
110 | with the string stored in the second SV. It also forces the second SV to |
111 | be interpreted as a string. |
112 | |
a0d0e21e |
113 | If you know the name of a scalar variable, you can get a pointer to its SV |
114 | by using the following: |
115 | |
116 | SV* perl_get_sv("varname", FALSE); |
117 | |
118 | This returns NULL if the variable does not exist. |
119 | |
d1b91892 |
120 | If you want to know if this variable (or any other SV) is actually C<defined>, |
a0d0e21e |
121 | you can call: |
122 | |
123 | SvOK(SV*) |
124 | |
125 | The scalar C<undef> value is stored in an SV instance called C<sv_undef>. Its |
126 | address can be used whenever an C<SV*> is needed. |
127 | |
128 | There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean |
129 | TRUE and FALSE values, respectively. Like C<sv_undef>, their addresses can |
130 | be used whenever an C<SV*> is needed. |
131 | |
132 | Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>. |
133 | Take this code: |
134 | |
135 | SV* sv = (SV*) 0; |
136 | if (I-am-to-return-a-real-value) { |
137 | sv = sv_2mortal(newSViv(42)); |
138 | } |
139 | sv_setsv(ST(0), sv); |
140 | |
141 | This code tries to return a new SV (which contains the value 42) if it should |
142 | return a real value, or undef otherwise. Instead it has returned a null |
143 | pointer which, somewhere down the line, will cause a segmentation violation, |
144 | or just weird results. Change the zero to C<&sv_undef> in the first line and |
145 | all will be well. |
146 | |
147 | To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this |
148 | call is not necessary. See the section on B<MORTALITY>. |
149 | |
d1b91892 |
150 | =head2 What's Really Stored in an SV? |
a0d0e21e |
151 | |
152 | Recall that the usual method of determining the type of scalar you have is |
d1b91892 |
153 | to use C<Sv*OK> macros. Since a scalar can be both a number and a string, |
154 | usually these macros will always return TRUE and calling the C<Sv*V> |
a0d0e21e |
155 | macros will do the appropriate conversion of string to integer/double or |
156 | integer/double to string. |
157 | |
158 | If you I<really> need to know if you have an integer, double, or string |
159 | pointer in an SV, you can use the following three macros instead: |
160 | |
161 | SvIOKp(SV*) |
162 | SvNOKp(SV*) |
163 | SvPOKp(SV*) |
164 | |
165 | These will tell you if you truly have an integer, double, or string pointer |
d1b91892 |
166 | stored in your SV. The "p" stands for private. |
a0d0e21e |
167 | |
d1b91892 |
168 | In general, though, it's best to just use the C<Sv*V> macros. |
a0d0e21e |
169 | |
170 | =head2 Working with AV's |
171 | |
172 | There are two ways to create and load an AV. The first method just creates |
173 | an empty AV: |
174 | |
175 | AV* newAV(); |
176 | |
177 | The second method both creates the AV and initially populates it with SV's: |
178 | |
179 | AV* av_make(I32 num, SV **ptr); |
180 | |
d1b91892 |
181 | The second argument points to an array containing C<num> C<SV*>'s. Once the |
182 | AV has been created, the SV's can be destroyed, if so desired. |
a0d0e21e |
183 | |
184 | Once the AV has been created, the following operations are possible on AV's: |
185 | |
186 | void av_push(AV*, SV*); |
187 | SV* av_pop(AV*); |
188 | SV* av_shift(AV*); |
189 | void av_unshift(AV*, I32 num); |
190 | |
191 | These should be familiar operations, with the exception of C<av_unshift>. |
192 | This routine adds C<num> elements at the front of the array with the C<undef> |
193 | value. You must then use C<av_store> (described below) to assign values |
194 | to these new elements. |
195 | |
196 | Here are some other functions: |
197 | |
d1b91892 |
198 | I32 av_len(AV*); /* Returns highest index value in array */ |
a0d0e21e |
199 | |
200 | SV** av_fetch(AV*, I32 key, I32 lval); |
d1b91892 |
201 | /* Fetches value at key offset, but it stores an undef value |
202 | at the offset if lval is non-zero */ |
a0d0e21e |
203 | SV** av_store(AV*, I32 key, SV* val); |
204 | /* Stores val at offset key */ |
205 | |
d1b91892 |
206 | Take note that these two functions return C<SV**>'s, not C<SV*>'s. |
207 | |
a0d0e21e |
208 | void av_clear(AV*); |
209 | /* Clear out all elements, but leave the array */ |
210 | void av_undef(AV*); |
211 | /* Undefines the array, removing all elements */ |
212 | |
213 | If you know the name of an array variable, you can get a pointer to its AV |
214 | by using the following: |
215 | |
216 | AV* perl_get_av("varname", FALSE); |
217 | |
218 | This returns NULL if the variable does not exist. |
219 | |
220 | =head2 Working with HV's |
221 | |
222 | To create an HV, you use the following routine: |
223 | |
224 | HV* newHV(); |
225 | |
226 | Once the HV has been created, the following operations are possible on HV's: |
227 | |
228 | SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash); |
229 | SV** hv_fetch(HV*, char* key, U32 klen, I32 lval); |
230 | |
231 | The C<klen> parameter is the length of the key being passed in. The C<val> |
232 | argument contains the SV pointer to the scalar being stored, and C<hash> is |
233 | the pre-computed hash value (zero if you want C<hv_store> to calculate it |
234 | for you). The C<lval> parameter indicates whether this fetch is actually a |
235 | part of a store operation. |
236 | |
237 | Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just |
238 | C<SV*>. In order to access the scalar value, you must first dereference |
239 | the return value. However, you should check to make sure that the return |
240 | value is not NULL before dereferencing it. |
241 | |
242 | These two functions check if a hash table entry exists, and deletes it. |
243 | |
244 | bool hv_exists(HV*, char* key, U32 klen); |
d1b91892 |
245 | SV* hv_delete(HV*, char* key, U32 klen, I32 flags); |
a0d0e21e |
246 | |
247 | And more miscellaneous functions: |
248 | |
249 | void hv_clear(HV*); |
250 | /* Clears all entries in hash table */ |
251 | void hv_undef(HV*); |
252 | /* Undefines the hash table */ |
253 | |
d1b91892 |
254 | Perl keeps the actual data in linked list of structures with a typedef of HE. |
255 | These contain the actual key and value pointers (plus extra administrative |
256 | overhead). The key is a string pointer; the value is an C<SV*>. However, |
257 | once you have an C<HE*>, to get the actual key and value, use the routines |
258 | specified below. |
259 | |
a0d0e21e |
260 | I32 hv_iterinit(HV*); |
261 | /* Prepares starting point to traverse hash table */ |
262 | HE* hv_iternext(HV*); |
263 | /* Get the next entry, and return a pointer to a |
264 | structure that has both the key and value */ |
265 | char* hv_iterkey(HE* entry, I32* retlen); |
266 | /* Get the key from an HE structure and also return |
267 | the length of the key string */ |
268 | SV* hv_iterval(HV*, HE* entry); |
269 | /* Return a SV pointer to the value of the HE |
270 | structure */ |
d1b91892 |
271 | SV* hv_iternextsv(HV*, char** key, I32* retlen); |
272 | /* This convenience routine combines hv_iternext, |
273 | hv_iterkey, and hv_iterval. The key and retlen |
274 | arguments are return values for the key and its |
275 | length. The value is returned in the SV* argument */ |
a0d0e21e |
276 | |
277 | If you know the name of a hash variable, you can get a pointer to its HV |
278 | by using the following: |
279 | |
280 | HV* perl_get_hv("varname", FALSE); |
281 | |
282 | This returns NULL if the variable does not exist. |
283 | |
284 | The hash algorithm, for those who are interested, is: |
285 | |
286 | i = klen; |
287 | hash = 0; |
288 | s = key; |
289 | while (i--) |
290 | hash = hash * 33 + *s++; |
291 | |
d1b91892 |
292 | =head1 Creating New Variables |
293 | |
294 | To create a new Perl variable, which can be accessed from your Perl script, |
295 | use the following routines, depending on the variable type. |
296 | |
297 | SV* perl_get_sv("varname", TRUE); |
298 | AV* perl_get_av("varname", TRUE); |
299 | HV* perl_get_hv("varname", TRUE); |
300 | |
301 | Notice the use of TRUE as the second parameter. The new variable can now |
302 | be set, using the routines appropriate to the data type. |
303 | |
304 | There are additional bits that may be OR'ed with the TRUE argument to enable |
305 | certain extra features. Those bits are: |
306 | |
307 | 0x02 Marks the variable as multiply defined, thus preventing the |
308 | "Indentifier <varname> used only once: possible typo" warning. |
309 | 0x04 Issues a "Had to create <varname> unexpectedly" warning if |
310 | the variable didn't actually exist. This is useful if |
311 | you expected the variable to already exist and want to propagate |
312 | this warning back to the user. |
313 | |
314 | If the C<varname> argument does not contain a package specifier, it is |
315 | created in the current package. |
316 | |
a0d0e21e |
317 | =head2 References |
318 | |
d1b91892 |
319 | References are a special type of scalar that point to other data types |
320 | (including references). |
a0d0e21e |
321 | |
322 | To create a reference, use the following command: |
323 | |
d1b91892 |
324 | SV* newRV((SV*) thing); |
a0d0e21e |
325 | |
d1b91892 |
326 | The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. Once |
327 | you have a reference, you can use the following macro to dereference the |
328 | reference: |
a0d0e21e |
329 | |
330 | SvRV(SV*) |
331 | |
332 | then call the appropriate routines, casting the returned C<SV*> to either an |
d1b91892 |
333 | C<AV*> or C<HV*>, if required. |
a0d0e21e |
334 | |
d1b91892 |
335 | To determine if an SV is a reference, you can use the following macro: |
a0d0e21e |
336 | |
337 | SvROK(SV*) |
338 | |
d1b91892 |
339 | To actually discover what the reference refers to, you must use the following |
340 | macro and then check the value returned. |
341 | |
342 | SvTYPE(SvRV(SV*)) |
343 | |
344 | The most useful types that will be returned are: |
345 | |
346 | SVt_IV Scalar |
347 | SVt_NV Scalar |
348 | SVt_PV Scalar |
349 | SVt_PVAV Array |
350 | SVt_PVHV Hash |
351 | SVt_PVCV Code |
352 | SVt_PVMG Blessed Scalar |
353 | |
354 | =head1 XSUB's and the Argument Stack |
a0d0e21e |
355 | |
356 | The XSUB mechanism is a simple way for Perl programs to access C subroutines. |
357 | An XSUB routine will have a stack that contains the arguments from the Perl |
358 | program, and a way to map from the Perl data structures to a C equivalent. |
359 | |
360 | The stack arguments are accessible through the C<ST(n)> macro, which returns |
361 | the C<n>'th stack argument. Argument 0 is the first argument passed in the |
362 | Perl subroutine call. These arguments are C<SV*>, and can be used anywhere |
363 | an C<SV*> is used. |
364 | |
365 | Most of the time, output from the C routine can be handled through use of |
366 | the RETVAL and OUTPUT directives. However, there are some cases where the |
367 | argument stack is not already long enough to handle all the return values. |
368 | An example is the POSIX tzname() call, which takes no arguments, but returns |
369 | two, the local timezone's standard and summer time abbreviations. |
370 | |
371 | To handle this situation, the PPCODE directive is used and the stack is |
372 | extended using the macro: |
373 | |
374 | EXTEND(sp, num); |
375 | |
376 | where C<sp> is the stack pointer, and C<num> is the number of elements the |
377 | stack should be extended by. |
378 | |
379 | Now that there is room on the stack, values can be pushed on it using the |
380 | macros to push IV's, doubles, strings, and SV pointers respectively: |
381 | |
382 | PUSHi(IV) |
383 | PUSHn(double) |
384 | PUSHp(char*, I32) |
385 | PUSHs(SV*) |
386 | |
387 | And now the Perl program calling C<tzname>, the two values will be assigned |
388 | as in: |
389 | |
390 | ($standard_abbrev, $summer_abbrev) = POSIX::tzname; |
391 | |
392 | An alternate (and possibly simpler) method to pushing values on the stack is |
393 | to use the macros: |
394 | |
395 | XPUSHi(IV) |
396 | XPUSHn(double) |
397 | XPUSHp(char*, I32) |
398 | XPUSHs(SV*) |
399 | |
400 | These macros automatically adjust the stack for you, if needed. |
401 | |
d1b91892 |
402 | For more information, consult L<perlapi>. |
403 | |
a0d0e21e |
404 | =head1 Mortality |
405 | |
406 | In Perl, values are normally "immortal" -- that is, they are not freed unless |
407 | explicitly done so (via the Perl C<undef> call or other routines in Perl |
408 | itself). |
409 | |
d1b91892 |
410 | Add cruft about reference counts. |
411 | |
a0d0e21e |
412 | In the above example with C<tzname>, we needed to create two new SV's to push |
413 | onto the argument stack, that being the two strings. However, we don't want |
414 | these new SV's to stick around forever because they will eventually be |
415 | copied into the SV's that hold the two scalar variables. |
416 | |
417 | An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal" |
418 | SV, AV, or HV, but is only valid in the "current context". When the Perl |
419 | interpreter leaves the current context, the mortal SV, AV, or HV is |
420 | automatically freed. Generally the "current context" means a single |
421 | Perl statement. |
422 | |
423 | To create a mortal variable, use the functions: |
424 | |
425 | SV* sv_newmortal() |
426 | SV* sv_2mortal(SV*) |
427 | SV* sv_mortalcopy(SV*) |
428 | |
429 | The first call creates a mortal SV, the second converts an existing SV to |
430 | a mortal SV, the third creates a mortal copy of an existing SV. |
431 | |
432 | The mortal routines are not just for SV's -- AV's and HV's can be made mortal |
433 | by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or |
434 | C<sv_mortalcopy> routines. |
435 | |
d1b91892 |
436 | From Ilya: |
437 | Beware that the sv_2mortal() call is eventually equivalent to |
438 | svREFCNT_dec(). A value can happily be mortal in two different contexts, |
439 | and it will be svREFCNT_dec()ed twice, once on exit from these |
440 | contexts. It can also be mortal twice in the same context. This means |
441 | that you should be very careful to make a value mortal exactly as many |
442 | times as it is needed. The value that go to the Perl stack I<should> |
443 | be mortal. |
a0d0e21e |
444 | |
d1b91892 |
445 | You should be careful about creating mortal variables. It is possible for |
446 | strange things to happen should you make the same value mortal within |
447 | multiple contexts. |
a0d0e21e |
448 | |
449 | =head1 Stashes and Objects |
450 | |
451 | A stash is a hash table (associative array) that contains all of the |
452 | different objects that are contained within a package. Each key of the |
d1b91892 |
453 | stash is a symbol name (shared by all the different types of objects |
454 | that have the same name), and each value in the hash table is called a |
455 | GV (for Glob Value). This GV in turn contains references to the various |
456 | objects of that name, including (but not limited to) the following: |
a0d0e21e |
457 | |
458 | Scalar Value |
459 | Array Value |
460 | Hash Value |
461 | File Handle |
462 | Directory Handle |
463 | Format |
464 | Subroutine |
465 | |
d1b91892 |
466 | Perl stores various stashes in a separate GV structure (for global |
467 | variable) but represents them with an HV structure. The keys in this |
468 | larger GV are the various package names; the values are the C<GV*>'s |
469 | which are stashes. It may help to think of a stash purely as an HV, |
470 | and that the term "GV" means the global variable hash. |
a0d0e21e |
471 | |
d1b91892 |
472 | To get the stash pointer for a particular package, use the function: |
a0d0e21e |
473 | |
474 | HV* gv_stashpv(char* name, I32 create) |
475 | HV* gv_stashsv(SV*, I32 create) |
476 | |
477 | The first function takes a literal string, the second uses the string stored |
d1b91892 |
478 | in the SV. Remember that a stash is just a hash table, so you get back an |
479 | C<HV*>. |
a0d0e21e |
480 | |
481 | The name that C<gv_stash*v> wants is the name of the package whose symbol table |
482 | you want. The default package is called C<main>. If you have multiply nested |
d1b91892 |
483 | packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl |
484 | language itself. |
a0d0e21e |
485 | |
486 | Alternately, if you have an SV that is a blessed reference, you can find |
487 | out the stash pointer by using: |
488 | |
489 | HV* SvSTASH(SvRV(SV*)); |
490 | |
491 | then use the following to get the package name itself: |
492 | |
493 | char* HvNAME(HV* stash); |
494 | |
495 | If you need to return a blessed value to your Perl script, you can use the |
496 | following function: |
497 | |
498 | SV* sv_bless(SV*, HV* stash) |
499 | |
500 | where the first argument, an C<SV*>, must be a reference, and the second |
501 | argument is a stash. The returned C<SV*> can now be used in the same way |
502 | as any other SV. |
503 | |
d1b91892 |
504 | For more information on references and blessings, consult L<perlref>. |
505 | |
a0d0e21e |
506 | =head1 Magic |
507 | |
d1b91892 |
508 | [This section still under construction. Ignore everything here. Post no |
509 | bills. Everything not permitted is forbidden.] |
510 | |
511 | # Version 6, 1995/1/27 |
512 | |
513 | Any SV may be magical, that is, it has special features that a normal |
514 | SV does not have. These features are stored in the SV structure in a |
515 | linked list of C<struct magic>'s, typedef'ed to C<MAGIC>. |
516 | |
517 | struct magic { |
518 | MAGIC* mg_moremagic; |
519 | MGVTBL* mg_virtual; |
520 | U16 mg_private; |
521 | char mg_type; |
522 | U8 mg_flags; |
523 | SV* mg_obj; |
524 | char* mg_ptr; |
525 | I32 mg_len; |
526 | }; |
527 | |
528 | Note this is current as of patchlevel 0, and could change at any time. |
529 | |
530 | =head2 Assigning Magic |
531 | |
532 | Perl adds magic to an SV using the sv_magic function: |
533 | |
534 | void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen); |
535 | |
536 | The C<sv> argument is a pointer to the SV that is to acquire a new magical |
537 | feature. |
538 | |
539 | If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to |
540 | set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding |
541 | it to the beginning of the linked list of magical features. Any prior |
542 | entry of the same type of magic is deleted. Note that this can be |
543 | overriden, and multiple instances of the same type of magic can be |
544 | associated with an SV. |
545 | |
546 | The C<name> and C<namlem> arguments are used to associate a string with |
547 | the magic, typically the name of a variable. C<namlem> is stored in the |
548 | C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd |
549 | copy of the name is stored in C<mg_ptr> field. |
550 | |
551 | The sv_magic function uses C<how> to determine which, if any, predefined |
552 | "Magic Virtual Table" should be assigned to the C<mg_virtual> field. |
553 | See the "Magic Virtual Table" section below. |
554 | |
555 | The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC> |
556 | structure. If it is not the same as the C<sv> argument, the reference |
557 | count of the C<obj> object is incremented. If it is the same, or if |
558 | the C<how> argument is "#", or if it is a null pointer, then C<obj> is |
559 | merely stored, without the reference count being incremented. |
560 | |
561 | =head2 Magic Virtual Tables |
562 | |
563 | The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a |
564 | C<MGVTBL>, which is a structure of function pointers and stands for |
565 | "Magic Virtual Table" to handle the various operations that might be |
566 | applied to that variable. |
567 | |
568 | The C<MGVTBL> has five pointers to the following routine types: |
569 | |
570 | int (*svt_get)(SV* sv, MAGIC* mg); |
571 | int (*svt_set)(SV* sv, MAGIC* mg); |
572 | U32 (*svt_len)(SV* sv, MAGIC* mg); |
573 | int (*svt_clear)(SV* sv, MAGIC* mg); |
574 | int (*svt_free)(SV* sv, MAGIC* mg); |
575 | |
576 | This MGVTBL structure is set at compile-time in C<perl.h> and there are |
577 | currently 19 types (or 21 with overloading turned on). These different |
578 | structures contain pointers to various routines that perform additional |
579 | actions depending on which function is being called. |
580 | |
581 | Function pointer Action taken |
582 | ---------------- ------------ |
583 | svt_get Do something after the value of the SV is retrieved. |
584 | svt_set Do something after the SV is assigned a value. |
585 | svt_len Report on the SV's length. |
586 | svt_clear Clear something the SV represents. |
587 | svt_free Free any extra storage associated with the SV. |
588 | |
589 | For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds |
590 | to an C<mg_type> of '\0') contains: |
591 | |
592 | { magic_get, magic_set, magic_len, 0, 0 } |
593 | |
594 | Thus, when an SV is determined to be magical and of type '\0', if a get |
595 | operation is being performed, the routine C<magic_get> is called. All |
596 | the various routines for the various magical types begin with C<magic_>. |
597 | |
598 | The current kinds of Magic Virtual Tables are: |
599 | |
600 | mg_type MGVTBL Type of magicalness |
601 | ------- ------ ------------------- |
602 | \0 vtbl_sv Regexp??? |
603 | A vtbl_amagic Operator Overloading |
604 | a vtbl_amagicelem Operator Overloading |
605 | c 0 Used in Operator Overloading |
606 | B vtbl_bm Boyer-Moore??? |
607 | E vtbl_env %ENV hash |
608 | e vtbl_envelem %ENV hash element |
609 | g vtbl_mglob Regexp /g flag??? |
610 | I vtbl_isa @ISA array |
611 | i vtbl_isaelem @ISA array element |
612 | L 0 (but sets RMAGICAL) Perl Module/Debugger??? |
613 | l vtbl_dbline Debugger? |
614 | P vtbl_pack Tied Array or Hash |
615 | p vtbl_packelem Tied Array or Hash element |
616 | q vtbl_packelem Tied Scalar or Handle |
617 | S vtbl_sig Signal Hash |
618 | s vtbl_sigelem Signal Hash element |
619 | t vtbl_taint Taintedness |
620 | U vtbl_uvar ??? |
621 | v vtbl_vec Vector |
622 | x vtbl_substr Substring??? |
623 | * vtbl_glob GV??? |
624 | # vtbl_arylen Array Length |
625 | . vtbl_pos $. scalar variable |
626 | ~ Reserved for extensions, but multiple extensions may clash |
627 | |
628 | When an upper-case and lower-case letter both exist in the table, then the |
629 | upper-case letter is used to represent some kind of composite type (a list |
630 | or a hash), and the lower-case letter is used to represent an element of |
631 | that composite type. |
632 | |
633 | =head2 Finding Magic |
634 | |
635 | MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */ |
636 | |
637 | This routine returns a pointer to the C<MAGIC> structure stored in the SV. |
638 | If the SV does not have that magical feature, C<NULL> is returned. Also, |
639 | if the SV is not of type SVt_PVMG, Perl may core-dump. |
640 | |
641 | int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen); |
642 | |
643 | This routine checks to see what types of magic C<sv> has. If the mg_type |
644 | field is an upper-case letter, then the mg_obj is copied to C<nsv>, but |
645 | the mg_type field is changed to be the lower-case letter. |
a0d0e21e |
646 | |
647 | =head1 Double-Typed SV's |
648 | |
649 | Scalar variables normally contain only one type of value, an integer, |
650 | double, pointer, or reference. Perl will automatically convert the |
651 | actual scalar data from the stored type into the requested type. |
652 | |
653 | Some scalar variables contain more than one type of scalar data. For |
654 | example, the variable C<$!> contains either the numeric value of C<errno> |
d1b91892 |
655 | or its string equivalent from either C<strerror> or C<sys_errlist[]>. |
a0d0e21e |
656 | |
657 | To force multiple data values into an SV, you must do two things: use the |
658 | C<sv_set*v> routines to add the additional scalar type, then set a flag |
659 | so that Perl will believe it contains more than one type of data. The |
660 | four macros to set the flags are: |
661 | |
662 | SvIOK_on |
663 | SvNOK_on |
664 | SvPOK_on |
665 | SvROK_on |
666 | |
667 | The particular macro you must use depends on which C<sv_set*v> routine |
668 | you called first. This is because every C<sv_set*v> routine turns on |
669 | only the bit for the particular type of data being set, and turns off |
670 | all the rest. |
671 | |
672 | For example, to create a new Perl variable called "dberror" that contains |
673 | both the numeric and descriptive string error values, you could use the |
674 | following code: |
675 | |
676 | extern int dberror; |
677 | extern char *dberror_list; |
678 | |
679 | SV* sv = perl_get_sv("dberror", TRUE); |
680 | sv_setiv(sv, (IV) dberror); |
681 | sv_setpv(sv, dberror_list[dberror]); |
682 | SvIOK_on(sv); |
683 | |
684 | If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the |
685 | macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>. |
686 | |
687 | =head1 Calling Perl Routines from within C Programs |
688 | |
689 | There are four routines that can be used to call a Perl subroutine from |
690 | within a C program. These four are: |
691 | |
692 | I32 perl_call_sv(SV*, I32); |
693 | I32 perl_call_pv(char*, I32); |
694 | I32 perl_call_method(char*, I32); |
695 | I32 perl_call_argv(char*, I32, register char**); |
696 | |
d1b91892 |
697 | The routine most often used is C<perl_call_sv>. The C<SV*> argument |
698 | contains either the name of the Perl subroutine to be called, or a |
699 | reference to the subroutine. The second argument consists of flags |
700 | that control the context in which the subroutine is called, whether |
701 | or not the subroutine is being passed arguments, how errors should be |
702 | trapped, and how to treat return values. |
a0d0e21e |
703 | |
704 | All four routines return the number of arguments that the subroutine returned |
705 | on the Perl stack. |
706 | |
d1b91892 |
707 | When using any of these routines (except C<perl_call_argv>), the programmer |
708 | must manipulate the Perl stack. These include the following macros and |
709 | functions: |
a0d0e21e |
710 | |
711 | dSP |
712 | PUSHMARK() |
713 | PUTBACK |
714 | SPAGAIN |
715 | ENTER |
716 | SAVETMPS |
717 | FREETMPS |
718 | LEAVE |
719 | XPUSH*() |
720 | |
721 | For more information, consult L<perlcall>. |
722 | |
723 | =head1 Memory Allocation |
724 | |
d1b91892 |
725 | It is strongly suggested that you use the version of malloc that is distributed |
726 | with Perl. It keeps pools of various sizes of unallocated memory in order to |
727 | more quickly satisfy allocation requests. |
728 | However, on some platforms, it may cause spurious malloc or free errors. |
729 | |
730 | New(x, pointer, number, type); |
731 | Newc(x, pointer, number, type, cast); |
732 | Newz(x, pointer, number, type); |
733 | |
734 | These three macros are used to initially allocate memory. The first argument |
735 | C<x> was a "magic cookie" that was used to keep track of who called the macro, |
736 | to help when debugging memory problems. However, the current code makes no |
737 | use of this feature (Larry has switched to using a run-time memory checker), |
738 | so this argument can be any number. |
739 | |
740 | The second argument C<pointer> will point to the newly allocated memory. |
741 | The third and fourth arguments C<number> and C<type> specify how many of |
742 | the specified type of data structure should be allocated. The argument |
743 | C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>, |
744 | should be used if the C<pointer> argument is different from the C<type> |
745 | argument. |
746 | |
747 | Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero> |
748 | to zero out all the newly allocated memory. |
749 | |
750 | Renew(pointer, number, type); |
751 | Renewc(pointer, number, type, cast); |
752 | Safefree(pointer) |
753 | |
754 | These three macros are used to change a memory buffer size or to free a |
755 | piece of memory no longer needed. The arguments to C<Renew> and C<Renewc> |
756 | match those of C<New> and C<Newc> with the exception of not needing the |
757 | "magic cookie" argument. |
758 | |
759 | Move(source, dest, number, type); |
760 | Copy(source, dest, number, type); |
761 | Zero(dest, number, type); |
762 | |
763 | These three macros are used to move, copy, or zero out previously allocated |
764 | memory. The C<source> and C<dest> arguments point to the source and |
765 | destination starting points. Perl will move, copy, or zero out C<number> |
766 | instances of the size of the C<type> data structure (using the C<sizeof> |
767 | function). |
a0d0e21e |
768 | |
769 | =head1 AUTHOR |
770 | |
771 | Jeff Okamoto <okamoto@corp.hp.com> |
772 | |
773 | With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, |
d1b91892 |
774 | Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil |
775 | Bowers, Matthew Green, Tim Bunce, and Spider Boardman. |
a0d0e21e |
776 | |
777 | =head1 DATE |
778 | |
d1b91892 |
779 | Version 19: 1995/4/26 |