pod/perlintern.pod

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