pod/perlintern.pod

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