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 SvLOCK
1363
1364 Aquires an internal mutex for a SV. Used to make sure multiple threads
1365 don't stomp on the guts of an SV at the same time
1366
1367         void    SvLOCK(SV* sv)
1368
1369 =item SvNIOK
1370
1371 Returns a boolean indicating whether the SV contains a number, integer or
1372 double.
1373
1374         bool    SvNIOK(SV* sv)
1375
1376 =item SvNIOKp
1377
1378 Returns a boolean indicating whether the SV contains a number, integer or
1379 double.  Checks the B<private> setting.  Use C<SvNIOK>.
1380
1381         bool    SvNIOKp(SV* sv)
1382
1383 =item SvNIOK_off
1384
1385 Unsets the NV/IV status of an SV.
1386
1387         void    SvNIOK_off(SV* sv)
1388
1389 =item SvNOK
1390
1391 Returns a boolean indicating whether the SV contains a double.
1392
1393         bool    SvNOK(SV* sv)
1394
1395 =item SvNOKp
1396
1397 Returns a boolean indicating whether the SV contains a double.  Checks the
1398 B<private> setting.  Use C<SvNOK>.
1399
1400         bool    SvNOKp(SV* sv)
1401
1402 =item SvNOK_off
1403
1404 Unsets the NV status of an SV.
1405
1406         void    SvNOK_off(SV* sv)
1407
1408 =item SvNOK_on
1409
1410 Tells an SV that it is a double.
1411
1412         void    SvNOK_on(SV* sv)
1413
1414 =item SvNOK_only
1415
1416 Tells an SV that it is a double and disables all other OK bits.
1417
1418         void    SvNOK_only(SV* sv)
1419
1420 =item SvNV
1421
1422 Coerce the given SV to a double and return it.
1423
1424         NV      SvNV(SV* sv)
1425
1426 =item SvNVX
1427
1428 Returns the double which is stored in the SV, assuming SvNOK is
1429 true.
1430
1431         NV      SvNVX(SV* sv)
1432
1433 =item SvOK
1434
1435 Returns a boolean indicating whether the value is an SV.
1436
1437         bool    SvOK(SV* sv)
1438
1439 =item SvOOK
1440
1441 Returns a boolean indicating whether the SvIVX is a valid offset value for
1442 the SvPVX.  This hack is used internally to speed up removal of characters
1443 from the beginning of a SvPV.  When SvOOK is true, then the start of the
1444 allocated string buffer is really (SvPVX - SvIVX).
1445
1446         bool    SvOOK(SV* sv)
1447
1448 =item SvPOK
1449
1450 Returns a boolean indicating whether the SV contains a character
1451 string.
1452
1453         bool    SvPOK(SV* sv)
1454
1455 =item SvPOKp
1456
1457 Returns a boolean indicating whether the SV contains a character string.
1458 Checks the B<private> setting.  Use C<SvPOK>.
1459
1460         bool    SvPOKp(SV* sv)
1461
1462 =item SvPOK_off
1463
1464 Unsets the PV status of an SV.
1465
1466         void    SvPOK_off(SV* sv)
1467
1468 =item SvPOK_on
1469
1470 Tells an SV that it is a string.
1471
1472         void    SvPOK_on(SV* sv)
1473
1474 =item SvPOK_only
1475
1476 Tells an SV that it is a string and disables all other OK bits.
1477
1478         void    SvPOK_only(SV* sv)
1479
1480 =item SvPV
1481
1482 Returns a pointer to the string in the SV, or a stringified form of the SV
1483 if the SV does not contain a string.  Handles 'get' magic.
1484
1485         char*   SvPV(SV* sv, STRLEN len)
1486
1487 =item SvPVX
1488
1489 Returns a pointer to the string in the SV.  The SV must contain a
1490 string.
1491
1492         char*   SvPVX(SV* sv)
1493
1494 =item SvPV_force
1495
1496 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
1497 force if you are going to update the SvPVX directly.
1498
1499         char*   SvPV_force(SV* sv, STRLEN len)
1500
1501 =item SvPV_nolen
1502
1503 Returns a pointer to the string in the SV, or a stringified form of the SV
1504 if the SV does not contain a string.  Handles 'get' magic.
1505
1506         char*   SvPV_nolen(SV* sv)
1507
1508 =item SvREFCNT
1509
1510 Returns the value of the object's reference count.
1511
1512         U32     SvREFCNT(SV* sv)
1513
1514 =item SvREFCNT_dec
1515
1516 Decrements the reference count of the given SV.
1517
1518         void    SvREFCNT_dec(SV* sv)
1519
1520 =item SvREFCNT_inc
1521
1522 Increments the reference count of the given SV.
1523
1524         SV*     SvREFCNT_inc(SV* sv)
1525
1526 =item SvROK
1527
1528 Tests if the SV is an RV.
1529
1530         bool    SvROK(SV* sv)
1531
1532 =item SvROK_off
1533
1534 Unsets the RV status of an SV.
1535
1536         void    SvROK_off(SV* sv)
1537
1538 =item SvROK_on
1539
1540 Tells an SV that it is an RV.
1541
1542         void    SvROK_on(SV* sv)
1543
1544 =item SvRV
1545
1546 Dereferences an RV to return the SV.
1547
1548         SV*     SvRV(SV* sv)
1549
1550 =item SvSETMAGIC
1551
1552 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
1553 argument more than once.
1554
1555         void    SvSETMAGIC(SV* sv)
1556
1557 =item SvSetSV
1558
1559 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
1560 more than once.
1561
1562         void    SvSetSV(SV* dsb, SV* ssv)
1563
1564 =item SvSetSV_nosteal
1565
1566 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1567 ssv. May evaluate arguments more than once.
1568
1569         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
1570
1571 =item SvSTASH
1572
1573 Returns the stash of the SV.
1574
1575         HV*     SvSTASH(SV* sv)
1576
1577 =item SvTAINT
1578
1579 Taints an SV if tainting is enabled
1580
1581         void    SvTAINT(SV* sv)
1582
1583 =item SvTAINTED
1584
1585 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
1586 not.
1587
1588         bool    SvTAINTED(SV* sv)
1589
1590 =item SvTAINTED_off
1591
1592 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
1593 some of Perl's fundamental security features. XS module authors should not
1594 use this function unless they fully understand all the implications of
1595 unconditionally untainting the value. Untainting should be done in the
1596 standard perl fashion, via a carefully crafted regexp, rather than directly
1597 untainting variables.
1598
1599         void    SvTAINTED_off(SV* sv)
1600
1601 =item SvTAINTED_on
1602
1603 Marks an SV as tainted.
1604
1605         void    SvTAINTED_on(SV* sv)
1606
1607 =item SvTRUE
1608
1609 Returns a boolean indicating whether Perl would evaluate the SV as true or
1610 false, defined or undefined.  Does not handle 'get' magic.
1611
1612         bool    SvTRUE(SV* sv)
1613
1614 =item SvTYPE
1615
1616 Returns the type of the SV.  See C<svtype>.
1617
1618         svtype  SvTYPE(SV* sv)
1619
1620 =item svtype
1621
1622 An enum of flags for Perl types.  These are found in the file B<sv.h>
1623 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
1624
1625 =item SVt_IV
1626
1627 Integer type flag for scalars.  See C<svtype>.
1628
1629 =item SVt_NV
1630
1631 Double type flag for scalars.  See C<svtype>.
1632
1633 =item SVt_PV
1634
1635 Pointer type flag for scalars.  See C<svtype>.
1636
1637 =item SVt_PVAV
1638
1639 Type flag for arrays.  See C<svtype>.
1640
1641 =item SVt_PVCV
1642
1643 Type flag for code refs.  See C<svtype>.
1644
1645 =item SVt_PVHV
1646
1647 Type flag for hashes.  See C<svtype>.
1648
1649 =item SVt_PVMG
1650
1651 Type flag for blessed scalars.  See C<svtype>.
1652
1653 =item SvUNLOCK
1654
1655 Release the internal mutex for an SV.
1656
1657         void    SvUNLOCK(SV* sv)
1658
1659 =item SvUPGRADE
1660
1661 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
1662 perform the upgrade if necessary.  See C<svtype>.
1663
1664         void    SvUPGRADE(SV* sv, svtype type)
1665
1666 =item SvUV
1667
1668 Coerces the given SV to an unsigned integer and returns it.
1669
1670         UV      SvUV(SV* sv)
1671
1672 =item SvUVX
1673
1674 Returns the unsigned integer which is stored in the SV, assuming SvIOK is
1675 true.
1676
1677         UV      SvUVX(SV* sv)
1678
1679 =item sv_2mortal
1680
1681 Marks an SV as mortal.  The SV will be destroyed when the current context
1682 ends.
1683
1684         SV*     sv_2mortal(SV* sv)
1685
1686 =item sv_bless
1687
1688 Blesses an SV into a specified package.  The SV must be an RV.  The package
1689 must be designated by its stash (see C<gv_stashpv()>).  The reference count
1690 of the SV is unaffected.
1691
1692         SV*     sv_bless(SV* sv, HV* stash)
1693
1694 =item sv_catpv
1695
1696 Concatenates the string onto the end of the string which is in the SV.
1697 Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
1698
1699         void    sv_catpv(SV* sv, const char* ptr)
1700
1701 =item sv_catpvf
1702
1703 Processes its arguments like C<sprintf> and appends the formatted output
1704 to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
1705 typically be called after calling this function to handle 'set' magic.
1706
1707         void    sv_catpvf(SV* sv, const char* pat, ...)
1708
1709 =item sv_catpvf_mg
1710
1711 Like C<sv_catpvf>, but also handles 'set' magic.
1712
1713         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
1714
1715 =item sv_catpvn
1716
1717 Concatenates the string onto the end of the string which is in the SV.  The
1718 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
1719 'set' magic.  See C<sv_catpvn_mg>.
1720
1721         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
1722
1723 =item sv_catpvn_mg
1724
1725 Like C<sv_catpvn>, but also handles 'set' magic.
1726
1727         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
1728
1729 =item sv_catpv_mg
1730
1731 Like C<sv_catpv>, but also handles 'set' magic.
1732
1733         void    sv_catpv_mg(SV *sv, const char *ptr)
1734
1735 =item sv_catsv
1736
1737 Concatenates the string from SV C<ssv> onto the end of the string in SV
1738 C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
1739
1740         void    sv_catsv(SV* dsv, SV* ssv)
1741
1742 =item sv_catsv_mg
1743
1744 Like C<sv_catsv>, but also handles 'set' magic.
1745
1746         void    sv_catsv_mg(SV *dstr, SV *sstr)
1747
1748 =item sv_chop
1749
1750 Efficient removal of characters from the beginning of the string buffer.
1751 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
1752 the string buffer.  The C<ptr> becomes the first character of the adjusted
1753 string.
1754
1755         void    sv_chop(SV* sv, char* ptr)
1756
1757 =item sv_cmp
1758
1759 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
1760 string in C<sv1> is less than, equal to, or greater than the string in
1761 C<sv2>.
1762
1763         I32     sv_cmp(SV* sv1, SV* sv2)
1764
1765 =item sv_dec
1766
1767 Auto-decrement of the value in the SV.
1768
1769         void    sv_dec(SV* sv)
1770
1771 =item sv_derived_from
1772
1773 Returns a boolean indicating whether the SV is derived from the specified
1774 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
1775 for class names as well as for objects.
1776
1777         bool    sv_derived_from(SV* sv, const char* name)
1778
1779 =item sv_eq
1780
1781 Returns a boolean indicating whether the strings in the two SVs are
1782 identical.
1783
1784         I32     sv_eq(SV* sv1, SV* sv2)
1785
1786 =item sv_grow
1787
1788 Expands the character buffer in the SV.  This will use C<sv_unref> and will
1789 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
1790 Use C<SvGROW>.
1791
1792         char*   sv_grow(SV* sv, STRLEN newlen)
1793
1794 =item sv_inc
1795
1796 Auto-increment of the value in the SV.
1797
1798         void    sv_inc(SV* sv)
1799
1800 =item sv_insert
1801
1802 Inserts a string at the specified offset/length within the SV. Similar to
1803 the Perl substr() function.
1804
1805         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
1806
1807 =item sv_isa
1808
1809 Returns a boolean indicating whether the SV is blessed into the specified
1810 class.  This does not check for subtypes; use C<sv_derived_from> to verify
1811 an inheritance relationship.
1812
1813         int     sv_isa(SV* sv, const char* name)
1814
1815 =item sv_isobject
1816
1817 Returns a boolean indicating whether the SV is an RV pointing to a blessed
1818 object.  If the SV is not an RV, or if the object is not blessed, then this
1819 will return false.
1820
1821         int     sv_isobject(SV* sv)
1822
1823 =item sv_len
1824
1825 Returns the length of the string in the SV.  See also C<SvCUR>.
1826
1827         STRLEN  sv_len(SV* sv)
1828
1829 =item sv_magic
1830
1831 Adds magic to an SV.
1832
1833         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
1834
1835 =item sv_mortalcopy
1836
1837 Creates a new SV which is a copy of the original SV.  The new SV is marked
1838 as mortal.
1839
1840         SV*     sv_mortalcopy(SV* oldsv)
1841
1842 =item sv_newmortal
1843
1844 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
1845
1846         SV*     sv_newmortal()
1847
1848 =item sv_setiv
1849
1850 Copies an integer into the given SV.  Does not handle 'set' magic.  See
1851 C<sv_setiv_mg>.
1852
1853         void    sv_setiv(SV* sv, IV num)
1854
1855 =item sv_setiv_mg
1856
1857 Like C<sv_setiv>, but also handles 'set' magic.
1858
1859         void    sv_setiv_mg(SV *sv, IV i)
1860
1861 =item sv_setnv
1862
1863 Copies a double into the given SV.  Does not handle 'set' magic.  See
1864 C<sv_setnv_mg>.
1865
1866         void    sv_setnv(SV* sv, NV num)
1867
1868 =item sv_setnv_mg
1869
1870 Like C<sv_setnv>, but also handles 'set' magic.
1871
1872         void    sv_setnv_mg(SV *sv, NV num)
1873
1874 =item sv_setpv
1875
1876 Copies a string into an SV.  The string must be null-terminated.  Does not
1877 handle 'set' magic.  See C<sv_setpv_mg>.
1878
1879         void    sv_setpv(SV* sv, const char* ptr)
1880
1881 =item sv_setpvf
1882
1883 Processes its arguments like C<sprintf> and sets an SV to the formatted
1884 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
1885
1886         void    sv_setpvf(SV* sv, const char* pat, ...)
1887
1888 =item sv_setpvf_mg
1889
1890 Like C<sv_setpvf>, but also handles 'set' magic.
1891
1892         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
1893
1894 =item sv_setpviv
1895
1896 Copies an integer into the given SV, also updating its string value.
1897 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
1898
1899         void    sv_setpviv(SV* sv, IV num)
1900
1901 =item sv_setpviv_mg
1902
1903 Like C<sv_setpviv>, but also handles 'set' magic.
1904
1905         void    sv_setpviv_mg(SV *sv, IV iv)
1906
1907 =item sv_setpvn
1908
1909 Copies a string into an SV.  The C<len> parameter indicates the number of
1910 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
1911
1912         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
1913
1914 =item sv_setpvn_mg
1915
1916 Like C<sv_setpvn>, but also handles 'set' magic.
1917
1918         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
1919
1920 =item sv_setpv_mg
1921
1922 Like C<sv_setpv>, but also handles 'set' magic.
1923
1924         void    sv_setpv_mg(SV *sv, const char *ptr)
1925
1926 =item sv_setref_iv
1927
1928 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
1929 argument will be upgraded to an RV.  That RV will be modified to point to
1930 the new SV.  The C<classname> argument indicates the package for the
1931 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1932 will be returned and will have a reference count of 1.
1933
1934         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
1935
1936 =item sv_setref_nv
1937
1938 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
1939 argument will be upgraded to an RV.  That RV will be modified to point to
1940 the new SV.  The C<classname> argument indicates the package for the
1941 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1942 will be returned and will have a reference count of 1.
1943
1944         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
1945
1946 =item sv_setref_pv
1947
1948 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
1949 argument will be upgraded to an RV.  That RV will be modified to point to
1950 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
1951 into the SV.  The C<classname> argument indicates the package for the
1952 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
1953 will be returned and will have a reference count of 1.
1954
1955 Do not use with other Perl types such as HV, AV, SV, CV, because those
1956 objects will become corrupted by the pointer copy process.
1957
1958 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
1959
1960         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
1961
1962 =item sv_setref_pvn
1963
1964 Copies a string into a new SV, optionally blessing the SV.  The length of the
1965 string must be specified with C<n>.  The C<rv> argument will be upgraded to
1966 an RV.  That RV will be modified to point to the new SV.  The C<classname>
1967 argument indicates the package for the blessing.  Set C<classname> to
1968 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
1969 a reference count of 1.
1970
1971 Note that C<sv_setref_pv> copies the pointer while this copies the string.
1972
1973         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
1974
1975 =item sv_setsv
1976
1977 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
1978 The source SV may be destroyed if it is mortal.  Does not handle 'set'
1979 magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
1980 C<sv_setsv_mg>.
1981
1982         void    sv_setsv(SV* dsv, SV* ssv)
1983
1984 =item sv_setsv_mg
1985
1986 Like C<sv_setsv>, but also handles 'set' magic.
1987
1988         void    sv_setsv_mg(SV *dstr, SV *sstr)
1989
1990 =item sv_setuv
1991
1992 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
1993 See C<sv_setuv_mg>.
1994
1995         void    sv_setuv(SV* sv, UV num)
1996
1997 =item sv_setuv_mg
1998
1999 Like C<sv_setuv>, but also handles 'set' magic.
2000
2001         void    sv_setuv_mg(SV *sv, UV u)
2002
2003 =item sv_unref
2004
2005 Unsets the RV status of the SV, and decrements the reference count of
2006 whatever was being referenced by the RV.  This can almost be thought of
2007 as a reversal of C<newSVrv>.  See C<SvROK_off>.
2008
2009         void    sv_unref(SV* sv)
2010
2011 =item sv_upgrade
2012
2013 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
2014 C<svtype>.
2015
2016         bool    sv_upgrade(SV* sv, U32 mt)
2017
2018 =item sv_usepvn
2019
2020 Tells an SV to use C<ptr> to find its string value.  Normally the string is
2021 stored inside the SV but sv_usepvn allows the SV to use an outside string.
2022 The C<ptr> should point to memory that was allocated by C<malloc>.  The
2023 string length, C<len>, must be supplied.  This function will realloc the
2024 memory pointed to by C<ptr>, so that pointer should not be freed or used by
2025 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
2026 See C<sv_usepvn_mg>.
2027
2028         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
2029
2030 =item sv_usepvn_mg
2031
2032 Like C<sv_usepvn>, but also handles 'set' magic.
2033
2034         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
2035
2036 =item sv_vcatpvfn
2037
2038 Processes its arguments like C<vsprintf> and appends the formatted output
2039 to an SV.  Uses an array of SVs if the C style variable argument list is
2040 missing (NULL).  When running with taint checks enabled, indicates via
2041 C<maybe_tainted> if results are untrustworthy (often due to the use of
2042 locales).
2043
2044         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2045
2046 =item sv_vsetpvfn
2047
2048 Works like C<vcatpvfn> but copies the text into the SV instead of
2049 appending it.
2050
2051         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2052
2053 =item THIS
2054
2055 Variable which is setup by C<xsubpp> to designate the object in a C++
2056 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and
2057 L<perlxs/"Using XS With C++">.
2058
2059         (whatever)      THIS
2060
2061 =item toLOWER
2062
2063 Converts the specified character to lowercase.
2064
2065         char    toLOWER(char ch)
2066
2067 =item toUPPER
2068
2069 Converts the specified character to uppercase.
2070
2071         char    toUPPER(char ch)
2072
2073 =item warn
2074
2075 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
2076 function the same way you use the C C<printf> function.  See
2077 C<croak>.
2078
2079         void    warn(const char* pat, ...)
2080
2081 =item XPUSHi
2082
2083 Push an integer onto the stack, extending the stack if necessary.  Handles
2084 'set' magic. See C<PUSHi>.
2085
2086         void    XPUSHi(IV iv)
2087
2088 =item XPUSHn
2089
2090 Push a double onto the stack, extending the stack if necessary.  Handles
2091 'set' magic.  See C<PUSHn>.
2092
2093         void    XPUSHn(NV nv)
2094
2095 =item XPUSHp
2096
2097 Push a string onto the stack, extending the stack if necessary.  The C<len>
2098 indicates the length of the string.  Handles 'set' magic.  See
2099 C<PUSHp>.
2100
2101         void    XPUSHp(char* str, STRLEN len)
2102
2103 =item XPUSHs
2104
2105 Push an SV onto the stack, extending the stack if necessary.  Does not
2106 handle 'set' magic.  See C<PUSHs>.
2107
2108         void    XPUSHs(SV* sv)
2109
2110 =item XPUSHu
2111
2112 Push an unsigned integer onto the stack, extending the stack if necessary.
2113 See C<PUSHu>.
2114
2115         void    XPUSHu(UV uv)
2116
2117 =item XS
2118
2119 Macro to declare an XSUB and its C parameter list.  This is handled by
2120 C<xsubpp>.
2121
2122 =item XSRETURN
2123
2124 Return from XSUB, indicating number of items on the stack.  This is usually
2125 handled by C<xsubpp>.
2126
2127         void    XSRETURN(int nitems)
2128
2129 =item XSRETURN_EMPTY
2130
2131 Return an empty list from an XSUB immediately.
2132
2133                 XSRETURN_EMPTY;
2134
2135 =item XSRETURN_IV
2136
2137 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
2138
2139         void    XSRETURN_IV(IV iv)
2140
2141 =item XSRETURN_NO
2142
2143 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
2144
2145                 XSRETURN_NO;
2146
2147 =item XSRETURN_NV
2148
2149 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
2150
2151         void    XSRETURN_NV(NV nv)
2152
2153 =item XSRETURN_PV
2154
2155 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
2156
2157         void    XSRETURN_PV(char* str)
2158
2159 =item XSRETURN_UNDEF
2160
2161 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
2162
2163                 XSRETURN_UNDEF;
2164
2165 =item XSRETURN_YES
2166
2167 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
2168
2169                 XSRETURN_YES;
2170
2171 =item XST_mIV
2172
2173 Place an integer into the specified position C<pos> on the stack.  The
2174 value is stored in a new mortal SV.
2175
2176         void    XST_mIV(int pos, IV iv)
2177
2178 =item XST_mNO
2179
2180 Place C<&PL_sv_no> into the specified position C<pos> on the
2181 stack.
2182
2183         void    XST_mNO(int pos)
2184
2185 =item XST_mNV
2186
2187 Place a double into the specified position C<pos> on the stack.  The value
2188 is stored in a new mortal SV.
2189
2190         void    XST_mNV(int pos, NV nv)
2191
2192 =item XST_mPV
2193
2194 Place a copy of a string into the specified position C<pos> on the stack.
2195 The value is stored in a new mortal SV.
2196
2197         void    XST_mPV(int pos, char* str)
2198
2199 =item XST_mUNDEF
2200
2201 Place C<&PL_sv_undef> into the specified position C<pos> on the
2202 stack.
2203
2204         void    XST_mUNDEF(int pos)
2205
2206 =item XST_mYES
2207
2208 Place C<&PL_sv_yes> into the specified position C<pos> on the
2209 stack.
2210
2211         void    XST_mYES(int pos)
2212
2213 =item XS_VERSION
2214
2215 The version identifier for an XS module.  This is usually
2216 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
2217
2218 =item XS_VERSION_BOOTCHECK
2219
2220 Macro to verify that a PM module's $VERSION variable matches the XS
2221 module's C<XS_VERSION> variable.  This is usually handled automatically by
2222 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
2223
2224                 XS_VERSION_BOOTCHECK;
2225
2226 =item Zero
2227
2228 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2229 destination, C<nitems> is the number of items, and C<type> is the type.
2230
2231         void    Zero(void* dest, int nitems, type)
2232
2233 =back
2234
2235 =head1 AUTHORS
2236
2237 Until May 1997, this document was maintained by Jeff Okamoto
2238 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
2239
2240 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2241 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2242 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
2243 Stephen McCamant, and Gurusamy Sarathy.
2244
2245 API Listing originally by Dean Roehrich <roehrich@cray.com>.
2246
2247 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
2248
2249 =head1 SEE ALSO
2250
2251 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
2252