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