1 -*- buffer-read-only: t -*-
3 !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
4 This file is built by autodoc.pl extracting documentation from the C source
9 perlintern - autogenerated documentation of purely B<internal>
13 X<internal Perl functions> X<interpreter functions>
15 This file is the autogenerated documentation of functions in the
16 Perl interpreter that are documented using Perl's internal documentation
17 format but are not marked as part of the Perl API. In other words,
18 B<they are not for use in extensions>!
21 =head1 CV reference counts and CvOUTSIDE
28 Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
29 CV (if any). Because pointers to anonymous sub prototypes are
30 stored in C<&> pad slots, it is a possible to get a circular reference,
31 with the parent pointing to the child and vice-versa. To avoid the
32 ensuing memory leak, we do not increment the reference count of the CV
33 pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
34 has a C<&> pad slot pointing back to us. In this case, we set the
35 C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
36 circumstances we should decrement the refcount of the parent when freeing
39 There is a further complication with non-closure anonymous subs (i.e. those
40 that do not refer to any lexicals outside that sub). In this case, the
41 anonymous prototype is shared rather than being cloned. This has the
42 consequence that the parent may be freed while there are still active
45 BEGIN { $a = sub { eval '$x' } }
47 In this case, the BEGIN is freed immediately after execution since there
48 are no active references to it: the anon sub prototype has
49 C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
50 CV, so it doesn't contribute to BEGIN's refcount either. When $a is
51 executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
52 and the freed BEGIN is accessed.
54 To avoid this, whenever a CV and its associated pad is freed, any
55 C<&> entries in the pad are explicitly removed from the pad, and if the
56 refcount of the pointed-to anon sub is still positive, then that
57 child's C<CvOUTSIDE> is set to point to its grandparent. This will only
58 occur in the single specific case of a non-closure anon prototype
59 having one or more active references (such as C<$a> above).
61 One other thing to consider is that a CV may be merely undefined
62 rather than freed, eg C<undef &foo>. In this case, its refcount may
63 not have reached zero, but we still delete its pad and its C<CvROOT> etc.
64 Since various children may still have their C<CvOUTSIDE> pointing at this
65 undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
66 the chain of lexical scopes is unbroken. For example, the following
70 sub tmp { sub { eval '$x' } }
75 bool CvWEAKOUTSIDE(CV *cv)
83 =head1 Functions in file pad.h
91 Save the current pad in the given context block structure.
93 void CX_CURPAD_SAVE(struct context)
101 Access the SV at offset po in the saved current pad in the given
102 context block structure (can be used as an lvalue).
104 SV * CX_CURPAD_SV(struct context, PADOFFSET po)
112 Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
114 SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
123 Clone the state variables associated with running and compiling pads.
125 void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
130 =item PAD_COMPNAME_FLAGS
131 X<PAD_COMPNAME_FLAGS>
133 Return the flags for the current compiling pad name
134 at offset C<po>. Assumes a valid slot entry.
136 U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
141 =item PAD_COMPNAME_GEN
144 The generation number of the name at offset C<po> in the current
145 compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
147 STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
152 =item PAD_COMPNAME_GEN_set
153 X<PAD_COMPNAME_GEN_set>
155 Sets the generation number of the name at offset C<po> in the current
156 ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose.
158 STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
163 =item PAD_COMPNAME_OURSTASH
164 X<PAD_COMPNAME_OURSTASH>
166 Return the stash associated with an C<our> variable.
167 Assumes the slot entry is a valid C<our> lexical.
169 HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
174 =item PAD_COMPNAME_PV
177 Return the name of the current compiling pad name
178 at offset C<po>. Assumes a valid slot entry.
180 char * PAD_COMPNAME_PV(PADOFFSET po)
185 =item PAD_COMPNAME_TYPE
188 Return the type (stash) of the current compiling pad name at offset
189 C<po>. Must be a valid name. Returns null if not typed.
191 HV * PAD_COMPNAME_TYPE(PADOFFSET po)
201 void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
206 =item PAD_RESTORE_LOCAL
209 Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
211 void PAD_RESTORE_LOCAL(PAD *opad)
219 Save the current pad to the local variable opad, then make the
220 current pad equal to npad
222 void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
227 =item PAD_SAVE_SETNULLPAD
228 X<PAD_SAVE_SETNULLPAD>
230 Save the current pad then set it to null.
232 void PAD_SAVE_SETNULLPAD()
240 Set the slot at offset C<po> in the current pad to C<sv>
242 SV * PAD_SETSV(PADOFFSET po, SV* sv)
250 Set the current pad to be pad C<n> in the padlist, saving
251 the previous current pad. NB currently this macro expands to a string too
252 long for some compilers, so it's best to replace it with
255 PAD_SET_CUR_NOSAVE(padlist,n);
258 void PAD_SET_CUR(PADLIST padlist, I32 n)
263 =item PAD_SET_CUR_NOSAVE
264 X<PAD_SET_CUR_NOSAVE>
266 like PAD_SET_CUR, but without the save
268 void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
276 Get the value at offset C<po> in the current pad
278 void PAD_SV(PADOFFSET po)
286 Lightweight and lvalue version of C<PAD_SV>.
287 Get or set the value at offset C<po> in the current pad.
288 Unlike C<PAD_SV>, does not print diagnostics with -DX.
289 For internal use only.
291 SV * PAD_SVl(PADOFFSET po)
299 Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
301 void SAVECLEARSV(SV **svp)
309 save PL_comppad and PL_curpad
323 Save a pad slot (used to restore after an iteration)
325 XXX DAPM it would make more sense to make the arg a PADOFFSET
326 void SAVEPADSV(PADOFFSET po)
341 Returns C<TRUE> if given the name of a magical GV.
343 Currently only useful internally when determining if a GV should be
344 created even in rvalue contexts.
346 C<flags> is not used at present but available for future extension to
347 allow selecting particular classes of magical variable.
349 Currently assumes that C<name> is NUL terminated (as well as len being valid).
350 This assumption is met by all callers within the perl core, which all pass
351 pointers returned by SvPV.
353 bool is_gv_magical(const char *name, STRLEN len, U32 flags)
358 =item is_gv_magical_sv
361 Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical.
363 bool is_gv_magical_sv(SV *name, U32 flags)
371 =head1 Hash Manipulation Functions
375 =item refcounted_he_chain_2hv
376 X<refcounted_he_chain_2hv>
378 Generates and returns a C<HV *> by walking up the tree starting at the passed
379 in C<struct refcounted_he *>.
381 HV * refcounted_he_chain_2hv(const struct refcounted_he *c)
386 =item refcounted_he_free
387 X<refcounted_he_free>
389 Decrements the reference count of the passed in C<struct refcounted_he *>
390 by one. If the reference count reaches zero the structure's memory is freed,
391 and C<refcounted_he_free> iterates onto the parent node.
393 void refcounted_he_free(struct refcounted_he *he)
398 =item refcounted_he_new
401 Creates a new C<struct refcounted_he>. As S<key> is copied, and value is
402 stored in a compact form, all references remain the property of the caller.
403 The C<struct refcounted_he> is returned with a reference count of 1.
405 struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value)
420 Function called by C<do_readline> to spawn a glob (or do the glob inside
421 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
422 this glob starter is only used by miniperl during the build process.
423 Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
425 PerlIO* start_glob(SV* pattern, IO *io)
433 =head1 Magical Functions
440 Triggered by a delete from %^H, records the key to
441 C<PL_compiling.cop_hints_hash>.
443 int magic_sethint(SV* sv, MAGIC* mg)
451 Copy some of the magic from an existing SV to new localized version of
452 that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic
453 doesn't (eg taint, pos).
455 void mg_localize(SV* sv, SV* nsv)
467 =item mro_isa_changed_in
468 X<mro_isa_changed_in>
470 Takes the necessary steps (cache invalidations, mostly)
471 when the @ISA of the given package has changed. Invoked
472 by the C<setisa> magic, should not need to invoke directly.
474 void mro_isa_changed_in(HV* stash)
482 =head1 Pad Data Structures
489 CV's can have CvPADLIST(cv) set to point to an AV.
491 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
492 not callable at will and are always thrown away after the eval"" is done
493 executing). Require'd files are simply evals without any outer lexical
496 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
497 but that is really the callers pad (a slot of which is allocated by
500 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
501 is managed "manual" (mostly in pad.c) rather than normal av.c rules.
502 The items in the AV are not SVs as for a normal AV, but other AVs:
504 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
505 the "static type information" for lexicals.
507 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
508 depth of recursion into the CV.
509 The 0'th slot of a frame AV is an AV which is @_.
510 other entries are storage for variables and op targets.
513 C<PL_comppad_name> is set to the names AV.
514 C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
515 C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
517 During execution, C<PL_comppad> and C<PL_curpad> refer to the live
518 frame of the currently executing sub.
520 Iterating over the names AV iterates over all possible pad
521 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
522 &PL_sv_undef "names" (see pad_alloc()).
524 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
525 The rest are op targets/GVs/constants which are statically allocated
526 or resolved at compile time. These don't have names by which they
527 can be looked up from Perl code at run time through eval"" like
528 my/our variables can be. Since they can't be looked up by "name"
529 but only by their index allocated at compile time (which is usually
530 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
532 The SVs in the names AV have their PV being the name of the variable.
533 xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for
534 which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH
535 points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the
536 SvOURSTASH slot pointing at the stash of the associated global (so that
537 duplicate C<our> declarations in the same package can be detected). SvUVX is
538 sometimes hijacked to store the generation number during compilation.
540 If SvFAKE is set on the name SV, then that slot in the frame AV is
541 a REFCNT'ed reference to a lexical from "outside". In this case,
542 the name SV does not use xlow and xhigh to store a cop_seq range, since it is
543 in scope throughout. Instead xhigh stores some flags containing info about
544 the real lexical (is it declared in an anon, and is it capable of being
545 instantiated multiple times?), and for fake ANONs, xlow contains the index
546 within the parent's pad where the lexical's value is stored, to make
549 If the 'name' is '&' the corresponding entry in frame AV
550 is a CV representing a possible closure.
551 (SvFAKE and name of '&' is not a meaningful combination currently but could
552 become so if C<my sub foo {}> is implemented.)
554 Note that formats are treated as anon subs, and are cloned each time
555 write is called (if necessary).
557 The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
558 and set on scope exit. This allows the 'Variable $x is not available' warning
559 to be generated in evals, such as
561 { my $x = 1; sub f { eval '$x'} } f();
563 AV * CvPADLIST(CV *cv)
571 Clone a CV: make a new CV which points to the same code etc, but which
572 has a newly-created pad built by copying the prototype pad and capturing
575 CV* cv_clone(CV* proto)
583 dump the contents of a CV
585 void cv_dump(const CV *cv, const char *title)
593 Dump the contents of a padlist
595 void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
603 "Introduce" my variables to visible status.
613 Add an anon code entry to the current compiling pad
615 PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
623 Create a new name and associated PADMY SV in the current pad; return the
625 If C<typestash> is valid, the name is for a typed lexical; set the
626 name's stash to that value.
627 If C<ourstash> is valid, it's an our lexical, set the name's
628 SvOURSTASH to that value
630 If fake, it means we're cloning an existing entry
632 PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state)
640 Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
641 the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
642 for a slot which has no name and no active value.
644 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
649 =item pad_block_start
652 Update the pad compilation state variables on entry to a new block
654 void pad_block_start(int full)
662 Check for duplicate declarations: report any of:
663 * a my in the current scope with the same name;
664 * an our (anywhere in the pad) with the same name and the same stash
666 C<is_our> indicates that the name to check is an 'our' declaration
668 void pad_check_dup(const char* name, bool is_our, const HV* ourstash)
676 Find a named lexical anywhere in a chain of nested pads. Add fake entries
677 in the inner pads if it's found in an outer one.
679 Returns the offset in the bottom pad of the lex or the fake lex.
680 cv is the CV in which to start the search, and seq is the current cop_seq
681 to match against. If warn is true, print appropriate warnings. The out_*
682 vars return values, and so are pointers to where the returned values
683 should be stored. out_capture, if non-null, requests that the innermost
684 instance of the lexical is captured; out_name_sv is set to the innermost
685 matched namesv or fake namesv; out_flags returns the flags normally
686 associated with the IVX field of a fake namesv.
688 Note that pad_findlex() is recursive; it recurses up the chain of CVs,
689 then comes back down, adding fake entries as it goes. It has to be this way
690 because fake namesvs in anon protoypes have to store in xlow the index into
693 PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
701 Given a lexical name, try to find its offset, first in the current pad,
702 or failing that, in the pads of any lexically enclosing subs (including
703 the complications introduced by eval). If the name is found in an outer pad,
704 then a fake entry is added to the current pad.
705 Returns the offset in the current pad, or NOT_IN_PAD on failure.
707 PADOFFSET pad_findmy(const char* name)
712 =item pad_fixup_inner_anons
713 X<pad_fixup_inner_anons>
715 For any anon CVs in the pad, change CvOUTSIDE of that CV from
716 old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
717 moved to a pre-existing CV struct.
719 void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
727 Free the SV at offset po in the current pad.
729 void pad_free(PADOFFSET po)
737 Cleanup at end of scope during compilation: set the max seq number for
738 lexicals in this scope and warn of any lexicals that never got introduced.
748 Create a new compiling padlist, saving and updating the various global
749 vars at the same time as creating the pad itself. The following flags
750 can be OR'ed together:
752 padnew_CLONE this pad is for a cloned CV
753 padnew_SAVE save old globals
754 padnew_SAVESUB also save extra stuff for start of sub
756 PADLIST* pad_new(int flags)
764 Push a new pad frame onto the padlist, unless there's already a pad at
765 this depth, in which case don't bother creating a new one. Then give
766 the new pad an @_ in slot zero.
768 void pad_push(PADLIST *padlist, int depth)
776 Mark all the current temporaries for reuse
786 Set the entry at offset po in the current pad to sv.
787 Use the macro PAD_SETSV() rather than calling this function directly.
789 void pad_setsv(PADOFFSET po, SV* sv)
797 Abandon the tmp in the current pad at offset po and replace with a
800 void pad_swipe(PADOFFSET po, bool refadjust)
808 Tidy up a pad after we've finished compiling it:
809 * remove most stuff from the pads of anonsub prototypes;
813 void pad_tidy(padtidy_type type)
821 Free the padlist associated with a CV.
822 If parts of it happen to be current, we null the relevant
823 PL_*pad* global vars so that we don't have any dangling references left.
824 We also repoint the CvOUTSIDE of any about-to-be-orphaned
825 inner subs to the outer of this cv.
827 (This function should really be called pad_free, but the name was already
830 void pad_undef(CV* cv)
838 =head1 Per-Interpreter Variables
845 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
846 boolean which indicates whether subs are being single-stepped.
847 Single-stepping is automatically turned on after every step. This is the C
848 variable which corresponds to Perl's $DB::single variable. See
854 Found in file intrpvar.h
859 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
860 the SV which holds the name of the sub being debugged. This is the C
861 variable which corresponds to Perl's $DB::sub variable. See
867 Found in file intrpvar.h
872 Trace variable used when Perl is run in debugging mode, with the B<-d>
873 switch. This is the C variable which corresponds to Perl's $DB::trace
874 variable. See C<PL_DBsingle>.
879 Found in file intrpvar.h
884 The C variable which corresponds to Perl's $^W warning variable.
889 Found in file intrpvar.h
894 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
899 Found in file intrpvar.h
904 The output field separator - C<$,> in Perl space.
909 Found in file intrpvar.h
914 The input record separator - C<$/> in Perl space.
919 Found in file intrpvar.h
924 =head1 Stack Manipulation Macros
931 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
932 a local copy of perl's stack pointer, available via the C<SP> macro.
933 See C<SP>. (Available for backward source code compatibility with the
934 old (Perl 5.005) thread model.)
944 True if this op will be the return value of an lvalue subroutine
952 =head1 SV Manipulation Functions
959 Given a chunk of memory, link it to the head of the list of arenas,
960 and split it into a list of free SVs.
962 void sv_add_arena(char* ptr, U32 size, U32 flags)
970 Decrement the refcnt of each remaining SV, possibly triggering a
971 cleanup. This function may have to be called multiple times to free
972 SVs which are in complex self-referential hierarchies.
982 Attempt to destroy all objects not yet freed
992 Deallocate the memory used by all arenas. Note that all the individual SV
993 heads and bodies within the arenas must already have been freed.
995 void sv_free_arenas()
1003 =head1 Unicode Support
1007 =item find_uninit_var
1010 Find the name of the undefined variable (if any) that caused the operator o
1011 to issue a "Use of uninitialized value" warning.
1012 If match is true, only return a name if it's value matches uninit_sv.
1013 So roughly speaking, if a unary operator (such as OP_COS) generates a
1014 warning, then following the direct child of the op may yield an
1015 OP_PADSV or OP_GV that gives the name of the undefined variable. On the
1016 other hand, with OP_ADD there are two branches to follow, so we only print
1017 the variable name if we get an exact match.
1019 The name is returned as a mortal SV.
1021 Assumes that PL_op is the op that originally triggered the error, and that
1022 PL_comppad/PL_curpad points to the currently executing pad.
1024 SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top)
1032 Print appropriate "Use of uninitialized variable" warning
1034 void report_uninit(SV* uninit_sv)
1044 The autodocumentation system was originally added to the Perl core by
1045 Benjamin Stuhl. Documentation is by whoever was kind enough to
1046 document their functions.
1050 perlguts(1), perlapi(1)
projects / p5sagit/p5-mst-13.2.git / blob