pod/perlapi.pod

   1 =head1 NAME
   2
   3 perlapi - autogenerated documentation for the perl public API
   4
   5 =head1 DESCRIPTION
   6
   7 This file contains the documentation of the perl public API generated by
   8 embed.pl, specifically a listing of functions, macros, flags, and variables
   9 that may be used by extension writers.  The interfaces of any functions that
  10 are not listed here are subject to change without notice.  For this reason,
  11 blindly using functions listed in proto.h is to be avoided when writing
  12 extensions.
  13
  14 Note that all Perl API global variables must be referenced with the C<PL_>
  15 prefix.  Some macros are provided for compatibility with the older,
  16 unadorned names, but this support may be disabled in a future release.
  17
  18 The listing is alphabetical, case insensitive.
  19
  20 =over 8
  21
  22 =item AvFILL
  23
  24 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
  25
  26         int     AvFILL(AV* av)
  27
  28 =item av_clear
  29
  30 Clears an array, making it empty.  Does not free the memory used by the
  31 array itself.
  32
  33         void    av_clear(AV* ar)
  34
  35 =item av_extend
  36
  37 Pre-extend an array.  The C<key> is the index to which the array should be
  38 extended.
  39
  40         void    av_extend(AV* ar, I32 key)
  41
  42 =item av_fetch
  43
  44 Returns the SV at the specified index in the array.  The C<key> is the
  45 index.  If C<lval> is set then the fetch will be part of a store.  Check
  46 that the return value is non-null before dereferencing it to a C<SV*>.
  47
  48 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
  49 more information on how to use this function on tied arrays.
  50
  51         SV**    av_fetch(AV* ar, I32 key, I32 lval)
  52
  53 =item av_len
  54
  55 Returns the highest index in the array.  Returns -1 if the array is
  56 empty.
  57
  58         I32     av_len(AV* ar)
  59
  60 =item av_make
  61
  62 Creates a new AV and populates it with a list of SVs.  The SVs are copied
  63 into the array, so they may be freed after the call to av_make.  The new AV
  64 will have a reference count of 1.
  65
  66         AV*     av_make(I32 size, SV** svp)
  67
  68 =item av_pop
  69
  70 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
  71 is empty.
  72
  73         SV*     av_pop(AV* ar)
  74
  75 =item av_push
  76
  77 Pushes an SV onto the end of the array.  The array will grow automatically
  78 to accommodate the addition.
  79
  80         void    av_push(AV* ar, SV* val)
  81
  82 =item av_shift
  83
  84 Shifts an SV off the beginning of the array.
  85
  86         SV*     av_shift(AV* ar)
  87
  88 =item av_store
  89
  90 Stores an SV in an array.  The array index is specified as C<key>.  The
  91 return value will be NULL if the operation failed or if the value did not
  92 need to be actually stored within the array (as in the case of tied
  93 arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
  94 that the caller is responsible for suitably incrementing the reference
  95 count of C<val> before the call, and decrementing it if the function
  96 returned NULL.
  97
  98 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
  99 more information on how to use this function on tied arrays.
 100
 101         SV**    av_store(AV* ar, I32 key, SV* val)
 102
 103 =item av_undef
 104
 105 Undefines the array.  Frees the memory used by the array itself.
 106
 107         void    av_undef(AV* ar)
 108
 109 =item av_unshift
 110
 111 Unshift the given number of C<undef> values onto the beginning of the
 112 array.  The array will grow automatically to accommodate the addition.  You
 113 must then use C<av_store> to assign values to these new elements.
 114
 115         void    av_unshift(AV* ar, I32 num)
 116
 117 =item call_argv
 118
 119 Performs a callback to the specified Perl sub.  See L<perlcall>.
 120
 121 NOTE: the perl_ form of this function is deprecated.
 122
 123         I32     call_argv(const char* sub_name, I32 flags, char** argv)
 124
 125 =item call_method
 126
 127 Performs a callback to the specified Perl method.  The blessed object must
 128 be on the stack.  See L<perlcall>.
 129
 130 NOTE: the perl_ form of this function is deprecated.
 131
 132         I32     call_method(const char* methname, I32 flags)
 133
 134 =item call_pv
 135
 136 Performs a callback to the specified Perl sub.  See L<perlcall>.
 137
 138 NOTE: the perl_ form of this function is deprecated.
 139
 140         I32     call_pv(const char* sub_name, I32 flags)
 141
 142 =item call_sv
 143
 144 Performs a callback to the Perl sub whose name is in the SV.  See
 145 L<perlcall>.
 146
 147 NOTE: the perl_ form of this function is deprecated.
 148
 149         I32     call_sv(SV* sv, I32 flags)
 150
 151 =item CLASS
 152
 153 Variable which is setup by C<xsubpp> to indicate the
 154 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
 155
 156         char*   CLASS
 157
 158 =item Copy
 159
 160 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
 161 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
 162 the type.  May fail on overlapping copies.  See also C<Move>.
 163
 164         void    Copy(void* src, void* dest, int nitems, type)
 165
 166 =item croak
 167
 168 This is the XSUB-writer's interface to Perl's C<die> function.
 169 Normally use this function the same way you use the C C<printf>
 170 function.  See C<warn>.
 171
 172 If you want to throw an exception object, assign the object to
 173 C<$@> and then pass C<Nullch> to croak():
 174
 175    errsv = get_sv("@", TRUE);
 176    sv_setsv(errsv, exception_object);
 177    croak(Nullch);
 178
 179         void    croak(const char* pat, ...)
 180
 181 =item CvSTASH
 182
 183 Returns the stash of the CV.
 184
 185         HV*     CvSTASH(CV* cv)
 186
 187 =item dMARK
 188
 189 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
 190 C<dORIGMARK>.
 191
 192                 dMARK;
 193
 194 =item dORIGMARK
 195
 196 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
 197
 198                 dORIGMARK;
 199
 200 =item dSP
 201
 202 Declares a local copy of perl's stack pointer for the XSUB, available via
 203 the C<SP> macro.  See C<SP>.
 204
 205                 dSP;
 206
 207 =item dXSARGS
 208
 209 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
 210 is usually handled automatically by C<xsubpp>.  Declares the C<items>
 211 variable to indicate the number of items on the stack.
 212
 213                 dXSARGS;
 214
 215 =item dXSI32
 216
 217 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
 218 handled automatically by C<xsubpp>.
 219
 220                 dXSI32;
 221
 222 =item ENTER
 223
 224 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
 225
 226                 ENTER;
 227
 228 =item eval_pv
 229
 230 Tells Perl to C<eval> the given string and return an SV* result.
 231
 232 NOTE: the perl_ form of this function is deprecated.
 233
 234         SV*     eval_pv(const char* p, I32 croak_on_error)
 235
 236 =item eval_sv
 237
 238 Tells Perl to C<eval> the string in the SV.
 239
 240 NOTE: the perl_ form of this function is deprecated.
 241
 242         I32     eval_sv(SV* sv, I32 flags)
 243
 244 =item EXTEND
 245
 246 Used to extend the argument stack for an XSUB's return values. Once
 247 used, guarantees that there is room for at least C<nitems> to be pushed
 248 onto the stack.
 249
 250         void    EXTEND(SP, int nitems)
 251
 252 =item fbm_compile
 253
 254 Analyses the string in order to make fast searches on it using fbm_instr()
 255 -- the Boyer-Moore algorithm.
 256
 257         void    fbm_compile(SV* sv, U32 flags)
 258
 259 =item fbm_instr
 260
 261 Returns the location of the SV in the string delimited by C<str> and
 262 C<strend>.  It returns C<Nullch> if the string can't be found.  The C<sv>
 263 does not have to be fbm_compiled, but the search will not be as fast
 264 then.
 265
 266         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
 267
 268 =item FREETMPS
 269
 270 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
 271 L<perlcall>.
 272
 273                 FREETMPS;
 274
 275 =item get_av
 276
 277 Returns the AV of the specified Perl array.  If C<create> is set and the
 278 Perl variable does not exist then it will be created.  If C<create> is not
 279 set and the variable does not exist then NULL is returned.
 280
 281 NOTE: the perl_ form of this function is deprecated.
 282
 283         AV*     get_av(const char* name, I32 create)
 284
 285 =item get_cv
 286
 287 Returns the CV of the specified Perl subroutine.  If C<create> is set and
 288 the Perl subroutine does not exist then it will be declared (which has the
 289 same effect as saying C<sub name;>).  If C<create> is not set and the
 290 subroutine does not exist then NULL is returned.
 291
 292 NOTE: the perl_ form of this function is deprecated.
 293
 294         CV*     get_cv(const char* name, I32 create)
 295
 296 =item get_hv
 297
 298 Returns the HV of the specified Perl hash.  If C<create> is set and the
 299 Perl variable does not exist then it will be created.  If C<create> is not
 300 set and the variable does not exist then NULL is returned.
 301
 302 NOTE: the perl_ form of this function is deprecated.
 303
 304         HV*     get_hv(const char* name, I32 create)
 305
 306 =item get_sv
 307
 308 Returns the SV of the specified Perl scalar.  If C<create> is set and the
 309 Perl variable does not exist then it will be created.  If C<create> is not
 310 set and the variable does not exist then NULL is returned.
 311
 312 NOTE: the perl_ form of this function is deprecated.
 313
 314         SV*     get_sv(const char* name, I32 create)
 315
 316 =item GIMME
 317
 318 A backward-compatible version of C<GIMME_V> which can only return
 319 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
 320 Deprecated.  Use C<GIMME_V> instead.
 321
 322         U32     GIMME
 323
 324 =item GIMME_V
 325
 326 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
 327 C<G_SCALAR> or C<G_ARRAY> for void, scalar or array context,
 328 respectively.
 329
 330         U32     GIMME_V
 331
 332 =item GvSV
 333
 334 Return the SV from the GV.
 335
 336         SV*     GvSV(GV* gv)
 337
 338 =item gv_fetchmeth
 339
 340 Returns the glob with the given C<name> and a defined subroutine or
 341 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
 342 accessible via @ISA and @UNIVERSAL.
 343
 344 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
 345 side-effect creates a glob with the given C<name> in the given C<stash>
 346 which in the case of success contains an alias for the subroutine, and sets
 347 up caching info for this glob.  Similarly for all the searched stashes.
 348
 349 This function grants C<"SUPER"> token as a postfix of the stash name. The
 350 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
 351 visible to Perl code.  So when calling C<call_sv>, you should not use
 352 the GV directly; instead, you should use the method's CV, which can be
 353 obtained from the GV with the C<GvCV> macro.
 354
 355         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
 356
 357 =item gv_fetchmethod
 358
 359 See L<gv_fetchmethod_autoload>.
 360
 361         GV*     gv_fetchmethod(HV* stash, const char* name)
 362
 363 =item gv_fetchmethod_autoload
 364
 365 Returns the glob which contains the subroutine to call to invoke the method
 366 on the C<stash>.  In fact in the presence of autoloading this may be the
 367 glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
 368 already setup.
 369
 370 The third parameter of C<gv_fetchmethod_autoload> determines whether
 371 AUTOLOAD lookup is performed if the given method is not present: non-zero
 372 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
 373 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
 374 with a non-zero C<autoload> parameter.
 375
 376 These functions grant C<"SUPER"> token as a prefix of the method name. Note
 377 that if you want to keep the returned glob for a long time, you need to
 378 check for it being "AUTOLOAD", since at the later time the call may load a
 379 different subroutine due to $AUTOLOAD changing its value. Use the glob
 380 created via a side effect to do this.
 381
 382 These functions have the same side-effects and as C<gv_fetchmeth> with
 383 C<level==0>.  C<name> should be writable if contains C<':'> or C<'
 384 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
 385 C<call_sv> apply equally to these functions.
 386
 387         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
 388
 389 =item gv_stashpv
 390
 391 Returns a pointer to the stash for a specified package.  C<name> should
 392 be a valid UTF-8 string.  If C<create> is set then the package will be
 393 created if it does not already exist.  If C<create> is not set and the
 394 package does not exist then NULL is returned.
 395
 396         HV*     gv_stashpv(const char* name, I32 create)
 397
 398 =item gv_stashsv
 399
 400 Returns a pointer to the stash for a specified package, which must be a
 401 valid UTF-8 string.  See C<gv_stashpv>.
 402
 403         HV*     gv_stashsv(SV* sv, I32 create)
 404
 405 =item G_ARRAY
 406
 407 Used to indicate array context.  See C<GIMME_V>, C<GIMME> and
 408 L<perlcall>.
 409
 410 =item G_DISCARD
 411
 412 Indicates that arguments returned from a callback should be discarded.  See
 413 L<perlcall>.
 414
 415 =item G_EVAL
 416
 417 Used to force a Perl C<eval> wrapper around a callback.  See
 418 L<perlcall>.
 419
 420 =item G_NOARGS
 421
 422 Indicates that no arguments are being sent to a callback.  See
 423 L<perlcall>.
 424
 425 =item G_SCALAR
 426
 427 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
 428 L<perlcall>.
 429
 430 =item G_VOID
 431
 432 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
 433
 434 =item HEf_SVKEY
 435
 436 This flag, used in the length slot of hash entries and magic structures,
 437 specifies the structure contains a C<SV*> pointer where a C<char*> pointer
 438 is to be expected. (For information only--not to be used).
 439
 440 =item HeHASH
 441
 442 Returns the computed hash stored in the hash entry.
 443
 444         U32     HeHASH(HE* he)
 445
 446 =item HeKEY
 447
 448 Returns the actual pointer stored in the key slot of the hash entry. The
 449 pointer may be either C<char*> or C<SV*>, depending on the value of
 450 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
 451 usually preferable for finding the value of a key.
 452
 453         void*   HeKEY(HE* he)
 454
 455 =item HeKLEN
 456
 457 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
 458 holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
 459 be assigned to. The C<HePV()> macro is usually preferable for finding key
 460 lengths.
 461
 462         STRLEN  HeKLEN(HE* he)
 463
 464 =item HePV
 465
 466 Returns the key slot of the hash entry as a C<char*> value, doing any
 467 necessary dereferencing of possibly C<SV*> keys.  The length of the string
 468 is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
 469 not care about what the length of the key is, you may use the global
 470 variable C<PL_na>, though this is rather less efficient than using a local
 471 variable.  Remember though, that hash keys in perl are free to contain
 472 embedded nulls, so using C<strlen()> or similar is not a good way to find
 473 the length of hash keys. This is very similar to the C<SvPV()> macro
 474 described elsewhere in this document.
 475
 476         char*   HePV(HE* he, STRLEN len)
 477
 478 =item HeSVKEY
 479
 480 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
 481 contain an C<SV*> key.
 482
 483         SV*     HeSVKEY(HE* he)
 484
 485 =item HeSVKEY_force
 486
 487 Returns the key as an C<SV*>.  Will create and return a temporary mortal
 488 C<SV*> if the hash entry contains only a C<char*> key.
 489
 490         SV*     HeSVKEY_force(HE* he)
 491
 492 =item HeSVKEY_set
 493
 494 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
 495 indicate the presence of an C<SV*> key, and returns the same
 496 C<SV*>.
 497
 498         SV*     HeSVKEY_set(HE* he, SV* sv)
 499
 500 =item HeVAL
 501
 502 Returns the value slot (type C<SV*>) stored in the hash entry.
 503
 504         SV*     HeVAL(HE* he)
 505
 506 =item HvNAME
 507
 508 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
 509
 510         char*   HvNAME(HV* stash)
 511
 512 =item hv_clear
 513
 514 Clears a hash, making it empty.
 515
 516         void    hv_clear(HV* tb)
 517
 518 =item hv_delete
 519
 520 Deletes a key/value pair in the hash.  The value SV is removed from the
 521 hash and returned to the caller.  The C<klen> is the length of the key.
 522 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
 523 will be returned.
 524
 525         SV*     hv_delete(HV* tb, const char* key, U32 klen, I32 flags)
 526
 527 =item hv_delete_ent
 528
 529 Deletes a key/value pair in the hash.  The value SV is removed from the
 530 hash and returned to the caller.  The C<flags> value will normally be zero;
 531 if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
 532 precomputed hash value, or 0 to ask for it to be computed.
 533
 534         SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
 535
 536 =item hv_exists
 537
 538 Returns a boolean indicating whether the specified hash key exists.  The
 539 C<klen> is the length of the key.
 540
 541         bool    hv_exists(HV* tb, const char* key, U32 klen)
 542
 543 =item hv_exists_ent
 544
 545 Returns a boolean indicating whether the specified hash key exists. C<hash>
 546 can be a valid precomputed hash value, or 0 to ask for it to be
 547 computed.
 548
 549         bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
 550
 551 =item hv_fetch
 552
 553 Returns the SV which corresponds to the specified key in the hash.  The
 554 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
 555 part of a store.  Check that the return value is non-null before
 556 dereferencing it to a C<SV*>.
 557
 558 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
 559 information on how to use this function on tied hashes.
 560
 561         SV**    hv_fetch(HV* tb, const char* key, U32 klen, I32 lval)
 562
 563 =item hv_fetch_ent
 564
 565 Returns the hash entry which corresponds to the specified key in the hash.
 566 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
 567 if you want the function to compute it.  IF C<lval> is set then the fetch
 568 will be part of a store.  Make sure the return value is non-null before
 569 accessing it.  The return value when C<tb> is a tied hash is a pointer to a
 570 static location, so be sure to make a copy of the structure if you need to
 571 store it somewhere.
 572
 573 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
 574 information on how to use this function on tied hashes.
 575
 576         HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
 577
 578 =item hv_iterinit
 579
 580 Prepares a starting point to traverse a hash table.  Returns the number of
 581 keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
 582 currently only meaningful for hashes without tie magic.
 583
 584 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
 585 hash buckets that happen to be in use.  If you still need that esoteric
 586 value, you can get it through the macro C<HvFILL(tb)>.
 587
 588         I32     hv_iterinit(HV* tb)
 589
 590 =item hv_iterkey
 591
 592 Returns the key from the current position of the hash iterator.  See
 593 C<hv_iterinit>.
 594
 595         char*   hv_iterkey(HE* entry, I32* retlen)
 596
 597 =item hv_iterkeysv
 598
 599 Returns the key as an C<SV*> from the current position of the hash
 600 iterator.  The return value will always be a mortal copy of the key.  Also
 601 see C<hv_iterinit>.
 602
 603         SV*     hv_iterkeysv(HE* entry)
 604
 605 =item hv_iternext
 606
 607 Returns entries from a hash iterator.  See C<hv_iterinit>.
 608
 609         HE*     hv_iternext(HV* tb)
 610
 611 =item hv_iternextsv
 612
 613 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
 614 operation.
 615
 616         SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
 617
 618 =item hv_iterval
 619
 620 Returns the value from the current position of the hash iterator.  See
 621 C<hv_iterkey>.
 622
 623         SV*     hv_iterval(HV* tb, HE* entry)
 624
 625 =item hv_magic
 626
 627 Adds magic to a hash.  See C<sv_magic>.
 628
 629         void    hv_magic(HV* hv, GV* gv, int how)
 630
 631 =item hv_store
 632
 633 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
 634 the length of the key.  The C<hash> parameter is the precomputed hash
 635 value; if it is zero then Perl will compute it.  The return value will be
 636 NULL if the operation failed or if the value did not need to be actually
 637 stored within the hash (as in the case of tied hashes).  Otherwise it can
 638 be dereferenced to get the original C<SV*>.  Note that the caller is
 639 responsible for suitably incrementing the reference count of C<val> before
 640 the call, and decrementing it if the function returned NULL.
 641
 642 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
 643 information on how to use this function on tied hashes.
 644
 645         SV**    hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash)
 646
 647 =item hv_store_ent
 648
 649 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
 650 parameter is the precomputed hash value; if it is zero then Perl will
 651 compute it.  The return value is the new hash entry so created.  It will be
 652 NULL if the operation failed or if the value did not need to be actually
 653 stored within the hash (as in the case of tied hashes).  Otherwise the
 654 contents of the return value can be accessed using the C<He???> macros
 655 described here.  Note that the caller is responsible for suitably
 656 incrementing the reference count of C<val> before the call, and
 657 decrementing it if the function returned NULL.
 658
 659 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
 660 information on how to use this function on tied hashes.
 661
 662         HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
 663
 664 =item hv_undef
 665
 666 Undefines the hash.
 667
 668         void    hv_undef(HV* tb)
 669
 670 =item isALNUM
 671
 672 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
 673 character (including underscore) or digit.
 674
 675         bool    isALNUM(char ch)
 676
 677 =item isALPHA
 678
 679 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
 680 character.
 681
 682         bool    isALPHA(char ch)
 683
 684 =item isDIGIT
 685
 686 Returns a boolean indicating whether the C C<char> is an ASCII
 687 digit.
 688
 689         bool    isDIGIT(char ch)
 690
 691 =item isLOWER
 692
 693 Returns a boolean indicating whether the C C<char> is a lowercase
 694 character.
 695
 696         bool    isLOWER(char ch)
 697
 698 =item isSPACE
 699
 700 Returns a boolean indicating whether the C C<char> is whitespace.
 701
 702         bool    isSPACE(char ch)
 703
 704 =item isUPPER
 705
 706 Returns a boolean indicating whether the C C<char> is an uppercase
 707 character.
 708
 709         bool    isUPPER(char ch)
 710
 711 =item items
 712
 713 Variable which is setup by C<xsubpp> to indicate the number of
 714 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
 715
 716         I32     items
 717
 718 =item ix
 719
 720 Variable which is setup by C<xsubpp> to indicate which of an
 721 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
 722
 723         I32     ix
 724
 725 =item LEAVE
 726
 727 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
 728
 729                 LEAVE;
 730
 731 =item looks_like_number
 732
 733 Test if an the content of an SV looks like a number (or is a
 734 number).
 735
 736         I32     looks_like_number(SV* sv)
 737
 738 =item MARK
 739
 740 Stack marker variable for the XSUB.  See C<dMARK>.
 741
 742 =item mg_clear
 743
 744 Clear something magical that the SV represents.  See C<sv_magic>.
 745
 746         int     mg_clear(SV* sv)
 747
 748 =item mg_copy
 749
 750 Copies the magic from one SV to another.  See C<sv_magic>.
 751
 752         int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
 753
 754 =item mg_find
 755
 756 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
 757
 758         MAGIC*  mg_find(SV* sv, int type)
 759
 760 =item mg_free
 761
 762 Free any magic storage used by the SV.  See C<sv_magic>.
 763
 764         int     mg_free(SV* sv)
 765
 766 =item mg_get
 767
 768 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
 769
 770         int     mg_get(SV* sv)
 771
 772 =item mg_length
 773
 774 Report on the SV's length.  See C<sv_magic>.
 775
 776         U32     mg_length(SV* sv)
 777
 778 =item mg_magical
 779
 780 Turns on the magical status of an SV.  See C<sv_magic>.
 781
 782         void    mg_magical(SV* sv)
 783
 784 =item mg_set
 785
 786 Do magic after a value is assigned to the SV.  See C<sv_magic>.
 787
 788         int     mg_set(SV* sv)
 789
 790 =item Move
 791
 792 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
 793 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
 794 the type.  Can do overlapping moves.  See also C<Copy>.
 795
 796         void    Move(void* src, void* dest, int nitems, type)
 797
 798 =item New
 799
 800 The XSUB-writer's interface to the C C<malloc> function.
 801
 802         void    New(int id, void* ptr, int nitems, type)
 803
 804 =item newAV
 805
 806 Creates a new AV.  The reference count is set to 1.
 807
 808         AV*     newAV()
 809
 810 =item Newc
 811
 812 The XSUB-writer's interface to the C C<malloc> function, with
 813 cast.
 814
 815         void    Newc(int id, void* ptr, int nitems, type, cast)
 816
 817 =item newCONSTSUB
 818
 819 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
 820 eligible for inlining at compile-time.
 821
 822         void    newCONSTSUB(HV* stash, char* name, SV* sv)
 823
 824 =item newHV
 825
 826 Creates a new HV.  The reference count is set to 1.
 827
 828         HV*     newHV()
 829
 830 =item newRV_inc
 831
 832 Creates an RV wrapper for an SV.  The reference count for the original SV is
 833 incremented.
 834
 835         SV*     newRV_inc(SV* sv)
 836
 837 =item newRV_noinc
 838
 839 Creates an RV wrapper for an SV.  The reference count for the original
 840 SV is B<not> incremented.
 841
 842         SV*     newRV_noinc(SV *sv)
 843
 844 =item NEWSV
 845
 846 Creates a new SV.  A non-zero C<len> parameter indicates the number of
 847 bytes of preallocated string space the SV should have.  An extra byte for a
 848 tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
 849 space is allocated.)  The reference count for the new SV is set to 1.
 850 C<id> is an integer id between 0 and 1299 (used to identify leaks).
 851
 852         SV*     NEWSV(int id, STRLEN len)
 853
 854 =item newSViv
 855
 856 Creates a new SV and copies an integer into it.  The reference count for the
 857 SV is set to 1.
 858
 859         SV*     newSViv(IV i)
 860
 861 =item newSVnv
 862
 863 Creates a new SV and copies a floating point value into it.
 864 The reference count for the SV is set to 1.
 865
 866         SV*     newSVnv(NV n)
 867
 868 =item newSVpv
 869
 870 Creates a new SV and copies a string into it.  The reference count for the
 871 SV is set to 1.  If C<len> is zero, Perl will compute the length using
 872 strlen().  For efficiency, consider using C<newSVpvn> instead.
 873
 874         SV*     newSVpv(const char* s, STRLEN len)
 875
 876 =item newSVpvf
 877
 878 Creates a new SV an initialize it with the string formatted like
 879 C<sprintf>.
 880
 881         SV*     newSVpvf(const char* pat, ...)
 882
 883 =item newSVpvn
 884
 885 Creates a new SV and copies a string into it.  The reference count for the
 886 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
 887 string.  You are responsible for ensuring that the source string is at least
 888 C<len> bytes long.
 889
 890         SV*     newSVpvn(const char* s, STRLEN len)
 891
 892 =item newSVrv
 893
 894 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
 895 it will be upgraded to one.  If C<classname> is non-null then the new SV will
 896 be blessed in the specified package.  The new SV is returned and its
 897 reference count is 1.
 898
 899         SV*     newSVrv(SV* rv, const char* classname)
 900
 901 =item newSVsv
 902
 903 Creates a new SV which is an exact duplicate of the original SV.
 904
 905         SV*     newSVsv(SV* old)
 906
 907 =item newSVuv
 908
 909 Creates a new SV and copies an unsigned integer into it.
 910 The reference count for the SV is set to 1.
 911
 912         SV*     newSVuv(UV u)
 913
 914 =item newXS
 915
 916 Used by C<xsubpp> to hook up XSUBs as Perl subs.
 917
 918 =item newXSproto
 919
 920 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
 921 the subs.
 922
 923 =item Newz
 924
 925 The XSUB-writer's interface to the C C<malloc> function.  The allocated
 926 memory is zeroed with C<memzero>.
 927
 928         void    Newz(int id, void* ptr, int nitems, type)
 929
 930 =item Nullav
 931
 932 Null AV pointer.
 933
 934 =item Nullch
 935
 936 Null character pointer.
 937
 938 =item Nullcv
 939
 940 Null CV pointer.
 941
 942 =item Nullhv
 943
 944 Null HV pointer.
 945
 946 =item Nullsv
 947
 948 Null SV pointer.
 949
 950 =item ORIGMARK
 951
 952 The original stack mark for the XSUB.  See C<dORIGMARK>.
 953
 954 =item perl_alloc
 955
 956 Allocates a new Perl interpreter.  See L<perlembed>.
 957
 958         PerlInterpreter*        perl_alloc()
 959
 960 =item perl_construct
 961
 962 Initializes a new Perl interpreter.  See L<perlembed>.
 963
 964         void    perl_construct(PerlInterpreter* interp)
 965
 966 =item perl_destruct
 967
 968 Shuts down a Perl interpreter.  See L<perlembed>.
 969
 970         void    perl_destruct(PerlInterpreter* interp)
 971
 972 =item perl_free
 973
 974 Releases a Perl interpreter.  See L<perlembed>.
 975
 976         void    perl_free(PerlInterpreter* interp)
 977
 978 =item perl_parse
 979
 980 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
 981
 982         int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
 983
 984 =item perl_run
 985
 986 Tells a Perl interpreter to run.  See L<perlembed>.
 987
 988         int     perl_run(PerlInterpreter* interp)
 989
 990 =item PL_DBsingle
 991
 992 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
 993 boolean which indicates whether subs are being single-stepped.
 994 Single-stepping is automatically turned on after every step.  This is the C
 995 variable which corresponds to Perl's $DB::single variable.  See
 996 C<PL_DBsub>.
 997
 998         SV *    PL_DBsingle
 999
1000 =item PL_DBsub
1001
1002 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1003 the SV which holds the name of the sub being debugged.  This is the C
1004 variable which corresponds to Perl's $DB::sub variable.  See
1005 C<PL_DBsingle>.
1006
1007         GV *    PL_DBsub
1008
1009 =item PL_DBtrace
1010
1011 Trace variable used when Perl is run in debugging mode, with the B<-d>
1012 switch.  This is the C variable which corresponds to Perl's $DB::trace
1013 variable.  See C<PL_DBsingle>.
1014
1015         SV *    PL_DBtrace
1016
1017 =item PL_dowarn
1018
1019 The C variable which corresponds to Perl's $^W warning variable.
1020
1021         bool    PL_dowarn
1022
1023 =item PL_modglobal
1024
1025 C<PL_modglobal> is a general purpose, interpreter global HV for use by
1026 extensions that need to keep information on a per-interpreter basis.
1027 In a pinch, it can also be used as a symbol table for extensions
1028 to share data among each other.  It is a good idea to use keys
1029 prefixed by the package name of the extension that owns the data.
1030
1031         HV*     PL_modglobal
1032
1033 =item PL_na
1034
1035 A convenience variable which is typically used with C<SvPV> when one
1036 doesn't care about the length of the string.  It is usually more efficient
1037 to either declare a local variable and use that instead or to use the
1038 C<SvPV_nolen> macro.
1039
1040         STRLEN  PL_na
1041
1042 =item PL_sv_no
1043
1044 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
1045 C<&PL_sv_no>.
1046
1047         SV      PL_sv_no
1048
1049 =item PL_sv_undef
1050
1051 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
1052
1053         SV      PL_sv_undef
1054
1055 =item PL_sv_yes
1056
1057 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
1058 C<&PL_sv_yes>.
1059
1060         SV      PL_sv_yes
1061
1062 =item POPi
1063
1064 Pops an integer off the stack.
1065
1066         IV      POPi
1067
1068 =item POPl
1069
1070 Pops a long off the stack.
1071
1072         long    POPl
1073
1074 =item POPn
1075
1076 Pops a double off the stack.
1077
1078         NV      POPn
1079
1080 =item POPp
1081
1082 Pops a string off the stack.
1083
1084         char*   POPp
1085
1086 =item POPs
1087
1088 Pops an SV off the stack.
1089
1090         SV*     POPs
1091
1092 =item PUSHi
1093
1094 Push an integer onto the stack.  The stack must have room for this element.
1095 Handles 'set' magic.  See C<XPUSHi>.
1096
1097         void    PUSHi(IV iv)
1098
1099 =item PUSHMARK
1100
1101 Opening bracket for arguments on a callback.  See C<PUTBACK> and
1102 L<perlcall>.
1103
1104                 PUSHMARK;
1105
1106 =item PUSHn
1107
1108 Push a double onto the stack.  The stack must have room for this element.
1109 Handles 'set' magic.  See C<XPUSHn>.
1110
1111         void    PUSHn(NV nv)
1112
1113 =item PUSHp
1114
1115 Push a string onto the stack.  The stack must have room for this element.
1116 The C<len> indicates the length of the string.  Handles 'set' magic.  See
1117 C<XPUSHp>.
1118
1119         void    PUSHp(char* str, STRLEN len)
1120
1121 =item PUSHs
1122
1123 Push an SV onto the stack.  The stack must have room for this element.
1124 Does not handle 'set' magic.  See C<XPUSHs>.
1125
1126         void    PUSHs(SV* sv)
1127
1128 =item PUSHu
1129
1130 Push an unsigned integer onto the stack.  The stack must have room for this
1131 element.  See C<XPUSHu>.
1132
1133         void    PUSHu(UV uv)
1134
1135 =item PUTBACK
1136
1137 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
1138 See C<PUSHMARK> and L<perlcall> for other uses.
1139
1140                 PUTBACK;
1141
1142 =item Renew
1143
1144 The XSUB-writer's interface to the C C<realloc> function.
1145
1146         void    Renew(void* ptr, int nitems, type)
1147
1148 =item Renewc
1149
1150 The XSUB-writer's interface to the C C<realloc> function, with
1151 cast.
1152
1153         void    Renewc(void* ptr, int nitems, type, cast)
1154
1155 =item require_pv
1156
1157 Tells Perl to C<require> a module.
1158
1159 NOTE: the perl_ form of this function is deprecated.
1160
1161         void    require_pv(const char* pv)
1162
1163 =item RETVAL
1164
1165 Variable which is setup by C<xsubpp> to hold the return value for an
1166 XSUB. This is always the proper type for the XSUB. See
1167 L<perlxs/"The RETVAL Variable">.
1168
1169         (whatever)      RETVAL
1170
1171 =item Safefree
1172
1173 The XSUB-writer's interface to the C C<free> function.
1174
1175         void    Safefree(void* src, void* dest, int nitems, type)
1176
1177 =item savepv
1178
1179 Copy a string to a safe spot.  This does not use an SV.
1180
1181         char*   savepv(const char* sv)
1182
1183 =item savepvn
1184
1185 Copy a string to a safe spot.  The C<len> indicates number of bytes to
1186 copy.  This does not use an SV.
1187
1188         char*   savepvn(const char* sv, I32 len)
1189
1190 =item SAVETMPS
1191
1192 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
1193 L<perlcall>.
1194
1195                 SAVETMPS;
1196
1197 =item SP
1198
1199 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
1200 C<SPAGAIN>.
1201
1202 =item SPAGAIN
1203
1204 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
1205
1206                 SPAGAIN;
1207
1208 =item ST
1209
1210 Used to access elements on the XSUB's stack.
1211
1212         SV*     ST(int ix)
1213
1214 =item strEQ
1215
1216 Test two strings to see if they are equal.  Returns true or false.
1217
1218         bool    strEQ(char* s1, char* s2)
1219
1220 =item strGE
1221
1222 Test two strings to see if the first, C<s1>, is greater than or equal to
1223 the second, C<s2>.  Returns true or false.
1224
1225         bool    strGE(char* s1, char* s2)
1226
1227 =item strGT
1228
1229 Test two strings to see if the first, C<s1>, is greater than the second,
1230 C<s2>.  Returns true or false.
1231
1232         bool    strGT(char* s1, char* s2)
1233
1234 =item strLE
1235
1236 Test two strings to see if the first, C<s1>, is less than or equal to the
1237 second, C<s2>.  Returns true or false.
1238
1239         bool    strLE(char* s1, char* s2)
1240
1241 =item strLT
1242
1243 Test two strings to see if the first, C<s1>, is less than the second,
1244 C<s2>.  Returns true or false.
1245
1246         bool    strLT(char* s1, char* s2)
1247
1248 =item strNE
1249
1250 Test two strings to see if they are different.  Returns true or
1251 false.
1252
1253         bool    strNE(char* s1, char* s2)
1254
1255 =item strnEQ
1256
1257 Test two strings to see if they are equal.  The C<len> parameter indicates
1258 the number of bytes to compare.  Returns true or false. (A wrapper for
1259 C<strncmp>).
1260
1261         bool    strnEQ(char* s1, char* s2, STRLEN len)
1262
1263 =item strnNE
1264
1265 Test two strings to see if they are different.  The C<len> parameter
1266 indicates the number of bytes to compare.  Returns true or false. (A
1267 wrapper for C<strncmp>).
1268
1269         bool    strnNE(char* s1, char* s2, STRLEN len)
1270
1271 =item StructCopy
1272
1273 This is an architecture-independent macro to copy one structure to another.
1274
1275         void    StructCopy(type src, type dest, type)
1276
1277 =item SvCUR
1278
1279 Returns the length of the string which is in the SV.  See C<SvLEN>.
1280
1281         STRLEN  SvCUR(SV* sv)
1282
1283 =item SvCUR_set
1284
1285 Set the length of the string which is in the SV.  See C<SvCUR>.
1286
1287         void    SvCUR_set(SV* sv, STRLEN len)
1288
1289 =item SvEND
1290
1291 Returns a pointer to the last character in the string which is in the SV.
1292 See C<SvCUR>.  Access the character as *(SvEND(sv)).
1293
1294         char*   SvEND(SV* sv)
1295
1296 =item SvGETMAGIC
1297
1298 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
1299 argument more than once.
1300
1301         void    SvGETMAGIC(SV* sv)
1302
1303 =item SvGROW
1304
1305 Expands the character buffer in the SV so that it has room for the
1306 indicated number of bytes (remember to reserve space for an extra trailing
1307 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
1308 Returns a pointer to the character buffer.
1309
1310         void    SvGROW(SV* sv, STRLEN len)
1311
1312 =item SvIOK
1313
1314 Returns a boolean indicating whether the SV contains an integer.
1315
1316         bool    SvIOK(SV* sv)
1317
1318 =item SvIOKp
1319
1320 Returns a boolean indicating whether the SV contains an integer.  Checks
1321 the B<private> setting.  Use C<SvIOK>.
1322
1323         bool    SvIOKp(SV* sv)
1324
1325 =item SvIOK_off
1326
1327 Unsets the IV status of an SV.
1328
1329         void    SvIOK_off(SV* sv)
1330
1331 =item SvIOK_on
1332
1333 Tells an SV that it is an integer.
1334
1335         void    SvIOK_on(SV* sv)
1336
1337 =item SvIOK_only
1338
1339 Tells an SV that it is an integer and disables all other OK bits.
1340
1341         void    SvIOK_only(SV* sv)
1342
1343 =item SvIV
1344
1345 Coerces the given SV to an integer and returns it.
1346
1347         IV      SvIV(SV* sv)
1348
1349 =item SvIVX
1350
1351 Returns the integer which is stored in the SV, assuming SvIOK is
1352 true.
1353
1354         IV      SvIVX(SV* sv)
1355
1356 =item SvLEN
1357
1358 Returns the size of the string buffer in the SV.  See C<SvCUR>.
1359
1360         STRLEN  SvLEN(SV* sv)
1361
1362 =item SvNIOK
1363
1364 Returns a boolean indicating whether the SV contains a number, integer or
1365 double.
1366
1367         bool    SvNIOK(SV* sv)
1368
1369 =item SvNIOKp
1370
1371 Returns a boolean indicating whether the SV contains a number, integer or
1372 double.  Checks the B<private> setting.  Use C<SvNIOK>.
1373
1374         bool    SvNIOKp(SV* sv)
1375
1376 =item SvNIOK_off
1377
1378 Unsets the NV/IV status of an SV.
1379
1380         void    SvNIOK_off(SV* sv)
1381
1382 =item SvNOK
1383
1384 Returns a boolean indicating whether the SV contains a double.
1385
1386         bool    SvNOK(SV* sv)
1387
1388 =item SvNOKp
1389
1390 Returns a boolean indicating whether the SV contains a double.  Checks the
1391 B<private> setting.  Use C<SvNOK>.
1392
1393         bool    SvNOKp(SV* sv)
1394
1395 =item SvNOK_off
1396
1397 Unsets the NV status of an SV.
1398
1399         void    SvNOK_off(SV* sv)
1400
1401 =item SvNOK_on
1402
1403 Tells an SV that it is a double.
1404
1405         void    SvNOK_on(SV* sv)
1406
1407 =item SvNOK_only
1408
1409 Tells an SV that it is a double and disables all other OK bits.
1410
1411         void    SvNOK_only(SV* sv)
1412
1413 =item SvNV
1414
1415 Coerce the given SV to a double and return it.
1416
1417         NV      SvNV(SV* sv)
1418
1419 =item SvNVX
1420
1421 Returns the double which is stored in the SV, assuming SvNOK is
1422 true.
1423
1424         NV      SvNVX(SV* sv)
1425
1426 =item SvOK
1427
1428 Returns a boolean indicating whether the value is an SV.
1429
1430         bool    SvOK(SV* sv)
1431
1432 =item SvOOK
1433
1434 Returns a boolean indicating whether the SvIVX is a valid offset value for
1435 the SvPVX.  This hack is used internally to speed up removal of characters
1436 from the beginning of a SvPV.  When SvOOK is true, then the start of the
1437 allocated string buffer is really (SvPVX - SvIVX).
1438
1439         bool    SvOOK(SV* sv)
1440
1441 =item SvPOK
1442
1443 Returns a boolean indicating whether the SV contains a character
1444 string.
1445
1446         bool    SvPOK(SV* sv)
1447
1448 =item SvPOKp
1449
1450 Returns a boolean indicating whether the SV contains a character string.
1451 Checks the B<private> setting.  Use C<SvPOK>.
1452
1453         bool    SvPOKp(SV* sv)
1454
1455 =item SvPOK_off
1456
1457 Unsets the PV status of an SV.
1458
1459         void    SvPOK_off(SV* sv)
1460
1461 =item SvPOK_on
1462
1463 Tells an SV that it is a string.
1464
1465         void    SvPOK_on(SV* sv)
1466
1467 =item SvPOK_only
1468
1469 Tells an SV that it is a string and disables all other OK bits.
1470
1471         void    SvPOK_only(SV* sv)
1472
1473 =item SvPV
1474
1475 Returns a pointer to the string in the SV, or a stringified form of the SV
1476 if the SV does not contain a string.  Handles 'get' magic.
1477
1478         char*   SvPV(SV* sv, STRLEN len)
1479
1480 =item SvPVX
1481
1482 Returns a pointer to the string in the SV.  The SV must contain a
1483 string.
1484
1485         char*   SvPVX(SV* sv)
1486
1487 =item SvPV_force
1488
1489 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
1490 force if you are going to update the SvPVX directly.
1491
1492         char*   SvPV_force(SV* sv, STRLEN len)
1493
1494 =item SvPV_nolen
1495
1496 Returns a pointer to the string in the SV, or a stringified form of the SV
1497 if the SV does not contain a string.  Handles 'get' magic.
1498
1499         char*   SvPV_nolen(SV* sv)
1500
1501 =item SvREFCNT
1502
1503 Returns the value of the object's reference count.
1504
1505         U32     SvREFCNT(SV* sv)
1506
1507 =item SvREFCNT_dec
1508
1509 Decrements the reference count of the given SV.
1510
1511         void    SvREFCNT_dec(SV* sv)
1512
1513 =item SvREFCNT_inc
1514
1515 Increments the reference count of the given SV.
1516
1517         SV*     SvREFCNT_inc(SV* sv)
1518
1519 =item SvROK
1520
1521 Tests if the SV is an RV.
1522
1523         bool    SvROK(SV* sv)
1524
1525 =item SvROK_off
1526
1527 Unsets the RV status of an SV.
1528
1529         void    SvROK_off(SV* sv)
1530
1531 =item SvROK_on
1532
1533 Tells an SV that it is an RV.
1534
1535         void    SvROK_on(SV* sv)
1536
1537 =item SvRV
1538
1539 Dereferences an RV to return the SV.
1540
1541         SV*     SvRV(SV* sv)
1542
1543 =item SvSETMAGIC
1544
1545 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
1546 argument more than once.
1547
1548         void    SvSETMAGIC(SV* sv)
1549
1550 =item SvSetSV
1551
1552 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
1553 more than once.
1554
1555         void    SvSetSV(SV* dsb, SV* ssv)
1556
1557 =item SvSetSV_nosteal
1558
1559 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1560 ssv. May evaluate arguments more than once.
1561
1562         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
1563
1564 =item SvSTASH
1565
1566 Returns the stash of the SV.
1567
1568         HV*     SvSTASH(SV* sv)
1569
1570 =item SvTAINT
1571
1572 Taints an SV if tainting is enabled
1573
1574         void    SvTAINT(SV* sv)
1575
1576 =item SvTAINTED
1577
1578 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
1579 not.
1580
1581         bool    SvTAINTED(SV* sv)
1582
1583 =item SvTAINTED_off
1584
1585 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
1586 some of Perl's fundamental security features. XS module authors should not
1587 use this function unless they fully understand all the implications of
1588 unconditionally untainting the value. Untainting should be done in the
1589 standard perl fashion, via a carefully crafted regexp, rather than directly
1590 untainting variables.
1591
1592         void    SvTAINTED_off(SV* sv)
1593
1594 =item SvTAINTED_on
1595
1596 Marks an SV as tainted.
1597
1598         void    SvTAINTED_on(SV* sv)
1599
1600 =item SvTRUE
1601
1602 Returns a boolean indicating whether Perl would evaluate the SV as true or
1603 false, defined or undefined.  Does not handle 'get' magic.
1604
1605         bool    SvTRUE(SV* sv)
1606
1607 =item SvTYPE
1608
1609 Returns the type of the SV.  See C<svtype>.
1610
1611         svtype  SvTYPE(SV* sv)
1612
1613 =item svtype
1614
1615 An enum of flags for Perl types.  These are found in the file B<sv.h>
1616 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
1617
1618 =item SVt_IV
1619
1620 Integer type flag for scalars.  See C<svtype>.
1621
1622 =item SVt_NV
1623
1624 Double type flag for scalars.  See C<svtype>.
1625
1626 =item SVt_PV
1627
1628 Pointer type flag for scalars.  See C<svtype>.
1629
1630 =item SVt_PVAV
1631
1632 Type flag for arrays.  See C<svtype>.
1633
1634 =item SVt_PVCV
1635
1636 Type flag for code refs.  See C<svtype>.
1637
1638 =item SVt_PVHV
1639
1640 Type flag for hashes.  See C<svtype>.
1641
1642 =item SVt_PVMG
1643
1644 Type flag for blessed scalars.  See C<svtype>.
1645
1646 =item SvUPGRADE
1647
1648 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
1649 perform the upgrade if necessary.  See C<svtype>.
1650
1651         void    SvUPGRADE(SV* sv, svtype type)
1652
1653 =item SvUV
1654
1655 Coerces the given SV to an unsigned integer and returns it.
1656
1657         UV      SvUV(SV* sv)
1658
1659 =item SvUVX
1660
1661 Returns the unsigned integer which is stored in the SV, assuming SvIOK is
1662 true.
1663
1664         UV      SvUVX(SV* sv)
1665
1666 =item sv_2mortal
1667
1668 Marks an SV as mortal.  The SV will be destroyed when the current context
1669 ends.
1670
1671         SV*     sv_2mortal(SV* sv)
1672
1673 =item sv_bless
1674
1675 Blesses an SV into a specified package.  The SV must be an RV.  The package
1676 must be designated by its stash (see C<gv_stashpv()>).  The reference count
1677 of the SV is unaffected.
1678
1679         SV*     sv_bless(SV* sv, HV* stash)
1680
1681 =item sv_catpv
1682
1683 Concatenates the string onto the end of the string which is in the SV.
1684 Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
1685
1686         void    sv_catpv(SV* sv, const char* ptr)
1687
1688 =item sv_catpvf
1689
1690 Processes its arguments like C<sprintf> and appends the formatted output
1691 to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
1692 typically be called after calling this function to handle 'set' magic.
1693
1694         void    sv_catpvf(SV* sv, const char* pat, ...)
1695
1696 =item sv_catpvf_mg
1697
1698 Like C<sv_catpvf>, but also handles 'set' magic.
1699
1700         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
1701
1702 =item sv_catpvn
1703
1704 Concatenates the string onto the end of the string which is in the SV.  The
1705 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
1706 'set' magic.  See C<sv_catpvn_mg>.
1707
1708         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
1709
1710 =item sv_catpvn_mg
1711
1712 Like C<sv_catpvn>, but also handles 'set' magic.
1713
1714         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
1715
1716 =item sv_catpv_mg
1717
1718 Like C<sv_catpv>, but also handles 'set' magic.
1719
1720         void    sv_catpv_mg(SV *sv, const char *ptr)
1721
1722 =item sv_catsv
1723
1724 Concatenates the string from SV C<ssv> onto the end of the string in SV
1725 C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
1726
1727         void    sv_catsv(SV* dsv, SV* ssv)
1728
1729 =item sv_catsv_mg
1730
1731 Like C<sv_catsv>, but also handles 'set' magic.
1732
1733         void    sv_catsv_mg(SV *dstr, SV *sstr)
1734
1735 =item sv_chop
1736
1737 Efficient removal of characters from the beginning of the string buffer.
1738 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
1739 the string buffer.  The C<ptr> becomes the first character of the adjusted
1740 string.
1741
1742         void    sv_chop(SV* sv, char* ptr)
1743
1744 =item sv_cmp
1745
1746 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
1747 string in C<sv1> is less than, equal to, or greater than the string in
1748 C<sv2>.
1749
1750         I32     sv_cmp(SV* sv1, SV* sv2)
1751
1752 =item sv_dec
1753
1754 Auto-decrement of the value in the SV.
1755
1756         void    sv_dec(SV* sv)
1757
1758 =item sv_derived_from
1759
1760 Returns a boolean indicating whether the SV is derived from the specified
1761 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
1762 for class names as well as for objects.
1763
1764         bool    sv_derived_from(SV* sv, const char* name)
1765
1766 =item sv_eq
1767
1768 Returns a boolean indicating whether the strings in the two SVs are
1769 identical.
1770
1771         I32     sv_eq(SV* sv1, SV* sv2)
1772
1773 =item sv_grow
1774
1775 Expands the character buffer in the SV.  This will use C<sv_unref> and will
1776 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
1777 Use C<SvGROW>.
1778
1779         char*   sv_grow(SV* sv, STRLEN newlen)
1780
1781 =item sv_inc
1782
1783 Auto-increment of the value in the SV.
1784
1785         void    sv_inc(SV* sv)
1786
1787 =item sv_insert
1788
1789 Inserts a string at the specified offset/length within the SV. Similar to
1790 the Perl substr() function.
1791
1792         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
1793
1794 =item sv_isa
1795
1796 Returns a boolean indicating whether the SV is blessed into the specified
1797 class.  This does not check for subtypes; use C<sv_derived_from> to verify
1798 an inheritance relationship.
1799
1800         int     sv_isa(SV* sv, const char* name)
1801
1802 =item sv_isobject
1803
1804 Returns a boolean indicating whether the SV is an RV pointing to a blessed
1805 object.  If the SV is not an RV, or if the object is not blessed, then this
1806 will return false.
1807
1808         int     sv_isobject(SV* sv)
1809
1810 =item sv_len
1811
1812 Returns the length of the string in the SV.  See also C<SvCUR>.
1813
1814         STRLEN  sv_len(SV* sv)
1815
1816 =item sv_magic
1817
1818 Adds magic to an SV.
1819
1820         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
1821
1822 =item sv_mortalcopy
1823
1824 Creates a new SV which is a copy of the original SV.  The new SV is marked
1825 as mortal.
1826
1827         SV*     sv_mortalcopy(SV* oldsv)
1828
1829 =item sv_newmortal
1830
1831 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
1832
1833         SV*     sv_newmortal()
1834
1835 =item sv_setiv
1836
1837 Copies an integer into the given SV.  Does not handle 'set' magic.  See
1838 C<sv_setiv_mg>.
1839
1840         void    sv_setiv(SV* sv, IV num)
1841
1842 =item sv_setiv_mg
1843
1844 Like C<sv_setiv>, but also handles 'set' magic.
1845
1846         void    sv_setiv_mg(SV *sv, IV i)
1847
1848 =item sv_setnv
1849
1850 Copies a double into the given SV.  Does not handle 'set' magic.  See
1851 C<sv_setnv_mg>.
1852
1853         void    sv_setnv(SV* sv, NV num)
1854
1855 =item sv_setnv_mg
1856
1857 Like C<sv_setnv>, but also handles 'set' magic.
1858
1859         void    sv_setnv_mg(SV *sv, NV num)
1860
1861 =item sv_setpv
1862
1863 Copies a string into an SV.  The string must be null-terminated.  Does not
1864 handle 'set' magic.  See C<sv_setpv_mg>.
1865
1866         void    sv_setpv(SV* sv, const char* ptr)
1867
1868 =item sv_setpvf
1869
1870 Processes its arguments like C<sprintf> and sets an SV to the formatted
1871 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
1872
1873         void    sv_setpvf(SV* sv, const char* pat, ...)
1874
1875 =item sv_setpvf_mg
1876
1877 Like C<sv_setpvf>, but also handles 'set' magic.
1878
1879         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
1880
1881 =item sv_setpviv
1882
1883 Copies an integer into the given SV, also updating its string value.
1884 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
1885
1886         void    sv_setpviv(SV* sv, IV num)
1887
1888 =item sv_setpviv_mg
1889
1890 Like C<sv_setpviv>, but also handles 'set' magic.
1891
1892         void    sv_setpviv_mg(SV *sv, IV iv)
1893
1894 =item sv_setpvn
1895
1896 Copies a string into an SV.  The C<len> parameter indicates the number of
1897 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
1898
1899         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
1900
1901 =item sv_setpvn_mg
1902
1903 Like C<sv_setpvn>, but also handles 'set' magic.
1904
1905         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
1906
1907 =item sv_setpv_mg
1908
1909 Like C<sv_setpv>, but also handles 'set' magic.
1910
1911         void    sv_setpv_mg(SV *sv, const char *ptr)
1912
1913 =item sv_setref_iv
1914
1915 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
1916 argument will be upgraded to an RV.  That RV will be modified to point to
1917 the new SV.  The C<classname> argument indicates the package for the
1918 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1919 will be returned and will have a reference count of 1.
1920
1921         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
1922
1923 =item sv_setref_nv
1924
1925 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
1926 argument will be upgraded to an RV.  That RV will be modified to point to
1927 the new SV.  The C<classname> argument indicates the package for the
1928 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1929 will be returned and will have a reference count of 1.
1930
1931         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
1932
1933 =item sv_setref_pv
1934
1935 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
1936 argument will be upgraded to an RV.  That RV will be modified to point to
1937 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
1938 into the SV.  The C<classname> argument indicates the package for the
1939 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1940 will be returned and will have a reference count of 1.
1941
1942 Do not use with other Perl types such as HV, AV, SV, CV, because those
1943 objects will become corrupted by the pointer copy process.
1944
1945 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
1946
1947         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
1948
1949 =item sv_setref_pvn
1950
1951 Copies a string into a new SV, optionally blessing the SV.  The length of the
1952 string must be specified with C<n>.  The C<rv> argument will be upgraded to
1953 an RV.  That RV will be modified to point to the new SV.  The C<classname>
1954 argument indicates the package for the blessing.  Set C<classname> to
1955 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
1956 a reference count of 1.
1957
1958 Note that C<sv_setref_pv> copies the pointer while this copies the string.
1959
1960         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
1961
1962 =item sv_setsv
1963
1964 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
1965 The source SV may be destroyed if it is mortal.  Does not handle 'set'
1966 magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
1967 C<sv_setsv_mg>.
1968
1969         void    sv_setsv(SV* dsv, SV* ssv)
1970
1971 =item sv_setsv_mg
1972
1973 Like C<sv_setsv>, but also handles 'set' magic.
1974
1975         void    sv_setsv_mg(SV *dstr, SV *sstr)
1976
1977 =item sv_setuv
1978
1979 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
1980 See C<sv_setuv_mg>.
1981
1982         void    sv_setuv(SV* sv, UV num)
1983
1984 =item sv_setuv_mg
1985
1986 Like C<sv_setuv>, but also handles 'set' magic.
1987
1988         void    sv_setuv_mg(SV *sv, UV u)
1989
1990 =item sv_unref
1991
1992 Unsets the RV status of the SV, and decrements the reference count of
1993 whatever was being referenced by the RV.  This can almost be thought of
1994 as a reversal of C<newSVrv>.  See C<SvROK_off>.
1995
1996         void    sv_unref(SV* sv)
1997
1998 =item sv_upgrade
1999
2000 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
2001 C<svtype>.
2002
2003         bool    sv_upgrade(SV* sv, U32 mt)
2004
2005 =item sv_usepvn
2006
2007 Tells an SV to use C<ptr> to find its string value.  Normally the string is
2008 stored inside the SV but sv_usepvn allows the SV to use an outside string.
2009 The C<ptr> should point to memory that was allocated by C<malloc>.  The
2010 string length, C<len>, must be supplied.  This function will realloc the
2011 memory pointed to by C<ptr>, so that pointer should not be freed or used by
2012 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
2013 See C<sv_usepvn_mg>.
2014
2015         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
2016
2017 =item sv_usepvn_mg
2018
2019 Like C<sv_usepvn>, but also handles 'set' magic.
2020
2021         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
2022
2023 =item sv_vcatpvfn
2024
2025 Processes its arguments like C<vsprintf> and appends the formatted output
2026 to an SV.  Uses an array of SVs if the C style variable argument list is
2027 missing (NULL).  When running with taint checks enabled, indicates via
2028 C<maybe_tainted> if results are untrustworthy (often due to the use of
2029 locales).
2030
2031         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2032
2033 =item sv_vsetpvfn
2034
2035 Works like C<vcatpvfn> but copies the text into the SV instead of
2036 appending it.
2037
2038         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2039
2040 =item THIS
2041
2042 Variable which is setup by C<xsubpp> to designate the object in a C++
2043 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and
2044 L<perlxs/"Using XS With C++">.
2045
2046         (whatever)      THIS
2047
2048 =item toLOWER
2049
2050 Converts the specified character to lowercase.
2051
2052         char    toLOWER(char ch)
2053
2054 =item toUPPER
2055
2056 Converts the specified character to uppercase.
2057
2058         char    toUPPER(char ch)
2059
2060 =item warn
2061
2062 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
2063 function the same way you use the C C<printf> function.  See
2064 C<croak>.
2065
2066         void    warn(const char* pat, ...)
2067
2068 =item XPUSHi
2069
2070 Push an integer onto the stack, extending the stack if necessary.  Handles
2071 'set' magic. See C<PUSHi>.
2072
2073         void    XPUSHi(IV iv)
2074
2075 =item XPUSHn
2076
2077 Push a double onto the stack, extending the stack if necessary.  Handles
2078 'set' magic.  See C<PUSHn>.
2079
2080         void    XPUSHn(NV nv)
2081
2082 =item XPUSHp
2083
2084 Push a string onto the stack, extending the stack if necessary.  The C<len>
2085 indicates the length of the string.  Handles 'set' magic.  See
2086 C<PUSHp>.
2087
2088         void    XPUSHp(char* str, STRLEN len)
2089
2090 =item XPUSHs
2091
2092 Push an SV onto the stack, extending the stack if necessary.  Does not
2093 handle 'set' magic.  See C<PUSHs>.
2094
2095         void    XPUSHs(SV* sv)
2096
2097 =item XPUSHu
2098
2099 Push an unsigned integer onto the stack, extending the stack if necessary.
2100 See C<PUSHu>.
2101
2102         void    XPUSHu(UV uv)
2103
2104 =item XS
2105
2106 Macro to declare an XSUB and its C parameter list.  This is handled by
2107 C<xsubpp>.
2108
2109 =item XSRETURN
2110
2111 Return from XSUB, indicating number of items on the stack.  This is usually
2112 handled by C<xsubpp>.
2113
2114         void    XSRETURN(int nitems)
2115
2116 =item XSRETURN_EMPTY
2117
2118 Return an empty list from an XSUB immediately.
2119
2120                 XSRETURN_EMPTY;
2121
2122 =item XSRETURN_IV
2123
2124 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
2125
2126         void    XSRETURN_IV(IV iv)
2127
2128 =item XSRETURN_NO
2129
2130 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
2131
2132                 XSRETURN_NO;
2133
2134 =item XSRETURN_NV
2135
2136 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
2137
2138         void    XSRETURN_NV(NV nv)
2139
2140 =item XSRETURN_PV
2141
2142 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
2143
2144         void    XSRETURN_PV(char* str)
2145
2146 =item XSRETURN_UNDEF
2147
2148 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
2149
2150                 XSRETURN_UNDEF;
2151
2152 =item XSRETURN_YES
2153
2154 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
2155
2156                 XSRETURN_YES;
2157
2158 =item XST_mIV
2159
2160 Place an integer into the specified position C<pos> on the stack.  The
2161 value is stored in a new mortal SV.
2162
2163         void    XST_mIV(int pos, IV iv)
2164
2165 =item XST_mNO
2166
2167 Place C<&PL_sv_no> into the specified position C<pos> on the
2168 stack.
2169
2170         void    XST_mNO(int pos)
2171
2172 =item XST_mNV
2173
2174 Place a double into the specified position C<pos> on the stack.  The value
2175 is stored in a new mortal SV.
2176
2177         void    XST_mNV(int pos, NV nv)
2178
2179 =item XST_mPV
2180
2181 Place a copy of a string into the specified position C<pos> on the stack.
2182 The value is stored in a new mortal SV.
2183
2184         void    XST_mPV(int pos, char* str)
2185
2186 =item XST_mUNDEF
2187
2188 Place C<&PL_sv_undef> into the specified position C<pos> on the
2189 stack.
2190
2191         void    XST_mUNDEF(int pos)
2192
2193 =item XST_mYES
2194
2195 Place C<&PL_sv_yes> into the specified position C<pos> on the
2196 stack.
2197
2198         void    XST_mYES(int pos)
2199
2200 =item XS_VERSION
2201
2202 The version identifier for an XS module.  This is usually
2203 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
2204
2205 =item XS_VERSION_BOOTCHECK
2206
2207 Macro to verify that a PM module's $VERSION variable matches the XS
2208 module's C<XS_VERSION> variable.  This is usually handled automatically by
2209 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
2210
2211                 XS_VERSION_BOOTCHECK;
2212
2213 =item Zero
2214
2215 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2216 destination, C<nitems> is the number of items, and C<type> is the type.
2217
2218         void    Zero(void* dest, int nitems, type)
2219
2220 =back
2221
2222 =head1 AUTHORS
2223
2224 Until May 1997, this document was maintained by Jeff Okamoto
2225 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
2226
2227 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2228 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2229 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
2230 Stephen McCamant, and Gurusamy Sarathy.
2231
2232 API Listing originally by Dean Roehrich <roehrich@cray.com>.
2233
2234 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
2235
2236 =head1 SEE ALSO
2237
2238 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
2239