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
 464 that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic
 465 doesn't (eg taint, pos).
 466
 467         void    mg_localize(SV* sv, SV* nsv)
 468
 469 =for hackers
 470 Found in file mg.c
 471
 472
 473 =back
 474
 475 =head1 MRO Functions
 476
 477 =over 8
 478
 479 =item mro_get_linear_isa_c3
 480 X<mro_get_linear_isa_c3>
 481
 482 Returns the C3 linearization of @ISA
 483 the given stash.  The return value is a read-only AV*.
 484 C<level> should be 0 (it is used internally in this
 485 function's recursion).
 486
 487 You are responsible for C<SvREFCNT_inc()> on the
 488 return value if you plan to store it anywhere
 489 semi-permanently (otherwise it might be deleted
 490 out from under you the next time the cache is
 491 invalidated).
 492
 493         AV*     mro_get_linear_isa_c3(HV* stash, I32 level)
 494
 495 =for hackers
 496 Found in file mro.c
 497
 498 =item mro_get_linear_isa_dfs
 499 X<mro_get_linear_isa_dfs>
 500
 501 Returns the Depth-First Search linearization of @ISA
 502 the given stash.  The return value is a read-only AV*.
 503 C<level> should be 0 (it is used internally in this
 504 function's recursion).
 505
 506 You are responsible for C<SvREFCNT_inc()> on the
 507 return value if you plan to store it anywhere
 508 semi-permanently (otherwise it might be deleted
 509 out from under you the next time the cache is
 510 invalidated).
 511
 512         AV*     mro_get_linear_isa_dfs(HV* stash, I32 level)
 513
 514 =for hackers
 515 Found in file mro.c
 516
 517 =item mro_isa_changed_in
 518 X<mro_isa_changed_in>
 519
 520 Takes the necessary steps (cache invalidations, mostly)
 521 when the @ISA of the given package has changed.  Invoked
 522 by the C<setisa> magic, should not need to invoke directly.
 523
 524         void    mro_isa_changed_in(HV* stash)
 525
 526 =for hackers
 527 Found in file mro.c
 528
 529
 530 =back
 531
 532 =head1 Pad Data Structures
 533
 534 =over 8
 535
 536 =item CvPADLIST
 537 X<CvPADLIST>
 538
 539 CV's can have CvPADLIST(cv) set to point to an AV.
 540
 541 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
 542 not callable at will and are always thrown away after the eval"" is done
 543 executing). Require'd files are simply evals without any outer lexical
 544 scope.
 545
 546 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
 547 but that is really the callers pad (a slot of which is allocated by
 548 every entersub).
 549
 550 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
 551 is managed "manual" (mostly in pad.c) rather than normal av.c rules.
 552 The items in the AV are not SVs as for a normal AV, but other AVs:
 553
 554 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
 555 the "static type information" for lexicals.
 556
 557 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
 558 depth of recursion into the CV.
 559 The 0'th slot of a frame AV is an AV which is @_.
 560 other entries are storage for variables and op targets.
 561
 562 During compilation:
 563 C<PL_comppad_name> is set to the names AV.
 564 C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
 565 C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
 566
 567 During execution, C<PL_comppad> and C<PL_curpad> refer to the live
 568 frame of the currently executing sub.
 569
 570 Iterating over the names AV iterates over all possible pad
 571 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
 572 &PL_sv_undef "names" (see pad_alloc()).
 573
 574 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
 575 The rest are op targets/GVs/constants which are statically allocated
 576 or resolved at compile time.  These don't have names by which they
 577 can be looked up from Perl code at run time through eval"" like
 578 my/our variables can be.  Since they can't be looked up by "name"
 579 but only by their index allocated at compile time (which is usually
 580 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
 581
 582 The SVs in the names AV have their PV being the name of the variable.
 583 xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for
 584 which the name is valid.  For typed lexicals name SV is SVt_PVMG and SvSTASH
 585 points at the type.  For C<our> lexicals, the type is also SVt_PVMG, with the
 586 SvOURSTASH slot pointing at the stash of the associated global (so that
 587 duplicate C<our> declarations in the same package can be detected).  SvUVX is
 588 sometimes hijacked to store the generation number during compilation.
 589
 590 If SvFAKE is set on the name SV, then that slot in the frame AV is
 591 a REFCNT'ed reference to a lexical from "outside". In this case,
 592 the name SV does not use xlow and xhigh to store a cop_seq range, since it is
 593 in scope throughout. Instead xhigh stores some flags containing info about
 594 the real lexical (is it declared in an anon, and is it capable of being
 595 instantiated multiple times?), and for fake ANONs, xlow contains the index
 596 within the parent's pad where the lexical's value is stored, to make
 597 cloning quicker.
 598
 599 If the 'name' is '&' the corresponding entry in frame AV
 600 is a CV representing a possible closure.
 601 (SvFAKE and name of '&' is not a meaningful combination currently but could
 602 become so if C<my sub foo {}> is implemented.)
 603
 604 Note that formats are treated as anon subs, and are cloned each time
 605 write is called (if necessary).
 606
 607 The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
 608 and set on scope exit. This allows the 'Variable $x is not available' warning
 609 to be generated in evals, such as
 610
 611     { my $x = 1; sub f { eval '$x'} } f();
 612
 613 For state vars, SVf_PADSTALE is overloaded to mean 'not yet initialised'
 614
 615         AV *    CvPADLIST(CV *cv)
 616
 617 =for hackers
 618 Found in file pad.c
 619
 620 =item cv_clone
 621 X<cv_clone>
 622
 623 Clone a CV: make a new CV which points to the same code etc, but which
 624 has a newly-created pad built by copying the prototype pad and capturing
 625 any outer lexicals.
 626
 627         CV*     cv_clone(CV* proto)
 628
 629 =for hackers
 630 Found in file pad.c
 631
 632 =item cv_dump
 633 X<cv_dump>
 634
 635 dump the contents of a CV
 636
 637         void    cv_dump(const CV *cv, const char *title)
 638
 639 =for hackers
 640 Found in file pad.c
 641
 642 =item do_dump_pad
 643 X<do_dump_pad>
 644
 645 Dump the contents of a padlist
 646
 647         void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
 648
 649 =for hackers
 650 Found in file pad.c
 651
 652 =item intro_my
 653 X<intro_my>
 654
 655 "Introduce" my variables to visible status.
 656
 657         U32     intro_my()
 658
 659 =for hackers
 660 Found in file pad.c
 661
 662 =item pad_add_anon
 663 X<pad_add_anon>
 664
 665 Add an anon code entry to the current compiling pad
 666
 667         PADOFFSET       pad_add_anon(SV* sv, OPCODE op_type)
 668
 669 =for hackers
 670 Found in file pad.c
 671
 672 =item pad_add_name
 673 X<pad_add_name>
 674
 675 Create a new name and associated PADMY SV in the current pad; return the
 676 offset.
 677 If C<typestash> is valid, the name is for a typed lexical; set the
 678 name's stash to that value.
 679 If C<ourstash> is valid, it's an our lexical, set the name's
 680 SvOURSTASH to that value
 681
 682 If fake, it means we're cloning an existing entry
 683
 684         PADOFFSET       pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state)
 685
 686 =for hackers
 687 Found in file pad.c
 688
 689 =item pad_alloc
 690 X<pad_alloc>
 691
 692 Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
 693 the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
 694 for a slot which has no name and no active value.
 695
 696         PADOFFSET       pad_alloc(I32 optype, U32 tmptype)
 697
 698 =for hackers
 699 Found in file pad.c
 700
 701 =item pad_block_start
 702 X<pad_block_start>
 703
 704 Update the pad compilation state variables on entry to a new block
 705
 706         void    pad_block_start(int full)
 707
 708 =for hackers
 709 Found in file pad.c
 710
 711 =item pad_check_dup
 712 X<pad_check_dup>
 713
 714 Check for duplicate declarations: report any of:
 715      * a my in the current scope with the same name;
 716      * an our (anywhere in the pad) with the same name and the same stash
 717        as C<ourstash>
 718 C<is_our> indicates that the name to check is an 'our' declaration
 719
 720         void    pad_check_dup(const char* name, bool is_our, const HV* ourstash)
 721
 722 =for hackers
 723 Found in file pad.c
 724
 725 =item pad_findlex
 726 X<pad_findlex>
 727
 728 Find a named lexical anywhere in a chain of nested pads. Add fake entries
 729 in the inner pads if it's found in an outer one.
 730
 731 Returns the offset in the bottom pad of the lex or the fake lex.
 732 cv is the CV in which to start the search, and seq is the current cop_seq
 733 to match against. If warn is true, print appropriate warnings.  The out_*
 734 vars return values, and so are pointers to where the returned values
 735 should be stored. out_capture, if non-null, requests that the innermost
 736 instance of the lexical is captured; out_name_sv is set to the innermost
 737 matched namesv or fake namesv; out_flags returns the flags normally
 738 associated with the IVX field of a fake namesv.
 739
 740 Note that pad_findlex() is recursive; it recurses up the chain of CVs,
 741 then comes back down, adding fake entries as it goes. It has to be this way
 742 because fake namesvs in anon protoypes have to store in xlow the index into
 743 the parent pad.
 744
 745         PADOFFSET       pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
 746
 747 =for hackers
 748 Found in file pad.c
 749
 750 =item pad_findmy
 751 X<pad_findmy>
 752
 753 Given a lexical name, try to find its offset, first in the current pad,
 754 or failing that, in the pads of any lexically enclosing subs (including
 755 the complications introduced by eval). If the name is found in an outer pad,
 756 then a fake entry is added to the current pad.
 757 Returns the offset in the current pad, or NOT_IN_PAD on failure.
 758
 759         PADOFFSET       pad_findmy(const char* name)
 760
 761 =for hackers
 762 Found in file pad.c
 763
 764 =item pad_fixup_inner_anons
 765 X<pad_fixup_inner_anons>
 766
 767 For any anon CVs in the pad, change CvOUTSIDE of that CV from
 768 old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
 769 moved to a pre-existing CV struct.
 770
 771         void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
 772
 773 =for hackers
 774 Found in file pad.c
 775
 776 =item pad_free
 777 X<pad_free>
 778
 779 Free the SV at offset po in the current pad.
 780
 781         void    pad_free(PADOFFSET po)
 782
 783 =for hackers
 784 Found in file pad.c
 785
 786 =item pad_leavemy
 787 X<pad_leavemy>
 788
 789 Cleanup at end of scope during compilation: set the max seq number for
 790 lexicals in this scope and warn of any lexicals that never got introduced.
 791
 792         void    pad_leavemy()
 793
 794 =for hackers
 795 Found in file pad.c
 796
 797 =item pad_new
 798 X<pad_new>
 799
 800 Create a new compiling padlist, saving and updating the various global
 801 vars at the same time as creating the pad itself. The following flags
 802 can be OR'ed together:
 803
 804     padnew_CLONE        this pad is for a cloned CV
 805     padnew_SAVE         save old globals
 806     padnew_SAVESUB      also save extra stuff for start of sub
 807
 808         PADLIST*        pad_new(int flags)
 809
 810 =for hackers
 811 Found in file pad.c
 812
 813 =item pad_push
 814 X<pad_push>
 815
 816 Push a new pad frame onto the padlist, unless there's already a pad at
 817 this depth, in which case don't bother creating a new one.  Then give
 818 the new pad an @_ in slot zero.
 819
 820         void    pad_push(PADLIST *padlist, int depth)
 821
 822 =for hackers
 823 Found in file pad.c
 824
 825 =item pad_reset
 826 X<pad_reset>
 827
 828 Mark all the current temporaries for reuse
 829
 830         void    pad_reset()
 831
 832 =for hackers
 833 Found in file pad.c
 834
 835 =item pad_setsv
 836 X<pad_setsv>
 837
 838 Set the entry at offset po in the current pad to sv.
 839 Use the macro PAD_SETSV() rather than calling this function directly.
 840
 841         void    pad_setsv(PADOFFSET po, SV* sv)
 842
 843 =for hackers
 844 Found in file pad.c
 845
 846 =item pad_swipe
 847 X<pad_swipe>
 848
 849 Abandon the tmp in the current pad at offset po and replace with a
 850 new one.
 851
 852         void    pad_swipe(PADOFFSET po, bool refadjust)
 853
 854 =for hackers
 855 Found in file pad.c
 856
 857 =item pad_tidy
 858 X<pad_tidy>
 859
 860 Tidy up a pad after we've finished compiling it:
 861     * remove most stuff from the pads of anonsub prototypes;
 862     * give it a @_;
 863     * mark tmps as such.
 864
 865         void    pad_tidy(padtidy_type type)
 866
 867 =for hackers
 868 Found in file pad.c
 869
 870 =item pad_undef
 871 X<pad_undef>
 872
 873 Free the padlist associated with a CV.
 874 If parts of it happen to be current, we null the relevant
 875 PL_*pad* global vars so that we don't have any dangling references left.
 876 We also repoint the CvOUTSIDE of any about-to-be-orphaned
 877 inner subs to the outer of this cv.
 878
 879 (This function should really be called pad_free, but the name was already
 880 taken)
 881
 882         void    pad_undef(CV* cv)
 883
 884 =for hackers
 885 Found in file pad.c
 886
 887
 888 =back
 889
 890 =head1 Per-Interpreter Variables
 891
 892 =over 8
 893
 894 =item PL_DBsingle
 895 X<PL_DBsingle>
 896
 897 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
 898 boolean which indicates whether subs are being single-stepped.
 899 Single-stepping is automatically turned on after every step.  This is the C
 900 variable which corresponds to Perl's $DB::single variable.  See
 901 C<PL_DBsub>.
 902
 903         SV *    PL_DBsingle
 904
 905 =for hackers
 906 Found in file intrpvar.h
 907
 908 =item PL_DBsub
 909 X<PL_DBsub>
 910
 911 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
 912 the SV which holds the name of the sub being debugged.  This is the C
 913 variable which corresponds to Perl's $DB::sub variable.  See
 914 C<PL_DBsingle>.
 915
 916         GV *    PL_DBsub
 917
 918 =for hackers
 919 Found in file intrpvar.h
 920
 921 =item PL_DBtrace
 922 X<PL_DBtrace>
 923
 924 Trace variable used when Perl is run in debugging mode, with the B<-d>
 925 switch.  This is the C variable which corresponds to Perl's $DB::trace
 926 variable.  See C<PL_DBsingle>.
 927
 928         SV *    PL_DBtrace
 929
 930 =for hackers
 931 Found in file intrpvar.h
 932
 933 =item PL_dowarn
 934 X<PL_dowarn>
 935
 936 The C variable which corresponds to Perl's $^W warning variable.
 937
 938         bool    PL_dowarn
 939
 940 =for hackers
 941 Found in file intrpvar.h
 942
 943 =item PL_last_in_gv
 944 X<PL_last_in_gv>
 945
 946 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
 947
 948         GV*     PL_last_in_gv
 949
 950 =for hackers
 951 Found in file intrpvar.h
 952
 953 =item PL_ofs_sv
 954 X<PL_ofs_sv>
 955
 956 The output field separator - C<$,> in Perl space.
 957
 958         SV*     PL_ofs_sv
 959
 960 =for hackers
 961 Found in file intrpvar.h
 962
 963 =item PL_rs
 964 X<PL_rs>
 965
 966 The input record separator - C<$/> in Perl space.
 967
 968         SV*     PL_rs
 969
 970 =for hackers
 971 Found in file intrpvar.h
 972
 973
 974 =back
 975
 976 =head1 Stack Manipulation Macros
 977
 978 =over 8
 979
 980 =item djSP
 981 X<djSP>
 982
 983 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
 984 a local copy of perl's stack pointer, available via the C<SP> macro.
 985 See C<SP>.  (Available for backward source code compatibility with the
 986 old (Perl 5.005) thread model.)
 987
 988                 djSP;
 989
 990 =for hackers
 991 Found in file pp.h
 992
 993 =item LVRET
 994 X<LVRET>
 995
 996 True if this op will be the return value of an lvalue subroutine
 997
 998 =for hackers
 999 Found in file pp.h
1000
1001
1002 =back
1003
1004 =head1 SV Manipulation Functions
1005
1006 =over 8
1007
1008 =item sv_add_arena
1009 X<sv_add_arena>
1010
1011 Given a chunk of memory, link it to the head of the list of arenas,
1012 and split it into a list of free SVs.
1013
1014         void    sv_add_arena(char *const ptr, const U32 size, const U32 flags)
1015
1016 =for hackers
1017 Found in file sv.c
1018
1019 =item sv_clean_all
1020 X<sv_clean_all>
1021
1022 Decrement the refcnt of each remaining SV, possibly triggering a
1023 cleanup. This function may have to be called multiple times to free
1024 SVs which are in complex self-referential hierarchies.
1025
1026         I32     sv_clean_all()
1027
1028 =for hackers
1029 Found in file sv.c
1030
1031 =item sv_clean_objs
1032 X<sv_clean_objs>
1033
1034 Attempt to destroy all objects not yet freed
1035
1036         void    sv_clean_objs()
1037
1038 =for hackers
1039 Found in file sv.c
1040
1041 =item sv_free_arenas
1042 X<sv_free_arenas>
1043
1044 Deallocate the memory used by all arenas. Note that all the individual SV
1045 heads and bodies within the arenas must already have been freed.
1046
1047         void    sv_free_arenas()
1048
1049 =for hackers
1050 Found in file sv.c
1051
1052
1053 =back
1054
1055 =head1 SV-Body Allocation
1056
1057 =over 8
1058
1059 =item sv_2num
1060 X<sv_2num>
1061
1062 Return an SV with the numeric value of the source SV, doing any necessary
1063 reference or overload conversion.  You must use the C<SvNUM(sv)> macro to
1064 access this function.
1065
1066         SV*     sv_2num(SV *const sv)
1067
1068 =for hackers
1069 Found in file sv.c
1070
1071
1072 =back
1073
1074 =head1 Unicode Support
1075
1076 =over 8
1077
1078 =item find_uninit_var
1079 X<find_uninit_var>
1080
1081 Find the name of the undefined variable (if any) that caused the operator o
1082 to issue a "Use of uninitialized value" warning.
1083 If match is true, only return a name if it's value matches uninit_sv.
1084 So roughly speaking, if a unary operator (such as OP_COS) generates a
1085 warning, then following the direct child of the op may yield an
1086 OP_PADSV or OP_GV that gives the name of the undefined variable. On the
1087 other hand, with OP_ADD there are two branches to follow, so we only print
1088 the variable name if we get an exact match.
1089
1090 The name is returned as a mortal SV.
1091
1092 Assumes that PL_op is the op that originally triggered the error, and that
1093 PL_comppad/PL_curpad points to the currently executing pad.
1094
1095         SV*     find_uninit_var(OP* obase, SV* uninit_sv, bool top)
1096
1097 =for hackers
1098 Found in file sv.c
1099
1100 =item report_uninit
1101 X<report_uninit>
1102
1103 Print appropriate "Use of uninitialized variable" warning
1104
1105         void    report_uninit(SV* uninit_sv)
1106
1107 =for hackers
1108 Found in file sv.c
1109
1110
1111 =back
1112
1113 =head1 AUTHORS
1114
1115 The autodocumentation system was originally added to the Perl core by
1116 Benjamin Stuhl. Documentation is by whoever was kind enough to
1117 document their functions.
1118
1119 =head1 SEE ALSO
1120
1121 perlguts(1), perlapi(1)
1122
1123 =cut
1124
1125  ex: set ro: