This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
notes on PERL_IMPLICIT_CONTEXT (from a version by Nathan Torkington
[perl5.git] / pod / perlguts.pod
1 =head1 NAME
2
3 perlguts - Perl's Internal Functions
4
5 =head1 DESCRIPTION
6
7 This document attempts to describe some of the internal functions of the
8 Perl executable.  It is far from complete and probably contains many errors.
9 Please refer any questions or comments to the author below.
10
11 =head1 Variables
12
13 =head2 Datatypes
14
15 Perl has three typedefs that handle Perl's three main data types:
16
17     SV  Scalar Value
18     AV  Array Value
19     HV  Hash Value
20
21 Each typedef has specific routines that manipulate the various data types.
22
23 =head2 What is an "IV"?
24
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).
27
28 Perl also uses two special typedefs, I32 and I16, which will always be at
29 least 32-bits and 16-bits long, respectively.
30
31 =head2 Working with SVs
32
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).
36
37 The six routines are:
38
39     SV*  newSViv(IV);
40     SV*  newSVnv(double);
41     SV*  newSVpv(const char*, int);
42     SV*  newSVpvn(const char*, int);
43     SV*  newSVpvf(const char*, ...);
44     SV*  newSVsv(SV*);
45
46 To change the value of an *already-existing* SV, there are seven routines:
47
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*);
56
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.
63
64 The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
65 formatted output becomes the value.
66
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
74 the format.
75
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.
78
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.
86
87 To access the actual value that an SV points to, you can use the macros:
88
89     SvIV(SV*)
90     SvNV(SV*)
91     SvPV(SV*, STRLEN len)
92     SvPV_nolen(SV*)
93
94 which will automatically coerce the actual scalar type into an IV, double,
95 or string.
96
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.
105
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:
109
110         STRLEN len;
111         char * ptr;
112         ptr = SvPV(len);
113         foo(ptr, len);
114
115 If you want to know if the scalar value is TRUE, you can use:
116
117     SvTRUE(SV*)
118
119 Although Perl will automatically grow strings for you, if you need to force
120 Perl to allocate more memory for your SV, you can use the macro
121
122     SvGROW(SV*, STRLEN newlen)
123
124 which will determine if more memory needs to be allocated.  If so, it will
125 call the function C<sv_grow>.  Note that C<SvGROW> can only increase, not
126 decrease, the allocated memory of an SV and that it does not automatically
127 add a byte for the a trailing NUL (perl's own string functions typically do
128 C<SvGROW(sv, len + 1)>).
129
130 If you have an SV and want to know what kind of data Perl thinks is stored
131 in it, you can use the following macros to check the type of SV you have.
132
133     SvIOK(SV*)
134     SvNOK(SV*)
135     SvPOK(SV*)
136
137 You can get and set the current length of the string stored in an SV with
138 the following macros:
139
140     SvCUR(SV*)
141     SvCUR_set(SV*, I32 val)
142
143 You can also get a pointer to the end of the string stored in the SV
144 with the macro:
145
146     SvEND(SV*)
147
148 But note that these last three macros are valid only if C<SvPOK()> is true.
149
150 If you want to append something to the end of string stored in an C<SV*>,
151 you can use the following functions:
152
153     void  sv_catpv(SV*, const char*);
154     void  sv_catpvn(SV*, const char*, STRLEN);
155     void  sv_catpvf(SV*, const char*, ...);
156     void  sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
157     void  sv_catsv(SV*, SV*);
158
159 The first function calculates the length of the string to be appended by
160 using C<strlen>.  In the second, you specify the length of the string
161 yourself.  The third function processes its arguments like C<sprintf> and
162 appends the formatted output.  The fourth function works like C<vsprintf>.
163 You can specify the address and length of an array of SVs instead of the
164 va_list argument. The fifth function extends the string stored in the first
165 SV with the string stored in the second SV.  It also forces the second SV
166 to be interpreted as a string.
167
168 The C<sv_cat*()> functions are not generic enough to operate on values that
169 have "magic".  See L<Magic Virtual Tables> later in this document.
170
171 If you know the name of a scalar variable, you can get a pointer to its SV
172 by using the following:
173
174     SV*  perl_get_sv("package::varname", FALSE);
175
176 This returns NULL if the variable does not exist.
177
178 If you want to know if this variable (or any other SV) is actually C<defined>,
179 you can call:
180
181     SvOK(SV*)
182
183 The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.  Its
184 address can be used whenever an C<SV*> is needed.
185
186 There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
187 TRUE and FALSE values, respectively.  Like C<PL_sv_undef>, their addresses can
188 be used whenever an C<SV*> is needed.
189
190 Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
191 Take this code:
192
193     SV* sv = (SV*) 0;
194     if (I-am-to-return-a-real-value) {
195             sv = sv_2mortal(newSViv(42));
196     }
197     sv_setsv(ST(0), sv);
198
199 This code tries to return a new SV (which contains the value 42) if it should
200 return a real value, or undef otherwise.  Instead it has returned a NULL
201 pointer which, somewhere down the line, will cause a segmentation violation,
202 bus error, or just weird results.  Change the zero to C<&PL_sv_undef> in the first
203 line and all will be well.
204
205 To free an SV that you've created, call C<SvREFCNT_dec(SV*)>.  Normally this
206 call is not necessary (see L<Reference Counts and Mortality>).
207
208 =head2 What's Really Stored in an SV?
209
210 Recall that the usual method of determining the type of scalar you have is
211 to use C<Sv*OK> macros.  Because a scalar can be both a number and a string,
212 usually these macros will always return TRUE and calling the C<Sv*V>
213 macros will do the appropriate conversion of string to integer/double or
214 integer/double to string.
215
216 If you I<really> need to know if you have an integer, double, or string
217 pointer in an SV, you can use the following three macros instead:
218
219     SvIOKp(SV*)
220     SvNOKp(SV*)
221     SvPOKp(SV*)
222
223 These will tell you if you truly have an integer, double, or string pointer
224 stored in your SV.  The "p" stands for private.
225
226 In general, though, it's best to use the C<Sv*V> macros.
227
228 =head2 Working with AVs
229
230 There are two ways to create and load an AV.  The first method creates an
231 empty AV:
232
233     AV*  newAV();
234
235 The second method both creates the AV and initially populates it with SVs:
236
237     AV*  av_make(I32 num, SV **ptr);
238
239 The second argument points to an array containing C<num> C<SV*>'s.  Once the
240 AV has been created, the SVs can be destroyed, if so desired.
241
242 Once the AV has been created, the following operations are possible on AVs:
243
244     void  av_push(AV*, SV*);
245     SV*   av_pop(AV*);
246     SV*   av_shift(AV*);
247     void  av_unshift(AV*, I32 num);
248
249 These should be familiar operations, with the exception of C<av_unshift>.
250 This routine adds C<num> elements at the front of the array with the C<undef>
251 value.  You must then use C<av_store> (described below) to assign values
252 to these new elements.
253
254 Here are some other functions:
255
256     I32   av_len(AV*);
257     SV**  av_fetch(AV*, I32 key, I32 lval);
258     SV**  av_store(AV*, I32 key, SV* val);
259
260 The C<av_len> function returns the highest index value in array (just
261 like $#array in Perl).  If the array is empty, -1 is returned.  The
262 C<av_fetch> function returns the value at index C<key>, but if C<lval>
263 is non-zero, then C<av_fetch> will store an undef value at that index.
264 The C<av_store> function stores the value C<val> at index C<key>, and does
265 not increment the reference count of C<val>.  Thus the caller is responsible
266 for taking care of that, and if C<av_store> returns NULL, the caller will
267 have to decrement the reference count to avoid a memory leak.  Note that
268 C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
269 return value.
270
271     void  av_clear(AV*);
272     void  av_undef(AV*);
273     void  av_extend(AV*, I32 key);
274
275 The C<av_clear> function deletes all the elements in the AV* array, but
276 does not actually delete the array itself.  The C<av_undef> function will
277 delete all the elements in the array plus the array itself.  The
278 C<av_extend> function extends the array so that it contains at least C<key+1>
279 elements.  If C<key+1> is less than the currently allocated length of the array,
280 then nothing is done.
281
282 If you know the name of an array variable, you can get a pointer to its AV
283 by using the following:
284
285     AV*  perl_get_av("package::varname", FALSE);
286
287 This returns NULL if the variable does not exist.
288
289 See L<Understanding the Magic of Tied Hashes and Arrays> for more
290 information on how to use the array access functions on tied arrays.
291
292 =head2 Working with HVs
293
294 To create an HV, you use the following routine:
295
296     HV*  newHV();
297
298 Once the HV has been created, the following operations are possible on HVs:
299
300     SV**  hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
301     SV**  hv_fetch(HV*, const char* key, U32 klen, I32 lval);
302
303 The C<klen> parameter is the length of the key being passed in (Note that
304 you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
305 length of the key).  The C<val> argument contains the SV pointer to the
306 scalar being stored, and C<hash> is the precomputed hash value (zero if
307 you want C<hv_store> to calculate it for you).  The C<lval> parameter
308 indicates whether this fetch is actually a part of a store operation, in
309 which case a new undefined value will be added to the HV with the supplied
310 key and C<hv_fetch> will return as if the value had already existed.
311
312 Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
313 C<SV*>.  To access the scalar value, you must first dereference the return
314 value.  However, you should check to make sure that the return value is
315 not NULL before dereferencing it.
316
317 These two functions check if a hash table entry exists, and deletes it.
318
319     bool  hv_exists(HV*, const char* key, U32 klen);
320     SV*   hv_delete(HV*, const char* key, U32 klen, I32 flags);
321
322 If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
323 create and return a mortal copy of the deleted value.
324
325 And more miscellaneous functions:
326
327     void   hv_clear(HV*);
328     void   hv_undef(HV*);
329
330 Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
331 table but does not actually delete the hash table.  The C<hv_undef> deletes
332 both the entries and the hash table itself.
333
334 Perl keeps the actual data in linked list of structures with a typedef of HE.
335 These contain the actual key and value pointers (plus extra administrative
336 overhead).  The key is a string pointer; the value is an C<SV*>.  However,
337 once you have an C<HE*>, to get the actual key and value, use the routines
338 specified below.
339
340     I32    hv_iterinit(HV*);
341             /* Prepares starting point to traverse hash table */
342     HE*    hv_iternext(HV*);
343             /* Get the next entry, and return a pointer to a
344                structure that has both the key and value */
345     char*  hv_iterkey(HE* entry, I32* retlen);
346             /* Get the key from an HE structure and also return
347                the length of the key string */
348     SV*    hv_iterval(HV*, HE* entry);
349             /* Return a SV pointer to the value of the HE
350                structure */
351     SV*    hv_iternextsv(HV*, char** key, I32* retlen);
352             /* This convenience routine combines hv_iternext,
353                hv_iterkey, and hv_iterval.  The key and retlen
354                arguments are return values for the key and its
355                length.  The value is returned in the SV* argument */
356
357 If you know the name of a hash variable, you can get a pointer to its HV
358 by using the following:
359
360     HV*  perl_get_hv("package::varname", FALSE);
361
362 This returns NULL if the variable does not exist.
363
364 The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
365
366     hash = 0;
367     while (klen--)
368         hash = (hash * 33) + *key++;
369     hash = hash + (hash >> 5);                  /* after 5.6 */
370
371 The last step was added in version 5.6 to improve distribution of
372 lower bits in the resulting hash value.
373
374 See L<Understanding the Magic of Tied Hashes and Arrays> for more
375 information on how to use the hash access functions on tied hashes.
376
377 =head2 Hash API Extensions
378
379 Beginning with version 5.004, the following functions are also supported:
380
381     HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
382     HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
383     
384     bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
385     SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
386     
387     SV*     hv_iterkeysv  (HE* entry);
388
389 Note that these functions take C<SV*> keys, which simplifies writing
390 of extension code that deals with hash structures.  These functions
391 also allow passing of C<SV*> keys to C<tie> functions without forcing
392 you to stringify the keys (unlike the previous set of functions).
393
394 They also return and accept whole hash entries (C<HE*>), making their
395 use more efficient (since the hash number for a particular string
396 doesn't have to be recomputed every time).  See L<API LISTING> later in
397 this document for detailed descriptions.
398
399 The following macros must always be used to access the contents of hash
400 entries.  Note that the arguments to these macros must be simple
401 variables, since they may get evaluated more than once.  See
402 L<API LISTING> later in this document for detailed descriptions of these
403 macros.
404
405     HePV(HE* he, STRLEN len)
406     HeVAL(HE* he)
407     HeHASH(HE* he)
408     HeSVKEY(HE* he)
409     HeSVKEY_force(HE* he)
410     HeSVKEY_set(HE* he, SV* sv)
411
412 These two lower level macros are defined, but must only be used when
413 dealing with keys that are not C<SV*>s:
414
415     HeKEY(HE* he)
416     HeKLEN(HE* he)
417
418 Note that both C<hv_store> and C<hv_store_ent> do not increment the
419 reference count of the stored C<val>, which is the caller's responsibility.
420 If these functions return a NULL value, the caller will usually have to
421 decrement the reference count of C<val> to avoid a memory leak.
422
423 =head2 References
424
425 References are a special type of scalar that point to other data types
426 (including references).
427
428 To create a reference, use either of the following functions:
429
430     SV* newRV_inc((SV*) thing);
431     SV* newRV_noinc((SV*) thing);
432
433 The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>.  The
434 functions are identical except that C<newRV_inc> increments the reference
435 count of the C<thing>, while C<newRV_noinc> does not.  For historical
436 reasons, C<newRV> is a synonym for C<newRV_inc>.
437
438 Once you have a reference, you can use the following macro to dereference
439 the reference:
440
441     SvRV(SV*)
442
443 then call the appropriate routines, casting the returned C<SV*> to either an
444 C<AV*> or C<HV*>, if required.
445
446 To determine if an SV is a reference, you can use the following macro:
447
448     SvROK(SV*)
449
450 To discover what type of value the reference refers to, use the following
451 macro and then check the return value.
452
453     SvTYPE(SvRV(SV*))
454
455 The most useful types that will be returned are:
456
457     SVt_IV    Scalar
458     SVt_NV    Scalar
459     SVt_PV    Scalar
460     SVt_RV    Scalar
461     SVt_PVAV  Array
462     SVt_PVHV  Hash
463     SVt_PVCV  Code
464     SVt_PVGV  Glob (possible a file handle)
465     SVt_PVMG  Blessed or Magical Scalar
466
467     See the sv.h header file for more details.
468
469 =head2 Blessed References and Class Objects
470
471 References are also used to support object-oriented programming.  In the
472 OO lexicon, an object is simply a reference that has been blessed into a
473 package (or class).  Once blessed, the programmer may now use the reference
474 to access the various methods in the class.
475
476 A reference can be blessed into a package with the following function:
477
478     SV* sv_bless(SV* sv, HV* stash);
479
480 The C<sv> argument must be a reference.  The C<stash> argument specifies
481 which class the reference will belong to.  See
482 L<Stashes and Globs> for information on converting class names into stashes.
483
484 /* Still under construction */
485
486 Upgrades rv to reference if not already one.  Creates new SV for rv to
487 point to.  If C<classname> is non-null, the SV is blessed into the specified
488 class.  SV is returned.
489
490         SV* newSVrv(SV* rv, const char* classname);
491
492 Copies integer or double into an SV whose reference is C<rv>.  SV is blessed
493 if C<classname> is non-null.
494
495         SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
496         SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
497
498 Copies the pointer value (I<the address, not the string!>) into an SV whose
499 reference is rv.  SV is blessed if C<classname> is non-null.
500
501         SV* sv_setref_pv(SV* rv, const char* classname, PV iv);
502
503 Copies string into an SV whose reference is C<rv>.  Set length to 0 to let
504 Perl calculate the string length.  SV is blessed if C<classname> is non-null.
505
506         SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);
507
508 Tests whether the SV is blessed into the specified class.  It does not
509 check inheritance relationships.
510
511         int  sv_isa(SV* sv, const char* name);
512
513 Tests whether the SV is a reference to a blessed object.
514
515         int  sv_isobject(SV* sv);
516
517 Tests whether the SV is derived from the specified class. SV can be either
518 a reference to a blessed object or a string containing a class name. This
519 is the function implementing the C<UNIVERSAL::isa> functionality.
520
521         bool sv_derived_from(SV* sv, const char* name);
522
523 To check if you've got an object derived from a specific class you have 
524 to write:
525
526         if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
527
528 =head2 Creating New Variables
529
530 To create a new Perl variable with an undef value which can be accessed from
531 your Perl script, use the following routines, depending on the variable type.
532
533     SV*  perl_get_sv("package::varname", TRUE);
534     AV*  perl_get_av("package::varname", TRUE);
535     HV*  perl_get_hv("package::varname", TRUE);
536
537 Notice the use of TRUE as the second parameter.  The new variable can now
538 be set, using the routines appropriate to the data type.
539
540 There are additional macros whose values may be bitwise OR'ed with the
541 C<TRUE> argument to enable certain extra features.  Those bits are:
542
543     GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
544                 "Name <varname> used only once: possible typo" warning.
545     GV_ADDWARN  Issues the warning "Had to create <varname> unexpectedly" if
546                 the variable did not exist before the function was called.
547
548 If you do not specify a package name, the variable is created in the current
549 package.
550
551 =head2 Reference Counts and Mortality
552
553 Perl uses an reference count-driven garbage collection mechanism. SVs,
554 AVs, or HVs (xV for short in the following) start their life with a
555 reference count of 1.  If the reference count of an xV ever drops to 0,
556 then it will be destroyed and its memory made available for reuse.
557
558 This normally doesn't happen at the Perl level unless a variable is
559 undef'ed or the last variable holding a reference to it is changed or
560 overwritten.  At the internal level, however, reference counts can be
561 manipulated with the following macros:
562
563     int SvREFCNT(SV* sv);
564     SV* SvREFCNT_inc(SV* sv);
565     void SvREFCNT_dec(SV* sv);
566
567 However, there is one other function which manipulates the reference
568 count of its argument.  The C<newRV_inc> function, you will recall,
569 creates a reference to the specified argument.  As a side effect,
570 it increments the argument's reference count.  If this is not what
571 you want, use C<newRV_noinc> instead.
572
573 For example, imagine you want to return a reference from an XSUB function.
574 Inside the XSUB routine, you create an SV which initially has a reference
575 count of one.  Then you call C<newRV_inc>, passing it the just-created SV.
576 This returns the reference as a new SV, but the reference count of the
577 SV you passed to C<newRV_inc> has been incremented to two.  Now you
578 return the reference from the XSUB routine and forget about the SV.
579 But Perl hasn't!  Whenever the returned reference is destroyed, the
580 reference count of the original SV is decreased to one and nothing happens.
581 The SV will hang around without any way to access it until Perl itself
582 terminates.  This is a memory leak.
583
584 The correct procedure, then, is to use C<newRV_noinc> instead of
585 C<newRV_inc>.  Then, if and when the last reference is destroyed,
586 the reference count of the SV will go to zero and it will be destroyed,
587 stopping any memory leak.
588
589 There are some convenience functions available that can help with the
590 destruction of xVs.  These functions introduce the concept of "mortality".
591 An xV that is mortal has had its reference count marked to be decremented,
592 but not actually decremented, until "a short time later".  Generally the
593 term "short time later" means a single Perl statement, such as a call to
594 an XSUB function.  The actual determinant for when mortal xVs have their
595 reference count decremented depends on two macros, SAVETMPS and FREETMPS.
596 See L<perlcall> and L<perlxs> for more details on these macros.
597
598 "Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
599 However, if you mortalize a variable twice, the reference count will
600 later be decremented twice.
601
602 You should be careful about creating mortal variables.  Strange things
603 can happen if you make the same value mortal within multiple contexts,
604 or if you make a variable mortal multiple times.
605
606 To create a mortal variable, use the functions:
607
608     SV*  sv_newmortal()
609     SV*  sv_2mortal(SV*)
610     SV*  sv_mortalcopy(SV*)
611
612 The first call creates a mortal SV, the second converts an existing
613 SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
614 third creates a mortal copy of an existing SV.
615
616 The mortal routines are not just for SVs -- AVs and HVs can be
617 made mortal by passing their address (type-casted to C<SV*>) to the
618 C<sv_2mortal> or C<sv_mortalcopy> routines.
619
620 =head2 Stashes and Globs
621
622 A "stash" is a hash that contains all of the different objects that
623 are contained within a package.  Each key of the stash is a symbol
624 name (shared by all the different types of objects that have the same
625 name), and each value in the hash table is a GV (Glob Value).  This GV
626 in turn contains references to the various objects of that name,
627 including (but not limited to) the following:
628
629     Scalar Value
630     Array Value
631     Hash Value
632     I/O Handle
633     Format
634     Subroutine
635
636 There is a single stash called "PL_defstash" that holds the items that exist
637 in the "main" package.  To get at the items in other packages, append the
638 string "::" to the package name.  The items in the "Foo" package are in
639 the stash "Foo::" in PL_defstash.  The items in the "Bar::Baz" package are
640 in the stash "Baz::" in "Bar::"'s stash.
641
642 To get the stash pointer for a particular package, use the function:
643
644     HV*  gv_stashpv(const char* name, I32 create)
645     HV*  gv_stashsv(SV*, I32 create)
646
647 The first function takes a literal string, the second uses the string stored
648 in the SV.  Remember that a stash is just a hash table, so you get back an
649 C<HV*>.  The C<create> flag will create a new package if it is set.
650
651 The name that C<gv_stash*v> wants is the name of the package whose symbol table
652 you want.  The default package is called C<main>.  If you have multiply nested
653 packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
654 language itself.
655
656 Alternately, if you have an SV that is a blessed reference, you can find
657 out the stash pointer by using:
658
659     HV*  SvSTASH(SvRV(SV*));
660
661 then use the following to get the package name itself:
662
663     char*  HvNAME(HV* stash);
664
665 If you need to bless or re-bless an object you can use the following
666 function:
667
668     SV*  sv_bless(SV*, HV* stash)
669
670 where the first argument, an C<SV*>, must be a reference, and the second
671 argument is a stash.  The returned C<SV*> can now be used in the same way
672 as any other SV.
673
674 For more information on references and blessings, consult L<perlref>.
675
676 =head2 Double-Typed SVs
677
678 Scalar variables normally contain only one type of value, an integer,
679 double, pointer, or reference.  Perl will automatically convert the
680 actual scalar data from the stored type into the requested type.
681
682 Some scalar variables contain more than one type of scalar data.  For
683 example, the variable C<$!> contains either the numeric value of C<errno>
684 or its string equivalent from either C<strerror> or C<sys_errlist[]>.
685
686 To force multiple data values into an SV, you must do two things: use the
687 C<sv_set*v> routines to add the additional scalar type, then set a flag
688 so that Perl will believe it contains more than one type of data.  The
689 four macros to set the flags are:
690
691         SvIOK_on
692         SvNOK_on
693         SvPOK_on
694         SvROK_on
695
696 The particular macro you must use depends on which C<sv_set*v> routine
697 you called first.  This is because every C<sv_set*v> routine turns on
698 only the bit for the particular type of data being set, and turns off
699 all the rest.
700
701 For example, to create a new Perl variable called "dberror" that contains
702 both the numeric and descriptive string error values, you could use the
703 following code:
704
705     extern int  dberror;
706     extern char *dberror_list;
707
708     SV* sv = perl_get_sv("dberror", TRUE);
709     sv_setiv(sv, (IV) dberror);
710     sv_setpv(sv, dberror_list[dberror]);
711     SvIOK_on(sv);
712
713 If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
714 macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
715
716 =head2 Magic Variables
717
718 [This section still under construction.  Ignore everything here.  Post no
719 bills.  Everything not permitted is forbidden.]
720
721 Any SV may be magical, that is, it has special features that a normal
722 SV does not have.  These features are stored in the SV structure in a
723 linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
724
725     struct magic {
726         MAGIC*      mg_moremagic;
727         MGVTBL*     mg_virtual;
728         U16         mg_private;
729         char        mg_type;
730         U8          mg_flags;
731         SV*         mg_obj;
732         char*       mg_ptr;
733         I32         mg_len;
734     };
735
736 Note this is current as of patchlevel 0, and could change at any time.
737
738 =head2 Assigning Magic
739
740 Perl adds magic to an SV using the sv_magic function:
741
742     void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
743
744 The C<sv> argument is a pointer to the SV that is to acquire a new magical
745 feature.
746
747 If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
748 set the C<SVt_PVMG> flag for the C<sv>.  Perl then continues by adding
749 it to the beginning of the linked list of magical features.  Any prior
750 entry of the same type of magic is deleted.  Note that this can be
751 overridden, and multiple instances of the same type of magic can be
752 associated with an SV.
753
754 The C<name> and C<namlen> arguments are used to associate a string with
755 the magic, typically the name of a variable. C<namlen> is stored in the
756 C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
757 copy of the name is stored in C<mg_ptr> field.
758
759 The sv_magic function uses C<how> to determine which, if any, predefined
760 "Magic Virtual Table" should be assigned to the C<mg_virtual> field.
761 See the "Magic Virtual Table" section below.  The C<how> argument is also
762 stored in the C<mg_type> field.
763
764 The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
765 structure.  If it is not the same as the C<sv> argument, the reference
766 count of the C<obj> object is incremented.  If it is the same, or if
767 the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
768 merely stored, without the reference count being incremented.
769
770 There is also a function to add magic to an C<HV>:
771
772     void hv_magic(HV *hv, GV *gv, int how);
773
774 This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
775
776 To remove the magic from an SV, call the function sv_unmagic:
777
778     void sv_unmagic(SV *sv, int type);
779
780 The C<type> argument should be equal to the C<how> value when the C<SV>
781 was initially made magical.
782
783 =head2 Magic Virtual Tables
784
785 The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
786 C<MGVTBL>, which is a structure of function pointers and stands for
787 "Magic Virtual Table" to handle the various operations that might be
788 applied to that variable.
789
790 The C<MGVTBL> has five pointers to the following routine types:
791
792     int  (*svt_get)(SV* sv, MAGIC* mg);
793     int  (*svt_set)(SV* sv, MAGIC* mg);
794     U32  (*svt_len)(SV* sv, MAGIC* mg);
795     int  (*svt_clear)(SV* sv, MAGIC* mg);
796     int  (*svt_free)(SV* sv, MAGIC* mg);
797
798 This MGVTBL structure is set at compile-time in C<perl.h> and there are
799 currently 19 types (or 21 with overloading turned on).  These different
800 structures contain pointers to various routines that perform additional
801 actions depending on which function is being called.
802
803     Function pointer    Action taken
804     ----------------    ------------
805     svt_get             Do something after the value of the SV is retrieved.
806     svt_set             Do something after the SV is assigned a value.
807     svt_len             Report on the SV's length.
808     svt_clear           Clear something the SV represents.
809     svt_free            Free any extra storage associated with the SV.
810
811 For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
812 to an C<mg_type> of '\0') contains:
813
814     { magic_get, magic_set, magic_len, 0, 0 }
815
816 Thus, when an SV is determined to be magical and of type '\0', if a get
817 operation is being performed, the routine C<magic_get> is called.  All
818 the various routines for the various magical types begin with C<magic_>.
819
820 The current kinds of Magic Virtual Tables are:
821
822     mg_type  MGVTBL              Type of magic
823     -------  ------              ----------------------------
824     \0       vtbl_sv             Special scalar variable
825     A        vtbl_amagic         %OVERLOAD hash
826     a        vtbl_amagicelem     %OVERLOAD hash element
827     c        (none)              Holds overload table (AMT) on stash
828     B        vtbl_bm             Boyer-Moore (fast string search)
829     E        vtbl_env            %ENV hash
830     e        vtbl_envelem        %ENV hash element
831     f        vtbl_fm             Formline ('compiled' format)
832     g        vtbl_mglob          m//g target / study()ed string
833     I        vtbl_isa            @ISA array
834     i        vtbl_isaelem        @ISA array element
835     k        vtbl_nkeys          scalar(keys()) lvalue
836     L        (none)              Debugger %_<filename 
837     l        vtbl_dbline         Debugger %_<filename element
838     o        vtbl_collxfrm       Locale transformation
839     P        vtbl_pack           Tied array or hash
840     p        vtbl_packelem       Tied array or hash element
841     q        vtbl_packelem       Tied scalar or handle
842     S        vtbl_sig            %SIG hash
843     s        vtbl_sigelem        %SIG hash element
844     t        vtbl_taint          Taintedness
845     U        vtbl_uvar           Available for use by extensions
846     v        vtbl_vec            vec() lvalue
847     x        vtbl_substr         substr() lvalue
848     y        vtbl_defelem        Shadow "foreach" iterator variable /
849                                   smart parameter vivification
850     *        vtbl_glob           GV (typeglob)
851     #        vtbl_arylen         Array length ($#ary)
852     .        vtbl_pos            pos() lvalue
853     ~        (none)              Available for use by extensions
854
855 When an uppercase and lowercase letter both exist in the table, then the
856 uppercase letter is used to represent some kind of composite type (a list
857 or a hash), and the lowercase letter is used to represent an element of
858 that composite type.
859
860 The '~' and 'U' magic types are defined specifically for use by
861 extensions and will not be used by perl itself.  Extensions can use
862 '~' magic to 'attach' private information to variables (typically
863 objects).  This is especially useful because there is no way for
864 normal perl code to corrupt this private information (unlike using
865 extra elements of a hash object).
866
867 Similarly, 'U' magic can be used much like tie() to call a C function
868 any time a scalar's value is used or changed.  The C<MAGIC>'s
869 C<mg_ptr> field points to a C<ufuncs> structure:
870
871     struct ufuncs {
872         I32 (*uf_val)(IV, SV*);
873         I32 (*uf_set)(IV, SV*);
874         IV uf_index;
875     };
876
877 When the SV is read from or written to, the C<uf_val> or C<uf_set>
878 function will be called with C<uf_index> as the first arg and a
879 pointer to the SV as the second.  A simple example of how to add 'U'
880 magic is shown below.  Note that the ufuncs structure is copied by
881 sv_magic, so you can safely allocate it on the stack.
882
883     void
884     Umagic(sv)
885         SV *sv;
886     PREINIT:
887         struct ufuncs uf;
888     CODE:
889         uf.uf_val   = &my_get_fn;
890         uf.uf_set   = &my_set_fn;
891         uf.uf_index = 0;
892         sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf));
893
894 Note that because multiple extensions may be using '~' or 'U' magic,
895 it is important for extensions to take extra care to avoid conflict.
896 Typically only using the magic on objects blessed into the same class
897 as the extension is sufficient.  For '~' magic, it may also be
898 appropriate to add an I32 'signature' at the top of the private data
899 area and check that.
900
901 Also note that the C<sv_set*()> and C<sv_cat*()> functions described
902 earlier do B<not> invoke 'set' magic on their targets.  This must
903 be done by the user either by calling the C<SvSETMAGIC()> macro after
904 calling these functions, or by using one of the C<sv_set*_mg()> or
905 C<sv_cat*_mg()> functions.  Similarly, generic C code must call the
906 C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
907 obtained from external sources in functions that don't handle magic.
908 L<API LISTING> later in this document identifies such functions.
909 For example, calls to the C<sv_cat*()> functions typically need to be
910 followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
911 since their implementation handles 'get' magic.
912
913 =head2 Finding Magic
914
915     MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
916
917 This routine returns a pointer to the C<MAGIC> structure stored in the SV.
918 If the SV does not have that magical feature, C<NULL> is returned.  Also,
919 if the SV is not of type SVt_PVMG, Perl may core dump.
920
921     int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);
922
923 This routine checks to see what types of magic C<sv> has.  If the mg_type
924 field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
925 the mg_type field is changed to be the lowercase letter.
926
927 =head2 Understanding the Magic of Tied Hashes and Arrays
928
929 Tied hashes and arrays are magical beasts of the 'P' magic type.
930
931 WARNING: As of the 5.004 release, proper usage of the array and hash
932 access functions requires understanding a few caveats.  Some
933 of these caveats are actually considered bugs in the API, to be fixed
934 in later releases, and are bracketed with [MAYCHANGE] below. If
935 you find yourself actually applying such information in this section, be
936 aware that the behavior may change in the future, umm, without warning.
937
938 The perl tie function associates a variable with an object that implements
939 the various GET, SET etc methods.  To perform the equivalent of the perl
940 tie function from an XSUB, you must mimic this behaviour.  The code below
941 carries out the necessary steps - firstly it creates a new hash, and then
942 creates a second hash which it blesses into the class which will implement
943 the tie methods. Lastly it ties the two hashes together, and returns a
944 reference to the new tied hash.  Note that the code below does NOT call the
945 TIEHASH method in the MyTie class -
946 see L<Calling Perl Routines from within C Programs> for details on how
947 to do this.
948
949     SV*
950     mytie()
951     PREINIT:
952         HV *hash;
953         HV *stash;
954         SV *tie;
955     CODE:
956         hash = newHV();
957         tie = newRV_noinc((SV*)newHV());
958         stash = gv_stashpv("MyTie", TRUE);
959         sv_bless(tie, stash);
960         hv_magic(hash, tie, 'P');
961         RETVAL = newRV_noinc(hash);
962     OUTPUT:
963         RETVAL
964
965 The C<av_store> function, when given a tied array argument, merely
966 copies the magic of the array onto the value to be "stored", using
967 C<mg_copy>.  It may also return NULL, indicating that the value did not
968 actually need to be stored in the array.  [MAYCHANGE] After a call to
969 C<av_store> on a tied array, the caller will usually need to call
970 C<mg_set(val)> to actually invoke the perl level "STORE" method on the
971 TIEARRAY object.  If C<av_store> did return NULL, a call to
972 C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
973 leak. [/MAYCHANGE]
974
975 The previous paragraph is applicable verbatim to tied hash access using the
976 C<hv_store> and C<hv_store_ent> functions as well.
977
978 C<av_fetch> and the corresponding hash functions C<hv_fetch> and
979 C<hv_fetch_ent> actually return an undefined mortal value whose magic
980 has been initialized using C<mg_copy>.  Note the value so returned does not
981 need to be deallocated, as it is already mortal.  [MAYCHANGE] But you will
982 need to call C<mg_get()> on the returned value in order to actually invoke
983 the perl level "FETCH" method on the underlying TIE object.  Similarly,
984 you may also call C<mg_set()> on the return value after possibly assigning
985 a suitable value to it using C<sv_setsv>,  which will invoke the "STORE"
986 method on the TIE object. [/MAYCHANGE]
987
988 [MAYCHANGE]
989 In other words, the array or hash fetch/store functions don't really
990 fetch and store actual values in the case of tied arrays and hashes.  They
991 merely call C<mg_copy> to attach magic to the values that were meant to be
992 "stored" or "fetched".  Later calls to C<mg_get> and C<mg_set> actually
993 do the job of invoking the TIE methods on the underlying objects.  Thus
994 the magic mechanism currently implements a kind of lazy access to arrays
995 and hashes.
996
997 Currently (as of perl version 5.004), use of the hash and array access
998 functions requires the user to be aware of whether they are operating on
999 "normal" hashes and arrays, or on their tied variants.  The API may be
1000 changed to provide more transparent access to both tied and normal data
1001 types in future versions.
1002 [/MAYCHANGE]
1003
1004 You would do well to understand that the TIEARRAY and TIEHASH interfaces
1005 are mere sugar to invoke some perl method calls while using the uniform hash
1006 and array syntax.  The use of this sugar imposes some overhead (typically
1007 about two to four extra opcodes per FETCH/STORE operation, in addition to
1008 the creation of all the mortal variables required to invoke the methods).
1009 This overhead will be comparatively small if the TIE methods are themselves
1010 substantial, but if they are only a few statements long, the overhead
1011 will not be insignificant.
1012
1013 =head2 Localizing changes
1014
1015 Perl has a very handy construction
1016
1017   {
1018     local $var = 2;
1019     ...
1020   }
1021
1022 This construction is I<approximately> equivalent to
1023
1024   {
1025     my $oldvar = $var;
1026     $var = 2;
1027     ...
1028     $var = $oldvar;
1029   }
1030
1031 The biggest difference is that the first construction would
1032 reinstate the initial value of $var, irrespective of how control exits
1033 the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
1034 more efficient as well.
1035
1036 There is a way to achieve a similar task from C via Perl API: create a
1037 I<pseudo-block>, and arrange for some changes to be automatically
1038 undone at the end of it, either explicit, or via a non-local exit (via
1039 die()). A I<block>-like construct is created by a pair of
1040 C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
1041 Such a construct may be created specially for some important localized
1042 task, or an existing one (like boundaries of enclosing Perl
1043 subroutine/block, or an existing pair for freeing TMPs) may be
1044 used. (In the second case the overhead of additional localization must
1045 be almost negligible.) Note that any XSUB is automatically enclosed in
1046 an C<ENTER>/C<LEAVE> pair.
1047
1048 Inside such a I<pseudo-block> the following service is available:
1049
1050 =over
1051
1052 =item C<SAVEINT(int i)>
1053
1054 =item C<SAVEIV(IV i)>
1055
1056 =item C<SAVEI32(I32 i)>
1057
1058 =item C<SAVELONG(long i)>
1059
1060 These macros arrange things to restore the value of integer variable
1061 C<i> at the end of enclosing I<pseudo-block>.
1062
1063 =item C<SAVESPTR(s)>
1064
1065 =item C<SAVEPPTR(p)>
1066
1067 These macros arrange things to restore the value of pointers C<s> and
1068 C<p>. C<s> must be a pointer of a type which survives conversion to
1069 C<SV*> and back, C<p> should be able to survive conversion to C<char*>
1070 and back.
1071
1072 =item C<SAVEFREESV(SV *sv)>
1073
1074 The refcount of C<sv> would be decremented at the end of
1075 I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
1076 used instead.
1077
1078 =item C<SAVEFREEOP(OP *op)>
1079
1080 The C<OP *> is op_free()ed at the end of I<pseudo-block>.
1081
1082 =item C<SAVEFREEPV(p)>
1083
1084 The chunk of memory which is pointed to by C<p> is Safefree()ed at the
1085 end of I<pseudo-block>.
1086
1087 =item C<SAVECLEARSV(SV *sv)>
1088
1089 Clears a slot in the current scratchpad which corresponds to C<sv> at
1090 the end of I<pseudo-block>.
1091
1092 =item C<SAVEDELETE(HV *hv, char *key, I32 length)>
1093
1094 The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
1095 string pointed to by C<key> is Safefree()ed.  If one has a I<key> in
1096 short-lived storage, the corresponding string may be reallocated like
1097 this:
1098
1099   SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
1100
1101 =item C<SAVEDESTRUCTOR(f,p)>
1102
1103 At the end of I<pseudo-block> the function C<f> is called with the
1104 only argument (of type C<void*>) C<p>.
1105
1106 =item C<SAVESTACK_POS()>
1107
1108 The current offset on the Perl internal stack (cf. C<SP>) is restored
1109 at the end of I<pseudo-block>.
1110
1111 =back
1112
1113 The following API list contains functions, thus one needs to
1114 provide pointers to the modifiable data explicitly (either C pointers,
1115 or Perlish C<GV *>s).  Where the above macros take C<int>, a similar 
1116 function takes C<int *>.
1117
1118 =over
1119
1120 =item C<SV* save_scalar(GV *gv)>
1121
1122 Equivalent to Perl code C<local $gv>.
1123
1124 =item C<AV* save_ary(GV *gv)>
1125
1126 =item C<HV* save_hash(GV *gv)>
1127
1128 Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
1129
1130 =item C<void save_item(SV *item)>
1131
1132 Duplicates the current value of C<SV>, on the exit from the current
1133 C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
1134 using the stored value.
1135
1136 =item C<void save_list(SV **sarg, I32 maxsarg)>
1137
1138 A variant of C<save_item> which takes multiple arguments via an array
1139 C<sarg> of C<SV*> of length C<maxsarg>.
1140
1141 =item C<SV* save_svref(SV **sptr)>
1142
1143 Similar to C<save_scalar>, but will reinstate a C<SV *>.
1144
1145 =item C<void save_aptr(AV **aptr)>
1146
1147 =item C<void save_hptr(HV **hptr)>
1148
1149 Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
1150
1151 =back
1152
1153 The C<Alias> module implements localization of the basic types within the
1154 I<caller's scope>.  People who are interested in how to localize things in
1155 the containing scope should take a look there too.
1156
1157 =head1 Subroutines
1158
1159 =head2 XSUBs and the Argument Stack
1160
1161 The XSUB mechanism is a simple way for Perl programs to access C subroutines.
1162 An XSUB routine will have a stack that contains the arguments from the Perl
1163 program, and a way to map from the Perl data structures to a C equivalent.
1164
1165 The stack arguments are accessible through the C<ST(n)> macro, which returns
1166 the C<n>'th stack argument.  Argument 0 is the first argument passed in the
1167 Perl subroutine call.  These arguments are C<SV*>, and can be used anywhere
1168 an C<SV*> is used.
1169
1170 Most of the time, output from the C routine can be handled through use of
1171 the RETVAL and OUTPUT directives.  However, there are some cases where the
1172 argument stack is not already long enough to handle all the return values.
1173 An example is the POSIX tzname() call, which takes no arguments, but returns
1174 two, the local time zone's standard and summer time abbreviations.
1175
1176 To handle this situation, the PPCODE directive is used and the stack is
1177 extended using the macro:
1178
1179     EXTEND(SP, num);
1180
1181 where C<SP> is the macro that represents the local copy of the stack pointer,
1182 and C<num> is the number of elements the stack should be extended by.
1183
1184 Now that there is room on the stack, values can be pushed on it using the
1185 macros to push IVs, doubles, strings, and SV pointers respectively:
1186
1187     PUSHi(IV)
1188     PUSHn(double)
1189     PUSHp(char*, I32)
1190     PUSHs(SV*)
1191
1192 And now the Perl program calling C<tzname>, the two values will be assigned
1193 as in:
1194
1195     ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
1196
1197 An alternate (and possibly simpler) method to pushing values on the stack is
1198 to use the macros:
1199
1200     XPUSHi(IV)
1201     XPUSHn(double)
1202     XPUSHp(char*, I32)
1203     XPUSHs(SV*)
1204
1205 These macros automatically adjust the stack for you, if needed.  Thus, you
1206 do not need to call C<EXTEND> to extend the stack.
1207
1208 For more information, consult L<perlxs> and L<perlxstut>.
1209
1210 =head2 Calling Perl Routines from within C Programs
1211
1212 There are four routines that can be used to call a Perl subroutine from
1213 within a C program.  These four are:
1214
1215     I32  perl_call_sv(SV*, I32);
1216     I32  perl_call_pv(const char*, I32);
1217     I32  perl_call_method(const char*, I32);
1218     I32  perl_call_argv(const char*, I32, register char**);
1219
1220 The routine most often used is C<perl_call_sv>.  The C<SV*> argument
1221 contains either the name of the Perl subroutine to be called, or a
1222 reference to the subroutine.  The second argument consists of flags
1223 that control the context in which the subroutine is called, whether
1224 or not the subroutine is being passed arguments, how errors should be
1225 trapped, and how to treat return values.
1226
1227 All four routines return the number of arguments that the subroutine returned
1228 on the Perl stack.
1229
1230 When using any of these routines (except C<perl_call_argv>), the programmer
1231 must manipulate the Perl stack.  These include the following macros and
1232 functions:
1233
1234     dSP
1235     SP
1236     PUSHMARK()
1237     PUTBACK
1238     SPAGAIN
1239     ENTER
1240     SAVETMPS
1241     FREETMPS
1242     LEAVE
1243     XPUSH*()
1244     POP*()
1245
1246 For a detailed description of calling conventions from C to Perl,
1247 consult L<perlcall>.
1248
1249 =head2 Memory Allocation
1250
1251 All memory meant to be used with the Perl API functions should be manipulated
1252 using the macros described in this section.  The macros provide the necessary
1253 transparency between differences in the actual malloc implementation that is
1254 used within perl.
1255
1256 It is suggested that you enable the version of malloc that is distributed
1257 with Perl.  It keeps pools of various sizes of unallocated memory in
1258 order to satisfy allocation requests more quickly.  However, on some
1259 platforms, it may cause spurious malloc or free errors.
1260
1261     New(x, pointer, number, type);
1262     Newc(x, pointer, number, type, cast);
1263     Newz(x, pointer, number, type);
1264
1265 These three macros are used to initially allocate memory.
1266
1267 The first argument C<x> was a "magic cookie" that was used to keep track
1268 of who called the macro, to help when debugging memory problems.  However,
1269 the current code makes no use of this feature (most Perl developers now
1270 use run-time memory checkers), so this argument can be any number.
1271
1272 The second argument C<pointer> should be the name of a variable that will
1273 point to the newly allocated memory.
1274
1275 The third and fourth arguments C<number> and C<type> specify how many of
1276 the specified type of data structure should be allocated.  The argument
1277 C<type> is passed to C<sizeof>.  The final argument to C<Newc>, C<cast>,
1278 should be used if the C<pointer> argument is different from the C<type>
1279 argument.
1280
1281 Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
1282 to zero out all the newly allocated memory.
1283
1284     Renew(pointer, number, type);
1285     Renewc(pointer, number, type, cast);
1286     Safefree(pointer)
1287
1288 These three macros are used to change a memory buffer size or to free a
1289 piece of memory no longer needed.  The arguments to C<Renew> and C<Renewc>
1290 match those of C<New> and C<Newc> with the exception of not needing the
1291 "magic cookie" argument.
1292
1293     Move(source, dest, number, type);
1294     Copy(source, dest, number, type);
1295     Zero(dest, number, type);
1296
1297 These three macros are used to move, copy, or zero out previously allocated
1298 memory.  The C<source> and C<dest> arguments point to the source and
1299 destination starting points.  Perl will move, copy, or zero out C<number>
1300 instances of the size of the C<type> data structure (using the C<sizeof>
1301 function).
1302
1303 =head2 PerlIO
1304
1305 The most recent development releases of Perl has been experimenting with
1306 removing Perl's dependency on the "normal" standard I/O suite and allowing
1307 other stdio implementations to be used.  This involves creating a new
1308 abstraction layer that then calls whichever implementation of stdio Perl
1309 was compiled with.  All XSUBs should now use the functions in the PerlIO
1310 abstraction layer and not make any assumptions about what kind of stdio
1311 is being used.
1312
1313 For a complete description of the PerlIO abstraction, consult L<perlapio>.
1314
1315 =head2 Putting a C value on Perl stack
1316
1317 A lot of opcodes (this is an elementary operation in the internal perl
1318 stack machine) put an SV* on the stack. However, as an optimization
1319 the corresponding SV is (usually) not recreated each time. The opcodes
1320 reuse specially assigned SVs (I<target>s) which are (as a corollary)
1321 not constantly freed/created.
1322
1323 Each of the targets is created only once (but see
1324 L<Scratchpads and recursion> below), and when an opcode needs to put
1325 an integer, a double, or a string on stack, it just sets the
1326 corresponding parts of its I<target> and puts the I<target> on stack.
1327
1328 The macro to put this target on stack is C<PUSHTARG>, and it is
1329 directly used in some opcodes, as well as indirectly in zillions of
1330 others, which use it via C<(X)PUSH[pni]>.
1331
1332 =head2 Scratchpads
1333
1334 The question remains on when the SVs which are I<target>s for opcodes
1335 are created. The answer is that they are created when the current unit --
1336 a subroutine or a file (for opcodes for statements outside of
1337 subroutines) -- is compiled. During this time a special anonymous Perl
1338 array is created, which is called a scratchpad for the current
1339 unit.
1340
1341 A scratchpad keeps SVs which are lexicals for the current unit and are
1342 targets for opcodes. One can deduce that an SV lives on a scratchpad
1343 by looking on its flags: lexicals have C<SVs_PADMY> set, and
1344 I<target>s have C<SVs_PADTMP> set.
1345
1346 The correspondence between OPs and I<target>s is not 1-to-1. Different
1347 OPs in the compile tree of the unit can use the same target, if this
1348 would not conflict with the expected life of the temporary.
1349
1350 =head2 Scratchpads and recursion
1351
1352 In fact it is not 100% true that a compiled unit contains a pointer to
1353 the scratchpad AV. In fact it contains a pointer to an AV of
1354 (initially) one element, and this element is the scratchpad AV. Why do
1355 we need an extra level of indirection?
1356
1357 The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1358 these can create several execution pointers going into the same
1359 subroutine. For the subroutine-child not write over the temporaries
1360 for the subroutine-parent (lifespan of which covers the call to the
1361 child), the parent and the child should have different
1362 scratchpads. (I<And> the lexicals should be separate anyway!)
1363
1364 So each subroutine is born with an array of scratchpads (of length 1).
1365 On each entry to the subroutine it is checked that the current
1366 depth of the recursion is not more than the length of this array, and
1367 if it is, new scratchpad is created and pushed into the array.
1368
1369 The I<target>s on this scratchpad are C<undef>s, but they are already
1370 marked with correct flags.
1371
1372 =head1 Compiled code
1373
1374 =head2 Code tree
1375
1376 Here we describe the internal form your code is converted to by
1377 Perl. Start with a simple example:
1378
1379   $a = $b + $c;
1380
1381 This is converted to a tree similar to this one:
1382
1383              assign-to
1384            /           \
1385           +             $a
1386         /   \
1387       $b     $c
1388
1389 (but slightly more complicated).  This tree reflects the way Perl
1390 parsed your code, but has nothing to do with the execution order.
1391 There is an additional "thread" going through the nodes of the tree
1392 which shows the order of execution of the nodes.  In our simplified
1393 example above it looks like:
1394
1395      $b ---> $c ---> + ---> $a ---> assign-to
1396
1397 But with the actual compile tree for C<$a = $b + $c> it is different:
1398 some nodes I<optimized away>.  As a corollary, though the actual tree
1399 contains more nodes than our simplified example, the execution order
1400 is the same as in our example.
1401
1402 =head2 Examining the tree
1403
1404 If you have your perl compiled for debugging (usually done with C<-D
1405 optimize=-g> on C<Configure> command line), you may examine the
1406 compiled tree by specifying C<-Dx> on the Perl command line.  The
1407 output takes several lines per node, and for C<$b+$c> it looks like
1408 this:
1409
1410     5           TYPE = add  ===> 6
1411                 TARG = 1
1412                 FLAGS = (SCALAR,KIDS)
1413                 {
1414                     TYPE = null  ===> (4)
1415                       (was rv2sv)
1416                     FLAGS = (SCALAR,KIDS)
1417                     {
1418     3                   TYPE = gvsv  ===> 4
1419                         FLAGS = (SCALAR)
1420                         GV = main::b
1421                     }
1422                 }
1423                 {
1424                     TYPE = null  ===> (5)
1425                       (was rv2sv)
1426                     FLAGS = (SCALAR,KIDS)
1427                     {
1428     4                   TYPE = gvsv  ===> 5
1429                         FLAGS = (SCALAR)
1430                         GV = main::c
1431                     }
1432                 }
1433
1434 This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1435 not optimized away (one per number in the left column).  The immediate
1436 children of the given node correspond to C<{}> pairs on the same level
1437 of indentation, thus this listing corresponds to the tree:
1438
1439                    add
1440                  /     \
1441                null    null
1442                 |       |
1443                gvsv    gvsv
1444
1445 The execution order is indicated by C<===E<gt>> marks, thus it is C<3
1446 4 5 6> (node C<6> is not included into above listing), i.e.,
1447 C<gvsv gvsv add whatever>.
1448
1449 =head2 Compile pass 1: check routines
1450
1451 The tree is created by the I<pseudo-compiler> while yacc code feeds it
1452 the constructions it recognizes. Since yacc works bottom-up, so does
1453 the first pass of perl compilation.
1454
1455 What makes this pass interesting for perl developers is that some
1456 optimization may be performed on this pass.  This is optimization by
1457 so-called I<check routines>.  The correspondence between node names
1458 and corresponding check routines is described in F<opcode.pl> (do not
1459 forget to run C<make regen_headers> if you modify this file).
1460
1461 A check routine is called when the node is fully constructed except
1462 for the execution-order thread.  Since at this time there are no
1463 back-links to the currently constructed node, one can do most any
1464 operation to the top-level node, including freeing it and/or creating
1465 new nodes above/below it.
1466
1467 The check routine returns the node which should be inserted into the
1468 tree (if the top-level node was not modified, check routine returns
1469 its argument).
1470
1471 By convention, check routines have names C<ck_*>. They are usually
1472 called from C<new*OP> subroutines (or C<convert>) (which in turn are
1473 called from F<perly.y>).
1474
1475 =head2 Compile pass 1a: constant folding
1476
1477 Immediately after the check routine is called the returned node is
1478 checked for being compile-time executable.  If it is (the value is
1479 judged to be constant) it is immediately executed, and a I<constant>
1480 node with the "return value" of the corresponding subtree is
1481 substituted instead.  The subtree is deleted.
1482
1483 If constant folding was not performed, the execution-order thread is
1484 created.
1485
1486 =head2 Compile pass 2: context propagation
1487
1488 When a context for a part of compile tree is known, it is propagated
1489 down through the tree.  At this time the context can have 5 values
1490 (instead of 2 for runtime context): void, boolean, scalar, list, and
1491 lvalue.  In contrast with the pass 1 this pass is processed from top
1492 to bottom: a node's context determines the context for its children.
1493
1494 Additional context-dependent optimizations are performed at this time.
1495 Since at this moment the compile tree contains back-references (via
1496 "thread" pointers), nodes cannot be free()d now.  To allow
1497 optimized-away nodes at this stage, such nodes are null()ified instead
1498 of free()ing (i.e. their type is changed to OP_NULL).
1499
1500 =head2 Compile pass 3: peephole optimization
1501
1502 After the compile tree for a subroutine (or for an C<eval> or a file)
1503 is created, an additional pass over the code is performed. This pass
1504 is neither top-down or bottom-up, but in the execution order (with
1505 additional complications for conditionals).  These optimizations are
1506 done in the subroutine peep().  Optimizations performed at this stage
1507 are subject to the same restrictions as in the pass 2.
1508
1509 =head1 The Perl API
1510
1511 WARNING: This information is subject to radical changes prior to
1512 the Perl 5.6 release.  Use with caution.
1513
1514 =head2 Background and PERL_IMPLICIT_CONTEXT
1515
1516 The Perl interpreter can be regarded as a closed box: it has an API
1517 for feeding it code or otherwise making it do things, but it also has
1518 functions for its own use.  This smells a lot like an object, and
1519 there are ways for you to build Perl so that you can have multiple
1520 interpreters, with one interpreter represented either as a C++ object,
1521 a C structure, or inside a thread.  The thread, the C structure, or
1522 the C++ object will contain all the context, the state of that
1523 interpreter.
1524
1525 Four macros control the way Perl is built: PERL_IMPLICIT_CONTEXT
1526 (build for multiple interpreters?), MULTIPLICITY (we pass around an
1527 C interpreter structure as the first argument), USE_THREADS (we pass
1528 around a thread as the first argument), and PERL_OBJECT (we build a
1529 C++ class for the interpreter so the Perl API implementation has a
1530 C<this> object).  If PERL_IMPLICIT_CONTEXT is not defined, then
1531 subroutines take no first argument.
1532
1533 This obviously requires a way for the Perl internal functions to be
1534 C++ methods, subroutines taking some kind of structure as the first
1535 argument, or subroutines taking nothing as the first argument.  To
1536 enable these three very different ways of building the interpreter,
1537 the Perl source (as it does in so many other situations) makes heavy
1538 use of macros and subroutine naming conventions.
1539
1540 First problem: deciding which functions will be C++ public methods and
1541 which will be private.  Those functions whose names begin C<Perl_> are
1542 public, and those whose names begin C<S_> are protected (think "S" for
1543 "Secret").  You can't call them from C++, and should not call them
1544 from C.  If you find yourself calling an C<S_> function, consider your
1545 code broken (even though it works, it may not do so forever).
1546
1547 Some functions have no prefix (e.g., restore_rsfp in toke.c).  These
1548 are not parts of the object or pseudo-structure because you need to
1549 pass pointers to them to other subroutines.
1550
1551 Second problem: there must be a syntax so that the same subroutine
1552 declarations and calls can pass a structure as their first argument,
1553 or pass nothing.  To solve this, the subroutines are named and
1554 declared in a particular way.  Here's a typical start of a static
1555 function used within the Perl guts:
1556
1557   STATIC void
1558   S_incline(pTHX_ char *s)
1559
1560 STATIC becomes "static" in C, and is #define'd to nothing in C++.
1561
1562 A public function (i.e. part of the API) begins like this:
1563
1564   void
1565   Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv)
1566
1567 C<pTHX_> is one of a number of macros (in perl.h) that hide the
1568 details of the interpreter's context.  THX stands for "thread", "this",
1569 or "thingy", as the case may be.  (And no, George Lucas is not involved. :-)
1570 The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
1571 or 'd' for B<d>eclaration.
1572
1573 When Perl is built without PERL_IMPLICIT_CONTEXT, there is no first
1574 argument containing the interpreter's context.  The trailing underscore
1575 in the pTHX_ macro indicates that the macro expansion needs a comma
1576 after the context argument because other arguments follow it.  If
1577 PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
1578 subroutine is not prototyped to take an argument.  The form of the
1579 macro without the trailing underscore is used when there are no
1580 explicit arguments.
1581
1582 When an core function calls another, it must pass the context.  This
1583 is normally hidden via macros.  Consider C<sv_setsv>.  It expands
1584 something like this:
1585
1586     ifdef PERL_IMPLICIT_CONTEXT
1587       define sv_setsv(a,b)      Perl_sv_setsv(aTHX_ a, b)
1588       /* can't do this for vararg functions, see below */
1589     else
1590       define sv_setsv           Perl_sv_setsv
1591     endif
1592
1593 This works well, and means that XS authors can gleefully write:
1594
1595     sv_setsv(foo, bar);
1596
1597 and still have it work under all the modes Perl could have been
1598 compiled with.
1599
1600 Under PERL_OBJECT in the core, that will translate to either:
1601
1602     CPerlObj::Perl_sv_setsv(foo,bar);  # in CPerlObj functions,
1603                                        # C++ takes care of 'this'
1604   or
1605
1606     pPerl->Perl_sv_setsv(foo,bar);     # in truly static functions,
1607                                        # see objXSUB.h
1608
1609 Under PERL_OBJECT in extensions (aka PERL_CAPI), or under
1610 MULTIPLICITY/USE_THREADS w/ PERL_IMPLICIT_CONTEXT in both core
1611 and extensions, it will be:
1612
1613     Perl_sv_setsv(aTHX_ foo, bar);     # the canonical Perl "API"
1614                                        # for all build flavors
1615
1616 This doesn't work so cleanly for varargs functions, though, as macros
1617 imply that the number of arguments is known in advance.  Instead we
1618 either need to spell them out fully, passing C<aTHX_> as the first
1619 argument (the Perl core tends to do this with functions like
1620 Perl_warner), or use a context-free version.
1621
1622 The context-free version of Perl_warner is called
1623 Perl_warner_nocontext, and does not take the extra argument.  Instead
1624 it does dTHX; to get the context from thread-local storage.  We
1625 C<#define warner Perl_warner_nocontext> so that extensions get source
1626 compatibility at the expense of performance.  (Passing an arg is
1627 cheaper than grabbing it from thread-local storage.)
1628
1629 You can ignore [pad]THX[xo] when browsing the Perl headers/sources.
1630 Those are strictly for use within the core.  Extensions and embedders
1631 need only be aware of [pad]THX.
1632
1633 =head2 How do I use all this in extensions?
1634
1635 When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
1636 any functions in the Perl API will need to pass the initial context
1637 argument somehow.  The kicker is that you will need to write it in
1638 such a way that the extension still compiles when Perl hasn't been
1639 built with PERL_IMPLICIT_CONTEXT enabled.
1640
1641 There are three ways to do this.  First, the easy but inefficient way,
1642 which is also the default, in order to maintain source compatibility
1643 with extensions: whenever XSUB.h is #included, it redefines the aTHX
1644 and aTHX_ macros to call a function that will return the context.
1645 Thus, something like:
1646
1647         sv_setsv(asv, bsv);
1648
1649 in your extesion will translate to this:
1650
1651         Perl_sv_setsv(GetPerlInterpreter(), asv, bsv);
1652
1653 when PERL_IMPLICIT_CONTEXT is in effect, or to this otherwise:
1654
1655         Perl_sv_setsv(asv, bsv);
1656
1657 You have to do nothing new in your extension to get this; since
1658 the Perl library provides GetPerlInterpreter(), it will all just
1659 work.
1660
1661 The second, more efficient way is to use the following template for
1662 your Foo.xs:
1663
1664         #define PERL_NO_GET_CONTEXT     /* we want efficiency */
1665         #include "EXTERN.h"
1666         #include "perl.h"
1667         #include "XSUB.h"
1668
1669         static my_private_function(int arg1, int arg2);
1670
1671         static SV *
1672         my_private_function(pTHX_ int arg1, int arg2)
1673         {
1674             dTHX;       /* fetch context */
1675             ... call many Perl API functions ...
1676         }
1677
1678         [... etc ...]
1679
1680         MODULE = Foo            PACKAGE = Foo
1681
1682         /* typical XSUB */
1683
1684         void
1685         my_xsub(arg)
1686                 int arg
1687             CODE:
1688                 my_private_function(arg, 10);
1689
1690 Note that the only two changes from the normal way of writing an
1691 extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before
1692 including the Perl headers, followed by a C<dTHX;> declaration at
1693 the start of every function that will call the Perl API.  (You'll
1694 know which functions need this, because the C compiler will complain
1695 that there's an undeclared identifier in those functions.)  No changes
1696 are needed for the XSUBs themselves, because the XS() macro is
1697 correctly defined to pass in the implicit context if needed.
1698
1699 The third, even more efficient way is to ape how it is done within
1700 the Perl guts:
1701
1702
1703         #define PERL_NO_GET_CONTEXT     /* we want efficiency */
1704         #include "EXTERN.h"
1705         #include "perl.h"
1706         #include "XSUB.h"
1707
1708         /* pTHX_ only needed for functions that call Perl API */
1709         static my_private_function(pTHX_ int arg1, int arg2);
1710
1711         static SV *
1712         my_private_function(pTHX_ int arg1, int arg2)
1713         {
1714             /* dTHX; not needed here, because THX is an argument */
1715             ... call Perl API functions ...
1716         }
1717
1718         [... etc ...]
1719
1720         MODULE = Foo            PACKAGE = Foo
1721
1722         /* typical XSUB */
1723
1724         void
1725         my_xsub(arg)
1726                 int arg
1727             CODE:
1728                 my_private_function(aTHX_ arg, 10);
1729
1730 This implementation never has to fetch the context using a function
1731 call, since it is always passed as an extra argument.  Depending on
1732 your needs for simplicity or efficiency, you may mix the previous
1733 two approaches freely.
1734
1735 Never say C<pTHX,> yourself--always use the form of the macro with the
1736 underscore for functions that take explicit arguments, or the form
1737 without the argument for functions with no explicit arguments.
1738
1739 =head2 Future Plans and PERL_IMPLICIT_SYS
1740
1741 Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
1742 that the interpreter knows about itself and pass it around, so too are
1743 there plans to allow the interpreter to bundle up everything it knows
1744 about the environment it's running on.  This is enabled with the
1745 PERL_IMPLICIT_SYS macro.  Currently it only works with PERL_OBJECT,
1746 but is mostly there for MULTIPLICITY and USE_THREADS (see inside
1747 iperlsys.h).
1748
1749 This allows the ability to provide an extra pointer (called the "host"
1750 environment) for all the system calls.  This makes it possible for
1751 all the system stuff to maintain their own state, broken down into
1752 seven C structures.  These are thin wrappers around the usual system
1753 calls (see win32/perllib.c) for the default perl executable, but for a
1754 more ambitious host (like the one that would do fork() emulation) all
1755 the extra work needed to pretend that different interpreters are
1756 actually different "processes", would be done here.
1757
1758 The Perl engine/interpreter and the host are orthogonal entities.
1759 There could be one or more interpreters in a process, and one or
1760 more "hosts", with free association between them.
1761
1762 =head1 API LISTING
1763
1764 This is a listing of functions, macros, flags, and variables that may be
1765 useful to extension writers or that may be found while reading other
1766 extensions.
1767
1768 Note that all Perl API global variables must be referenced with the C<PL_>
1769 prefix.  Some macros are provided for compatibility with the older,
1770 unadorned names, but this support may be disabled in a future release.
1771
1772 The sort order of the listing is case insensitive, with any
1773 occurrences of '_' ignored for the purpose of sorting.
1774
1775 =over 8
1776
1777 =item av_clear
1778
1779 Clears an array, making it empty.  Does not free the memory used by the
1780 array itself.
1781
1782         void    av_clear (AV* ar)
1783
1784 =item av_extend
1785
1786 Pre-extend an array.  The C<key> is the index to which the array should be
1787 extended.
1788
1789         void    av_extend (AV* ar, I32 key)
1790
1791 =item av_fetch
1792
1793 Returns the SV at the specified index in the array.  The C<key> is the
1794 index.  If C<lval> is set then the fetch will be part of a store.  Check
1795 that the return value is non-null before dereferencing it to a C<SV*>.
1796
1797 See L<Understanding the Magic of Tied Hashes and Arrays> for more
1798 information on how to use this function on tied arrays.
1799
1800         SV**    av_fetch (AV* ar, I32 key, I32 lval)
1801
1802 =item AvFILL
1803
1804 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
1805
1806 =item av_len
1807
1808 Returns the highest index in the array.  Returns -1 if the array is empty.
1809
1810         I32     av_len (AV* ar)
1811
1812 =item av_make
1813
1814 Creates a new AV and populates it with a list of SVs.  The SVs are copied
1815 into the array, so they may be freed after the call to av_make.  The new AV
1816 will have a reference count of 1.
1817
1818         AV*     av_make (I32 size, SV** svp)
1819
1820 =item av_pop
1821
1822 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array is
1823 empty.
1824
1825         SV*     av_pop (AV* ar)
1826
1827 =item av_push
1828
1829 Pushes an SV onto the end of the array.  The array will grow automatically
1830 to accommodate the addition.
1831
1832         void    av_push (AV* ar, SV* val)
1833
1834 =item av_shift
1835
1836 Shifts an SV off the beginning of the array.
1837
1838         SV*     av_shift (AV* ar)
1839
1840 =item av_store
1841
1842 Stores an SV in an array.  The array index is specified as C<key>.  The
1843 return value will be NULL if the operation failed or if the value did not
1844 need to be actually stored within the array (as in the case of tied arrays).
1845 Otherwise it can be dereferenced to get the original C<SV*>.  Note that the
1846 caller is responsible for suitably incrementing the reference count of C<val>
1847 before the call, and decrementing it if the function returned NULL.
1848
1849 See L<Understanding the Magic of Tied Hashes and Arrays> for more
1850 information on how to use this function on tied arrays.
1851
1852         SV**    av_store (AV* ar, I32 key, SV* val)
1853
1854 =item av_undef
1855
1856 Undefines the array.  Frees the memory used by the array itself.
1857
1858         void    av_undef (AV* ar)
1859
1860 =item av_unshift
1861
1862 Unshift the given number of C<undef> values onto the beginning of the
1863 array.  The array will grow automatically to accommodate the addition.
1864 You must then use C<av_store> to assign values to these new elements.
1865
1866         void    av_unshift (AV* ar, I32 num)
1867
1868 =item CLASS
1869
1870 Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
1871 constructor.  This is always a C<char*>.  See C<THIS> and
1872 L<perlxs/"Using XS With C++">.
1873
1874 =item Copy
1875
1876 The XSUB-writer's interface to the C C<memcpy> function.  The C<s> is the
1877 source, C<d> is the destination, C<n> is the number of items, and C<t> is
1878 the type.  May fail on overlapping copies.  See also C<Move>.
1879
1880         void    Copy( s, d, n, t )
1881
1882 =item croak
1883
1884 This is the XSUB-writer's interface to Perl's C<die> function.  Use this
1885 function the same way you use the C C<printf> function.  See C<warn>.
1886
1887 =item CvSTASH
1888
1889 Returns the stash of the CV.
1890
1891         HV*     CvSTASH( SV* sv )
1892
1893 =item PL_DBsingle
1894
1895 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1896 boolean which indicates whether subs are being single-stepped.
1897 Single-stepping is automatically turned on after every step.  This is the C
1898 variable which corresponds to Perl's $DB::single variable.  See C<PL_DBsub>.
1899
1900 =item PL_DBsub
1901
1902 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1903 the SV which holds the name of the sub being debugged.  This is the C
1904 variable which corresponds to Perl's $DB::sub variable.  See C<PL_DBsingle>.
1905 The sub name can be found by
1906
1907         SvPV( GvSV( PL_DBsub ), len )
1908
1909 =item PL_DBtrace
1910
1911 Trace variable used when Perl is run in debugging mode, with the B<-d>
1912 switch.  This is the C variable which corresponds to Perl's $DB::trace
1913 variable.  See C<PL_DBsingle>.
1914
1915 =item dMARK
1916
1917 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
1918 C<dORIGMARK>.
1919
1920 =item dORIGMARK
1921
1922 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
1923
1924 =item PL_dowarn
1925
1926 The C variable which corresponds to Perl's $^W warning variable.
1927
1928 =item dSP
1929
1930 Declares a local copy of perl's stack pointer for the XSUB, available via
1931 the C<SP> macro.  See C<SP>.
1932
1933 =item dXSARGS
1934
1935 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This is
1936 usually handled automatically by C<xsubpp>.  Declares the C<items> variable
1937 to indicate the number of items on the stack.
1938
1939 =item dXSI32
1940
1941 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
1942 handled automatically by C<xsubpp>.
1943
1944 =item do_binmode
1945
1946 Switches filehandle to binmode.  C<iotype> is what C<IoTYPE(io)> would
1947 contain.
1948
1949         do_binmode(fp, iotype, TRUE);
1950
1951 =item ENTER
1952
1953 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
1954
1955         ENTER;
1956
1957 =item EXTEND
1958
1959 Used to extend the argument stack for an XSUB's return values.
1960
1961         EXTEND( sp, int x )
1962
1963 =item fbm_compile
1964
1965 Analyses the string in order to make fast searches on it using fbm_instr() --
1966 the Boyer-Moore algorithm.
1967
1968         void    fbm_compile(SV* sv, U32 flags)
1969
1970 =item fbm_instr
1971
1972 Returns the location of the SV in the string delimited by C<str> and
1973 C<strend>.  It returns C<Nullch> if the string can't be found.  The
1974 C<sv> does not have to be fbm_compiled, but the search will not be as
1975 fast then.
1976
1977         char*   fbm_instr(char *str, char *strend, SV *sv, U32 flags)
1978
1979 =item FREETMPS
1980
1981 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
1982 L<perlcall>.
1983
1984         FREETMPS;
1985
1986 =item G_ARRAY
1987
1988 Used to indicate array context.  See C<GIMME_V>, C<GIMME> and L<perlcall>.
1989
1990 =item G_DISCARD
1991
1992 Indicates that arguments returned from a callback should be discarded.  See
1993 L<perlcall>.
1994
1995 =item G_EVAL
1996
1997 Used to force a Perl C<eval> wrapper around a callback.  See L<perlcall>.
1998
1999 =item GIMME
2000
2001 A backward-compatible version of C<GIMME_V> which can only return
2002 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
2003
2004 =item GIMME_V
2005
2006 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns
2007 C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
2008 context, respectively.
2009
2010 =item G_NOARGS
2011
2012 Indicates that no arguments are being sent to a callback.  See L<perlcall>.
2013
2014 =item G_SCALAR
2015
2016 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and L<perlcall>.
2017
2018 =item gv_fetchmeth
2019
2020 Returns the glob with the given C<name> and a defined subroutine or
2021 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
2022 accessible via @ISA and @UNIVERSAL.
2023
2024 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
2025 side-effect creates a glob with the given C<name> in the given
2026 C<stash> which in the case of success contains an alias for the
2027 subroutine, and sets up caching info for this glob.  Similarly for all
2028 the searched stashes.
2029
2030 This function grants C<"SUPER"> token as a postfix of the stash name.
2031
2032 The GV returned from C<gv_fetchmeth> may be a method cache entry,
2033 which is not visible to Perl code.  So when calling C<perl_call_sv>,
2034 you should not use the GV directly; instead, you should use the
2035 method's CV, which can be obtained from the GV with the C<GvCV> macro.
2036
2037         GV*     gv_fetchmeth (HV* stash, const char* name, STRLEN len, I32 level)
2038
2039 =item gv_fetchmethod
2040
2041 =item gv_fetchmethod_autoload
2042
2043 Returns the glob which contains the subroutine to call to invoke the
2044 method on the C<stash>.  In fact in the presence of autoloading this may
2045 be the glob for "AUTOLOAD".  In this case the corresponding variable
2046 $AUTOLOAD is already setup.
2047
2048 The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
2049 lookup is performed if the given method is not present: non-zero means
2050 yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.  Calling
2051 C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
2052 non-zero C<autoload> parameter.
2053
2054 These functions grant C<"SUPER"> token as a prefix of the method name.
2055
2056 Note that if you want to keep the returned glob for a long time, you
2057 need to check for it being "AUTOLOAD", since at the later time the call
2058 may load a different subroutine due to $AUTOLOAD changing its value.
2059 Use the glob created via a side effect to do this.
2060
2061 These functions have the same side-effects and as C<gv_fetchmeth> with
2062 C<level==0>.  C<name> should be writable if contains C<':'> or C<'\''>.
2063 The warning against passing the GV returned by C<gv_fetchmeth> to
2064 C<perl_call_sv> apply equally to these functions.
2065
2066         GV*     gv_fetchmethod (HV* stash, const char* name)
2067         GV*     gv_fetchmethod_autoload (HV* stash, const char* name, I32 autoload)
2068
2069 =item G_VOID
2070
2071 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
2072
2073 =item gv_stashpv
2074
2075 Returns a pointer to the stash for a specified package.  If C<create> is set
2076 then the package will be created if it does not already exist.  If C<create>
2077 is not set and the package does not exist then NULL is returned.
2078
2079         HV*     gv_stashpv (const char* name, I32 create)
2080
2081 =item gv_stashsv
2082
2083 Returns a pointer to the stash for a specified package.  See C<gv_stashpv>.
2084
2085         HV*     gv_stashsv (SV* sv, I32 create)
2086
2087 =item GvSV
2088
2089 Return the SV from the GV.
2090
2091 =item HEf_SVKEY
2092
2093 This flag, used in the length slot of hash entries and magic
2094 structures, specifies the structure contains a C<SV*> pointer where a
2095 C<char*> pointer is to be expected. (For information only--not to be used).
2096
2097 =item HeHASH
2098
2099 Returns the computed hash stored in the hash entry.
2100
2101         U32     HeHASH(HE* he)
2102
2103 =item HeKEY
2104
2105 Returns the actual pointer stored in the key slot of the hash entry.
2106 The pointer may be either C<char*> or C<SV*>, depending on the value of
2107 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros
2108 are usually preferable for finding the value of a key.
2109
2110         char*   HeKEY(HE* he)
2111
2112 =item HeKLEN
2113
2114 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
2115 holds an C<SV*> key.  Otherwise, holds the actual length of the key.
2116 Can be assigned to. The C<HePV()> macro is usually preferable for finding
2117 key lengths.
2118
2119         int     HeKLEN(HE* he)
2120
2121 =item HePV
2122
2123 Returns the key slot of the hash entry as a C<char*> value, doing any
2124 necessary dereferencing of possibly C<SV*> keys.  The length of
2125 the string is placed in C<len> (this is a macro, so do I<not> use
2126 C<&len>).  If you do not care about what the length of the key is,
2127 you may use the global variable C<PL_na>, though this is rather less
2128 efficient than using a local variable.  Remember though, that hash
2129 keys in perl are free to contain embedded nulls, so using C<strlen()>
2130 or similar is not a good way to find the length of hash keys.
2131 This is very similar to the C<SvPV()> macro described elsewhere in
2132 this document.
2133
2134         char*   HePV(HE* he, STRLEN len)
2135
2136 =item HeSVKEY
2137
2138 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
2139 does not contain an C<SV*> key.
2140
2141         HeSVKEY(HE* he)
2142
2143 =item HeSVKEY_force
2144
2145 Returns the key as an C<SV*>.  Will create and return a temporary
2146 mortal C<SV*> if the hash entry contains only a C<char*> key.
2147
2148         HeSVKEY_force(HE* he)
2149
2150 =item HeSVKEY_set
2151
2152 Sets the key to a given C<SV*>, taking care to set the appropriate flags
2153 to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
2154
2155         HeSVKEY_set(HE* he, SV* sv)
2156
2157 =item HeVAL
2158
2159 Returns the value slot (type C<SV*>) stored in the hash entry.
2160
2161         HeVAL(HE* he)
2162
2163 =item hv_clear
2164
2165 Clears a hash, making it empty.
2166
2167         void    hv_clear (HV* tb)
2168
2169 =item hv_delete
2170
2171 Deletes a key/value pair in the hash.  The value SV is removed from the hash
2172 and returned to the caller.  The C<klen> is the length of the key.  The
2173 C<flags> value will normally be zero; if set to G_DISCARD then NULL will be
2174 returned.
2175
2176         SV*     hv_delete (HV* tb, const char* key, U32 klen, I32 flags)
2177
2178 =item hv_delete_ent
2179
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<flags> value will normally be zero; if set
2182 to G_DISCARD then NULL will be returned.  C<hash> can be a valid precomputed
2183 hash value, or 0 to ask for it to be computed.
2184
2185         SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash)
2186
2187 =item hv_exists
2188
2189 Returns a boolean indicating whether the specified hash key exists.  The
2190 C<klen> is the length of the key.
2191
2192         bool    hv_exists (HV* tb, const char* key, U32 klen)
2193
2194 =item hv_exists_ent
2195
2196 Returns a boolean indicating whether the specified hash key exists. C<hash>
2197 can be a valid precomputed hash value, or 0 to ask for it to be computed.
2198
2199         bool    hv_exists_ent (HV* tb, SV* key, U32 hash)
2200
2201 =item hv_fetch
2202
2203 Returns the SV which corresponds to the specified key in the hash.  The
2204 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
2205 part of a store.  Check that the return value is non-null before
2206 dereferencing it to a C<SV*>.
2207
2208 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2209 information on how to use this function on tied hashes.
2210
2211         SV**    hv_fetch (HV* tb, const char* key, U32 klen, I32 lval)
2212
2213 =item hv_fetch_ent
2214
2215 Returns the hash entry which corresponds to the specified key in the hash.
2216 C<hash> must be a valid precomputed hash number for the given C<key>, or
2217 0 if you want the function to compute it.  IF C<lval> is set then the
2218 fetch will be part of a store.  Make sure the return value is non-null
2219 before accessing it.  The return value when C<tb> is a tied hash
2220 is a pointer to a static location, so be sure to make a copy of the
2221 structure if you need to store it somewhere.
2222
2223 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2224 information on how to use this function on tied hashes.
2225
2226         HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash)
2227
2228 =item hv_iterinit
2229
2230 Prepares a starting point to traverse a hash table.
2231
2232         I32     hv_iterinit (HV* tb)
2233
2234 Returns the number of keys in the hash (i.e. the same as C<HvKEYS(tb)>).
2235 The return value is currently only meaningful for hashes without tie
2236 magic.
2237
2238 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number
2239 of hash buckets that happen to be in use.  If you still need that
2240 esoteric value, you can get it through the macro C<HvFILL(tb)>.
2241
2242 =item hv_iterkey
2243
2244 Returns the key from the current position of the hash iterator.  See
2245 C<hv_iterinit>.
2246
2247         char*   hv_iterkey (HE* entry, I32* retlen)
2248
2249 =item hv_iterkeysv
2250
2251 Returns the key as an C<SV*> from the current position of the hash
2252 iterator.  The return value will always be a mortal copy of the
2253 key.  Also see C<hv_iterinit>.
2254
2255         SV*     hv_iterkeysv  (HE* entry)
2256
2257 =item hv_iternext
2258
2259 Returns entries from a hash iterator.  See C<hv_iterinit>.
2260
2261         HE*     hv_iternext (HV* tb)
2262
2263 =item hv_iternextsv
2264
2265 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
2266 operation.
2267
2268         SV*     hv_iternextsv (HV* hv, char** key, I32* retlen)
2269
2270 =item hv_iterval
2271
2272 Returns the value from the current position of the hash iterator.  See
2273 C<hv_iterkey>.
2274
2275         SV*     hv_iterval (HV* tb, HE* entry)
2276
2277 =item hv_magic
2278
2279 Adds magic to a hash.  See C<sv_magic>.
2280
2281         void    hv_magic (HV* hv, GV* gv, int how)
2282
2283 =item HvNAME
2284
2285 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
2286
2287         char*   HvNAME (HV* stash)
2288
2289 =item hv_store
2290
2291 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
2292 the length of the key.  The C<hash> parameter is the precomputed hash
2293 value; if it is zero then Perl will compute it.  The return value will be
2294 NULL if the operation failed or if the value did not need to be actually
2295 stored within the hash (as in the case of tied hashes).  Otherwise it can
2296 be dereferenced to get the original C<SV*>.  Note that the caller is
2297 responsible for suitably incrementing the reference count of C<val>
2298 before the call, and decrementing it if the function returned NULL.
2299
2300 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2301 information on how to use this function on tied hashes.
2302
2303         SV**    hv_store (HV* tb, const char* key, U32 klen, SV* val, U32 hash)
2304
2305 =item hv_store_ent
2306
2307 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
2308 parameter is the precomputed hash value; if it is zero then Perl will
2309 compute it.  The return value is the new hash entry so created.  It will be
2310 NULL if the operation failed or if the value did not need to be actually
2311 stored within the hash (as in the case of tied hashes).  Otherwise the
2312 contents of the return value can be accessed using the C<He???> macros
2313 described here.  Note that the caller is responsible for suitably
2314 incrementing the reference count of C<val> before the call, and decrementing
2315 it if the function returned NULL.
2316
2317 See L<Understanding the Magic of Tied Hashes and Arrays> for more
2318 information on how to use this function on tied hashes.
2319
2320         HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash)
2321
2322 =item hv_undef
2323
2324 Undefines the hash.
2325
2326         void    hv_undef (HV* tb)
2327
2328 =item isALNUM
2329
2330 Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
2331 character or digit.
2332
2333         int     isALNUM (char c)
2334
2335 =item isALPHA
2336
2337 Returns a boolean indicating whether the C C<char> is an ascii alphabetic
2338 character.
2339
2340         int     isALPHA (char c)
2341
2342 =item isDIGIT
2343
2344 Returns a boolean indicating whether the C C<char> is an ascii digit.
2345
2346         int     isDIGIT (char c)
2347
2348 =item isLOWER
2349
2350 Returns a boolean indicating whether the C C<char> is a lowercase character.
2351
2352         int     isLOWER (char c)
2353
2354 =item isSPACE
2355
2356 Returns a boolean indicating whether the C C<char> is whitespace.
2357
2358         int     isSPACE (char c)
2359
2360 =item isUPPER
2361
2362 Returns a boolean indicating whether the C C<char> is an uppercase character.
2363
2364         int     isUPPER (char c)
2365
2366 =item items
2367
2368 Variable which is setup by C<xsubpp> to indicate the number of items on the
2369 stack.  See L<perlxs/"Variable-length Parameter Lists">.
2370
2371 =item ix
2372
2373 Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
2374 was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
2375
2376 =item LEAVE
2377
2378 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
2379
2380         LEAVE;
2381
2382 =item looks_like_number
2383
2384 Test if an the content of an SV looks like a number (or is a number).
2385
2386         int     looks_like_number(SV*)
2387
2388
2389 =item MARK
2390
2391 Stack marker variable for the XSUB.  See C<dMARK>.
2392
2393 =item mg_clear
2394
2395 Clear something magical that the SV represents.  See C<sv_magic>.
2396
2397         int     mg_clear (SV* sv)
2398
2399 =item mg_copy
2400
2401 Copies the magic from one SV to another.  See C<sv_magic>.
2402
2403         int     mg_copy (SV *, SV *, const char *, STRLEN)
2404
2405 =item mg_find
2406
2407 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
2408
2409         MAGIC*  mg_find (SV* sv, int type)
2410
2411 =item mg_free
2412
2413 Free any magic storage used by the SV.  See C<sv_magic>.
2414
2415         int     mg_free (SV* sv)
2416
2417 =item mg_get
2418
2419 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
2420
2421         int     mg_get (SV* sv)
2422
2423 =item mg_len
2424
2425 Report on the SV's length.  See C<sv_magic>.
2426
2427         U32     mg_len (SV* sv)
2428
2429 =item mg_magical
2430
2431 Turns on the magical status of an SV.  See C<sv_magic>.
2432
2433         void    mg_magical (SV* sv)
2434
2435 =item mg_set
2436
2437 Do magic after a value is assigned to the SV.  See C<sv_magic>.
2438
2439         int     mg_set (SV* sv)
2440
2441 =item modglobal
2442
2443 C<modglobal> is a general purpose, interpreter global HV for use by
2444 extensions that need to keep information on a per-interpreter basis.
2445 In a pinch, it can also be used as a symbol table for extensions
2446 to share data among each other.  It is a good idea to use keys
2447 prefixed by the package name of the extension that owns the data.
2448
2449 =item Move
2450
2451 The XSUB-writer's interface to the C C<memmove> function.  The C<s> is the
2452 source, C<d> is the destination, C<n> is the number of items, and C<t> is
2453 the type.  Can do overlapping moves.  See also C<Copy>.
2454
2455         void    Move( s, d, n, t )
2456
2457 =item PL_na
2458
2459 A convenience variable which is typically used with C<SvPV> when one doesn't
2460 care about the length of the string.  It is usually more efficient to
2461 either declare a local variable and use that instead or to use the C<SvPV_nolen>
2462 macro.
2463
2464 =item New
2465
2466 The XSUB-writer's interface to the C C<malloc> function.
2467
2468         void*   New( x, void *ptr, int size, type )
2469
2470 =item newAV
2471
2472 Creates a new AV.  The reference count is set to 1.
2473
2474         AV*     newAV (void)
2475
2476 =item Newc
2477
2478 The XSUB-writer's interface to the C C<malloc> function, with cast.
2479
2480         void*   Newc( x, void *ptr, int size, type, cast )
2481
2482 =item newCONSTSUB
2483
2484 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }>
2485 which is eligible for inlining at compile-time.
2486
2487         void    newCONSTSUB(HV* stash, char* name, SV* sv)
2488
2489 =item newHV
2490
2491 Creates a new HV.  The reference count is set to 1.
2492
2493         HV*     newHV (void)
2494
2495 =item newRV_inc
2496
2497 Creates an RV wrapper for an SV.  The reference count for the original SV is
2498 incremented.
2499
2500         SV*     newRV_inc (SV* ref)
2501
2502 For historical reasons, "newRV" is a synonym for "newRV_inc".
2503
2504 =item newRV_noinc
2505
2506 Creates an RV wrapper for an SV.  The reference count for the original
2507 SV is B<not> incremented.
2508
2509         SV*     newRV_noinc (SV* ref)
2510
2511 =item NEWSV
2512
2513 Creates a new SV.  A non-zero C<len> parameter indicates the number of
2514 bytes of preallocated string space the SV should have.  An extra byte
2515 for a tailing NUL is also reserved.  (SvPOK is not set for the SV even
2516 if string space is allocated.)  The reference count for the new SV is
2517 set to 1.  C<id> is an integer id between 0 and 1299 (used to identify
2518 leaks).
2519
2520         SV*     NEWSV (int id, STRLEN len)
2521
2522 =item newSViv
2523
2524 Creates a new SV and copies an integer into it.  The reference count for the
2525 SV is set to 1.
2526
2527         SV*     newSViv (IV i)
2528
2529 =item newSVnv
2530
2531 Creates a new SV and copies a double into it.  The reference count for the
2532 SV is set to 1.
2533
2534         SV*     newSVnv (NV i)
2535
2536 =item newSVpv
2537
2538 Creates a new SV and copies a string into it.  The reference count for the
2539 SV is set to 1.  If C<len> is zero, Perl will compute the length using
2540 strlen().  For efficiency, consider using C<newSVpvn> instead.
2541
2542         SV*     newSVpv (const char* s, STRLEN len)
2543
2544 =item newSVpvf
2545
2546 Creates a new SV an initialize it with the string formatted like
2547 C<sprintf>.
2548
2549         SV*     newSVpvf(const char* pat, ...)
2550
2551 =item newSVpvn
2552
2553 Creates a new SV and copies a string into it.  The reference count for the
2554 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length 
2555 string.  You are responsible for ensuring that the source string is at least
2556 C<len> bytes long.
2557
2558         SV*     newSVpvn (const char* s, STRLEN len)
2559
2560 =item newSVrv
2561
2562 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
2563 it will be upgraded to one.  If C<classname> is non-null then the new SV will
2564 be blessed in the specified package.  The new SV is returned and its
2565 reference count is 1.
2566
2567         SV*     newSVrv (SV* rv, const char* classname)
2568
2569 =item newSVsv
2570
2571 Creates a new SV which is an exact duplicate of the original SV.
2572
2573         SV*     newSVsv (SV* old)
2574
2575 =item newXS
2576
2577 Used by C<xsubpp> to hook up XSUBs as Perl subs.
2578
2579 =item newXSproto
2580
2581 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
2582 the subs.
2583
2584 =item Newz
2585
2586 The XSUB-writer's interface to the C C<malloc> function.  The allocated
2587 memory is zeroed with C<memzero>.
2588
2589         void*   Newz( x, void *ptr, int size, type )
2590
2591 =item Nullav
2592
2593 Null AV pointer.
2594
2595 =item Nullch
2596
2597 Null character pointer.
2598
2599 =item Nullcv
2600
2601 Null CV pointer.
2602
2603 =item Nullhv
2604
2605 Null HV pointer.
2606
2607 =item Nullsv
2608
2609 Null SV pointer.
2610
2611 =item ORIGMARK
2612
2613 The original stack mark for the XSUB.  See C<dORIGMARK>.
2614
2615 =item perl_alloc
2616
2617 Allocates a new Perl interpreter.  See L<perlembed>.
2618
2619 =item perl_call_argv
2620
2621 Performs a callback to the specified Perl sub.  See L<perlcall>.
2622
2623         I32     perl_call_argv (const char* subname, I32 flags, char** argv)
2624
2625 =item perl_call_method
2626
2627 Performs a callback to the specified Perl method.  The blessed object must
2628 be on the stack.  See L<perlcall>.
2629
2630         I32     perl_call_method (const char* methname, I32 flags)
2631
2632 =item perl_call_pv
2633
2634 Performs a callback to the specified Perl sub.  See L<perlcall>.
2635
2636         I32     perl_call_pv (const char* subname, I32 flags)
2637
2638 =item perl_call_sv
2639
2640 Performs a callback to the Perl sub whose name is in the SV.  See
2641 L<perlcall>.
2642
2643         I32     perl_call_sv (SV* sv, I32 flags)
2644
2645 =item perl_construct
2646
2647 Initializes a new Perl interpreter.  See L<perlembed>.
2648
2649 =item perl_destruct
2650
2651 Shuts down a Perl interpreter.  See L<perlembed>.
2652
2653 =item perl_eval_sv
2654
2655 Tells Perl to C<eval> the string in the SV.
2656
2657         I32     perl_eval_sv (SV* sv, I32 flags)
2658
2659 =item perl_eval_pv
2660
2661 Tells Perl to C<eval> the given string and return an SV* result.
2662
2663         SV*     perl_eval_pv (const char* p, I32 croak_on_error)
2664
2665 =item perl_free
2666
2667 Releases a Perl interpreter.  See L<perlembed>.
2668
2669 =item perl_get_av
2670
2671 Returns the AV of the specified Perl array.  If C<create> is set and the
2672 Perl variable does not exist then it will be created.  If C<create> is not
2673 set and the variable does not exist then NULL is returned.
2674
2675         AV*     perl_get_av (const char* name, I32 create)
2676
2677 =item perl_get_cv
2678
2679 Returns the CV of the specified Perl subroutine.  If C<create> is set and
2680 the Perl subroutine does not exist then it will be declared (which has
2681 the same effect as saying C<sub name;>).  If C<create> is not
2682 set and the subroutine does not exist then NULL is returned.
2683
2684         CV*     perl_get_cv (const char* name, I32 create)
2685
2686 =item perl_get_hv
2687
2688 Returns the HV of the specified Perl hash.  If C<create> is set and the Perl
2689 variable does not exist then it will be created.  If C<create> is not
2690 set and the variable does not exist then NULL is returned.
2691
2692         HV*     perl_get_hv (const char* name, I32 create)
2693
2694 =item perl_get_sv
2695
2696 Returns the SV of the specified Perl scalar.  If C<create> is set and the
2697 Perl variable does not exist then it will be created.  If C<create> is not
2698 set and the variable does not exist then NULL is returned.
2699
2700         SV*     perl_get_sv (const char* name, I32 create)
2701
2702 =item perl_parse
2703
2704 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
2705
2706 =item perl_require_pv
2707
2708 Tells Perl to C<require> a module.
2709
2710         void    perl_require_pv (const char* pv)
2711
2712 =item perl_run
2713
2714 Tells a Perl interpreter to run.  See L<perlembed>.
2715
2716 =item POPi
2717
2718 Pops an integer off the stack.
2719
2720         int     POPi()
2721
2722 =item POPl
2723
2724 Pops a long off the stack.
2725
2726         long    POPl()
2727
2728 =item POPp
2729
2730 Pops a string off the stack.
2731
2732         char*   POPp()
2733
2734 =item POPn
2735
2736 Pops a double off the stack.
2737
2738         double  POPn()
2739
2740 =item POPs
2741
2742 Pops an SV off the stack.
2743
2744         SV*     POPs()
2745
2746 =item PUSHMARK
2747
2748 Opening bracket for arguments on a callback.  See C<PUTBACK> and L<perlcall>.
2749
2750         PUSHMARK(p)
2751
2752 =item PUSHi
2753
2754 Push an integer onto the stack.  The stack must have room for this element.
2755 Handles 'set' magic.  See C<XPUSHi>.
2756
2757         void    PUSHi(int d)
2758
2759 =item PUSHn
2760
2761 Push a double onto the stack.  The stack must have room for this element.
2762 Handles 'set' magic.  See C<XPUSHn>.
2763
2764         void    PUSHn(double d)
2765
2766 =item PUSHp
2767
2768 Push a string onto the stack.  The stack must have room for this element.
2769 The C<len> indicates the length of the string.  Handles 'set' magic.  See
2770 C<XPUSHp>.
2771
2772         void    PUSHp(char *c, int len )
2773
2774 =item PUSHs
2775
2776 Push an SV onto the stack.  The stack must have room for this element.  Does
2777 not handle 'set' magic.  See C<XPUSHs>.
2778
2779         void    PUSHs(sv)
2780
2781 =item PUSHu
2782
2783 Push an unsigned integer onto the stack.  The stack must have room for
2784 this element.  See C<XPUSHu>.
2785
2786         void    PUSHu(unsigned int d)
2787
2788
2789 =item PUTBACK
2790
2791 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
2792 See C<PUSHMARK> and L<perlcall> for other uses.
2793
2794         PUTBACK;
2795
2796 =item Renew
2797
2798 The XSUB-writer's interface to the C C<realloc> function.
2799
2800         void*   Renew( void *ptr, int size, type )
2801
2802 =item Renewc
2803
2804 The XSUB-writer's interface to the C C<realloc> function, with cast.
2805
2806         void*   Renewc( void *ptr, int size, type, cast )
2807
2808 =item RETVAL
2809
2810 Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
2811 This is always the proper type for the XSUB.
2812 See L<perlxs/"The RETVAL Variable">.
2813
2814 =item safefree
2815
2816 The XSUB-writer's interface to the C C<free> function.
2817
2818 =item safemalloc
2819
2820 The XSUB-writer's interface to the C C<malloc> function.
2821
2822 =item saferealloc
2823
2824 The XSUB-writer's interface to the C C<realloc> function.
2825
2826 =item savepv
2827
2828 Copy a string to a safe spot.  This does not use an SV.
2829
2830         char*   savepv (const char* sv)
2831
2832 =item savepvn
2833
2834 Copy a string to a safe spot.  The C<len> indicates number of bytes to
2835 copy.  This does not use an SV.
2836
2837         char*   savepvn (const char* sv, I32 len)
2838
2839 =item SAVETMPS
2840
2841 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
2842 L<perlcall>.
2843
2844         SAVETMPS;
2845
2846 =item SP
2847
2848 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
2849 C<SPAGAIN>.
2850
2851 =item SPAGAIN
2852
2853 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
2854
2855         SPAGAIN;
2856
2857 =item ST
2858
2859 Used to access elements on the XSUB's stack.
2860
2861         SV*     ST(int x)
2862
2863 =item strEQ
2864
2865 Test two strings to see if they are equal.  Returns true or false.
2866
2867         int     strEQ( char *s1, char *s2 )
2868
2869 =item strGE
2870
2871 Test two strings to see if the first, C<s1>, is greater than or equal to the
2872 second, C<s2>.  Returns true or false.
2873
2874         int     strGE( char *s1, char *s2 )
2875
2876 =item strGT
2877
2878 Test two strings to see if the first, C<s1>, is greater than the second,
2879 C<s2>.  Returns true or false.
2880
2881         int     strGT( char *s1, char *s2 )
2882
2883 =item strLE
2884
2885 Test two strings to see if the first, C<s1>, is less than or equal to the
2886 second, C<s2>.  Returns true or false.
2887
2888         int     strLE( char *s1, char *s2 )
2889
2890 =item strLT
2891
2892 Test two strings to see if the first, C<s1>, is less than the second,
2893 C<s2>.  Returns true or false.
2894
2895         int     strLT( char *s1, char *s2 )
2896
2897 =item strNE
2898
2899 Test two strings to see if they are different.  Returns true or false.
2900
2901         int     strNE( char *s1, char *s2 )
2902
2903 =item strnEQ
2904
2905 Test two strings to see if they are equal.  The C<len> parameter indicates
2906 the number of bytes to compare.  Returns true or false.
2907
2908         int     strnEQ( char *s1, char *s2 )
2909
2910 =item strnNE
2911
2912 Test two strings to see if they are different.  The C<len> parameter
2913 indicates the number of bytes to compare.  Returns true or false.
2914
2915         int     strnNE( char *s1, char *s2, int len )
2916
2917 =item sv_2mortal
2918
2919 Marks an SV as mortal.  The SV will be destroyed when the current context
2920 ends.
2921
2922         SV*     sv_2mortal (SV* sv)
2923
2924 =item sv_bless
2925
2926 Blesses an SV into a specified package.  The SV must be an RV.  The package
2927 must be designated by its stash (see C<gv_stashpv()>).  The reference count
2928 of the SV is unaffected.
2929
2930         SV*     sv_bless (SV* sv, HV* stash)
2931
2932 =item sv_catpv
2933
2934 Concatenates the string onto the end of the string which is in the SV.
2935 Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
2936
2937         void    sv_catpv (SV* sv, const char* ptr)
2938
2939 =item sv_catpv_mg
2940
2941 Like C<sv_catpv>, but also handles 'set' magic.
2942
2943         void    sv_catpvn (SV* sv, const char* ptr)
2944
2945 =item sv_catpvn
2946
2947 Concatenates the string onto the end of the string which is in the SV.  The
2948 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
2949 'set' magic.  See C<sv_catpvn_mg>.
2950
2951         void    sv_catpvn (SV* sv, const char* ptr, STRLEN len)
2952
2953 =item sv_catpvn_mg
2954
2955 Like C<sv_catpvn>, but also handles 'set' magic.
2956
2957         void    sv_catpvn_mg (SV* sv, const char* ptr, STRLEN len)
2958
2959 =item sv_catpvf
2960
2961 Processes its arguments like C<sprintf> and appends the formatted output
2962 to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
2963 typically be called after calling this function to handle 'set' magic.
2964
2965         void    sv_catpvf (SV* sv, const char* pat, ...)
2966
2967 =item sv_catpvf_mg
2968
2969 Like C<sv_catpvf>, but also handles 'set' magic.
2970
2971         void    sv_catpvf_mg (SV* sv, const char* pat, ...)
2972
2973 =item sv_catsv
2974
2975 Concatenates the string from SV C<ssv> onto the end of the string in SV
2976 C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
2977
2978         void    sv_catsv (SV* dsv, SV* ssv)
2979
2980 =item sv_catsv_mg
2981
2982 Like C<sv_catsv>, but also handles 'set' magic.
2983
2984         void    sv_catsv_mg (SV* dsv, SV* ssv)
2985
2986 =item sv_chop
2987
2988 Efficient removal of characters from the beginning of the string
2989 buffer.  SvPOK(sv) must be true and the C<ptr> must be a pointer to
2990 somewhere inside the string buffer.  The C<ptr> becomes the first
2991 character of the adjusted string.
2992
2993         void    sv_chop(SV* sv, const char *ptr)
2994
2995
2996 =item sv_cmp
2997
2998 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
2999 string in C<sv1> is less than, equal to, or greater than the string in
3000 C<sv2>.
3001
3002         I32     sv_cmp (SV* sv1, SV* sv2)
3003
3004 =item SvCUR
3005
3006 Returns the length of the string which is in the SV.  See C<SvLEN>.
3007
3008         int     SvCUR (SV* sv)
3009
3010 =item SvCUR_set
3011
3012 Set the length of the string which is in the SV.  See C<SvCUR>.
3013
3014         void    SvCUR_set (SV* sv, int val)
3015
3016 =item sv_dec
3017
3018 Auto-decrement of the value in the SV.
3019
3020         void    sv_dec (SV* sv)
3021
3022 =item sv_derived_from
3023
3024 Returns a boolean indicating whether the SV is derived from the specified
3025 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
3026 for class names as well as for objects.
3027
3028         bool    sv_derived_from (SV* sv, const char* name);
3029
3030 =item SvEND
3031
3032 Returns a pointer to the last character in the string which is in the SV.
3033 See C<SvCUR>.  Access the character as
3034
3035         char*   SvEND(sv)
3036
3037 =item sv_eq
3038
3039 Returns a boolean indicating whether the strings in the two SVs are
3040 identical.
3041
3042         I32     sv_eq (SV* sv1, SV* sv2)
3043
3044 =item SvGETMAGIC
3045
3046 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates
3047 its argument more than once.
3048
3049         void    SvGETMAGIC(SV *sv)
3050
3051 =item SvGROW
3052
3053 Expands the character buffer in the SV so that it has room for the
3054 indicated number of bytes (remember to reserve space for an extra
3055 trailing NUL character).  Calls C<sv_grow> to perform the expansion if
3056 necessary.  Returns a pointer to the character buffer.
3057
3058         char*   SvGROW(SV* sv, STRLEN len)
3059
3060 =item sv_grow
3061
3062 Expands the character buffer in the SV.  This will use C<sv_unref> and will
3063 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
3064 Use C<SvGROW>.
3065
3066 =item sv_inc
3067
3068 Auto-increment of the value in the SV.
3069
3070         void    sv_inc (SV* sv)
3071
3072 =item sv_insert
3073
3074 Inserts a string at the specified offset/length within the SV.
3075 Similar to the Perl substr() function.
3076
3077         void    sv_insert(SV *sv, STRLEN offset, STRLEN len,
3078                           char *str, STRLEN strlen)
3079
3080 =item SvIOK
3081
3082 Returns a boolean indicating whether the SV contains an integer.
3083
3084         int     SvIOK (SV* SV)
3085
3086 =item SvIOK_off
3087
3088 Unsets the IV status of an SV.
3089
3090         void    SvIOK_off (SV* sv)
3091
3092 =item SvIOK_on
3093
3094 Tells an SV that it is an integer.
3095
3096         void    SvIOK_on (SV* sv)
3097
3098 =item SvIOK_only
3099
3100 Tells an SV that it is an integer and disables all other OK bits.
3101
3102         void    SvIOK_only (SV* sv)
3103
3104 =item SvIOKp
3105
3106 Returns a boolean indicating whether the SV contains an integer.  Checks the
3107 B<private> setting.  Use C<SvIOK>.
3108
3109         int     SvIOKp (SV* SV)
3110
3111 =item sv_isa
3112
3113 Returns a boolean indicating whether the SV is blessed into the specified
3114 class.  This does not check for subtypes; use C<sv_derived_from> to verify
3115 an inheritance relationship.
3116
3117         int     sv_isa (SV* sv, char* name)
3118
3119 =item sv_isobject
3120
3121 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3122 object.  If the SV is not an RV, or if the object is not blessed, then this
3123 will return false.
3124
3125         int     sv_isobject (SV* sv)
3126
3127 =item SvIV
3128
3129 Coerces the given SV to an integer and returns it.
3130
3131         int SvIV (SV* sv)
3132
3133 =item SvIVX
3134
3135 Returns the integer which is stored in the SV, assuming SvIOK is true.
3136
3137         int     SvIVX (SV* sv)
3138
3139 =item SvLEN
3140
3141 Returns the size of the string buffer in the SV.  See C<SvCUR>.
3142
3143         int     SvLEN (SV* sv)
3144
3145 =item sv_len
3146
3147 Returns the length of the string in the SV.  Use C<SvCUR>.
3148
3149         STRLEN  sv_len (SV* sv)
3150
3151 =item sv_magic
3152
3153 Adds magic to an SV.
3154
3155         void    sv_magic (SV* sv, SV* obj, int how, const char* name, I32 namlen)
3156
3157 =item sv_mortalcopy
3158
3159 Creates a new SV which is a copy of the original SV.  The new SV is marked
3160 as mortal.
3161
3162         SV*     sv_mortalcopy (SV* oldsv)
3163
3164 =item sv_newmortal
3165
3166 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
3167
3168         SV*     sv_newmortal (void)
3169
3170 =item SvNIOK
3171
3172 Returns a boolean indicating whether the SV contains a number, integer or
3173 double.
3174
3175         int     SvNIOK (SV* SV)
3176
3177 =item SvNIOK_off
3178
3179 Unsets the NV/IV status of an SV.
3180
3181         void    SvNIOK_off (SV* sv)
3182
3183 =item SvNIOKp
3184
3185 Returns a boolean indicating whether the SV contains a number, integer or
3186 double.  Checks the B<private> setting.  Use C<SvNIOK>.
3187
3188         int     SvNIOKp (SV* SV)
3189
3190 =item PL_sv_no
3191
3192 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as C<&PL_sv_no>.
3193
3194 =item SvNOK
3195
3196 Returns a boolean indicating whether the SV contains a double.
3197
3198         int     SvNOK (SV* SV)
3199
3200 =item SvNOK_off
3201
3202 Unsets the NV status of an SV.
3203
3204         void    SvNOK_off (SV* sv)
3205
3206 =item SvNOK_on
3207
3208 Tells an SV that it is a double.
3209
3210         void    SvNOK_on (SV* sv)
3211
3212 =item SvNOK_only
3213
3214 Tells an SV that it is a double and disables all other OK bits.
3215
3216         void    SvNOK_only (SV* sv)
3217
3218 =item SvNOKp
3219
3220 Returns a boolean indicating whether the SV contains a double.  Checks the
3221 B<private> setting.  Use C<SvNOK>.
3222
3223         int     SvNOKp (SV* SV)
3224
3225 =item SvNV
3226
3227 Coerce the given SV to a double and return it.
3228
3229         double  SvNV (SV* sv)
3230
3231 =item SvNVX
3232
3233 Returns the double which is stored in the SV, assuming SvNOK is true.
3234
3235         double  SvNVX (SV* sv)
3236
3237 =item SvOK
3238
3239 Returns a boolean indicating whether the value is an SV.
3240
3241         int     SvOK (SV* sv)
3242
3243 =item SvOOK
3244
3245 Returns a boolean indicating whether the SvIVX is a valid offset value
3246 for the SvPVX.  This hack is used internally to speed up removal of
3247 characters from the beginning of a SvPV.  When SvOOK is true, then the
3248 start of the allocated string buffer is really (SvPVX - SvIVX).
3249
3250         int     SvOOK(SV* sv)
3251
3252 =item SvPOK
3253
3254 Returns a boolean indicating whether the SV contains a character string.
3255
3256         int     SvPOK (SV* SV)
3257
3258 =item SvPOK_off
3259
3260 Unsets the PV status of an SV.
3261
3262         void    SvPOK_off (SV* sv)
3263
3264 =item SvPOK_on
3265
3266 Tells an SV that it is a string.
3267
3268         void    SvPOK_on (SV* sv)
3269
3270 =item SvPOK_only
3271
3272 Tells an SV that it is a string and disables all other OK bits.
3273
3274         void    SvPOK_only (SV* sv)
3275
3276 =item SvPOKp
3277
3278 Returns a boolean indicating whether the SV contains a character string.
3279 Checks the B<private> setting.  Use C<SvPOK>.
3280
3281         int     SvPOKp (SV* SV)
3282
3283 =item SvPV
3284
3285 Returns a pointer to the string in the SV, or a stringified form of the SV
3286 if the SV does not contain a string.  Handles 'get' magic.
3287
3288         char*   SvPV (SV* sv, STRLEN len)
3289
3290 =item SvPV_force
3291
3292 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You
3293 want force if you are going to update the SvPVX directly.
3294
3295         char*   SvPV_force(SV* sv, STRLEN len)
3296
3297 =item SvPV_nolen
3298
3299 Returns a pointer to the string in the SV, or a stringified form of the SV
3300 if the SV does not contain a string.  Handles 'get' magic.
3301
3302         char*   SvPV_nolen (SV* sv)
3303
3304 =item SvPVX
3305
3306 Returns a pointer to the string in the SV.  The SV must contain a string.
3307
3308         char*   SvPVX (SV* sv)
3309
3310 =item SvREFCNT
3311
3312 Returns the value of the object's reference count.
3313
3314         int     SvREFCNT (SV* sv)
3315
3316 =item SvREFCNT_dec
3317
3318 Decrements the reference count of the given SV.
3319
3320         void    SvREFCNT_dec (SV* sv)
3321
3322 =item SvREFCNT_inc
3323
3324 Increments the reference count of the given SV.
3325
3326         void    SvREFCNT_inc (SV* sv)
3327
3328 =item SvROK
3329
3330 Tests if the SV is an RV.
3331
3332         int     SvROK (SV* sv)
3333
3334 =item SvROK_off
3335
3336 Unsets the RV status of an SV.
3337
3338         void    SvROK_off (SV* sv)
3339
3340 =item SvROK_on
3341
3342 Tells an SV that it is an RV.
3343
3344         void    SvROK_on (SV* sv)
3345
3346 =item SvRV
3347
3348 Dereferences an RV to return the SV.
3349
3350         SV*     SvRV (SV* sv)
3351
3352 =item SvSETMAGIC
3353
3354 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates
3355 its argument more than once.
3356
3357         void    SvSETMAGIC( SV *sv )
3358
3359 =item sv_setiv
3360
3361 Copies an integer into the given SV.  Does not handle 'set' magic.
3362 See C<sv_setiv_mg>.
3363
3364         void    sv_setiv (SV* sv, IV num)
3365
3366 =item sv_setiv_mg
3367
3368 Like C<sv_setiv>, but also handles 'set' magic.
3369
3370         void    sv_setiv_mg (SV* sv, IV num)
3371
3372 =item sv_setnv
3373
3374 Copies a double into the given SV.  Does not handle 'set' magic.
3375 See C<sv_setnv_mg>.
3376
3377         void    sv_setnv (SV* sv, double num)
3378
3379 =item sv_setnv_mg
3380
3381 Like C<sv_setnv>, but also handles 'set' magic.
3382
3383         void    sv_setnv_mg (SV* sv, double num)
3384
3385 =item sv_setpv
3386
3387 Copies a string into an SV.  The string must be null-terminated.
3388 Does not handle 'set' magic.  See C<sv_setpv_mg>.
3389
3390         void    sv_setpv (SV* sv, const char* ptr)
3391
3392 =item sv_setpv_mg
3393
3394 Like C<sv_setpv>, but also handles 'set' magic.
3395
3396         void    sv_setpv_mg (SV* sv, const char* ptr)
3397
3398 =item sv_setpviv
3399
3400 Copies an integer into the given SV, also updating its string value.
3401 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
3402
3403         void    sv_setpviv (SV* sv, IV num)
3404
3405 =item sv_setpviv_mg
3406
3407 Like C<sv_setpviv>, but also handles 'set' magic.
3408
3409         void    sv_setpviv_mg (SV* sv, IV num)
3410
3411 =item sv_setpvn
3412
3413 Copies a string into an SV.  The C<len> parameter indicates the number of
3414 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
3415
3416         void    sv_setpvn (SV* sv, const char* ptr, STRLEN len)
3417
3418 =item sv_setpvn_mg
3419
3420 Like C<sv_setpvn>, but also handles 'set' magic.
3421
3422         void    sv_setpvn_mg (SV* sv, const char* ptr, STRLEN len)
3423
3424 =item sv_setpvf
3425
3426 Processes its arguments like C<sprintf> and sets an SV to the formatted
3427 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
3428
3429         void    sv_setpvf (SV* sv, const char* pat, ...)
3430
3431 =item sv_setpvf_mg
3432
3433 Like C<sv_setpvf>, but also handles 'set' magic.
3434
3435         void    sv_setpvf_mg (SV* sv, const char* pat, ...)
3436
3437 =item sv_setref_iv
3438
3439 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
3440 argument will be upgraded to an RV.  That RV will be modified to point to
3441 the new SV.  The C<classname> argument indicates the package for the
3442 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
3443 will be returned and will have a reference count of 1.
3444
3445         SV*     sv_setref_iv (SV *rv, char *classname, IV iv)
3446
3447 =item sv_setref_nv
3448
3449 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
3450 argument will be upgraded to an RV.  That RV will be modified to point to
3451 the new SV.  The C<classname> argument indicates the package for the
3452 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
3453 will be returned and will have a reference count of 1.
3454
3455         SV*     sv_setref_nv (SV *rv, char *classname, double nv)
3456
3457 =item sv_setref_pv
3458
3459 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
3460 argument will be upgraded to an RV.  That RV will be modified to point to
3461 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
3462 into the 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.
3465
3466         SV*     sv_setref_pv (SV *rv, char *classname, void* pv)
3467
3468 Do not use with integral Perl types such as HV, AV, SV, CV, because those
3469 objects will become corrupted by the pointer copy process.
3470
3471 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3472
3473 =item sv_setref_pvn
3474
3475 Copies a string into a new SV, optionally blessing the SV.  The length of the
3476 string must be specified with C<n>.  The C<rv> argument will be upgraded to
3477 an RV.  That RV will be modified to point to the new SV.  The C<classname>
3478 argument indicates the package for the blessing.  Set C<classname> to
3479 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
3480 a reference count of 1.
3481
3482         SV*     sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n)
3483
3484 Note that C<sv_setref_pv> copies the pointer while this copies the string.
3485
3486 =item SvSetSV
3487
3488 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
3489 more than once.
3490
3491         void    SvSetSV (SV* dsv, SV* ssv)
3492
3493 =item SvSetSV_nosteal
3494
3495 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as ssv.
3496 May evaluate arguments more than once.
3497
3498         void    SvSetSV_nosteal (SV* dsv, SV* ssv)
3499
3500 =item sv_setsv
3501
3502 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
3503 The source SV may be destroyed if it is mortal.  Does not handle 'set' magic.
3504 See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and C<sv_setsv_mg>.
3505
3506         void    sv_setsv (SV* dsv, SV* ssv)
3507
3508 =item sv_setsv_mg
3509
3510 Like C<sv_setsv>, but also handles 'set' magic.
3511
3512         void    sv_setsv_mg (SV* dsv, SV* ssv)
3513
3514 =item sv_setuv
3515
3516 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
3517 See C<sv_setuv_mg>.
3518
3519         void    sv_setuv (SV* sv, UV num)
3520
3521 =item sv_setuv_mg
3522
3523 Like C<sv_setuv>, but also handles 'set' magic.
3524
3525         void    sv_setuv_mg (SV* sv, UV num)
3526
3527 =item SvSTASH
3528
3529 Returns the stash of the SV.
3530
3531         HV*     SvSTASH (SV* sv)
3532
3533 =item SvTAINT
3534
3535 Taints an SV if tainting is enabled
3536
3537         void    SvTAINT (SV* sv)
3538
3539 =item SvTAINTED
3540
3541 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.
3542
3543         int     SvTAINTED (SV* sv)
3544
3545 =item SvTAINTED_off
3546
3547 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3548 some of Perl's fundamental security features. XS module authors should
3549 not use this function unless they fully understand all the implications
3550 of unconditionally untainting the value. Untainting should be done in
3551 the standard perl fashion, via a carefully crafted regexp, rather than
3552 directly untainting variables.
3553
3554         void    SvTAINTED_off (SV* sv)
3555
3556 =item SvTAINTED_on
3557
3558 Marks an SV as tainted.
3559
3560         void    SvTAINTED_on (SV* sv)
3561
3562 =item SVt_IV
3563
3564 Integer type flag for scalars.  See C<svtype>.
3565
3566 =item SVt_PV
3567
3568 Pointer type flag for scalars.  See C<svtype>.
3569
3570 =item SVt_PVAV
3571
3572 Type flag for arrays.  See C<svtype>.
3573
3574 =item SVt_PVCV
3575
3576 Type flag for code refs.  See C<svtype>.
3577
3578 =item SVt_PVHV
3579
3580 Type flag for hashes.  See C<svtype>.
3581
3582 =item SVt_PVMG
3583
3584 Type flag for blessed scalars.  See C<svtype>.
3585
3586 =item SVt_NV
3587
3588 Double type flag for scalars.  See C<svtype>.
3589
3590 =item SvTRUE
3591
3592 Returns a boolean indicating whether Perl would evaluate the SV as true or
3593 false, defined or undefined.  Does not handle 'get' magic.
3594
3595         int     SvTRUE (SV* sv)
3596
3597 =item SvTYPE
3598
3599 Returns the type of the SV.  See C<svtype>.
3600
3601         svtype  SvTYPE (SV* sv)
3602
3603 =item svtype
3604
3605 An enum of flags for Perl types.  These are found in the file B<sv.h> in the
3606 C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3607
3608 =item PL_sv_undef
3609
3610 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
3611
3612 =item sv_unref
3613
3614 Unsets the RV status of the SV, and decrements the reference count of
3615 whatever was being referenced by the RV.  This can almost be thought of
3616 as a reversal of C<newSVrv>.  See C<SvROK_off>.
3617
3618         void    sv_unref (SV* sv)
3619
3620 =item SvUPGRADE
3621
3622 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to perform
3623 the upgrade if necessary.  See C<svtype>.
3624
3625         bool    SvUPGRADE (SV* sv, svtype mt)
3626
3627 =item sv_upgrade
3628
3629 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See C<svtype>.
3630
3631 =item sv_usepvn
3632
3633 Tells an SV to use C<ptr> to find its string value.  Normally the string is
3634 stored inside the SV but sv_usepvn allows the SV to use an outside string.
3635 The C<ptr> should point to memory that was allocated by C<malloc>.  The
3636 string length, C<len>, must be supplied.  This function will realloc the
3637 memory pointed to by C<ptr>, so that pointer should not be freed or used by
3638 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
3639 See C<sv_usepvn_mg>.
3640
3641         void    sv_usepvn (SV* sv, char* ptr, STRLEN len)
3642
3643 =item sv_usepvn_mg
3644
3645 Like C<sv_usepvn>, but also handles 'set' magic.
3646
3647         void    sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
3648
3649 =item sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3650
3651 Processes its arguments like C<vsprintf> and appends the formatted output
3652 to an SV.  Uses an array of SVs if the C style variable argument list is
3653 missing (NULL).  Indicates if locale information has been used for formatting.
3654
3655         void    sv_catpvfn (SV* sv, const char* pat, STRLEN patlen,
3656                             va_list *args, SV **svargs, I32 svmax,
3657                             bool *used_locale);
3658
3659 =item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3660
3661 Works like C<vcatpvfn> but copies the text into the SV instead of
3662 appending it.
3663
3664         void    sv_setpvfn (SV* sv, const char* pat, STRLEN patlen,
3665                             va_list *args, SV **svargs, I32 svmax,
3666                             bool *used_locale);
3667
3668 =item SvUV
3669
3670 Coerces the given SV to an unsigned integer and returns it.
3671
3672         UV      SvUV(SV* sv)
3673
3674 =item SvUVX
3675
3676 Returns the unsigned integer which is stored in the SV, assuming SvIOK is true.
3677
3678         UV      SvUVX(SV* sv)
3679
3680 =item PL_sv_yes
3681
3682 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as C<&PL_sv_yes>.
3683
3684 =item THIS
3685
3686 Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
3687 This is always the proper type for the C++ object.  See C<CLASS> and
3688 L<perlxs/"Using XS With C++">.
3689
3690 =item toLOWER
3691
3692 Converts the specified character to lowercase.
3693
3694         int     toLOWER (char c)
3695
3696 =item toUPPER
3697
3698 Converts the specified character to uppercase.
3699
3700         int     toUPPER (char c)
3701
3702 =item warn
3703
3704 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
3705 function the same way you use the C C<printf> function.  See C<croak()>.
3706
3707 =item XPUSHi
3708
3709 Push an integer onto the stack, extending the stack if necessary.  Handles
3710 'set' magic. See C<PUSHi>.
3711
3712         XPUSHi(int d)
3713
3714 =item XPUSHn
3715
3716 Push a double onto the stack, extending the stack if necessary.  Handles 'set'
3717 magic.  See C<PUSHn>.
3718
3719         XPUSHn(double d)
3720
3721 =item XPUSHp
3722
3723 Push a string onto the stack, extending the stack if necessary.  The C<len>
3724 indicates the length of the string.  Handles 'set' magic.  See C<PUSHp>.
3725
3726         XPUSHp(char *c, int len)
3727
3728 =item XPUSHs
3729
3730 Push an SV onto the stack, extending the stack if necessary.  Does not
3731 handle 'set' magic.  See C<PUSHs>.
3732
3733         XPUSHs(sv)
3734
3735 =item XPUSHu
3736
3737 Push an unsigned integer onto the stack, extending the stack if
3738 necessary.  See C<PUSHu>.
3739
3740 =item XS
3741
3742 Macro to declare an XSUB and its C parameter list.  This is handled by
3743 C<xsubpp>.
3744
3745 =item XSRETURN
3746
3747 Return from XSUB, indicating number of items on the stack.  This is usually
3748 handled by C<xsubpp>.
3749
3750         XSRETURN(int x)
3751
3752 =item XSRETURN_EMPTY
3753
3754 Return an empty list from an XSUB immediately.
3755
3756         XSRETURN_EMPTY;
3757
3758 =item XSRETURN_IV
3759
3760 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3761
3762         XSRETURN_IV(IV v)
3763
3764 =item XSRETURN_NO
3765
3766 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3767
3768         XSRETURN_NO;
3769
3770 =item XSRETURN_NV
3771
3772 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
3773
3774         XSRETURN_NV(NV v)
3775
3776 =item XSRETURN_PV
3777
3778 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3779
3780         XSRETURN_PV(char *v)
3781
3782 =item XSRETURN_UNDEF
3783
3784 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3785
3786         XSRETURN_UNDEF;
3787
3788 =item XSRETURN_YES
3789
3790 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3791
3792         XSRETURN_YES;
3793
3794 =item XST_mIV
3795
3796 Place an integer into the specified position C<i> on the stack.  The value is
3797 stored in a new mortal SV.
3798
3799         XST_mIV( int i, IV v )
3800
3801 =item XST_mNV
3802
3803 Place a double into the specified position C<i> on the stack.  The value is
3804 stored in a new mortal SV.
3805
3806         XST_mNV( int i, NV v )
3807
3808 =item XST_mNO
3809
3810 Place C<&PL_sv_no> into the specified position C<i> on the stack.
3811
3812         XST_mNO( int i )
3813
3814 =item XST_mPV
3815
3816 Place a copy of a string into the specified position C<i> on the stack.  The
3817 value is stored in a new mortal SV.
3818
3819         XST_mPV( int i, char *v )
3820
3821 =item XST_mUNDEF
3822
3823 Place C<&PL_sv_undef> into the specified position C<i> on the stack.
3824
3825         XST_mUNDEF( int i )
3826
3827 =item XST_mYES
3828
3829 Place C<&PL_sv_yes> into the specified position C<i> on the stack.
3830
3831         XST_mYES( int i )
3832
3833 =item XS_VERSION
3834
3835 The version identifier for an XS module.  This is usually handled
3836 automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
3837
3838 =item XS_VERSION_BOOTCHECK
3839
3840 Macro to verify that a PM module's $VERSION variable matches the XS module's
3841 C<XS_VERSION> variable.  This is usually handled automatically by
3842 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
3843
3844 =item Zero
3845
3846 The XSUB-writer's interface to the C C<memzero> function.  The C<d> is the
3847 destination, C<n> is the number of items, and C<t> is the type.
3848
3849         void    Zero( d, n, t )
3850
3851 =back
3852
3853 =head1 AUTHORS
3854
3855 Until May 1997, this document was maintained by Jeff Okamoto
3856 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
3857
3858 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3859 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3860 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3861 Stephen McCamant, and Gurusamy Sarathy.
3862
3863 API Listing originally by Dean Roehrich <roehrich@cray.com>.