[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  perlintern - autogenerated documentation of purely B<internal>
  10           Perl functions
  11  
  12  =head1 DESCRIPTION
  13  X<internal Perl functions> X<interpreter functions>
  14  
  15  This file is the autogenerated documentation of functions in the
  16  Perl interpreter that are documented using Perl's internal documentation
  17  format but are not marked as part of the Perl API. In other words,
  18  B<they are not for use in extensions>!
  19  
  20  
  21  =head1 CV reference counts and CvOUTSIDE
  22  
  23  =over 8
  24  
  25  =item CvWEAKOUTSIDE
  26  X<CvWEAKOUTSIDE>
  27  
  28  Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
  29  CV (if any). Because pointers to anonymous sub prototypes are
  30  stored in C<&> pad slots, it is a possible to get a circular reference,
  31  with the parent pointing to the child and vice-versa. To avoid the
  32  ensuing memory leak, we do not increment the reference count of the CV
  33  pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
  34  has a C<&> pad slot pointing back to us. In this case, we set the
  35  C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
  36  circumstances we should decrement the refcount of the parent when freeing
  37  the child.
  38  
  39  There is a further complication with non-closure anonymous subs (i.e. those
  40  that do not refer to any lexicals outside that sub). In this case, the
  41  anonymous prototype is shared rather than being cloned. This has the
  42  consequence that the parent may be freed while there are still active
  43  children, eg
  44  
  45      BEGIN { $a = sub { eval '$x' } }
  46  
  47  In this case, the BEGIN is freed immediately after execution since there
  48  are no active references to it: the anon sub prototype has
  49  C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
  50  CV, so it doesn't contribute to BEGIN's refcount either.  When $a is
  51  executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
  52  and the freed BEGIN is accessed.
  53  
  54  To avoid this, whenever a CV and its associated pad is freed, any
  55  C<&> entries in the pad are explicitly removed from the pad, and if the
  56  refcount of the pointed-to anon sub is still positive, then that
  57  child's C<CvOUTSIDE> is set to point to its grandparent. This will only
  58  occur in the single specific case of a non-closure anon prototype
  59  having one or more active references (such as C<$a> above).
  60  
  61  One other thing to consider is that a CV may be merely undefined
  62  rather than freed, eg C<undef &foo>. In this case, its refcount may
  63  not have reached zero, but we still delete its pad and its C<CvROOT> etc.
  64  Since various children may still have their C<CvOUTSIDE> pointing at this
  65  undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
  66  the chain of lexical scopes is unbroken. For example, the following
  67  should print 123:
  68  
  69      my $x = 123;
  70      sub tmp { sub { eval '$x' } }
  71      my $a = tmp();
  72      undef &tmp;
  73      print  $a->();
  74  
  75      bool    CvWEAKOUTSIDE(CV *cv)
  76  
  77  =for hackers
  78  Found in file cv.h
  79  
  80  
  81  =back
  82  
  83  =head1 Functions in file pad.h
  84  
  85  
  86  =over 8
  87  
  88  =item CX_CURPAD_SAVE
  89  X<CX_CURPAD_SAVE>
  90  
  91  Save the current pad in the given context block structure.
  92  
  93      void    CX_CURPAD_SAVE(struct context)
  94  
  95  =for hackers
  96  Found in file pad.h
  97  
  98  =item CX_CURPAD_SV
  99  X<CX_CURPAD_SV>
 100  
 101  Access the SV at offset po in the saved current pad in the given
 102  context block structure (can be used as an lvalue).
 103  
 104      SV *    CX_CURPAD_SV(struct context, PADOFFSET po)
 105  
 106  =for hackers
 107  Found in file pad.h
 108  
 109  =item PAD_BASE_SV
 110  X<PAD_BASE_SV>
 111  
 112  Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
 113  
 114      SV *    PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
 115  
 116  =for hackers
 117  Found in file pad.h
 118  
 119  =item PAD_CLONE_VARS
 120  X<PAD_CLONE_VARS>
 121  
 122  |CLONE_PARAMS* param
 123  Clone the state variables associated with running and compiling pads.
 124  
 125      void    PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
 126  
 127  =for hackers
 128  Found in file pad.h
 129  
 130  =item PAD_COMPNAME_FLAGS
 131  X<PAD_COMPNAME_FLAGS>
 132  
 133  Return the flags for the current compiling pad name
 134  at offset C<po>. Assumes a valid slot entry.
 135  
 136      U32    PAD_COMPNAME_FLAGS(PADOFFSET po)
 137  
 138  =for hackers
 139  Found in file pad.h
 140  
 141  =item PAD_COMPNAME_GEN
 142  X<PAD_COMPNAME_GEN>
 143  
 144  The generation number of the name at offset C<po> in the current
 145  compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
 146  
 147      STRLEN    PAD_COMPNAME_GEN(PADOFFSET po)
 148  
 149  =for hackers
 150  Found in file pad.h
 151  
 152  =item PAD_COMPNAME_GEN_set
 153  X<PAD_COMPNAME_GEN_set>
 154  
 155  Sets the generation number of the name at offset C<po> in the current
 156  ling pad (lvalue) to C<gen>.  Note that C<SvUV_set> is hijacked for this purpose.
 157  
 158      STRLEN    PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
 159  
 160  =for hackers
 161  Found in file pad.h
 162  
 163  =item PAD_COMPNAME_OURSTASH
 164  X<PAD_COMPNAME_OURSTASH>
 165  
 166  Return the stash associated with an C<our> variable.
 167  Assumes the slot entry is a valid C<our> lexical.
 168  
 169      HV *    PAD_COMPNAME_OURSTASH(PADOFFSET po)
 170  
 171  =for hackers
 172  Found in file pad.h
 173  
 174  =item PAD_COMPNAME_PV
 175  X<PAD_COMPNAME_PV>
 176  
 177  Return the name of the current compiling pad name
 178  at offset C<po>. Assumes a valid slot entry.
 179  
 180      char *    PAD_COMPNAME_PV(PADOFFSET po)
 181  
 182  =for hackers
 183  Found in file pad.h
 184  
 185  =item PAD_COMPNAME_TYPE
 186  X<PAD_COMPNAME_TYPE>
 187  
 188  Return the type (stash) of the current compiling pad name at offset
 189  C<po>. Must be a valid name. Returns null if not typed.
 190  
 191      HV *    PAD_COMPNAME_TYPE(PADOFFSET po)
 192  
 193  =for hackers
 194  Found in file pad.h
 195  
 196  =item PAD_DUP
 197  X<PAD_DUP>
 198  
 199  Clone a padlist.
 200  
 201      void    PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
 202  
 203  =for hackers
 204  Found in file pad.h
 205  
 206  =item PAD_RESTORE_LOCAL
 207  X<PAD_RESTORE_LOCAL>
 208  
 209  Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
 210  
 211      void    PAD_RESTORE_LOCAL(PAD *opad)
 212  
 213  =for hackers
 214  Found in file pad.h
 215  
 216  =item PAD_SAVE_LOCAL
 217  X<PAD_SAVE_LOCAL>
 218  
 219  Save the current pad to the local variable opad, then make the
 220  current pad equal to npad
 221  
 222      void    PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
 223  
 224  =for hackers
 225  Found in file pad.h
 226  
 227  =item PAD_SAVE_SETNULLPAD
 228  X<PAD_SAVE_SETNULLPAD>
 229  
 230  Save the current pad then set it to null.
 231  
 232      void    PAD_SAVE_SETNULLPAD()
 233  
 234  =for hackers
 235  Found in file pad.h
 236  
 237  =item PAD_SETSV
 238  X<PAD_SETSV>
 239  
 240  Set the slot at offset C<po> in the current pad to C<sv>
 241  
 242      SV *    PAD_SETSV(PADOFFSET po, SV* sv)
 243  
 244  =for hackers
 245  Found in file pad.h
 246  
 247  =item PAD_SET_CUR
 248  X<PAD_SET_CUR>
 249  
 250  Set the current pad to be pad C<n> in the padlist, saving
 251  the previous current pad. NB currently this macro expands to a string too
 252  long for some compilers, so it's best to replace it with
 253  
 254      SAVECOMPPAD();
 255      PAD_SET_CUR_NOSAVE(padlist,n);
 256  
 257  
 258      void    PAD_SET_CUR(PADLIST padlist, I32 n)
 259  
 260  =for hackers
 261  Found in file pad.h
 262  
 263  =item PAD_SET_CUR_NOSAVE
 264  X<PAD_SET_CUR_NOSAVE>
 265  
 266  like PAD_SET_CUR, but without the save
 267  
 268      void    PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
 269  
 270  =for hackers
 271  Found in file pad.h
 272  
 273  =item PAD_SV
 274  X<PAD_SV>
 275  
 276  Get the value at offset C<po> in the current pad
 277  
 278      void    PAD_SV(PADOFFSET po)
 279  
 280  =for hackers
 281  Found in file pad.h
 282  
 283  =item PAD_SVl
 284  X<PAD_SVl>
 285  
 286  Lightweight and lvalue version of C<PAD_SV>.
 287  Get or set the value at offset C<po> in the current pad.
 288  Unlike C<PAD_SV>, does not print diagnostics with -DX.
 289  For internal use only.
 290  
 291      SV *    PAD_SVl(PADOFFSET po)
 292  
 293  =for hackers
 294  Found in file pad.h
 295  
 296  =item SAVECLEARSV
 297  X<SAVECLEARSV>
 298  
 299  Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
 300  
 301      void    SAVECLEARSV(SV **svp)
 302  
 303  =for hackers
 304  Found in file pad.h
 305  
 306  =item SAVECOMPPAD
 307  X<SAVECOMPPAD>
 308  
 309  save PL_comppad and PL_curpad
 310  
 311  
 312  
 313  
 314  
 315      void    SAVECOMPPAD()
 316  
 317  =for hackers
 318  Found in file pad.h
 319  
 320  =item SAVEPADSV
 321  X<SAVEPADSV>
 322  
 323  Save a pad slot (used to restore after an iteration)
 324  
 325  XXX DAPM it would make more sense to make the arg a PADOFFSET
 326      void    SAVEPADSV(PADOFFSET po)
 327  
 328  =for hackers
 329  Found in file pad.h
 330  
 331  
 332  =back
 333  
 334  =head1 GV Functions
 335  
 336  =over 8
 337  
 338  =item is_gv_magical
 339  X<is_gv_magical>
 340  
 341  Returns C<TRUE> if given the name of a magical GV.
 342  
 343  Currently only useful internally when determining if a GV should be
 344  created even in rvalue contexts.
 345  
 346  C<flags> is not used at present but available for future extension to
 347  allow selecting particular classes of magical variable.
 348  
 349  Currently assumes that C<name> is NUL terminated (as well as len being valid).
 350  This assumption is met by all callers within the perl core, which all pass
 351  pointers returned by SvPV.
 352  
 353      bool    is_gv_magical(const char *name, STRLEN len, U32 flags)
 354  
 355  =for hackers
 356  Found in file gv.c
 357  
 358  =item is_gv_magical_sv
 359  X<is_gv_magical_sv>
 360  
 361  Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical.
 362  
 363      bool    is_gv_magical_sv(SV *name, U32 flags)
 364  
 365  =for hackers
 366  Found in file gv.c
 367  
 368  
 369  =back
 370  
 371  =head1 Hash Manipulation Functions
 372  
 373  =over 8
 374  
 375  =item refcounted_he_chain_2hv
 376  X<refcounted_he_chain_2hv>
 377  
 378  Generates and returns a C<HV *> by walking up the tree starting at the passed
 379  in C<struct refcounted_he *>.
 380  
 381      HV *    refcounted_he_chain_2hv(const struct refcounted_he *c)
 382  
 383  =for hackers
 384  Found in file hv.c
 385  
 386  =item refcounted_he_free
 387  X<refcounted_he_free>
 388  
 389  Decrements the reference count of the passed in C<struct refcounted_he *>
 390  by one. If the reference count reaches zero the structure's memory is freed,
 391  and C<refcounted_he_free> iterates onto the parent node.
 392  
 393      void    refcounted_he_free(struct refcounted_he *he)
 394  
 395  =for hackers
 396  Found in file hv.c
 397  
 398  =item refcounted_he_new
 399  X<refcounted_he_new>
 400  
 401  Creates a new C<struct refcounted_he>. As S<key> is copied, and value is
 402  stored in a compact form, all references remain the property of the caller.
 403  The C<struct refcounted_he> is returned with a reference count of 1.
 404  
 405      struct refcounted_he *    refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value)
 406  
 407  =for hackers
 408  Found in file hv.c
 409  
 410  
 411  =back
 412  
 413  =head1 IO Functions
 414  
 415  =over 8
 416  
 417  =item start_glob
 418  X<start_glob>
 419  
 420  Function called by C<do_readline> to spawn a glob (or do the glob inside
 421  perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
 422  this glob starter is only used by miniperl during the build process.
 423  Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
 424  
 425      PerlIO*    start_glob(SV* pattern, IO *io)
 426  
 427  =for hackers
 428  Found in file doio.c
 429  
 430  
 431  =back
 432  
 433  =head1 Magical Functions
 434  
 435  =over 8
 436  
 437  =item magic_sethint
 438  X<magic_sethint>
 439  
 440  Triggered by a delete from %^H, records the key to
 441  C<PL_compiling.cop_hints_hash>.
 442  
 443      int    magic_sethint(SV* sv, MAGIC* mg)
 444  
 445  =for hackers
 446  Found in file mg.c
 447  
 448  =item mg_localize
 449  X<mg_localize>
 450  
 451  Copy some of the magic from an existing SV to new localized version of
 452  that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic
 453  doesn't (eg taint, pos).
 454  
 455      void    mg_localize(SV* sv, SV* nsv)
 456  
 457  =for hackers
 458  Found in file mg.c
 459  
 460  
 461  =back
 462  
 463  =head1 MRO Functions
 464  
 465  =over 8
 466  
 467  =item mro_get_linear_isa_c3
 468  X<mro_get_linear_isa_c3>
 469  
 470  Returns the C3 linearization of @ISA
 471  the given stash.  The return value is a read-only AV*.
 472  C<level> should be 0 (it is used internally in this
 473  function's recursion).
 474  
 475  You are responsible for C<SvREFCNT_inc()> on the
 476  return value if you plan to store it anywhere
 477  semi-permanently (otherwise it might be deleted
 478  out from under you the next time the cache is
 479  invalidated).
 480  
 481      AV*    mro_get_linear_isa_c3(HV* stash, I32 level)
 482  
 483  =for hackers
 484  Found in file mro.c
 485  
 486  =item mro_get_linear_isa_dfs
 487  X<mro_get_linear_isa_dfs>
 488  
 489  Returns the Depth-First Search linearization of @ISA
 490  the given stash.  The return value is a read-only AV*.
 491  C<level> should be 0 (it is used internally in this
 492  function's recursion).
 493  
 494  You are responsible for C<SvREFCNT_inc()> on the
 495  return value if you plan to store it anywhere
 496  semi-permanently (otherwise it might be deleted
 497  out from under you the next time the cache is
 498  invalidated).
 499  
 500      AV*    mro_get_linear_isa_dfs(HV* stash, I32 level)
 501  
 502  =for hackers
 503  Found in file mro.c
 504  
 505  =item mro_isa_changed_in
 506  X<mro_isa_changed_in>
 507  
 508  Takes the necessary steps (cache invalidations, mostly)
 509  when the @ISA of the given package has changed.  Invoked
 510  by the C<setisa> magic, should not need to invoke directly.
 511  
 512      void    mro_isa_changed_in(HV* stash)
 513  
 514  =for hackers
 515  Found in file mro.c
 516  
 517  
 518  =back
 519  
 520  =head1 Pad Data Structures
 521  
 522  =over 8
 523  
 524  =item CvPADLIST
 525  X<CvPADLIST>
 526  
 527  CV's can have CvPADLIST(cv) set to point to an AV.
 528  
 529  For these purposes "forms" are a kind-of CV, eval""s are too (except they're
 530  not callable at will and are always thrown away after the eval"" is done
 531  executing). Require'd files are simply evals without any outer lexical
 532  scope.
 533  
 534  XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
 535  but that is really the callers pad (a slot of which is allocated by
 536  every entersub).
 537  
 538  The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
 539  is managed "manual" (mostly in pad.c) rather than normal av.c rules.
 540  The items in the AV are not SVs as for a normal AV, but other AVs:
 541  
 542  0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
 543  the "static type information" for lexicals.
 544  
 545  The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
 546  depth of recursion into the CV.
 547  The 0'th slot of a frame AV is an AV which is @_.
 548  other entries are storage for variables and op targets.
 549  
 550  During compilation:
 551  C<PL_comppad_name> is set to the names AV.
 552  C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
 553  C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
 554  
 555  During execution, C<PL_comppad> and C<PL_curpad> refer to the live
 556  frame of the currently executing sub.
 557  
 558  Iterating over the names AV iterates over all possible pad
 559  items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
 560  &PL_sv_undef "names" (see pad_alloc()).
 561  
 562  Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
 563  The rest are op targets/GVs/constants which are statically allocated
 564  or resolved at compile time.  These don't have names by which they
 565  can be looked up from Perl code at run time through eval"" like
 566  my/our variables can be.  Since they can't be looked up by "name"
 567  but only by their index allocated at compile time (which is usually
 568  in PL_op->op_targ), wasting a name SV for them doesn't make sense.
 569  
 570  The SVs in the names AV have their PV being the name of the variable.
 571  xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for
 572  which the name is valid.  For typed lexicals name SV is SVt_PVMG and SvSTASH
 573  points at the type.  For C<our> lexicals, the type is also SVt_PVMG, with the
 574  SvOURSTASH slot pointing at the stash of the associated global (so that
 575  duplicate C<our> declarations in the same package can be detected).  SvUVX is
 576  sometimes hijacked to store the generation number during compilation.
 577  
 578  If SvFAKE is set on the name SV, then that slot in the frame AV is
 579  a REFCNT'ed reference to a lexical from "outside". In this case,
 580  the name SV does not use xlow and xhigh to store a cop_seq range, since it is
 581  in scope throughout. Instead xhigh stores some flags containing info about
 582  the real lexical (is it declared in an anon, and is it capable of being
 583  instantiated multiple times?), and for fake ANONs, xlow contains the index
 584  within the parent's pad where the lexical's value is stored, to make
 585  cloning quicker.
 586  
 587  If the 'name' is '&' the corresponding entry in frame AV
 588  is a CV representing a possible closure.
 589  (SvFAKE and name of '&' is not a meaningful combination currently but could
 590  become so if C<my sub foo {}> is implemented.)
 591  
 592  Note that formats are treated as anon subs, and are cloned each time
 593  write is called (if necessary).
 594  
 595  The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
 596  and set on scope exit. This allows the 'Variable $x is not available' warning
 597  to be generated in evals, such as 
 598  
 599      { my $x = 1; sub f { eval '$x'} } f();
 600  
 601      AV *    CvPADLIST(CV *cv)
 602  
 603  =for hackers
 604  Found in file pad.c
 605  
 606  =item cv_clone
 607  X<cv_clone>
 608  
 609  Clone a CV: make a new CV which points to the same code etc, but which
 610  has a newly-created pad built by copying the prototype pad and capturing
 611  any outer lexicals.
 612  
 613      CV*    cv_clone(CV* proto)
 614  
 615  =for hackers
 616  Found in file pad.c
 617  
 618  =item cv_dump
 619  X<cv_dump>
 620  
 621  dump the contents of a CV
 622  
 623      void    cv_dump(const CV *cv, const char *title)
 624  
 625  =for hackers
 626  Found in file pad.c
 627  
 628  =item do_dump_pad
 629  X<do_dump_pad>
 630  
 631  Dump the contents of a padlist
 632  
 633      void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
 634  
 635  =for hackers
 636  Found in file pad.c
 637  
 638  =item intro_my
 639  X<intro_my>
 640  
 641  "Introduce" my variables to visible status.
 642  
 643      U32    intro_my()
 644  
 645  =for hackers
 646  Found in file pad.c
 647  
 648  =item pad_add_anon
 649  X<pad_add_anon>
 650  
 651  Add an anon code entry to the current compiling pad
 652  
 653      PADOFFSET    pad_add_anon(SV* sv, OPCODE op_type)
 654  
 655  =for hackers
 656  Found in file pad.c
 657  
 658  =item pad_add_name
 659  X<pad_add_name>
 660  
 661  Create a new name and associated PADMY SV in the current pad; return the
 662  offset.
 663  If C<typestash> is valid, the name is for a typed lexical; set the
 664  name's stash to that value.
 665  If C<ourstash> is valid, it's an our lexical, set the name's
 666  SvOURSTASH to that value
 667  
 668  If fake, it means we're cloning an existing entry
 669  
 670      PADOFFSET    pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state)
 671  
 672  =for hackers
 673  Found in file pad.c
 674  
 675  =item pad_alloc
 676  X<pad_alloc>
 677  
 678  Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
 679  the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
 680  for a slot which has no name and no active value.
 681  
 682      PADOFFSET    pad_alloc(I32 optype, U32 tmptype)
 683  
 684  =for hackers
 685  Found in file pad.c
 686  
 687  =item pad_block_start
 688  X<pad_block_start>
 689  
 690  Update the pad compilation state variables on entry to a new block
 691  
 692      void    pad_block_start(int full)
 693  
 694  =for hackers
 695  Found in file pad.c
 696  
 697  =item pad_check_dup
 698  X<pad_check_dup>
 699  
 700  Check for duplicate declarations: report any of:
 701       * a my in the current scope with the same name;
 702       * an our (anywhere in the pad) with the same name and the same stash
 703         as C<ourstash>
 704  C<is_our> indicates that the name to check is an 'our' declaration
 705  
 706      void    pad_check_dup(const char* name, bool is_our, const HV* ourstash)
 707  
 708  =for hackers
 709  Found in file pad.c
 710  
 711  =item pad_findlex
 712  X<pad_findlex>
 713  
 714  Find a named lexical anywhere in a chain of nested pads. Add fake entries
 715  in the inner pads if it's found in an outer one.
 716  
 717  Returns the offset in the bottom pad of the lex or the fake lex.
 718  cv is the CV in which to start the search, and seq is the current cop_seq
 719  to match against. If warn is true, print appropriate warnings.  The out_*
 720  vars return values, and so are pointers to where the returned values
 721  should be stored. out_capture, if non-null, requests that the innermost
 722  instance of the lexical is captured; out_name_sv is set to the innermost
 723  matched namesv or fake namesv; out_flags returns the flags normally
 724  associated with the IVX field of a fake namesv.
 725  
 726  Note that pad_findlex() is recursive; it recurses up the chain of CVs,
 727  then comes back down, adding fake entries as it goes. It has to be this way
 728  because fake namesvs in anon protoypes have to store in xlow the index into
 729  the parent pad.
 730  
 731      PADOFFSET    pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
 732  
 733  =for hackers
 734  Found in file pad.c
 735  
 736  =item pad_findmy
 737  X<pad_findmy>
 738  
 739  Given a lexical name, try to find its offset, first in the current pad,
 740  or failing that, in the pads of any lexically enclosing subs (including
 741  the complications introduced by eval). If the name is found in an outer pad,
 742  then a fake entry is added to the current pad.
 743  Returns the offset in the current pad, or NOT_IN_PAD on failure.
 744  
 745      PADOFFSET    pad_findmy(const char* name)
 746  
 747  =for hackers
 748  Found in file pad.c
 749  
 750  =item pad_fixup_inner_anons
 751  X<pad_fixup_inner_anons>
 752  
 753  For any anon CVs in the pad, change CvOUTSIDE of that CV from
 754  old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
 755  moved to a pre-existing CV struct.
 756  
 757      void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
 758  
 759  =for hackers
 760  Found in file pad.c
 761  
 762  =item pad_free
 763  X<pad_free>
 764  
 765  Free the SV at offset po in the current pad.
 766  
 767      void    pad_free(PADOFFSET po)
 768  
 769  =for hackers
 770  Found in file pad.c
 771  
 772  =item pad_leavemy
 773  X<pad_leavemy>
 774  
 775  Cleanup at end of scope during compilation: set the max seq number for
 776  lexicals in this scope and warn of any lexicals that never got introduced.
 777  
 778      void    pad_leavemy()
 779  
 780  =for hackers
 781  Found in file pad.c
 782  
 783  =item pad_new
 784  X<pad_new>
 785  
 786  Create a new compiling padlist, saving and updating the various global
 787  vars at the same time as creating the pad itself. The following flags
 788  can be OR'ed together:
 789  
 790      padnew_CLONE    this pad is for a cloned CV
 791      padnew_SAVE        save old globals
 792      padnew_SAVESUB    also save extra stuff for start of sub
 793  
 794      PADLIST*    pad_new(int flags)
 795  
 796  =for hackers
 797  Found in file pad.c
 798  
 799  =item pad_push
 800  X<pad_push>
 801  
 802  Push a new pad frame onto the padlist, unless there's already a pad at
 803  this depth, in which case don't bother creating a new one.  Then give
 804  the new pad an @_ in slot zero.
 805  
 806      void    pad_push(PADLIST *padlist, int depth)
 807  
 808  =for hackers
 809  Found in file pad.c
 810  
 811  =item pad_reset
 812  X<pad_reset>
 813  
 814  Mark all the current temporaries for reuse
 815  
 816      void    pad_reset()
 817  
 818  =for hackers
 819  Found in file pad.c
 820  
 821  =item pad_setsv
 822  X<pad_setsv>
 823  
 824  Set the entry at offset po in the current pad to sv.
 825  Use the macro PAD_SETSV() rather than calling this function directly.
 826  
 827      void    pad_setsv(PADOFFSET po, SV* sv)
 828  
 829  =for hackers
 830  Found in file pad.c
 831  
 832  =item pad_swipe
 833  X<pad_swipe>
 834  
 835  Abandon the tmp in the current pad at offset po and replace with a
 836  new one.
 837  
 838      void    pad_swipe(PADOFFSET po, bool refadjust)
 839  
 840  =for hackers
 841  Found in file pad.c
 842  
 843  =item pad_tidy
 844  X<pad_tidy>
 845  
 846  Tidy up a pad after we've finished compiling it:
 847      * remove most stuff from the pads of anonsub prototypes;
 848      * give it a @_;
 849      * mark tmps as such.
 850  
 851      void    pad_tidy(padtidy_type type)
 852  
 853  =for hackers
 854  Found in file pad.c
 855  
 856  =item pad_undef
 857  X<pad_undef>
 858  
 859  Free the padlist associated with a CV.
 860  If parts of it happen to be current, we null the relevant
 861  PL_*pad* global vars so that we don't have any dangling references left.
 862  We also repoint the CvOUTSIDE of any about-to-be-orphaned
 863  inner subs to the outer of this cv.
 864  
 865  (This function should really be called pad_free, but the name was already
 866  taken)
 867  
 868      void    pad_undef(CV* cv)
 869  
 870  =for hackers
 871  Found in file pad.c
 872  
 873  
 874  =back
 875  
 876  =head1 Per-Interpreter Variables
 877  
 878  =over 8
 879  
 880  =item PL_DBsingle
 881  X<PL_DBsingle>
 882  
 883  When Perl is run in debugging mode, with the B<-d> switch, this SV is a
 884  boolean which indicates whether subs are being single-stepped.
 885  Single-stepping is automatically turned on after every step.  This is the C
 886  variable which corresponds to Perl's $DB::single variable.  See
 887  C<PL_DBsub>.
 888  
 889      SV *    PL_DBsingle
 890  
 891  =for hackers
 892  Found in file intrpvar.h
 893  
 894  =item PL_DBsub
 895  X<PL_DBsub>
 896  
 897  When Perl is run in debugging mode, with the B<-d> switch, this GV contains
 898  the SV which holds the name of the sub being debugged.  This is the C
 899  variable which corresponds to Perl's $DB::sub variable.  See
 900  C<PL_DBsingle>.
 901  
 902      GV *    PL_DBsub
 903  
 904  =for hackers
 905  Found in file intrpvar.h
 906  
 907  =item PL_DBtrace
 908  X<PL_DBtrace>
 909  
 910  Trace variable used when Perl is run in debugging mode, with the B<-d>
 911  switch.  This is the C variable which corresponds to Perl's $DB::trace
 912  variable.  See C<PL_DBsingle>.
 913  
 914      SV *    PL_DBtrace
 915  
 916  =for hackers
 917  Found in file intrpvar.h
 918  
 919  =item PL_dowarn
 920  X<PL_dowarn>
 921  
 922  The C variable which corresponds to Perl's $^W warning variable.
 923  
 924      bool    PL_dowarn
 925  
 926  =for hackers
 927  Found in file intrpvar.h
 928  
 929  =item PL_last_in_gv
 930  X<PL_last_in_gv>
 931  
 932  The GV which was last used for a filehandle input operation. (C<< <FH> >>)
 933  
 934      GV*    PL_last_in_gv
 935  
 936  =for hackers
 937  Found in file intrpvar.h
 938  
 939  =item PL_ofs_sv
 940  X<PL_ofs_sv>
 941  
 942  The output field separator - C<$,> in Perl space.
 943  
 944      SV*    PL_ofs_sv
 945  
 946  =for hackers
 947  Found in file intrpvar.h
 948  
 949  =item PL_rs
 950  X<PL_rs>
 951  
 952  The input record separator - C<$/> in Perl space.
 953  
 954      SV*    PL_rs
 955  
 956  =for hackers
 957  Found in file intrpvar.h
 958  
 959  
 960  =back
 961  
 962  =head1 Stack Manipulation Macros
 963  
 964  =over 8
 965  
 966  =item djSP
 967  X<djSP>
 968  
 969  Declare Just C<SP>. This is actually identical to C<dSP>, and declares
 970  a local copy of perl's stack pointer, available via the C<SP> macro.
 971  See C<SP>.  (Available for backward source code compatibility with the
 972  old (Perl 5.005) thread model.)
 973  
 974          djSP;
 975  
 976  =for hackers
 977  Found in file pp.h
 978  
 979  =item LVRET
 980  X<LVRET>
 981  
 982  True if this op will be the return value of an lvalue subroutine
 983  
 984  =for hackers
 985  Found in file pp.h
 986  
 987  
 988  =back
 989  
 990  =head1 SV Manipulation Functions
 991  
 992  =over 8
 993  
 994  =item sv_add_arena
 995  X<sv_add_arena>
 996  
 997  Given a chunk of memory, link it to the head of the list of arenas,
 998  and split it into a list of free SVs.
 999  
1000      void    sv_add_arena(char* ptr, U32 size, U32 flags)
1001  
1002  =for hackers
1003  Found in file sv.c
1004  
1005  =item sv_clean_all
1006  X<sv_clean_all>
1007  
1008  Decrement the refcnt of each remaining SV, possibly triggering a
1009  cleanup. This function may have to be called multiple times to free
1010  SVs which are in complex self-referential hierarchies.
1011  
1012      I32    sv_clean_all()
1013  
1014  =for hackers
1015  Found in file sv.c
1016  
1017  =item sv_clean_objs
1018  X<sv_clean_objs>
1019  
1020  Attempt to destroy all objects not yet freed
1021  
1022      void    sv_clean_objs()
1023  
1024  =for hackers
1025  Found in file sv.c
1026  
1027  =item sv_free_arenas
1028  X<sv_free_arenas>
1029  
1030  Deallocate the memory used by all arenas. Note that all the individual SV
1031  heads and bodies within the arenas must already have been freed.
1032  
1033      void    sv_free_arenas()
1034  
1035  =for hackers
1036  Found in file sv.c
1037  
1038  
1039  =back
1040  
1041  =head1 SV-Body Allocation
1042  
1043  =over 8
1044  
1045  =item sv_2num
1046  X<sv_2num>
1047  
1048  Return an SV with the numeric value of the source SV, doing any necessary
1049  reference or overload conversion.  You must use the C<SvNUM(sv)> macro to
1050  access this function.
1051  
1052      SV*    sv_2num(SV* sv)
1053  
1054  =for hackers
1055  Found in file sv.c
1056  
1057  
1058  =back
1059  
1060  =head1 Unicode Support
1061  
1062  =over 8
1063  
1064  =item find_uninit_var
1065  X<find_uninit_var>
1066  
1067  Find the name of the undefined variable (if any) that caused the operator o
1068  to issue a "Use of uninitialized value" warning.
1069  If match is true, only return a name if it's value matches uninit_sv.
1070  So roughly speaking, if a unary operator (such as OP_COS) generates a
1071  warning, then following the direct child of the op may yield an
1072  OP_PADSV or OP_GV that gives the name of the undefined variable. On the
1073  other hand, with OP_ADD there are two branches to follow, so we only print
1074  the variable name if we get an exact match.
1075  
1076  The name is returned as a mortal SV.
1077  
1078  Assumes that PL_op is the op that originally triggered the error, and that
1079  PL_comppad/PL_curpad points to the currently executing pad.
1080  
1081      SV*    find_uninit_var(OP* obase, SV* uninit_sv, bool top)
1082  
1083  =for hackers
1084  Found in file sv.c
1085  
1086  =item report_uninit
1087  X<report_uninit>
1088  
1089  Print appropriate "Use of uninitialized variable" warning
1090  
1091      void    report_uninit(SV* uninit_sv)
1092  
1093  =for hackers
1094  Found in file sv.c
1095  
1096  
1097  =back
1098  
1099  =head1 AUTHORS
1100  
1101  The autodocumentation system was originally added to the Perl core by
1102  Benjamin Stuhl. Documentation is by whoever was kind enough to
1103  document their functions.
1104  
1105  =head1 SEE ALSO
1106  
1107  perlguts(1), perlapi(1)
1108  
1109  =cut
1110  
1111   ex: set ro: