[Summary view] [Print] [Text view]

   1  -*- buffer-read-only: t -*-
   2  
   3  !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
   4  This file is built by autodoc.pl extracting documentation from the C source
   5  files.
   6  
   7  =head1 NAME
   8  
   9  perlapi - autogenerated documentation for the perl public API
  10  
  11  =head1 DESCRIPTION
  12  X<Perl API> X<API> X<api>
  13  
  14  This file contains the documentation of the perl public API generated by
  15  embed.pl, specifically a listing of functions, macros, flags, and variables
  16  that may be used by extension writers.  The interfaces of any functions that
  17  are not listed here are subject to change without notice.  For this reason,
  18  blindly using functions listed in proto.h is to be avoided when writing
  19  extensions.
  20  
  21  Note that all Perl API global variables must be referenced with the C<PL_>
  22  prefix.  Some macros are provided for compatibility with the older,
  23  unadorned names, but this support may be disabled in a future release.
  24  
  25  The listing is alphabetical, case insensitive.
  26  
  27  
  28  =head1 "Gimme" Values
  29  
  30  =over 8
  31  
  32  =item GIMME
  33  X<GIMME>
  34  
  35  A backward-compatible version of C<GIMME_V> which can only return
  36  C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
  37  Deprecated.  Use C<GIMME_V> instead.
  38  
  39      U32    GIMME
  40  
  41  =for hackers
  42  Found in file op.h
  43  
  44  =item GIMME_V
  45  X<GIMME_V>
  46  
  47  The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
  48  C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
  49  respectively.
  50  
  51      U32    GIMME_V
  52  
  53  =for hackers
  54  Found in file op.h
  55  
  56  =item G_ARRAY
  57  X<G_ARRAY>
  58  
  59  Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
  60  L<perlcall>.
  61  
  62  =for hackers
  63  Found in file cop.h
  64  
  65  =item G_DISCARD
  66  X<G_DISCARD>
  67  
  68  Indicates that arguments returned from a callback should be discarded.  See
  69  L<perlcall>.
  70  
  71  =for hackers
  72  Found in file cop.h
  73  
  74  =item G_EVAL
  75  X<G_EVAL>
  76  
  77  Used to force a Perl C<eval> wrapper around a callback.  See
  78  L<perlcall>.
  79  
  80  =for hackers
  81  Found in file cop.h
  82  
  83  =item G_NOARGS
  84  X<G_NOARGS>
  85  
  86  Indicates that no arguments are being sent to a callback.  See
  87  L<perlcall>.
  88  
  89  =for hackers
  90  Found in file cop.h
  91  
  92  =item G_SCALAR
  93  X<G_SCALAR>
  94  
  95  Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
  96  L<perlcall>.
  97  
  98  =for hackers
  99  Found in file cop.h
 100  
 101  =item G_VOID
 102  X<G_VOID>
 103  
 104  Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
 105  
 106  =for hackers
 107  Found in file cop.h
 108  
 109  
 110  =back
 111  
 112  =head1 Array Manipulation Functions
 113  
 114  =over 8
 115  
 116  =item AvFILL
 117  X<AvFILL>
 118  
 119  Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
 120  
 121      int    AvFILL(AV* av)
 122  
 123  =for hackers
 124  Found in file av.h
 125  
 126  =item av_clear
 127  X<av_clear>
 128  
 129  Clears an array, making it empty.  Does not free the memory used by the
 130  array itself.
 131  
 132      void    av_clear(AV* ar)
 133  
 134  =for hackers
 135  Found in file av.c
 136  
 137  =item av_create_and_push
 138  X<av_create_and_push>
 139  
 140  Push an SV onto the end of the array, creating the array if necessary.
 141  A small internal helper function to remove a commonly duplicated idiom.
 142  
 143  NOTE: this function is experimental and may change or be
 144  removed without notice.
 145  
 146      void    av_create_and_push(AV **const avp, SV *const val)
 147  
 148  =for hackers
 149  Found in file av.c
 150  
 151  =item av_create_and_unshift_one
 152  X<av_create_and_unshift_one>
 153  
 154  Unshifts an SV onto the beginning of the array, creating the array if
 155  necessary.
 156  A small internal helper function to remove a commonly duplicated idiom.
 157  
 158  NOTE: this function is experimental and may change or be
 159  removed without notice.
 160  
 161      SV**    av_create_and_unshift_one(AV **const avp, SV *const val)
 162  
 163  =for hackers
 164  Found in file av.c
 165  
 166  =item av_delete
 167  X<av_delete>
 168  
 169  Deletes the element indexed by C<key> from the array.  Returns the
 170  deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
 171  and null is returned.
 172  
 173      SV*    av_delete(AV* ar, I32 key, I32 flags)
 174  
 175  =for hackers
 176  Found in file av.c
 177  
 178  =item av_exists
 179  X<av_exists>
 180  
 181  Returns true if the element indexed by C<key> has been initialized.
 182  
 183  This relies on the fact that uninitialized array elements are set to
 184  C<&PL_sv_undef>.
 185  
 186      bool    av_exists(AV* ar, I32 key)
 187  
 188  =for hackers
 189  Found in file av.c
 190  
 191  =item av_extend
 192  X<av_extend>
 193  
 194  Pre-extend an array.  The C<key> is the index to which the array should be
 195  extended.
 196  
 197      void    av_extend(AV* ar, I32 key)
 198  
 199  =for hackers
 200  Found in file av.c
 201  
 202  =item av_fetch
 203  X<av_fetch>
 204  
 205  Returns the SV at the specified index in the array.  The C<key> is the
 206  index.  If C<lval> is set then the fetch will be part of a store.  Check
 207  that the return value is non-null before dereferencing it to a C<SV*>.
 208  
 209  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
 210  more information on how to use this function on tied arrays. 
 211  
 212      SV**    av_fetch(AV* ar, I32 key, I32 lval)
 213  
 214  =for hackers
 215  Found in file av.c
 216  
 217  =item av_fill
 218  X<av_fill>
 219  
 220  Set the highest index in the array to the given number, equivalent to
 221  Perl's C<$#array = $fill;>.
 222  
 223  The number of elements in the an array will be C<fill + 1> after
 224  av_fill() returns.  If the array was previously shorter then the
 225  additional elements appended are set to C<PL_sv_undef>.  If the array
 226  was longer, then the excess elements are freed.  C<av_fill(av, -1)> is
 227  the same as C<av_clear(av)>.
 228  
 229      void    av_fill(AV* ar, I32 fill)
 230  
 231  =for hackers
 232  Found in file av.c
 233  
 234  =item av_len
 235  X<av_len>
 236  
 237  Returns the highest index in the array.  The number of elements in the
 238  array is C<av_len(av) + 1>.  Returns -1 if the array is empty.
 239  
 240      I32    av_len(const AV* ar)
 241  
 242  =for hackers
 243  Found in file av.c
 244  
 245  =item av_make
 246  X<av_make>
 247  
 248  Creates a new AV and populates it with a list of SVs.  The SVs are copied
 249  into the array, so they may be freed after the call to av_make.  The new AV
 250  will have a reference count of 1.
 251  
 252      AV*    av_make(I32 size, SV** svp)
 253  
 254  =for hackers
 255  Found in file av.c
 256  
 257  =item av_pop
 258  X<av_pop>
 259  
 260  Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
 261  is empty.
 262  
 263      SV*    av_pop(AV* ar)
 264  
 265  =for hackers
 266  Found in file av.c
 267  
 268  =item av_push
 269  X<av_push>
 270  
 271  Pushes an SV onto the end of the array.  The array will grow automatically
 272  to accommodate the addition.
 273  
 274      void    av_push(AV* ar, SV* val)
 275  
 276  =for hackers
 277  Found in file av.c
 278  
 279  =item av_shift
 280  X<av_shift>
 281  
 282  Shifts an SV off the beginning of the array.
 283  
 284      SV*    av_shift(AV* ar)
 285  
 286  =for hackers
 287  Found in file av.c
 288  
 289  =item av_store
 290  X<av_store>
 291  
 292  Stores an SV in an array.  The array index is specified as C<key>.  The
 293  return value will be NULL if the operation failed or if the value did not
 294  need to be actually stored within the array (as in the case of tied
 295  arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
 296  that the caller is responsible for suitably incrementing the reference
 297  count of C<val> before the call, and decrementing it if the function
 298  returned NULL.
 299  
 300  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
 301  more information on how to use this function on tied arrays.
 302  
 303      SV**    av_store(AV* ar, I32 key, SV* val)
 304  
 305  =for hackers
 306  Found in file av.c
 307  
 308  =item av_undef
 309  X<av_undef>
 310  
 311  Undefines the array.  Frees the memory used by the array itself.
 312  
 313      void    av_undef(AV* ar)
 314  
 315  =for hackers
 316  Found in file av.c
 317  
 318  =item av_unshift
 319  X<av_unshift>
 320  
 321  Unshift the given number of C<undef> values onto the beginning of the
 322  array.  The array will grow automatically to accommodate the addition.  You
 323  must then use C<av_store> to assign values to these new elements.
 324  
 325      void    av_unshift(AV* ar, I32 num)
 326  
 327  =for hackers
 328  Found in file av.c
 329  
 330  =item get_av
 331  X<get_av>
 332  
 333  Returns the AV of the specified Perl array.  If C<create> is set and the
 334  Perl variable does not exist then it will be created.  If C<create> is not
 335  set and the variable does not exist then NULL is returned.
 336  
 337  NOTE: the perl_ form of this function is deprecated.
 338  
 339      AV*    get_av(const char* name, I32 create)
 340  
 341  =for hackers
 342  Found in file perl.c
 343  
 344  =item newAV
 345  X<newAV>
 346  
 347  Creates a new AV.  The reference count is set to 1.
 348  
 349      AV*    newAV()
 350  
 351  =for hackers
 352  Found in file av.c
 353  
 354  =item sortsv
 355  X<sortsv>
 356  
 357  Sort an array. Here is an example:
 358  
 359      sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
 360  
 361  Currently this always uses mergesort. See sortsv_flags for a more
 362  flexible routine.
 363  
 364      void    sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
 365  
 366  =for hackers
 367  Found in file pp_sort.c
 368  
 369  =item sortsv_flags
 370  X<sortsv_flags>
 371  
 372  Sort an array, with various options.
 373  
 374      void    sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
 375  
 376  =for hackers
 377  Found in file pp_sort.c
 378  
 379  
 380  =back
 381  
 382  =head1 Callback Functions
 383  
 384  =over 8
 385  
 386  =item call_argv
 387  X<call_argv>
 388  
 389  Performs a callback to the specified Perl sub.  See L<perlcall>.
 390  
 391  NOTE: the perl_ form of this function is deprecated.
 392  
 393      I32    call_argv(const char* sub_name, I32 flags, char** argv)
 394  
 395  =for hackers
 396  Found in file perl.c
 397  
 398  =item call_method
 399  X<call_method>
 400  
 401  Performs a callback to the specified Perl method.  The blessed object must
 402  be on the stack.  See L<perlcall>.
 403  
 404  NOTE: the perl_ form of this function is deprecated.
 405  
 406      I32    call_method(const char* methname, I32 flags)
 407  
 408  =for hackers
 409  Found in file perl.c
 410  
 411  =item call_pv
 412  X<call_pv>
 413  
 414  Performs a callback to the specified Perl sub.  See L<perlcall>.
 415  
 416  NOTE: the perl_ form of this function is deprecated.
 417  
 418      I32    call_pv(const char* sub_name, I32 flags)
 419  
 420  =for hackers
 421  Found in file perl.c
 422  
 423  =item call_sv
 424  X<call_sv>
 425  
 426  Performs a callback to the Perl sub whose name is in the SV.  See
 427  L<perlcall>.
 428  
 429  NOTE: the perl_ form of this function is deprecated.
 430  
 431      I32    call_sv(SV* sv, I32 flags)
 432  
 433  =for hackers
 434  Found in file perl.c
 435  
 436  =item ENTER
 437  X<ENTER>
 438  
 439  Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
 440  
 441          ENTER;
 442  
 443  =for hackers
 444  Found in file scope.h
 445  
 446  =item eval_pv
 447  X<eval_pv>
 448  
 449  Tells Perl to C<eval> the given string and return an SV* result.
 450  
 451  NOTE: the perl_ form of this function is deprecated.
 452  
 453      SV*    eval_pv(const char* p, I32 croak_on_error)
 454  
 455  =for hackers
 456  Found in file perl.c
 457  
 458  =item eval_sv
 459  X<eval_sv>
 460  
 461  Tells Perl to C<eval> the string in the SV.
 462  
 463  NOTE: the perl_ form of this function is deprecated.
 464  
 465      I32    eval_sv(SV* sv, I32 flags)
 466  
 467  =for hackers
 468  Found in file perl.c
 469  
 470  =item FREETMPS
 471  X<FREETMPS>
 472  
 473  Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
 474  L<perlcall>.
 475  
 476          FREETMPS;
 477  
 478  =for hackers
 479  Found in file scope.h
 480  
 481  =item LEAVE
 482  X<LEAVE>
 483  
 484  Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
 485  
 486          LEAVE;
 487  
 488  =for hackers
 489  Found in file scope.h
 490  
 491  =item SAVETMPS
 492  X<SAVETMPS>
 493  
 494  Opening bracket for temporaries on a callback.  See C<FREETMPS> and
 495  L<perlcall>.
 496  
 497          SAVETMPS;
 498  
 499  =for hackers
 500  Found in file scope.h
 501  
 502  
 503  =back
 504  
 505  =head1 Character classes
 506  
 507  =over 8
 508  
 509  =item isALNUM
 510  X<isALNUM>
 511  
 512  Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
 513  character (including underscore) or digit.
 514  
 515      bool    isALNUM(char ch)
 516  
 517  =for hackers
 518  Found in file handy.h
 519  
 520  =item isALPHA
 521  X<isALPHA>
 522  
 523  Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
 524  character.
 525  
 526      bool    isALPHA(char ch)
 527  
 528  =for hackers
 529  Found in file handy.h
 530  
 531  =item isDIGIT
 532  X<isDIGIT>
 533  
 534  Returns a boolean indicating whether the C C<char> is an ASCII
 535  digit.
 536  
 537      bool    isDIGIT(char ch)
 538  
 539  =for hackers
 540  Found in file handy.h
 541  
 542  =item isLOWER
 543  X<isLOWER>
 544  
 545  Returns a boolean indicating whether the C C<char> is a lowercase
 546  character.
 547  
 548      bool    isLOWER(char ch)
 549  
 550  =for hackers
 551  Found in file handy.h
 552  
 553  =item isSPACE
 554  X<isSPACE>
 555  
 556  Returns a boolean indicating whether the C C<char> is whitespace.
 557  
 558      bool    isSPACE(char ch)
 559  
 560  =for hackers
 561  Found in file handy.h
 562  
 563  =item isUPPER
 564  X<isUPPER>
 565  
 566  Returns a boolean indicating whether the C C<char> is an uppercase
 567  character.
 568  
 569      bool    isUPPER(char ch)
 570  
 571  =for hackers
 572  Found in file handy.h
 573  
 574  =item toLOWER
 575  X<toLOWER>
 576  
 577  Converts the specified character to lowercase.
 578  
 579      char    toLOWER(char ch)
 580  
 581  =for hackers
 582  Found in file handy.h
 583  
 584  =item toUPPER
 585  X<toUPPER>
 586  
 587  Converts the specified character to uppercase.
 588  
 589      char    toUPPER(char ch)
 590  
 591  =for hackers
 592  Found in file handy.h
 593  
 594  
 595  =back
 596  
 597  =head1 Cloning an interpreter
 598  
 599  =over 8
 600  
 601  =item perl_clone
 602  X<perl_clone>
 603  
 604  Create and return a new interpreter by cloning the current one.
 605  
 606  perl_clone takes these flags as parameters:
 607  
 608  CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
 609  without it we only clone the data and zero the stacks,
 610  with it we copy the stacks and the new perl interpreter is
 611  ready to run at the exact same point as the previous one.
 612  The pseudo-fork code uses COPY_STACKS while the
 613  threads->create doesn't.
 614  
 615  CLONEf_KEEP_PTR_TABLE
 616  perl_clone keeps a ptr_table with the pointer of the old
 617  variable as a key and the new variable as a value,
 618  this allows it to check if something has been cloned and not
 619  clone it again but rather just use the value and increase the
 620  refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
 621  the ptr_table using the function
 622  C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
 623  reason to keep it around is if you want to dup some of your own
 624  variable who are outside the graph perl scans, example of this
 625  code is in threads.xs create
 626  
 627  CLONEf_CLONE_HOST
 628  This is a win32 thing, it is ignored on unix, it tells perls
 629  win32host code (which is c++) to clone itself, this is needed on
 630  win32 if you want to run two threads at the same time,
 631  if you just want to do some stuff in a separate perl interpreter
 632  and then throw it away and return to the original one,
 633  you don't need to do anything.
 634  
 635      PerlInterpreter*    perl_clone(PerlInterpreter* interp, UV flags)
 636  
 637  =for hackers
 638  Found in file sv.c
 639  
 640  
 641  =back
 642  
 643  =head1 CV Manipulation Functions
 644  
 645  =over 8
 646  
 647  =item CvSTASH
 648  X<CvSTASH>
 649  
 650  Returns the stash of the CV.
 651  
 652      HV*    CvSTASH(CV* cv)
 653  
 654  =for hackers
 655  Found in file cv.h
 656  
 657  =item get_cv
 658  X<get_cv>
 659  
 660  Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
 661  
 662  NOTE: the perl_ form of this function is deprecated.
 663  
 664      CV*    get_cv(const char* name, I32 flags)
 665  
 666  =for hackers
 667  Found in file perl.c
 668  
 669  =item get_cvn_flags
 670  X<get_cvn_flags>
 671  
 672  Returns the CV of the specified Perl subroutine.  C<flags> are passed to
 673  C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
 674  exist then it will be declared (which has the same effect as saying
 675  C<sub name;>).  If C<GV_ADD> is not set and the subroutine does not exist
 676  then NULL is returned.
 677  
 678  NOTE: the perl_ form of this function is deprecated.
 679  
 680      CV*    get_cvn_flags(const char* name, STRLEN len, I32 flags)
 681  
 682  =for hackers
 683  Found in file perl.c
 684  
 685  
 686  =back
 687  
 688  =head1 Embedding Functions
 689  
 690  =over 8
 691  
 692  =item cv_undef
 693  X<cv_undef>
 694  
 695  Clear out all the active components of a CV. This can happen either
 696  by an explicit C<undef &foo>, or by the reference count going to zero.
 697  In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
 698  children can still follow the full lexical scope chain.
 699  
 700      void    cv_undef(CV* cv)
 701  
 702  =for hackers
 703  Found in file op.c
 704  
 705  =item load_module
 706  X<load_module>
 707  
 708  Loads the module whose name is pointed to by the string part of name.
 709  Note that the actual module name, not its filename, should be given.
 710  Eg, "Foo::Bar" instead of "Foo/Bar.pm".  flags can be any of
 711  PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
 712  (or 0 for no flags). ver, if specified, provides version semantics
 713  similar to C<use Foo::Bar VERSION>.  The optional trailing SV*
 714  arguments can be used to specify arguments to the module's import()
 715  method, similar to C<use Foo::Bar VERSION LIST>.
 716  
 717      void    load_module(U32 flags, SV* name, SV* ver, ...)
 718  
 719  =for hackers
 720  Found in file op.c
 721  
 722  =item nothreadhook
 723  X<nothreadhook>
 724  
 725  Stub that provides thread hook for perl_destruct when there are
 726  no threads.
 727  
 728      int    nothreadhook()
 729  
 730  =for hackers
 731  Found in file perl.c
 732  
 733  =item perl_alloc
 734  X<perl_alloc>
 735  
 736  Allocates a new Perl interpreter.  See L<perlembed>.
 737  
 738      PerlInterpreter*    perl_alloc()
 739  
 740  =for hackers
 741  Found in file perl.c
 742  
 743  =item perl_construct
 744  X<perl_construct>
 745  
 746  Initializes a new Perl interpreter.  See L<perlembed>.
 747  
 748      void    perl_construct(PerlInterpreter* interp)
 749  
 750  =for hackers
 751  Found in file perl.c
 752  
 753  =item perl_destruct
 754  X<perl_destruct>
 755  
 756  Shuts down a Perl interpreter.  See L<perlembed>.
 757  
 758      int    perl_destruct(PerlInterpreter* interp)
 759  
 760  =for hackers
 761  Found in file perl.c
 762  
 763  =item perl_free
 764  X<perl_free>
 765  
 766  Releases a Perl interpreter.  See L<perlembed>.
 767  
 768      void    perl_free(PerlInterpreter* interp)
 769  
 770  =for hackers
 771  Found in file perl.c
 772  
 773  =item perl_parse
 774  X<perl_parse>
 775  
 776  Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
 777  
 778      int    perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
 779  
 780  =for hackers
 781  Found in file perl.c
 782  
 783  =item perl_run
 784  X<perl_run>
 785  
 786  Tells a Perl interpreter to run.  See L<perlembed>.
 787  
 788      int    perl_run(PerlInterpreter* interp)
 789  
 790  =for hackers
 791  Found in file perl.c
 792  
 793  =item require_pv
 794  X<require_pv>
 795  
 796  Tells Perl to C<require> the file named by the string argument.  It is
 797  analogous to the Perl code C<eval "require '$file'">.  It's even
 798  implemented that way; consider using load_module instead.
 799  
 800  NOTE: the perl_ form of this function is deprecated.
 801  
 802      void    require_pv(const char* pv)
 803  
 804  =for hackers
 805  Found in file perl.c
 806  
 807  
 808  =back
 809  
 810  =head1 Functions in file dump.c
 811  
 812  
 813  =over 8
 814  
 815  =item pv_display
 816  X<pv_display>
 817  
 818    char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
 819                     STRLEN pvlim, U32 flags)
 820  
 821  Similar to
 822  
 823    pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
 824  
 825  except that an additional "\0" will be appended to the string when
 826  len > cur and pv[cur] is "\0".
 827  
 828  Note that the final string may be up to 7 chars longer than pvlim.
 829  
 830      char*    pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
 831  
 832  =for hackers
 833  Found in file dump.c
 834  
 835  =item pv_escape
 836  X<pv_escape>
 837  
 838                 |const STRLEN count|const STRLEN max
 839                 |STRLEN const *escaped, const U32 flags
 840  
 841  Escapes at most the first "count" chars of pv and puts the results into
 842  dsv such that the size of the escaped string will not exceed "max" chars
 843  and will not contain any incomplete escape sequences.
 844  
 845  If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
 846  will also be escaped.
 847  
 848  Normally the SV will be cleared before the escaped string is prepared,
 849  but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
 850  
 851  If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
 852  if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
 853  using C<is_utf8_string()> to determine if it is Unicode.
 854  
 855  If PERL_PV_ESCAPE_ALL is set then all input chars will be output
 856  using C<\x01F1> style escapes, otherwise only chars above 255 will be
 857  escaped using this style, other non printable chars will use octal or
 858  common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
 859  then all chars below 255 will be treated as printable and 
 860  will be output as literals.
 861  
 862  If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
 863  string will be escaped, regardles of max. If the string is utf8 and 
 864  the chars value is >255 then it will be returned as a plain hex 
 865  sequence. Thus the output will either be a single char, 
 866  an octal escape sequence, a special escape like C<\n> or a 3 or 
 867  more digit hex value. 
 868  
 869  If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
 870  not a '\\'. This is because regexes very often contain backslashed
 871  sequences, whereas '%' is not a particularly common character in patterns.
 872  
 873  Returns a pointer to the escaped text as held by dsv.
 874  
 875  NOTE: the perl_ form of this function is deprecated.
 876  
 877      char*    pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
 878  
 879  =for hackers
 880  Found in file dump.c
 881  
 882  =item pv_pretty
 883  X<pv_pretty>
 884  
 885             |const STRLEN count|const STRLEN max\
 886             |const char const *start_color| const char const *end_color\
 887             |const U32 flags
 888  
 889  Converts a string into something presentable, handling escaping via
 890  pv_escape() and supporting quoting and ellipses.
 891  
 892  If the PERL_PV_PRETTY_QUOTE flag is set then the result will be 
 893  double quoted with any double quotes in the string escaped. Otherwise
 894  if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
 895  angle brackets. 
 896             
 897  If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
 898  string were output then an ellipsis C<...> will be appended to the
 899  string. Note that this happens AFTER it has been quoted.
 900             
 901  If start_color is non-null then it will be inserted after the opening
 902  quote (if there is one) but before the escaped text. If end_color
 903  is non-null then it will be inserted after the escaped text but before
 904  any quotes or ellipses.
 905  
 906  Returns a pointer to the prettified text as held by dsv.
 907             
 908  NOTE: the perl_ form of this function is deprecated.
 909  
 910      char*    pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
 911  
 912  =for hackers
 913  Found in file dump.c
 914  
 915  
 916  =back
 917  
 918  =head1 Functions in file mathoms.c
 919  
 920  
 921  =over 8
 922  
 923  =item gv_fetchmethod
 924  X<gv_fetchmethod>
 925  
 926  See L<gv_fetchmethod_autoload>.
 927  
 928      GV*    gv_fetchmethod(HV* stash, const char* name)
 929  
 930  =for hackers
 931  Found in file mathoms.c
 932  
 933  =item pack_cat
 934  X<pack_cat>
 935  
 936  The engine implementing pack() Perl function. Note: parameters next_in_list and
 937  flags are not used. This call should not be used; use packlist instead.
 938  
 939      void    pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
 940  
 941  =for hackers
 942  Found in file mathoms.c
 943  
 944  =item sv_2pvbyte_nolen
 945  X<sv_2pvbyte_nolen>
 946  
 947  Return a pointer to the byte-encoded representation of the SV.
 948  May cause the SV to be downgraded from UTF-8 as a side-effect.
 949  
 950  Usually accessed via the C<SvPVbyte_nolen> macro.
 951  
 952      char*    sv_2pvbyte_nolen(SV* sv)
 953  
 954  =for hackers
 955  Found in file mathoms.c
 956  
 957  =item sv_2pvutf8_nolen
 958  X<sv_2pvutf8_nolen>
 959  
 960  Return a pointer to the UTF-8-encoded representation of the SV.
 961  May cause the SV to be upgraded to UTF-8 as a side-effect.
 962  
 963  Usually accessed via the C<SvPVutf8_nolen> macro.
 964  
 965      char*    sv_2pvutf8_nolen(SV* sv)
 966  
 967  =for hackers
 968  Found in file mathoms.c
 969  
 970  =item sv_2pv_nolen
 971  X<sv_2pv_nolen>
 972  
 973  Like C<sv_2pv()>, but doesn't return the length too. You should usually
 974  use the macro wrapper C<SvPV_nolen(sv)> instead.
 975      char*    sv_2pv_nolen(SV* sv)
 976  
 977  =for hackers
 978  Found in file mathoms.c
 979  
 980  =item sv_catpvn_mg
 981  X<sv_catpvn_mg>
 982  
 983  Like C<sv_catpvn>, but also handles 'set' magic.
 984  
 985      void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
 986  
 987  =for hackers
 988  Found in file mathoms.c
 989  
 990  =item sv_catsv_mg
 991  X<sv_catsv_mg>
 992  
 993  Like C<sv_catsv>, but also handles 'set' magic.
 994  
 995      void    sv_catsv_mg(SV *dstr, SV *sstr)
 996  
 997  =for hackers
 998  Found in file mathoms.c
 999  
1000  =item sv_force_normal
1001  X<sv_force_normal>
1002  
1003  Undo various types of fakery on an SV: if the PV is a shared string, make
1004  a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
1005  an xpvmg. See also C<sv_force_normal_flags>.
1006  
1007      void    sv_force_normal(SV *sv)
1008  
1009  =for hackers
1010  Found in file mathoms.c
1011  
1012  =item sv_iv
1013  X<sv_iv>
1014  
1015  A private implementation of the C<SvIVx> macro for compilers which can't
1016  cope with complex macro expressions. Always use the macro instead.
1017  
1018      IV    sv_iv(SV* sv)
1019  
1020  =for hackers
1021  Found in file mathoms.c
1022  
1023  =item sv_nolocking
1024  X<sv_nolocking>
1025  
1026  Dummy routine which "locks" an SV when there is no locking module present.
1027  Exists to avoid test for a NULL function pointer and because it could
1028  potentially warn under some level of strict-ness.
1029  
1030  "Superseded" by sv_nosharing().
1031  
1032      void    sv_nolocking(SV *sv)
1033  
1034  =for hackers
1035  Found in file mathoms.c
1036  
1037  =item sv_nounlocking
1038  X<sv_nounlocking>
1039  
1040  Dummy routine which "unlocks" an SV when there is no locking module present.
1041  Exists to avoid test for a NULL function pointer and because it could
1042  potentially warn under some level of strict-ness.
1043  
1044  "Superseded" by sv_nosharing().
1045  
1046      void    sv_nounlocking(SV *sv)
1047  
1048  =for hackers
1049  Found in file mathoms.c
1050  
1051  =item sv_nv
1052  X<sv_nv>
1053  
1054  A private implementation of the C<SvNVx> macro for compilers which can't
1055  cope with complex macro expressions. Always use the macro instead.
1056  
1057      NV    sv_nv(SV* sv)
1058  
1059  =for hackers
1060  Found in file mathoms.c
1061  
1062  =item sv_pv
1063  X<sv_pv>
1064  
1065  Use the C<SvPV_nolen> macro instead
1066  
1067      char*    sv_pv(SV *sv)
1068  
1069  =for hackers
1070  Found in file mathoms.c
1071  
1072  =item sv_pvbyte
1073  X<sv_pvbyte>
1074  
1075  Use C<SvPVbyte_nolen> instead.
1076  
1077      char*    sv_pvbyte(SV *sv)
1078  
1079  =for hackers
1080  Found in file mathoms.c
1081  
1082  =item sv_pvbyten
1083  X<sv_pvbyten>
1084  
1085  A private implementation of the C<SvPVbyte> macro for compilers
1086  which can't cope with complex macro expressions. Always use the macro
1087  instead.
1088  
1089      char*    sv_pvbyten(SV *sv, STRLEN *len)
1090  
1091  =for hackers
1092  Found in file mathoms.c
1093  
1094  =item sv_pvn
1095  X<sv_pvn>
1096  
1097  A private implementation of the C<SvPV> macro for compilers which can't
1098  cope with complex macro expressions. Always use the macro instead.
1099  
1100      char*    sv_pvn(SV *sv, STRLEN *len)
1101  
1102  =for hackers
1103  Found in file mathoms.c
1104  
1105  =item sv_pvutf8
1106  X<sv_pvutf8>
1107  
1108  Use the C<SvPVutf8_nolen> macro instead
1109  
1110      char*    sv_pvutf8(SV *sv)
1111  
1112  =for hackers
1113  Found in file mathoms.c
1114  
1115  =item sv_pvutf8n
1116  X<sv_pvutf8n>
1117  
1118  A private implementation of the C<SvPVutf8> macro for compilers
1119  which can't cope with complex macro expressions. Always use the macro
1120  instead.
1121  
1122      char*    sv_pvutf8n(SV *sv, STRLEN *len)
1123  
1124  =for hackers
1125  Found in file mathoms.c
1126  
1127  =item sv_taint
1128  X<sv_taint>
1129  
1130  Taint an SV. Use C<SvTAINTED_on> instead.
1131      void    sv_taint(SV* sv)
1132  
1133  =for hackers
1134  Found in file mathoms.c
1135  
1136  =item sv_unref
1137  X<sv_unref>
1138  
1139  Unsets the RV status of the SV, and decrements the reference count of
1140  whatever was being referenced by the RV.  This can almost be thought of
1141  as a reversal of C<newSVrv>.  This is C<sv_unref_flags> with the C<flag>
1142  being zero.  See C<SvROK_off>.
1143  
1144      void    sv_unref(SV* sv)
1145  
1146  =for hackers
1147  Found in file mathoms.c
1148  
1149  =item sv_usepvn
1150  X<sv_usepvn>
1151  
1152  Tells an SV to use C<ptr> to find its string value. Implemented by
1153  calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
1154  magic. See C<sv_usepvn_flags>.
1155  
1156      void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
1157  
1158  =for hackers
1159  Found in file mathoms.c
1160  
1161  =item sv_usepvn_mg
1162  X<sv_usepvn_mg>
1163  
1164  Like C<sv_usepvn>, but also handles 'set' magic.
1165  
1166      void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1167  
1168  =for hackers
1169  Found in file mathoms.c
1170  
1171  =item sv_uv
1172  X<sv_uv>
1173  
1174  A private implementation of the C<SvUVx> macro for compilers which can't
1175  cope with complex macro expressions. Always use the macro instead.
1176  
1177      UV    sv_uv(SV* sv)
1178  
1179  =for hackers
1180  Found in file mathoms.c
1181  
1182  =item unpack_str
1183  X<unpack_str>
1184  
1185  The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
1186  and ocnt are not used. This call should not be used, use unpackstring instead.
1187  
1188      I32    unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
1189  
1190  =for hackers
1191  Found in file mathoms.c
1192  
1193  
1194  =back
1195  
1196  =head1 Functions in file pp_ctl.c
1197  
1198  
1199  =over 8
1200  
1201  =item find_runcv
1202  X<find_runcv>
1203  
1204  Locate the CV corresponding to the currently executing sub or eval.
1205  If db_seqp is non_null, skip CVs that are in the DB package and populate
1206  *db_seqp with the cop sequence number at the point that the DB:: code was
1207  entered. (allows debuggers to eval in the scope of the breakpoint rather
1208  than in the scope of the debugger itself).
1209  
1210      CV*    find_runcv(U32 *db_seqp)
1211  
1212  =for hackers
1213  Found in file pp_ctl.c
1214  
1215  
1216  =back
1217  
1218  =head1 Functions in file pp_pack.c
1219  
1220  
1221  =over 8
1222  
1223  =item packlist
1224  X<packlist>
1225  
1226  The engine implementing pack() Perl function.
1227  
1228      void    packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
1229  
1230  =for hackers
1231  Found in file pp_pack.c
1232  
1233  =item unpackstring
1234  X<unpackstring>
1235  
1236  The engine implementing unpack() Perl function. C<unpackstring> puts the
1237  extracted list items on the stack and returns the number of elements.
1238  Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
1239  
1240      I32    unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
1241  
1242  =for hackers
1243  Found in file pp_pack.c
1244  
1245  
1246  =back
1247  
1248  =head1 GV Functions
1249  
1250  =over 8
1251  
1252  =item GvSV
1253  X<GvSV>
1254  
1255  Return the SV from the GV.
1256  
1257      SV*    GvSV(GV* gv)
1258  
1259  =for hackers
1260  Found in file gv.h
1261  
1262  =item gv_const_sv
1263  X<gv_const_sv>
1264  
1265  If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1266  inlining, or C<gv> is a placeholder reference that would be promoted to such
1267  a typeglob, then returns the value returned by the sub.  Otherwise, returns
1268  NULL.
1269  
1270      SV*    gv_const_sv(GV* gv)
1271  
1272  =for hackers
1273  Found in file gv.c
1274  
1275  =item gv_fetchmeth
1276  X<gv_fetchmeth>
1277  
1278  Returns the glob with the given C<name> and a defined subroutine or
1279  C<NULL>.  The glob lives in the given C<stash>, or in the stashes
1280  accessible via @ISA and UNIVERSAL::.
1281  
1282  The argument C<level> should be either 0 or -1.  If C<level==0>, as a
1283  side-effect creates a glob with the given C<name> in the given C<stash>
1284  which in the case of success contains an alias for the subroutine, and sets
1285  up caching info for this glob.
1286  
1287  This function grants C<"SUPER"> token as a postfix of the stash name. The
1288  GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1289  visible to Perl code.  So when calling C<call_sv>, you should not use
1290  the GV directly; instead, you should use the method's CV, which can be
1291  obtained from the GV with the C<GvCV> macro.
1292  
1293      GV*    gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1294  
1295  =for hackers
1296  Found in file gv.c
1297  
1298  =item gv_fetchmethod_autoload
1299  X<gv_fetchmethod_autoload>
1300  
1301  Returns the glob which contains the subroutine to call to invoke the method
1302  on the C<stash>.  In fact in the presence of autoloading this may be the
1303  glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
1304  already setup.
1305  
1306  The third parameter of C<gv_fetchmethod_autoload> determines whether
1307  AUTOLOAD lookup is performed if the given method is not present: non-zero
1308  means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1309  Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1310  with a non-zero C<autoload> parameter.
1311  
1312  These functions grant C<"SUPER"> token as a prefix of the method name. Note
1313  that if you want to keep the returned glob for a long time, you need to
1314  check for it being "AUTOLOAD", since at the later time the call may load a
1315  different subroutine due to $AUTOLOAD changing its value. Use the glob
1316  created via a side effect to do this.
1317  
1318  These functions have the same side-effects and as C<gv_fetchmeth> with
1319  C<level==0>.  C<name> should be writable if contains C<':'> or C<'
1320  ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1321  C<call_sv> apply equally to these functions.
1322  
1323      GV*    gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1324  
1325  =for hackers
1326  Found in file gv.c
1327  
1328  =item gv_fetchmeth_autoload
1329  X<gv_fetchmeth_autoload>
1330  
1331  Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1332  Returns a glob for the subroutine.
1333  
1334  For an autoloaded subroutine without a GV, will create a GV even
1335  if C<level < 0>.  For an autoloaded subroutine without a stub, GvCV()
1336  of the result may be zero.
1337  
1338      GV*    gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1339  
1340  =for hackers
1341  Found in file gv.c
1342  
1343  =item gv_stashpv
1344  X<gv_stashpv>
1345  
1346  Returns a pointer to the stash for a specified package.  Uses C<strlen> to
1347  determine the length of C<name>, then calls C<gv_stashpvn()>.
1348  
1349      HV*    gv_stashpv(const char* name, I32 flags)
1350  
1351  =for hackers
1352  Found in file gv.c
1353  
1354  =item gv_stashpvn
1355  X<gv_stashpvn>
1356  
1357  Returns a pointer to the stash for a specified package.  The C<namelen>
1358  parameter indicates the length of the C<name>, in bytes.  C<flags> is passed
1359  to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
1360  created if it does not already exist.  If the package does not exist and
1361  C<flags> is 0 (or any other setting that does not create packages) then NULL
1362  is returned.
1363  
1364  
1365      HV*    gv_stashpvn(const char* name, U32 namelen, I32 flags)
1366  
1367  =for hackers
1368  Found in file gv.c
1369  
1370  =item gv_stashpvs
1371  X<gv_stashpvs>
1372  
1373  Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1374  
1375      HV*    gv_stashpvs(const char* name, I32 create)
1376  
1377  =for hackers
1378  Found in file handy.h
1379  
1380  =item gv_stashsv
1381  X<gv_stashsv>
1382  
1383  Returns a pointer to the stash for a specified package.  See C<gv_stashpvn>.
1384  
1385      HV*    gv_stashsv(SV* sv, I32 flags)
1386  
1387  =for hackers
1388  Found in file gv.c
1389  
1390  
1391  =back
1392  
1393  =head1 Handy Values
1394  
1395  =over 8
1396  
1397  =item Nullav
1398  X<Nullav>
1399  
1400  Null AV pointer.
1401  
1402  =for hackers
1403  Found in file av.h
1404  
1405  =item Nullch
1406  X<Nullch>
1407  
1408  Null character pointer.
1409  
1410  =for hackers
1411  Found in file handy.h
1412  
1413  =item Nullcv
1414  X<Nullcv>
1415  
1416  Null CV pointer.
1417  
1418  =for hackers
1419  Found in file cv.h
1420  
1421  =item Nullhv
1422  X<Nullhv>
1423  
1424  Null HV pointer.
1425  
1426  =for hackers
1427  Found in file hv.h
1428  
1429  =item Nullsv
1430  X<Nullsv>
1431  
1432  Null SV pointer.
1433  
1434  =for hackers
1435  Found in file handy.h
1436  
1437  
1438  =back
1439  
1440  =head1 Hash Manipulation Functions
1441  
1442  =over 8
1443  
1444  =item get_hv
1445  X<get_hv>
1446  
1447  Returns the HV of the specified Perl hash.  If C<create> is set and the
1448  Perl variable does not exist then it will be created.  If C<create> is not
1449  set and the variable does not exist then NULL is returned.
1450  
1451  NOTE: the perl_ form of this function is deprecated.
1452  
1453      HV*    get_hv(const char* name, I32 create)
1454  
1455  =for hackers
1456  Found in file perl.c
1457  
1458  =item HEf_SVKEY
1459  X<HEf_SVKEY>
1460  
1461  This flag, used in the length slot of hash entries and magic structures,
1462  specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1463  is to be expected. (For information only--not to be used).
1464  
1465  =for hackers
1466  Found in file hv.h
1467  
1468  =item HeHASH
1469  X<HeHASH>
1470  
1471  Returns the computed hash stored in the hash entry.
1472  
1473      U32    HeHASH(HE* he)
1474  
1475  =for hackers
1476  Found in file hv.h
1477  
1478  =item HeKEY
1479  X<HeKEY>
1480  
1481  Returns the actual pointer stored in the key slot of the hash entry. The
1482  pointer may be either C<char*> or C<SV*>, depending on the value of
1483  C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
1484  usually preferable for finding the value of a key.
1485  
1486      void*    HeKEY(HE* he)
1487  
1488  =for hackers
1489  Found in file hv.h
1490  
1491  =item HeKLEN
1492  X<HeKLEN>
1493  
1494  If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1495  holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
1496  be assigned to. The C<HePV()> macro is usually preferable for finding key
1497  lengths.
1498  
1499      STRLEN    HeKLEN(HE* he)
1500  
1501  =for hackers
1502  Found in file hv.h
1503  
1504  =item HePV
1505  X<HePV>
1506  
1507  Returns the key slot of the hash entry as a C<char*> value, doing any
1508  necessary dereferencing of possibly C<SV*> keys.  The length of the string
1509  is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
1510  not care about what the length of the key is, you may use the global
1511  variable C<PL_na>, though this is rather less efficient than using a local
1512  variable.  Remember though, that hash keys in perl are free to contain
1513  embedded nulls, so using C<strlen()> or similar is not a good way to find
1514  the length of hash keys. This is very similar to the C<SvPV()> macro
1515  described elsewhere in this document.
1516  
1517      char*    HePV(HE* he, STRLEN len)
1518  
1519  =for hackers
1520  Found in file hv.h
1521  
1522  =item HeSVKEY
1523  X<HeSVKEY>
1524  
1525  Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
1526  contain an C<SV*> key.
1527  
1528      SV*    HeSVKEY(HE* he)
1529  
1530  =for hackers
1531  Found in file hv.h
1532  
1533  =item HeSVKEY_force
1534  X<HeSVKEY_force>
1535  
1536  Returns the key as an C<SV*>.  Will create and return a temporary mortal
1537  C<SV*> if the hash entry contains only a C<char*> key.
1538  
1539      SV*    HeSVKEY_force(HE* he)
1540  
1541  =for hackers
1542  Found in file hv.h
1543  
1544  =item HeSVKEY_set
1545  X<HeSVKEY_set>
1546  
1547  Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1548  indicate the presence of an C<SV*> key, and returns the same
1549  C<SV*>.
1550  
1551      SV*    HeSVKEY_set(HE* he, SV* sv)
1552  
1553  =for hackers
1554  Found in file hv.h
1555  
1556  =item HeVAL
1557  X<HeVAL>
1558  
1559  Returns the value slot (type C<SV*>) stored in the hash entry.
1560  
1561      SV*    HeVAL(HE* he)
1562  
1563  =for hackers
1564  Found in file hv.h
1565  
1566  =item HvNAME
1567  X<HvNAME>
1568  
1569  Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1570  See C<SvSTASH>, C<CvSTASH>.
1571  
1572      char*    HvNAME(HV* stash)
1573  
1574  =for hackers
1575  Found in file hv.h
1576  
1577  =item hv_assert
1578  X<hv_assert>
1579  
1580  Check that a hash is in an internally consistent state.
1581  
1582      void    hv_assert(HV* tb)
1583  
1584  =for hackers
1585  Found in file hv.c
1586  
1587  =item hv_clear
1588  X<hv_clear>
1589  
1590  Clears a hash, making it empty.
1591  
1592      void    hv_clear(HV* tb)
1593  
1594  =for hackers
1595  Found in file hv.c
1596  
1597  =item hv_clear_placeholders
1598  X<hv_clear_placeholders>
1599  
1600  Clears any placeholders from a hash.  If a restricted hash has any of its keys
1601  marked as readonly and the key is subsequently deleted, the key is not actually
1602  deleted but is marked by assigning it a value of &PL_sv_placeholder.  This tags
1603  it so it will be ignored by future operations such as iterating over the hash,
1604  but will still allow the hash to have a value reassigned to the key at some
1605  future point.  This function clears any such placeholder keys from the hash.
1606  See Hash::Util::lock_keys() for an example of its use.
1607  
1608      void    hv_clear_placeholders(HV* hb)
1609  
1610  =for hackers
1611  Found in file hv.c
1612  
1613  =item hv_delete
1614  X<hv_delete>
1615  
1616  Deletes a key/value pair in the hash.  The value SV is removed from the
1617  hash and returned to the caller.  The C<klen> is the length of the key.
1618  The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1619  will be returned.
1620  
1621      SV*    hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
1622  
1623  =for hackers
1624  Found in file hv.c
1625  
1626  =item hv_delete_ent
1627  X<hv_delete_ent>
1628  
1629  Deletes a key/value pair in the hash.  The value SV is removed from the
1630  hash and returned to the caller.  The C<flags> value will normally be zero;
1631  if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
1632  precomputed hash value, or 0 to ask for it to be computed.
1633  
1634      SV*    hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1635  
1636  =for hackers
1637  Found in file hv.c
1638  
1639  =item hv_exists
1640  X<hv_exists>
1641  
1642  Returns a boolean indicating whether the specified hash key exists.  The
1643  C<klen> is the length of the key.
1644  
1645      bool    hv_exists(HV* tb, const char* key, I32 klen)
1646  
1647  =for hackers
1648  Found in file hv.c
1649  
1650  =item hv_exists_ent
1651  X<hv_exists_ent>
1652  
1653  Returns a boolean indicating whether the specified hash key exists. C<hash>
1654  can be a valid precomputed hash value, or 0 to ask for it to be
1655  computed.
1656  
1657      bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
1658  
1659  =for hackers
1660  Found in file hv.c
1661  
1662  =item hv_fetch
1663  X<hv_fetch>
1664  
1665  Returns the SV which corresponds to the specified key in the hash.  The
1666  C<klen> is the length of the key.  If C<lval> is set then the fetch will be
1667  part of a store.  Check that the return value is non-null before
1668  dereferencing it to an C<SV*>.
1669  
1670  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1671  information on how to use this function on tied hashes.
1672  
1673      SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1674  
1675  =for hackers
1676  Found in file hv.c
1677  
1678  =item hv_fetchs
1679  X<hv_fetchs>
1680  
1681  Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1682  
1683      SV**    hv_fetchs(HV* tb, const char* key, I32 lval)
1684  
1685  =for hackers
1686  Found in file handy.h
1687  
1688  =item hv_fetch_ent
1689  X<hv_fetch_ent>
1690  
1691  Returns the hash entry which corresponds to the specified key in the hash.
1692  C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1693  if you want the function to compute it.  IF C<lval> is set then the fetch
1694  will be part of a store.  Make sure the return value is non-null before
1695  accessing it.  The return value when C<tb> is a tied hash is a pointer to a
1696  static location, so be sure to make a copy of the structure if you need to
1697  store it somewhere.
1698  
1699  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1700  information on how to use this function on tied hashes.
1701  
1702      HE*    hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1703  
1704  =for hackers
1705  Found in file hv.c
1706  
1707  =item hv_iterinit
1708  X<hv_iterinit>
1709  
1710  Prepares a starting point to traverse a hash table.  Returns the number of
1711  keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
1712  currently only meaningful for hashes without tie magic.
1713  
1714  NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1715  hash buckets that happen to be in use.  If you still need that esoteric
1716  value, you can get it through the macro C<HvFILL(tb)>.
1717  
1718  
1719      I32    hv_iterinit(HV* tb)
1720  
1721  =for hackers
1722  Found in file hv.c
1723  
1724  =item hv_iterkey
1725  X<hv_iterkey>
1726  
1727  Returns the key from the current position of the hash iterator.  See
1728  C<hv_iterinit>.
1729  
1730      char*    hv_iterkey(HE* entry, I32* retlen)
1731  
1732  =for hackers
1733  Found in file hv.c
1734  
1735  =item hv_iterkeysv
1736  X<hv_iterkeysv>
1737  
1738  Returns the key as an C<SV*> from the current position of the hash
1739  iterator.  The return value will always be a mortal copy of the key.  Also
1740  see C<hv_iterinit>.
1741  
1742      SV*    hv_iterkeysv(HE* entry)
1743  
1744  =for hackers
1745  Found in file hv.c
1746  
1747  =item hv_iternext
1748  X<hv_iternext>
1749  
1750  Returns entries from a hash iterator.  See C<hv_iterinit>.
1751  
1752  You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1753  iterator currently points to, without losing your place or invalidating your
1754  iterator.  Note that in this case the current entry is deleted from the hash
1755  with your iterator holding the last reference to it.  Your iterator is flagged
1756  to free the entry on the next call to C<hv_iternext>, so you must not discard
1757  your iterator immediately else the entry will leak - call C<hv_iternext> to
1758  trigger the resource deallocation.
1759  
1760      HE*    hv_iternext(HV* tb)
1761  
1762  =for hackers
1763  Found in file hv.c
1764  
1765  =item hv_iternextsv
1766  X<hv_iternextsv>
1767  
1768  Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1769  operation.
1770  
1771      SV*    hv_iternextsv(HV* hv, char** key, I32* retlen)
1772  
1773  =for hackers
1774  Found in file hv.c
1775  
1776  =item hv_iternext_flags
1777  X<hv_iternext_flags>
1778  
1779  Returns entries from a hash iterator.  See C<hv_iterinit> and C<hv_iternext>.
1780  The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1781  set the placeholders keys (for restricted hashes) will be returned in addition
1782  to normal keys. By default placeholders are automatically skipped over.
1783  Currently a placeholder is implemented with a value that is
1784  C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1785  restricted hashes may change, and the implementation currently is
1786  insufficiently abstracted for any change to be tidy.
1787  
1788  NOTE: this function is experimental and may change or be
1789  removed without notice.
1790  
1791      HE*    hv_iternext_flags(HV* tb, I32 flags)
1792  
1793  =for hackers
1794  Found in file hv.c
1795  
1796  =item hv_iterval
1797  X<hv_iterval>
1798  
1799  Returns the value from the current position of the hash iterator.  See
1800  C<hv_iterkey>.
1801  
1802      SV*    hv_iterval(HV* tb, HE* entry)
1803  
1804  =for hackers
1805  Found in file hv.c
1806  
1807  =item hv_magic
1808  X<hv_magic>
1809  
1810  Adds magic to a hash.  See C<sv_magic>.
1811  
1812      void    hv_magic(HV* hv, GV* gv, int how)
1813  
1814  =for hackers
1815  Found in file hv.c
1816  
1817  =item hv_scalar
1818  X<hv_scalar>
1819  
1820  Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1821  
1822      SV*    hv_scalar(HV* hv)
1823  
1824  =for hackers
1825  Found in file hv.c
1826  
1827  =item hv_store
1828  X<hv_store>
1829  
1830  Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
1831  the length of the key.  The C<hash> parameter is the precomputed hash
1832  value; if it is zero then Perl will compute it.  The return value will be
1833  NULL if the operation failed or if the value did not need to be actually
1834  stored within the hash (as in the case of tied hashes).  Otherwise it can
1835  be dereferenced to get the original C<SV*>.  Note that the caller is
1836  responsible for suitably incrementing the reference count of C<val> before
1837  the call, and decrementing it if the function returned NULL.  Effectively
1838  a successful hv_store takes ownership of one reference to C<val>.  This is
1839  usually what you want; a newly created SV has a reference count of one, so
1840  if all your code does is create SVs then store them in a hash, hv_store
1841  will own the only reference to the new SV, and your code doesn't need to do
1842  anything further to tidy up.  hv_store is not implemented as a call to
1843  hv_store_ent, and does not create a temporary SV for the key, so if your
1844  key data is not already in SV form then use hv_store in preference to
1845  hv_store_ent.
1846  
1847  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1848  information on how to use this function on tied hashes.
1849  
1850      SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1851  
1852  =for hackers
1853  Found in file hv.c
1854  
1855  =item hv_stores
1856  X<hv_stores>
1857  
1858  Like C<hv_store>, but takes a literal string instead of a string/length pair
1859  and omits the hash parameter.
1860  
1861      SV**    hv_stores(HV* tb, const char* key, NULLOK SV* val)
1862  
1863  =for hackers
1864  Found in file handy.h
1865  
1866  =item hv_store_ent
1867  X<hv_store_ent>
1868  
1869  Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
1870  parameter is the precomputed hash value; if it is zero then Perl will
1871  compute it.  The return value is the new hash entry so created.  It will be
1872  NULL if the operation failed or if the value did not need to be actually
1873  stored within the hash (as in the case of tied hashes).  Otherwise the
1874  contents of the return value can be accessed using the C<He?> macros
1875  described here.  Note that the caller is responsible for suitably
1876  incrementing the reference count of C<val> before the call, and
1877  decrementing it if the function returned NULL.  Effectively a successful
1878  hv_store_ent takes ownership of one reference to C<val>.  This is
1879  usually what you want; a newly created SV has a reference count of one, so
1880  if all your code does is create SVs then store them in a hash, hv_store
1881  will own the only reference to the new SV, and your code doesn't need to do
1882  anything further to tidy up.  Note that hv_store_ent only reads the C<key>;
1883  unlike C<val> it does not take ownership of it, so maintaining the correct
1884  reference count on C<key> is entirely the caller's responsibility.  hv_store
1885  is not implemented as a call to hv_store_ent, and does not create a temporary
1886  SV for the key, so if your key data is not already in SV form then use
1887  hv_store in preference to hv_store_ent.
1888  
1889  See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1890  information on how to use this function on tied hashes.
1891  
1892      HE*    hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1893  
1894  =for hackers
1895  Found in file hv.c
1896  
1897  =item hv_undef
1898  X<hv_undef>
1899  
1900  Undefines the hash.
1901  
1902      void    hv_undef(HV* tb)
1903  
1904  =for hackers
1905  Found in file hv.c
1906  
1907  =item newHV
1908  X<newHV>
1909  
1910  Creates a new HV.  The reference count is set to 1.
1911  
1912      HV*    newHV()
1913  
1914  =for hackers
1915  Found in file hv.c
1916  
1917  
1918  =back
1919  
1920  =head1 Magical Functions
1921  
1922  =over 8
1923  
1924  =item mg_clear
1925  X<mg_clear>
1926  
1927  Clear something magical that the SV represents.  See C<sv_magic>.
1928  
1929      int    mg_clear(SV* sv)
1930  
1931  =for hackers
1932  Found in file mg.c
1933  
1934  =item mg_copy
1935  X<mg_copy>
1936  
1937  Copies the magic from one SV to another.  See C<sv_magic>.
1938  
1939      int    mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1940  
1941  =for hackers
1942  Found in file mg.c
1943  
1944  =item mg_find
1945  X<mg_find>
1946  
1947  Finds the magic pointer for type matching the SV.  See C<sv_magic>.
1948  
1949      MAGIC*    mg_find(const SV* sv, int type)
1950  
1951  =for hackers
1952  Found in file mg.c
1953  
1954  =item mg_free
1955  X<mg_free>
1956  
1957  Free any magic storage used by the SV.  See C<sv_magic>.
1958  
1959      int    mg_free(SV* sv)
1960  
1961  =for hackers
1962  Found in file mg.c
1963  
1964  =item mg_get
1965  X<mg_get>
1966  
1967  Do magic after a value is retrieved from the SV.  See C<sv_magic>.
1968  
1969      int    mg_get(SV* sv)
1970  
1971  =for hackers
1972  Found in file mg.c
1973  
1974  =item mg_length
1975  X<mg_length>
1976  
1977  Report on the SV's length.  See C<sv_magic>.
1978  
1979      U32    mg_length(SV* sv)
1980  
1981  =for hackers
1982  Found in file mg.c
1983  
1984  =item mg_magical
1985  X<mg_magical>
1986  
1987  Turns on the magical status of an SV.  See C<sv_magic>.
1988  
1989      void    mg_magical(SV* sv)
1990  
1991  =for hackers
1992  Found in file mg.c
1993  
1994  =item mg_set
1995  X<mg_set>
1996  
1997  Do magic after a value is assigned to the SV.  See C<sv_magic>.
1998  
1999      int    mg_set(SV* sv)
2000  
2001  =for hackers
2002  Found in file mg.c
2003  
2004  =item SvGETMAGIC
2005  X<SvGETMAGIC>
2006  
2007  Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
2008  argument more than once.
2009  
2010      void    SvGETMAGIC(SV* sv)
2011  
2012  =for hackers
2013  Found in file sv.h
2014  
2015  =item SvLOCK
2016  X<SvLOCK>
2017  
2018  Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
2019  has been loaded.
2020  
2021      void    SvLOCK(SV* sv)
2022  
2023  =for hackers
2024  Found in file sv.h
2025  
2026  =item SvSETMAGIC
2027  X<SvSETMAGIC>
2028  
2029  Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
2030  argument more than once.
2031  
2032      void    SvSETMAGIC(SV* sv)
2033  
2034  =for hackers
2035  Found in file sv.h
2036  
2037  =item SvSetMagicSV
2038  X<SvSetMagicSV>
2039  
2040  Like C<SvSetSV>, but does any set magic required afterwards.
2041  
2042      void    SvSetMagicSV(SV* dsb, SV* ssv)
2043  
2044  =for hackers
2045  Found in file sv.h
2046  
2047  =item SvSetMagicSV_nosteal
2048  X<SvSetMagicSV_nosteal>
2049  
2050  Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
2051  
2052      void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2053  
2054  =for hackers
2055  Found in file sv.h
2056  
2057  =item SvSetSV
2058  X<SvSetSV>
2059  
2060  Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
2061  more than once.
2062  
2063      void    SvSetSV(SV* dsb, SV* ssv)
2064  
2065  =for hackers
2066  Found in file sv.h
2067  
2068  =item SvSetSV_nosteal
2069  X<SvSetSV_nosteal>
2070  
2071  Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2072  ssv. May evaluate arguments more than once.
2073  
2074      void    SvSetSV_nosteal(SV* dsv, SV* ssv)
2075  
2076  =for hackers
2077  Found in file sv.h
2078  
2079  =item SvSHARE
2080  X<SvSHARE>
2081  
2082  Arranges for sv to be shared between threads if a suitable module
2083  has been loaded.
2084  
2085      void    SvSHARE(SV* sv)
2086  
2087  =for hackers
2088  Found in file sv.h
2089  
2090  =item SvUNLOCK
2091  X<SvUNLOCK>
2092  
2093  Releases a mutual exclusion lock on sv if a suitable module
2094  has been loaded.
2095  
2096      void    SvUNLOCK(SV* sv)
2097  
2098  =for hackers
2099  Found in file sv.h
2100  
2101  
2102  =back
2103  
2104  =head1 Memory Management
2105  
2106  =over 8
2107  
2108  =item Copy
2109  X<Copy>
2110  
2111  The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
2112  source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2113  the type.  May fail on overlapping copies.  See also C<Move>.
2114  
2115      void    Copy(void* src, void* dest, int nitems, type)
2116  
2117  =for hackers
2118  Found in file handy.h
2119  
2120  =item CopyD
2121  X<CopyD>
2122  
2123  Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2124  optimise.
2125  
2126      void *    CopyD(void* src, void* dest, int nitems, type)
2127  
2128  =for hackers
2129  Found in file handy.h
2130  
2131  =item Move
2132  X<Move>
2133  
2134  The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
2135  source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2136  the type.  Can do overlapping moves.  See also C<Copy>.
2137  
2138      void    Move(void* src, void* dest, int nitems, type)
2139  
2140  =for hackers
2141  Found in file handy.h
2142  
2143  =item MoveD
2144  X<MoveD>
2145  
2146  Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2147  optimise.
2148  
2149      void *    MoveD(void* src, void* dest, int nitems, type)
2150  
2151  =for hackers
2152  Found in file handy.h
2153  
2154  =item Newx
2155  X<Newx>
2156  
2157  The XSUB-writer's interface to the C C<malloc> function.
2158  
2159  In 5.9.3, Newx() and friends replace the older New() API, and drops
2160  the first parameter, I<x>, a debug aid which allowed callers to identify
2161  themselves.  This aid has been superseded by a new build option,
2162  PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>).  The older API is still
2163  there for use in XS modules supporting older perls.
2164  
2165      void    Newx(void* ptr, int nitems, type)
2166  
2167  =for hackers
2168  Found in file handy.h
2169  
2170  =item Newxc
2171  X<Newxc>
2172  
2173  The XSUB-writer's interface to the C C<malloc> function, with
2174  cast.  See also C<Newx>.
2175  
2176      void    Newxc(void* ptr, int nitems, type, cast)
2177  
2178  =for hackers
2179  Found in file handy.h
2180  
2181  =item Newxz
2182  X<Newxz>
2183  
2184  The XSUB-writer's interface to the C C<malloc> function.  The allocated
2185  memory is zeroed with C<memzero>.  See also C<Newx>.
2186  
2187      void    Newxz(void* ptr, int nitems, type)
2188  
2189  =for hackers
2190  Found in file handy.h
2191  
2192  =item Poison
2193  X<Poison>
2194  
2195  PoisonWith(0xEF) for catching access to freed memory.
2196  
2197      void    Poison(void* dest, int nitems, type)
2198  
2199  =for hackers
2200  Found in file handy.h
2201  
2202  =item PoisonFree
2203  X<PoisonFree>
2204  
2205  PoisonWith(0xEF) for catching access to freed memory.
2206  
2207      void    PoisonFree(void* dest, int nitems, type)
2208  
2209  =for hackers
2210  Found in file handy.h
2211  
2212  =item PoisonNew
2213  X<PoisonNew>
2214  
2215  PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2216  
2217      void    PoisonNew(void* dest, int nitems, type)
2218  
2219  =for hackers
2220  Found in file handy.h
2221  
2222  =item PoisonWith
2223  X<PoisonWith>
2224  
2225  Fill up memory with a byte pattern (a byte repeated over and over
2226  again) that hopefully catches attempts to access uninitialized memory.
2227  
2228      void    PoisonWith(void* dest, int nitems, type, U8 byte)
2229  
2230  =for hackers
2231  Found in file handy.h
2232  
2233  =item Renew
2234  X<Renew>
2235  
2236  The XSUB-writer's interface to the C C<realloc> function.
2237  
2238      void    Renew(void* ptr, int nitems, type)
2239  
2240  =for hackers
2241  Found in file handy.h
2242  
2243  =item Renewc
2244  X<Renewc>
2245  
2246  The XSUB-writer's interface to the C C<realloc> function, with
2247  cast.
2248  
2249      void    Renewc(void* ptr, int nitems, type, cast)
2250  
2251  =for hackers
2252  Found in file handy.h
2253  
2254  =item Safefree
2255  X<Safefree>
2256  
2257  The XSUB-writer's interface to the C C<free> function.
2258  
2259      void    Safefree(void* ptr)
2260  
2261  =for hackers
2262  Found in file handy.h
2263  
2264  =item savepv
2265  X<savepv>
2266  
2267  Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2268  string which is a duplicate of C<pv>. The size of the string is
2269  determined by C<strlen()>. The memory allocated for the new string can
2270  be freed with the C<Safefree()> function.
2271  
2272      char*    savepv(const char* pv)
2273  
2274  =for hackers
2275  Found in file util.c
2276  
2277  =item savepvn
2278  X<savepvn>
2279  
2280  Perl's version of what C<strndup()> would be if it existed. Returns a
2281  pointer to a newly allocated string which is a duplicate of the first
2282  C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2283  the new string can be freed with the C<Safefree()> function.
2284  
2285      char*    savepvn(const char* pv, I32 len)
2286  
2287  =for hackers
2288  Found in file util.c
2289  
2290  =item savepvs
2291  X<savepvs>
2292  
2293  Like C<savepvn>, but takes a literal string instead of a string/length pair.
2294  
2295      char*    savepvs(const char* s)
2296  
2297  =for hackers
2298  Found in file handy.h
2299  
2300  =item savesharedpv
2301  X<savesharedpv>
2302  
2303  A version of C<savepv()> which allocates the duplicate string in memory
2304  which is shared between threads.
2305  
2306      char*    savesharedpv(const char* pv)
2307  
2308  =for hackers
2309  Found in file util.c
2310  
2311  =item savesharedpvn
2312  X<savesharedpvn>
2313  
2314  A version of C<savepvn()> which allocates the duplicate string in memory
2315  which is shared between threads. (With the specific difference that a NULL
2316  pointer is not acceptable)
2317  
2318      char*    savesharedpvn(const char *const pv, const STRLEN len)
2319  
2320  =for hackers
2321  Found in file util.c
2322  
2323  =item savesvpv
2324  X<savesvpv>
2325  
2326  A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
2327  the passed in SV using C<SvPV()>
2328  
2329      char*    savesvpv(SV* sv)
2330  
2331  =for hackers
2332  Found in file util.c
2333  
2334  =item StructCopy
2335  X<StructCopy>
2336  
2337  This is an architecture-independent macro to copy one structure to another.
2338  
2339      void    StructCopy(type src, type dest, type)
2340  
2341  =for hackers
2342  Found in file handy.h
2343  
2344  =item Zero
2345  X<Zero>
2346  
2347  The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2348  destination, C<nitems> is the number of items, and C<type> is the type.
2349  
2350      void    Zero(void* dest, int nitems, type)
2351  
2352  =for hackers
2353  Found in file handy.h
2354  
2355  =item ZeroD
2356  X<ZeroD>
2357  
2358  Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2359  optimise.
2360  
2361      void *    ZeroD(void* dest, int nitems, type)
2362  
2363  =for hackers
2364  Found in file handy.h
2365  
2366  
2367  =back
2368  
2369  =head1 Miscellaneous Functions
2370  
2371  =over 8
2372  
2373  =item fbm_compile
2374  X<fbm_compile>
2375  
2376  Analyses the string in order to make fast searches on it using fbm_instr()
2377  -- the Boyer-Moore algorithm.
2378  
2379      void    fbm_compile(SV* sv, U32 flags)
2380  
2381  =for hackers
2382  Found in file util.c
2383  
2384  =item fbm_instr
2385  X<fbm_instr>
2386  
2387  Returns the location of the SV in the string delimited by C<str> and
2388  C<strend>.  It returns C<NULL> if the string can't be found.  The C<sv>
2389  does not have to be fbm_compiled, but the search will not be as fast
2390  then.
2391  
2392      char*    fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
2393  
2394  =for hackers
2395  Found in file util.c
2396  
2397  =item form
2398  X<form>
2399  
2400  Takes a sprintf-style format pattern and conventional
2401  (non-SV) arguments and returns the formatted string.
2402  
2403      (char *) Perl_form(pTHX_ const char* pat, ...)
2404  
2405  can be used any place a string (char *) is required:
2406  
2407      char * s = Perl_form("%d.%d",major,minor);
2408  
2409  Uses a single private buffer so if you want to format several strings you
2410  must explicitly copy the earlier strings away (and free the copies when you
2411  are done).
2412  
2413      char*    form(const char* pat, ...)
2414  
2415  =for hackers
2416  Found in file util.c
2417  
2418  =item getcwd_sv
2419  X<getcwd_sv>
2420  
2421  Fill the sv with current working directory
2422  
2423      int    getcwd_sv(SV* sv)
2424  
2425  =for hackers
2426  Found in file util.c
2427  
2428  =item my_snprintf
2429  X<my_snprintf>
2430  
2431  The C library C<snprintf> functionality, if available and
2432  standards-compliant (uses C<vsnprintf>, actually).  However, if the
2433  C<vsnprintf> is not available, will unfortunately use the unsafe
2434  C<vsprintf> which can overrun the buffer (there is an overrun check,
2435  but that may be too late).  Consider using C<sv_vcatpvf> instead, or
2436  getting C<vsnprintf>.
2437  
2438      int    my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2439  
2440  =for hackers
2441  Found in file util.c
2442  
2443  =item my_sprintf
2444  X<my_sprintf>
2445  
2446  The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2447  the length of the string written to the buffer. Only rare pre-ANSI systems
2448  need the wrapper function - usually this is a direct call to C<sprintf>.
2449  
2450      int    my_sprintf(char *buffer, const char *pat, ...)
2451  
2452  =for hackers
2453  Found in file util.c
2454  
2455  =item my_vsnprintf
2456  X<my_vsnprintf>
2457  
2458  The C library C<vsnprintf> if available and standards-compliant.
2459  However, if if the C<vsnprintf> is not available, will unfortunately
2460  use the unsafe C<vsprintf> which can overrun the buffer (there is an
2461  overrun check, but that may be too late).  Consider using
2462  C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2463  
2464      int    my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2465  
2466  =for hackers
2467  Found in file util.c
2468  
2469  =item new_version
2470  X<new_version>
2471  
2472  Returns a new version object based on the passed in SV:
2473  
2474      SV *sv = new_version(SV *ver);
2475  
2476  Does not alter the passed in ver SV.  See "upg_version" if you
2477  want to upgrade the SV.
2478  
2479      SV*    new_version(SV *ver)
2480  
2481  =for hackers
2482  Found in file util.c
2483  
2484  =item scan_version
2485  X<scan_version>
2486  
2487  Returns a pointer to the next character after the parsed
2488  version string, as well as upgrading the passed in SV to
2489  an RV.
2490  
2491  Function must be called with an already existing SV like
2492  
2493      sv = newSV(0);
2494      s = scan_version(s, SV *sv, bool qv);
2495  
2496  Performs some preprocessing to the string to ensure that
2497  it has the correct characteristics of a version.  Flags the
2498  object if it contains an underscore (which denotes this
2499  is an alpha version).  The boolean qv denotes that the version
2500  should be interpreted as if it had multiple decimals, even if
2501  it doesn't.
2502  
2503      const char*    scan_version(const char *vstr, SV *sv, bool qv)
2504  
2505  =for hackers
2506  Found in file util.c
2507  
2508  =item strEQ
2509  X<strEQ>
2510  
2511  Test two strings to see if they are equal.  Returns true or false.
2512  
2513      bool    strEQ(char* s1, char* s2)
2514  
2515  =for hackers
2516  Found in file handy.h
2517  
2518  =item strGE
2519  X<strGE>
2520  
2521  Test two strings to see if the first, C<s1>, is greater than or equal to
2522  the second, C<s2>.  Returns true or false.
2523  
2524      bool    strGE(char* s1, char* s2)
2525  
2526  =for hackers
2527  Found in file handy.h
2528  
2529  =item strGT
2530  X<strGT>
2531  
2532  Test two strings to see if the first, C<s1>, is greater than the second,
2533  C<s2>.  Returns true or false.
2534  
2535      bool    strGT(char* s1, char* s2)
2536  
2537  =for hackers
2538  Found in file handy.h
2539  
2540  =item strLE
2541  X<strLE>
2542  
2543  Test two strings to see if the first, C<s1>, is less than or equal to the
2544  second, C<s2>.  Returns true or false.
2545  
2546      bool    strLE(char* s1, char* s2)
2547  
2548  =for hackers
2549  Found in file handy.h
2550  
2551  =item strLT
2552  X<strLT>
2553  
2554  Test two strings to see if the first, C<s1>, is less than the second,
2555  C<s2>.  Returns true or false.
2556  
2557      bool    strLT(char* s1, char* s2)
2558  
2559  =for hackers
2560  Found in file handy.h
2561  
2562  =item strNE
2563  X<strNE>
2564  
2565  Test two strings to see if they are different.  Returns true or
2566  false.
2567  
2568      bool    strNE(char* s1, char* s2)
2569  
2570  =for hackers
2571  Found in file handy.h
2572  
2573  =item strnEQ
2574  X<strnEQ>
2575  
2576  Test two strings to see if they are equal.  The C<len> parameter indicates
2577  the number of bytes to compare.  Returns true or false. (A wrapper for
2578  C<strncmp>).
2579  
2580      bool    strnEQ(char* s1, char* s2, STRLEN len)
2581  
2582  =for hackers
2583  Found in file handy.h
2584  
2585  =item strnNE
2586  X<strnNE>
2587  
2588  Test two strings to see if they are different.  The C<len> parameter
2589  indicates the number of bytes to compare.  Returns true or false. (A
2590  wrapper for C<strncmp>).
2591  
2592      bool    strnNE(char* s1, char* s2, STRLEN len)
2593  
2594  =for hackers
2595  Found in file handy.h
2596  
2597  =item sv_destroyable
2598  X<sv_destroyable>
2599  
2600  Dummy routine which reports that object can be destroyed when there is no
2601  sharing module present.  It ignores its single SV argument, and returns
2602  'true'.  Exists to avoid test for a NULL function pointer and because it
2603  could potentially warn under some level of strict-ness.
2604  
2605      bool    sv_destroyable(SV *sv)
2606  
2607  =for hackers
2608  Found in file util.c
2609  
2610  =item sv_nosharing
2611  X<sv_nosharing>
2612  
2613  Dummy routine which "shares" an SV when there is no sharing module present.
2614  Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2615  Exists to avoid test for a NULL function pointer and because it could
2616  potentially warn under some level of strict-ness.
2617  
2618      void    sv_nosharing(SV *sv)
2619  
2620  =for hackers
2621  Found in file util.c
2622  
2623  =item upg_version
2624  X<upg_version>
2625  
2626  In-place upgrade of the supplied SV to a version object.
2627  
2628      SV *sv = upg_version(SV *sv, bool qv);
2629  
2630  Returns a pointer to the upgraded SV.  Set the boolean qv if you want
2631  to force this SV to be interpreted as an "extended" version.
2632  
2633      SV*    upg_version(SV *ver, bool qv)
2634  
2635  =for hackers
2636  Found in file util.c
2637  
2638  =item vcmp
2639  X<vcmp>
2640  
2641  Version object aware cmp.  Both operands must already have been 
2642  converted into version objects.
2643  
2644      int    vcmp(SV *lvs, SV *rvs)
2645  
2646  =for hackers
2647  Found in file util.c
2648  
2649  =item vnormal
2650  X<vnormal>
2651  
2652  Accepts a version object and returns the normalized string
2653  representation.  Call like:
2654  
2655      sv = vnormal(rv);
2656  
2657  NOTE: you can pass either the object directly or the SV
2658  contained within the RV.
2659  
2660      SV*    vnormal(SV *vs)
2661  
2662  =for hackers
2663  Found in file util.c
2664  
2665  =item vnumify
2666  X<vnumify>
2667  
2668  Accepts a version object and returns the normalized floating
2669  point representation.  Call like:
2670  
2671      sv = vnumify(rv);
2672  
2673  NOTE: you can pass either the object directly or the SV
2674  contained within the RV.
2675  
2676      SV*    vnumify(SV *vs)
2677  
2678  =for hackers
2679  Found in file util.c
2680  
2681  =item vstringify
2682  X<vstringify>
2683  
2684  In order to maintain maximum compatibility with earlier versions
2685  of Perl, this function will return either the floating point
2686  notation or the multiple dotted notation, depending on whether
2687  the original version contained 1 or more dots, respectively
2688  
2689      SV*    vstringify(SV *vs)
2690  
2691  =for hackers
2692  Found in file util.c
2693  
2694  =item vverify
2695  X<vverify>
2696  
2697  Validates that the SV contains a valid version object.
2698  
2699      bool vverify(SV *vobj);
2700  
2701  Note that it only confirms the bare minimum structure (so as not to get
2702  confused by derived classes which may contain additional hash entries):
2703  
2704      bool    vverify(SV *vs)
2705  
2706  =for hackers
2707  Found in file util.c
2708  
2709  
2710  =back
2711  
2712  =head1 MRO Functions
2713  
2714  =over 8
2715  
2716  =item mro_get_linear_isa
2717  X<mro_get_linear_isa>
2718  
2719  Returns either C<mro_get_linear_isa_c3> or
2720  C<mro_get_linear_isa_dfs> for the given stash,
2721  dependant upon which MRO is in effect
2722  for that stash.  The return value is a
2723  read-only AV*.
2724  
2725  You are responsible for C<SvREFCNT_inc()> on the
2726  return value if you plan to store it anywhere
2727  semi-permanently (otherwise it might be deleted
2728  out from under you the next time the cache is
2729  invalidated).
2730  
2731      AV*    mro_get_linear_isa(HV* stash)
2732  
2733  =for hackers
2734  Found in file mro.c
2735  
2736  =item mro_method_changed_in
2737  X<mro_method_changed_in>
2738  
2739  Invalidates method caching on any child classes
2740  of the given stash, so that they might notice
2741  the changes in this one.
2742  
2743  Ideally, all instances of C<PL_sub_generation++> in
2744  perl source outside of C<mro.c> should be
2745  replaced by calls to this.
2746  
2747  Perl automatically handles most of the common
2748  ways a method might be redefined.  However, there
2749  are a few ways you could change a method in a stash
2750  without the cache code noticing, in which case you
2751  need to call this method afterwards:
2752  
2753  1) Directly manipulating the stash HV entries from
2754  XS code.
2755  
2756  2) Assigning a reference to a readonly scalar
2757  constant into a stash entry in order to create
2758  a constant subroutine (like constant.pm
2759  does).
2760  
2761  This same method is available from pure perl
2762  via, C<mro::method_changed_in(classname)>.
2763  
2764      void    mro_method_changed_in(HV* stash)
2765  
2766  =for hackers
2767  Found in file mro.c
2768  
2769  
2770  =back
2771  
2772  =head1 Multicall Functions
2773  
2774  =over 8
2775  
2776  =item dMULTICALL
2777  X<dMULTICALL>
2778  
2779  Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2780  
2781          dMULTICALL;
2782  
2783  =for hackers
2784  Found in file cop.h
2785  
2786  =item MULTICALL
2787  X<MULTICALL>
2788  
2789  Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2790  
2791          MULTICALL;
2792  
2793  =for hackers
2794  Found in file cop.h
2795  
2796  =item POP_MULTICALL
2797  X<POP_MULTICALL>
2798  
2799  Closing bracket for a lightweight callback.
2800  See L<perlcall/Lightweight Callbacks>.
2801  
2802          POP_MULTICALL;
2803  
2804  =for hackers
2805  Found in file cop.h
2806  
2807  =item PUSH_MULTICALL
2808  X<PUSH_MULTICALL>
2809  
2810  Opening bracket for a lightweight callback.
2811  See L<perlcall/Lightweight Callbacks>.
2812  
2813          PUSH_MULTICALL;
2814  
2815  =for hackers
2816  Found in file cop.h
2817  
2818  
2819  =back
2820  
2821  =head1 Numeric functions
2822  
2823  =over 8
2824  
2825  =item grok_bin
2826  X<grok_bin>
2827  
2828  converts a string representing a binary number to numeric form.
2829  
2830  On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2831  conversion flags, and I<result> should be NULL or a pointer to an NV.
2832  The scan stops at the end of the string, or the first invalid character.
2833  Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2834  invalid character will also trigger a warning.
2835  On return I<*len> is set to the length of the scanned string,
2836  and I<*flags> gives output flags.
2837  
2838  If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2839  and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2840  returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2841  and writes the value to I<*result> (or the value is discarded if I<result>
2842  is NULL).
2843  
2844  The binary number may optionally be prefixed with "0b" or "b" unless
2845  C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2846  C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2847  number may use '_' characters to separate digits.
2848  
2849      UV    grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2850  
2851  =for hackers
2852  Found in file numeric.c
2853  
2854  =item grok_hex
2855  X<grok_hex>
2856  
2857  converts a string representing a hex number to numeric form.
2858  
2859  On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2860  conversion flags, and I<result> should be NULL or a pointer to an NV.
2861  The scan stops at the end of the string, or the first invalid character.
2862  Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2863  invalid character will also trigger a warning.
2864  On return I<*len> is set to the length of the scanned string,
2865  and I<*flags> gives output flags.
2866  
2867  If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2868  and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2869  returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2870  and writes the value to I<*result> (or the value is discarded if I<result>
2871  is NULL).
2872  
2873  The hex number may optionally be prefixed with "0x" or "x" unless
2874  C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2875  C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2876  number may use '_' characters to separate digits.
2877  
2878      UV    grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2879  
2880  =for hackers
2881  Found in file numeric.c
2882  
2883  =item grok_number
2884  X<grok_number>
2885  
2886  Recognise (or not) a number.  The type of the number is returned
2887  (0 if unrecognised), otherwise it is a bit-ORed combination of
2888  IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2889  IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2890  
2891  If the value of the number can fit an in UV, it is returned in the *valuep
2892  IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2893  will never be set unless *valuep is valid, but *valuep may have been assigned
2894  to during processing even though IS_NUMBER_IN_UV is not set on return.
2895  If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2896  valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2897  
2898  IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2899  seen (in which case *valuep gives the true value truncated to an integer), and
2900  IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2901  absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
2902  number is larger than a UV.
2903  
2904      int    grok_number(const char *pv, STRLEN len, UV *valuep)
2905  
2906  =for hackers
2907  Found in file numeric.c
2908  
2909  =item grok_numeric_radix
2910  X<grok_numeric_radix>
2911  
2912  Scan and skip for a numeric decimal separator (radix).
2913  
2914      bool    grok_numeric_radix(const char **sp, const char *send)
2915  
2916  =for hackers
2917  Found in file numeric.c
2918  
2919  =item grok_oct
2920  X<grok_oct>
2921  
2922  converts a string representing an octal number to numeric form.
2923  
2924  On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2925  conversion flags, and I<result> should be NULL or a pointer to an NV.
2926  The scan stops at the end of the string, or the first invalid character.
2927  Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2928  invalid character will also trigger a warning.
2929  On return I<*len> is set to the length of the scanned string,
2930  and I<*flags> gives output flags.
2931  
2932  If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2933  and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2934  returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2935  and writes the value to I<*result> (or the value is discarded if I<result>
2936  is NULL).
2937  
2938  If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2939  number may use '_' characters to separate digits.
2940  
2941      UV    grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
2942  
2943  =for hackers
2944  Found in file numeric.c
2945  
2946  =item Perl_signbit
2947  X<Perl_signbit>
2948  
2949  Return a non-zero integer if the sign bit on an NV is set, and 0 if
2950  it is not.  
2951  
2952  If Configure detects this system has a signbit() that will work with
2953  our NVs, then we just use it via the #define in perl.h.  Otherwise,
2954  fall back on this implementation.  As a first pass, this gets everything
2955  right except -0.0.  Alas, catching -0.0 is the main use for this function,
2956  so this is not too helpful yet.  Still, at least we have the scaffolding
2957  in place to support other systems, should that prove useful.
2958  
2959  
2960  Configure notes:  This function is called 'Perl_signbit' instead of a
2961  plain 'signbit' because it is easy to imagine a system having a signbit()
2962  function or macro that doesn't happen to work with our particular choice
2963  of NVs.  We shouldn't just re-#define signbit as Perl_signbit and expect
2964  the standard system headers to be happy.  Also, this is a no-context
2965  function (no pTHX_) because Perl_signbit() is usually re-#defined in
2966  perl.h as a simple macro call to the system's signbit().
2967  Users should just always call Perl_signbit().
2968  
2969  NOTE: this function is experimental and may change or be
2970  removed without notice.
2971  
2972      int    Perl_signbit(NV f)
2973  
2974  =for hackers
2975  Found in file numeric.c
2976  
2977  =item scan_bin
2978  X<scan_bin>
2979  
2980  For backwards compatibility. Use C<grok_bin> instead.
2981  
2982      NV    scan_bin(const char* start, STRLEN len, STRLEN* retlen)
2983  
2984  =for hackers
2985  Found in file numeric.c
2986  
2987  =item scan_hex
2988  X<scan_hex>
2989  
2990  For backwards compatibility. Use C<grok_hex> instead.
2991  
2992      NV    scan_hex(const char* start, STRLEN len, STRLEN* retlen)
2993  
2994  =for hackers
2995  Found in file numeric.c
2996  
2997  =item scan_oct
2998  X<scan_oct>
2999  
3000  For backwards compatibility. Use C<grok_oct> instead.
3001  
3002      NV    scan_oct(const char* start, STRLEN len, STRLEN* retlen)
3003  
3004  =for hackers
3005  Found in file numeric.c
3006  
3007  
3008  =back
3009  
3010  =head1 Optree Manipulation Functions
3011  
3012  =over 8
3013  
3014  =item cv_const_sv
3015  X<cv_const_sv>
3016  
3017  If C<cv> is a constant sub eligible for inlining. returns the constant
3018  value returned by the sub.  Otherwise, returns NULL.
3019  
3020  Constant subs can be created with C<newCONSTSUB> or as described in
3021  L<perlsub/"Constant Functions">.
3022  
3023      SV*    cv_const_sv(CV* cv)
3024  
3025  =for hackers
3026  Found in file op.c
3027  
3028  =item newCONSTSUB
3029  X<newCONSTSUB>
3030  
3031  Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
3032  eligible for inlining at compile-time.
3033  
3034      CV*    newCONSTSUB(HV* stash, const char* name, SV* sv)
3035  
3036  =for hackers
3037  Found in file op.c
3038  
3039  =item newXS
3040  X<newXS>
3041  
3042  Used by C<xsubpp> to hook up XSUBs as Perl subs.  I<filename> needs to be
3043  static storage, as it is used directly as CvFILE(), without a copy being made.
3044  
3045  =for hackers
3046  Found in file op.c
3047  
3048  
3049  =back
3050  
3051  =head1 Pad Data Structures
3052  
3053  =over 8
3054  
3055  =item pad_sv
3056  X<pad_sv>
3057  
3058  Get the value at offset po in the current pad.
3059  Use macro PAD_SV instead of calling this function directly.
3060  
3061      SV*    pad_sv(PADOFFSET po)
3062  
3063  =for hackers
3064  Found in file pad.c
3065  
3066  
3067  =back
3068  
3069  =head1 Per-Interpreter Variables
3070  
3071  =over 8
3072  
3073  =item PL_modglobal
3074  X<PL_modglobal>
3075  
3076  C<PL_modglobal> is a general purpose, interpreter global HV for use by
3077  extensions that need to keep information on a per-interpreter basis.
3078  In a pinch, it can also be used as a symbol table for extensions
3079  to share data among each other.  It is a good idea to use keys
3080  prefixed by the package name of the extension that owns the data.
3081  
3082      HV*    PL_modglobal
3083  
3084  =for hackers
3085  Found in file intrpvar.h
3086  
3087  =item PL_na
3088  X<PL_na>
3089  
3090  A convenience variable which is typically used with C<SvPV> when one
3091  doesn't care about the length of the string.  It is usually more efficient
3092  to either declare a local variable and use that instead or to use the
3093  C<SvPV_nolen> macro.
3094  
3095      STRLEN    PL_na
3096  
3097  =for hackers
3098  Found in file intrpvar.h
3099  
3100  =item PL_sv_no
3101  X<PL_sv_no>
3102  
3103  This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
3104  C<&PL_sv_no>.
3105  
3106      SV    PL_sv_no
3107  
3108  =for hackers
3109  Found in file intrpvar.h
3110  
3111  =item PL_sv_undef
3112  X<PL_sv_undef>
3113  
3114  This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
3115  
3116      SV    PL_sv_undef
3117  
3118  =for hackers
3119  Found in file intrpvar.h
3120  
3121  =item PL_sv_yes
3122  X<PL_sv_yes>
3123  
3124  This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
3125  C<&PL_sv_yes>.
3126  
3127      SV    PL_sv_yes
3128  
3129  =for hackers
3130  Found in file intrpvar.h
3131  
3132  
3133  =back
3134  
3135  =head1 REGEXP Functions
3136  
3137  =over 8
3138  
3139  =item SvRX
3140  X<SvRX>
3141  
3142  Convenience macro to get the REGEXP from a SV. This is approximately
3143  equivalent to the following snippet:
3144  
3145      if (SvMAGICAL(sv))
3146          mg_get(sv);
3147      if (SvROK(sv) &&
3148          (tmpsv = (SV*)SvRV(sv)) &&
3149          SvTYPE(tmpsv) == SVt_PVMG &&
3150          (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
3151      {
3152          return (REGEXP *)tmpmg->mg_obj;
3153      }
3154  
3155  NULL will be returned if a REGEXP* is not found.
3156  
3157      REGEXP *    SvRX(SV *sv)
3158  
3159  =for hackers
3160  Found in file regexp.h
3161  
3162  =item SvRXOK
3163  X<SvRXOK>
3164  
3165  Returns a boolean indicating whether the SV contains qr magic
3166  (PERL_MAGIC_qr).
3167  
3168  If you want to do something with the REGEXP* later use SvRX instead
3169  and check for NULL.
3170  
3171      bool    SvRXOK(SV* sv)
3172  
3173  =for hackers
3174  Found in file regexp.h
3175  
3176  
3177  =back
3178  
3179  =head1 Simple Exception Handling Macros
3180  
3181  =over 8
3182  
3183  =item dXCPT
3184  X<dXCPT>
3185  
3186  Set up necessary local variables for exception handling.
3187  See L<perlguts/"Exception Handling">.
3188  
3189          dXCPT;
3190  
3191  =for hackers
3192  Found in file XSUB.h
3193  
3194  =item XCPT_CATCH
3195  X<XCPT_CATCH>
3196  
3197  Introduces a catch block.  See L<perlguts/"Exception Handling">.
3198  
3199  =for hackers
3200  Found in file XSUB.h
3201  
3202  =item XCPT_RETHROW
3203  X<XCPT_RETHROW>
3204  
3205  Rethrows a previously caught exception.  See L<perlguts/"Exception Handling">.
3206  
3207          XCPT_RETHROW;
3208  
3209  =for hackers
3210  Found in file XSUB.h
3211  
3212  =item XCPT_TRY_END
3213  X<XCPT_TRY_END>
3214  
3215  Ends a try block.  See L<perlguts/"Exception Handling">.
3216  
3217  =for hackers
3218  Found in file XSUB.h
3219  
3220  =item XCPT_TRY_START
3221  X<XCPT_TRY_START>
3222  
3223  Starts a try block.  See L<perlguts/"Exception Handling">.
3224  
3225  =for hackers
3226  Found in file XSUB.h
3227  
3228  
3229  =back
3230  
3231  =head1 Stack Manipulation Macros
3232  
3233  =over 8
3234  
3235  =item dMARK
3236  X<dMARK>
3237  
3238  Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
3239  C<dORIGMARK>.
3240  
3241          dMARK;
3242  
3243  =for hackers
3244  Found in file pp.h
3245  
3246  =item dORIGMARK
3247  X<dORIGMARK>
3248  
3249  Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
3250  
3251          dORIGMARK;
3252  
3253  =for hackers
3254  Found in file pp.h
3255  
3256  =item dSP
3257  X<dSP>
3258  
3259  Declares a local copy of perl's stack pointer for the XSUB, available via
3260  the C<SP> macro.  See C<SP>.
3261  
3262          dSP;
3263  
3264  =for hackers
3265  Found in file pp.h
3266  
3267  =item EXTEND
3268  X<EXTEND>
3269  
3270  Used to extend the argument stack for an XSUB's return values. Once
3271  used, guarantees that there is room for at least C<nitems> to be pushed
3272  onto the stack.
3273  
3274      void    EXTEND(SP, int nitems)
3275  
3276  =for hackers
3277  Found in file pp.h
3278  
3279  =item MARK
3280  X<MARK>
3281  
3282  Stack marker variable for the XSUB.  See C<dMARK>.
3283  
3284  =for hackers
3285  Found in file pp.h
3286  
3287  =item mPUSHi
3288  X<mPUSHi>
3289  
3290  Push an integer onto the stack.  The stack must have room for this element.
3291  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi>
3292  and C<XPUSHi>.
3293  
3294      void    mPUSHi(IV iv)
3295  
3296  =for hackers
3297  Found in file pp.h
3298  
3299  =item mPUSHn
3300  X<mPUSHn>
3301  
3302  Push a double onto the stack.  The stack must have room for this element.
3303  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn>
3304  and C<XPUSHn>.
3305  
3306      void    mPUSHn(NV nv)
3307  
3308  =for hackers
3309  Found in file pp.h
3310  
3311  =item mPUSHp
3312  X<mPUSHp>
3313  
3314  Push a string onto the stack.  The stack must have room for this element.
3315  The C<len> indicates the length of the string.  Handles 'set' magic.  Does
3316  not use C<TARG>.  See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3317  
3318      void    mPUSHp(char* str, STRLEN len)
3319  
3320  =for hackers
3321  Found in file pp.h
3322  
3323  =item mPUSHu
3324  X<mPUSHu>
3325  
3326  Push an unsigned integer onto the stack.  The stack must have room for this
3327  element.  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHu>,
3328  C<mXPUSHu> and C<XPUSHu>.
3329  
3330      void    mPUSHu(UV uv)
3331  
3332  =for hackers
3333  Found in file pp.h
3334  
3335  =item mXPUSHi
3336  X<mXPUSHi>
3337  
3338  Push an integer onto the stack, extending the stack if necessary.  Handles
3339  'set' magic.  Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and
3340  C<PUSHi>.
3341  
3342      void    mXPUSHi(IV iv)
3343  
3344  =for hackers
3345  Found in file pp.h
3346  
3347  =item mXPUSHn
3348  X<mXPUSHn>
3349  
3350  Push a double onto the stack, extending the stack if necessary.  Handles
3351  'set' magic.  Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and
3352  C<PUSHn>.
3353  
3354      void    mXPUSHn(NV nv)
3355  
3356  =for hackers
3357  Found in file pp.h
3358  
3359  =item mXPUSHp
3360  X<mXPUSHp>
3361  
3362  Push a string onto the stack, extending the stack if necessary.  The C<len>
3363  indicates the length of the string.  Handles 'set' magic.  Does not use
3364  C<TARG>.  See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
3365  
3366      void    mXPUSHp(char* str, STRLEN len)
3367  
3368  =for hackers
3369  Found in file pp.h
3370  
3371  =item mXPUSHu
3372  X<mXPUSHu>
3373  
3374  Push an unsigned integer onto the stack, extending the stack if necessary.
3375  Handles 'set' magic.  Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu>
3376  and C<PUSHu>.
3377  
3378      void    mXPUSHu(UV uv)
3379  
3380  =for hackers
3381  Found in file pp.h
3382  
3383  =item ORIGMARK
3384  X<ORIGMARK>
3385  
3386  The original stack mark for the XSUB.  See C<dORIGMARK>.
3387  
3388  =for hackers
3389  Found in file pp.h
3390  
3391  =item POPi
3392  X<POPi>
3393  
3394  Pops an integer off the stack.
3395  
3396      IV    POPi
3397  
3398  =for hackers
3399  Found in file pp.h
3400  
3401  =item POPl
3402  X<POPl>
3403  
3404  Pops a long off the stack.
3405  
3406      long    POPl
3407  
3408  =for hackers
3409  Found in file pp.h
3410  
3411  =item POPn
3412  X<POPn>
3413  
3414  Pops a double off the stack.
3415  
3416      NV    POPn
3417  
3418  =for hackers
3419  Found in file pp.h
3420  
3421  =item POPp
3422  X<POPp>
3423  
3424  Pops a string off the stack. Deprecated. New code should use POPpx.
3425  
3426      char*    POPp
3427  
3428  =for hackers
3429  Found in file pp.h
3430  
3431  =item POPpbytex
3432  X<POPpbytex>
3433  
3434  Pops a string off the stack which must consist of bytes i.e. characters < 256.
3435  
3436      char*    POPpbytex
3437  
3438  =for hackers
3439  Found in file pp.h
3440  
3441  =item POPpx
3442  X<POPpx>
3443  
3444  Pops a string off the stack.
3445  
3446      char*    POPpx
3447  
3448  =for hackers
3449  Found in file pp.h
3450  
3451  =item POPs
3452  X<POPs>
3453  
3454  Pops an SV off the stack.
3455  
3456      SV*    POPs
3457  
3458  =for hackers
3459  Found in file pp.h
3460  
3461  =item PUSHi
3462  X<PUSHi>
3463  
3464  Push an integer onto the stack.  The stack must have room for this element.
3465  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3466  called to declare it.  Do not call multiple C<TARG>-oriented macros to 
3467  return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
3468  C<mXPUSHi>.
3469  
3470      void    PUSHi(IV iv)
3471  
3472  =for hackers
3473  Found in file pp.h
3474  
3475  =item PUSHMARK
3476  X<PUSHMARK>
3477  
3478  Opening bracket for arguments on a callback.  See C<PUTBACK> and
3479  L<perlcall>.
3480  
3481      void    PUSHMARK(SP)
3482  
3483  =for hackers
3484  Found in file pp.h
3485  
3486  =item PUSHmortal
3487  X<PUSHmortal>
3488  
3489  Push a new mortal SV onto the stack.  The stack must have room for this
3490  element.  Does not handle 'set' magic.  Does not use C<TARG>.  See also
3491  C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3492  
3493      void    PUSHmortal()
3494  
3495  =for hackers
3496  Found in file pp.h
3497  
3498  =item PUSHn
3499  X<PUSHn>
3500  
3501  Push a double onto the stack.  The stack must have room for this element.
3502  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3503  called to declare it.  Do not call multiple C<TARG>-oriented macros to
3504  return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
3505  C<mXPUSHn>.
3506  
3507      void    PUSHn(NV nv)
3508  
3509  =for hackers
3510  Found in file pp.h
3511  
3512  =item PUSHp
3513  X<PUSHp>
3514  
3515  Push a string onto the stack.  The stack must have room for this element.
3516  The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
3517  C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
3518  call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3519  C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
3520  
3521      void    PUSHp(char* str, STRLEN len)
3522  
3523  =for hackers
3524  Found in file pp.h
3525  
3526  =item PUSHs
3527  X<PUSHs>
3528  
3529  Push an SV onto the stack.  The stack must have room for this element.
3530  Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
3531  C<XPUSHs> and C<XPUSHmortal>.
3532  
3533      void    PUSHs(SV* sv)
3534  
3535  =for hackers
3536  Found in file pp.h
3537  
3538  =item PUSHu
3539  X<PUSHu>
3540  
3541  Push an unsigned integer onto the stack.  The stack must have room for this
3542  element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3543  should be called to declare it.  Do not call multiple C<TARG>-oriented
3544  macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
3545  C<XPUSHu> and C<mXPUSHu>.
3546  
3547      void    PUSHu(UV uv)
3548  
3549  =for hackers
3550  Found in file pp.h
3551  
3552  =item PUTBACK
3553  X<PUTBACK>
3554  
3555  Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
3556  See C<PUSHMARK> and L<perlcall> for other uses.
3557  
3558          PUTBACK;
3559  
3560  =for hackers
3561  Found in file pp.h
3562  
3563  =item SP
3564  X<SP>
3565  
3566  Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
3567  C<SPAGAIN>.
3568  
3569  =for hackers
3570  Found in file pp.h
3571  
3572  =item SPAGAIN
3573  X<SPAGAIN>
3574  
3575  Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
3576  
3577          SPAGAIN;
3578  
3579  =for hackers
3580  Found in file pp.h
3581  
3582  =item XPUSHi
3583  X<XPUSHi>
3584  
3585  Push an integer onto the stack, extending the stack if necessary.  Handles
3586  'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3587  declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3588  from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
3589  
3590      void    XPUSHi(IV iv)
3591  
3592  =for hackers
3593  Found in file pp.h
3594  
3595  =item XPUSHmortal
3596  X<XPUSHmortal>
3597  
3598  Push a new mortal SV onto the stack, extending the stack if necessary.  Does
3599  not handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHs>,
3600  C<PUSHmortal> and C<PUSHs>.
3601  
3602      void    XPUSHmortal()
3603  
3604  =for hackers
3605  Found in file pp.h
3606  
3607  =item XPUSHn
3608  X<XPUSHn>
3609  
3610  Push a double onto the stack, extending the stack if necessary.  Handles
3611  'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3612  declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3613  from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
3614  
3615      void    XPUSHn(NV nv)
3616  
3617  =for hackers
3618  Found in file pp.h
3619  
3620  =item XPUSHp
3621  X<XPUSHp>
3622  
3623  Push a string onto the stack, extending the stack if necessary.  The C<len>
3624  indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
3625  C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
3626  multiple C<TARG>-oriented macros to return lists from XSUB's - see
3627  C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
3628  
3629      void    XPUSHp(char* str, STRLEN len)
3630  
3631  =for hackers
3632  Found in file pp.h
3633  
3634  =item XPUSHs
3635  X<XPUSHs>
3636  
3637  Push an SV onto the stack, extending the stack if necessary.  Does not
3638  handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
3639  C<PUSHs> and C<PUSHmortal>.
3640  
3641      void    XPUSHs(SV* sv)
3642  
3643  =for hackers
3644  Found in file pp.h
3645  
3646  =item XPUSHu
3647  X<XPUSHu>
3648  
3649  Push an unsigned integer onto the stack, extending the stack if necessary.
3650  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3651  called to declare it.  Do not call multiple C<TARG>-oriented macros to
3652  return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
3653  C<mPUSHu>.
3654  
3655      void    XPUSHu(UV uv)
3656  
3657  =for hackers
3658  Found in file pp.h
3659  
3660  =item XSRETURN
3661  X<XSRETURN>
3662  
3663  Return from XSUB, indicating number of items on the stack.  This is usually
3664  handled by C<xsubpp>.
3665  
3666      void    XSRETURN(int nitems)
3667  
3668  =for hackers
3669  Found in file XSUB.h
3670  
3671  =item XSRETURN_EMPTY
3672  X<XSRETURN_EMPTY>
3673  
3674  Return an empty list from an XSUB immediately.
3675  
3676          XSRETURN_EMPTY;
3677  
3678  =for hackers
3679  Found in file XSUB.h
3680  
3681  =item XSRETURN_IV
3682  X<XSRETURN_IV>
3683  
3684  Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3685  
3686      void    XSRETURN_IV(IV iv)
3687  
3688  =for hackers
3689  Found in file XSUB.h
3690  
3691  =item XSRETURN_NO
3692  X<XSRETURN_NO>
3693  
3694  Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3695  
3696          XSRETURN_NO;
3697  
3698  =for hackers
3699  Found in file XSUB.h
3700  
3701  =item XSRETURN_NV
3702  X<XSRETURN_NV>
3703  
3704  Return a double from an XSUB immediately.  Uses C<XST_mNV>.
3705  
3706      void    XSRETURN_NV(NV nv)
3707  
3708  =for hackers
3709  Found in file XSUB.h
3710  
3711  =item XSRETURN_PV
3712  X<XSRETURN_PV>
3713  
3714  Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3715  
3716      void    XSRETURN_PV(char* str)
3717  
3718  =for hackers
3719  Found in file XSUB.h
3720  
3721  =item XSRETURN_UNDEF
3722  X<XSRETURN_UNDEF>
3723  
3724  Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3725  
3726          XSRETURN_UNDEF;
3727  
3728  =for hackers
3729  Found in file XSUB.h
3730  
3731  =item XSRETURN_UV
3732  X<XSRETURN_UV>
3733  
3734  Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
3735  
3736      void    XSRETURN_UV(IV uv)
3737  
3738  =for hackers
3739  Found in file XSUB.h
3740  
3741  =item XSRETURN_YES
3742  X<XSRETURN_YES>
3743  
3744  Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3745  
3746          XSRETURN_YES;
3747  
3748  =for hackers
3749  Found in file XSUB.h
3750  
3751  =item XST_mIV
3752  X<XST_mIV>
3753  
3754  Place an integer into the specified position C<pos> on the stack.  The
3755  value is stored in a new mortal SV.
3756  
3757      void    XST_mIV(int pos, IV iv)
3758  
3759  =for hackers
3760  Found in file XSUB.h
3761  
3762  =item XST_mNO
3763  X<XST_mNO>
3764  
3765  Place C<&PL_sv_no> into the specified position C<pos> on the
3766  stack.
3767  
3768      void    XST_mNO(int pos)
3769  
3770  =for hackers
3771  Found in file XSUB.h
3772  
3773  =item XST_mNV
3774  X<XST_mNV>
3775  
3776  Place a double into the specified position C<pos> on the stack.  The value
3777  is stored in a new mortal SV.
3778  
3779      void    XST_mNV(int pos, NV nv)
3780  
3781  =for hackers
3782  Found in file XSUB.h
3783  
3784  =item XST_mPV
3785  X<XST_mPV>
3786  
3787  Place a copy of a string into the specified position C<pos> on the stack. 
3788  The value is stored in a new mortal SV.
3789  
3790      void    XST_mPV(int pos, char* str)
3791  
3792  =for hackers
3793  Found in file XSUB.h
3794  
3795  =item XST_mUNDEF
3796  X<XST_mUNDEF>
3797  
3798  Place C<&PL_sv_undef> into the specified position C<pos> on the
3799  stack.
3800  
3801      void    XST_mUNDEF(int pos)
3802  
3803  =for hackers
3804  Found in file XSUB.h
3805  
3806  =item XST_mYES
3807  X<XST_mYES>
3808  
3809  Place C<&PL_sv_yes> into the specified position C<pos> on the
3810  stack.
3811  
3812      void    XST_mYES(int pos)
3813  
3814  =for hackers
3815  Found in file XSUB.h
3816  
3817  
3818  =back
3819  
3820  =head1 SV Flags
3821  
3822  =over 8
3823  
3824  =item svtype
3825  X<svtype>
3826  
3827  An enum of flags for Perl types.  These are found in the file B<sv.h>
3828  in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3829  
3830  =for hackers
3831  Found in file sv.h
3832  
3833  =item SVt_IV
3834  X<SVt_IV>
3835  
3836  Integer type flag for scalars.  See C<svtype>.
3837  
3838  =for hackers
3839  Found in file sv.h
3840  
3841  =item SVt_NV
3842  X<SVt_NV>
3843  
3844  Double type flag for scalars.  See C<svtype>.
3845  
3846  =for hackers
3847  Found in file sv.h
3848  
3849  =item SVt_PV
3850  X<SVt_PV>
3851  
3852  Pointer type flag for scalars.  See C<svtype>.
3853  
3854  =for hackers
3855  Found in file sv.h
3856  
3857  =item SVt_PVAV
3858  X<SVt_PVAV>
3859  
3860  Type flag for arrays.  See C<svtype>.
3861  
3862  =for hackers
3863  Found in file sv.h
3864  
3865  =item SVt_PVCV
3866  X<SVt_PVCV>
3867  
3868  Type flag for code refs.  See C<svtype>.
3869  
3870  =for hackers
3871  Found in file sv.h
3872  
3873  =item SVt_PVHV
3874  X<SVt_PVHV>
3875  
3876  Type flag for hashes.  See C<svtype>.
3877  
3878  =for hackers
3879  Found in file sv.h
3880  
3881  =item SVt_PVMG
3882  X<SVt_PVMG>
3883  
3884  Type flag for blessed scalars.  See C<svtype>.
3885  
3886  =for hackers
3887  Found in file sv.h
3888  
3889  
3890  =back
3891  
3892  =head1 SV Manipulation Functions
3893  
3894  =over 8
3895  
3896  =item get_sv
3897  X<get_sv>
3898  
3899  Returns the SV of the specified Perl scalar.  If C<create> is set and the
3900  Perl variable does not exist then it will be created.  If C<create> is not
3901  set and the variable does not exist then NULL is returned.
3902  
3903  NOTE: the perl_ form of this function is deprecated.
3904  
3905      SV*    get_sv(const char* name, I32 create)
3906  
3907  =for hackers
3908  Found in file perl.c
3909  
3910  =item newRV_inc
3911  X<newRV_inc>
3912  
3913  Creates an RV wrapper for an SV.  The reference count for the original SV is
3914  incremented.
3915  
3916      SV*    newRV_inc(SV* sv)
3917  
3918  =for hackers
3919  Found in file sv.h
3920  
3921  =item SvCUR
3922  X<SvCUR>
3923  
3924  Returns the length of the string which is in the SV.  See C<SvLEN>.
3925  
3926      STRLEN    SvCUR(SV* sv)
3927  
3928  =for hackers
3929  Found in file sv.h
3930  
3931  =item SvCUR_set
3932  X<SvCUR_set>
3933  
3934  Set the current length of the string which is in the SV.  See C<SvCUR>
3935  and C<SvIV_set>.
3936  
3937      void    SvCUR_set(SV* sv, STRLEN len)
3938  
3939  =for hackers
3940  Found in file sv.h
3941  
3942  =item SvEND
3943  X<SvEND>
3944  
3945  Returns a pointer to the last character in the string which is in the SV.
3946  See C<SvCUR>.  Access the character as *(SvEND(sv)).
3947  
3948      char*    SvEND(SV* sv)
3949  
3950  =for hackers
3951  Found in file sv.h
3952  
3953  =item SvGAMAGIC
3954  X<SvGAMAGIC>
3955  
3956  Returns true if the SV has get magic or overloading. If either is true then
3957  the scalar is active data, and has the potential to return a new value every
3958  time it is accessed. Hence you must be careful to only read it once per user
3959  logical operation and work with that returned value. If neither is true then
3960  the scalar's value cannot change unless written to.
3961  
3962      char*    SvGAMAGIC(SV* sv)
3963  
3964  =for hackers
3965  Found in file sv.h
3966  
3967  =item SvGROW
3968  X<SvGROW>
3969  
3970  Expands the character buffer in the SV so that it has room for the
3971  indicated number of bytes (remember to reserve space for an extra trailing
3972  NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
3973  Returns a pointer to the character buffer.
3974  
3975      char *    SvGROW(SV* sv, STRLEN len)
3976  
3977  =for hackers
3978  Found in file sv.h
3979  
3980  =item SvIOK
3981  X<SvIOK>
3982  
3983  Returns a U32 value indicating whether the SV contains an integer.
3984  
3985      U32    SvIOK(SV* sv)
3986  
3987  =for hackers
3988  Found in file sv.h
3989  
3990  =item SvIOKp
3991  X<SvIOKp>
3992  
3993  Returns a U32 value indicating whether the SV contains an integer.  Checks
3994  the B<private> setting.  Use C<SvIOK>.
3995  
3996      U32    SvIOKp(SV* sv)
3997  
3998  =for hackers
3999  Found in file sv.h
4000  
4001  =item SvIOK_notUV
4002  X<SvIOK_notUV>
4003  
4004  Returns a boolean indicating whether the SV contains a signed integer.
4005  
4006      bool    SvIOK_notUV(SV* sv)
4007  
4008  =for hackers
4009  Found in file sv.h
4010  
4011  =item SvIOK_off
4012  X<SvIOK_off>
4013  
4014  Unsets the IV status of an SV.
4015  
4016      void    SvIOK_off(SV* sv)
4017  
4018  =for hackers
4019  Found in file sv.h
4020  
4021  =item SvIOK_on
4022  X<SvIOK_on>
4023  
4024  Tells an SV that it is an integer.
4025  
4026      void    SvIOK_on(SV* sv)
4027  
4028  =for hackers
4029  Found in file sv.h
4030  
4031  =item SvIOK_only
4032  X<SvIOK_only>
4033  
4034  Tells an SV that it is an integer and disables all other OK bits.
4035  
4036      void    SvIOK_only(SV* sv)
4037  
4038  =for hackers
4039  Found in file sv.h
4040  
4041  =item SvIOK_only_UV
4042  X<SvIOK_only_UV>
4043  
4044  Tells and SV that it is an unsigned integer and disables all other OK bits.
4045  
4046      void    SvIOK_only_UV(SV* sv)
4047  
4048  =for hackers
4049  Found in file sv.h
4050  
4051  =item SvIOK_UV
4052  X<SvIOK_UV>
4053  
4054  Returns a boolean indicating whether the SV contains an unsigned integer.
4055  
4056      bool    SvIOK_UV(SV* sv)
4057  
4058  =for hackers
4059  Found in file sv.h
4060  
4061  =item SvIsCOW
4062  X<SvIsCOW>
4063  
4064  Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
4065  hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
4066  COW)
4067  
4068      bool    SvIsCOW(SV* sv)
4069  
4070  =for hackers
4071  Found in file sv.h
4072  
4073  =item SvIsCOW_shared_hash
4074  X<SvIsCOW_shared_hash>
4075  
4076  Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
4077  scalar.
4078  
4079      bool    SvIsCOW_shared_hash(SV* sv)
4080  
4081  =for hackers
4082  Found in file sv.h
4083  
4084  =item SvIV
4085  X<SvIV>
4086  
4087  Coerces the given SV to an integer and returns it. See C<SvIVx> for a
4088  version which guarantees to evaluate sv only once.
4089  
4090      IV    SvIV(SV* sv)
4091  
4092  =for hackers
4093  Found in file sv.h
4094  
4095  =item SvIVX
4096  X<SvIVX>
4097  
4098  Returns the raw value in the SV's IV slot, without checks or conversions.
4099  Only use when you are sure SvIOK is true. See also C<SvIV()>.
4100  
4101      IV    SvIVX(SV* sv)
4102  
4103  =for hackers
4104  Found in file sv.h
4105  
4106  =item SvIVx
4107  X<SvIVx>
4108  
4109  Coerces the given SV to an integer and returns it. Guarantees to evaluate
4110  C<sv> only once. Only use this if C<sv> is an expression with side effects,
4111  otherwise use the more efficient C<SvIV>.
4112  
4113      IV    SvIVx(SV* sv)
4114  
4115  =for hackers
4116  Found in file sv.h
4117  
4118  =item SvIV_nomg
4119  X<SvIV_nomg>
4120  
4121  Like C<SvIV> but doesn't process magic.
4122  
4123      IV    SvIV_nomg(SV* sv)
4124  
4125  =for hackers
4126  Found in file sv.h
4127  
4128  =item SvIV_set
4129  X<SvIV_set>
4130  
4131  Set the value of the IV pointer in sv to val.  It is possible to perform
4132  the same function of this macro with an lvalue assignment to C<SvIVX>.
4133  With future Perls, however, it will be more efficient to use 
4134  C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
4135  
4136      void    SvIV_set(SV* sv, IV val)
4137  
4138  =for hackers
4139  Found in file sv.h
4140  
4141  =item SvLEN
4142  X<SvLEN>
4143  
4144  Returns the size of the string buffer in the SV, not including any part
4145  attributable to C<SvOOK>.  See C<SvCUR>.
4146  
4147      STRLEN    SvLEN(SV* sv)
4148  
4149  =for hackers
4150  Found in file sv.h
4151  
4152  =item SvLEN_set
4153  X<SvLEN_set>
4154  
4155  Set the actual length of the string which is in the SV.  See C<SvIV_set>.
4156  
4157      void    SvLEN_set(SV* sv, STRLEN len)
4158  
4159  =for hackers
4160  Found in file sv.h
4161  
4162  =item SvMAGIC_set
4163  X<SvMAGIC_set>
4164  
4165  Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
4166  
4167      void    SvMAGIC_set(SV* sv, MAGIC* val)
4168  
4169  =for hackers
4170  Found in file sv.h
4171  
4172  =item SvNIOK
4173  X<SvNIOK>
4174  
4175  Returns a U32 value indicating whether the SV contains a number, integer or
4176  double.
4177  
4178      U32    SvNIOK(SV* sv)
4179  
4180  =for hackers
4181  Found in file sv.h
4182  
4183  =item SvNIOKp
4184  X<SvNIOKp>
4185  
4186  Returns a U32 value indicating whether the SV contains a number, integer or
4187  double.  Checks the B<private> setting.  Use C<SvNIOK>.
4188  
4189      U32    SvNIOKp(SV* sv)
4190  
4191  =for hackers
4192  Found in file sv.h
4193  
4194  =item SvNIOK_off
4195  X<SvNIOK_off>
4196  
4197  Unsets the NV/IV status of an SV.
4198  
4199      void    SvNIOK_off(SV* sv)
4200  
4201  =for hackers
4202  Found in file sv.h
4203  
4204  =item SvNOK
4205  X<SvNOK>
4206  
4207  Returns a U32 value indicating whether the SV contains a double.
4208  
4209      U32    SvNOK(SV* sv)
4210  
4211  =for hackers
4212  Found in file sv.h
4213  
4214  =item SvNOKp
4215  X<SvNOKp>
4216  
4217  Returns a U32 value indicating whether the SV contains a double.  Checks the
4218  B<private> setting.  Use C<SvNOK>.
4219  
4220      U32    SvNOKp(SV* sv)
4221  
4222  =for hackers
4223  Found in file sv.h
4224  
4225  =item SvNOK_off
4226  X<SvNOK_off>
4227  
4228  Unsets the NV status of an SV.
4229  
4230      void    SvNOK_off(SV* sv)
4231  
4232  =for hackers
4233  Found in file sv.h
4234  
4235  =item SvNOK_on
4236  X<SvNOK_on>
4237  
4238  Tells an SV that it is a double.
4239  
4240      void    SvNOK_on(SV* sv)
4241  
4242  =for hackers
4243  Found in file sv.h
4244  
4245  =item SvNOK_only
4246  X<SvNOK_only>
4247  
4248  Tells an SV that it is a double and disables all other OK bits.
4249  
4250      void    SvNOK_only(SV* sv)
4251  
4252  =for hackers
4253  Found in file sv.h
4254  
4255  =item SvNV
4256  X<SvNV>
4257  
4258  Coerce the given SV to a double and return it. See C<SvNVx> for a version
4259  which guarantees to evaluate sv only once.
4260  
4261      NV    SvNV(SV* sv)
4262  
4263  =for hackers
4264  Found in file sv.h
4265  
4266  =item SvNVX
4267  X<SvNVX>
4268  
4269  Returns the raw value in the SV's NV slot, without checks or conversions.
4270  Only use when you are sure SvNOK is true. See also C<SvNV()>.
4271  
4272      NV    SvNVX(SV* sv)
4273  
4274  =for hackers
4275  Found in file sv.h
4276  
4277  =item SvNVx
4278  X<SvNVx>
4279  
4280  Coerces the given SV to a double and returns it. Guarantees to evaluate
4281  C<sv> only once. Only use this if C<sv> is an expression with side effects,
4282  otherwise use the more efficient C<SvNV>.
4283  
4284      NV    SvNVx(SV* sv)
4285  
4286  =for hackers
4287  Found in file sv.h
4288  
4289  =item SvNV_set
4290  X<SvNV_set>
4291  
4292  Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
4293  
4294      void    SvNV_set(SV* sv, NV val)
4295  
4296  =for hackers
4297  Found in file sv.h
4298  
4299  =item SvOK
4300  X<SvOK>
4301  
4302  Returns a U32 value indicating whether the value is an SV. It also tells
4303  whether the value is defined or not.
4304  
4305      U32    SvOK(SV* sv)
4306  
4307  =for hackers
4308  Found in file sv.h
4309  
4310  =item SvOOK
4311  X<SvOOK>
4312  
4313  Returns a U32 indicating whether the SvIVX is a valid offset value for
4314  the SvPVX.  This hack is used internally to speed up removal of characters
4315  from the beginning of a SvPV.  When SvOOK is true, then the start of the
4316  allocated string buffer is really (SvPVX - SvIVX).
4317  
4318      U32    SvOOK(SV* sv)
4319  
4320  =for hackers
4321  Found in file sv.h
4322  
4323  =item SvPOK
4324  X<SvPOK>
4325  
4326  Returns a U32 value indicating whether the SV contains a character
4327  string.
4328  
4329      U32    SvPOK(SV* sv)
4330  
4331  =for hackers
4332  Found in file sv.h
4333  
4334  =item SvPOKp
4335  X<SvPOKp>
4336  
4337  Returns a U32 value indicating whether the SV contains a character string.
4338  Checks the B<private> setting.  Use C<SvPOK>.
4339  
4340      U32    SvPOKp(SV* sv)
4341  
4342  =for hackers
4343  Found in file sv.h
4344  
4345  =item SvPOK_off
4346  X<SvPOK_off>
4347  
4348  Unsets the PV status of an SV.
4349  
4350      void    SvPOK_off(SV* sv)
4351  
4352  =for hackers
4353  Found in file sv.h
4354  
4355  =item SvPOK_on
4356  X<SvPOK_on>
4357  
4358  Tells an SV that it is a string.
4359  
4360      void    SvPOK_on(SV* sv)
4361  
4362  =for hackers
4363  Found in file sv.h
4364  
4365  =item SvPOK_only
4366  X<SvPOK_only>
4367  
4368  Tells an SV that it is a string and disables all other OK bits.
4369  Will also turn off the UTF-8 status.
4370  
4371      void    SvPOK_only(SV* sv)
4372  
4373  =for hackers
4374  Found in file sv.h
4375  
4376  =item SvPOK_only_UTF8
4377  X<SvPOK_only_UTF8>
4378  
4379  Tells an SV that it is a string and disables all other OK bits,
4380  and leaves the UTF-8 status as it was.
4381  
4382      void    SvPOK_only_UTF8(SV* sv)
4383  
4384  =for hackers
4385  Found in file sv.h
4386  
4387  =item SvPV
4388  X<SvPV>
4389  
4390  Returns a pointer to the string in the SV, or a stringified form of
4391  the SV if the SV does not contain a string.  The SV may cache the
4392  stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
4393  C<SvPVx> for a version which guarantees to evaluate sv only once.
4394  
4395      char*    SvPV(SV* sv, STRLEN len)
4396  
4397  =for hackers
4398  Found in file sv.h
4399  
4400  =item SvPVbyte
4401  X<SvPVbyte>
4402  
4403  Like C<SvPV>, but converts sv to byte representation first if necessary.
4404  
4405      char*    SvPVbyte(SV* sv, STRLEN len)
4406  
4407  =for hackers
4408  Found in file sv.h
4409  
4410  =item SvPVbytex
4411  X<SvPVbytex>
4412  
4413  Like C<SvPV>, but converts sv to byte representation first if necessary.
4414  Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4415  otherwise.
4416  
4417      char*    SvPVbytex(SV* sv, STRLEN len)
4418  
4419  =for hackers
4420  Found in file sv.h
4421  
4422  =item SvPVbytex_force
4423  X<SvPVbytex_force>
4424  
4425  Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4426  Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4427  otherwise.
4428  
4429      char*    SvPVbytex_force(SV* sv, STRLEN len)
4430  
4431  =for hackers
4432  Found in file sv.h
4433  
4434  =item SvPVbyte_force
4435  X<SvPVbyte_force>
4436  
4437  Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4438  
4439      char*    SvPVbyte_force(SV* sv, STRLEN len)
4440  
4441  =for hackers
4442  Found in file sv.h
4443  
4444  =item SvPVbyte_nolen
4445  X<SvPVbyte_nolen>
4446  
4447  Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4448  
4449      char*    SvPVbyte_nolen(SV* sv)
4450  
4451  =for hackers
4452  Found in file sv.h
4453  
4454  =item SvPVutf8
4455  X<SvPVutf8>
4456  
4457  Like C<SvPV>, but converts sv to utf8 first if necessary.
4458  
4459      char*    SvPVutf8(SV* sv, STRLEN len)
4460  
4461  =for hackers
4462  Found in file sv.h
4463  
4464  =item SvPVutf8x
4465  X<SvPVutf8x>
4466  
4467  Like C<SvPV>, but converts sv to utf8 first if necessary.
4468  Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4469  otherwise.
4470  
4471      char*    SvPVutf8x(SV* sv, STRLEN len)
4472  
4473  =for hackers
4474  Found in file sv.h
4475  
4476  =item SvPVutf8x_force
4477  X<SvPVutf8x_force>
4478  
4479  Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4480  Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4481  otherwise.
4482  
4483      char*    SvPVutf8x_force(SV* sv, STRLEN len)
4484  
4485  =for hackers
4486  Found in file sv.h
4487  
4488  =item SvPVutf8_force
4489  X<SvPVutf8_force>
4490  
4491  Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4492  
4493      char*    SvPVutf8_force(SV* sv, STRLEN len)
4494  
4495  =for hackers
4496  Found in file sv.h
4497  
4498  =item SvPVutf8_nolen
4499  X<SvPVutf8_nolen>
4500  
4501  Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4502  
4503      char*    SvPVutf8_nolen(SV* sv)
4504  
4505  =for hackers
4506  Found in file sv.h
4507  
4508  =item SvPVX
4509  X<SvPVX>
4510  
4511  Returns a pointer to the physical string in the SV.  The SV must contain a
4512  string.
4513  
4514      char*    SvPVX(SV* sv)
4515  
4516  =for hackers
4517  Found in file sv.h
4518  
4519  =item SvPVx
4520  X<SvPVx>
4521  
4522  A version of C<SvPV> which guarantees to evaluate C<sv> only once.
4523  Only use this if C<sv> is an expression with side effects, otherwise use the
4524  more efficient C<SvPVX>.
4525  
4526      char*    SvPVx(SV* sv, STRLEN len)
4527  
4528  =for hackers
4529  Found in file sv.h
4530  
4531  =item SvPV_force
4532  X<SvPV_force>
4533  
4534  Like C<SvPV> but will force the SV into containing just a string
4535  (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4536  directly.
4537  
4538      char*    SvPV_force(SV* sv, STRLEN len)
4539  
4540  =for hackers
4541  Found in file sv.h
4542  
4543  =item SvPV_force_nomg
4544  X<SvPV_force_nomg>
4545  
4546  Like C<SvPV> but will force the SV into containing just a string
4547  (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4548  directly. Doesn't process magic.
4549  
4550      char*    SvPV_force_nomg(SV* sv, STRLEN len)
4551  
4552  =for hackers
4553  Found in file sv.h
4554  
4555  =item SvPV_nolen
4556  X<SvPV_nolen>
4557  
4558  Returns a pointer to the string in the SV, or a stringified form of
4559  the SV if the SV does not contain a string.  The SV may cache the
4560  stringified form becoming C<SvPOK>.  Handles 'get' magic.
4561  
4562      char*    SvPV_nolen(SV* sv)
4563  
4564  =for hackers
4565  Found in file sv.h
4566  
4567  =item SvPV_nomg
4568  X<SvPV_nomg>
4569  
4570  Like C<SvPV> but doesn't process magic.
4571  
4572      char*    SvPV_nomg(SV* sv, STRLEN len)
4573  
4574  =for hackers
4575  Found in file sv.h
4576  
4577  =item SvPV_set
4578  X<SvPV_set>
4579  
4580  Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
4581  
4582      void    SvPV_set(SV* sv, char* val)
4583  
4584  =for hackers
4585  Found in file sv.h
4586  
4587  =item SvREFCNT
4588  X<SvREFCNT>
4589  
4590  Returns the value of the object's reference count.
4591  
4592      U32    SvREFCNT(SV* sv)
4593  
4594  =for hackers
4595  Found in file sv.h
4596  
4597  =item SvREFCNT_dec
4598  X<SvREFCNT_dec>
4599  
4600  Decrements the reference count of the given SV.
4601  
4602      void    SvREFCNT_dec(SV* sv)
4603  
4604  =for hackers
4605  Found in file sv.h
4606  
4607  =item SvREFCNT_inc
4608  X<SvREFCNT_inc>
4609  
4610  Increments the reference count of the given SV.
4611  
4612  All of the following SvREFCNT_inc* macros are optimized versions of
4613  SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4614  
4615      SV*    SvREFCNT_inc(SV* sv)
4616  
4617  =for hackers
4618  Found in file sv.h
4619  
4620  =item SvREFCNT_inc_NN
4621  X<SvREFCNT_inc_NN>
4622  
4623  Same as SvREFCNT_inc, but can only be used if you know I<sv>
4624  is not NULL.  Since we don't have to check the NULLness, it's faster
4625  and smaller.
4626  
4627      SV*    SvREFCNT_inc_NN(SV* sv)
4628  
4629  =for hackers
4630  Found in file sv.h
4631  
4632  =item SvREFCNT_inc_simple
4633  X<SvREFCNT_inc_simple>
4634  
4635  Same as SvREFCNT_inc, but can only be used with expressions without side
4636  effects.  Since we don't have to store a temporary value, it's faster.
4637  
4638      SV*    SvREFCNT_inc_simple(SV* sv)
4639  
4640  =for hackers
4641  Found in file sv.h
4642  
4643  =item SvREFCNT_inc_simple_NN
4644  X<SvREFCNT_inc_simple_NN>
4645  
4646  Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4647  is not NULL.  Since we don't have to check the NULLness, it's faster
4648  and smaller.
4649  
4650      SV*    SvREFCNT_inc_simple_NN(SV* sv)
4651  
4652  =for hackers
4653  Found in file sv.h
4654  
4655  =item SvREFCNT_inc_simple_void
4656  X<SvREFCNT_inc_simple_void>
4657  
4658  Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4659  return value.  The macro doesn't need to return a meaningful value.
4660  
4661      void    SvREFCNT_inc_simple_void(SV* sv)
4662  
4663  =for hackers
4664  Found in file sv.h
4665  
4666  =item SvREFCNT_inc_simple_void_NN
4667  X<SvREFCNT_inc_simple_void_NN>
4668  
4669  Same as SvREFCNT_inc, but can only be used if you don't need the return
4670  value, and you know that I<sv> is not NULL.  The macro doesn't need
4671  to return a meaningful value, or check for NULLness, so it's smaller
4672  and faster.
4673  
4674      void    SvREFCNT_inc_simple_void_NN(SV* sv)
4675  
4676  =for hackers
4677  Found in file sv.h
4678  
4679  =item SvREFCNT_inc_void
4680  X<SvREFCNT_inc_void>
4681  
4682  Same as SvREFCNT_inc, but can only be used if you don't need the
4683  return value.  The macro doesn't need to return a meaningful value.
4684  
4685      void    SvREFCNT_inc_void(SV* sv)
4686  
4687  =for hackers
4688  Found in file sv.h
4689  
4690  =item SvREFCNT_inc_void_NN
4691  X<SvREFCNT_inc_void_NN>
4692  
4693  Same as SvREFCNT_inc, but can only be used if you don't need the return
4694  value, and you know that I<sv> is not NULL.  The macro doesn't need
4695  to return a meaningful value, or check for NULLness, so it's smaller
4696  and faster.
4697  
4698      void    SvREFCNT_inc_void_NN(SV* sv)
4699  
4700  =for hackers
4701  Found in file sv.h
4702  
4703  =item SvROK
4704  X<SvROK>
4705  
4706  Tests if the SV is an RV.
4707  
4708      U32    SvROK(SV* sv)
4709  
4710  =for hackers
4711  Found in file sv.h
4712  
4713  =item SvROK_off
4714  X<SvROK_off>
4715  
4716  Unsets the RV status of an SV.
4717  
4718      void    SvROK_off(SV* sv)
4719  
4720  =for hackers
4721  Found in file sv.h
4722  
4723  =item SvROK_on
4724  X<SvROK_on>
4725  
4726  Tells an SV that it is an RV.
4727  
4728      void    SvROK_on(SV* sv)
4729  
4730  =for hackers
4731  Found in file sv.h
4732  
4733  =item SvRV
4734  X<SvRV>
4735  
4736  Dereferences an RV to return the SV.
4737  
4738      SV*    SvRV(SV* sv)
4739  
4740  =for hackers
4741  Found in file sv.h
4742  
4743  =item SvRV_set
4744  X<SvRV_set>
4745  
4746  Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
4747  
4748      void    SvRV_set(SV* sv, SV* val)
4749  
4750  =for hackers
4751  Found in file sv.h
4752  
4753  =item SvSTASH
4754  X<SvSTASH>
4755  
4756  Returns the stash of the SV.
4757  
4758      HV*    SvSTASH(SV* sv)
4759  
4760  =for hackers
4761  Found in file sv.h
4762  
4763  =item SvSTASH_set
4764  X<SvSTASH_set>
4765  
4766  Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
4767  
4768      void    SvSTASH_set(SV* sv, HV* val)
4769  
4770  =for hackers
4771  Found in file sv.h
4772  
4773  =item SvTAINT
4774  X<SvTAINT>
4775  
4776  Taints an SV if tainting is enabled.
4777  
4778      void    SvTAINT(SV* sv)
4779  
4780  =for hackers
4781  Found in file sv.h
4782  
4783  =item SvTAINTED
4784  X<SvTAINTED>
4785  
4786  Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4787  not.
4788  
4789      bool    SvTAINTED(SV* sv)
4790  
4791  =for hackers
4792  Found in file sv.h
4793  
4794  =item SvTAINTED_off
4795  X<SvTAINTED_off>
4796  
4797  Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4798  some of Perl's fundamental security features. XS module authors should not
4799  use this function unless they fully understand all the implications of
4800  unconditionally untainting the value. Untainting should be done in the
4801  standard perl fashion, via a carefully crafted regexp, rather than directly
4802  untainting variables.
4803  
4804      void    SvTAINTED_off(SV* sv)
4805  
4806  =for hackers
4807  Found in file sv.h
4808  
4809  =item SvTAINTED_on
4810  X<SvTAINTED_on>
4811  
4812  Marks an SV as tainted if tainting is enabled.
4813  
4814      void    SvTAINTED_on(SV* sv)
4815  
4816  =for hackers
4817  Found in file sv.h
4818  
4819  =item SvTRUE
4820  X<SvTRUE>
4821  
4822  Returns a boolean indicating whether Perl would evaluate the SV as true or
4823  false, defined or undefined.  Does not handle 'get' magic.
4824  
4825      bool    SvTRUE(SV* sv)
4826  
4827  =for hackers
4828  Found in file sv.h
4829  
4830  =item SvTYPE
4831  X<SvTYPE>
4832  
4833  Returns the type of the SV.  See C<svtype>.
4834  
4835      svtype    SvTYPE(SV* sv)
4836  
4837  =for hackers
4838  Found in file sv.h
4839  
4840  =item SvUOK
4841  X<SvUOK>
4842  
4843  Returns a boolean indicating whether the SV contains an unsigned integer.
4844  
4845      bool    SvUOK(SV* sv)
4846  
4847  =for hackers
4848  Found in file sv.h
4849  
4850  =item SvUPGRADE
4851  X<SvUPGRADE>
4852  
4853  Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
4854  perform the upgrade if necessary.  See C<svtype>.
4855  
4856      void    SvUPGRADE(SV* sv, svtype type)
4857  
4858  =for hackers
4859  Found in file sv.h
4860  
4861  =item SvUTF8
4862  X<SvUTF8>
4863  
4864  Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
4865  Call this after SvPV() in case any call to string overloading updates the
4866  internal flag.
4867  
4868      U32    SvUTF8(SV* sv)
4869  
4870  =for hackers
4871  Found in file sv.h
4872  
4873  =item SvUTF8_off
4874  X<SvUTF8_off>
4875  
4876  Unsets the UTF-8 status of an SV.
4877  
4878      void    SvUTF8_off(SV *sv)
4879  
4880  =for hackers
4881  Found in file sv.h
4882  
4883  =item SvUTF8_on
4884  X<SvUTF8_on>
4885  
4886  Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4887  Do not use frivolously.
4888  
4889      void    SvUTF8_on(SV *sv)
4890  
4891  =for hackers
4892  Found in file sv.h
4893  
4894  =item SvUV
4895  X<SvUV>
4896  
4897  Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
4898  for a version which guarantees to evaluate sv only once.
4899  
4900      UV    SvUV(SV* sv)
4901  
4902  =for hackers
4903  Found in file sv.h
4904  
4905  =item SvUVX
4906  X<SvUVX>
4907  
4908  Returns the raw value in the SV's UV slot, without checks or conversions.
4909  Only use when you are sure SvIOK is true. See also C<SvUV()>.
4910  
4911      UV    SvUVX(SV* sv)
4912  
4913  =for hackers
4914  Found in file sv.h
4915  
4916  =item SvUVx
4917  X<SvUVx>
4918  
4919  Coerces the given SV to an unsigned integer and returns it. Guarantees to
4920  C<sv> only once. Only use this if C<sv> is an expression with side effects,
4921  otherwise use the more efficient C<SvUV>.
4922  
4923      UV    SvUVx(SV* sv)
4924  
4925  =for hackers
4926  Found in file sv.h
4927  
4928  =item SvUV_nomg
4929  X<SvUV_nomg>
4930  
4931  Like C<SvUV> but doesn't process magic.
4932  
4933      UV    SvUV_nomg(SV* sv)
4934  
4935  =for hackers
4936  Found in file sv.h
4937  
4938  =item SvUV_set
4939  X<SvUV_set>
4940  
4941  Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
4942  
4943      void    SvUV_set(SV* sv, UV val)
4944  
4945  =for hackers
4946  Found in file sv.h
4947  
4948  =item SvVOK
4949  X<SvVOK>
4950  
4951  Returns a boolean indicating whether the SV contains a v-string.
4952  
4953      bool    SvVOK(SV* sv)
4954  
4955  =for hackers
4956  Found in file sv.h
4957  
4958  =item sv_catpvn_nomg
4959  X<sv_catpvn_nomg>
4960  
4961  Like C<sv_catpvn> but doesn't process magic.
4962  
4963      void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
4964  
4965  =for hackers
4966  Found in file sv.h
4967  
4968  =item sv_catsv_nomg
4969  X<sv_catsv_nomg>
4970  
4971  Like C<sv_catsv> but doesn't process magic.
4972  
4973      void    sv_catsv_nomg(SV* dsv, SV* ssv)
4974  
4975  =for hackers
4976  Found in file sv.h
4977  
4978  =item sv_derived_from
4979  X<sv_derived_from>
4980  
4981  Returns a boolean indicating whether the SV is derived from the specified class
4982  I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
4983  normal Perl method.
4984  
4985      bool    sv_derived_from(SV* sv, const char* name)
4986  
4987  =for hackers
4988  Found in file universal.c
4989  
4990  =item sv_does
4991  X<sv_does>
4992  
4993  Returns a boolean indicating whether the SV performs a specific, named role.
4994  The SV can be a Perl object or the name of a Perl class.
4995  
4996      bool    sv_does(SV* sv, const char* name)
4997  
4998  =for hackers
4999  Found in file universal.c
5000  
5001  =item sv_report_used
5002  X<sv_report_used>
5003  
5004  Dump the contents of all SVs not yet freed. (Debugging aid).
5005  
5006      void    sv_report_used()
5007  
5008  =for hackers
5009  Found in file sv.c
5010  
5011  =item sv_setsv_nomg
5012  X<sv_setsv_nomg>
5013  
5014  Like C<sv_setsv> but doesn't process magic.
5015  
5016      void    sv_setsv_nomg(SV* dsv, SV* ssv)
5017  
5018  =for hackers
5019  Found in file sv.h
5020  
5021  
5022  =back
5023  
5024  =head1 SV-Body Allocation
5025  
5026  =over 8
5027  
5028  =item looks_like_number
5029  X<looks_like_number>
5030  
5031  Test if the content of an SV looks like a number (or is a number).
5032  C<Inf> and C<Infinity> are treated as numbers (so will not issue a
5033  non-numeric warning), even if your atof() doesn't grok them.
5034  
5035      I32    looks_like_number(SV* sv)
5036  
5037  =for hackers
5038  Found in file sv.c
5039  
5040  =item newRV_noinc
5041  X<newRV_noinc>
5042  
5043  Creates an RV wrapper for an SV.  The reference count for the original
5044  SV is B<not> incremented.
5045  
5046      SV*    newRV_noinc(SV* sv)
5047  
5048  =for hackers
5049  Found in file sv.c
5050  
5051  =item newSV
5052  X<newSV>
5053  
5054  Creates a new SV.  A non-zero C<len> parameter indicates the number of
5055  bytes of preallocated string space the SV should have.  An extra byte for a
5056  trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
5057  space is allocated.)  The reference count for the new SV is set to 1.
5058  
5059  In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5060  parameter, I<x>, a debug aid which allowed callers to identify themselves.
5061  This aid has been superseded by a new build option, PERL_MEM_LOG (see
5062  L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
5063  modules supporting older perls.
5064  
5065      SV*    newSV(STRLEN len)
5066  
5067  =for hackers
5068  Found in file sv.c
5069  
5070  =item newSVhek
5071  X<newSVhek>
5072  
5073  Creates a new SV from the hash key structure.  It will generate scalars that
5074  point to the shared string table where possible. Returns a new (undefined)
5075  SV if the hek is NULL.
5076  
5077      SV*    newSVhek(const HEK *hek)
5078  
5079  =for hackers
5080  Found in file sv.c
5081  
5082  =item newSViv
5083  X<newSViv>
5084  
5085  Creates a new SV and copies an integer into it.  The reference count for the
5086  SV is set to 1.
5087  
5088      SV*    newSViv(IV i)
5089  
5090  =for hackers
5091  Found in file sv.c
5092  
5093  =item newSVnv
5094  X<newSVnv>
5095  
5096  Creates a new SV and copies a floating point value into it.
5097  The reference count for the SV is set to 1.
5098  
5099      SV*    newSVnv(NV n)
5100  
5101  =for hackers
5102  Found in file sv.c
5103  
5104  =item newSVpv
5105  X<newSVpv>
5106  
5107  Creates a new SV and copies a string into it.  The reference count for the
5108  SV is set to 1.  If C<len> is zero, Perl will compute the length using
5109  strlen().  For efficiency, consider using C<newSVpvn> instead.
5110  
5111      SV*    newSVpv(const char* s, STRLEN len)
5112  
5113  =for hackers
5114  Found in file sv.c
5115  
5116  =item newSVpvf
5117  X<newSVpvf>
5118  
5119  Creates a new SV and initializes it with the string formatted like
5120  C<sprintf>.
5121  
5122      SV*    newSVpvf(const char* pat, ...)
5123  
5124  =for hackers
5125  Found in file sv.c
5126  
5127  =item newSVpvn
5128  X<newSVpvn>
5129  
5130  Creates a new SV and copies a string into it.  The reference count for the
5131  SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5132  string.  You are responsible for ensuring that the source string is at least
5133  C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5134  
5135      SV*    newSVpvn(const char* s, STRLEN len)
5136  
5137  =for hackers
5138  Found in file sv.c
5139  
5140  =item newSVpvn_share
5141  X<newSVpvn_share>
5142  
5143  Creates a new SV with its SvPVX_const pointing to a shared string in the string
5144  table. If the string does not already exist in the table, it is created
5145  first.  Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
5146  value is used; otherwise the hash is computed. The string's hash can be later
5147  be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
5148  that as the string table is used for shared hash keys these strings will have
5149  SvPVX_const == HeKEY and hash lookup will avoid string compare.
5150  
5151      SV*    newSVpvn_share(const char* s, I32 len, U32 hash)
5152  
5153  =for hackers
5154  Found in file sv.c
5155  
5156  =item newSVpvs
5157  X<newSVpvs>
5158  
5159  Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5160  
5161      SV*    newSVpvs(const char* s)
5162  
5163  =for hackers
5164  Found in file handy.h
5165  
5166  =item newSVpvs_share
5167  X<newSVpvs_share>
5168  
5169  Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5170  pair and omits the hash parameter.
5171  
5172      SV*    newSVpvs_share(const char* s)
5173  
5174  =for hackers
5175  Found in file handy.h
5176  
5177  =item newSVrv
5178  X<newSVrv>
5179  
5180  Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
5181  it will be upgraded to one.  If C<classname> is non-null then the new SV will
5182  be blessed in the specified package.  The new SV is returned and its
5183  reference count is 1.
5184  
5185      SV*    newSVrv(SV* rv, const char* classname)
5186  
5187  =for hackers
5188  Found in file sv.c
5189  
5190  =item newSVsv
5191  X<newSVsv>
5192  
5193  Creates a new SV which is an exact duplicate of the original SV.
5194  (Uses C<sv_setsv>).
5195  
5196      SV*    newSVsv(SV* old)
5197  
5198  =for hackers
5199  Found in file sv.c
5200  
5201  =item newSVuv
5202  X<newSVuv>
5203  
5204  Creates a new SV and copies an unsigned integer into it.
5205  The reference count for the SV is set to 1.
5206  
5207      SV*    newSVuv(UV u)
5208  
5209  =for hackers
5210  Found in file sv.c
5211  
5212  =item newSV_type
5213  X<newSV_type>
5214  
5215  Creates a new SV, of the type specified.  The reference count for the new SV
5216  is set to 1.
5217  
5218      SV*    newSV_type(svtype type)
5219  
5220  =for hackers
5221  Found in file sv.c
5222  
5223  =item sv_2bool
5224  X<sv_2bool>
5225  
5226  This function is only called on magical items, and is only used by
5227  sv_true() or its macro equivalent.
5228  
5229      bool    sv_2bool(SV* sv)
5230  
5231  =for hackers
5232  Found in file sv.c
5233  
5234  =item sv_2cv
5235  X<sv_2cv>
5236  
5237  Using various gambits, try to get a CV from an SV; in addition, try if
5238  possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5239  The flags in C<lref> are passed to sv_fetchsv.
5240  
5241      CV*    sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
5242  
5243  =for hackers
5244  Found in file sv.c
5245  
5246  =item sv_2io
5247  X<sv_2io>
5248  
5249  Using various gambits, try to get an IO from an SV: the IO slot if its a
5250  GV; or the recursive result if we're an RV; or the IO slot of the symbol
5251  named after the PV if we're a string.
5252  
5253      IO*    sv_2io(SV* sv)
5254  
5255  =for hackers
5256  Found in file sv.c
5257  
5258  =item sv_2iv_flags
5259  X<sv_2iv_flags>
5260  
5261  Return the integer value of an SV, doing any necessary string
5262  conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5263  Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5264  
5265      IV    sv_2iv_flags(SV* sv, I32 flags)
5266  
5267  =for hackers
5268  Found in file sv.c
5269  
5270  =item sv_2mortal
5271  X<sv_2mortal>
5272  
5273  Marks an existing SV as mortal.  The SV will be destroyed "soon", either
5274  by an explicit call to FREETMPS, or by an implicit call at places such as
5275  statement boundaries.  SvTEMP() is turned on which means that the SV's
5276  string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5277  and C<sv_mortalcopy>.
5278  
5279      SV*    sv_2mortal(SV* sv)
5280  
5281  =for hackers
5282  Found in file sv.c
5283  
5284  =item sv_2nv
5285  X<sv_2nv>
5286  
5287  Return the num value of an SV, doing any necessary string or integer
5288  conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5289  macros.
5290  
5291      NV    sv_2nv(SV* sv)
5292  
5293  =for hackers
5294  Found in file sv.c
5295  
5296  =item sv_2pvbyte
5297  X<sv_2pvbyte>
5298  
5299  Return a pointer to the byte-encoded representation of the SV, and set *lp
5300  to its length.  May cause the SV to be downgraded from UTF-8 as a
5301  side-effect.
5302  
5303  Usually accessed via the C<SvPVbyte> macro.
5304  
5305      char*    sv_2pvbyte(SV* sv, STRLEN* lp)
5306  
5307  =for hackers
5308  Found in file sv.c
5309  
5310  =item sv_2pvutf8
5311  X<sv_2pvutf8>
5312  
5313  Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5314  to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
5315  
5316  Usually accessed via the C<SvPVutf8> macro.
5317  
5318      char*    sv_2pvutf8(SV* sv, STRLEN* lp)
5319  
5320  =for hackers
5321  Found in file sv.c
5322  
5323  =item sv_2pv_flags
5324  X<sv_2pv_flags>
5325  
5326  Returns a pointer to the string value of an SV, and sets *lp to its length.
5327  If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5328  if necessary.
5329  Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5330  usually end up here too.
5331  
5332      char*    sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
5333  
5334  =for hackers
5335  Found in file sv.c
5336  
5337  =item sv_2uv_flags
5338  X<sv_2uv_flags>
5339  
5340  Return the unsigned integer value of an SV, doing any necessary string
5341  conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5342  Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5343  
5344      UV    sv_2uv_flags(SV* sv, I32 flags)
5345  
5346  =for hackers
5347  Found in file sv.c
5348  
5349  =item sv_backoff
5350  X<sv_backoff>
5351  
5352  Remove any string offset. You should normally use the C<SvOOK_off> macro
5353  wrapper instead.
5354  
5355      int    sv_backoff(SV* sv)
5356  
5357  =for hackers
5358  Found in file sv.c
5359  
5360  =item sv_bless
5361  X<sv_bless>
5362  
5363  Blesses an SV into a specified package.  The SV must be an RV.  The package
5364  must be designated by its stash (see C<gv_stashpv()>).  The reference count
5365  of the SV is unaffected.
5366  
5367      SV*    sv_bless(SV* sv, HV* stash)
5368  
5369  =for hackers
5370  Found in file sv.c
5371  
5372  =item sv_catpv
5373  X<sv_catpv>
5374  
5375  Concatenates the string onto the end of the string which is in the SV.
5376  If the SV has the UTF-8 status set, then the bytes appended should be
5377  valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
5378  
5379      void    sv_catpv(SV* sv, const char* ptr)
5380  
5381  =for hackers
5382  Found in file sv.c
5383  
5384  =item sv_catpvf
5385  X<sv_catpvf>
5386  
5387  Processes its arguments like C<sprintf> and appends the formatted
5388  output to an SV.  If the appended data contains "wide" characters
5389  (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5390  and characters >255 formatted with %c), the original SV might get
5391  upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
5392  C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5393  valid UTF-8; if the original SV was bytes, the pattern should be too.
5394  
5395      void    sv_catpvf(SV* sv, const char* pat, ...)
5396  
5397  =for hackers
5398  Found in file sv.c
5399  
5400  =item sv_catpvf_mg
5401  X<sv_catpvf_mg>
5402  
5403  Like C<sv_catpvf>, but also handles 'set' magic.
5404  
5405      void    sv_catpvf_mg(SV *sv, const char* pat, ...)
5406  
5407  =for hackers
5408  Found in file sv.c
5409  
5410  =item sv_catpvn
5411  X<sv_catpvn>
5412  
5413  Concatenates the string onto the end of the string which is in the SV.  The
5414  C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5415  status set, then the bytes appended should be valid UTF-8.
5416  Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
5417  
5418      void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
5419  
5420  =for hackers
5421  Found in file sv.c
5422  
5423  =item sv_catpvn_flags
5424  X<sv_catpvn_flags>
5425  
5426  Concatenates the string onto the end of the string which is in the SV.  The
5427  C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5428  status set, then the bytes appended should be valid UTF-8.
5429  If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5430  appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5431  in terms of this function.
5432  
5433      void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
5434  
5435  =for hackers
5436  Found in file sv.c
5437  
5438  =item sv_catpvs
5439  X<sv_catpvs>
5440  
5441  Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5442  
5443      void    sv_catpvs(SV* sv, const char* s)
5444  
5445  =for hackers
5446  Found in file handy.h
5447  
5448  =item sv_catpv_mg
5449  X<sv_catpv_mg>
5450  
5451  Like C<sv_catpv>, but also handles 'set' magic.
5452  
5453      void    sv_catpv_mg(SV *sv, const char *ptr)
5454  
5455  =for hackers
5456  Found in file sv.c
5457  
5458  =item sv_catsv
5459  X<sv_catsv>
5460  
5461  Concatenates the string from SV C<ssv> onto the end of the string in
5462  SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
5463  not 'set' magic.  See C<sv_catsv_mg>.
5464  
5465      void    sv_catsv(SV* dsv, SV* ssv)
5466  
5467  =for hackers
5468  Found in file sv.c
5469  
5470  =item sv_catsv_flags
5471  X<sv_catsv_flags>
5472  
5473  Concatenates the string from SV C<ssv> onto the end of the string in
5474  SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
5475  bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5476  and C<sv_catsv_nomg> are implemented in terms of this function.
5477  
5478      void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
5479  
5480  =for hackers
5481  Found in file sv.c
5482  
5483  =item sv_chop
5484  X<sv_chop>
5485  
5486  Efficient removal of characters from the beginning of the string buffer.
5487  SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5488  the string buffer.  The C<ptr> becomes the first character of the adjusted
5489  string. Uses the "OOK hack".
5490  Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5491  refer to the same chunk of data.
5492  
5493      void    sv_chop(SV* sv, const char* ptr)
5494  
5495  =for hackers
5496  Found in file sv.c
5497  
5498  =item sv_clear
5499  X<sv_clear>
5500  
5501  Clear an SV: call any destructors, free up any memory used by the body,
5502  and free the body itself. The SV's head is I<not> freed, although
5503  its type is set to all 1's so that it won't inadvertently be assumed
5504  to be live during global destruction etc.
5505  This function should only be called when REFCNT is zero. Most of the time
5506  you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5507  instead.
5508  
5509      void    sv_clear(SV* sv)
5510  
5511  =for hackers
5512  Found in file sv.c
5513  
5514  =item sv_cmp
5515  X<sv_cmp>
5516  
5517  Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
5518  string in C<sv1> is less than, equal to, or greater than the string in
5519  C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5520  coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
5521  
5522      I32    sv_cmp(SV* sv1, SV* sv2)
5523  
5524  =for hackers
5525  Found in file sv.c
5526  
5527  =item sv_cmp_locale
5528  X<sv_cmp_locale>
5529  
5530  Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5531  'use bytes' aware, handles get magic, and will coerce its args to strings
5532  if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
5533  
5534      I32    sv_cmp_locale(SV* sv1, SV* sv2)
5535  
5536  =for hackers
5537  Found in file sv.c
5538  
5539  =item sv_collxfrm
5540  X<sv_collxfrm>
5541  
5542  Add Collate Transform magic to an SV if it doesn't already have it.
5543  
5544  Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
5545  scalar data of the variable, but transformed to such a format that a normal
5546  memory comparison can be used to compare the data according to the locale
5547  settings.
5548  
5549      char*    sv_collxfrm(SV* sv, STRLEN* nxp)
5550  
5551  =for hackers
5552  Found in file sv.c
5553  
5554  =item sv_copypv
5555  X<sv_copypv>
5556  
5557  Copies a stringified representation of the source SV into the
5558  destination SV.  Automatically performs any necessary mg_get and
5559  coercion of numeric values into strings.  Guaranteed to preserve
5560  UTF8 flag even from overloaded objects.  Similar in nature to
5561  sv_2pv[_flags] but operates directly on an SV instead of just the
5562  string.  Mostly uses sv_2pv_flags to do its work, except when that
5563  would lose the UTF-8'ness of the PV.
5564  
5565      void    sv_copypv(SV* dsv, SV* ssv)
5566  
5567  =for hackers
5568  Found in file sv.c
5569  
5570  =item sv_dec
5571  X<sv_dec>
5572  
5573  Auto-decrement of the value in the SV, doing string to numeric conversion
5574  if necessary. Handles 'get' magic.
5575  
5576      void    sv_dec(SV* sv)
5577  
5578  =for hackers
5579  Found in file sv.c
5580  
5581  =item sv_eq
5582  X<sv_eq>
5583  
5584  Returns a boolean indicating whether the strings in the two SVs are
5585  identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5586  coerce its args to strings if necessary.
5587  
5588      I32    sv_eq(SV* sv1, SV* sv2)
5589  
5590  =for hackers
5591  Found in file sv.c
5592  
5593  =item sv_force_normal_flags
5594  X<sv_force_normal_flags>
5595  
5596  Undo various types of fakery on an SV: if the PV is a shared string, make
5597  a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
5598  an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
5599  we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
5600  then a copy-on-write scalar drops its PV buffer (if any) and becomes
5601  SvPOK_off rather than making a copy. (Used where this scalar is about to be
5602  set to some other value.) In addition, the C<flags> parameter gets passed to
5603  C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
5604  with flags set to 0.
5605  
5606      void    sv_force_normal_flags(SV *sv, U32 flags)
5607  
5608  =for hackers
5609  Found in file sv.c
5610  
5611  =item sv_free
5612  X<sv_free>
5613  
5614  Decrement an SV's reference count, and if it drops to zero, call
5615  C<sv_clear> to invoke destructors and free up any memory used by
5616  the body; finally, deallocate the SV's head itself.
5617  Normally called via a wrapper macro C<SvREFCNT_dec>.
5618  
5619      void    sv_free(SV* sv)
5620  
5621  =for hackers
5622  Found in file sv.c
5623  
5624  =item sv_gets
5625  X<sv_gets>
5626  
5627  Get a line from the filehandle and store it into the SV, optionally
5628  appending to the currently-stored string.
5629  
5630      char*    sv_gets(SV* sv, PerlIO* fp, I32 append)
5631  
5632  =for hackers
5633  Found in file sv.c
5634  
5635  =item sv_grow
5636  X<sv_grow>
5637  
5638  Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
5639  upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
5640  Use the C<SvGROW> wrapper instead.
5641  
5642      char*    sv_grow(SV* sv, STRLEN newlen)
5643  
5644  =for hackers
5645  Found in file sv.c
5646  
5647  =item sv_inc
5648  X<sv_inc>
5649  
5650  Auto-increment of the value in the SV, doing string to numeric conversion
5651  if necessary. Handles 'get' magic.
5652  
5653      void    sv_inc(SV* sv)
5654  
5655  =for hackers
5656  Found in file sv.c
5657  
5658  =item sv_insert
5659  X<sv_insert>
5660  
5661  Inserts a string at the specified offset/length within the SV. Similar to
5662  the Perl substr() function.
5663  
5664      void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
5665  
5666  =for hackers
5667  Found in file sv.c
5668  
5669  =item sv_isa
5670  X<sv_isa>
5671  
5672  Returns a boolean indicating whether the SV is blessed into the specified
5673  class.  This does not check for subtypes; use C<sv_derived_from> to verify
5674  an inheritance relationship.
5675  
5676      int    sv_isa(SV* sv, const char* name)
5677  
5678  =for hackers
5679  Found in file sv.c
5680  
5681  =item sv_isobject
5682  X<sv_isobject>
5683  
5684  Returns a boolean indicating whether the SV is an RV pointing to a blessed
5685  object.  If the SV is not an RV, or if the object is not blessed, then this
5686  will return false.
5687  
5688      int    sv_isobject(SV* sv)
5689  
5690  =for hackers
5691  Found in file sv.c
5692  
5693  =item sv_len
5694  X<sv_len>
5695  
5696  Returns the length of the string in the SV. Handles magic and type
5697  coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
5698  
5699      STRLEN    sv_len(SV* sv)
5700  
5701  =for hackers
5702  Found in file sv.c
5703  
5704  =item sv_len_utf8
5705  X<sv_len_utf8>
5706  
5707  Returns the number of characters in the string in an SV, counting wide
5708  UTF-8 bytes as a single character. Handles magic and type coercion.
5709  
5710      STRLEN    sv_len_utf8(SV* sv)
5711  
5712  =for hackers
5713  Found in file sv.c
5714  
5715  =item sv_magic
5716  X<sv_magic>
5717  
5718  Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
5719  then adds a new magic item of type C<how> to the head of the magic list.
5720  
5721  See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
5722  handling of the C<name> and C<namlen> arguments.
5723  
5724  You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
5725  to add more than one instance of the same 'how'.
5726  
5727      void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
5728  
5729  =for hackers
5730  Found in file sv.c
5731  
5732  =item sv_magicext
5733  X<sv_magicext>
5734  
5735  Adds magic to an SV, upgrading it if necessary. Applies the
5736  supplied vtable and returns a pointer to the magic added.
5737  
5738  Note that C<sv_magicext> will allow things that C<sv_magic> will not.
5739  In particular, you can add magic to SvREADONLY SVs, and add more than
5740  one instance of the same 'how'.
5741  
5742  If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
5743  stored, if C<namlen> is zero then C<name> is stored as-is and - as another
5744  special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
5745  to contain an C<SV*> and is stored as-is with its REFCNT incremented.
5746  
5747  (This is now used as a subroutine by C<sv_magic>.)
5748  
5749      MAGIC *    sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
5750  
5751  =for hackers
5752  Found in file sv.c
5753  
5754  =item sv_mortalcopy
5755  X<sv_mortalcopy>
5756  
5757  Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
5758  The new SV is marked as mortal. It will be destroyed "soon", either by an
5759  explicit call to FREETMPS, or by an implicit call at places such as
5760  statement boundaries.  See also C<sv_newmortal> and C<sv_2mortal>.
5761  
5762      SV*    sv_mortalcopy(SV* oldsv)
5763  
5764  =for hackers
5765  Found in file sv.c
5766  
5767  =item sv_newmortal
5768  X<sv_newmortal>
5769  
5770  Creates a new null SV which is mortal.  The reference count of the SV is
5771  set to 1. It will be destroyed "soon", either by an explicit call to
5772  FREETMPS, or by an implicit call at places such as statement boundaries.
5773  See also C<sv_mortalcopy> and C<sv_2mortal>.
5774  
5775      SV*    sv_newmortal()
5776  
5777  =for hackers
5778  Found in file sv.c
5779  
5780  =item sv_newref
5781  X<sv_newref>
5782  
5783  Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
5784  instead.
5785  
5786      SV*    sv_newref(SV* sv)
5787  
5788  =for hackers
5789  Found in file sv.c
5790  
5791  =item sv_pos_b2u
5792  X<sv_pos_b2u>
5793  
5794  Converts the value pointed to by offsetp from a count of bytes from the
5795  start of the string, to a count of the equivalent number of UTF-8 chars.
5796  Handles magic and type coercion.
5797  
5798      void    sv_pos_b2u(SV* sv, I32* offsetp)
5799  
5800  =for hackers
5801  Found in file sv.c
5802  
5803  =item sv_pos_u2b
5804  X<sv_pos_u2b>
5805  
5806  Converts the value pointed to by offsetp from a count of UTF-8 chars from
5807  the start of the string, to a count of the equivalent number of bytes; if
5808  lenp is non-zero, it does the same to lenp, but this time starting from
5809  the offset, rather than from the start of the string. Handles magic and
5810  type coercion.
5811  
5812      void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
5813  
5814  =for hackers
5815  Found in file sv.c
5816  
5817  =item sv_pvbyten_force
5818  X<sv_pvbyten_force>
5819  
5820  The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
5821  
5822      char*    sv_pvbyten_force(SV* sv, STRLEN* lp)
5823  
5824  =for hackers
5825  Found in file sv.c
5826  
5827  =item sv_pvn_force
5828  X<sv_pvn_force>
5829  
5830  Get a sensible string out of the SV somehow.
5831  A private implementation of the C<SvPV_force> macro for compilers which
5832  can't cope with complex macro expressions. Always use the macro instead.
5833  
5834      char*    sv_pvn_force(SV* sv, STRLEN* lp)
5835  
5836  =for hackers
5837  Found in file sv.c
5838  
5839  =item sv_pvn_force_flags
5840  X<sv_pvn_force_flags>
5841  
5842  Get a sensible string out of the SV somehow.
5843  If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
5844  appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
5845  implemented in terms of this function.
5846  You normally want to use the various wrapper macros instead: see
5847  C<SvPV_force> and C<SvPV_force_nomg>
5848  
5849      char*    sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
5850  
5851  =for hackers
5852  Found in file sv.c
5853  
5854  =item sv_pvutf8n_force
5855  X<sv_pvutf8n_force>
5856  
5857  The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
5858  
5859      char*    sv_pvutf8n_force(SV* sv, STRLEN* lp)
5860  
5861  =for hackers
5862  Found in file sv.c
5863  
5864  =item sv_reftype
5865  X<sv_reftype>
5866  
5867  Returns a string describing what the SV is a reference to.
5868  
5869      const char*    sv_reftype(const SV* sv, int ob)
5870  
5871  =for hackers
5872  Found in file sv.c
5873  
5874  =item sv_replace
5875  X<sv_replace>
5876  
5877  Make the first argument a copy of the second, then delete the original.
5878  The target SV physically takes over ownership of the body of the source SV
5879  and inherits its flags; however, the target keeps any magic it owns,
5880  and any magic in the source is discarded.
5881  Note that this is a rather specialist SV copying operation; most of the
5882  time you'll want to use C<sv_setsv> or one of its many macro front-ends.
5883  
5884      void    sv_replace(SV* sv, SV* nsv)
5885  
5886  =for hackers
5887  Found in file sv.c
5888  
5889  =item sv_reset
5890  X<sv_reset>
5891  
5892  Underlying implementation for the C<reset> Perl function.
5893  Note that the perl-level function is vaguely deprecated.
5894  
5895      void    sv_reset(const char* s, HV* stash)
5896  
5897  =for hackers
5898  Found in file sv.c
5899  
5900  =item sv_rvweaken
5901  X<sv_rvweaken>
5902  
5903  Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
5904  referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
5905  push a back-reference to this RV onto the array of backreferences
5906  associated with that magic. If the RV is magical, set magic will be
5907  called after the RV is cleared.
5908  
5909      SV*    sv_rvweaken(SV *sv)
5910  
5911  =for hackers
5912  Found in file sv.c
5913  
5914  =item sv_setiv
5915  X<sv_setiv>
5916  
5917  Copies an integer into the given SV, upgrading first if necessary.
5918  Does not handle 'set' magic.  See also C<sv_setiv_mg>.
5919  
5920      void    sv_setiv(SV* sv, IV num)
5921  
5922  =for hackers
5923  Found in file sv.c
5924  
5925  =item sv_setiv_mg
5926  X<sv_setiv_mg>
5927  
5928  Like C<sv_setiv>, but also handles 'set' magic.
5929  
5930      void    sv_setiv_mg(SV *sv, IV i)
5931  
5932  =for hackers
5933  Found in file sv.c
5934  
5935  =item sv_setnv
5936  X<sv_setnv>
5937  
5938  Copies a double into the given SV, upgrading first if necessary.
5939  Does not handle 'set' magic.  See also C<sv_setnv_mg>.
5940  
5941      void    sv_setnv(SV* sv, NV num)
5942  
5943  =for hackers
5944  Found in file sv.c
5945  
5946  =item sv_setnv_mg
5947  X<sv_setnv_mg>
5948  
5949  Like C<sv_setnv>, but also handles 'set' magic.
5950  
5951      void    sv_setnv_mg(SV *sv, NV num)
5952  
5953  =for hackers
5954  Found in file sv.c
5955  
5956  =item sv_setpv
5957  X<sv_setpv>
5958  
5959  Copies a string into an SV.  The string must be null-terminated.  Does not
5960  handle 'set' magic.  See C<sv_setpv_mg>.
5961  
5962      void    sv_setpv(SV* sv, const char* ptr)
5963  
5964  =for hackers
5965  Found in file sv.c
5966  
5967  =item sv_setpvf
5968  X<sv_setpvf>
5969  
5970  Works like C<sv_catpvf> but copies the text into the SV instead of
5971  appending it.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
5972  
5973      void    sv_setpvf(SV* sv, const char* pat, ...)
5974  
5975  =for hackers
5976  Found in file sv.c
5977  
5978  =item sv_setpvf_mg
5979  X<sv_setpvf_mg>
5980  
5981  Like C<sv_setpvf>, but also handles 'set' magic.
5982  
5983      void    sv_setpvf_mg(SV *sv, const char* pat, ...)
5984  
5985  =for hackers
5986  Found in file sv.c
5987  
5988  =item sv_setpviv
5989  X<sv_setpviv>
5990  
5991  Copies an integer into the given SV, also updating its string value.
5992  Does not handle 'set' magic.  See C<sv_setpviv_mg>.
5993  
5994      void    sv_setpviv(SV* sv, IV num)
5995  
5996  =for hackers
5997  Found in file sv.c
5998  
5999  =item sv_setpviv_mg
6000  X<sv_setpviv_mg>
6001  
6002  Like C<sv_setpviv>, but also handles 'set' magic.
6003  
6004      void    sv_setpviv_mg(SV *sv, IV iv)
6005  
6006  =for hackers
6007  Found in file sv.c
6008  
6009  =item sv_setpvn
6010  X<sv_setpvn>
6011  
6012  Copies a string into an SV.  The C<len> parameter indicates the number of
6013  bytes to be copied.  If the C<ptr> argument is NULL the SV will become
6014  undefined.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
6015  
6016      void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
6017  
6018  =for hackers
6019  Found in file sv.c
6020  
6021  =item sv_setpvn_mg
6022  X<sv_setpvn_mg>
6023  
6024  Like C<sv_setpvn>, but also handles 'set' magic.
6025  
6026      void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
6027  
6028  =for hackers
6029  Found in file sv.c
6030  
6031  =item sv_setpvs
6032  X<sv_setpvs>
6033  
6034  Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
6035  
6036      void    sv_setpvs(SV* sv, const char* s)
6037  
6038  =for hackers
6039  Found in file handy.h
6040  
6041  =item sv_setpv_mg
6042  X<sv_setpv_mg>
6043  
6044  Like C<sv_setpv>, but also handles 'set' magic.
6045  
6046      void    sv_setpv_mg(SV *sv, const char *ptr)
6047  
6048  =for hackers
6049  Found in file sv.c
6050  
6051  =item sv_setref_iv
6052  X<sv_setref_iv>
6053  
6054  Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
6055  argument will be upgraded to an RV.  That RV will be modified to point to
6056  the new SV.  The C<classname> argument indicates the package for the
6057  blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6058  will have a reference count of 1, and the RV will be returned.
6059  
6060      SV*    sv_setref_iv(SV* rv, const char* classname, IV iv)
6061  
6062  =for hackers
6063  Found in file sv.c
6064  
6065  =item sv_setref_nv
6066  X<sv_setref_nv>
6067  
6068  Copies a double into a new SV, optionally blessing the SV.  The C<rv>
6069  argument will be upgraded to an RV.  That RV will be modified to point to
6070  the new SV.  The C<classname> argument indicates the package for the
6071  blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6072  will have a reference count of 1, and the RV will be returned.
6073  
6074      SV*    sv_setref_nv(SV* rv, const char* classname, NV nv)
6075  
6076  =for hackers
6077  Found in file sv.c
6078  
6079  =item sv_setref_pv
6080  X<sv_setref_pv>
6081  
6082  Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
6083  argument will be upgraded to an RV.  That RV will be modified to point to
6084  the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
6085  into the SV.  The C<classname> argument indicates the package for the
6086  blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6087  will have a reference count of 1, and the RV will be returned.
6088  
6089  Do not use with other Perl types such as HV, AV, SV, CV, because those
6090  objects will become corrupted by the pointer copy process.
6091  
6092  Note that C<sv_setref_pvn> copies the string while this copies the pointer.
6093  
6094      SV*    sv_setref_pv(SV* rv, const char* classname, void* pv)
6095  
6096  =for hackers
6097  Found in file sv.c
6098  
6099  =item sv_setref_pvn
6100  X<sv_setref_pvn>
6101  
6102  Copies a string into a new SV, optionally blessing the SV.  The length of the
6103  string must be specified with C<n>.  The C<rv> argument will be upgraded to
6104  an RV.  That RV will be modified to point to the new SV.  The C<classname>
6105  argument indicates the package for the blessing.  Set C<classname> to
6106  C<NULL> to avoid the blessing.  The new SV will have a reference count
6107  of 1, and the RV will be returned.
6108  
6109  Note that C<sv_setref_pv> copies the pointer while this copies the string.
6110  
6111      SV*    sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
6112  
6113  =for hackers
6114  Found in file sv.c
6115  
6116  =item sv_setref_uv
6117  X<sv_setref_uv>
6118  
6119  Copies an unsigned integer into a new SV, optionally blessing the SV.  The C<rv>
6120  argument will be upgraded to an RV.  That RV will be modified to point to
6121  the new SV.  The C<classname> argument indicates the package for the
6122  blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6123  will have a reference count of 1, and the RV will be returned.
6124  
6125      SV*    sv_setref_uv(SV* rv, const char* classname, UV uv)
6126  
6127  =for hackers
6128  Found in file sv.c
6129  
6130  =item sv_setsv
6131  X<sv_setsv>
6132  
6133  Copies the contents of the source SV C<ssv> into the destination SV
6134  C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
6135  function if the source SV needs to be reused. Does not handle 'set' magic.
6136  Loosely speaking, it performs a copy-by-value, obliterating any previous
6137  content of the destination.
6138  
6139  You probably want to use one of the assortment of wrappers, such as
6140  C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6141  C<SvSetMagicSV_nosteal>.
6142  
6143      void    sv_setsv(SV* dsv, SV* ssv)
6144  
6145  =for hackers
6146  Found in file sv.c
6147  
6148  =item sv_setsv_flags
6149  X<sv_setsv_flags>
6150  
6151  Copies the contents of the source SV C<ssv> into the destination SV
6152  C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
6153  function if the source SV needs to be reused. Does not handle 'set' magic.
6154  Loosely speaking, it performs a copy-by-value, obliterating any previous
6155  content of the destination.
6156  If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
6157  C<ssv> if appropriate, else not. If the C<flags> parameter has the
6158  C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
6159  and C<sv_setsv_nomg> are implemented in terms of this function.
6160  
6161  You probably want to use one of the assortment of wrappers, such as
6162  C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6163  C<SvSetMagicSV_nosteal>.
6164  
6165  This is the primary function for copying scalars, and most other
6166  copy-ish functions and macros use this underneath.
6167  
6168      void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
6169  
6170  =for hackers
6171  Found in file sv.c
6172  
6173  =item sv_setsv_mg
6174  X<sv_setsv_mg>
6175  
6176  Like C<sv_setsv>, but also handles 'set' magic.
6177  
6178      void    sv_setsv_mg(SV *dstr, SV *sstr)
6179  
6180  =for hackers
6181  Found in file sv.c
6182  
6183  =item sv_setuv
6184  X<sv_setuv>
6185  
6186  Copies an unsigned integer into the given SV, upgrading first if necessary.
6187  Does not handle 'set' magic.  See also C<sv_setuv_mg>.
6188  
6189      void    sv_setuv(SV* sv, UV num)
6190  
6191  =for hackers
6192  Found in file sv.c
6193  
6194  =item sv_setuv_mg
6195  X<sv_setuv_mg>
6196  
6197  Like C<sv_setuv>, but also handles 'set' magic.
6198  
6199      void    sv_setuv_mg(SV *sv, UV u)
6200  
6201  =for hackers
6202  Found in file sv.c
6203  
6204  =item sv_tainted
6205  X<sv_tainted>
6206  
6207  Test an SV for taintedness. Use C<SvTAINTED> instead.
6208      bool    sv_tainted(SV* sv)
6209  
6210  =for hackers
6211  Found in file sv.c
6212  
6213  =item sv_true
6214  X<sv_true>
6215  
6216  Returns true if the SV has a true value by Perl's rules.
6217  Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
6218  instead use an in-line version.
6219  
6220      I32    sv_true(SV *sv)
6221  
6222  =for hackers
6223  Found in file sv.c
6224  
6225  =item sv_unmagic
6226  X<sv_unmagic>
6227  
6228  Removes all magic of type C<type> from an SV.
6229  
6230      int    sv_unmagic(SV* sv, int type)
6231  
6232  =for hackers
6233  Found in file sv.c
6234  
6235  =item sv_unref_flags
6236  X<sv_unref_flags>
6237  
6238  Unsets the RV status of the SV, and decrements the reference count of
6239  whatever was being referenced by the RV.  This can almost be thought of
6240  as a reversal of C<newSVrv>.  The C<cflags> argument can contain
6241  C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
6242  (otherwise the decrementing is conditional on the reference count being
6243  different from one or the reference being a readonly SV).
6244  See C<SvROK_off>.
6245  
6246      void    sv_unref_flags(SV* sv, U32 flags)
6247  
6248  =for hackers
6249  Found in file sv.c
6250  
6251  =item sv_untaint
6252  X<sv_untaint>
6253  
6254  Untaint an SV. Use C<SvTAINTED_off> instead.
6255      void    sv_untaint(SV* sv)
6256  
6257  =for hackers
6258  Found in file sv.c
6259  
6260  =item sv_upgrade
6261  X<sv_upgrade>
6262  
6263  Upgrade an SV to a more complex form.  Generally adds a new body type to the
6264  SV, then copies across as much information as possible from the old body.
6265  You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
6266  
6267      void    sv_upgrade(SV* sv, svtype new_type)
6268  
6269  =for hackers
6270  Found in file sv.c
6271  
6272  =item sv_usepvn_flags
6273  X<sv_usepvn_flags>
6274  
6275  Tells an SV to use C<ptr> to find its string value.  Normally the
6276  string is stored inside the SV but sv_usepvn allows the SV to use an
6277  outside string.  The C<ptr> should point to memory that was allocated
6278  by C<malloc>.  The string length, C<len>, must be supplied.  By default
6279  this function will realloc (i.e. move) the memory pointed to by C<ptr>,
6280  so that pointer should not be freed or used by the programmer after
6281  giving it to sv_usepvn, and neither should any pointers from "behind"
6282  that pointer (e.g. ptr + 1) be used.
6283  
6284  If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
6285  SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
6286  will be skipped. (i.e. the buffer is actually at least 1 byte longer than
6287  C<len>, and already meets the requirements for storing in C<SvPVX>)
6288  
6289      void    sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
6290  
6291  =for hackers
6292  Found in file sv.c
6293  
6294  =item sv_utf8_decode
6295  X<sv_utf8_decode>
6296  
6297  If the PV of the SV is an octet sequence in UTF-8
6298  and contains a multiple-byte character, the C<SvUTF8> flag is turned on
6299  so that it looks like a character. If the PV contains only single-byte
6300  characters, the C<SvUTF8> flag stays being off.
6301  Scans PV for validity and returns false if the PV is invalid UTF-8.
6302  
6303  NOTE: this function is experimental and may change or be
6304  removed without notice.
6305  
6306      bool    sv_utf8_decode(SV *sv)
6307  
6308  =for hackers
6309  Found in file sv.c
6310  
6311  =item sv_utf8_downgrade
6312  X<sv_utf8_downgrade>
6313  
6314  Attempts to convert the PV of an SV from characters to bytes.
6315  If the PV contains a character beyond byte, this conversion will fail;
6316  in this case, either returns false or, if C<fail_ok> is not
6317  true, croaks.
6318  
6319  This is not as a general purpose Unicode to byte encoding interface:
6320  use the Encode extension for that.
6321  
6322  NOTE: this function is experimental and may change or be
6323  removed without notice.
6324  
6325      bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
6326  
6327  =for hackers
6328  Found in file sv.c
6329  
6330  =item sv_utf8_encode
6331  X<sv_utf8_encode>
6332  
6333  Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
6334  flag off so that it looks like octets again.
6335  
6336      void    sv_utf8_encode(SV *sv)
6337  
6338  =for hackers
6339  Found in file sv.c
6340  
6341  =item sv_utf8_upgrade
6342  X<sv_utf8_upgrade>
6343  
6344  Converts the PV of an SV to its UTF-8-encoded form.
6345  Forces the SV to string form if it is not already.
6346  Always sets the SvUTF8 flag to avoid future validity checks even
6347  if all the bytes have hibit clear.
6348  
6349  This is not as a general purpose byte encoding to Unicode interface:
6350  use the Encode extension for that.
6351  
6352      STRLEN    sv_utf8_upgrade(SV *sv)
6353  
6354  =for hackers
6355  Found in file sv.c
6356  
6357  =item sv_utf8_upgrade_flags
6358  X<sv_utf8_upgrade_flags>
6359  
6360  Converts the PV of an SV to its UTF-8-encoded form.
6361  Forces the SV to string form if it is not already.
6362  Always sets the SvUTF8 flag to avoid future validity checks even
6363  if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
6364  will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
6365  C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
6366  
6367  This is not as a general purpose byte encoding to Unicode interface:
6368  use the Encode extension for that.
6369  
6370      STRLEN    sv_utf8_upgrade_flags(SV *sv, I32 flags)
6371  
6372  =for hackers
6373  Found in file sv.c
6374  
6375  =item sv_vcatpvf
6376  X<sv_vcatpvf>
6377  
6378  Processes its arguments like C<vsprintf> and appends the formatted output
6379  to an SV.  Does not handle 'set' magic.  See C<sv_vcatpvf_mg>.
6380  
6381  Usually used via its frontend C<sv_catpvf>.
6382  
6383      void    sv_vcatpvf(SV* sv, const char* pat, va_list* args)
6384  
6385  =for hackers
6386  Found in file sv.c
6387  
6388  =item sv_vcatpvfn
6389  X<sv_vcatpvfn>
6390  
6391  Processes its arguments like C<vsprintf> and appends the formatted output
6392  to an SV.  Uses an array of SVs if the C style variable argument list is
6393  missing (NULL).  When running with taint checks enabled, indicates via
6394  C<maybe_tainted> if results are untrustworthy (often due to the use of
6395  locales).
6396  
6397  Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
6398  
6399      void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
6400  
6401  =for hackers
6402  Found in file sv.c
6403  
6404  =item sv_vcatpvf_mg
6405  X<sv_vcatpvf_mg>
6406  
6407  Like C<sv_vcatpvf>, but also handles 'set' magic.
6408  
6409  Usually used via its frontend C<sv_catpvf_mg>.
6410  
6411      void    sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
6412  
6413  =for hackers
6414  Found in file sv.c
6415  
6416  =item sv_vsetpvf
6417  X<sv_vsetpvf>
6418  
6419  Works like C<sv_vcatpvf> but copies the text into the SV instead of
6420  appending it.  Does not handle 'set' magic.  See C<sv_vsetpvf_mg>.
6421  
6422  Usually used via its frontend C<sv_setpvf>.
6423  
6424      void    sv_vsetpvf(SV* sv, const char* pat, va_list* args)
6425  
6426  =for hackers
6427  Found in file sv.c
6428  
6429  =item sv_vsetpvfn
6430  X<sv_vsetpvfn>
6431  
6432  Works like C<sv_vcatpvfn> but copies the text into the SV instead of
6433  appending it.
6434  
6435  Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
6436  
6437      void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
6438  
6439  =for hackers
6440  Found in file sv.c
6441  
6442  =item sv_vsetpvf_mg
6443  X<sv_vsetpvf_mg>
6444  
6445  Like C<sv_vsetpvf>, but also handles 'set' magic.
6446  
6447  Usually used via its frontend C<sv_setpvf_mg>.
6448  
6449      void    sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
6450  
6451  =for hackers
6452  Found in file sv.c
6453  
6454  
6455  =back
6456  
6457  =head1 Unicode Support
6458  
6459  =over 8
6460  
6461  =item bytes_from_utf8
6462  X<bytes_from_utf8>
6463  
6464  Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
6465  Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
6466  the newly-created string, and updates C<len> to contain the new
6467  length.  Returns the original string if no conversion occurs, C<len>
6468  is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
6469  0 if C<s> is converted or contains all 7bit characters.
6470  
6471  NOTE: this function is experimental and may change or be
6472  removed without notice.
6473  
6474      U8*    bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
6475  
6476  =for hackers
6477  Found in file utf8.c
6478  
6479  =item bytes_to_utf8
6480  X<bytes_to_utf8>
6481  
6482  Converts a string C<s> of length C<len> from ASCII into UTF-8 encoding.
6483  Returns a pointer to the newly-created string, and sets C<len> to
6484  reflect the new length.
6485  
6486  If you want to convert to UTF-8 from other encodings than ASCII,
6487  see sv_recode_to_utf8().
6488  
6489  NOTE: this function is experimental and may change or be
6490  removed without notice.
6491  
6492      U8*    bytes_to_utf8(const U8 *s, STRLEN *len)
6493  
6494  =for hackers
6495  Found in file utf8.c
6496  
6497  =item ibcmp_utf8
6498  X<ibcmp_utf8>
6499  
6500  Return true if the strings s1 and s2 differ case-insensitively, false
6501  if not (if they are equal case-insensitively).  If u1 is true, the
6502  string s1 is assumed to be in UTF-8-encoded Unicode.  If u2 is true,
6503  the string s2 is assumed to be in UTF-8-encoded Unicode.  If u1 or u2
6504  are false, the respective string is assumed to be in native 8-bit
6505  encoding.
6506  
6507  If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
6508  in there (they will point at the beginning of the I<next> character).
6509  If the pointers behind pe1 or pe2 are non-NULL, they are the end
6510  pointers beyond which scanning will not continue under any
6511  circumstances.  If the byte lengths l1 and l2 are non-zero, s1+l1 and
6512  s2+l2 will be used as goal end pointers that will also stop the scan,
6513  and which qualify towards defining a successful match: all the scans
6514  that define an explicit length must reach their goal pointers for
6515  a match to succeed).
6516  
6517  For case-insensitiveness, the "casefolding" of Unicode is used
6518  instead of upper/lowercasing both the characters, see
6519  http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
6520  
6521      I32    ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
6522  
6523  =for hackers
6524  Found in file utf8.c
6525  
6526  =item is_utf8_char
6527  X<is_utf8_char>
6528  
6529  Tests if some arbitrary number of bytes begins in a valid UTF-8
6530  character.  Note that an INVARIANT (i.e. ASCII) character is a valid
6531  UTF-8 character.  The actual number of bytes in the UTF-8 character
6532  will be returned if it is valid, otherwise 0.
6533  
6534      STRLEN    is_utf8_char(const U8 *p)
6535  
6536  =for hackers
6537  Found in file utf8.c
6538  
6539  =item is_utf8_string
6540  X<is_utf8_string>
6541  
6542  Returns true if first C<len> bytes of the given string form a valid
6543  UTF-8 string, false otherwise.  Note that 'a valid UTF-8 string' does
6544  not mean 'a string that contains code points above 0x7F encoded in UTF-8'
6545  because a valid ASCII string is a valid UTF-8 string.
6546  
6547  See also is_utf8_string_loclen() and is_utf8_string_loc().
6548  
6549      bool    is_utf8_string(const U8 *s, STRLEN len)
6550  
6551  =for hackers
6552  Found in file utf8.c
6553  
6554  =item is_utf8_string_loc
6555  X<is_utf8_string_loc>
6556  
6557  Like is_utf8_string() but stores the location of the failure (in the
6558  case of "utf8ness failure") or the location s+len (in the case of
6559  "utf8ness success") in the C<ep>.
6560  
6561  See also is_utf8_string_loclen() and is_utf8_string().
6562  
6563      bool    is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
6564  
6565  =for hackers
6566  Found in file utf8.c
6567  
6568  =item is_utf8_string_loclen
6569  X<is_utf8_string_loclen>
6570  
6571  Like is_utf8_string() but stores the location of the failure (in the
6572  case of "utf8ness failure") or the location s+len (in the case of
6573  "utf8ness success") in the C<ep>, and the number of UTF-8
6574  encoded characters in the C<el>.
6575  
6576  See also is_utf8_string_loc() and is_utf8_string().
6577  
6578      bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
6579  
6580  =for hackers
6581  Found in file utf8.c
6582  
6583  =item pv_uni_display
6584  X<pv_uni_display>
6585  
6586  Build to the scalar dsv a displayable version of the string spv,
6587  length len, the displayable version being at most pvlim bytes long
6588  (if longer, the rest is truncated and "..." will be appended).
6589  
6590  The flags argument can have UNI_DISPLAY_ISPRINT set to display
6591  isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
6592  to display the \\[nrfta\\] as the backslashed versions (like '\n')
6593  (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
6594  UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
6595  UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
6596  
6597  The pointer to the PV of the dsv is returned.
6598  
6599      char*    pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
6600  
6601  =for hackers
6602  Found in file utf8.c
6603  
6604  =item sv_cat_decode
6605  X<sv_cat_decode>
6606  
6607  The encoding is assumed to be an Encode object, the PV of the ssv is
6608  assumed to be octets in that encoding and decoding the input starts
6609  from the position which (PV + *offset) pointed to.  The dsv will be
6610  concatenated the decoded UTF-8 string from ssv.  Decoding will terminate
6611  when the string tstr appears in decoding output or the input ends on
6612  the PV of the ssv. The value which the offset points will be modified
6613  to the last input position on the ssv.
6614  
6615  Returns TRUE if the terminator was found, else returns FALSE.
6616  
6617      bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
6618  
6619  =for hackers
6620  Found in file sv.c
6621  
6622  =item sv_recode_to_utf8
6623  X<sv_recode_to_utf8>
6624  
6625  The encoding is assumed to be an Encode object, on entry the PV
6626  of the sv is assumed to be octets in that encoding, and the sv
6627  will be converted into Unicode (and UTF-8).
6628  
6629  If the sv already is UTF-8 (or if it is not POK), or if the encoding
6630  is not a reference, nothing is done to the sv.  If the encoding is not
6631  an C<Encode::XS> Encoding object, bad things will happen.
6632  (See F<lib/encoding.pm> and L<Encode>).
6633  
6634  The PV of the sv is returned.
6635  
6636      char*    sv_recode_to_utf8(SV* sv, SV *encoding)
6637  
6638  =for hackers
6639  Found in file sv.c
6640  
6641  =item sv_uni_display
6642  X<sv_uni_display>
6643  
6644  Build to the scalar dsv a displayable version of the scalar sv,
6645  the displayable version being at most pvlim bytes long
6646  (if longer, the rest is truncated and "..." will be appended).
6647  
6648  The flags argument is as in pv_uni_display().
6649  
6650  The pointer to the PV of the dsv is returned.
6651  
6652      char*    sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
6653  
6654  =for hackers
6655  Found in file utf8.c
6656  
6657  =item to_utf8_case
6658  X<to_utf8_case>
6659  
6660  The "p" contains the pointer to the UTF-8 string encoding
6661  the character that is being converted.
6662  
6663  The "ustrp" is a pointer to the character buffer to put the
6664  conversion result to.  The "lenp" is a pointer to the length
6665  of the result.
6666  
6667  The "swashp" is a pointer to the swash to use.
6668  
6669  Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
6670  and loaded by SWASHNEW, using lib/utf8_heavy.pl.  The special (usually,
6671  but not always, a multicharacter mapping), is tried first.
6672  
6673  The "special" is a string like "utf8::ToSpecLower", which means the
6674  hash %utf8::ToSpecLower.  The access to the hash is through
6675  Perl_to_utf8_case().
6676  
6677  The "normal" is a string like "ToLower" which means the swash
6678  %utf8::ToLower.
6679  
6680      UV    to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
6681  
6682  =for hackers
6683  Found in file utf8.c
6684  
6685  =item to_utf8_fold
6686  X<to_utf8_fold>
6687  
6688  Convert the UTF-8 encoded character at p to its foldcase version and
6689  store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6690  that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6691  foldcase version may be longer than the original character (up to
6692  three characters).
6693  
6694  The first character of the foldcased version is returned
6695  (but note, as explained above, that there may be more.)
6696  
6697      UV    to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
6698  
6699  =for hackers
6700  Found in file utf8.c
6701  
6702  =item to_utf8_lower
6703  X<to_utf8_lower>
6704  
6705  Convert the UTF-8 encoded character at p to its lowercase version and
6706  store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6707  that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6708  lowercase version may be longer than the original character.
6709  
6710  The first character of the lowercased version is returned
6711  (but note, as explained above, that there may be more.)
6712  
6713      UV    to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
6714  
6715  =for hackers
6716  Found in file utf8.c
6717  
6718  =item to_utf8_title
6719  X<to_utf8_title>
6720  
6721  Convert the UTF-8 encoded character at p to its titlecase version and
6722  store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6723  that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6724  titlecase version may be longer than the original character.
6725  
6726  The first character of the titlecased version is returned
6727  (but note, as explained above, that there may be more.)
6728  
6729      UV    to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
6730  
6731  =for hackers
6732  Found in file utf8.c
6733  
6734  =item to_utf8_upper
6735  X<to_utf8_upper>
6736  
6737  Convert the UTF-8 encoded character at p to its uppercase version and
6738  store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6739  that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
6740  the uppercase version may be longer than the original character.
6741  
6742  The first character of the uppercased version is returned
6743  (but note, as explained above, that there may be more.)
6744  
6745      UV    to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
6746  
6747  =for hackers
6748  Found in file utf8.c
6749  
6750  =item utf8n_to_uvchr
6751  X<utf8n_to_uvchr>
6752  
6753  flags
6754  
6755  Returns the native character value of the first character in the string 
6756  C<s>
6757  which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6758  length, in bytes, of that character.
6759  
6760  Allows length and flags to be passed to low level routine.
6761  
6762      UV    utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6763  
6764  =for hackers
6765  Found in file utf8.c
6766  
6767  =item utf8n_to_uvuni
6768  X<utf8n_to_uvuni>
6769  
6770  Bottom level UTF-8 decode routine.
6771  Returns the Unicode code point value of the first character in the string C<s>
6772  which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
6773  C<retlen> will be set to the length, in bytes, of that character.
6774  
6775  If C<s> does not point to a well-formed UTF-8 character, the behaviour
6776  is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
6777  it is assumed that the caller will raise a warning, and this function
6778  will silently just set C<retlen> to C<-1> and return zero.  If the
6779  C<flags> does not contain UTF8_CHECK_ONLY, warnings about
6780  malformations will be given, C<retlen> will be set to the expected
6781  length of the UTF-8 character in bytes, and zero will be returned.
6782  
6783  The C<flags> can also contain various flags to allow deviations from
6784  the strict UTF-8 encoding (see F<utf8.h>).
6785  
6786  Most code should use utf8_to_uvchr() rather than call this directly.
6787  
6788      UV    utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6789  
6790  =for hackers
6791  Found in file utf8.c
6792  
6793  =item utf8_distance
6794  X<utf8_distance>
6795  
6796  Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
6797  and C<b>.
6798  
6799  WARNING: use only if you *know* that the pointers point inside the
6800  same UTF-8 buffer.
6801  
6802      IV    utf8_distance(const U8 *a, const U8 *b)
6803  
6804  =for hackers
6805  Found in file utf8.c
6806  
6807  =item utf8_hop
6808  X<utf8_hop>
6809  
6810  Return the UTF-8 pointer C<s> displaced by C<off> characters, either
6811  forward or backward.
6812  
6813  WARNING: do not use the following unless you *know* C<off> is within
6814  the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
6815  on the first byte of character or just after the last byte of a character.
6816  
6817      U8*    utf8_hop(const U8 *s, I32 off)
6818  
6819  =for hackers
6820  Found in file utf8.c
6821  
6822  =item utf8_length
6823  X<utf8_length>
6824  
6825  Return the length of the UTF-8 char encoded string C<s> in characters.
6826  Stops at C<e> (inclusive).  If C<e E<lt> s> or if the scan would end
6827  up past C<e>, croaks.
6828  
6829      STRLEN    utf8_length(const U8* s, const U8 *e)
6830  
6831  =for hackers
6832  Found in file utf8.c
6833  
6834  =item utf8_to_bytes
6835  X<utf8_to_bytes>
6836  
6837  Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
6838  Unlike C<bytes_to_utf8>, this over-writes the original string, and
6839  updates len to contain the new length.
6840  Returns zero on failure, setting C<len> to -1.
6841  
6842  If you need a copy of the string, see C<bytes_from_utf8>.
6843  
6844  NOTE: this function is experimental and may change or be
6845  removed without notice.
6846  
6847      U8*    utf8_to_bytes(U8 *s, STRLEN *len)
6848  
6849  =for hackers
6850  Found in file utf8.c
6851  
6852  =item utf8_to_uvchr
6853  X<utf8_to_uvchr>
6854  
6855  Returns the native character value of the first character in the string C<s>
6856  which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6857  length, in bytes, of that character.
6858  
6859  If C<s> does not point to a well-formed UTF-8 character, zero is
6860  returned and retlen is set, if possible, to -1.
6861  
6862      UV    utf8_to_uvchr(const U8 *s, STRLEN *retlen)
6863  
6864  =for hackers
6865  Found in file utf8.c
6866  
6867  =item utf8_to_uvuni
6868  X<utf8_to_uvuni>
6869  
6870  Returns the Unicode code point of the first character in the string C<s>
6871  which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6872  length, in bytes, of that character.
6873  
6874  This function should only be used when returned UV is considered
6875  an index into the Unicode semantic tables (e.g. swashes).
6876  
6877  If C<s> does not point to a well-formed UTF-8 character, zero is
6878  returned and retlen is set, if possible, to -1.
6879  
6880      UV    utf8_to_uvuni(const U8 *s, STRLEN *retlen)
6881  
6882  =for hackers
6883  Found in file utf8.c
6884  
6885  =item uvchr_to_utf8
6886  X<uvchr_to_utf8>
6887  
6888  Adds the UTF-8 representation of the Native codepoint C<uv> to the end
6889  of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
6890  bytes available. The return value is the pointer to the byte after the
6891  end of the new character. In other words,
6892  
6893      d = uvchr_to_utf8(d, uv);
6894  
6895  is the recommended wide native character-aware way of saying
6896  
6897      *(d++) = uv;
6898  
6899      U8*    uvchr_to_utf8(U8 *d, UV uv)
6900  
6901  =for hackers
6902  Found in file utf8.c
6903  
6904  =item uvuni_to_utf8_flags
6905  X<uvuni_to_utf8_flags>
6906  
6907  Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
6908  of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
6909  bytes available. The return value is the pointer to the byte after the
6910  end of the new character. In other words,
6911  
6912      d = uvuni_to_utf8_flags(d, uv, flags);
6913  
6914  or, in most cases,
6915  
6916      d = uvuni_to_utf8(d, uv);
6917  
6918  (which is equivalent to)
6919  
6920      d = uvuni_to_utf8_flags(d, uv, 0);
6921  
6922  is the recommended Unicode-aware way of saying
6923  
6924      *(d++) = uv;
6925  
6926      U8*    uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
6927  
6928  =for hackers
6929  Found in file utf8.c
6930  
6931  
6932  =back
6933  
6934  =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
6935  
6936  =over 8
6937  
6938  =item ax
6939  X<ax>
6940  
6941  Variable which is setup by C<xsubpp> to indicate the stack base offset,
6942  used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
6943  must be called prior to setup the C<MARK> variable.
6944  
6945      I32    ax
6946  
6947  =for hackers
6948  Found in file XSUB.h
6949  
6950  =item CLASS
6951  X<CLASS>
6952  
6953  Variable which is setup by C<xsubpp> to indicate the 
6954  class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
6955  
6956      char*    CLASS
6957  
6958  =for hackers
6959  Found in file XSUB.h
6960  
6961  =item dAX
6962  X<dAX>
6963  
6964  Sets up the C<ax> variable.
6965  This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6966  
6967          dAX;
6968  
6969  =for hackers
6970  Found in file XSUB.h
6971  
6972  =item dAXMARK
6973  X<dAXMARK>
6974  
6975  Sets up the C<ax> variable and stack marker variable C<mark>.
6976  This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6977  
6978          dAXMARK;
6979  
6980  =for hackers
6981  Found in file XSUB.h
6982  
6983  =item dITEMS
6984  X<dITEMS>
6985  
6986  Sets up the C<items> variable.
6987  This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6988  
6989          dITEMS;
6990  
6991  =for hackers
6992  Found in file XSUB.h
6993  
6994  =item dUNDERBAR
6995  X<dUNDERBAR>
6996  
6997  Sets up the C<padoff_du> variable for an XSUB that wishes to use
6998  C<UNDERBAR>.
6999  
7000          dUNDERBAR;
7001  
7002  =for hackers
7003  Found in file XSUB.h
7004  
7005  =item dXSARGS
7006  X<dXSARGS>
7007  
7008  Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
7009  Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
7010  This is usually handled automatically by C<xsubpp>.
7011  
7012          dXSARGS;
7013  
7014  =for hackers
7015  Found in file XSUB.h
7016  
7017  =item dXSI32
7018  X<dXSI32>
7019  
7020  Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
7021  handled automatically by C<xsubpp>.
7022  
7023          dXSI32;
7024  
7025  =for hackers
7026  Found in file XSUB.h
7027  
7028  =item items
7029  X<items>
7030  
7031  Variable which is setup by C<xsubpp> to indicate the number of 
7032  items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
7033  
7034      I32    items
7035  
7036  =for hackers
7037  Found in file XSUB.h
7038  
7039  =item ix
7040  X<ix>
7041  
7042  Variable which is setup by C<xsubpp> to indicate which of an 
7043  XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
7044  
7045      I32    ix
7046  
7047  =for hackers
7048  Found in file XSUB.h
7049  
7050  =item newXSproto
7051  X<newXSproto>
7052  
7053  Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
7054  the subs.
7055  
7056  =for hackers
7057  Found in file XSUB.h
7058  
7059  =item RETVAL
7060  X<RETVAL>
7061  
7062  Variable which is setup by C<xsubpp> to hold the return value for an 
7063  XSUB. This is always the proper type for the XSUB. See 
7064  L<perlxs/"The RETVAL Variable">.
7065  
7066      (whatever)    RETVAL
7067  
7068  =for hackers
7069  Found in file XSUB.h
7070  
7071  =item ST
7072  X<ST>
7073  
7074  Used to access elements on the XSUB's stack.
7075  
7076      SV*    ST(int ix)
7077  
7078  =for hackers
7079  Found in file XSUB.h
7080  
7081  =item THIS
7082  X<THIS>
7083  
7084  Variable which is setup by C<xsubpp> to designate the object in a C++ 
7085  XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
7086  L<perlxs/"Using XS With C++">.
7087  
7088      (whatever)    THIS
7089  
7090  =for hackers
7091  Found in file XSUB.h
7092  
7093  =item UNDERBAR
7094  X<UNDERBAR>
7095  
7096  The SV* corresponding to the $_ variable. Works even if there
7097  is a lexical $_ in scope.
7098  
7099  =for hackers
7100  Found in file XSUB.h
7101  
7102  =item XS
7103  X<XS>
7104  
7105  Macro to declare an XSUB and its C parameter list.  This is handled by
7106  C<xsubpp>.
7107  
7108  =for hackers
7109  Found in file XSUB.h
7110  
7111  =item XS_VERSION
7112  X<XS_VERSION>
7113  
7114  The version identifier for an XS module.  This is usually
7115  handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
7116  
7117  =for hackers
7118  Found in file XSUB.h
7119  
7120  =item XS_VERSION_BOOTCHECK
7121  X<XS_VERSION_BOOTCHECK>
7122  
7123  Macro to verify that a PM module's $VERSION variable matches the XS
7124  module's C<XS_VERSION> variable.  This is usually handled automatically by
7125  C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
7126  
7127          XS_VERSION_BOOTCHECK;
7128  
7129  =for hackers
7130  Found in file XSUB.h
7131  
7132  
7133  =back
7134  
7135  =head1 Warning and Dieing
7136  
7137  =over 8
7138  
7139  =item croak
7140  X<croak>
7141  
7142  This is the XSUB-writer's interface to Perl's C<die> function.
7143  Normally call this function the same way you call the C C<printf>
7144  function.  Calling C<croak> returns control directly to Perl,
7145  sidestepping the normal C order of execution. See C<warn>.
7146  
7147  If you want to throw an exception object, assign the object to
7148  C<$@> and then pass C<NULL> to croak():
7149  
7150     errsv = get_sv("@", TRUE);
7151     sv_setsv(errsv, exception_object);
7152     croak(NULL);
7153  
7154      void    croak(const char* pat, ...)
7155  
7156  =for hackers
7157  Found in file util.c
7158  
7159  =item warn
7160  X<warn>
7161  
7162  This is the XSUB-writer's interface to Perl's C<warn> function.  Call this
7163  function the same way you call the C C<printf> function.  See C<croak>.
7164  
7165      void    warn(const char* pat, ...)
7166  
7167  =for hackers
7168  Found in file util.c
7169  
7170  
7171  =back
7172  
7173  =head1 AUTHORS
7174  
7175  Until May 1997, this document was maintained by Jeff Okamoto
7176  <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
7177  
7178  With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
7179  Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
7180  Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
7181  Stephen McCamant, and Gurusamy Sarathy.
7182  
7183  API Listing originally by Dean Roehrich <roehrich@cray.com>.
7184  
7185  Updated to be autogenerated from comments in the source by Benjamin Stuhl.
7186  
7187  =head1 SEE ALSO
7188  
7189  perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
7190  
7191  =cut
7192  
7193   ex: set ro: