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