This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
This is patch.2b1f to perl5.002beta1.
[perl5.git] / pod / perlguts.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlguts - Perl's Internal Functions
4
5=head1 DESCRIPTION
6
7This document attempts to describe some of the internal functions of the
8Perl executable. It is far from complete and probably contains many errors.
9Please refer any questions or comments to the author below.
10
11=head1 Datatypes
12
13Perl 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 19Each typedef has specific routines that manipulate the various data types.
a0d0e21e
LW
20
21=head2 What is an "IV"?
22
23Perl uses a special typedef IV which is large enough to hold either an
24integer or a pointer.
25
d1b91892
AD
26Perl also uses two special typedefs, I32 and I16, which will always be at
27least 32-bits and 16-bits long, respectively.
a0d0e21e
LW
28
29=head2 Working with SV's
30
31An SV can be created and loaded with one command. There are four types of
32values that can be loaded: an integer value (IV), a double (NV), a string,
33(PV), and another scalar (SV).
34
35The four routines are:
36
37 SV* newSViv(IV);
38 SV* newSVnv(double);
39 SV* newSVpv(char*, int);
40 SV* newSVsv(SV*);
41
42To 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
50Notice that you can choose to specify the length of the string to be
d1b91892
AD
51assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to
52calculate the length by using C<sv_setpv> or specifying 0 as the second
53argument to C<newSVpv>. Be warned, though, that Perl will determine the
a0d0e21e
LW
54string's length by using C<strlen>, which depends on the string terminating
55with a NUL character.
56
57To 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
63which will automatically coerce the actual scalar type into an IV, double,
64or string.
65
66In the C<SvPV> macro, the length of the string returned is placed into the
67variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
68care what the length of the data is, use the global variable C<na>. Remember,
69however, that Perl allows arbitrary strings of data that may both contain
70NUL's and not be terminated by a NUL.
71
72If you simply want to know if the scalar value is TRUE, you can use:
73
74 SvTRUE(SV*)
75
76Although Perl will automatically grow strings for you, if you need to force
77Perl to allocate more memory for your SV, you can use the macro
78
79 SvGROW(SV*, STRLEN newlen)
80
81which will determine if more memory needs to be allocated. If so, it will
82call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
83decrease, the allocated memory of an SV.
84
85If you have an SV and want to know what kind of data Perl thinks is stored
86in 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
92You can get and set the current length of the string stored in an SV with
93the following macros:
94
95 SvCUR(SV*)
96 SvCUR_set(SV*, I32 val)
97
98But note that these are valid only if C<SvPOK()> is true.
99
d1b91892
AD
100If you want to append something to the end of string stored in an C<SV*>,
101you 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
107The first function calculates the length of the string to be appended by
108using C<strlen>. In the second, you specify the length of the string
109yourself. The third function extends the string stored in the first SV
110with the string stored in the second SV. It also forces the second SV to
111be interpreted as a string.
112
a0d0e21e
LW
113If you know the name of a scalar variable, you can get a pointer to its SV
114by using the following:
115
116 SV* perl_get_sv("varname", FALSE);
117
118This returns NULL if the variable does not exist.
119
d1b91892 120If you want to know if this variable (or any other SV) is actually C<defined>,
a0d0e21e
LW
121you can call:
122
123 SvOK(SV*)
124
125The scalar C<undef> value is stored in an SV instance called C<sv_undef>. Its
126address can be used whenever an C<SV*> is needed.
127
128There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
129TRUE and FALSE values, respectively. Like C<sv_undef>, their addresses can
130be used whenever an C<SV*> is needed.
131
132Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
133Take 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
141This code tries to return a new SV (which contains the value 42) if it should
142return a real value, or undef otherwise. Instead it has returned a null
143pointer which, somewhere down the line, will cause a segmentation violation,
144or just weird results. Change the zero to C<&sv_undef> in the first line and
145all will be well.
146
147To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
148call is not necessary. See the section on B<MORTALITY>.
149
d1b91892 150=head2 What's Really Stored in an SV?
a0d0e21e
LW
151
152Recall that the usual method of determining the type of scalar you have is
d1b91892
AD
153to use C<Sv*OK> macros. Since a scalar can be both a number and a string,
154usually these macros will always return TRUE and calling the C<Sv*V>
a0d0e21e
LW
155macros will do the appropriate conversion of string to integer/double or
156integer/double to string.
157
158If you I<really> need to know if you have an integer, double, or string
159pointer in an SV, you can use the following three macros instead:
160
161 SvIOKp(SV*)
162 SvNOKp(SV*)
163 SvPOKp(SV*)
164
165These will tell you if you truly have an integer, double, or string pointer
d1b91892 166stored in your SV. The "p" stands for private.
a0d0e21e 167
d1b91892 168In general, though, it's best to just use the C<Sv*V> macros.
a0d0e21e
LW
169
170=head2 Working with AV's
171
172There are two ways to create and load an AV. The first method just creates
173an empty AV:
174
175 AV* newAV();
176
177The second method both creates the AV and initially populates it with SV's:
178
179 AV* av_make(I32 num, SV **ptr);
180
d1b91892
AD
181The second argument points to an array containing C<num> C<SV*>'s. Once the
182AV has been created, the SV's can be destroyed, if so desired.
a0d0e21e
LW
183
184Once 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
191These should be familiar operations, with the exception of C<av_unshift>.
192This routine adds C<num> elements at the front of the array with the C<undef>
193value. You must then use C<av_store> (described below) to assign values
194to these new elements.
195
196Here are some other functions:
197
d1b91892 198 I32 av_len(AV*); /* Returns highest index value in array */
a0d0e21e
LW
199
200 SV** av_fetch(AV*, I32 key, I32 lval);
d1b91892
AD
201 /* Fetches value at key offset, but it stores an undef value
202 at the offset if lval is non-zero */
a0d0e21e
LW
203 SV** av_store(AV*, I32 key, SV* val);
204 /* Stores val at offset key */
205
d1b91892
AD
206Take note that these two functions return C<SV**>'s, not C<SV*>'s.
207
a0d0e21e
LW
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
213If you know the name of an array variable, you can get a pointer to its AV
214by using the following:
215
216 AV* perl_get_av("varname", FALSE);
217
218This returns NULL if the variable does not exist.
219
220=head2 Working with HV's
221
222To create an HV, you use the following routine:
223
224 HV* newHV();
225
226Once 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
231The C<klen> parameter is the length of the key being passed in. The C<val>
232argument contains the SV pointer to the scalar being stored, and C<hash> is
233the pre-computed hash value (zero if you want C<hv_store> to calculate it
234for you). The C<lval> parameter indicates whether this fetch is actually a
235part of a store operation.
236
237Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
238C<SV*>. In order to access the scalar value, you must first dereference
239the return value. However, you should check to make sure that the return
240value is not NULL before dereferencing it.
241
242These 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
LW
246
247And 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
AD
254Perl keeps the actual data in linked list of structures with a typedef of HE.
255These contain the actual key and value pointers (plus extra administrative
256overhead). The key is a string pointer; the value is an C<SV*>. However,
257once you have an C<HE*>, to get the actual key and value, use the routines
258specified below.
259
a0d0e21e
LW
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
AD
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
LW
276
277If you know the name of a hash variable, you can get a pointer to its HV
278by using the following:
279
280 HV* perl_get_hv("varname", FALSE);
281
282This returns NULL if the variable does not exist.
283
284The 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
AD
292=head1 Creating New Variables
293
294To create a new Perl variable, which can be accessed from your Perl script,
295use 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
301Notice the use of TRUE as the second parameter. The new variable can now
302be set, using the routines appropriate to the data type.
303
304There are additional bits that may be OR'ed with the TRUE argument to enable
305certain 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
314If the C<varname> argument does not contain a package specifier, it is
315created in the current package.
316
a0d0e21e
LW
317=head2 References
318
d1b91892
AD
319References are a special type of scalar that point to other data types
320(including references).
a0d0e21e
LW
321
322To create a reference, use the following command:
323
d1b91892 324 SV* newRV((SV*) thing);
a0d0e21e 325
d1b91892
AD
326The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. Once
327you have a reference, you can use the following macro to dereference the
328reference:
a0d0e21e
LW
329
330 SvRV(SV*)
331
332then call the appropriate routines, casting the returned C<SV*> to either an
d1b91892 333C<AV*> or C<HV*>, if required.
a0d0e21e 334
d1b91892 335To determine if an SV is a reference, you can use the following macro:
a0d0e21e
LW
336
337 SvROK(SV*)
338
d1b91892
AD
339To actually discover what the reference refers to, you must use the following
340macro and then check the value returned.
341
342 SvTYPE(SvRV(SV*))
343
344The 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
LW
355
356The XSUB mechanism is a simple way for Perl programs to access C subroutines.
357An XSUB routine will have a stack that contains the arguments from the Perl
358program, and a way to map from the Perl data structures to a C equivalent.
359
360The stack arguments are accessible through the C<ST(n)> macro, which returns
361the C<n>'th stack argument. Argument 0 is the first argument passed in the
362Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
363an C<SV*> is used.
364
365Most of the time, output from the C routine can be handled through use of
366the RETVAL and OUTPUT directives. However, there are some cases where the
367argument stack is not already long enough to handle all the return values.
368An example is the POSIX tzname() call, which takes no arguments, but returns
369two, the local timezone's standard and summer time abbreviations.
370
371To handle this situation, the PPCODE directive is used and the stack is
372extended using the macro:
373
374 EXTEND(sp, num);
375
376where C<sp> is the stack pointer, and C<num> is the number of elements the
377stack should be extended by.
378
379Now that there is room on the stack, values can be pushed on it using the
380macros 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
387And now the Perl program calling C<tzname>, the two values will be assigned
388as in:
389
390 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
391
392An alternate (and possibly simpler) method to pushing values on the stack is
393to use the macros:
394
395 XPUSHi(IV)
396 XPUSHn(double)
397 XPUSHp(char*, I32)
398 XPUSHs(SV*)
399
400These macros automatically adjust the stack for you, if needed.
401
8e07c86e 402For more information, consult L<perlxs>.
d1b91892 403
a0d0e21e
LW
404=head1 Mortality
405
406In Perl, values are normally "immortal" -- that is, they are not freed unless
407explicitly done so (via the Perl C<undef> call or other routines in Perl
408itself).
409
d1b91892
AD
410Add cruft about reference counts.
411
a0d0e21e
LW
412In the above example with C<tzname>, we needed to create two new SV's to push
413onto the argument stack, that being the two strings. However, we don't want
414these new SV's to stick around forever because they will eventually be
415copied into the SV's that hold the two scalar variables.
416
417An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal"
418SV, AV, or HV, but is only valid in the "current context". When the Perl
419interpreter leaves the current context, the mortal SV, AV, or HV is
420automatically freed. Generally the "current context" means a single
421Perl statement.
422
423To create a mortal variable, use the functions:
424
425 SV* sv_newmortal()
426 SV* sv_2mortal(SV*)
427 SV* sv_mortalcopy(SV*)
428
429The first call creates a mortal SV, the second converts an existing SV to
430a mortal SV, the third creates a mortal copy of an existing SV.
431
432The mortal routines are not just for SV's -- AV's and HV's can be made mortal
433by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
434C<sv_mortalcopy> routines.
435
d1b91892
AD
436From Ilya:
437Beware that the sv_2mortal() call is eventually equivalent to
438svREFCNT_dec(). A value can happily be mortal in two different contexts,
439and it will be svREFCNT_dec()ed twice, once on exit from these
440contexts. It can also be mortal twice in the same context. This means
441that you should be very careful to make a value mortal exactly as many
442times as it is needed. The value that go to the Perl stack I<should>
443be mortal.
a0d0e21e 444
d1b91892
AD
445You should be careful about creating mortal variables. It is possible for
446strange things to happen should you make the same value mortal within
447multiple contexts.
a0d0e21e
LW
448
449=head1 Stashes and Objects
450
451A stash is a hash table (associative array) that contains all of the
452different objects that are contained within a package. Each key of the
d1b91892
AD
453stash is a symbol name (shared by all the different types of objects
454that have the same name), and each value in the hash table is called a
455GV (for Glob Value). This GV in turn contains references to the various
456objects of that name, including (but not limited to) the following:
a0d0e21e
LW
457
458 Scalar Value
459 Array Value
460 Hash Value
461 File Handle
462 Directory Handle
463 Format
464 Subroutine
465
d1b91892
AD
466Perl stores various stashes in a separate GV structure (for global
467variable) but represents them with an HV structure. The keys in this
468larger GV are the various package names; the values are the C<GV*>'s
469which are stashes. It may help to think of a stash purely as an HV,
470and that the term "GV" means the global variable hash.
a0d0e21e 471
d1b91892 472To get the stash pointer for a particular package, use the function:
a0d0e21e
LW
473
474 HV* gv_stashpv(char* name, I32 create)
475 HV* gv_stashsv(SV*, I32 create)
476
477The first function takes a literal string, the second uses the string stored
d1b91892
AD
478in the SV. Remember that a stash is just a hash table, so you get back an
479C<HV*>.
a0d0e21e
LW
480
481The name that C<gv_stash*v> wants is the name of the package whose symbol table
482you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
483packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
484language itself.
a0d0e21e
LW
485
486Alternately, if you have an SV that is a blessed reference, you can find
487out the stash pointer by using:
488
489 HV* SvSTASH(SvRV(SV*));
490
491then use the following to get the package name itself:
492
493 char* HvNAME(HV* stash);
494
495If you need to return a blessed value to your Perl script, you can use the
496following function:
497
498 SV* sv_bless(SV*, HV* stash)
499
500where the first argument, an C<SV*>, must be a reference, and the second
501argument is a stash. The returned C<SV*> can now be used in the same way
502as any other SV.
503
d1b91892
AD
504For more information on references and blessings, consult L<perlref>.
505
a0d0e21e
LW
506=head1 Magic
507
d1b91892
AD
508[This section still under construction. Ignore everything here. Post no
509bills. Everything not permitted is forbidden.]
510
511# Version 6, 1995/1/27
512
513Any SV may be magical, that is, it has special features that a normal
514SV does not have. These features are stored in the SV structure in a
515linked 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
528Note this is current as of patchlevel 0, and could change at any time.
529
530=head2 Assigning Magic
531
532Perl 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
536The C<sv> argument is a pointer to the SV that is to acquire a new magical
537feature.
538
539If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
540set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
541it to the beginning of the linked list of magical features. Any prior
542entry of the same type of magic is deleted. Note that this can be
543overriden, and multiple instances of the same type of magic can be
544associated with an SV.
545
546The C<name> and C<namlem> arguments are used to associate a string with
547the magic, typically the name of a variable. C<namlem> is stored in the
548C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
549copy of the name is stored in C<mg_ptr> field.
550
551The 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.
553See the "Magic Virtual Table" section below.
554
555The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
556structure. If it is not the same as the C<sv> argument, the reference
557count of the C<obj> object is incremented. If it is the same, or if
558the C<how> argument is "#", or if it is a null pointer, then C<obj> is
559merely stored, without the reference count being incremented.
560
561=head2 Magic Virtual Tables
562
563The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
564C<MGVTBL>, which is a structure of function pointers and stands for
565"Magic Virtual Table" to handle the various operations that might be
566applied to that variable.
567
568The 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
576This MGVTBL structure is set at compile-time in C<perl.h> and there are
577currently 19 types (or 21 with overloading turned on). These different
578structures contain pointers to various routines that perform additional
579actions 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
589For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
590to an C<mg_type> of '\0') contains:
591
592 { magic_get, magic_set, magic_len, 0, 0 }
593
594Thus, when an SV is determined to be magical and of type '\0', if a get
595operation is being performed, the routine C<magic_get> is called. All
596the various routines for the various magical types begin with C<magic_>.
597
598The 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
628When an upper-case and lower-case letter both exist in the table, then the
629upper-case letter is used to represent some kind of composite type (a list
630or a hash), and the lower-case letter is used to represent an element of
631that composite type.
632
633=head2 Finding Magic
634
635 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
636
637This routine returns a pointer to the C<MAGIC> structure stored in the SV.
638If the SV does not have that magical feature, C<NULL> is returned. Also,
639if 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
643This routine checks to see what types of magic C<sv> has. If the mg_type
644field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
645the mg_type field is changed to be the lower-case letter.
a0d0e21e
LW
646
647=head1 Double-Typed SV's
648
649Scalar variables normally contain only one type of value, an integer,
650double, pointer, or reference. Perl will automatically convert the
651actual scalar data from the stored type into the requested type.
652
653Some scalar variables contain more than one type of scalar data. For
654example, the variable C<$!> contains either the numeric value of C<errno>
d1b91892 655or its string equivalent from either C<strerror> or C<sys_errlist[]>.
a0d0e21e
LW
656
657To force multiple data values into an SV, you must do two things: use the
658C<sv_set*v> routines to add the additional scalar type, then set a flag
659so that Perl will believe it contains more than one type of data. The
660four macros to set the flags are:
661
662 SvIOK_on
663 SvNOK_on
664 SvPOK_on
665 SvROK_on
666
667The particular macro you must use depends on which C<sv_set*v> routine
668you called first. This is because every C<sv_set*v> routine turns on
669only the bit for the particular type of data being set, and turns off
670all the rest.
671
672For example, to create a new Perl variable called "dberror" that contains
673both the numeric and descriptive string error values, you could use the
674following 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
684If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
685macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
686
687=head1 Calling Perl Routines from within C Programs
688
689There are four routines that can be used to call a Perl subroutine from
690within 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
AD
697The routine most often used is C<perl_call_sv>. The C<SV*> argument
698contains either the name of the Perl subroutine to be called, or a
699reference to the subroutine. The second argument consists of flags
700that control the context in which the subroutine is called, whether
701or not the subroutine is being passed arguments, how errors should be
702trapped, and how to treat return values.
a0d0e21e
LW
703
704All four routines return the number of arguments that the subroutine returned
705on the Perl stack.
706
d1b91892
AD
707When using any of these routines (except C<perl_call_argv>), the programmer
708must manipulate the Perl stack. These include the following macros and
709functions:
a0d0e21e
LW
710
711 dSP
712 PUSHMARK()
713 PUTBACK
714 SPAGAIN
715 ENTER
716 SAVETMPS
717 FREETMPS
718 LEAVE
719 XPUSH*()
720
721For more information, consult L<perlcall>.
722
723=head1 Memory Allocation
724
d1b91892
AD
725It is strongly suggested that you use the version of malloc that is distributed
726with Perl. It keeps pools of various sizes of unallocated memory in order to
727more quickly satisfy allocation requests.
728However, 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
734These three macros are used to initially allocate memory. The first argument
735C<x> was a "magic cookie" that was used to keep track of who called the macro,
736to help when debugging memory problems. However, the current code makes no
737use of this feature (Larry has switched to using a run-time memory checker),
738so this argument can be any number.
739
740The second argument C<pointer> will point to the newly allocated memory.
741The third and fourth arguments C<number> and C<type> specify how many of
742the specified type of data structure should be allocated. The argument
743C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
744should be used if the C<pointer> argument is different from the C<type>
745argument.
746
747Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
748to zero out all the newly allocated memory.
749
750 Renew(pointer, number, type);
751 Renewc(pointer, number, type, cast);
752 Safefree(pointer)
753
754These three macros are used to change a memory buffer size or to free a
755piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
756match 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
763These three macros are used to move, copy, or zero out previously allocated
764memory. The C<source> and C<dest> arguments point to the source and
765destination starting points. Perl will move, copy, or zero out C<number>
766instances of the size of the C<type> data structure (using the C<sizeof>
767function).
a0d0e21e
LW
768
769=head1 AUTHOR
770
771Jeff Okamoto <okamoto@corp.hp.com>
772
773With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
d1b91892
AD
774Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
775Bowers, Matthew Green, Tim Bunce, and Spider Boardman.
a0d0e21e
LW
776
777=head1 DATE
778
d1b91892 779Version 19: 1995/4/26