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 five routines are:
  38
  39     SV*  newSViv(IV);
  40     SV*  newSVnv(double);
  41     SV*  newSVpv(char*, int);
  42     SV*  newSVpvf(const char*, ...);
  43     SV*  newSVsv(SV*);
  44
  45 To change the value of an *already-existing* SV, there are six routines:
  46
  47     void  sv_setiv(SV*, IV);
  48     void  sv_setnv(SV*, double);
  49     void  sv_setpv(SV*, char*);
  50     void  sv_setpvn(SV*, char*, int)
  51     void  sv_setpvf(SV*, const char*, ...);
  52     void  sv_setsv(SV*, SV*);
  53
  54 Notice that you can choose to specify the length of the string to be
  55 assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to
  56 calculate the length by using C<sv_setpv> or by specifying 0 as the second
  57 argument to C<newSVpv>.  Be warned, though, that Perl will determine the
  58 string's length by using C<strlen>, which depends on the string terminating
  59 with a NUL character.  The arguments of C<sv_setpvf> are processed like
  60 C<sprintf>, and the formatted output becomes the value.
  61
  62 All SVs that will contain strings should, but need not, be terminated
  63 with a NUL character.  If it is not NUL-terminated there is a risk of
  64 core dumps and corruptions from code which passes the string to C
  65 functions or system calls which expect a NUL-terminated string.
  66 Perl's own functions typically add a trailing NUL for this reason.
  67 Nevertheless, you should be very careful when you pass a string stored
  68 in an SV to a C function or system call.
  69
  70 To access the actual value that an SV points to, you can use the macros:
  71
  72     SvIV(SV*)
  73     SvNV(SV*)
  74     SvPV(SV*, STRLEN len)
  75
  76 which will automatically coerce the actual scalar type into an IV, double,
  77 or string.
  78
  79 In the C<SvPV> macro, the length of the string returned is placed into the
  80 variable C<len> (this is a macro, so you do I<not> use C<&len>).  If you do not
  81 care what the length of the data is, use the global variable C<na>.  Remember,
  82 however, that Perl allows arbitrary strings of data that may both contain
  83 NULs and might not be terminated by a NUL.
  84
  85 If you want to know if the scalar value is TRUE, you can use:
  86
  87     SvTRUE(SV*)
  88
  89 Although Perl will automatically grow strings for you, if you need to force
  90 Perl to allocate more memory for your SV, you can use the macro
  91
  92     SvGROW(SV*, STRLEN newlen)
  93
  94 which will determine if more memory needs to be allocated.  If so, it will
  95 call the function C<sv_grow>.  Note that C<SvGROW> can only increase, not
  96 decrease, the allocated memory of an SV and that it does not automatically
  97 add a byte for the a trailing NUL (perl's own string functions typically do
  98 C<SvGROW(sv, len + 1)>).
  99
 100 If you have an SV and want to know what kind of data Perl thinks is stored
 101 in it, you can use the following macros to check the type of SV you have.
 102
 103     SvIOK(SV*)
 104     SvNOK(SV*)
 105     SvPOK(SV*)
 106
 107 You can get and set the current length of the string stored in an SV with
 108 the following macros:
 109
 110     SvCUR(SV*)
 111     SvCUR_set(SV*, I32 val)
 112
 113 You can also get a pointer to the end of the string stored in the SV
 114 with the macro:
 115
 116     SvEND(SV*)
 117
 118 But note that these last three macros are valid only if C<SvPOK()> is true.
 119
 120 If you want to append something to the end of string stored in an C<SV*>,
 121 you can use the following functions:
 122
 123     void  sv_catpv(SV*, char*);
 124     void  sv_catpvn(SV*, char*, int);
 125     void  sv_catpvf(SV*, const char*, ...);
 126     void  sv_catsv(SV*, SV*);
 127
 128 The first function calculates the length of the string to be appended by
 129 using C<strlen>.  In the second, you specify the length of the string
 130 yourself.  The third function processes its arguments like C<sprintf> and
 131 appends the formatted output.  The fourth function extends the string
 132 stored in the first SV with the string stored in the second SV.  It also
 133 forces the second SV to be interpreted as a string.
 134
 135 If you know the name of a scalar variable, you can get a pointer to its SV
 136 by using the following:
 137
 138     SV*  perl_get_sv("package::varname", FALSE);
 139
 140 This returns NULL if the variable does not exist.
 141
 142 If you want to know if this variable (or any other SV) is actually C<defined>,
 143 you can call:
 144
 145     SvOK(SV*)
 146
 147 The scalar C<undef> value is stored in an SV instance called C<sv_undef>.  Its
 148 address can be used whenever an C<SV*> is needed.
 149
 150 There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
 151 TRUE and FALSE values, respectively.  Like C<sv_undef>, their addresses can
 152 be used whenever an C<SV*> is needed.
 153
 154 Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
 155 Take this code:
 156
 157     SV* sv = (SV*) 0;
 158     if (I-am-to-return-a-real-value) {
 159             sv = sv_2mortal(newSViv(42));
 160     }
 161     sv_setsv(ST(0), sv);
 162
 163 This code tries to return a new SV (which contains the value 42) if it should
 164 return a real value, or undef otherwise.  Instead it has returned a null
 165 pointer which, somewhere down the line, will cause a segmentation violation,
 166 bus error, or just weird results.  Change the zero to C<&sv_undef> in the first
 167 line and all will be well.
 168
 169 To free an SV that you've created, call C<SvREFCNT_dec(SV*)>.  Normally this
 170 call is not necessary (see L<Reference Counts and Mortality>).
 171
 172 =head2 What's Really Stored in an SV?
 173
 174 Recall that the usual method of determining the type of scalar you have is
 175 to use C<Sv*OK> macros.  Because a scalar can be both a number and a string,
 176 usually these macros will always return TRUE and calling the C<Sv*V>
 177 macros will do the appropriate conversion of string to integer/double or
 178 integer/double to string.
 179
 180 If you I<really> need to know if you have an integer, double, or string
 181 pointer in an SV, you can use the following three macros instead:
 182
 183     SvIOKp(SV*)
 184     SvNOKp(SV*)
 185     SvPOKp(SV*)
 186
 187 These will tell you if you truly have an integer, double, or string pointer
 188 stored in your SV.  The "p" stands for private.
 189
 190 In general, though, it's best to use the C<Sv*V> macros.
 191
 192 =head2 Working with AVs
 193
 194 There are two ways to create and load an AV.  The first method creates an
 195 empty AV:
 196
 197     AV*  newAV();
 198
 199 The second method both creates the AV and initially populates it with SVs:
 200
 201     AV*  av_make(I32 num, SV **ptr);
 202
 203 The second argument points to an array containing C<num> C<SV*>'s.  Once the
 204 AV has been created, the SVs can be destroyed, if so desired.
 205
 206 Once the AV has been created, the following operations are possible on AVs:
 207
 208     void  av_push(AV*, SV*);
 209     SV*   av_pop(AV*);
 210     SV*   av_shift(AV*);
 211     void  av_unshift(AV*, I32 num);
 212
 213 These should be familiar operations, with the exception of C<av_unshift>.
 214 This routine adds C<num> elements at the front of the array with the C<undef>
 215 value.  You must then use C<av_store> (described below) to assign values
 216 to these new elements.
 217
 218 Here are some other functions:
 219
 220     I32   av_len(AV*);
 221     SV**  av_fetch(AV*, I32 key, I32 lval);
 222     SV**  av_store(AV*, I32 key, SV* val);
 223
 224 The C<av_len> function returns the highest index value in array (just
 225 like $#array in Perl).  If the array is empty, -1 is returned.  The
 226 C<av_fetch> function returns the value at index C<key>, but if C<lval>
 227 is non-zero, then C<av_fetch> will store an undef value at that index.
 228 The C<av_store> function stores the value C<val> at index C<key>.
 229 note that C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s
 230 as their return value.
 231
 232     void  av_clear(AV*);
 233     void  av_undef(AV*);
 234     void  av_extend(AV*, I32 key);
 235
 236 The C<av_clear> function deletes all the elements in the AV* array, but
 237 does not actually delete the array itself.  The C<av_undef> function will
 238 delete all the elements in the array plus the array itself.  The
 239 C<av_extend> function extends the array so that it contains C<key>
 240 elements.  If C<key> is less than the current length of the array, then
 241 nothing is done.
 242
 243 If you know the name of an array variable, you can get a pointer to its AV
 244 by using the following:
 245
 246     AV*  perl_get_av("package::varname", FALSE);
 247
 248 This returns NULL if the variable does not exist.
 249
 250 =head2 Working with HVs
 251
 252 To create an HV, you use the following routine:
 253
 254     HV*  newHV();
 255
 256 Once the HV has been created, the following operations are possible on HVs:
 257
 258     SV**  hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
 259     SV**  hv_fetch(HV*, char* key, U32 klen, I32 lval);
 260
 261 The C<klen> parameter is the length of the key being passed in (Note that
 262 you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
 263 length of the key).  The C<val> argument contains the SV pointer to the
 264 scalar being stored, and C<hash> is the precomputed hash value (zero if
 265 you want C<hv_store> to calculate it for you).  The C<lval> parameter
 266 indicates whether this fetch is actually a part of a store operation, in
 267 which case a new undefined value will be added to the HV with the supplied
 268 key and C<hv_fetch> will return as if the value had already existed.
 269
 270 Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
 271 C<SV*>.  To access the scalar value, you must first dereference the return
 272 value.  However, you should check to make sure that the return value is
 273 not NULL before dereferencing it.
 274
 275 These two functions check if a hash table entry exists, and deletes it.
 276
 277     bool  hv_exists(HV*, char* key, U32 klen);
 278     SV*   hv_delete(HV*, char* key, U32 klen, I32 flags);
 279
 280 If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
 281 create and return a mortal copy of the deleted value.
 282
 283 And more miscellaneous functions:
 284
 285     void   hv_clear(HV*);
 286     void   hv_undef(HV*);
 287
 288 Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
 289 table but does not actually delete the hash table.  The C<hv_undef> deletes
 290 both the entries and the hash table itself.
 291
 292 Perl keeps the actual data in linked list of structures with a typedef of HE.
 293 These contain the actual key and value pointers (plus extra administrative
 294 overhead).  The key is a string pointer; the value is an C<SV*>.  However,
 295 once you have an C<HE*>, to get the actual key and value, use the routines
 296 specified below.
 297
 298     I32    hv_iterinit(HV*);
 299             /* Prepares starting point to traverse hash table */
 300     HE*    hv_iternext(HV*);
 301             /* Get the next entry, and return a pointer to a
 302                structure that has both the key and value */
 303     char*  hv_iterkey(HE* entry, I32* retlen);
 304             /* Get the key from an HE structure and also return
 305                the length of the key string */
 306     SV*    hv_iterval(HV*, HE* entry);
 307             /* Return a SV pointer to the value of the HE
 308                structure */
 309     SV*    hv_iternextsv(HV*, char** key, I32* retlen);
 310             /* This convenience routine combines hv_iternext,
 311                hv_iterkey, and hv_iterval.  The key and retlen
 312                arguments are return values for the key and its
 313                length.  The value is returned in the SV* argument */
 314
 315 If you know the name of a hash variable, you can get a pointer to its HV
 316 by using the following:
 317
 318     HV*  perl_get_hv("package::varname", FALSE);
 319
 320 This returns NULL if the variable does not exist.
 321
 322 The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
 323
 324     i = klen;
 325     hash = 0;
 326     s = key;
 327     while (i--)
 328         hash = hash * 33 + *s++;
 329
 330 =head2 Hash API Extensions
 331
 332 Beginning with version 5.004, the following functions are also supported:
 333
 334     HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
 335     HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
 336
 337     bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
 338     SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
 339
 340     SV*     hv_iterkeysv  (HE* entry);
 341
 342 Note that these functions take C<SV*> keys, which simplifies writing
 343 of extension code that deals with hash structures.  These functions
 344 also allow passing of C<SV*> keys to C<tie> functions without forcing
 345 you to stringify the keys (unlike the previous set of functions).
 346
 347 They also return and accept whole hash entries (C<HE*>), making their
 348 use more efficient (since the hash number for a particular string
 349 doesn't have to be recomputed every time).  See L<API LISTING> later in
 350 this document for detailed descriptions.
 351
 352 The following macros must always be used to access the contents of hash
 353 entries.  Note that the arguments to these macros must be simple
 354 variables, since they may get evaluated more than once.  See
 355 L<API LISTING> later in this document for detailed descriptions of these
 356 macros.
 357
 358     HePV(HE* he, STRLEN len)
 359     HeVAL(HE* he)
 360     HeHASH(HE* he)
 361     HeSVKEY(HE* he)
 362     HeSVKEY_force(HE* he)
 363     HeSVKEY_set(HE* he, SV* sv)
 364
 365 These two lower level macros are defined, but must only be used when
 366 dealing with keys that are not C<SV*>s:
 367
 368     HeKEY(HE* he)
 369     HeKLEN(HE* he)
 370
 371
 372 =head2 References
 373
 374 References are a special type of scalar that point to other data types
 375 (including references).
 376
 377 To create a reference, use either of the following functions:
 378
 379     SV* newRV_inc((SV*) thing);
 380     SV* newRV_noinc((SV*) thing);
 381
 382 The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>.  The
 383 functions are identical except that C<newRV_inc> increments the reference
 384 count of the C<thing>, while C<newRV_noinc> does not.  For historical
 385 reasons, C<newRV> is a synonym for C<newRV_inc>.
 386
 387 Once you have a reference, you can use the following macro to dereference
 388 the reference:
 389
 390     SvRV(SV*)
 391
 392 then call the appropriate routines, casting the returned C<SV*> to either an
 393 C<AV*> or C<HV*>, if required.
 394
 395 To determine if an SV is a reference, you can use the following macro:
 396
 397     SvROK(SV*)
 398
 399 To discover what type of value the reference refers to, use the following
 400 macro and then check the return value.
 401
 402     SvTYPE(SvRV(SV*))
 403
 404 The most useful types that will be returned are:
 405
 406     SVt_IV    Scalar
 407     SVt_NV    Scalar
 408     SVt_PV    Scalar
 409     SVt_RV    Scalar
 410     SVt_PVAV  Array
 411     SVt_PVHV  Hash
 412     SVt_PVCV  Code
 413     SVt_PVGV  Glob (possible a file handle)
 414     SVt_PVMG  Blessed or Magical Scalar
 415
 416     See the sv.h header file for more details.
 417
 418 =head2 Blessed References and Class Objects
 419
 420 References are also used to support object-oriented programming.  In the
 421 OO lexicon, an object is simply a reference that has been blessed into a
 422 package (or class).  Once blessed, the programmer may now use the reference
 423 to access the various methods in the class.
 424
 425 A reference can be blessed into a package with the following function:
 426
 427     SV* sv_bless(SV* sv, HV* stash);
 428
 429 The C<sv> argument must be a reference.  The C<stash> argument specifies
 430 which class the reference will belong to.  See
 431 L<Stashes and Globs> for information on converting class names into stashes.
 432
 433 /* Still under construction */
 434
 435 Upgrades rv to reference if not already one.  Creates new SV for rv to
 436 point to.  If C<classname> is non-null, the SV is blessed into the specified
 437 class.  SV is returned.
 438
 439         SV* newSVrv(SV* rv, char* classname);
 440
 441 Copies integer or double into an SV whose reference is C<rv>.  SV is blessed
 442 if C<classname> is non-null.
 443
 444         SV* sv_setref_iv(SV* rv, char* classname, IV iv);
 445         SV* sv_setref_nv(SV* rv, char* classname, NV iv);
 446
 447 Copies the pointer value (I<the address, not the string!>) into an SV whose
 448 reference is rv.  SV is blessed if C<classname> is non-null.
 449
 450         SV* sv_setref_pv(SV* rv, char* classname, PV iv);
 451
 452 Copies string into an SV whose reference is C<rv>.  Set length to 0 to let
 453 Perl calculate the string length.  SV is blessed if C<classname> is non-null.
 454
 455         SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
 456
 457         int sv_isa(SV* sv, char* name);
 458         int sv_isobject(SV* sv);
 459
 460 =head2 Creating New Variables
 461
 462 To create a new Perl variable with an undef value which can be accessed from
 463 your Perl script, use the following routines, depending on the variable type.
 464
 465     SV*  perl_get_sv("package::varname", TRUE);
 466     AV*  perl_get_av("package::varname", TRUE);
 467     HV*  perl_get_hv("package::varname", TRUE);
 468
 469 Notice the use of TRUE as the second parameter.  The new variable can now
 470 be set, using the routines appropriate to the data type.
 471
 472 There are additional macros whose values may be bitwise OR'ed with the
 473 C<TRUE> argument to enable certain extra features.  Those bits are:
 474
 475     GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
 476                 "Name <varname> used only once: possible typo" warning.
 477     GV_ADDWARN  Issues the warning "Had to create <varname> unexpectedly" if
 478                 the variable did not exist before the function was called.
 479
 480 If you do not specify a package name, the variable is created in the current
 481 package.
 482
 483 =head2 Reference Counts and Mortality
 484
 485 Perl uses an reference count-driven garbage collection mechanism. SVs,
 486 AVs, or HVs (xV for short in the following) start their life with a
 487 reference count of 1.  If the reference count of an xV ever drops to 0,
 488 then it will be destroyed and its memory made available for reuse.
 489
 490 This normally doesn't happen at the Perl level unless a variable is
 491 undef'ed or the last variable holding a reference to it is changed or
 492 overwritten.  At the internal level, however, reference counts can be
 493 manipulated with the following macros:
 494
 495     int SvREFCNT(SV* sv);
 496     SV* SvREFCNT_inc(SV* sv);
 497     void SvREFCNT_dec(SV* sv);
 498
 499 However, there is one other function which manipulates the reference
 500 count of its argument.  The C<newRV_inc> function, you will recall,
 501 creates a reference to the specified argument.  As a side effect,
 502 it increments the argument's reference count.  If this is not what
 503 you want, use C<newRV_noinc> instead.
 504
 505 For example, imagine you want to return a reference from an XSUB function.
 506 Inside the XSUB routine, you create an SV which initially has a reference
 507 count of one.  Then you call C<newRV_inc>, passing it the just-created SV.
 508 This returns the reference as a new SV, but the reference count of the
 509 SV you passed to C<newRV_inc> has been incremented to two.  Now you
 510 return the reference from the XSUB routine and forget about the SV.
 511 But Perl hasn't!  Whenever the returned reference is destroyed, the
 512 reference count of the original SV is decreased to one and nothing happens.
 513 The SV will hang around without any way to access it until Perl itself
 514 terminates.  This is a memory leak.
 515
 516 The correct procedure, then, is to use C<newRV_noinc> instead of
 517 C<newRV_inc>.  Then, if and when the last reference is destroyed,
 518 the reference count of the SV will go to zero and it will be destroyed,
 519 stopping any memory leak.
 520
 521 There are some convenience functions available that can help with the
 522 destruction of xVs.  These functions introduce the concept of "mortality".
 523 An xV that is mortal has had its reference count marked to be decremented,
 524 but not actually decremented, until "a short time later".  Generally the
 525 term "short time later" means a single Perl statement, such as a call to
 526 an XSUB function.  The actual determinant for when mortal xVs have their
 527 reference count decremented depends on two macros, SAVETMPS and FREETMPS.
 528 See L<perlcall> and L<perlxs> for more details on these macros.
 529
 530 "Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
 531 However, if you mortalize a variable twice, the reference count will
 532 later be decremented twice.
 533
 534 You should be careful about creating mortal variables.  Strange things
 535 can happen if you make the same value mortal within multiple contexts,
 536 or if you make a variable mortal multiple times.
 537
 538 To create a mortal variable, use the functions:
 539
 540     SV*  sv_newmortal()
 541     SV*  sv_2mortal(SV*)
 542     SV*  sv_mortalcopy(SV*)
 543
 544 The first call creates a mortal SV, the second converts an existing
 545 SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
 546 third creates a mortal copy of an existing SV.
 547
 548 The mortal routines are not just for SVs -- AVs and HVs can be
 549 made mortal by passing their address (type-casted to C<SV*>) to the
 550 C<sv_2mortal> or C<sv_mortalcopy> routines.
 551
 552 =head2 Stashes and Globs
 553
 554 A "stash" is a hash that contains all of the different objects that
 555 are contained within a package.  Each key of the stash is a symbol
 556 name (shared by all the different types of objects that have the same
 557 name), and each value in the hash table is a GV (Glob Value).  This GV
 558 in turn contains references to the various objects of that name,
 559 including (but not limited to) the following:
 560
 561     Scalar Value
 562     Array Value
 563     Hash Value
 564     File Handle
 565     Directory Handle
 566     Format
 567     Subroutine
 568
 569 There is a single stash called "defstash" that holds the items that exist
 570 in the "main" package.  To get at the items in other packages, append the
 571 string "::" to the package name.  The items in the "Foo" package are in
 572 the stash "Foo::" in defstash.  The items in the "Bar::Baz" package are
 573 in the stash "Baz::" in "Bar::"'s stash.
 574
 575 To get the stash pointer for a particular package, use the function:
 576
 577     HV*  gv_stashpv(char* name, I32 create)
 578     HV*  gv_stashsv(SV*, I32 create)
 579
 580 The first function takes a literal string, the second uses the string stored
 581 in the SV.  Remember that a stash is just a hash table, so you get back an
 582 C<HV*>.  The C<create> flag will create a new package if it is set.
 583
 584 The name that C<gv_stash*v> wants is the name of the package whose symbol table
 585 you want.  The default package is called C<main>.  If you have multiply nested
 586 packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
 587 language itself.
 588
 589 Alternately, if you have an SV that is a blessed reference, you can find
 590 out the stash pointer by using:
 591
 592     HV*  SvSTASH(SvRV(SV*));
 593
 594 then use the following to get the package name itself:
 595
 596     char*  HvNAME(HV* stash);
 597
 598 If you need to bless or re-bless an object you can use the following
 599 function:
 600
 601     SV*  sv_bless(SV*, HV* stash)
 602
 603 where the first argument, an C<SV*>, must be a reference, and the second
 604 argument is a stash.  The returned C<SV*> can now be used in the same way
 605 as any other SV.
 606
 607 For more information on references and blessings, consult L<perlref>.
 608
 609 =head2 Double-Typed SVs
 610
 611 Scalar variables normally contain only one type of value, an integer,
 612 double, pointer, or reference.  Perl will automatically convert the
 613 actual scalar data from the stored type into the requested type.
 614
 615 Some scalar variables contain more than one type of scalar data.  For
 616 example, the variable C<$!> contains either the numeric value of C<errno>
 617 or its string equivalent from either C<strerror> or C<sys_errlist[]>.
 618
 619 To force multiple data values into an SV, you must do two things: use the
 620 C<sv_set*v> routines to add the additional scalar type, then set a flag
 621 so that Perl will believe it contains more than one type of data.  The
 622 four macros to set the flags are:
 623
 624         SvIOK_on
 625         SvNOK_on
 626         SvPOK_on
 627         SvROK_on
 628
 629 The particular macro you must use depends on which C<sv_set*v> routine
 630 you called first.  This is because every C<sv_set*v> routine turns on
 631 only the bit for the particular type of data being set, and turns off
 632 all the rest.
 633
 634 For example, to create a new Perl variable called "dberror" that contains
 635 both the numeric and descriptive string error values, you could use the
 636 following code:
 637
 638     extern int  dberror;
 639     extern char *dberror_list;
 640
 641     SV* sv = perl_get_sv("dberror", TRUE);
 642     sv_setiv(sv, (IV) dberror);
 643     sv_setpv(sv, dberror_list[dberror]);
 644     SvIOK_on(sv);
 645
 646 If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
 647 macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
 648
 649 =head2 Magic Variables
 650
 651 [This section still under construction.  Ignore everything here.  Post no
 652 bills.  Everything not permitted is forbidden.]
 653
 654 Any SV may be magical, that is, it has special features that a normal
 655 SV does not have.  These features are stored in the SV structure in a
 656 linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
 657
 658     struct magic {
 659         MAGIC*      mg_moremagic;
 660         MGVTBL*     mg_virtual;
 661         U16         mg_private;
 662         char        mg_type;
 663         U8          mg_flags;
 664         SV*         mg_obj;
 665         char*       mg_ptr;
 666         I32         mg_len;
 667     };
 668
 669 Note this is current as of patchlevel 0, and could change at any time.
 670
 671 =head2 Assigning Magic
 672
 673 Perl adds magic to an SV using the sv_magic function:
 674
 675     void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
 676
 677 The C<sv> argument is a pointer to the SV that is to acquire a new magical
 678 feature.
 679
 680 If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
 681 set the C<SVt_PVMG> flag for the C<sv>.  Perl then continues by adding
 682 it to the beginning of the linked list of magical features.  Any prior
 683 entry of the same type of magic is deleted.  Note that this can be
 684 overridden, and multiple instances of the same type of magic can be
 685 associated with an SV.
 686
 687 The C<name> and C<namlen> arguments are used to associate a string with
 688 the magic, typically the name of a variable. C<namlen> is stored in the
 689 C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
 690 copy of the name is stored in C<mg_ptr> field.
 691
 692 The sv_magic function uses C<how> to determine which, if any, predefined
 693 "Magic Virtual Table" should be assigned to the C<mg_virtual> field.
 694 See the "Magic Virtual Table" section below.  The C<how> argument is also
 695 stored in the C<mg_type> field.
 696
 697 The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
 698 structure.  If it is not the same as the C<sv> argument, the reference
 699 count of the C<obj> object is incremented.  If it is the same, or if
 700 the C<how> argument is "#", or if it is a null pointer, then C<obj> is
 701 merely stored, without the reference count being incremented.
 702
 703 There is also a function to add magic to an C<HV>:
 704
 705     void hv_magic(HV *hv, GV *gv, int how);
 706
 707 This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
 708
 709 To remove the magic from an SV, call the function sv_unmagic:
 710
 711     void sv_unmagic(SV *sv, int type);
 712
 713 The C<type> argument should be equal to the C<how> value when the C<SV>
 714 was initially made magical.
 715
 716 =head2 Magic Virtual Tables
 717
 718 The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
 719 C<MGVTBL>, which is a structure of function pointers and stands for
 720 "Magic Virtual Table" to handle the various operations that might be
 721 applied to that variable.
 722
 723 The C<MGVTBL> has five pointers to the following routine types:
 724
 725     int  (*svt_get)(SV* sv, MAGIC* mg);
 726     int  (*svt_set)(SV* sv, MAGIC* mg);
 727     U32  (*svt_len)(SV* sv, MAGIC* mg);
 728     int  (*svt_clear)(SV* sv, MAGIC* mg);
 729     int  (*svt_free)(SV* sv, MAGIC* mg);
 730
 731 This MGVTBL structure is set at compile-time in C<perl.h> and there are
 732 currently 19 types (or 21 with overloading turned on).  These different
 733 structures contain pointers to various routines that perform additional
 734 actions depending on which function is being called.
 735
 736     Function pointer    Action taken
 737     ----------------    ------------
 738     svt_get             Do something after the value of the SV is retrieved.
 739     svt_set             Do something after the SV is assigned a value.
 740     svt_len             Report on the SV's length.
 741     svt_clear           Clear something the SV represents.
 742     svt_free            Free any extra storage associated with the SV.
 743
 744 For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
 745 to an C<mg_type> of '\0') contains:
 746
 747     { magic_get, magic_set, magic_len, 0, 0 }
 748
 749 Thus, when an SV is determined to be magical and of type '\0', if a get
 750 operation is being performed, the routine C<magic_get> is called.  All
 751 the various routines for the various magical types begin with C<magic_>.
 752
 753 The current kinds of Magic Virtual Tables are:
 754
 755     mg_type  MGVTBL              Type of magical
 756     -------  ------              ----------------------------
 757     \0       vtbl_sv             Regexp???
 758     A        vtbl_amagic         Operator Overloading
 759     a        vtbl_amagicelem     Operator Overloading
 760     c        0                   Used in Operator Overloading
 761     B        vtbl_bm             Boyer-Moore???
 762     E        vtbl_env            %ENV hash
 763     e        vtbl_envelem        %ENV hash element
 764     g        vtbl_mglob          Regexp /g flag???
 765     I        vtbl_isa            @ISA array
 766     i        vtbl_isaelem        @ISA array element
 767     L        0 (but sets RMAGICAL)     Perl Module/Debugger???
 768     l        vtbl_dbline         Debugger?
 769     o        vtbl_collxfrm       Locale transformation
 770     P        vtbl_pack           Tied Array or Hash
 771     p        vtbl_packelem       Tied Array or Hash element
 772     q        vtbl_packelem       Tied Scalar or Handle
 773     S        vtbl_sig            Signal Hash
 774     s        vtbl_sigelem        Signal Hash element
 775     t        vtbl_taint          Taintedness
 776     U        vtbl_uvar           ???
 777     v        vtbl_vec            Vector
 778     x        vtbl_substr         Substring???
 779     y        vtbl_itervar        Shadow "foreach" iterator variable
 780     *        vtbl_glob           GV???
 781     #        vtbl_arylen         Array Length
 782     .        vtbl_pos            $. scalar variable
 783     ~        None                Used by certain extensions
 784
 785 When an uppercase and lowercase letter both exist in the table, then the
 786 uppercase letter is used to represent some kind of composite type (a list
 787 or a hash), and the lowercase letter is used to represent an element of
 788 that composite type.
 789
 790 The '~' magic type is defined specifically for use by extensions and
 791 will not be used by perl itself. Extensions can use ~ magic to 'attach'
 792 private information to variables (typically objects).  This is especially
 793 useful because there is no way for normal perl code to corrupt this
 794 private information (unlike using extra elements of a hash object).
 795
 796 Note that because multiple extensions may be using ~ magic it is
 797 important for extensions to take extra care with it.  Typically only
 798 using it on objects blessed into the same class as the extension
 799 is sufficient.  It may also be appropriate to add an I32 'signature'
 800 at the top of the private data area and check that.
 801
 802 =head2 Finding Magic
 803
 804     MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
 805
 806 This routine returns a pointer to the C<MAGIC> structure stored in the SV.
 807 If the SV does not have that magical feature, C<NULL> is returned.  Also,
 808 if the SV is not of type SVt_PVMG, Perl may core dump.
 809
 810     int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
 811
 812 This routine checks to see what types of magic C<sv> has.  If the mg_type
 813 field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
 814 the mg_type field is changed to be the lowercase letter.
 815
 816 =head1 Subroutines
 817
 818 =head2 XSUBs and the Argument Stack
 819
 820 The XSUB mechanism is a simple way for Perl programs to access C subroutines.
 821 An XSUB routine will have a stack that contains the arguments from the Perl
 822 program, and a way to map from the Perl data structures to a C equivalent.
 823
 824 The stack arguments are accessible through the C<ST(n)> macro, which returns
 825 the C<n>'th stack argument.  Argument 0 is the first argument passed in the
 826 Perl subroutine call.  These arguments are C<SV*>, and can be used anywhere
 827 an C<SV*> is used.
 828
 829 Most of the time, output from the C routine can be handled through use of
 830 the RETVAL and OUTPUT directives.  However, there are some cases where the
 831 argument stack is not already long enough to handle all the return values.
 832 An example is the POSIX tzname() call, which takes no arguments, but returns
 833 two, the local time zone's standard and summer time abbreviations.
 834
 835 To handle this situation, the PPCODE directive is used and the stack is
 836 extended using the macro:
 837
 838     EXTEND(sp, num);
 839
 840 where C<sp> is the stack pointer, and C<num> is the number of elements the
 841 stack should be extended by.
 842
 843 Now that there is room on the stack, values can be pushed on it using the
 844 macros to push IVs, doubles, strings, and SV pointers respectively:
 845
 846     PUSHi(IV)
 847     PUSHn(double)
 848     PUSHp(char*, I32)
 849     PUSHs(SV*)
 850
 851 And now the Perl program calling C<tzname>, the two values will be assigned
 852 as in:
 853
 854     ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
 855
 856 An alternate (and possibly simpler) method to pushing values on the stack is
 857 to use the macros:
 858
 859     XPUSHi(IV)
 860     XPUSHn(double)
 861     XPUSHp(char*, I32)
 862     XPUSHs(SV*)
 863
 864 These macros automatically adjust the stack for you, if needed.  Thus, you
 865 do not need to call C<EXTEND> to extend the stack.
 866
 867 For more information, consult L<perlxs> and L<perlxstut>.
 868
 869 =head2 Calling Perl Routines from within C Programs
 870
 871 There are four routines that can be used to call a Perl subroutine from
 872 within a C program.  These four are:
 873
 874     I32  perl_call_sv(SV*, I32);
 875     I32  perl_call_pv(char*, I32);
 876     I32  perl_call_method(char*, I32);
 877     I32  perl_call_argv(char*, I32, register char**);
 878
 879 The routine most often used is C<perl_call_sv>.  The C<SV*> argument
 880 contains either the name of the Perl subroutine to be called, or a
 881 reference to the subroutine.  The second argument consists of flags
 882 that control the context in which the subroutine is called, whether
 883 or not the subroutine is being passed arguments, how errors should be
 884 trapped, and how to treat return values.
 885
 886 All four routines return the number of arguments that the subroutine returned
 887 on the Perl stack.
 888
 889 When using any of these routines (except C<perl_call_argv>), the programmer
 890 must manipulate the Perl stack.  These include the following macros and
 891 functions:
 892
 893     dSP
 894     PUSHMARK()
 895     PUTBACK
 896     SPAGAIN
 897     ENTER
 898     SAVETMPS
 899     FREETMPS
 900     LEAVE
 901     XPUSH*()
 902     POP*()
 903
 904 For a detailed description of calling conventions from C to Perl,
 905 consult L<perlcall>.
 906
 907 =head2 Memory Allocation
 908
 909 It is suggested that you use the version of malloc that is distributed
 910 with Perl.  It keeps pools of various sizes of unallocated memory in
 911 order to satisfy allocation requests more quickly.  However, on some
 912 platforms, it may cause spurious malloc or free errors.
 913
 914     New(x, pointer, number, type);
 915     Newc(x, pointer, number, type, cast);
 916     Newz(x, pointer, number, type);
 917
 918 These three macros are used to initially allocate memory.
 919
 920 The first argument C<x> was a "magic cookie" that was used to keep track
 921 of who called the macro, to help when debugging memory problems.  However,
 922 the current code makes no use of this feature (most Perl developers now
 923 use run-time memory checkers), so this argument can be any number.
 924
 925 The second argument C<pointer> should be the name of a variable that will
 926 point to the newly allocated memory.
 927
 928 The third and fourth arguments C<number> and C<type> specify how many of
 929 the specified type of data structure should be allocated.  The argument
 930 C<type> is passed to C<sizeof>.  The final argument to C<Newc>, C<cast>,
 931 should be used if the C<pointer> argument is different from the C<type>
 932 argument.
 933
 934 Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
 935 to zero out all the newly allocated memory.
 936
 937     Renew(pointer, number, type);
 938     Renewc(pointer, number, type, cast);
 939     Safefree(pointer)
 940
 941 These three macros are used to change a memory buffer size or to free a
 942 piece of memory no longer needed.  The arguments to C<Renew> and C<Renewc>
 943 match those of C<New> and C<Newc> with the exception of not needing the
 944 "magic cookie" argument.
 945
 946     Move(source, dest, number, type);
 947     Copy(source, dest, number, type);
 948     Zero(dest, number, type);
 949
 950 These three macros are used to move, copy, or zero out previously allocated
 951 memory.  The C<source> and C<dest> arguments point to the source and
 952 destination starting points.  Perl will move, copy, or zero out C<number>
 953 instances of the size of the C<type> data structure (using the C<sizeof>
 954 function).
 955
 956 =head2 PerlIO
 957
 958 The most recent development releases of Perl has been experimenting with
 959 removing Perl's dependency on the "normal" standard I/O suite and allowing
 960 other stdio implementations to be used.  This involves creating a new
 961 abstraction layer that then calls whichever implementation of stdio Perl
 962 was compiled with.  All XSUBs should now use the functions in the PerlIO
 963 abstraction layer and not make any assumptions about what kind of stdio
 964 is being used.
 965
 966 For a complete description of the PerlIO abstraction, consult L<perlapio>.
 967
 968 =head2 Putting a C value on Perl stack
 969
 970 A lot of opcodes (this is an elementary operation in the internal perl
 971 stack machine) put an SV* on the stack. However, as an optimization
 972 the corresponding SV is (usually) not recreated each time. The opcodes
 973 reuse specially assigned SVs (I<target>s) which are (as a corollary)
 974 not constantly freed/created.
 975
 976 Each of the targets is created only once (but see
 977 L<Scratchpads and recursion> below), and when an opcode needs to put
 978 an integer, a double, or a string on stack, it just sets the
 979 corresponding parts of its I<target> and puts the I<target> on stack.
 980
 981 The macro to put this target on stack is C<PUSHTARG>, and it is
 982 directly used in some opcodes, as well as indirectly in zillions of
 983 others, which use it via C<(X)PUSH[pni]>.
 984
 985 =head2 Scratchpads
 986
 987 The question remains on when the SVs which are I<target>s for opcodes
 988 are created. The answer is that they are created when the current unit --
 989 a subroutine or a file (for opcodes for statements outside of
 990 subroutines) -- is compiled. During this time a special anonymous Perl
 991 array is created, which is called a scratchpad for the current
 992 unit.
 993
 994 A scratchpad keeps SVs which are lexicals for the current unit and are
 995 targets for opcodes. One can deduce that an SV lives on a scratchpad
 996 by looking on its flags: lexicals have C<SVs_PADMY> set, and
 997 I<target>s have C<SVs_PADTMP> set.
 998
 999 The correspondence between OPs and I<target>s is not 1-to-1. Different
1000 OPs in the compile tree of the unit can use the same target, if this
1001 would not conflict with the expected life of the temporary.
1002
1003 =head2 Scratchpads and recursion
1004
1005 In fact it is not 100% true that a compiled unit contains a pointer to
1006 the scratchpad AV. In fact it contains a pointer to an AV of
1007 (initially) one element, and this element is the scratchpad AV. Why do
1008 we need an extra level of indirection?
1009
1010 The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1011 these can create several execution pointers going into the same
1012 subroutine. For the subroutine-child not write over the temporaries
1013 for the subroutine-parent (lifespan of which covers the call to the
1014 child), the parent and the child should have different
1015 scratchpads. (I<And> the lexicals should be separate anyway!)
1016
1017 So each subroutine is born with an array of scratchpads (of length 1).
1018 On each entry to the subroutine it is checked that the current
1019 depth of the recursion is not more than the length of this array, and
1020 if it is, new scratchpad is created and pushed into the array.
1021
1022 The I<target>s on this scratchpad are C<undef>s, but they are already
1023 marked with correct flags.
1024
1025 =head1 Compiled code
1026
1027 =head2 Code tree
1028
1029 Here we describe the internal form your code is converted to by
1030 Perl. Start with a simple example:
1031
1032   $a = $b + $c;
1033
1034 This is converted to a tree similar to this one:
1035
1036              assign-to
1037            /           \
1038           +             $a
1039         /   \
1040       $b     $c
1041
1042 (but slightly more complicated).  This tree reflect the way Perl
1043 parsed your code, but has nothing to do with the execution order.
1044 There is an additional "thread" going through the nodes of the tree
1045 which shows the order of execution of the nodes.  In our simplified
1046 example above it looks like:
1047
1048      $b ---> $c ---> + ---> $a ---> assign-to
1049
1050 But with the actual compile tree for C<$a = $b + $c> it is different:
1051 some nodes I<optimized away>.  As a corollary, though the actual tree
1052 contains more nodes than our simplified example, the execution order
1053 is the same as in our example.
1054
1055 =head2 Examining the tree
1056
1057 If you have your perl compiled for debugging (usually done with C<-D
1058 optimize=-g> on C<Configure> command line), you may examine the
1059 compiled tree by specifying C<-Dx> on the Perl command line.  The
1060 output takes several lines per node, and for C<$b+$c> it looks like
1061 this:
1062
1063     5           TYPE = add  ===> 6
1064                 TARG = 1
1065                 FLAGS = (SCALAR,KIDS)
1066                 {
1067                     TYPE = null  ===> (4)
1068                       (was rv2sv)
1069                     FLAGS = (SCALAR,KIDS)
1070                     {
1071     3                   TYPE = gvsv  ===> 4
1072                         FLAGS = (SCALAR)
1073                         GV = main::b
1074                     }
1075                 }
1076                 {
1077                     TYPE = null  ===> (5)
1078                       (was rv2sv)
1079                     FLAGS = (SCALAR,KIDS)
1080                     {
1081     4                   TYPE = gvsv  ===> 5
1082                         FLAGS = (SCALAR)
1083                         GV = main::c
1084                     }
1085                 }
1086
1087 This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1088 not optimized away (one per number in the left column).  The immediate
1089 children of the given node correspond to C<{}> pairs on the same level
1090 of indentation, thus this listing corresponds to the tree:
1091
1092                    add
1093                  /     \
1094                null    null
1095                 |       |
1096                gvsv    gvsv
1097
1098 The execution order is indicated by C<===E<gt>> marks, thus it is C<3
1099 4 5 6> (node C<6> is not included into above listing), i.e.,
1100 C<gvsv gvsv add whatever>.
1101
1102 =head2 Compile pass 1: check routines
1103
1104 The tree is created by the I<pseudo-compiler> while yacc code feeds it
1105 the constructions it recognizes. Since yacc works bottom-up, so does
1106 the first pass of perl compilation.
1107
1108 What makes this pass interesting for perl developers is that some
1109 optimization may be performed on this pass.  This is optimization by
1110 so-called I<check routines>.  The correspondence between node names
1111 and corresponding check routines is described in F<opcode.pl> (do not
1112 forget to run C<make regen_headers> if you modify this file).
1113
1114 A check routine is called when the node is fully constructed except
1115 for the execution-order thread.  Since at this time there is no
1116 back-links to the currently constructed node, one can do most any
1117 operation to the top-level node, including freeing it and/or creating
1118 new nodes above/below it.
1119
1120 The check routine returns the node which should be inserted into the
1121 tree (if the top-level node was not modified, check routine returns
1122 its argument).
1123
1124 By convention, check routines have names C<ck_*>. They are usually
1125 called from C<new*OP> subroutines (or C<convert>) (which in turn are
1126 called from F<perly.y>).
1127
1128 =head2 Compile pass 1a: constant folding
1129
1130 Immediately after the check routine is called the returned node is
1131 checked for being compile-time executable.  If it is (the value is
1132 judged to be constant) it is immediately executed, and a I<constant>
1133 node with the "return value" of the corresponding subtree is
1134 substituted instead.  The subtree is deleted.
1135
1136 If constant folding was not performed, the execution-order thread is
1137 created.
1138
1139 =head2 Compile pass 2: context propagation
1140
1141 When a context for a part of compile tree is known, it is propagated
1142 down through the tree.  Aat this time the context can have 5 values
1143 (instead of 2 for runtime context): void, boolean, scalar, list, and
1144 lvalue.  In contrast with the pass 1 this pass is processed from top
1145 to bottom: a node's context determines the context for its children.
1146
1147 Additional context-dependent optimizations are performed at this time.
1148 Since at this moment the compile tree contains back-references (via
1149 "thread" pointers), nodes cannot be free()d now.  To allow
1150 optimized-away nodes at this stage, such nodes are null()ified instead
1151 of free()ing (i.e. their type is changed to OP_NULL).
1152
1153 =head2 Compile pass 3: peephole optimization
1154
1155 After the compile tree for a subroutine (or for an C<eval> or a file)
1156 is created, an additional pass over the code is performed. This pass
1157 is neither top-down or bottom-up, but in the execution order (with
1158 additional compilications for conditionals).  These optimizations are
1159 done in the subroutine peep().  Optimizations performed at this stage
1160 are subject to the same restrictions as in the pass 2.
1161
1162 =head1 API LISTING
1163
1164 This is a listing of functions, macros, flags, and variables that may be
1165 useful to extension writers or that may be found while reading other
1166 extensions.
1167
1168 =over 8
1169
1170 =item AvFILL
1171
1172 See C<av_len>.
1173
1174 =item av_clear
1175
1176 Clears an array, making it empty.  Does not free the memory used by the
1177 array itself.
1178
1179         void    av_clear _((AV* ar));
1180
1181 =item av_extend
1182
1183 Pre-extend an array.  The C<key> is the index to which the array should be
1184 extended.
1185
1186         void    av_extend _((AV* ar, I32 key));
1187
1188 =item av_fetch
1189
1190 Returns the SV at the specified index in the array.  The C<key> is the
1191 index.  If C<lval> is set then the fetch will be part of a store.  Check
1192 that the return value is non-null before dereferencing it to a C<SV*>.
1193
1194         SV**    av_fetch _((AV* ar, I32 key, I32 lval));
1195
1196 =item av_len
1197
1198 Returns the highest index in the array.  Returns -1 if the array is empty.
1199
1200         I32     av_len _((AV* ar));
1201
1202 =item av_make
1203
1204 Creates a new AV and populates it with a list of SVs.  The SVs are copied
1205 into the array, so they may be freed after the call to av_make.  The new AV
1206 will have a reference count of 1.
1207
1208         AV*     av_make _((I32 size, SV** svp));
1209
1210 =item av_pop
1211
1212 Pops an SV off the end of the array.  Returns C<&sv_undef> if the array is
1213 empty.
1214
1215         SV*     av_pop _((AV* ar));
1216
1217 =item av_push
1218
1219 Pushes an SV onto the end of the array.  The array will grow automatically
1220 to accommodate the addition.
1221
1222         void    av_push _((AV* ar, SV* val));
1223
1224 =item av_shift
1225
1226 Shifts an SV off the beginning of the array.
1227
1228         SV*     av_shift _((AV* ar));
1229
1230 =item av_store
1231
1232 Stores an SV in an array.  The array index is specified as C<key>.  The
1233 return value will be null if the operation failed, otherwise it can be
1234 dereferenced to get the original C<SV*>.
1235
1236         SV**    av_store _((AV* ar, I32 key, SV* val));
1237
1238 =item av_undef
1239
1240 Undefines the array.  Frees the memory used by the array itself.
1241
1242         void    av_undef _((AV* ar));
1243
1244 =item av_unshift
1245
1246 Unshift the given number of C<undef> values onto the beginning of the
1247 array.  The array will grow automatically to accommodate the addition.
1248 You must then use C<av_store> to assign values to these new elements.
1249
1250         void    av_unshift _((AV* ar, I32 num));
1251
1252 =item CLASS
1253
1254 Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
1255 constructor.  This is always a C<char*>.  See C<THIS> and
1256 L<perlxs/"Using XS With C++">.
1257
1258 =item Copy
1259
1260 The XSUB-writer's interface to the C C<memcpy> function.  The C<s> is the
1261 source, C<d> is the destination, C<n> is the number of items, and C<t> is
1262 the type.  May fail on overlapping copies.  See also C<Move>.
1263
1264         (void) Copy( s, d, n, t );
1265
1266 =item croak
1267
1268 This is the XSUB-writer's interface to Perl's C<die> function.  Use this
1269 function the same way you use the C C<printf> function.  See C<warn>.
1270
1271 =item CvSTASH
1272
1273 Returns the stash of the CV.
1274
1275         HV * CvSTASH( SV* sv )
1276
1277 =item DBsingle
1278
1279 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1280 boolean which indicates whether subs are being single-stepped.
1281 Single-stepping is automatically turned on after every step.  This is the C
1282 variable which corresponds to Perl's $DB::single variable.  See C<DBsub>.
1283
1284 =item DBsub
1285
1286 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1287 the SV which holds the name of the sub being debugged.  This is the C
1288 variable which corresponds to Perl's $DB::sub variable.  See C<DBsingle>.
1289 The sub name can be found by
1290
1291         SvPV( GvSV( DBsub ), na )
1292
1293 =item DBtrace
1294
1295 Trace variable used when Perl is run in debugging mode, with the B<-d>
1296 switch.  This is the C variable which corresponds to Perl's $DB::trace
1297 variable.  See C<DBsingle>.
1298
1299 =item dMARK
1300
1301 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
1302 C<dORIGMARK>.
1303
1304 =item dORIGMARK
1305
1306 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
1307
1308 =item dowarn
1309
1310 The C variable which corresponds to Perl's $^W warning variable.
1311
1312 =item dSP
1313
1314 Declares a stack pointer variable, C<sp>, for the XSUB.  See C<SP>.
1315
1316 =item dXSARGS
1317
1318 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This is
1319 usually handled automatically by C<xsubpp>.  Declares the C<items> variable
1320 to indicate the number of items on the stack.
1321
1322 =item dXSI32
1323
1324 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
1325 handled automatically by C<xsubpp>.
1326
1327 =item dXSI32
1328
1329 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
1330 handled automatically by C<xsubpp>.
1331
1332 =item ENTER
1333
1334 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
1335
1336         ENTER;
1337
1338 =item EXTEND
1339
1340 Used to extend the argument stack for an XSUB's return values.
1341
1342         EXTEND( sp, int x );
1343
1344 =item FREETMPS
1345
1346 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
1347 L<perlcall>.
1348
1349         FREETMPS;
1350
1351 =item G_ARRAY
1352
1353 Used to indicate array context.  See C<GIMME_V>, C<GIMME> and L<perlcall>.
1354
1355 =item G_DISCARD
1356
1357 Indicates that arguments returned from a callback should be discarded.  See
1358 L<perlcall>.
1359
1360 =item G_EVAL
1361
1362 Used to force a Perl C<eval> wrapper around a callback.  See L<perlcall>.
1363
1364 =item GIMME
1365
1366 A backward-compatible version of C<GIMME_V> which can only return
1367 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
1368
1369 =item GIMME_V
1370
1371 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns
1372 C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
1373 context, respectively.
1374
1375 =item G_NOARGS
1376
1377 Indicates that no arguments are being sent to a callback.  See L<perlcall>.
1378
1379 =item G_SCALAR
1380
1381 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and L<perlcall>.
1382
1383 =item G_VOID
1384
1385 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
1386
1387 =item gv_fetchmeth
1388
1389 Returns the glob with the given C<name> and a defined subroutine or
1390 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
1391 accessable via @ISA and @<UNIVERSAL>.
1392
1393 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
1394 side-effect creates a glob with the given C<name> in the given
1395 C<stash> which in the case of success contains an alias for the
1396 subroutine, and sets up caching info for this glob.  Similarly for all
1397 the searched stashes.
1398
1399 This function grants C<"SUPER"> token as a postfix of the stash name.
1400
1401 The GV returned from C<gv_fetchmeth> may be a method cache entry,
1402 which is not visible to Perl code.  So when calling C<perl_call_sv>,
1403 you should not use the GV directly; instead, you should use the
1404 method's CV, which can be obtained from the GV with the C<GvCV> macro.
1405
1406         GV*     gv_fetchmeth _((HV* stash, char* name, STRLEN len, I32 level));
1407
1408 =item gv_fetchmethod
1409
1410 =item gv_fetchmethod_autoload
1411
1412 Returns the glob which contains the subroutine to call to invoke the
1413 method on the C<stash>.  In fact in the presense of autoloading this may
1414 be the glob for "AUTOLOAD".  In this case the corresponding variable
1415 $AUTOLOAD is already setup.
1416
1417 The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
1418 lookup is performed if the given method is not present: non-zero means
1419 yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.  Calling
1420 C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
1421 non-zero C<autoload> parameter.
1422
1423 These functions grant C<"SUPER"> token as a prefix of the method name.
1424
1425 Note that if you want to keep the returned glob for a long time, you
1426 need to check for it being "AUTOLOAD", since at the later time the call
1427 may load a different subroutine due to $AUTOLOAD changing its value.
1428 Use the glob created via a side effect to do this.
1429
1430 These functions have the same side-effects and as C<gv_fetchmeth> with
1431 C<level==0>.  C<name> should be writable if contains C<':'> or C<'\''>.
1432 The warning against passing the GV returned by C<gv_fetchmeth> to
1433 C<perl_call_sv> apply equally to these functions.
1434
1435         GV*     gv_fetchmethod _((HV* stash, char* name));
1436         GV*     gv_fetchmethod_autoload _((HV* stash, char* name,
1437                                            I32 autoload));
1438
1439 =item gv_stashpv
1440
1441 Returns a pointer to the stash for a specified package.  If C<create> is set
1442 then the package will be created if it does not already exist.  If C<create>
1443 is not set and the package does not exist then NULL is returned.
1444
1445         HV*     gv_stashpv _((char* name, I32 create));
1446
1447 =item gv_stashsv
1448
1449 Returns a pointer to the stash for a specified package.  See C<gv_stashpv>.
1450
1451         HV*     gv_stashsv _((SV* sv, I32 create));
1452
1453 =item GvSV
1454
1455 Return the SV from the GV.
1456
1457 =item HEf_SVKEY
1458
1459 This flag, used in the length slot of hash entries and magic
1460 structures, specifies the structure contains a C<SV*> pointer where a
1461 C<char*> pointer is to be expected. (For information only--not to be used).
1462
1463 =item HeHASH
1464
1465 Returns the computed hash (type C<U32>) stored in the hash entry.
1466
1467         HeHASH(HE* he)
1468
1469 =item HeKEY
1470
1471 Returns the actual pointer stored in the key slot of the hash entry.
1472 The pointer may be either C<char*> or C<SV*>, depending on the value of
1473 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros
1474 are usually preferable for finding the value of a key.
1475
1476         HeKEY(HE* he)
1477
1478 =item HeKLEN
1479
1480 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1481 holds an C<SV*> key.  Otherwise, holds the actual length of the key.
1482 Can be assigned to. The C<HePV()> macro is usually preferable for finding
1483 key lengths.
1484
1485         HeKLEN(HE* he)
1486
1487 =item HePV
1488
1489 Returns the key slot of the hash entry as a C<char*> value, doing any
1490 necessary dereferencing of possibly C<SV*> keys.  The length of
1491 the string is placed in C<len> (this is a macro, so do I<not> use
1492 C<&len>).  If you do not care about what the length of the key is,
1493 you may use the global variable C<na>.  Remember though, that hash
1494 keys in perl are free to contain embedded nulls, so using C<strlen()>
1495 or similar is not a good way to find the length of hash keys.
1496 This is very similar to the C<SvPV()> macro described elsewhere in
1497 this document.
1498
1499         HePV(HE* he, STRLEN len)
1500
1501 =item HeSVKEY
1502
1503 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
1504 does not contain an C<SV*> key.
1505
1506         HeSVKEY(HE* he)
1507
1508 =item HeSVKEY_force
1509
1510 Returns the key as an C<SV*>.  Will create and return a temporary
1511 mortal C<SV*> if the hash entry contains only a C<char*> key.
1512
1513         HeSVKEY_force(HE* he)
1514
1515 =item HeSVKEY_set
1516
1517 Sets the key to a given C<SV*>, taking care to set the appropriate flags
1518 to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
1519
1520         HeSVKEY_set(HE* he, SV* sv)
1521
1522 =item HeVAL
1523
1524 Returns the value slot (type C<SV*>) stored in the hash entry.
1525
1526         HeVAL(HE* he)
1527
1528 =item hv_clear
1529
1530 Clears a hash, making it empty.
1531
1532         void    hv_clear _((HV* tb));
1533
1534 =item hv_delayfree_ent
1535
1536 Releases a hash entry, such as while iterating though the hash, but
1537 delays actual freeing of key and value until the end of the current
1538 statement (or thereabouts) with C<sv_2mortal>.  See C<hv_iternext>
1539 and C<hv_free_ent>.
1540
1541         void    hv_delayfree_ent _((HV* hv, HE* entry));
1542
1543 =item hv_delete
1544
1545 Deletes a key/value pair in the hash.  The value SV is removed from the hash
1546 and returned to the caller.  The C<klen> is the length of the key.  The
1547 C<flags> value will normally be zero; if set to G_DISCARD then null will be
1548 returned.
1549
1550         SV*     hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
1551
1552 =item hv_delete_ent
1553
1554 Deletes a key/value pair in the hash.  The value SV is removed from the hash
1555 and returned to the caller.  The C<flags> value will normally be zero; if set
1556 to G_DISCARD then null will be returned.  C<hash> can be a valid precomputed
1557 hash value, or 0 to ask for it to be computed.
1558
1559         SV*     hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash));
1560
1561 =item hv_exists
1562
1563 Returns a boolean indicating whether the specified hash key exists.  The
1564 C<klen> is the length of the key.
1565
1566         bool    hv_exists _((HV* tb, char* key, U32 klen));
1567
1568 =item hv_exists_ent
1569
1570 Returns a boolean indicating whether the specified hash key exists. C<hash>
1571 can be a valid precomputed hash value, or 0 to ask for it to be computed.
1572
1573         bool    hv_exists_ent _((HV* tb, SV* key, U32 hash));
1574
1575 =item hv_fetch
1576
1577 Returns the SV which corresponds to the specified key in the hash.  The
1578 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
1579 part of a store.  Check that the return value is non-null before
1580 dereferencing it to a C<SV*>.
1581
1582         SV**    hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
1583
1584 =item hv_fetch_ent
1585
1586 Returns the hash entry which corresponds to the specified key in the hash.
1587 C<hash> must be a valid precomputed hash number for the given C<key>, or
1588 0 if you want the function to compute it.  IF C<lval> is set then the
1589 fetch will be part of a store.  Make sure the return value is non-null
1590 before accessing it.  The return value when C<tb> is a tied hash
1591 is a pointer to a static location, so be sure to make a copy of the
1592 structure if you need to store it somewhere.
1593
1594         HE*     hv_fetch_ent  _((HV* tb, SV* key, I32 lval, U32 hash));
1595
1596 =item hv_free_ent
1597
1598 Releases a hash entry, such as while iterating though the hash.  See
1599 C<hv_iternext> and C<hv_delayfree_ent>.
1600
1601         void    hv_free_ent _((HV* hv, HE* entry));
1602
1603 =item hv_iterinit
1604
1605 Prepares a starting point to traverse a hash table.
1606
1607         I32     hv_iterinit _((HV* tb));
1608
1609 =item hv_iterkey
1610
1611 Returns the key from the current position of the hash iterator.  See
1612 C<hv_iterinit>.
1613
1614         char*   hv_iterkey _((HE* entry, I32* retlen));
1615
1616 =item hv_iterkeysv
1617
1618 Returns the key as an C<SV*> from the current position of the hash
1619 iterator.  The return value will always be a mortal copy of the
1620 key.  Also see C<hv_iterinit>.
1621
1622         SV*     hv_iterkeysv  _((HE* entry));
1623
1624 =item hv_iternext
1625
1626 Returns entries from a hash iterator.  See C<hv_iterinit>.
1627
1628         HE*     hv_iternext _((HV* tb));
1629
1630 =item hv_iternextsv
1631
1632 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1633 operation.
1634
1635         SV *    hv_iternextsv _((HV* hv, char** key, I32* retlen));
1636
1637 =item hv_iterval
1638
1639 Returns the value from the current position of the hash iterator.  See
1640 C<hv_iterkey>.
1641
1642         SV*     hv_iterval _((HV* tb, HE* entry));
1643
1644 =item hv_magic
1645
1646 Adds magic to a hash.  See C<sv_magic>.
1647
1648         void    hv_magic _((HV* hv, GV* gv, int how));
1649
1650 =item HvNAME
1651
1652 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
1653
1654         char *HvNAME (HV* stash)
1655
1656 =item hv_store
1657
1658 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
1659 the length of the key.  The C<hash> parameter is the precomputed hash
1660 value; if it is zero then Perl will compute it.  The return value will be
1661 null if the operation failed, otherwise it can be dereferenced to get the
1662 original C<SV*>.
1663
1664         SV**    hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
1665
1666 =item hv_store_ent
1667
1668 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
1669 parameter is the precomputed hash value; if it is zero then Perl will
1670 compute it.  The return value is the new hash entry so created.  It will be
1671 null if the operation failed or if the entry was stored in a tied hash.
1672 Otherwise the contents of the return value can be accessed using the
1673 C<He???> macros described here.
1674
1675         HE*     hv_store_ent  _((HV* tb, SV* key, SV* val, U32 hash));
1676
1677 =item hv_undef
1678
1679 Undefines the hash.
1680
1681         void    hv_undef _((HV* tb));
1682
1683 =item isALNUM
1684
1685 Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
1686 character or digit.
1687
1688         int isALNUM (char c)
1689
1690 =item isALPHA
1691
1692 Returns a boolean indicating whether the C C<char> is an ascii alphabetic
1693 character.
1694
1695         int isALPHA (char c)
1696
1697 =item isDIGIT
1698
1699 Returns a boolean indicating whether the C C<char> is an ascii digit.
1700
1701         int isDIGIT (char c)
1702
1703 =item isLOWER
1704
1705 Returns a boolean indicating whether the C C<char> is a lowercase character.
1706
1707         int isLOWER (char c)
1708
1709 =item isSPACE
1710
1711 Returns a boolean indicating whether the C C<char> is whitespace.
1712
1713         int isSPACE (char c)
1714
1715 =item isUPPER
1716
1717 Returns a boolean indicating whether the C C<char> is an uppercase character.
1718
1719         int isUPPER (char c)
1720
1721 =item items
1722
1723 Variable which is setup by C<xsubpp> to indicate the number of items on the
1724 stack.  See L<perlxs/"Variable-length Parameter Lists">.
1725
1726 =item ix
1727
1728 Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
1729 was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
1730
1731 =item LEAVE
1732
1733 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
1734
1735         LEAVE;
1736
1737 =item MARK
1738
1739 Stack marker variable for the XSUB.  See C<dMARK>.
1740
1741 =item mg_clear
1742
1743 Clear something magical that the SV represents.  See C<sv_magic>.
1744
1745         int     mg_clear _((SV* sv));
1746
1747 =item mg_copy
1748
1749 Copies the magic from one SV to another.  See C<sv_magic>.
1750
1751         int     mg_copy _((SV *, SV *, char *, STRLEN));
1752
1753 =item mg_find
1754
1755 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
1756
1757         MAGIC*  mg_find _((SV* sv, int type));
1758
1759 =item mg_free
1760
1761 Free any magic storage used by the SV.  See C<sv_magic>.
1762
1763         int     mg_free _((SV* sv));
1764
1765 =item mg_get
1766
1767 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
1768
1769         int     mg_get _((SV* sv));
1770
1771 =item mg_len
1772
1773 Report on the SV's length.  See C<sv_magic>.
1774
1775         U32     mg_len _((SV* sv));
1776
1777 =item mg_magical
1778
1779 Turns on the magical status of an SV.  See C<sv_magic>.
1780
1781         void    mg_magical _((SV* sv));
1782
1783 =item mg_set
1784
1785 Do magic after a value is assigned to the SV.  See C<sv_magic>.
1786
1787         int     mg_set _((SV* sv));
1788
1789 =item Move
1790
1791 The XSUB-writer's interface to the C C<memmove> function.  The C<s> is the
1792 source, C<d> is the destination, C<n> is the number of items, and C<t> is
1793 the type.  Can do overlapping moves.  See also C<Copy>.
1794
1795         (void) Move( s, d, n, t );
1796
1797 =item na
1798
1799 A variable which may be used with C<SvPV> to tell Perl to calculate the
1800 string length.
1801
1802 =item New
1803
1804 The XSUB-writer's interface to the C C<malloc> function.
1805
1806         void * New( x, void *ptr, int size, type )
1807
1808 =item Newc
1809
1810 The XSUB-writer's interface to the C C<malloc> function, with cast.
1811
1812         void * Newc( x, void *ptr, int size, type, cast )
1813
1814 =item Newz
1815
1816 The XSUB-writer's interface to the C C<malloc> function.  The allocated
1817 memory is zeroed with C<memzero>.
1818
1819         void * Newz( x, void *ptr, int size, type )
1820
1821 =item newAV
1822
1823 Creates a new AV.  The reference count is set to 1.
1824
1825         AV*     newAV _((void));
1826
1827 =item newHV
1828
1829 Creates a new HV.  The reference count is set to 1.
1830
1831         HV*     newHV _((void));
1832
1833 =item newRV_inc
1834
1835 Creates an RV wrapper for an SV.  The reference count for the original SV is
1836 incremented.
1837
1838         SV*     newRV_inc _((SV* ref));
1839
1840 For historical reasons, "newRV" is a synonym for "newRV_inc".
1841
1842 =item newRV_noinc
1843
1844 Creates an RV wrapper for an SV.  The reference count for the original
1845 SV is B<not> incremented.
1846
1847         SV*     newRV_noinc _((SV* ref));
1848
1849 =item newSV
1850
1851 Creates a new SV.  The C<len> parameter indicates the number of bytes of
1852 preallocated string space the SV should have.  The reference count for the
1853 new SV is set to 1.
1854
1855         SV*     newSV _((STRLEN len));
1856
1857 =item newSViv
1858
1859 Creates a new SV and copies an integer into it.  The reference count for the
1860 SV is set to 1.
1861
1862         SV*     newSViv _((IV i));
1863
1864 =item newSVnv
1865
1866 Creates a new SV and copies a double into it.  The reference count for the
1867 SV is set to 1.
1868
1869         SV*     newSVnv _((NV i));
1870
1871 =item newSVpv
1872
1873 Creates a new SV and copies a string into it.  The reference count for the
1874 SV is set to 1.  If C<len> is zero then Perl will compute the length.
1875
1876         SV*     newSVpv _((char* s, STRLEN len));
1877
1878 =item newSVrv
1879
1880 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
1881 it will be upgraded to one.  If C<classname> is non-null then the new SV will
1882 be blessed in the specified package.  The new SV is returned and its
1883 reference count is 1.
1884
1885         SV*     newSVrv _((SV* rv, char* classname));
1886
1887 =item newSVsv
1888
1889 Creates a new SV which is an exact duplicate of the original SV.
1890
1891         SV*     newSVsv _((SV* old));
1892
1893 =item newXS
1894
1895 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1896
1897 =item newXSproto
1898
1899 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
1900 the subs.
1901
1902 =item Nullav
1903
1904 Null AV pointer.
1905
1906 =item Nullch
1907
1908 Null character pointer.
1909
1910 =item Nullcv
1911
1912 Null CV pointer.
1913
1914 =item Nullhv
1915
1916 Null HV pointer.
1917
1918 =item Nullsv
1919
1920 Null SV pointer.
1921
1922 =item ORIGMARK
1923
1924 The original stack mark for the XSUB.  See C<dORIGMARK>.
1925
1926 =item perl_alloc
1927
1928 Allocates a new Perl interpreter.  See L<perlembed>.
1929
1930 =item perl_call_argv
1931
1932 Performs a callback to the specified Perl sub.  See L<perlcall>.
1933
1934         I32     perl_call_argv _((char* subname, I32 flags, char** argv));
1935
1936 =item perl_call_method
1937
1938 Performs a callback to the specified Perl method.  The blessed object must
1939 be on the stack.  See L<perlcall>.
1940
1941         I32     perl_call_method _((char* methname, I32 flags));
1942
1943 =item perl_call_pv
1944
1945 Performs a callback to the specified Perl sub.  See L<perlcall>.
1946
1947         I32     perl_call_pv _((char* subname, I32 flags));
1948
1949 =item perl_call_sv
1950
1951 Performs a callback to the Perl sub whose name is in the SV.  See
1952 L<perlcall>.
1953
1954         I32     perl_call_sv _((SV* sv, I32 flags));
1955
1956 =item perl_construct
1957
1958 Initializes a new Perl interpreter.  See L<perlembed>.
1959
1960 =item perl_destruct
1961
1962 Shuts down a Perl interpreter.  See L<perlembed>.
1963
1964 =item perl_eval_sv
1965
1966 Tells Perl to C<eval> the string in the SV.
1967
1968         I32     perl_eval_sv _((SV* sv, I32 flags));
1969
1970 =item perl_eval_pv
1971
1972 Tells Perl to C<eval> the given string and return an SV* result.
1973
1974         SV*     perl_eval_pv _((char* p, I32 croak_on_error));
1975
1976 =item perl_free
1977
1978 Releases a Perl interpreter.  See L<perlembed>.
1979
1980 =item perl_get_av
1981
1982 Returns the AV of the specified Perl array.  If C<create> is set and the
1983 Perl variable does not exist then it will be created.  If C<create> is not
1984 set and the variable does not exist then null is returned.
1985
1986         AV*     perl_get_av _((char* name, I32 create));
1987
1988 =item perl_get_cv
1989
1990 Returns the CV of the specified Perl sub.  If C<create> is set and the Perl
1991 variable does not exist then it will be created.  If C<create> is not
1992 set and the variable does not exist then null is returned.
1993
1994         CV*     perl_get_cv _((char* name, I32 create));
1995
1996 =item perl_get_hv
1997
1998 Returns the HV of the specified Perl hash.  If C<create> is set and the Perl
1999 variable does not exist then it will be created.  If C<create> is not
2000 set and the variable does not exist then null is returned.
2001
2002         HV*     perl_get_hv _((char* name, I32 create));
2003
2004 =item perl_get_sv
2005
2006 Returns the SV of the specified Perl scalar.  If C<create> is set and the
2007 Perl variable does not exist then it will be created.  If C<create> is not
2008 set and the variable does not exist then null is returned.
2009
2010         SV*     perl_get_sv _((char* name, I32 create));
2011
2012 =item perl_parse
2013
2014 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
2015
2016 =item perl_require_pv
2017
2018 Tells Perl to C<require> a module.
2019
2020         void    perl_require_pv _((char* pv));
2021
2022 =item perl_run
2023
2024 Tells a Perl interpreter to run.  See L<perlembed>.
2025
2026 =item POPi
2027
2028 Pops an integer off the stack.
2029
2030         int POPi();
2031
2032 =item POPl
2033
2034 Pops a long off the stack.
2035
2036         long POPl();
2037
2038 =item POPp
2039
2040 Pops a string off the stack.
2041
2042         char * POPp();
2043
2044 =item POPn
2045
2046 Pops a double off the stack.
2047
2048         double POPn();
2049
2050 =item POPs
2051
2052 Pops an SV off the stack.
2053
2054         SV* POPs();
2055
2056 =item PUSHMARK
2057
2058 Opening bracket for arguments on a callback.  See C<PUTBACK> and L<perlcall>.
2059
2060         PUSHMARK(p)
2061
2062 =item PUSHi
2063
2064 Push an integer onto the stack.  The stack must have room for this element.
2065 See C<XPUSHi>.
2066
2067         PUSHi(int d)
2068
2069 =item PUSHn
2070
2071 Push a double onto the stack.  The stack must have room for this element.
2072 See C<XPUSHn>.
2073
2074         PUSHn(double d)
2075
2076 =item PUSHp
2077
2078 Push a string onto the stack.  The stack must have room for this element.
2079 The C<len> indicates the length of the string.  See C<XPUSHp>.
2080
2081         PUSHp(char *c, int len )
2082
2083 =item PUSHs
2084
2085 Push an SV onto the stack.  The stack must have room for this element.  See
2086 C<XPUSHs>.
2087
2088         PUSHs(sv)
2089
2090 =item PUTBACK
2091
2092 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
2093 See C<PUSHMARK> and L<perlcall> for other uses.
2094
2095         PUTBACK;
2096
2097 =item Renew
2098
2099 The XSUB-writer's interface to the C C<realloc> function.
2100
2101         void * Renew( void *ptr, int size, type )
2102
2103 =item Renewc
2104
2105 The XSUB-writer's interface to the C C<realloc> function, with cast.
2106
2107         void * Renewc( void *ptr, int size, type, cast )
2108
2109 =item RETVAL
2110
2111 Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
2112 This is always the proper type for the XSUB.
2113 See L<perlxs/"The RETVAL Variable">.
2114
2115 =item safefree
2116
2117 The XSUB-writer's interface to the C C<free> function.
2118
2119 =item safemalloc
2120
2121 The XSUB-writer's interface to the C C<malloc> function.
2122
2123 =item saferealloc
2124
2125 The XSUB-writer's interface to the C C<realloc> function.
2126
2127 =item savepv
2128
2129 Copy a string to a safe spot.  This does not use an SV.
2130
2131         char*   savepv _((char* sv));
2132
2133 =item savepvn
2134
2135 Copy a string to a safe spot.  The C<len> indicates number of bytes to
2136 copy.  This does not use an SV.
2137
2138         char*   savepvn _((char* sv, I32 len));
2139
2140 =item SAVETMPS
2141
2142 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
2143 L<perlcall>.
2144
2145         SAVETMPS;
2146
2147 =item SP
2148
2149 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
2150 C<SPAGAIN>.
2151
2152 =item SPAGAIN
2153
2154 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
2155
2156         SPAGAIN;
2157
2158 =item ST
2159
2160 Used to access elements on the XSUB's stack.
2161
2162         SV* ST(int x)
2163
2164 =item strEQ
2165
2166 Test two strings to see if they are equal.  Returns true or false.
2167
2168         int strEQ( char *s1, char *s2 )
2169
2170 =item strGE
2171
2172 Test two strings to see if the first, C<s1>, is greater than or equal to the
2173 second, C<s2>.  Returns true or false.
2174
2175         int strGE( char *s1, char *s2 )
2176
2177 =item strGT
2178
2179 Test two strings to see if the first, C<s1>, is greater than the second,
2180 C<s2>.  Returns true or false.
2181
2182         int strGT( char *s1, char *s2 )
2183
2184 =item strLE
2185
2186 Test two strings to see if the first, C<s1>, is less than or equal to the
2187 second, C<s2>.  Returns true or false.
2188
2189         int strLE( char *s1, char *s2 )
2190
2191 =item strLT
2192
2193 Test two strings to see if the first, C<s1>, is less than the second,
2194 C<s2>.  Returns true or false.
2195
2196         int strLT( char *s1, char *s2 )
2197
2198 =item strNE
2199
2200 Test two strings to see if they are different.  Returns true or false.
2201
2202         int strNE( char *s1, char *s2 )
2203
2204 =item strnEQ
2205
2206 Test two strings to see if they are equal.  The C<len> parameter indicates
2207 the number of bytes to compare.  Returns true or false.
2208
2209         int strnEQ( char *s1, char *s2 )
2210
2211 =item strnNE
2212
2213 Test two strings to see if they are different.  The C<len> parameter
2214 indicates the number of bytes to compare.  Returns true or false.
2215
2216         int strnNE( char *s1, char *s2, int len )
2217
2218 =item sv_2mortal
2219
2220 Marks an SV as mortal.  The SV will be destroyed when the current context
2221 ends.
2222
2223         SV*     sv_2mortal _((SV* sv));
2224
2225 =item sv_bless
2226
2227 Blesses an SV into a specified package.  The SV must be an RV.  The package
2228 must be designated by its stash (see C<gv_stashpv()>).  The reference count
2229 of the SV is unaffected.
2230
2231         SV*     sv_bless _((SV* sv, HV* stash));
2232
2233 =item sv_catpv
2234
2235 Concatenates the string onto the end of the string which is in the SV.
2236
2237         void    sv_catpv _((SV* sv, char* ptr));
2238
2239 =item sv_catpvn
2240
2241 Concatenates the string onto the end of the string which is in the SV.  The
2242 C<len> indicates number of bytes to copy.
2243
2244         void    sv_catpvn _((SV* sv, char* ptr, STRLEN len));
2245
2246 =item sv_catpvf
2247
2248 Processes its arguments like C<sprintf> and appends the formatted output
2249 to an SV.
2250
2251         void    sv_catpvf _((SV* sv, const char* pat, ...));
2252
2253 =item sv_catsv
2254
2255 Concatenates the string from SV C<ssv> onto the end of the string in SV
2256 C<dsv>.
2257
2258         void    sv_catsv _((SV* dsv, SV* ssv));
2259
2260 =item sv_cmp
2261
2262 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
2263 string in C<sv1> is less than, equal to, or greater than the string in
2264 C<sv2>.
2265
2266         I32     sv_cmp _((SV* sv1, SV* sv2));
2267
2268 =item sv_cmp
2269
2270 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
2271 string in C<sv1> is less than, equal to, or greater than the string in
2272 C<sv2>.
2273
2274         I32     sv_cmp _((SV* sv1, SV* sv2));
2275
2276 =item SvCUR
2277
2278 Returns the length of the string which is in the SV.  See C<SvLEN>.
2279
2280         int SvCUR (SV* sv)
2281
2282 =item SvCUR_set
2283
2284 Set the length of the string which is in the SV.  See C<SvCUR>.
2285
2286         SvCUR_set (SV* sv, int val )
2287
2288 =item sv_dec
2289
2290 Auto-decrement of the value in the SV.
2291
2292         void    sv_dec _((SV* sv));
2293
2294 =item sv_dec
2295
2296 Auto-decrement of the value in the SV.
2297
2298         void    sv_dec _((SV* sv));
2299
2300 =item SvEND
2301
2302 Returns a pointer to the last character in the string which is in the SV.
2303 See C<SvCUR>.  Access the character as
2304
2305         *SvEND(sv)
2306
2307 =item sv_eq
2308
2309 Returns a boolean indicating whether the strings in the two SVs are
2310 identical.
2311
2312         I32     sv_eq _((SV* sv1, SV* sv2));
2313
2314 =item SvGROW
2315
2316 Expands the character buffer in the SV.  Calls C<sv_grow> to perform the
2317 expansion if necessary.  Returns a pointer to the character buffer.
2318
2319         char * SvGROW( SV* sv, int len )
2320
2321 =item sv_grow
2322
2323 Expands the character buffer in the SV.  This will use C<sv_unref> and will
2324 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
2325 Use C<SvGROW>.
2326
2327 =item sv_inc
2328
2329 Auto-increment of the value in the SV.
2330
2331         void    sv_inc _((SV* sv));
2332
2333 =item SvIOK
2334
2335 Returns a boolean indicating whether the SV contains an integer.
2336
2337         int SvIOK (SV* SV)
2338
2339 =item SvIOK_off
2340
2341 Unsets the IV status of an SV.
2342
2343         SvIOK_off (SV* sv)
2344
2345 =item SvIOK_on
2346
2347 Tells an SV that it is an integer.
2348
2349         SvIOK_on (SV* sv)
2350
2351 =item SvIOK_only
2352
2353 Tells an SV that it is an integer and disables all other OK bits.
2354
2355         SvIOK_on (SV* sv)
2356
2357 =item SvIOK_only
2358
2359 Tells an SV that it is an integer and disables all other OK bits.
2360
2361         SvIOK_on (SV* sv)
2362
2363 =item SvIOKp
2364
2365 Returns a boolean indicating whether the SV contains an integer.  Checks the
2366 B<private> setting.  Use C<SvIOK>.
2367
2368         int SvIOKp (SV* SV)
2369
2370 =item sv_isa
2371
2372 Returns a boolean indicating whether the SV is blessed into the specified
2373 class.  This does not know how to check for subtype, so it doesn't work in
2374 an inheritance relationship.
2375
2376         int     sv_isa _((SV* sv, char* name));
2377
2378 =item SvIV
2379
2380 Returns the integer which is in the SV.
2381
2382         int SvIV (SV* sv)
2383
2384 =item sv_isobject
2385
2386 Returns a boolean indicating whether the SV is an RV pointing to a blessed
2387 object.  If the SV is not an RV, or if the object is not blessed, then this
2388 will return false.
2389
2390         int     sv_isobject _((SV* sv));
2391
2392 =item SvIVX
2393
2394 Returns the integer which is stored in the SV.
2395
2396         int  SvIVX (SV* sv);
2397
2398 =item SvLEN
2399
2400 Returns the size of the string buffer in the SV.  See C<SvCUR>.
2401
2402         int SvLEN (SV* sv)
2403
2404 =item sv_len
2405
2406 Returns the length of the string in the SV.  Use C<SvCUR>.
2407
2408         STRLEN  sv_len _((SV* sv));
2409
2410 =item sv_len
2411
2412 Returns the length of the string in the SV.  Use C<SvCUR>.
2413
2414         STRLEN  sv_len _((SV* sv));
2415
2416 =item sv_magic
2417
2418 Adds magic to an SV.
2419
2420         void    sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
2421
2422 =item sv_mortalcopy
2423
2424 Creates a new SV which is a copy of the original SV.  The new SV is marked
2425 as mortal.
2426
2427         SV*     sv_mortalcopy _((SV* oldsv));
2428
2429 =item SvOK
2430
2431 Returns a boolean indicating whether the value is an SV.
2432
2433         int SvOK (SV* sv)
2434
2435 =item sv_newmortal
2436
2437 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
2438
2439         SV*     sv_newmortal _((void));
2440
2441 =item sv_no
2442
2443 This is the C<false> SV.  See C<sv_yes>.  Always refer to this as C<&sv_no>.
2444
2445 =item SvNIOK
2446
2447 Returns a boolean indicating whether the SV contains a number, integer or
2448 double.
2449
2450         int SvNIOK (SV* SV)
2451
2452 =item SvNIOK_off
2453
2454 Unsets the NV/IV status of an SV.
2455
2456         SvNIOK_off (SV* sv)
2457
2458 =item SvNIOKp
2459
2460 Returns a boolean indicating whether the SV contains a number, integer or
2461 double.  Checks the B<private> setting.  Use C<SvNIOK>.
2462
2463         int SvNIOKp (SV* SV)
2464
2465 =item SvNOK
2466
2467 Returns a boolean indicating whether the SV contains a double.
2468
2469         int SvNOK (SV* SV)
2470
2471 =item SvNOK_off
2472
2473 Unsets the NV status of an SV.
2474
2475         SvNOK_off (SV* sv)
2476
2477 =item SvNOK_on
2478
2479 Tells an SV that it is a double.
2480
2481         SvNOK_on (SV* sv)
2482
2483 =item SvNOK_only
2484
2485 Tells an SV that it is a double and disables all other OK bits.
2486
2487         SvNOK_on (SV* sv)
2488
2489 =item SvNOK_only
2490
2491 Tells an SV that it is a double and disables all other OK bits.
2492
2493         SvNOK_on (SV* sv)
2494
2495 =item SvNOKp
2496
2497 Returns a boolean indicating whether the SV contains a double.  Checks the
2498 B<private> setting.  Use C<SvNOK>.
2499
2500         int SvNOKp (SV* SV)
2501
2502 =item SvNV
2503
2504 Returns the double which is stored in the SV.
2505
2506         double SvNV (SV* sv);
2507
2508 =item SvNVX
2509
2510 Returns the double which is stored in the SV.
2511
2512         double SvNVX (SV* sv);
2513
2514 =item SvPOK
2515
2516 Returns a boolean indicating whether the SV contains a character string.
2517
2518         int SvPOK (SV* SV)
2519
2520 =item SvPOK_off
2521
2522 Unsets the PV status of an SV.
2523
2524         SvPOK_off (SV* sv)
2525
2526 =item SvPOK_on
2527
2528 Tells an SV that it is a string.
2529
2530         SvPOK_on (SV* sv)
2531
2532 =item SvPOK_only
2533
2534 Tells an SV that it is a string and disables all other OK bits.
2535
2536         SvPOK_on (SV* sv)
2537
2538 =item SvPOK_only
2539
2540 Tells an SV that it is a string and disables all other OK bits.
2541
2542         SvPOK_on (SV* sv)
2543
2544 =item SvPOKp
2545
2546 Returns a boolean indicating whether the SV contains a character string.
2547 Checks the B<private> setting.  Use C<SvPOK>.
2548
2549         int SvPOKp (SV* SV)
2550
2551 =item SvPV
2552
2553 Returns a pointer to the string in the SV, or a stringified form of the SV
2554 if the SV does not contain a string.  If C<len> is C<na> then Perl will
2555 handle the length on its own.
2556
2557         char * SvPV (SV* sv, int len )
2558
2559 =item SvPVX
2560
2561 Returns a pointer to the string in the SV.  The SV must contain a string.
2562
2563         char * SvPVX (SV* sv)
2564
2565 =item SvREFCNT
2566
2567 Returns the value of the object's reference count.
2568
2569         int SvREFCNT (SV* sv);
2570
2571 =item SvREFCNT_dec
2572
2573 Decrements the reference count of the given SV.
2574
2575         void SvREFCNT_dec (SV* sv)
2576
2577 =item SvREFCNT_inc
2578
2579 Increments the reference count of the given SV.
2580
2581         void SvREFCNT_inc (SV* sv)
2582
2583 =item SvROK
2584
2585 Tests if the SV is an RV.
2586
2587         int SvROK (SV* sv)
2588
2589 =item SvROK_off
2590
2591 Unsets the RV status of an SV.
2592
2593         SvROK_off (SV* sv)
2594
2595 =item SvROK_on
2596
2597 Tells an SV that it is an RV.
2598
2599         SvROK_on (SV* sv)
2600
2601 =item SvRV
2602
2603 Dereferences an RV to return the SV.
2604
2605         SV*     SvRV (SV* sv);
2606
2607 =item sv_setiv
2608
2609 Copies an integer into the given SV.
2610
2611         void    sv_setiv _((SV* sv, IV num));
2612
2613 =item sv_setnv
2614
2615 Copies a double into the given SV.
2616
2617         void    sv_setnv _((SV* sv, double num));
2618
2619 =item sv_setpv
2620
2621 Copies a string into an SV.  The string must be null-terminated.
2622
2623         void    sv_setpv _((SV* sv, char* ptr));
2624
2625 =item sv_setpvn
2626
2627 Copies a string into an SV.  The C<len> parameter indicates the number of
2628 bytes to be copied.
2629
2630         void    sv_setpvn _((SV* sv, char* ptr, STRLEN len));
2631
2632 =item sv_setpvf
2633
2634 Processes its arguments like C<sprintf> and sets an SV to the formatted
2635 output.
2636
2637         void    sv_setpvf _((SV* sv, const char* pat, ...));
2638
2639 =item sv_setref_iv
2640
2641 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
2642 argument will be upgraded to an RV.  That RV will be modified to point to
2643 the new SV.  The C<classname> argument indicates the package for the
2644 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2645 will be returned and will have a reference count of 1.
2646
2647         SV*     sv_setref_iv _((SV *rv, char *classname, IV iv));
2648
2649 =item sv_setref_nv
2650
2651 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
2652 argument will be upgraded to an RV.  That RV will be modified to point to
2653 the new SV.  The C<classname> argument indicates the package for the
2654 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2655 will be returned and will have a reference count of 1.
2656
2657         SV*     sv_setref_nv _((SV *rv, char *classname, double nv));
2658
2659 =item sv_setref_pv
2660
2661 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
2662 argument will be upgraded to an RV.  That RV will be modified to point to
2663 the new SV.  If the C<pv> argument is NULL then C<sv_undef> will be placed
2664 into the SV.  The C<classname> argument indicates the package for the
2665 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2666 will be returned and will have a reference count of 1.
2667
2668         SV*     sv_setref_pv _((SV *rv, char *classname, void* pv));
2669
2670 Do not use with integral Perl types such as HV, AV, SV, CV, because those
2671 objects will become corrupted by the pointer copy process.
2672
2673 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2674
2675 =item sv_setref_pvn
2676
2677 Copies a string into a new SV, optionally blessing the SV.  The length of the
2678 string must be specified with C<n>.  The C<rv> argument will be upgraded to
2679 an RV.  That RV will be modified to point to the new SV.  The C<classname>
2680 argument indicates the package for the blessing.  Set C<classname> to
2681 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
2682 a reference count of 1.
2683
2684         SV*     sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
2685
2686 Note that C<sv_setref_pv> copies the pointer while this copies the string.
2687
2688 =item sv_setsv
2689
2690 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2691 The source SV may be destroyed if it is mortal.
2692
2693         void    sv_setsv _((SV* dsv, SV* ssv));
2694
2695 =item SvSTASH
2696
2697 Returns the stash of the SV.
2698
2699         HV * SvSTASH (SV* sv)
2700
2701 =item SVt_IV
2702
2703 Integer type flag for scalars.  See C<svtype>.
2704
2705 =item SVt_PV
2706
2707 Pointer type flag for scalars.  See C<svtype>.
2708
2709 =item SVt_PVAV
2710
2711 Type flag for arrays.  See C<svtype>.
2712
2713 =item SVt_PVCV
2714
2715 Type flag for code refs.  See C<svtype>.
2716
2717 =item SVt_PVHV
2718
2719 Type flag for hashes.  See C<svtype>.
2720
2721 =item SVt_PVMG
2722
2723 Type flag for blessed scalars.  See C<svtype>.
2724
2725 =item SVt_NV
2726
2727 Double type flag for scalars.  See C<svtype>.
2728
2729 =item SvTRUE
2730
2731 Returns a boolean indicating whether Perl would evaluate the SV as true or
2732 false, defined or undefined.
2733
2734         int SvTRUE (SV* sv)
2735
2736 =item SvTYPE
2737
2738 Returns the type of the SV.  See C<svtype>.
2739
2740         svtype  SvTYPE (SV* sv)
2741
2742 =item svtype
2743
2744 An enum of flags for Perl types.  These are found in the file B<sv.h> in the
2745 C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
2746
2747 =item SvUPGRADE
2748
2749 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to perform
2750 the upgrade if necessary.  See C<svtype>.
2751
2752         bool    SvUPGRADE _((SV* sv, svtype mt));
2753
2754 =item sv_upgrade
2755
2756 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See C<svtype>.
2757
2758 =item sv_undef
2759
2760 This is the C<undef> SV.  Always refer to this as C<&sv_undef>.
2761
2762 =item sv_unref
2763
2764 Unsets the RV status of the SV, and decrements the reference count of
2765 whatever was being referenced by the RV.  This can almost be thought of
2766 as a reversal of C<newSVrv>.  See C<SvROK_off>.
2767
2768         void    sv_unref _((SV* sv));
2769
2770 =item sv_usepvn
2771
2772 Tells an SV to use C<ptr> to find its string value.  Normally the string is
2773 stored inside the SV but sv_usepvn allows the SV to use an outside string.
2774 The C<ptr> should point to memory that was allocated by C<malloc>.  The
2775 string length, C<len>, must be supplied.  This function will realloc the
2776 memory pointed to by C<ptr>, so that pointer should not be freed or used by
2777 the programmer after giving it to sv_usepvn.
2778
2779         void    sv_usepvn _((SV* sv, char* ptr, STRLEN len));
2780
2781 =item sv_yes
2782
2783 This is the C<true> SV.  See C<sv_no>.  Always refer to this as C<&sv_yes>.
2784
2785 =item THIS
2786
2787 Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
2788 This is always the proper type for the C++ object.  See C<CLASS> and
2789 L<perlxs/"Using XS With C++">.
2790
2791 =item toLOWER
2792
2793 Converts the specified character to lowercase.
2794
2795         int toLOWER (char c)
2796
2797 =item toUPPER
2798
2799 Converts the specified character to uppercase.
2800
2801         int toUPPER (char c)
2802
2803 =item warn
2804
2805 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
2806 function the same way you use the C C<printf> function.  See C<croak()>.
2807
2808 =item XPUSHi
2809
2810 Push an integer onto the stack, extending the stack if necessary.  See
2811 C<PUSHi>.
2812
2813         XPUSHi(int d)
2814
2815 =item XPUSHn
2816
2817 Push a double onto the stack, extending the stack if necessary.  See
2818 C<PUSHn>.
2819
2820         XPUSHn(double d)
2821
2822 =item XPUSHp
2823
2824 Push a string onto the stack, extending the stack if necessary.  The C<len>
2825 indicates the length of the string.  See C<PUSHp>.
2826
2827         XPUSHp(char *c, int len)
2828
2829 =item XPUSHs
2830
2831 Push an SV onto the stack, extending the stack if necessary.  See C<PUSHs>.
2832
2833         XPUSHs(sv)
2834
2835 =item XS
2836
2837 Macro to declare an XSUB and its C parameter list.  This is handled by
2838 C<xsubpp>.
2839
2840 =item XSRETURN
2841
2842 Return from XSUB, indicating number of items on the stack.  This is usually
2843 handled by C<xsubpp>.
2844
2845         XSRETURN(int x);
2846
2847 =item XSRETURN_EMPTY
2848
2849 Return an empty list from an XSUB immediately.
2850
2851         XSRETURN_EMPTY;
2852
2853 =item XSRETURN_IV
2854
2855 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
2856
2857         XSRETURN_IV(IV v);
2858
2859 =item XSRETURN_NO
2860
2861 Return C<&sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
2862
2863         XSRETURN_NO;
2864
2865 =item XSRETURN_NV
2866
2867 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
2868
2869         XSRETURN_NV(NV v);
2870
2871 =item XSRETURN_PV
2872
2873 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
2874
2875         XSRETURN_PV(char *v);
2876
2877 =item XSRETURN_UNDEF
2878
2879 Return C<&sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
2880
2881         XSRETURN_UNDEF;
2882
2883 =item XSRETURN_YES
2884
2885 Return C<&sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
2886
2887         XSRETURN_YES;
2888
2889 =item XST_mIV
2890
2891 Place an integer into the specified position C<i> on the stack.  The value is
2892 stored in a new mortal SV.
2893
2894         XST_mIV( int i, IV v );
2895
2896 =item XST_mNV
2897
2898 Place a double into the specified position C<i> on the stack.  The value is
2899 stored in a new mortal SV.
2900
2901         XST_mNV( int i, NV v );
2902
2903 =item XST_mNO
2904
2905 Place C<&sv_no> into the specified position C<i> on the stack.
2906
2907         XST_mNO( int i );
2908
2909 =item XST_mPV
2910
2911 Place a copy of a string into the specified position C<i> on the stack.  The
2912 value is stored in a new mortal SV.
2913
2914         XST_mPV( int i, char *v );
2915
2916 =item XST_mUNDEF
2917
2918 Place C<&sv_undef> into the specified position C<i> on the stack.
2919
2920         XST_mUNDEF( int i );
2921
2922 =item XST_mYES
2923
2924 Place C<&sv_yes> into the specified position C<i> on the stack.
2925
2926         XST_mYES( int i );
2927
2928 =item XS_VERSION
2929
2930 The version identifier for an XS module.  This is usually handled
2931 automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
2932
2933 =item XS_VERSION_BOOTCHECK
2934
2935 Macro to verify that a PM module's $VERSION variable matches the XS module's
2936 C<XS_VERSION> variable.  This is usually handled automatically by
2937 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
2938
2939 =item Zero
2940
2941 The XSUB-writer's interface to the C C<memzero> function.  The C<d> is the
2942 destination, C<n> is the number of items, and C<t> is the type.
2943
2944         (void) Zero( d, n, t );
2945
2946 =back
2947
2948 =head1 EDITOR
2949
2950 Jeff Okamoto <F<okamoto@corp.hp.com>>
2951
2952 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2953 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2954 Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer.
2955
2956 API Listing by Dean Roehrich <F<roehrich@cray.com>>.
2957
2958 =head1 DATE
2959
2960 Version 31.7: 1997/5/1