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