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