3 perlguts - Perl's Internal Functions
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.
15 Perl has three typedefs that handle Perl's three main data types:
21 Each typedef has specific routines that manipulate the various data types.
23 =head2 What is an "IV"?
25 Perl uses a special typedef IV which is a simple integer type that is
26 guaranteed to be large enough to hold a pointer (as well as an integer).
28 Perl also uses two special typedefs, I32 and I16, which will always be at
29 least 32-bits and 16-bits long, respectively.
31 =head2 Working with SVs
33 An SV can be created and loaded with one command. There are four types of
34 values that can be loaded: an integer value (IV), a double (NV), a string,
35 (PV), and another scalar (SV).
41 SV* newSVpv(const char*, int);
42 SV* newSVpvn(const char*, int);
43 SV* newSVpvf(const char*, ...);
46 To change the value of an *already-existing* SV, there are seven routines:
48 void sv_setiv(SV*, IV);
49 void sv_setuv(SV*, UV);
50 void sv_setnv(SV*, double);
51 void sv_setpv(SV*, const char*);
52 void sv_setpvn(SV*, const char*, int)
53 void sv_setpvf(SV*, const char*, ...);
54 void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
55 void sv_setsv(SV*, SV*);
57 Notice that you can choose to specify the length of the string to be
58 assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
59 allow Perl to calculate the length by using C<sv_setpv> or by specifying
60 0 as the second argument to C<newSVpv>. Be warned, though, that Perl will
61 determine the string's length by using C<strlen>, which depends on the
62 string terminating with a NUL character.
64 The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
65 formatted output becomes the value.
67 C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify
68 either a pointer to a variable argument list or the address and length of
69 an array of SVs. The last argument points to a boolean; on return, if that
70 boolean is true, then locale-specific information has been used to format
71 the string, and the string's contents are therefore untrustworthy (see
72 L<perlsec>). This pointer may be NULL if that information is not
73 important. Note that this function requires you to specify the length of
76 The C<sv_set*()> functions are not generic enough to operate on values
77 that have "magic". See L<Magic Virtual Tables> later in this document.
79 All SVs that contain strings should be terminated with a NUL character.
80 If it is not NUL-terminated there is a risk of
81 core dumps and corruptions from code which passes the string to C
82 functions or system calls which expect a NUL-terminated string.
83 Perl's own functions typically add a trailing NUL for this reason.
84 Nevertheless, you should be very careful when you pass a string stored
85 in an SV to a C function or system call.
87 To access the actual value that an SV points to, you can use the macros:
94 which will automatically coerce the actual scalar type into an IV, double,
97 In the C<SvPV> macro, the length of the string returned is placed into the
98 variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do
99 not care what the length of the data is, use the C<SvPV_nolen> macro.
100 Historically the C<SvPV> macro with the global variable C<PL_na> has been
101 used in this case. But that can be quite inefficient because C<PL_na> must
102 be accessed in thread-local storage in threaded Perl. In any case, remember
103 that Perl allows arbitrary strings of data that may both contain NULs and
104 might not be terminated by a NUL.
106 Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
107 len);>. It might work with your compiler, but it won't work for everyone.
108 Break this sort of statement up into separate assignments:
116 If you want to know if the scalar value is TRUE, you can use:
120 Although Perl will automatically grow strings for you, if you need to force
121 Perl to allocate more memory for your SV, you can use the macro
123 SvGROW(SV*, STRLEN newlen)
125 which will determine if more memory needs to be allocated. If so, it will
126 call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
127 decrease, the allocated memory of an SV and that it does not automatically
128 add a byte for the a trailing NUL (perl's own string functions typically do
129 C<SvGROW(sv, len + 1)>).
131 If you have an SV and want to know what kind of data Perl thinks is stored
132 in it, you can use the following macros to check the type of SV you have.
138 You can get and set the current length of the string stored in an SV with
139 the following macros:
142 SvCUR_set(SV*, I32 val)
144 You can also get a pointer to the end of the string stored in the SV
149 But note that these last three macros are valid only if C<SvPOK()> is true.
151 If you want to append something to the end of string stored in an C<SV*>,
152 you can use the following functions:
154 void sv_catpv(SV*, const char*);
155 void sv_catpvn(SV*, const char*, STRLEN);
156 void sv_catpvf(SV*, const char*, ...);
157 void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
158 void sv_catsv(SV*, SV*);
160 The first function calculates the length of the string to be appended by
161 using C<strlen>. In the second, you specify the length of the string
162 yourself. The third function processes its arguments like C<sprintf> and
163 appends the formatted output. The fourth function works like C<vsprintf>.
164 You can specify the address and length of an array of SVs instead of the
165 va_list argument. The fifth function extends the string stored in the first
166 SV with the string stored in the second SV. It also forces the second SV
167 to be interpreted as a string.
169 The C<sv_cat*()> functions are not generic enough to operate on values that
170 have "magic". See L<Magic Virtual Tables> later in this document.
172 If you know the name of a scalar variable, you can get a pointer to its SV
173 by using the following:
175 SV* perl_get_sv("package::varname", FALSE);
177 This returns NULL if the variable does not exist.
179 If you want to know if this variable (or any other SV) is actually C<defined>,
184 The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>. Its
185 address can be used whenever an C<SV*> is needed.
187 There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
188 TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their addresses can
189 be used whenever an C<SV*> is needed.
191 Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
195 if (I-am-to-return-a-real-value) {
196 sv = sv_2mortal(newSViv(42));
200 This code tries to return a new SV (which contains the value 42) if it should
201 return a real value, or undef otherwise. Instead it has returned a NULL
202 pointer which, somewhere down the line, will cause a segmentation violation,
203 bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the first
204 line and all will be well.
206 To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
207 call is not necessary (see L<Reference Counts and Mortality>).
209 =head2 What's Really Stored in an SV?
211 Recall that the usual method of determining the type of scalar you have is
212 to use C<Sv*OK> macros. Because a scalar can be both a number and a string,
213 usually these macros will always return TRUE and calling the C<Sv*V>
214 macros will do the appropriate conversion of string to integer/double or
215 integer/double to string.
217 If you I<really> need to know if you have an integer, double, or string
218 pointer in an SV, you can use the following three macros instead:
224 These will tell you if you truly have an integer, double, or string pointer
225 stored in your SV. The "p" stands for private.
227 In general, though, it's best to use the C<Sv*V> macros.
229 =head2 Working with AVs
231 There are two ways to create and load an AV. The first method creates an
236 The second method both creates the AV and initially populates it with SVs:
238 AV* av_make(I32 num, SV **ptr);
240 The second argument points to an array containing C<num> C<SV*>'s. Once the
241 AV has been created, the SVs can be destroyed, if so desired.
243 Once the AV has been created, the following operations are possible on AVs:
245 void av_push(AV*, SV*);
248 void av_unshift(AV*, I32 num);
250 These should be familiar operations, with the exception of C<av_unshift>.
251 This routine adds C<num> elements at the front of the array with the C<undef>
252 value. You must then use C<av_store> (described below) to assign values
253 to these new elements.
255 Here are some other functions:
258 SV** av_fetch(AV*, I32 key, I32 lval);
259 SV** av_store(AV*, I32 key, SV* val);
261 The C<av_len> function returns the highest index value in array (just
262 like $#array in Perl). If the array is empty, -1 is returned. The
263 C<av_fetch> function returns the value at index C<key>, but if C<lval>
264 is non-zero, then C<av_fetch> will store an undef value at that index.
265 The C<av_store> function stores the value C<val> at index C<key>, and does
266 not increment the reference count of C<val>. Thus the caller is responsible
267 for taking care of that, and if C<av_store> returns NULL, the caller will
268 have to decrement the reference count to avoid a memory leak. Note that
269 C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
274 void av_extend(AV*, I32 key);
276 The C<av_clear> function deletes all the elements in the AV* array, but
277 does not actually delete the array itself. The C<av_undef> function will
278 delete all the elements in the array plus the array itself. The
279 C<av_extend> function extends the array so that it contains at least C<key+1>
280 elements. If C<key+1> is less than the currently allocated length of the array,
281 then nothing is done.
283 If you know the name of an array variable, you can get a pointer to its AV
284 by using the following:
286 AV* perl_get_av("package::varname", FALSE);
288 This returns NULL if the variable does not exist.
290 See L<Understanding the Magic of Tied Hashes and Arrays> for more
291 information on how to use the array access functions on tied arrays.
293 =head2 Working with HVs
295 To create an HV, you use the following routine:
299 Once the HV has been created, the following operations are possible on HVs:
301 SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
302 SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);
304 The C<klen> parameter is the length of the key being passed in (Note that
305 you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
306 length of the key). The C<val> argument contains the SV pointer to the
307 scalar being stored, and C<hash> is the precomputed hash value (zero if
308 you want C<hv_store> to calculate it for you). The C<lval> parameter
309 indicates whether this fetch is actually a part of a store operation, in
310 which case a new undefined value will be added to the HV with the supplied
311 key and C<hv_fetch> will return as if the value had already existed.
313 Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
314 C<SV*>. To access the scalar value, you must first dereference the return
315 value. However, you should check to make sure that the return value is
316 not NULL before dereferencing it.
318 These two functions check if a hash table entry exists, and deletes it.
320 bool hv_exists(HV*, const char* key, U32 klen);
321 SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);
323 If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
324 create and return a mortal copy of the deleted value.
326 And more miscellaneous functions:
331 Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
332 table but does not actually delete the hash table. The C<hv_undef> deletes
333 both the entries and the hash table itself.
335 Perl keeps the actual data in linked list of structures with a typedef of HE.
336 These contain the actual key and value pointers (plus extra administrative
337 overhead). The key is a string pointer; the value is an C<SV*>. However,
338 once you have an C<HE*>, to get the actual key and value, use the routines
341 I32 hv_iterinit(HV*);
342 /* Prepares starting point to traverse hash table */
343 HE* hv_iternext(HV*);
344 /* Get the next entry, and return a pointer to a
345 structure that has both the key and value */
346 char* hv_iterkey(HE* entry, I32* retlen);
347 /* Get the key from an HE structure and also return
348 the length of the key string */
349 SV* hv_iterval(HV*, HE* entry);
350 /* Return a SV pointer to the value of the HE
352 SV* hv_iternextsv(HV*, char** key, I32* retlen);
353 /* This convenience routine combines hv_iternext,
354 hv_iterkey, and hv_iterval. The key and retlen
355 arguments are return values for the key and its
356 length. The value is returned in the SV* argument */
358 If you know the name of a hash variable, you can get a pointer to its HV
359 by using the following:
361 HV* perl_get_hv("package::varname", FALSE);
363 This returns NULL if the variable does not exist.
365 The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
369 hash = (hash * 33) + *key++;
370 hash = hash + (hash >> 5); /* after 5.6 */
372 The last step was added in version 5.6 to improve distribution of
373 lower bits in the resulting hash value.
375 See L<Understanding the Magic of Tied Hashes and Arrays> for more
376 information on how to use the hash access functions on tied hashes.
378 =head2 Hash API Extensions
380 Beginning with version 5.004, the following functions are also supported:
382 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
383 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
385 bool hv_exists_ent (HV* tb, SV* key, U32 hash);
386 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
388 SV* hv_iterkeysv (HE* entry);
390 Note that these functions take C<SV*> keys, which simplifies writing
391 of extension code that deals with hash structures. These functions
392 also allow passing of C<SV*> keys to C<tie> functions without forcing
393 you to stringify the keys (unlike the previous set of functions).
395 They also return and accept whole hash entries (C<HE*>), making their
396 use more efficient (since the hash number for a particular string
397 doesn't have to be recomputed every time). See L<API LISTING> later in
398 this document for detailed descriptions.
400 The following macros must always be used to access the contents of hash
401 entries. Note that the arguments to these macros must be simple
402 variables, since they may get evaluated more than once. See
403 L<API LISTING> later in this document for detailed descriptions of these
406 HePV(HE* he, STRLEN len)
410 HeSVKEY_force(HE* he)
411 HeSVKEY_set(HE* he, SV* sv)
413 These two lower level macros are defined, but must only be used when
414 dealing with keys that are not C<SV*>s:
419 Note that both C<hv_store> and C<hv_store_ent> do not increment the
420 reference count of the stored C<val>, which is the caller's responsibility.
421 If these functions return a NULL value, the caller will usually have to
422 decrement the reference count of C<val> to avoid a memory leak.
426 References are a special type of scalar that point to other data types
427 (including references).
429 To create a reference, use either of the following functions:
431 SV* newRV_inc((SV*) thing);
432 SV* newRV_noinc((SV*) thing);
434 The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
435 functions are identical except that C<newRV_inc> increments the reference
436 count of the C<thing>, while C<newRV_noinc> does not. For historical
437 reasons, C<newRV> is a synonym for C<newRV_inc>.
439 Once you have a reference, you can use the following macro to dereference
444 then call the appropriate routines, casting the returned C<SV*> to either an
445 C<AV*> or C<HV*>, if required.
447 To determine if an SV is a reference, you can use the following macro:
451 To discover what type of value the reference refers to, use the following
452 macro and then check the return value.
456 The most useful types that will be returned are:
465 SVt_PVGV Glob (possible a file handle)
466 SVt_PVMG Blessed or Magical Scalar
468 See the sv.h header file for more details.
470 =head2 Blessed References and Class Objects
472 References are also used to support object-oriented programming. In the
473 OO lexicon, an object is simply a reference that has been blessed into a
474 package (or class). Once blessed, the programmer may now use the reference
475 to access the various methods in the class.
477 A reference can be blessed into a package with the following function:
479 SV* sv_bless(SV* sv, HV* stash);
481 The C<sv> argument must be a reference. The C<stash> argument specifies
482 which class the reference will belong to. See
483 L<Stashes and Globs> for information on converting class names into stashes.
485 /* Still under construction */
487 Upgrades rv to reference if not already one. Creates new SV for rv to
488 point to. If C<classname> is non-null, the SV is blessed into the specified
489 class. SV is returned.
491 SV* newSVrv(SV* rv, const char* classname);
493 Copies integer or double into an SV whose reference is C<rv>. SV is blessed
494 if C<classname> is non-null.
496 SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
497 SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
499 Copies the pointer value (I<the address, not the string!>) into an SV whose
500 reference is rv. SV is blessed if C<classname> is non-null.
502 SV* sv_setref_pv(SV* rv, const char* classname, PV iv);
504 Copies string into an SV whose reference is C<rv>. Set length to 0 to let
505 Perl calculate the string length. SV is blessed if C<classname> is non-null.
507 SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);
509 Tests whether the SV is blessed into the specified class. It does not
510 check inheritance relationships.
512 int sv_isa(SV* sv, const char* name);
514 Tests whether the SV is a reference to a blessed object.
516 int sv_isobject(SV* sv);
518 Tests whether the SV is derived from the specified class. SV can be either
519 a reference to a blessed object or a string containing a class name. This
520 is the function implementing the C<UNIVERSAL::isa> functionality.
522 bool sv_derived_from(SV* sv, const char* name);
524 To check if you've got an object derived from a specific class you have
527 if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
529 =head2 Creating New Variables
531 To create a new Perl variable with an undef value which can be accessed from
532 your Perl script, use the following routines, depending on the variable type.
534 SV* perl_get_sv("package::varname", TRUE);
535 AV* perl_get_av("package::varname", TRUE);
536 HV* perl_get_hv("package::varname", TRUE);
538 Notice the use of TRUE as the second parameter. The new variable can now
539 be set, using the routines appropriate to the data type.
541 There are additional macros whose values may be bitwise OR'ed with the
542 C<TRUE> argument to enable certain extra features. Those bits are:
544 GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
545 "Name <varname> used only once: possible typo" warning.
546 GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
547 the variable did not exist before the function was called.
549 If you do not specify a package name, the variable is created in the current
552 =head2 Reference Counts and Mortality
554 Perl uses an reference count-driven garbage collection mechanism. SVs,
555 AVs, or HVs (xV for short in the following) start their life with a
556 reference count of 1. If the reference count of an xV ever drops to 0,
557 then it will be destroyed and its memory made available for reuse.
559 This normally doesn't happen at the Perl level unless a variable is
560 undef'ed or the last variable holding a reference to it is changed or
561 overwritten. At the internal level, however, reference counts can be
562 manipulated with the following macros:
564 int SvREFCNT(SV* sv);
565 SV* SvREFCNT_inc(SV* sv);
566 void SvREFCNT_dec(SV* sv);
568 However, there is one other function which manipulates the reference
569 count of its argument. The C<newRV_inc> function, you will recall,
570 creates a reference to the specified argument. As a side effect,
571 it increments the argument's reference count. If this is not what
572 you want, use C<newRV_noinc> instead.
574 For example, imagine you want to return a reference from an XSUB function.
575 Inside the XSUB routine, you create an SV which initially has a reference
576 count of one. Then you call C<newRV_inc>, passing it the just-created SV.
577 This returns the reference as a new SV, but the reference count of the
578 SV you passed to C<newRV_inc> has been incremented to two. Now you
579 return the reference from the XSUB routine and forget about the SV.
580 But Perl hasn't! Whenever the returned reference is destroyed, the
581 reference count of the original SV is decreased to one and nothing happens.
582 The SV will hang around without any way to access it until Perl itself
583 terminates. This is a memory leak.
585 The correct procedure, then, is to use C<newRV_noinc> instead of
586 C<newRV_inc>. Then, if and when the last reference is destroyed,
587 the reference count of the SV will go to zero and it will be destroyed,
588 stopping any memory leak.
590 There are some convenience functions available that can help with the
591 destruction of xVs. These functions introduce the concept of "mortality".
592 An xV that is mortal has had its reference count marked to be decremented,
593 but not actually decremented, until "a short time later". Generally the
594 term "short time later" means a single Perl statement, such as a call to
595 an XSUB function. The actual determinant for when mortal xVs have their
596 reference count decremented depends on two macros, SAVETMPS and FREETMPS.
597 See L<perlcall> and L<perlxs> for more details on these macros.
599 "Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
600 However, if you mortalize a variable twice, the reference count will
601 later be decremented twice.
603 You should be careful about creating mortal variables. Strange things
604 can happen if you make the same value mortal within multiple contexts,
605 or if you make a variable mortal multiple times.
607 To create a mortal variable, use the functions:
611 SV* sv_mortalcopy(SV*)
613 The first call creates a mortal SV, the second converts an existing
614 SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
615 third creates a mortal copy of an existing SV.
617 The mortal routines are not just for SVs -- AVs and HVs can be
618 made mortal by passing their address (type-casted to C<SV*>) to the
619 C<sv_2mortal> or C<sv_mortalcopy> routines.
621 =head2 Stashes and Globs
623 A "stash" is a hash that contains all of the different objects that
624 are contained within a package. Each key of the stash is a symbol
625 name (shared by all the different types of objects that have the same
626 name), and each value in the hash table is a GV (Glob Value). This GV
627 in turn contains references to the various objects of that name,
628 including (but not limited to) the following:
637 There is a single stash called "PL_defstash" that holds the items that exist
638 in the "main" package. To get at the items in other packages, append the
639 string "::" to the package name. The items in the "Foo" package are in
640 the stash "Foo::" in PL_defstash. The items in the "Bar::Baz" package are
641 in the stash "Baz::" in "Bar::"'s stash.
643 To get the stash pointer for a particular package, use the function:
645 HV* gv_stashpv(const char* name, I32 create)
646 HV* gv_stashsv(SV*, I32 create)
648 The first function takes a literal string, the second uses the string stored
649 in the SV. Remember that a stash is just a hash table, so you get back an
650 C<HV*>. The C<create> flag will create a new package if it is set.
652 The name that C<gv_stash*v> wants is the name of the package whose symbol table
653 you want. The default package is called C<main>. If you have multiply nested
654 packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
657 Alternately, if you have an SV that is a blessed reference, you can find
658 out the stash pointer by using:
660 HV* SvSTASH(SvRV(SV*));
662 then use the following to get the package name itself:
664 char* HvNAME(HV* stash);
666 If you need to bless or re-bless an object you can use the following
669 SV* sv_bless(SV*, HV* stash)
671 where the first argument, an C<SV*>, must be a reference, and the second
672 argument is a stash. The returned C<SV*> can now be used in the same way
675 For more information on references and blessings, consult L<perlref>.
677 =head2 Double-Typed SVs
679 Scalar variables normally contain only one type of value, an integer,
680 double, pointer, or reference. Perl will automatically convert the
681 actual scalar data from the stored type into the requested type.
683 Some scalar variables contain more than one type of scalar data. For
684 example, the variable C<$!> contains either the numeric value of C<errno>
685 or its string equivalent from either C<strerror> or C<sys_errlist[]>.
687 To force multiple data values into an SV, you must do two things: use the
688 C<sv_set*v> routines to add the additional scalar type, then set a flag
689 so that Perl will believe it contains more than one type of data. The
690 four macros to set the flags are:
697 The particular macro you must use depends on which C<sv_set*v> routine
698 you called first. This is because every C<sv_set*v> routine turns on
699 only the bit for the particular type of data being set, and turns off
702 For example, to create a new Perl variable called "dberror" that contains
703 both the numeric and descriptive string error values, you could use the
707 extern char *dberror_list;
709 SV* sv = perl_get_sv("dberror", TRUE);
710 sv_setiv(sv, (IV) dberror);
711 sv_setpv(sv, dberror_list[dberror]);
714 If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
715 macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
717 =head2 Magic Variables
719 [This section still under construction. Ignore everything here. Post no
720 bills. Everything not permitted is forbidden.]
722 Any SV may be magical, that is, it has special features that a normal
723 SV does not have. These features are stored in the SV structure in a
724 linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
737 Note this is current as of patchlevel 0, and could change at any time.
739 =head2 Assigning Magic
741 Perl adds magic to an SV using the sv_magic function:
743 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
745 The C<sv> argument is a pointer to the SV that is to acquire a new magical
748 If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
749 set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
750 it to the beginning of the linked list of magical features. Any prior
751 entry of the same type of magic is deleted. Note that this can be
752 overridden, and multiple instances of the same type of magic can be
753 associated with an SV.
755 The C<name> and C<namlen> arguments are used to associate a string with
756 the magic, typically the name of a variable. C<namlen> is stored in the
757 C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
758 copy of the name is stored in C<mg_ptr> field.
760 The sv_magic function uses C<how> to determine which, if any, predefined
761 "Magic Virtual Table" should be assigned to the C<mg_virtual> field.
762 See the "Magic Virtual Table" section below. The C<how> argument is also
763 stored in the C<mg_type> field.
765 The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
766 structure. If it is not the same as the C<sv> argument, the reference
767 count of the C<obj> object is incremented. If it is the same, or if
768 the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
769 merely stored, without the reference count being incremented.
771 There is also a function to add magic to an C<HV>:
773 void hv_magic(HV *hv, GV *gv, int how);
775 This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
777 To remove the magic from an SV, call the function sv_unmagic:
779 void sv_unmagic(SV *sv, int type);
781 The C<type> argument should be equal to the C<how> value when the C<SV>
782 was initially made magical.
784 =head2 Magic Virtual Tables
786 The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
787 C<MGVTBL>, which is a structure of function pointers and stands for
788 "Magic Virtual Table" to handle the various operations that might be
789 applied to that variable.
791 The C<MGVTBL> has five pointers to the following routine types:
793 int (*svt_get)(SV* sv, MAGIC* mg);
794 int (*svt_set)(SV* sv, MAGIC* mg);
795 U32 (*svt_len)(SV* sv, MAGIC* mg);
796 int (*svt_clear)(SV* sv, MAGIC* mg);
797 int (*svt_free)(SV* sv, MAGIC* mg);
799 This MGVTBL structure is set at compile-time in C<perl.h> and there are
800 currently 19 types (or 21 with overloading turned on). These different
801 structures contain pointers to various routines that perform additional
802 actions depending on which function is being called.
804 Function pointer Action taken
805 ---------------- ------------
806 svt_get Do something after the value of the SV is retrieved.
807 svt_set Do something after the SV is assigned a value.
808 svt_len Report on the SV's length.
809 svt_clear Clear something the SV represents.
810 svt_free Free any extra storage associated with the SV.
812 For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
813 to an C<mg_type> of '\0') contains:
815 { magic_get, magic_set, magic_len, 0, 0 }
817 Thus, when an SV is determined to be magical and of type '\0', if a get
818 operation is being performed, the routine C<magic_get> is called. All
819 the various routines for the various magical types begin with C<magic_>.
821 The current kinds of Magic Virtual Tables are:
823 mg_type MGVTBL Type of magic
824 ------- ------ ----------------------------
825 \0 vtbl_sv Special scalar variable
826 A vtbl_amagic %OVERLOAD hash
827 a vtbl_amagicelem %OVERLOAD hash element
828 c (none) Holds overload table (AMT) on stash
829 B vtbl_bm Boyer-Moore (fast string search)
831 e vtbl_envelem %ENV hash element
832 f vtbl_fm Formline ('compiled' format)
833 g vtbl_mglob m//g target / study()ed string
834 I vtbl_isa @ISA array
835 i vtbl_isaelem @ISA array element
836 k vtbl_nkeys scalar(keys()) lvalue
837 L (none) Debugger %_<filename
838 l vtbl_dbline Debugger %_<filename element
839 o vtbl_collxfrm Locale transformation
840 P vtbl_pack Tied array or hash
841 p vtbl_packelem Tied array or hash element
842 q vtbl_packelem Tied scalar or handle
844 s vtbl_sigelem %SIG hash element
845 t vtbl_taint Taintedness
846 U vtbl_uvar Available for use by extensions
847 v vtbl_vec vec() lvalue
848 x vtbl_substr substr() lvalue
849 y vtbl_defelem Shadow "foreach" iterator variable /
850 smart parameter vivification
851 * vtbl_glob GV (typeglob)
852 # vtbl_arylen Array length ($#ary)
853 . vtbl_pos pos() lvalue
854 ~ (none) Available for use by extensions
856 When an uppercase and lowercase letter both exist in the table, then the
857 uppercase letter is used to represent some kind of composite type (a list
858 or a hash), and the lowercase letter is used to represent an element of
861 The '~' and 'U' magic types are defined specifically for use by
862 extensions and will not be used by perl itself. Extensions can use
863 '~' magic to 'attach' private information to variables (typically
864 objects). This is especially useful because there is no way for
865 normal perl code to corrupt this private information (unlike using
866 extra elements of a hash object).
868 Similarly, 'U' magic can be used much like tie() to call a C function
869 any time a scalar's value is used or changed. The C<MAGIC>'s
870 C<mg_ptr> field points to a C<ufuncs> structure:
873 I32 (*uf_val)(IV, SV*);
874 I32 (*uf_set)(IV, SV*);
878 When the SV is read from or written to, the C<uf_val> or C<uf_set>
879 function will be called with C<uf_index> as the first arg and a
880 pointer to the SV as the second. A simple example of how to add 'U'
881 magic is shown below. Note that the ufuncs structure is copied by
882 sv_magic, so you can safely allocate it on the stack.
890 uf.uf_val = &my_get_fn;
891 uf.uf_set = &my_set_fn;
893 sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf));
895 Note that because multiple extensions may be using '~' or 'U' magic,
896 it is important for extensions to take extra care to avoid conflict.
897 Typically only using the magic on objects blessed into the same class
898 as the extension is sufficient. For '~' magic, it may also be
899 appropriate to add an I32 'signature' at the top of the private data
902 Also note that the C<sv_set*()> and C<sv_cat*()> functions described
903 earlier do B<not> invoke 'set' magic on their targets. This must
904 be done by the user either by calling the C<SvSETMAGIC()> macro after
905 calling these functions, or by using one of the C<sv_set*_mg()> or
906 C<sv_cat*_mg()> functions. Similarly, generic C code must call the
907 C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
908 obtained from external sources in functions that don't handle magic.
909 L<API LISTING> later in this document identifies such functions.
910 For example, calls to the C<sv_cat*()> functions typically need to be
911 followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
912 since their implementation handles 'get' magic.
916 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
918 This routine returns a pointer to the C<MAGIC> structure stored in the SV.
919 If the SV does not have that magical feature, C<NULL> is returned. Also,
920 if the SV is not of type SVt_PVMG, Perl may core dump.
922 int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);
924 This routine checks to see what types of magic C<sv> has. If the mg_type
925 field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
926 the mg_type field is changed to be the lowercase letter.
928 =head2 Understanding the Magic of Tied Hashes and Arrays
930 Tied hashes and arrays are magical beasts of the 'P' magic type.
932 WARNING: As of the 5.004 release, proper usage of the array and hash
933 access functions requires understanding a few caveats. Some
934 of these caveats are actually considered bugs in the API, to be fixed
935 in later releases, and are bracketed with [MAYCHANGE] below. If
936 you find yourself actually applying such information in this section, be
937 aware that the behavior may change in the future, umm, without warning.
939 The perl tie function associates a variable with an object that implements
940 the various GET, SET etc methods. To perform the equivalent of the perl
941 tie function from an XSUB, you must mimic this behaviour. The code below
942 carries out the necessary steps - firstly it creates a new hash, and then
943 creates a second hash which it blesses into the class which will implement
944 the tie methods. Lastly it ties the two hashes together, and returns a
945 reference to the new tied hash. Note that the code below does NOT call the
946 TIEHASH method in the MyTie class -
947 see L<Calling Perl Routines from within C Programs> for details on how
958 tie = newRV_noinc((SV*)newHV());
959 stash = gv_stashpv("MyTie", TRUE);
960 sv_bless(tie, stash);
961 hv_magic(hash, tie, 'P');
962 RETVAL = newRV_noinc(hash);
966 The C<av_store> function, when given a tied array argument, merely
967 copies the magic of the array onto the value to be "stored", using
968 C<mg_copy>. It may also return NULL, indicating that the value did not
969 actually need to be stored in the array. [MAYCHANGE] After a call to
970 C<av_store> on a tied array, the caller will usually need to call
971 C<mg_set(val)> to actually invoke the perl level "STORE" method on the
972 TIEARRAY object. If C<av_store> did return NULL, a call to
973 C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
976 The previous paragraph is applicable verbatim to tied hash access using the
977 C<hv_store> and C<hv_store_ent> functions as well.
979 C<av_fetch> and the corresponding hash functions C<hv_fetch> and
980 C<hv_fetch_ent> actually return an undefined mortal value whose magic
981 has been initialized using C<mg_copy>. Note the value so returned does not
982 need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
983 need to call C<mg_get()> on the returned value in order to actually invoke
984 the perl level "FETCH" method on the underlying TIE object. Similarly,
985 you may also call C<mg_set()> on the return value after possibly assigning
986 a suitable value to it using C<sv_setsv>, which will invoke the "STORE"
987 method on the TIE object. [/MAYCHANGE]
990 In other words, the array or hash fetch/store functions don't really
991 fetch and store actual values in the case of tied arrays and hashes. They
992 merely call C<mg_copy> to attach magic to the values that were meant to be
993 "stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually
994 do the job of invoking the TIE methods on the underlying objects. Thus
995 the magic mechanism currently implements a kind of lazy access to arrays
998 Currently (as of perl version 5.004), use of the hash and array access
999 functions requires the user to be aware of whether they are operating on
1000 "normal" hashes and arrays, or on their tied variants. The API may be
1001 changed to provide more transparent access to both tied and normal data
1002 types in future versions.
1005 You would do well to understand that the TIEARRAY and TIEHASH interfaces
1006 are mere sugar to invoke some perl method calls while using the uniform hash
1007 and array syntax. The use of this sugar imposes some overhead (typically
1008 about two to four extra opcodes per FETCH/STORE operation, in addition to
1009 the creation of all the mortal variables required to invoke the methods).
1010 This overhead will be comparatively small if the TIE methods are themselves
1011 substantial, but if they are only a few statements long, the overhead
1012 will not be insignificant.
1014 =head2 Localizing changes
1016 Perl has a very handy construction
1023 This construction is I<approximately> equivalent to
1032 The biggest difference is that the first construction would
1033 reinstate the initial value of $var, irrespective of how control exits
1034 the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
1035 more efficient as well.
1037 There is a way to achieve a similar task from C via Perl API: create a
1038 I<pseudo-block>, and arrange for some changes to be automatically
1039 undone at the end of it, either explicit, or via a non-local exit (via
1040 die()). A I<block>-like construct is created by a pair of
1041 C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
1042 Such a construct may be created specially for some important localized
1043 task, or an existing one (like boundaries of enclosing Perl
1044 subroutine/block, or an existing pair for freeing TMPs) may be
1045 used. (In the second case the overhead of additional localization must
1046 be almost negligible.) Note that any XSUB is automatically enclosed in
1047 an C<ENTER>/C<LEAVE> pair.
1049 Inside such a I<pseudo-block> the following service is available:
1053 =item C<SAVEINT(int i)>
1055 =item C<SAVEIV(IV i)>
1057 =item C<SAVEI32(I32 i)>
1059 =item C<SAVELONG(long i)>
1061 These macros arrange things to restore the value of integer variable
1062 C<i> at the end of enclosing I<pseudo-block>.
1064 =item C<SAVESPTR(s)>
1066 =item C<SAVEPPTR(p)>
1068 These macros arrange things to restore the value of pointers C<s> and
1069 C<p>. C<s> must be a pointer of a type which survives conversion to
1070 C<SV*> and back, C<p> should be able to survive conversion to C<char*>
1073 =item C<SAVEFREESV(SV *sv)>
1075 The refcount of C<sv> would be decremented at the end of
1076 I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
1079 =item C<SAVEFREEOP(OP *op)>
1081 The C<OP *> is op_free()ed at the end of I<pseudo-block>.
1083 =item C<SAVEFREEPV(p)>
1085 The chunk of memory which is pointed to by C<p> is Safefree()ed at the
1086 end of I<pseudo-block>.
1088 =item C<SAVECLEARSV(SV *sv)>
1090 Clears a slot in the current scratchpad which corresponds to C<sv> at
1091 the end of I<pseudo-block>.
1093 =item C<SAVEDELETE(HV *hv, char *key, I32 length)>
1095 The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
1096 string pointed to by C<key> is Safefree()ed. If one has a I<key> in
1097 short-lived storage, the corresponding string may be reallocated like
1100 SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
1102 =item C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>
1104 At the end of I<pseudo-block> the function C<f> is called with the
1107 =item C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>
1109 At the end of I<pseudo-block> the function C<f> is called with the
1110 implicit context argument (if any), and C<p>.
1112 =item C<SAVESTACK_POS()>
1114 The current offset on the Perl internal stack (cf. C<SP>) is restored
1115 at the end of I<pseudo-block>.
1119 The following API list contains functions, thus one needs to
1120 provide pointers to the modifiable data explicitly (either C pointers,
1121 or Perlish C<GV *>s). Where the above macros take C<int>, a similar
1122 function takes C<int *>.
1126 =item C<SV* save_scalar(GV *gv)>
1128 Equivalent to Perl code C<local $gv>.
1130 =item C<AV* save_ary(GV *gv)>
1132 =item C<HV* save_hash(GV *gv)>
1134 Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
1136 =item C<void save_item(SV *item)>
1138 Duplicates the current value of C<SV>, on the exit from the current
1139 C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
1140 using the stored value.
1142 =item C<void save_list(SV **sarg, I32 maxsarg)>
1144 A variant of C<save_item> which takes multiple arguments via an array
1145 C<sarg> of C<SV*> of length C<maxsarg>.
1147 =item C<SV* save_svref(SV **sptr)>
1149 Similar to C<save_scalar>, but will reinstate a C<SV *>.
1151 =item C<void save_aptr(AV **aptr)>
1153 =item C<void save_hptr(HV **hptr)>
1155 Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
1159 The C<Alias> module implements localization of the basic types within the
1160 I<caller's scope>. People who are interested in how to localize things in
1161 the containing scope should take a look there too.
1165 =head2 XSUBs and the Argument Stack
1167 The XSUB mechanism is a simple way for Perl programs to access C subroutines.
1168 An XSUB routine will have a stack that contains the arguments from the Perl
1169 program, and a way to map from the Perl data structures to a C equivalent.
1171 The stack arguments are accessible through the C<ST(n)> macro, which returns
1172 the C<n>'th stack argument. Argument 0 is the first argument passed in the
1173 Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
1176 Most of the time, output from the C routine can be handled through use of
1177 the RETVAL and OUTPUT directives. However, there are some cases where the
1178 argument stack is not already long enough to handle all the return values.
1179 An example is the POSIX tzname() call, which takes no arguments, but returns
1180 two, the local time zone's standard and summer time abbreviations.
1182 To handle this situation, the PPCODE directive is used and the stack is
1183 extended using the macro:
1187 where C<SP> is the macro that represents the local copy of the stack pointer,
1188 and C<num> is the number of elements the stack should be extended by.
1190 Now that there is room on the stack, values can be pushed on it using the
1191 macros to push IVs, doubles, strings, and SV pointers respectively:
1198 And now the Perl program calling C<tzname>, the two values will be assigned
1201 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
1203 An alternate (and possibly simpler) method to pushing values on the stack is
1211 These macros automatically adjust the stack for you, if needed. Thus, you
1212 do not need to call C<EXTEND> to extend the stack.
1214 For more information, consult L<perlxs> and L<perlxstut>.
1216 =head2 Calling Perl Routines from within C Programs
1218 There are four routines that can be used to call a Perl subroutine from
1219 within a C program. These four are:
1221 I32 perl_call_sv(SV*, I32);
1222 I32 perl_call_pv(const char*, I32);
1223 I32 perl_call_method(const char*, I32);
1224 I32 perl_call_argv(const char*, I32, register char**);
1226 The routine most often used is C<perl_call_sv>. The C<SV*> argument
1227 contains either the name of the Perl subroutine to be called, or a
1228 reference to the subroutine. The second argument consists of flags
1229 that control the context in which the subroutine is called, whether
1230 or not the subroutine is being passed arguments, how errors should be
1231 trapped, and how to treat return values.
1233 All four routines return the number of arguments that the subroutine returned
1236 When using any of these routines (except C<perl_call_argv>), the programmer
1237 must manipulate the Perl stack. These include the following macros and
1252 For a detailed description of calling conventions from C to Perl,
1253 consult L<perlcall>.
1255 =head2 Memory Allocation
1257 All memory meant to be used with the Perl API functions should be manipulated
1258 using the macros described in this section. The macros provide the necessary
1259 transparency between differences in the actual malloc implementation that is
1262 It is suggested that you enable the version of malloc that is distributed
1263 with Perl. It keeps pools of various sizes of unallocated memory in
1264 order to satisfy allocation requests more quickly. However, on some
1265 platforms, it may cause spurious malloc or free errors.
1267 New(x, pointer, number, type);
1268 Newc(x, pointer, number, type, cast);
1269 Newz(x, pointer, number, type);
1271 These three macros are used to initially allocate memory.
1273 The first argument C<x> was a "magic cookie" that was used to keep track
1274 of who called the macro, to help when debugging memory problems. However,
1275 the current code makes no use of this feature (most Perl developers now
1276 use run-time memory checkers), so this argument can be any number.
1278 The second argument C<pointer> should be the name of a variable that will
1279 point to the newly allocated memory.
1281 The third and fourth arguments C<number> and C<type> specify how many of
1282 the specified type of data structure should be allocated. The argument
1283 C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
1284 should be used if the C<pointer> argument is different from the C<type>
1287 Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
1288 to zero out all the newly allocated memory.
1290 Renew(pointer, number, type);
1291 Renewc(pointer, number, type, cast);
1294 These three macros are used to change a memory buffer size or to free a
1295 piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
1296 match those of C<New> and C<Newc> with the exception of not needing the
1297 "magic cookie" argument.
1299 Move(source, dest, number, type);
1300 Copy(source, dest, number, type);
1301 Zero(dest, number, type);
1303 These three macros are used to move, copy, or zero out previously allocated
1304 memory. The C<source> and C<dest> arguments point to the source and
1305 destination starting points. Perl will move, copy, or zero out C<number>
1306 instances of the size of the C<type> data structure (using the C<sizeof>
1311 The most recent development releases of Perl has been experimenting with
1312 removing Perl's dependency on the "normal" standard I/O suite and allowing
1313 other stdio implementations to be used. This involves creating a new
1314 abstraction layer that then calls whichever implementation of stdio Perl
1315 was compiled with. All XSUBs should now use the functions in the PerlIO
1316 abstraction layer and not make any assumptions about what kind of stdio
1319 For a complete description of the PerlIO abstraction, consult L<perlapio>.
1321 =head2 Putting a C value on Perl stack
1323 A lot of opcodes (this is an elementary operation in the internal perl
1324 stack machine) put an SV* on the stack. However, as an optimization
1325 the corresponding SV is (usually) not recreated each time. The opcodes
1326 reuse specially assigned SVs (I<target>s) which are (as a corollary)
1327 not constantly freed/created.
1329 Each of the targets is created only once (but see
1330 L<Scratchpads and recursion> below), and when an opcode needs to put
1331 an integer, a double, or a string on stack, it just sets the
1332 corresponding parts of its I<target> and puts the I<target> on stack.
1334 The macro to put this target on stack is C<PUSHTARG>, and it is
1335 directly used in some opcodes, as well as indirectly in zillions of
1336 others, which use it via C<(X)PUSH[pni]>.
1340 The question remains on when the SVs which are I<target>s for opcodes
1341 are created. The answer is that they are created when the current unit --
1342 a subroutine or a file (for opcodes for statements outside of
1343 subroutines) -- is compiled. During this time a special anonymous Perl
1344 array is created, which is called a scratchpad for the current
1347 A scratchpad keeps SVs which are lexicals for the current unit and are
1348 targets for opcodes. One can deduce that an SV lives on a scratchpad
1349 by looking on its flags: lexicals have C<SVs_PADMY> set, and
1350 I<target>s have C<SVs_PADTMP> set.
1352 The correspondence between OPs and I<target>s is not 1-to-1. Different
1353 OPs in the compile tree of the unit can use the same target, if this
1354 would not conflict with the expected life of the temporary.
1356 =head2 Scratchpads and recursion
1358 In fact it is not 100% true that a compiled unit contains a pointer to
1359 the scratchpad AV. In fact it contains a pointer to an AV of
1360 (initially) one element, and this element is the scratchpad AV. Why do
1361 we need an extra level of indirection?
1363 The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1364 these can create several execution pointers going into the same
1365 subroutine. For the subroutine-child not write over the temporaries
1366 for the subroutine-parent (lifespan of which covers the call to the
1367 child), the parent and the child should have different
1368 scratchpads. (I<And> the lexicals should be separate anyway!)
1370 So each subroutine is born with an array of scratchpads (of length 1).
1371 On each entry to the subroutine it is checked that the current
1372 depth of the recursion is not more than the length of this array, and
1373 if it is, new scratchpad is created and pushed into the array.
1375 The I<target>s on this scratchpad are C<undef>s, but they are already
1376 marked with correct flags.
1378 =head1 Compiled code
1382 Here we describe the internal form your code is converted to by
1383 Perl. Start with a simple example:
1387 This is converted to a tree similar to this one:
1395 (but slightly more complicated). This tree reflects the way Perl
1396 parsed your code, but has nothing to do with the execution order.
1397 There is an additional "thread" going through the nodes of the tree
1398 which shows the order of execution of the nodes. In our simplified
1399 example above it looks like:
1401 $b ---> $c ---> + ---> $a ---> assign-to
1403 But with the actual compile tree for C<$a = $b + $c> it is different:
1404 some nodes I<optimized away>. As a corollary, though the actual tree
1405 contains more nodes than our simplified example, the execution order
1406 is the same as in our example.
1408 =head2 Examining the tree
1410 If you have your perl compiled for debugging (usually done with C<-D
1411 optimize=-g> on C<Configure> command line), you may examine the
1412 compiled tree by specifying C<-Dx> on the Perl command line. The
1413 output takes several lines per node, and for C<$b+$c> it looks like
1418 FLAGS = (SCALAR,KIDS)
1420 TYPE = null ===> (4)
1422 FLAGS = (SCALAR,KIDS)
1424 3 TYPE = gvsv ===> 4
1430 TYPE = null ===> (5)
1432 FLAGS = (SCALAR,KIDS)
1434 4 TYPE = gvsv ===> 5
1440 This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1441 not optimized away (one per number in the left column). The immediate
1442 children of the given node correspond to C<{}> pairs on the same level
1443 of indentation, thus this listing corresponds to the tree:
1451 The execution order is indicated by C<===E<gt>> marks, thus it is C<3
1452 4 5 6> (node C<6> is not included into above listing), i.e.,
1453 C<gvsv gvsv add whatever>.
1455 =head2 Compile pass 1: check routines
1457 The tree is created by the I<pseudo-compiler> while yacc code feeds it
1458 the constructions it recognizes. Since yacc works bottom-up, so does
1459 the first pass of perl compilation.
1461 What makes this pass interesting for perl developers is that some
1462 optimization may be performed on this pass. This is optimization by
1463 so-called I<check routines>. The correspondence between node names
1464 and corresponding check routines is described in F<opcode.pl> (do not
1465 forget to run C<make regen_headers> if you modify this file).
1467 A check routine is called when the node is fully constructed except
1468 for the execution-order thread. Since at this time there are no
1469 back-links to the currently constructed node, one can do most any
1470 operation to the top-level node, including freeing it and/or creating
1471 new nodes above/below it.
1473 The check routine returns the node which should be inserted into the
1474 tree (if the top-level node was not modified, check routine returns
1477 By convention, check routines have names C<ck_*>. They are usually
1478 called from C<new*OP> subroutines (or C<convert>) (which in turn are
1479 called from F<perly.y>).
1481 =head2 Compile pass 1a: constant folding
1483 Immediately after the check routine is called the returned node is
1484 checked for being compile-time executable. If it is (the value is
1485 judged to be constant) it is immediately executed, and a I<constant>
1486 node with the "return value" of the corresponding subtree is
1487 substituted instead. The subtree is deleted.
1489 If constant folding was not performed, the execution-order thread is
1492 =head2 Compile pass 2: context propagation
1494 When a context for a part of compile tree is known, it is propagated
1495 down through the tree. At this time the context can have 5 values
1496 (instead of 2 for runtime context): void, boolean, scalar, list, and
1497 lvalue. In contrast with the pass 1 this pass is processed from top
1498 to bottom: a node's context determines the context for its children.
1500 Additional context-dependent optimizations are performed at this time.
1501 Since at this moment the compile tree contains back-references (via
1502 "thread" pointers), nodes cannot be free()d now. To allow
1503 optimized-away nodes at this stage, such nodes are null()ified instead
1504 of free()ing (i.e. their type is changed to OP_NULL).
1506 =head2 Compile pass 3: peephole optimization
1508 After the compile tree for a subroutine (or for an C<eval> or a file)
1509 is created, an additional pass over the code is performed. This pass
1510 is neither top-down or bottom-up, but in the execution order (with
1511 additional complications for conditionals). These optimizations are
1512 done in the subroutine peep(). Optimizations performed at this stage
1513 are subject to the same restrictions as in the pass 2.
1515 =head1 The Perl Internal API
1517 WARNING: This information is subject to radical changes prior to
1518 the Perl 5.6 release. Use with caution.
1520 =head2 Background and PERL_IMPLICIT_CONTEXT
1522 The Perl interpreter can be regarded as a closed box: it has an API
1523 for feeding it code or otherwise making it do things, but it also has
1524 functions for its own use. This smells a lot like an object, and
1525 there are ways for you to build Perl so that you can have multiple
1526 interpreters, with one interpreter represented either as a C++ object,
1527 a C structure, or inside a thread. The thread, the C structure, or
1528 the C++ object will contain all the context, the state of that
1531 Three macros control the major Perl build flavors: MULTIPLICITY,
1532 USE_THREADS and PERL_OBJECT. The MULTIPLICITY build has a C structure
1533 that packages all the interpreter state, there is a similar thread-specific
1534 data structure under USE_THREADS, and the PERL_OBJECT build has a C++
1535 class to maintain interpreter state. In all three cases,
1536 PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
1537 support for passing in a "hidden" first argument that represents all three
1540 All this obviously requires a way for the Perl internal functions to be
1541 C++ methods, subroutines taking some kind of structure as the first
1542 argument, or subroutines taking nothing as the first argument. To
1543 enable these three very different ways of building the interpreter,
1544 the Perl source (as it does in so many other situations) makes heavy
1545 use of macros and subroutine naming conventions.
1547 First problem: deciding which functions will be public API functions and
1548 which will be private. Those functions whose names begin C<Perl_> are
1549 public, and those whose names begin C<S_> are private (think "S" for
1550 "secret" or "static").
1552 Some functions have no prefix (e.g., restore_rsfp in toke.c). These
1553 are not parts of the object or pseudo-structure because you need to
1554 pass pointers to them to other subroutines.
1556 Second problem: there must be a syntax so that the same subroutine
1557 declarations and calls can pass a structure as their first argument,
1558 or pass nothing. To solve this, the subroutines are named and
1559 declared in a particular way. Here's a typical start of a static
1560 function used within the Perl guts:
1563 S_incline(pTHX_ char *s)
1565 STATIC becomes "static" in C, and is #define'd to nothing in C++.
1567 A public function (i.e. part of the internal API, but not necessarily
1568 sanctioned for use in extensions) begins like this:
1571 Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv)
1573 C<pTHX_> is one of a number of macros (in perl.h) that hide the
1574 details of the interpreter's context. THX stands for "thread", "this",
1575 or "thingy", as the case may be. (And no, George Lucas is not involved. :-)
1576 The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
1577 or 'd' for B<d>eclaration.
1579 When Perl is built without PERL_IMPLICIT_CONTEXT, there is no first
1580 argument containing the interpreter's context. The trailing underscore
1581 in the pTHX_ macro indicates that the macro expansion needs a comma
1582 after the context argument because other arguments follow it. If
1583 PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
1584 subroutine is not prototyped to take the extra argument. The form of the
1585 macro without the trailing underscore is used when there are no additional
1588 When a core function calls another, it must pass the context. This
1589 is normally hidden via macros. Consider C<sv_setsv>. It expands
1590 something like this:
1592 ifdef PERL_IMPLICIT_CONTEXT
1593 define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b)
1594 /* can't do this for vararg functions, see below */
1596 define sv_setsv Perl_sv_setsv
1599 This works well, and means that XS authors can gleefully write:
1603 and still have it work under all the modes Perl could have been
1606 Under PERL_OBJECT in the core, that will translate to either:
1608 CPerlObj::Perl_sv_setsv(foo,bar); # in CPerlObj functions,
1609 # C++ takes care of 'this'
1612 pPerl->Perl_sv_setsv(foo,bar); # in truly static functions,
1615 Under PERL_OBJECT in extensions (aka PERL_CAPI), or under
1616 MULTIPLICITY/USE_THREADS w/ PERL_IMPLICIT_CONTEXT in both core
1617 and extensions, it will be:
1619 Perl_sv_setsv(aTHX_ foo, bar); # the canonical Perl "API"
1620 # for all build flavors
1622 This doesn't work so cleanly for varargs functions, though, as macros
1623 imply that the number of arguments is known in advance. Instead we
1624 either need to spell them out fully, passing C<aTHX_> as the first
1625 argument (the Perl core tends to do this with functions like
1626 Perl_warner), or use a context-free version.
1628 The context-free version of Perl_warner is called
1629 Perl_warner_nocontext, and does not take the extra argument. Instead
1630 it does dTHX; to get the context from thread-local storage. We
1631 C<#define warner Perl_warner_nocontext> so that extensions get source
1632 compatibility at the expense of performance. (Passing an arg is
1633 cheaper than grabbing it from thread-local storage.)
1635 You can ignore [pad]THX[xo] when browsing the Perl headers/sources.
1636 Those are strictly for use within the core. Extensions and embedders
1637 need only be aware of [pad]THX.
1639 =head2 How do I use all this in extensions?
1641 When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
1642 any functions in the Perl API will need to pass the initial context
1643 argument somehow. The kicker is that you will need to write it in
1644 such a way that the extension still compiles when Perl hasn't been
1645 built with PERL_IMPLICIT_CONTEXT enabled.
1647 There are three ways to do this. First, the easy but inefficient way,
1648 which is also the default, in order to maintain source compatibility
1649 with extensions: whenever XSUB.h is #included, it redefines the aTHX
1650 and aTHX_ macros to call a function that will return the context.
1651 Thus, something like:
1655 in your extesion will translate to this when PERL_IMPLICIT_CONTEXT is
1658 Perl_sv_setsv(GetPerlInterpreter(), asv, bsv);
1660 or to this otherwise:
1662 Perl_sv_setsv(asv, bsv);
1664 You have to do nothing new in your extension to get this; since
1665 the Perl library provides GetPerlInterpreter(), it will all just
1668 The second, more efficient way is to use the following template for
1671 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1676 static my_private_function(int arg1, int arg2);
1679 my_private_function(int arg1, int arg2)
1681 dTHX; /* fetch context */
1682 ... call many Perl API functions ...
1687 MODULE = Foo PACKAGE = Foo
1695 my_private_function(arg, 10);
1697 Note that the only two changes from the normal way of writing an
1698 extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before
1699 including the Perl headers, followed by a C<dTHX;> declaration at
1700 the start of every function that will call the Perl API. (You'll
1701 know which functions need this, because the C compiler will complain
1702 that there's an undeclared identifier in those functions.) No changes
1703 are needed for the XSUBs themselves, because the XS() macro is
1704 correctly defined to pass in the implicit context if needed.
1706 The third, even more efficient way is to ape how it is done within
1710 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1715 /* pTHX_ only needed for functions that call Perl API */
1716 static my_private_function(pTHX_ int arg1, int arg2);
1719 my_private_function(pTHX_ int arg1, int arg2)
1721 /* dTHX; not needed here, because THX is an argument */
1722 ... call Perl API functions ...
1727 MODULE = Foo PACKAGE = Foo
1735 my_private_function(aTHX_ arg, 10);
1737 This implementation never has to fetch the context using a function
1738 call, since it is always passed as an extra argument. Depending on
1739 your needs for simplicity or efficiency, you may mix the previous
1740 two approaches freely.
1742 Never add a comma after C<pTHX> yourself--always use the form of the
1743 macro with the underscore for functions that take explicit arguments,
1744 or the form without the argument for functions with no explicit arguments.
1746 =head2 Future Plans and PERL_IMPLICIT_SYS
1748 Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
1749 that the interpreter knows about itself and pass it around, so too are
1750 there plans to allow the interpreter to bundle up everything it knows
1751 about the environment it's running on. This is enabled with the
1752 PERL_IMPLICIT_SYS macro. Currently it only works with PERL_OBJECT,
1753 but is mostly there for MULTIPLICITY and USE_THREADS (see inside
1756 This allows the ability to provide an extra pointer (called the "host"
1757 environment) for all the system calls. This makes it possible for
1758 all the system stuff to maintain their own state, broken down into
1759 seven C structures. These are thin wrappers around the usual system
1760 calls (see win32/perllib.c) for the default perl executable, but for a
1761 more ambitious host (like the one that would do fork() emulation) all
1762 the extra work needed to pretend that different interpreters are
1763 actually different "processes", would be done here.
1765 The Perl engine/interpreter and the host are orthogonal entities.
1766 There could be one or more interpreters in a process, and one or
1767 more "hosts", with free association between them.
1771 This is a listing of functions, macros, flags, and variables that may be
1772 used by extension writers. The interfaces of any functions that are not
1773 listed here are subject to change without notice. For this reason,
1774 blindly using functions listed in proto.h is to be avoided when writing
1777 Note that all Perl API global variables must be referenced with the C<PL_>
1778 prefix. Some macros are provided for compatibility with the older,
1779 unadorned names, but this support may be disabled in a future release.
1781 The sort order of the listing is case insensitive, with any
1782 occurrences of '_' ignored for the purpose of sorting.
1788 Clears an array, making it empty. Does not free the memory used by the
1791 void av_clear (AV* ar)
1795 Pre-extend an array. The C<key> is the index to which the array should be
1798 void av_extend (AV* ar, I32 key)
1802 Returns the SV at the specified index in the array. The C<key> is the
1803 index. If C<lval> is set then the fetch will be part of a store. Check
1804 that the return value is non-null before dereferencing it to a C<SV*>.
1806 See L<Understanding the Magic of Tied Hashes and Arrays> for more
1807 information on how to use this function on tied arrays.
1809 SV** av_fetch (AV* ar, I32 key, I32 lval)
1813 Same as C<av_len()>. Deprecated, use C<av_len()> instead.
1817 Returns the highest index in the array. Returns -1 if the array is empty.
1823 Creates a new AV and populates it with a list of SVs. The SVs are copied
1824 into the array, so they may be freed after the call to av_make. The new AV
1825 will have a reference count of 1.
1827 AV* av_make (I32 size, SV** svp)
1831 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is
1838 Pushes an SV onto the end of the array. The array will grow automatically
1839 to accommodate the addition.
1841 void av_push (AV* ar, SV* val)
1845 Shifts an SV off the beginning of the array.
1847 SV* av_shift (AV* ar)
1851 Stores an SV in an array. The array index is specified as C<key>. The
1852 return value will be NULL if the operation failed or if the value did not
1853 need to be actually stored within the array (as in the case of tied arrays).
1854 Otherwise it can be dereferenced to get the original C<SV*>. Note that the
1855 caller is responsible for suitably incrementing the reference count of C<val>
1856 before the call, and decrementing it if the function returned NULL.
1858 See L<Understanding the Magic of Tied Hashes and Arrays> for more
1859 information on how to use this function on tied arrays.
1861 SV** av_store (AV* ar, I32 key, SV* val)
1865 Undefines the array. Frees the memory used by the array itself.
1867 void av_undef (AV* ar)
1871 Unshift the given number of C<undef> values onto the beginning of the
1872 array. The array will grow automatically to accommodate the addition.
1873 You must then use C<av_store> to assign values to these new elements.
1875 void av_unshift (AV* ar, I32 num)
1879 Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
1880 constructor. This is always a C<char*>. See C<THIS> and
1881 L<perlxs/"Using XS With C++">.
1885 The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1886 source, C<d> is the destination, C<n> is the number of items, and C<t> is
1887 the type. May fail on overlapping copies. See also C<Move>.
1889 void Copy( s, d, n, t )
1893 This is the XSUB-writer's interface to Perl's C<die> function. Use this
1894 function the same way you use the C C<printf> function. See C<warn>.
1898 Returns the stash of the CV.
1900 HV* CvSTASH( SV* sv )
1904 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1905 boolean which indicates whether subs are being single-stepped.
1906 Single-stepping is automatically turned on after every step. This is the C
1907 variable which corresponds to Perl's $DB::single variable. See C<PL_DBsub>.
1911 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1912 the SV which holds the name of the sub being debugged. This is the C
1913 variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>.
1914 The sub name can be found by
1916 SvPV( GvSV( PL_DBsub ), len )
1920 Trace variable used when Perl is run in debugging mode, with the B<-d>
1921 switch. This is the C variable which corresponds to Perl's $DB::trace
1922 variable. See C<PL_DBsingle>.
1926 Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1931 Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1935 The C variable which corresponds to Perl's $^W warning variable.
1939 Declares a local copy of perl's stack pointer for the XSUB, available via
1940 the C<SP> macro. See C<SP>.
1944 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1945 usually handled automatically by C<xsubpp>. Declares the C<items> variable
1946 to indicate the number of items on the stack.
1950 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1951 handled automatically by C<xsubpp>.
1955 Switches filehandle to binmode. C<iotype> is what C<IoTYPE(io)> would
1958 do_binmode(fp, iotype, TRUE);
1962 Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1968 Used to extend the argument stack for an XSUB's return values.
1974 Analyses the string in order to make fast searches on it using fbm_instr() --
1975 the Boyer-Moore algorithm.
1977 void fbm_compile(SV* sv, U32 flags)
1981 Returns the location of the SV in the string delimited by C<str> and
1982 C<strend>. It returns C<Nullch> if the string can't be found. The
1983 C<sv> does not have to be fbm_compiled, but the search will not be as
1986 char* fbm_instr(char *str, char *strend, SV *sv, U32 flags)
1990 Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1997 Used to indicate array context. See C<GIMME_V>, C<GIMME> and L<perlcall>.
2001 Indicates that arguments returned from a callback should be discarded. See
2006 Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
2010 A backward-compatible version of C<GIMME_V> which can only return
2011 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
2015 The XSUB-writer's equivalent to Perl's C<wantarray>. Returns
2016 C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
2017 context, respectively.
2021 Indicates that no arguments are being sent to a callback. See L<perlcall>.
2025 Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>.
2029 Returns the glob with the given C<name> and a defined subroutine or
2030 C<NULL>. The glob lives in the given C<stash>, or in the stashes
2031 accessible via @ISA and @UNIVERSAL.
2033 The argument C<level> should be either 0 or -1. If C<level==0>, as a
2034 side-effect creates a glob with the given C<name> in the given
2035 C<stash> which in the case of success contains an alias for the
2036 subroutine, and sets up caching info for this glob. Similarly for all
2037 the searched stashes.
2039 This function grants C<"SUPER"> token as a postfix of the stash name.
2041 The GV returned from C<gv_fetchmeth> may be a method cache entry,
2042 which is not visible to Perl code. So when calling C<perl_call_sv>,
2043 you should not use the GV directly; instead, you should use the
2044 method's CV, which can be obtained from the GV with the C<GvCV> macro.
2046 GV* gv_fetchmeth (HV* stash, const char* name, STRLEN len, I32 level)
2048 =item gv_fetchmethod
2050 =item gv_fetchmethod_autoload
2052 Returns the glob which contains the subroutine to call to invoke the
2053 method on the C<stash>. In fact in the presence of autoloading this may
2054 be the glob for "AUTOLOAD". In this case the corresponding variable
2055 $AUTOLOAD is already setup.
2057 The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
2058 lookup is performed if the given method is not present: non-zero means
2059 yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling
2060 C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
2061 non-zero C<autoload> parameter.
2063 These functions grant C<"SUPER"> token as a prefix of the method name.
2065 Note that if you want to keep the returned glob for a long time, you
2066 need to check for it being "AUTOLOAD", since at the later time the call
2067 may load a different subroutine due to $AUTOLOAD changing its value.
2068 Use the glob created via a side effect to do this.
2070 These functions have the same side-effects and as C<gv_fetchmeth> with
2071 C<level==0>. C<name> should be writable if contains C<':'> or C<'\''>.
2072 The warning against passing the GV returned by C<gv_fetchmeth> to
2073 C<perl_call_sv> apply equally to these functions.
2075 GV* gv_fetchmethod (HV* stash, const char* name)
2076 GV* gv_fetchmethod_autoload (HV* stash, const char* name, I32 autoload)
2080 Used to indicate void context. See C<GIMME_V> and L<perlcall>.
2084 Returns a pointer to the stash for a specified package. If C<create> is set
2085 then the package will be created if it does not already exist. If C<create>
2086 is not set and the package does not exist then NULL is returned.
2088 HV* gv_stashpv (const char* name, I32 create)
2092 Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
2094 HV* gv_stashsv (SV* sv, I32 create)
2098 Return the SV from the GV.
2102 This flag, used in the length slot of hash entries and magic
2103 structures, specifies the structure contains a C<SV*> pointer where a
2104 C<char*> pointer is to be expected. (For information only--not to be used).
2108 Returns the computed hash stored in the hash entry.
2114 Returns the actual pointer stored in the key slot of the hash entry.
2115 The pointer may be either C<char*> or C<SV*>, depending on the value of
2116 C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros
2117 are usually preferable for finding the value of a key.
2123 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
2124 holds an C<SV*> key. Otherwise, holds the actual length of the key.
2125 Can be assigned to. The C<HePV()> macro is usually preferable for finding
2132 Returns the key slot of the hash entry as a C<char*> value, doing any
2133 necessary dereferencing of possibly C<SV*> keys. The length of
2134 the string is placed in C<len> (this is a macro, so do I<not> use
2135 C<&len>). If you do not care about what the length of the key is,
2136 you may use the global variable C<PL_na>, though this is rather less
2137 efficient than using a local variable. Remember though, that hash
2138 keys in perl are free to contain embedded nulls, so using C<strlen()>
2139 or similar is not a good way to find the length of hash keys.
2140 This is very similar to the C<SvPV()> macro described elsewhere in
2143 char* HePV(HE* he, STRLEN len)
2147 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
2148 does not contain an C<SV*> key.
2154 Returns the key as an C<SV*>. Will create and return a temporary
2155 mortal C<SV*> if the hash entry contains only a C<char*> key.
2157 HeSVKEY_force(HE* he)
2161 Sets the key to a given C<SV*>, taking care to set the appropriate flags
2162 to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
2164 HeSVKEY_set(HE* he, SV* sv)
2168 Returns the value slot (type C<SV*>) stored in the hash entry.
2174 Clears a hash, making it empty.
2176 void hv_clear (HV* tb)
2180 Deletes a key/value pair in the hash. The value SV is removed from the hash
2181 and returned to the caller. The C<klen> is the length of the key. The
2182 C<flags> value will normally be zero; if set to G_DISCARD then NULL will be
2185 SV* hv_delete (HV* tb, const char* key, U32 klen, I32 flags)
2189 Deletes a key/value pair in the hash. The value SV is removed from the hash
2190 and returned to the caller. The C<flags> value will normally be zero; if set
2191 to G_DISCARD then NULL will be returned. C<hash> can be a valid precomputed
2192 hash value, or 0 to ask for it to be computed.
2194 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash)
2198 Returns a boolean indicating whether the specified hash key exists. The
2199 C<klen> is the length of the key.
2201 bool hv_exists (HV* tb, const char* key, U32 klen)
2205 Returns a boolean indicating whether the specified hash key exists. C<hash>
2206 can be a valid precomputed hash value, or 0 to ask for it to be computed.
2208 bool hv_exists_ent (HV* tb, SV* key, U32 hash)
2212 Returns the SV which corresponds to the specified key in the hash. The
2213 C<klen> is the length of the key. If C<lval> is set then the fetch will be
2214 part of a store. Check that the return value is non-null before
2215 dereferencing it to a C<SV*>.
2217 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2218 information on how to use this function on tied hashes.
2220 SV** hv_fetch (HV* tb, const char* key, U32 klen, I32 lval)
2224 Returns the hash entry which corresponds to the specified key in the hash.
2225 C<hash> must be a valid precomputed hash number for the given C<key>, or
2226 0 if you want the function to compute it. IF C<lval> is set then the
2227 fetch will be part of a store. Make sure the return value is non-null
2228 before accessing it. The return value when C<tb> is a tied hash
2229 is a pointer to a static location, so be sure to make a copy of the
2230 structure if you need to store it somewhere.
2232 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2233 information on how to use this function on tied hashes.
2235 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash)
2239 Prepares a starting point to traverse a hash table.
2241 I32 hv_iterinit (HV* tb)
2243 Returns the number of keys in the hash (i.e. the same as C<HvKEYS(tb)>).
2244 The return value is currently only meaningful for hashes without tie
2247 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number
2248 of hash buckets that happen to be in use. If you still need that
2249 esoteric value, you can get it through the macro C<HvFILL(tb)>.
2253 Returns the key from the current position of the hash iterator. See
2256 char* hv_iterkey (HE* entry, I32* retlen)
2260 Returns the key as an C<SV*> from the current position of the hash
2261 iterator. The return value will always be a mortal copy of the
2262 key. Also see C<hv_iterinit>.
2264 SV* hv_iterkeysv (HE* entry)
2268 Returns entries from a hash iterator. See C<hv_iterinit>.
2270 HE* hv_iternext (HV* tb)
2274 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
2277 SV* hv_iternextsv (HV* hv, char** key, I32* retlen)
2281 Returns the value from the current position of the hash iterator. See
2284 SV* hv_iterval (HV* tb, HE* entry)
2288 Adds magic to a hash. See C<sv_magic>.
2290 void hv_magic (HV* hv, GV* gv, int how)
2294 Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
2296 char* HvNAME (HV* stash)
2300 Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
2301 the length of the key. The C<hash> parameter is the precomputed hash
2302 value; if it is zero then Perl will compute it. The return value will be
2303 NULL if the operation failed or if the value did not need to be actually
2304 stored within the hash (as in the case of tied hashes). Otherwise it can
2305 be dereferenced to get the original C<SV*>. Note that the caller is
2306 responsible for suitably incrementing the reference count of C<val>
2307 before the call, and decrementing it if the function returned NULL.
2309 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2310 information on how to use this function on tied hashes.
2312 SV** hv_store (HV* tb, const char* key, U32 klen, SV* val, U32 hash)
2316 Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
2317 parameter is the precomputed hash value; if it is zero then Perl will
2318 compute it. The return value is the new hash entry so created. It will be
2319 NULL if the operation failed or if the value did not need to be actually
2320 stored within the hash (as in the case of tied hashes). Otherwise the
2321 contents of the return value can be accessed using the C<He???> macros
2322 described here. Note that the caller is responsible for suitably
2323 incrementing the reference count of C<val> before the call, and decrementing
2324 it if the function returned NULL.
2326 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2327 information on how to use this function on tied hashes.
2329 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash)
2335 void hv_undef (HV* tb)
2339 Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
2342 int isALNUM (char c)
2346 Returns a boolean indicating whether the C C<char> is an ascii alphabetic
2349 int isALPHA (char c)
2353 Returns a boolean indicating whether the C C<char> is an ascii digit.
2355 int isDIGIT (char c)
2359 Returns a boolean indicating whether the C C<char> is a lowercase character.
2361 int isLOWER (char c)
2365 Returns a boolean indicating whether the C C<char> is whitespace.
2367 int isSPACE (char c)
2371 Returns a boolean indicating whether the C C<char> is an uppercase character.
2373 int isUPPER (char c)
2377 Variable which is setup by C<xsubpp> to indicate the number of items on the
2378 stack. See L<perlxs/"Variable-length Parameter Lists">.
2382 Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
2383 was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
2387 Closing bracket on a callback. See C<ENTER> and L<perlcall>.
2391 =item looks_like_number
2393 Test if an the content of an SV looks like a number (or is a number).
2395 int looks_like_number(SV*)
2400 Stack marker variable for the XSUB. See C<dMARK>.
2404 Clear something magical that the SV represents. See C<sv_magic>.
2406 int mg_clear (SV* sv)
2410 Copies the magic from one SV to another. See C<sv_magic>.
2412 int mg_copy (SV *, SV *, const char *, STRLEN)
2416 Finds the magic pointer for type matching the SV. See C<sv_magic>.
2418 MAGIC* mg_find (SV* sv, int type)
2422 Free any magic storage used by the SV. See C<sv_magic>.
2424 int mg_free (SV* sv)
2428 Do magic after a value is retrieved from the SV. See C<sv_magic>.
2434 Report on the SV's length. See C<sv_magic>.
2440 Turns on the magical status of an SV. See C<sv_magic>.
2442 void mg_magical (SV* sv)
2446 Do magic after a value is assigned to the SV. See C<sv_magic>.
2452 C<modglobal> is a general purpose, interpreter global HV for use by
2453 extensions that need to keep information on a per-interpreter basis.
2454 In a pinch, it can also be used as a symbol table for extensions
2455 to share data among each other. It is a good idea to use keys
2456 prefixed by the package name of the extension that owns the data.
2460 The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
2461 source, C<d> is the destination, C<n> is the number of items, and C<t> is
2462 the type. Can do overlapping moves. See also C<Copy>.
2464 void Move( s, d, n, t )
2468 A convenience variable which is typically used with C<SvPV> when one doesn't
2469 care about the length of the string. It is usually more efficient to
2470 either declare a local variable and use that instead or to use the C<SvPV_nolen>
2475 The XSUB-writer's interface to the C C<malloc> function.
2477 void* New( x, void *ptr, int size, type )
2481 Creates a new AV. The reference count is set to 1.
2487 The XSUB-writer's interface to the C C<malloc> function, with cast.
2489 void* Newc( x, void *ptr, int size, type, cast )
2493 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }>
2494 which is eligible for inlining at compile-time.
2496 void newCONSTSUB(HV* stash, char* name, SV* sv)
2500 Creates a new HV. The reference count is set to 1.
2506 Creates an RV wrapper for an SV. The reference count for the original SV is
2509 SV* newRV_inc (SV* ref)
2511 For historical reasons, "newRV" is a synonym for "newRV_inc".
2515 Creates an RV wrapper for an SV. The reference count for the original
2516 SV is B<not> incremented.
2518 SV* newRV_noinc (SV* ref)
2522 Creates a new SV. A non-zero C<len> parameter indicates the number of
2523 bytes of preallocated string space the SV should have. An extra byte
2524 for a tailing NUL is also reserved. (SvPOK is not set for the SV even
2525 if string space is allocated.) The reference count for the new SV is
2526 set to 1. C<id> is an integer id between 0 and 1299 (used to identify
2529 SV* NEWSV (int id, STRLEN len)
2533 Creates a new SV and copies an integer into it. The reference count for the
2540 Creates a new SV and copies a double into it. The reference count for the
2547 Creates a new SV and copies a string into it. The reference count for the
2548 SV is set to 1. If C<len> is zero, Perl will compute the length using
2549 strlen(). For efficiency, consider using C<newSVpvn> instead.
2551 SV* newSVpv (const char* s, STRLEN len)
2555 Creates a new SV an initialize it with the string formatted like
2558 SV* newSVpvf(const char* pat, ...)
2562 Creates a new SV and copies a string into it. The reference count for the
2563 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
2564 string. You are responsible for ensuring that the source string is at least
2567 SV* newSVpvn (const char* s, STRLEN len)
2571 Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
2572 it will be upgraded to one. If C<classname> is non-null then the new SV will
2573 be blessed in the specified package. The new SV is returned and its
2574 reference count is 1.
2576 SV* newSVrv (SV* rv, const char* classname)
2580 Creates a new SV which is an exact duplicate of the original SV.
2582 SV* newSVsv (SV* old)
2586 Used by C<xsubpp> to hook up XSUBs as Perl subs.
2590 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
2595 The XSUB-writer's interface to the C C<malloc> function. The allocated
2596 memory is zeroed with C<memzero>.
2598 void* Newz( x, void *ptr, int size, type )
2606 Null character pointer.
2622 The original stack mark for the XSUB. See C<dORIGMARK>.
2626 Allocates a new Perl interpreter. See L<perlembed>.
2628 =item perl_call_argv
2630 Performs a callback to the specified Perl sub. See L<perlcall>.
2632 I32 perl_call_argv (const char* subname, I32 flags, char** argv)
2634 =item perl_call_method
2636 Performs a callback to the specified Perl method. The blessed object must
2637 be on the stack. See L<perlcall>.
2639 I32 perl_call_method (const char* methname, I32 flags)
2643 Performs a callback to the specified Perl sub. See L<perlcall>.
2645 I32 perl_call_pv (const char* subname, I32 flags)
2649 Performs a callback to the Perl sub whose name is in the SV. See
2652 I32 perl_call_sv (SV* sv, I32 flags)
2654 =item perl_construct
2656 Initializes a new Perl interpreter. See L<perlembed>.
2660 Shuts down a Perl interpreter. See L<perlembed>.
2664 Tells Perl to C<eval> the string in the SV.
2666 I32 perl_eval_sv (SV* sv, I32 flags)
2670 Tells Perl to C<eval> the given string and return an SV* result.
2672 SV* perl_eval_pv (const char* p, I32 croak_on_error)
2676 Releases a Perl interpreter. See L<perlembed>.
2680 Returns the AV of the specified Perl array. If C<create> is set and the
2681 Perl variable does not exist then it will be created. If C<create> is not
2682 set and the variable does not exist then NULL is returned.
2684 AV* perl_get_av (const char* name, I32 create)
2688 Returns the CV of the specified Perl subroutine. If C<create> is set and
2689 the Perl subroutine does not exist then it will be declared (which has
2690 the same effect as saying C<sub name;>). If C<create> is not
2691 set and the subroutine does not exist then NULL is returned.
2693 CV* perl_get_cv (const char* name, I32 create)
2697 Returns the HV of the specified Perl hash. If C<create> is set and the Perl
2698 variable does not exist then it will be created. If C<create> is not
2699 set and the variable does not exist then NULL is returned.
2701 HV* perl_get_hv (const char* name, I32 create)
2705 Returns the SV of the specified Perl scalar. If C<create> is set and the
2706 Perl variable does not exist then it will be created. If C<create> is not
2707 set and the variable does not exist then NULL is returned.
2709 SV* perl_get_sv (const char* name, I32 create)
2713 Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
2715 =item perl_require_pv
2717 Tells Perl to C<require> a module.
2719 void perl_require_pv (const char* pv)
2723 Tells a Perl interpreter to run. See L<perlembed>.
2727 Pops an integer off the stack.
2733 Pops a long off the stack.
2739 Pops a string off the stack.
2745 Pops a double off the stack.
2751 Pops an SV off the stack.
2757 Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
2763 Push an integer onto the stack. The stack must have room for this element.
2764 Handles 'set' magic. See C<XPUSHi>.
2770 Push a double onto the stack. The stack must have room for this element.
2771 Handles 'set' magic. See C<XPUSHn>.
2773 void PUSHn(double d)
2777 Push a string onto the stack. The stack must have room for this element.
2778 The C<len> indicates the length of the string. Handles 'set' magic. See
2781 void PUSHp(char *c, int len )
2785 Push an SV onto the stack. The stack must have room for this element. Does
2786 not handle 'set' magic. See C<XPUSHs>.
2792 Push an unsigned integer onto the stack. The stack must have room for
2793 this element. See C<XPUSHu>.
2795 void PUSHu(unsigned int d)
2800 Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2801 See C<PUSHMARK> and L<perlcall> for other uses.
2807 The XSUB-writer's interface to the C C<realloc> function.
2809 void* Renew( void *ptr, int size, type )
2813 The XSUB-writer's interface to the C C<realloc> function, with cast.
2815 void* Renewc( void *ptr, int size, type, cast )
2819 Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
2820 This is always the proper type for the XSUB.
2821 See L<perlxs/"The RETVAL Variable">.
2825 The XSUB-writer's interface to the C C<free> function.
2829 The XSUB-writer's interface to the C C<malloc> function.
2833 The XSUB-writer's interface to the C C<realloc> function.
2837 Copy a string to a safe spot. This does not use an SV.
2839 char* savepv (const char* sv)
2843 Copy a string to a safe spot. The C<len> indicates number of bytes to
2844 copy. This does not use an SV.
2846 char* savepvn (const char* sv, I32 len)
2850 Opening bracket for temporaries on a callback. See C<FREETMPS> and
2857 Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2862 Refetch the stack pointer. Used after a callback. See L<perlcall>.
2868 Used to access elements on the XSUB's stack.
2874 Test two strings to see if they are equal. Returns true or false.
2876 int strEQ( char *s1, char *s2 )
2880 Test two strings to see if the first, C<s1>, is greater than or equal to the
2881 second, C<s2>. Returns true or false.
2883 int strGE( char *s1, char *s2 )
2887 Test two strings to see if the first, C<s1>, is greater than the second,
2888 C<s2>. Returns true or false.
2890 int strGT( char *s1, char *s2 )
2894 Test two strings to see if the first, C<s1>, is less than or equal to the
2895 second, C<s2>. Returns true or false.
2897 int strLE( char *s1, char *s2 )
2901 Test two strings to see if the first, C<s1>, is less than the second,
2902 C<s2>. Returns true or false.
2904 int strLT( char *s1, char *s2 )
2908 Test two strings to see if they are different. Returns true or false.
2910 int strNE( char *s1, char *s2 )
2914 Test two strings to see if they are equal. The C<len> parameter indicates
2915 the number of bytes to compare. Returns true or false.
2916 (A wrapper for C<strncmp>).
2918 int strnEQ( const char *s1, const char *s2, size_t len )
2922 Test two strings to see if they are different. The C<len> parameter
2923 indicates the number of bytes to compare. Returns true or false.
2924 (A wrapper for C<strncmp>).
2926 int strnNE( const char *s1, const char *s2, size_t len )
2930 Marks an SV as mortal. The SV will be destroyed when the current context
2933 SV* sv_2mortal (SV* sv)
2937 Blesses an SV into a specified package. The SV must be an RV. The package
2938 must be designated by its stash (see C<gv_stashpv()>). The reference count
2939 of the SV is unaffected.
2941 SV* sv_bless (SV* sv, HV* stash)
2945 Concatenates the string onto the end of the string which is in the SV.
2946 Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
2948 void sv_catpv (SV* sv, const char* ptr)
2952 Like C<sv_catpv>, but also handles 'set' magic.
2954 void sv_catpvn (SV* sv, const char* ptr)
2958 Concatenates the string onto the end of the string which is in the SV. The
2959 C<len> indicates number of bytes to copy. Handles 'get' magic, but not
2960 'set' magic. See C<sv_catpvn_mg>.
2962 void sv_catpvn (SV* sv, const char* ptr, STRLEN len)
2966 Like C<sv_catpvn>, but also handles 'set' magic.
2968 void sv_catpvn_mg (SV* sv, const char* ptr, STRLEN len)
2972 Processes its arguments like C<sprintf> and appends the formatted output
2973 to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
2974 typically be called after calling this function to handle 'set' magic.
2976 void sv_catpvf (SV* sv, const char* pat, ...)
2980 Like C<sv_catpvf>, but also handles 'set' magic.
2982 void sv_catpvf_mg (SV* sv, const char* pat, ...)
2986 Concatenates the string from SV C<ssv> onto the end of the string in SV
2987 C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
2989 void sv_catsv (SV* dsv, SV* ssv)
2993 Like C<sv_catsv>, but also handles 'set' magic.
2995 void sv_catsv_mg (SV* dsv, SV* ssv)
2999 Efficient removal of characters from the beginning of the string
3000 buffer. SvPOK(sv) must be true and the C<ptr> must be a pointer to
3001 somewhere inside the string buffer. The C<ptr> becomes the first
3002 character of the adjusted string.
3004 void sv_chop(SV* sv, const char *ptr)
3009 Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
3010 string in C<sv1> is less than, equal to, or greater than the string in
3013 I32 sv_cmp (SV* sv1, SV* sv2)
3017 Returns the length of the string which is in the SV. See C<SvLEN>.
3023 Set the length of the string which is in the SV. See C<SvCUR>.
3025 void SvCUR_set (SV* sv, int val)
3029 Auto-decrement of the value in the SV.
3031 void sv_dec (SV* sv)
3033 =item sv_derived_from
3035 Returns a boolean indicating whether the SV is derived from the specified
3036 class. This is the function that implements C<UNIVERSAL::isa>. It works
3037 for class names as well as for objects.
3039 bool sv_derived_from (SV* sv, const char* name);
3043 Returns a pointer to the last character in the string which is in the SV.
3044 See C<SvCUR>. Access the character as
3050 Returns a boolean indicating whether the strings in the two SVs are
3053 I32 sv_eq (SV* sv1, SV* sv2)
3057 Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates
3058 its argument more than once.
3060 void SvGETMAGIC(SV *sv)
3064 Expands the character buffer in the SV so that it has room for the
3065 indicated number of bytes (remember to reserve space for an extra
3066 trailing NUL character). Calls C<sv_grow> to perform the expansion if
3067 necessary. Returns a pointer to the character buffer.
3069 char* SvGROW(SV* sv, STRLEN len)
3073 Expands the character buffer in the SV. This will use C<sv_unref> and will
3074 upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
3079 Auto-increment of the value in the SV.
3081 void sv_inc (SV* sv)
3085 Inserts a string at the specified offset/length within the SV.
3086 Similar to the Perl substr() function.
3088 void sv_insert(SV *sv, STRLEN offset, STRLEN len,
3089 char *str, STRLEN strlen)
3093 Returns a boolean indicating whether the SV contains an integer.
3099 Unsets the IV status of an SV.
3101 void SvIOK_off (SV* sv)
3105 Tells an SV that it is an integer.
3107 void SvIOK_on (SV* sv)
3111 Tells an SV that it is an integer and disables all other OK bits.
3113 void SvIOK_only (SV* sv)
3117 Returns a boolean indicating whether the SV contains an integer. Checks the
3118 B<private> setting. Use C<SvIOK>.
3124 Returns a boolean indicating whether the SV is blessed into the specified
3125 class. This does not check for subtypes; use C<sv_derived_from> to verify
3126 an inheritance relationship.
3128 int sv_isa (SV* sv, char* name)
3132 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3133 object. If the SV is not an RV, or if the object is not blessed, then this
3136 int sv_isobject (SV* sv)
3140 Coerces the given SV to an integer and returns it.
3146 Returns the integer which is stored in the SV, assuming SvIOK is true.
3152 Returns the size of the string buffer in the SV. See C<SvCUR>.
3158 Returns the length of the string in the SV. Use C<SvCUR>.
3160 STRLEN sv_len (SV* sv)
3164 Adds magic to an SV.
3166 void sv_magic (SV* sv, SV* obj, int how, const char* name, I32 namlen)
3170 Creates a new SV which is a copy of the original SV. The new SV is marked
3173 SV* sv_mortalcopy (SV* oldsv)
3177 Creates a new SV which is mortal. The reference count of the SV is set to 1.
3179 SV* sv_newmortal (void)
3183 Returns a boolean indicating whether the SV contains a number, integer or
3190 Unsets the NV/IV status of an SV.
3192 void SvNIOK_off (SV* sv)
3196 Returns a boolean indicating whether the SV contains a number, integer or
3197 double. Checks the B<private> setting. Use C<SvNIOK>.
3199 int SvNIOKp (SV* SV)
3203 This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as C<&PL_sv_no>.
3207 Returns a boolean indicating whether the SV contains a double.
3213 Unsets the NV status of an SV.
3215 void SvNOK_off (SV* sv)
3219 Tells an SV that it is a double.
3221 void SvNOK_on (SV* sv)
3225 Tells an SV that it is a double and disables all other OK bits.
3227 void SvNOK_only (SV* sv)
3231 Returns a boolean indicating whether the SV contains a double. Checks the
3232 B<private> setting. Use C<SvNOK>.
3238 Coerce the given SV to a double and return it.
3240 double SvNV (SV* sv)
3244 Returns the double which is stored in the SV, assuming SvNOK is true.
3246 double SvNVX (SV* sv)
3250 Returns a boolean indicating whether the value is an SV.
3256 Returns a boolean indicating whether the SvIVX is a valid offset value
3257 for the SvPVX. This hack is used internally to speed up removal of
3258 characters from the beginning of a SvPV. When SvOOK is true, then the
3259 start of the allocated string buffer is really (SvPVX - SvIVX).
3265 Returns a boolean indicating whether the SV contains a character string.
3271 Unsets the PV status of an SV.
3273 void SvPOK_off (SV* sv)
3277 Tells an SV that it is a string.
3279 void SvPOK_on (SV* sv)
3283 Tells an SV that it is a string and disables all other OK bits.
3285 void SvPOK_only (SV* sv)
3289 Returns a boolean indicating whether the SV contains a character string.
3290 Checks the B<private> setting. Use C<SvPOK>.
3296 Returns a pointer to the string in the SV, or a stringified form of the SV
3297 if the SV does not contain a string. Handles 'get' magic.
3299 char* SvPV (SV* sv, STRLEN len)
3303 Like <SvPV> but will force the SV into becoming a string (SvPOK). You
3304 want force if you are going to update the SvPVX directly.
3306 char* SvPV_force(SV* sv, STRLEN len)
3310 Returns a pointer to the string in the SV, or a stringified form of the SV
3311 if the SV does not contain a string. Handles 'get' magic.
3313 char* SvPV_nolen (SV* sv)
3317 Returns a pointer to the string in the SV. The SV must contain a string.
3319 char* SvPVX (SV* sv)
3323 Returns the value of the object's reference count.
3325 int SvREFCNT (SV* sv)
3329 Decrements the reference count of the given SV.
3331 void SvREFCNT_dec (SV* sv)
3335 Increments the reference count of the given SV.
3337 void SvREFCNT_inc (SV* sv)
3341 Tests if the SV is an RV.
3347 Unsets the RV status of an SV.
3349 void SvROK_off (SV* sv)
3353 Tells an SV that it is an RV.
3355 void SvROK_on (SV* sv)
3359 Dereferences an RV to return the SV.
3365 Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates
3366 its argument more than once.
3368 void SvSETMAGIC( SV *sv )
3372 Copies an integer into the given SV. Does not handle 'set' magic.
3375 void sv_setiv (SV* sv, IV num)
3379 Like C<sv_setiv>, but also handles 'set' magic.
3381 void sv_setiv_mg (SV* sv, IV num)
3385 Copies a double into the given SV. Does not handle 'set' magic.
3388 void sv_setnv (SV* sv, double num)
3392 Like C<sv_setnv>, but also handles 'set' magic.
3394 void sv_setnv_mg (SV* sv, double num)
3398 Copies a string into an SV. The string must be null-terminated.
3399 Does not handle 'set' magic. See C<sv_setpv_mg>.
3401 void sv_setpv (SV* sv, const char* ptr)
3405 Like C<sv_setpv>, but also handles 'set' magic.
3407 void sv_setpv_mg (SV* sv, const char* ptr)
3411 Copies an integer into the given SV, also updating its string value.
3412 Does not handle 'set' magic. See C<sv_setpviv_mg>.
3414 void sv_setpviv (SV* sv, IV num)
3418 Like C<sv_setpviv>, but also handles 'set' magic.
3420 void sv_setpviv_mg (SV* sv, IV num)
3424 Copies a string into an SV. The C<len> parameter indicates the number of
3425 bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
3427 void sv_setpvn (SV* sv, const char* ptr, STRLEN len)
3431 Like C<sv_setpvn>, but also handles 'set' magic.
3433 void sv_setpvn_mg (SV* sv, const char* ptr, STRLEN len)
3437 Processes its arguments like C<sprintf> and sets an SV to the formatted
3438 output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
3440 void sv_setpvf (SV* sv, const char* pat, ...)
3444 Like C<sv_setpvf>, but also handles 'set' magic.
3446 void sv_setpvf_mg (SV* sv, const char* pat, ...)
3450 Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3451 argument will be upgraded to an RV. That RV will be modified to point to
3452 the new SV. The C<classname> argument indicates the package for the
3453 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3454 will be returned and will have a reference count of 1.
3456 SV* sv_setref_iv (SV *rv, char *classname, IV iv)
3460 Copies a double into a new SV, optionally blessing the SV. The C<rv>
3461 argument will be upgraded to an RV. That RV will be modified to point to
3462 the new SV. The C<classname> argument indicates the package for the
3463 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3464 will be returned and will have a reference count of 1.
3466 SV* sv_setref_nv (SV *rv, char *classname, double nv)
3470 Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3471 argument will be upgraded to an RV. That RV will be modified to point to
3472 the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
3473 into the SV. The C<classname> argument indicates the package for the
3474 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3475 will be returned and will have a reference count of 1.
3477 SV* sv_setref_pv (SV *rv, char *classname, void* pv)
3479 Do not use with integral Perl types such as HV, AV, SV, CV, because those
3480 objects will become corrupted by the pointer copy process.
3482 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3486 Copies a string into a new SV, optionally blessing the SV. The length of the
3487 string must be specified with C<n>. The C<rv> argument will be upgraded to
3488 an RV. That RV will be modified to point to the new SV. The C<classname>
3489 argument indicates the package for the blessing. Set C<classname> to
3490 C<Nullch> to avoid the blessing. The new SV will be returned and will have
3491 a reference count of 1.
3493 SV* sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n)
3495 Note that C<sv_setref_pv> copies the pointer while this copies the string.
3499 Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
3502 void SvSetSV (SV* dsv, SV* ssv)
3504 =item SvSetSV_nosteal
3506 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as ssv.
3507 May evaluate arguments more than once.
3509 void SvSetSV_nosteal (SV* dsv, SV* ssv)
3513 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
3514 The source SV may be destroyed if it is mortal. Does not handle 'set' magic.
3515 See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and C<sv_setsv_mg>.
3517 void sv_setsv (SV* dsv, SV* ssv)
3521 Like C<sv_setsv>, but also handles 'set' magic.
3523 void sv_setsv_mg (SV* dsv, SV* ssv)
3527 Copies an unsigned integer into the given SV. Does not handle 'set' magic.
3530 void sv_setuv (SV* sv, UV num)
3534 Like C<sv_setuv>, but also handles 'set' magic.
3536 void sv_setuv_mg (SV* sv, UV num)
3540 Returns the stash of the SV.
3542 HV* SvSTASH (SV* sv)
3546 Taints an SV if tainting is enabled
3548 void SvTAINT (SV* sv)
3552 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.
3554 int SvTAINTED (SV* sv)
3558 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3559 some of Perl's fundamental security features. XS module authors should
3560 not use this function unless they fully understand all the implications
3561 of unconditionally untainting the value. Untainting should be done in
3562 the standard perl fashion, via a carefully crafted regexp, rather than
3563 directly untainting variables.
3565 void SvTAINTED_off (SV* sv)
3569 Marks an SV as tainted.
3571 void SvTAINTED_on (SV* sv)
3575 Integer type flag for scalars. See C<svtype>.
3579 Pointer type flag for scalars. See C<svtype>.
3583 Type flag for arrays. See C<svtype>.
3587 Type flag for code refs. See C<svtype>.
3591 Type flag for hashes. See C<svtype>.
3595 Type flag for blessed scalars. See C<svtype>.
3599 Double type flag for scalars. See C<svtype>.
3603 Returns a boolean indicating whether Perl would evaluate the SV as true or
3604 false, defined or undefined. Does not handle 'get' magic.
3610 Returns the type of the SV. See C<svtype>.
3612 svtype SvTYPE (SV* sv)
3616 An enum of flags for Perl types. These are found in the file B<sv.h> in the
3617 C<svtype> enum. Test these flags with the C<SvTYPE> macro.
3621 This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
3625 Unsets the RV status of the SV, and decrements the reference count of
3626 whatever was being referenced by the RV. This can almost be thought of
3627 as a reversal of C<newSVrv>. See C<SvROK_off>.
3629 void sv_unref (SV* sv)
3633 Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
3634 the upgrade if necessary. See C<svtype>.
3636 bool SvUPGRADE (SV* sv, svtype mt)
3640 Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
3644 Tells an SV to use C<ptr> to find its string value. Normally the string is
3645 stored inside the SV but sv_usepvn allows the SV to use an outside string.
3646 The C<ptr> should point to memory that was allocated by C<malloc>. The
3647 string length, C<len>, must be supplied. This function will realloc the
3648 memory pointed to by C<ptr>, so that pointer should not be freed or used by
3649 the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
3650 See C<sv_usepvn_mg>.
3652 void sv_usepvn (SV* sv, char* ptr, STRLEN len)
3656 Like C<sv_usepvn>, but also handles 'set' magic.
3658 void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
3662 Processes its arguments like C<vsprintf> and appends the formatted output
3663 to an SV. Uses an array of SVs if the C style variable argument list is
3664 missing (NULL). When running with taint checks enabled, indicates via
3665 C<maybe_tainted> if results are untrustworthy (often due to the use of
3668 void sv_catpvfn (SV* sv, const char* pat, STRLEN patlen,
3669 va_list *args, SV **svargs, I32 svmax,
3670 bool *maybe_tainted);
3674 Works like C<vcatpvfn> but copies the text into the SV instead of
3677 void sv_setpvfn (SV* sv, const char* pat, STRLEN patlen,
3678 va_list *args, SV **svargs, I32 svmax,
3679 bool *maybe_tainted);
3683 Coerces the given SV to an unsigned integer and returns it.
3689 Returns the unsigned integer which is stored in the SV, assuming SvIOK is true.
3695 This is the C<true> SV. See C<PL_sv_no>. Always refer to this as C<&PL_sv_yes>.
3699 Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
3700 This is always the proper type for the C++ object. See C<CLASS> and
3701 L<perlxs/"Using XS With C++">.
3705 Converts the specified character to lowercase.
3707 int toLOWER (char c)
3711 Converts the specified character to uppercase.
3713 int toUPPER (char c)
3717 This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3718 function the same way you use the C C<printf> function. See C<croak()>.
3722 Push an integer onto the stack, extending the stack if necessary. Handles
3723 'set' magic. See C<PUSHi>.
3729 Push a double onto the stack, extending the stack if necessary. Handles 'set'
3730 magic. See C<PUSHn>.
3736 Push a string onto the stack, extending the stack if necessary. The C<len>
3737 indicates the length of the string. Handles 'set' magic. See C<PUSHp>.
3739 XPUSHp(char *c, int len)
3743 Push an SV onto the stack, extending the stack if necessary. Does not
3744 handle 'set' magic. See C<PUSHs>.
3750 Push an unsigned integer onto the stack, extending the stack if
3751 necessary. See C<PUSHu>.
3755 Macro to declare an XSUB and its C parameter list. This is handled by
3760 Return from XSUB, indicating number of items on the stack. This is usually
3761 handled by C<xsubpp>.
3765 =item XSRETURN_EMPTY
3767 Return an empty list from an XSUB immediately.
3773 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3779 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3785 Return an double from an XSUB immediately. Uses C<XST_mNV>.
3791 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3793 XSRETURN_PV(char *v)
3795 =item XSRETURN_UNDEF
3797 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3803 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3809 Place an integer into the specified position C<i> on the stack. The value is
3810 stored in a new mortal SV.
3812 XST_mIV( int i, IV v )
3816 Place a double into the specified position C<i> on the stack. The value is
3817 stored in a new mortal SV.
3819 XST_mNV( int i, NV v )
3823 Place C<&PL_sv_no> into the specified position C<i> on the stack.
3829 Place a copy of a string into the specified position C<i> on the stack. The
3830 value is stored in a new mortal SV.
3832 XST_mPV( int i, char *v )
3836 Place C<&PL_sv_undef> into the specified position C<i> on the stack.
3842 Place C<&PL_sv_yes> into the specified position C<i> on the stack.
3848 The version identifier for an XS module. This is usually handled
3849 automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3851 =item XS_VERSION_BOOTCHECK
3853 Macro to verify that a PM module's $VERSION variable matches the XS module's
3854 C<XS_VERSION> variable. This is usually handled automatically by
3855 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3859 The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
3860 destination, C<n> is the number of items, and C<t> is the type.
3862 void Zero( d, n, t )
3868 Until May 1997, this document was maintained by Jeff Okamoto
3869 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3871 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3872 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3873 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3874 Stephen McCamant, and Gurusamy Sarathy.
3876 API Listing originally by Dean Roehrich <roehrich@cray.com>.
projects / p5sagit/p5-mst-13.2.git / blob