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