X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlintern.pod;h=67ff429af01d51319de563623b65b7898039cc3b;hb=d77cdebfaf0c7eb784a132b575c93953a56db215;hp=de1f4b21e59b57f8825aaa2fd3b9347afe2d2715;hpb=f3548bdc4d2efd11e139d110e60764b9dae81319;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlintern.pod b/pod/perlintern.pod index de1f4b2..67ff429 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -1,9 +1,16 @@ +-*- buffer-read-only: t -*- + +!!!!!!! DO NOT EDIT THIS FILE !!!!!!! +This file is built by autodoc.pl extracting documentation from the C source +files. + =head1 NAME perlintern - autogenerated documentation of purely B Perl functions =head1 DESCRIPTION +X X This file is the autogenerated documentation of functions in the Perl interpreter that are documented using Perl's internal documentation @@ -11,12 +18,75 @@ format but are not marked as part of the Perl API. In other words, B! +=head1 CV reference counts and CvOUTSIDE + +=over 8 + +=item CvWEAKOUTSIDE +X + +Each CV has a pointer, C, to its lexically enclosing +CV (if any). Because pointers to anonymous sub prototypes are +stored in C<&> pad slots, it is a possible to get a circular reference, +with the parent pointing to the child and vice-versa. To avoid the +ensuing memory leak, we do not increment the reference count of the CV +pointed to by C in the I that the parent +has a C<&> pad slot pointing back to us. In this case, we set the +C flag in the child. This allows us to determine under what +circumstances we should decrement the refcount of the parent when freeing +the child. + +There is a further complication with non-closure anonymous subs (i.e. those +that do not refer to any lexicals outside that sub). In this case, the +anonymous prototype is shared rather than being cloned. This has the +consequence that the parent may be freed while there are still active +children, eg + + BEGIN { $a = sub { eval '$x' } } + +In this case, the BEGIN is freed immediately after execution since there +are no active references to it: the anon sub prototype has +C set since it's not a closure, and $a points to the same +CV, so it doesn't contribute to BEGIN's refcount either. When $a is +executed, the C causes the chain of Cs to be followed, +and the freed BEGIN is accessed. + +To avoid this, whenever a CV and its associated pad is freed, any +C<&> entries in the pad are explicitly removed from the pad, and if the +refcount of the pointed-to anon sub is still positive, then that +child's C is set to point to its grandparent. This will only +occur in the single specific case of a non-closure anon prototype +having one or more active references (such as C<$a> above). + +One other thing to consider is that a CV may be merely undefined +rather than freed, eg C. In this case, its refcount may +not have reached zero, but we still delete its pad and its C etc. +Since various children may still have their C pointing at this +undefined CV, we keep its own C for the time being, so that +the chain of lexical scopes is unbroken. For example, the following +should print 123: + + my $x = 123; + sub tmp { sub { eval '$x' } } + my $a = tmp(); + undef &tmp; + print $a->(); + + bool CvWEAKOUTSIDE(CV *cv) + +=for hackers +Found in file cv.h + + +=back + =head1 Functions in file pad.h =over 8 =item CX_CURPAD_SAVE +X Save the current pad in the given context block structure. @@ -26,6 +96,7 @@ Save the current pad in the given context block structure. Found in file pad.h =item CX_CURPAD_SV +X Access the SV at offset po in the saved current pad in the given context block structure (can be used as an lvalue). @@ -35,26 +106,28 @@ context block structure (can be used as an lvalue). =for hackers Found in file pad.h -=item PAD_BASE_SV +=item PAD_BASE_SV +X Get the value from slot C in the base (DEPTH=1) pad of a padlist - SV * PAD_BASE_SV (PADLIST padlist, PADOFFSET po) + SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po) =for hackers Found in file pad.h =item PAD_CLONE_VARS +X -|CLONE_PARAMS* param Clone the state variables associated with running and compiling pads. - void PAD_CLONE_VARS(PerlInterpreter *proto_perl \) + void PAD_CLONE_VARS(PerlInterpreter *proto_perl, CLONE_PARAMS* param) =for hackers Found in file pad.h =item PAD_COMPNAME_FLAGS +X Return the flags for the current compiling pad name at offset C. Assumes a valid slot entry. @@ -65,16 +138,29 @@ at offset C. Assumes a valid slot entry. Found in file pad.h =item PAD_COMPNAME_GEN +X The generation number of the name at offset C in the current -compiling pad (lvalue). Note that C is hijacked for this purpose. +compiling pad (lvalue). Note that C is hijacked for this purpose. STRLEN PAD_COMPNAME_GEN(PADOFFSET po) =for hackers Found in file pad.h +=item PAD_COMPNAME_GEN_set +X + +Sets the generation number of the name at offset C in the current +ling pad (lvalue) to C. Note that C is hijacked for this purpose. + + STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen) + +=for hackers +Found in file pad.h + =item PAD_COMPNAME_OURSTASH +X Return the stash associated with an C variable. Assumes the slot entry is a valid C lexical. @@ -85,6 +171,7 @@ Assumes the slot entry is a valid C lexical. Found in file pad.h =item PAD_COMPNAME_PV +X Return the name of the current compiling pad name at offset C. Assumes a valid slot entry. @@ -95,6 +182,7 @@ at offset C. Assumes a valid slot entry. Found in file pad.h =item PAD_COMPNAME_TYPE +X Return the type (stash) of the current compiling pad name at offset C. Must be a valid name. Returns null if not typed. @@ -105,6 +193,7 @@ C. Must be a valid name. Returns null if not typed. Found in file pad.h =item PAD_DUP +X Clone a padlist. @@ -114,6 +203,7 @@ Clone a padlist. Found in file pad.h =item PAD_RESTORE_LOCAL +X Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() @@ -123,6 +213,7 @@ Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() Found in file pad.h =item PAD_SAVE_LOCAL +X Save the current pad to the local variable opad, then make the current pad equal to npad @@ -133,6 +224,7 @@ current pad equal to npad Found in file pad.h =item PAD_SAVE_SETNULLPAD +X Save the current pad then set it to null. @@ -141,56 +233,77 @@ Save the current pad then set it to null. =for hackers Found in file pad.h -=item PAD_SETSV +=item PAD_SETSV +X Set the slot at offset C in the current pad to C - SV * PAD_SETSV (PADOFFSET po, SV* sv) + SV * PAD_SETSV(PADOFFSET po, SV* sv) =for hackers Found in file pad.h -=item PAD_SET_CUR +=item PAD_SET_CUR +X Set the current pad to be pad C in the padlist, saving -the previous current pad. +the previous current pad. NB currently this macro expands to a string too +long for some compilers, so it's best to replace it with + + SAVECOMPPAD(); + PAD_SET_CUR_NOSAVE(padlist,n); - void PAD_SET_CUR (PADLIST padlist, I32 n) + + void PAD_SET_CUR(PADLIST padlist, I32 n) =for hackers Found in file pad.h -=item PAD_SV +=item PAD_SET_CUR_NOSAVE +X + +like PAD_SET_CUR, but without the save + + void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n) + +=for hackers +Found in file pad.h + +=item PAD_SV +X Get the value at offset C in the current pad - void PAD_SV (PADOFFSET po) + void PAD_SV(PADOFFSET po) =for hackers Found in file pad.h -=item PAD_SVl +=item PAD_SVl +X Lightweight and lvalue version of C. Get or set the value at offset C in the current pad. Unlike C, does not print diagnostics with -DX. For internal use only. - SV * PAD_SVl (PADOFFSET po) + SV * PAD_SVl(PADOFFSET po) =for hackers Found in file pad.h -=item SAVECLEARSV +=item SAVECLEARSV +X -Clear the pointed to pad value on scope exit. (ie the runtime action of 'my') +Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my') - void SAVECLEARSV (SV **svp) + void SAVECLEARSV(SV **svp) =for hackers Found in file pad.h =item SAVECOMPPAD +X save PL_comppad and PL_curpad @@ -203,12 +316,13 @@ save PL_comppad and PL_curpad =for hackers Found in file pad.h -=item SAVEPADSV +=item SAVEPADSV +X Save a pad slot (used to restore after an iteration) XXX DAPM it would make more sense to make the arg a PADOFFSET - void SAVEPADSV (PADOFFSET po) + void SAVEPADSV(PADOFFSET po) =for hackers Found in file pad.h @@ -216,122 +330,188 @@ Found in file pad.h =back -=head1 Global Variables +=head1 GV Functions =over 8 -=item PL_DBsingle +=item is_gv_magical +X -When Perl is run in debugging mode, with the B<-d> switch, this SV is a -boolean which indicates whether subs are being single-stepped. -Single-stepping is automatically turned on after every step. This is the C -variable which corresponds to Perl's $DB::single variable. See -C. +Returns C if given the name of a magical GV. - SV * PL_DBsingle +Currently only useful internally when determining if a GV should be +created even in rvalue contexts. + +C is not used at present but available for future extension to +allow selecting particular classes of magical variable. + +Currently assumes that C is NUL terminated (as well as len being valid). +This assumption is met by all callers within the perl core, which all pass +pointers returned by SvPV. + + bool is_gv_magical(const char *name, STRLEN len, U32 flags) =for hackers -Found in file intrpvar.h +Found in file gv.c -=item PL_DBsub +=item is_gv_magical_sv +X -When Perl is run in debugging mode, with the B<-d> switch, this GV contains -the SV which holds the name of the sub being debugged. This is the C -variable which corresponds to Perl's $DB::sub variable. See -C. +Returns C if given the name of a magical GV. Calls is_gv_magical. - GV * PL_DBsub + bool is_gv_magical_sv(SV *name, U32 flags) =for hackers -Found in file intrpvar.h +Found in file gv.c -=item PL_DBtrace -Trace variable used when Perl is run in debugging mode, with the B<-d> -switch. This is the C variable which corresponds to Perl's $DB::trace -variable. See C. +=back - SV * PL_DBtrace +=head1 Hash Manipulation Functions -=for hackers -Found in file intrpvar.h +=over 8 -=item PL_dowarn +=item refcounted_he_chain_2hv +X -The C variable which corresponds to Perl's $^W warning variable. +Generates and returns a C by walking up the tree starting at the passed +in C. - bool PL_dowarn + HV * refcounted_he_chain_2hv(const struct refcounted_he *c) =for hackers -Found in file intrpvar.h +Found in file hv.c -=item PL_last_in_gv +=item refcounted_he_free +X -The GV which was last used for a filehandle input operation. (C<< >>) +Decrements the reference count of the passed in C +by one. If the reference count reaches zero the structure's memory is freed, +and C iterates onto the parent node. - GV* PL_last_in_gv + void refcounted_he_free(struct refcounted_he *he) =for hackers -Found in file thrdvar.h +Found in file hv.c -=item PL_ofs_sv +=item refcounted_he_new +X -The output field separator - C<$,> in Perl space. +Creates a new C. As S is copied, and value is +stored in a compact form, all references remain the property of the caller. +The C is returned with a reference count of 1. - SV* PL_ofs_sv + struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value) =for hackers -Found in file thrdvar.h +Found in file hv.c -=item PL_rs -The input record separator - C<$/> in Perl space. +=back - SV* PL_rs +=head1 IO Functions + +=over 8 + +=item start_glob +X + +Function called by C to spawn a glob (or do the glob inside +perl on VMS). This code used to be inline, but now perl uses C +this glob starter is only used by miniperl during the build process. +Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. + + PerlIO* start_glob(SV* pattern, IO *io) =for hackers -Found in file thrdvar.h +Found in file doio.c =back -=head1 GV Functions +=head1 Magical Functions =over 8 -=item is_gv_magical +=item magic_sethint +X -Returns C if given the name of a magical GV. +Triggered by a delete from %^H, records the key to +C. -Currently only useful internally when determining if a GV should be -created even in rvalue contexts. + int magic_sethint(SV* sv, MAGIC* mg) -C is not used at present but available for future extension to -allow selecting particular classes of magical variable. +=for hackers +Found in file mg.c + +=item mg_localize +X - bool is_gv_magical(char *name, STRLEN len, U32 flags) +Copy some of the magic from an existing SV to new localized version of +that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic +doesn't (eg taint, pos). + + void mg_localize(SV* sv, SV* nsv) =for hackers -Found in file gv.c +Found in file mg.c =back -=head1 IO Functions +=head1 MRO Functions =over 8 -=item start_glob +=item mro_get_linear_isa_c3 +X -Function called by C to spawn a glob (or do the glob inside -perl on VMS). This code used to be inline, but now perl uses C -this glob starter is only used by miniperl during the build process. -Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. +Returns the C3 linearization of @ISA +the given stash. The return value is a read-only AV*. +C should be 0 (it is used internally in this +function's recursion). - PerlIO* start_glob(SV* pattern, IO *io) +You are responsible for C on the +return value if you plan to store it anywhere +semi-permanently (otherwise it might be deleted +out from under you the next time the cache is +invalidated). + + AV* mro_get_linear_isa_c3(HV* stash, I32 level) =for hackers -Found in file doio.c +Found in file mro.c + +=item mro_get_linear_isa_dfs +X + +Returns the Depth-First Search linearization of @ISA +the given stash. The return value is a read-only AV*. +C should be 0 (it is used internally in this +function's recursion). + +You are responsible for C on the +return value if you plan to store it anywhere +semi-permanently (otherwise it might be deleted +out from under you the next time the cache is +invalidated). + + AV* mro_get_linear_isa_dfs(HV* stash, I32 level) + +=for hackers +Found in file mro.c + +=item mro_isa_changed_in +X + +Takes the necessary steps (cache invalidations, mostly) +when the @ISA of the given package has changed. Invoked +by the C magic, should not need to invoke directly. + + void mro_isa_changed_in(HV* stash) + +=for hackers +Found in file mro.c =back @@ -341,12 +521,14 @@ Found in file doio.c =over 8 =item CvPADLIST +X CV's can have CvPADLIST(cv) set to point to an AV. For these purposes "forms" are a kind-of CV, eval""s are too (except they're not callable at will and are always thrown away after the eval"" is done -executing). +executing). Require'd files are simply evals without any outer lexical +scope. XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, but that is really the callers pad (a slot of which is allocated by @@ -365,9 +547,9 @@ The 0'th slot of a frame AV is an AV which is @_. other entries are storage for variables and op targets. During compilation: -C is set the the the names AV. -C is set the the frame AV for the frame CvDEPTH == 1. -C is set the body of the frame AV (i.e. AvARRAY(PL_comppad)). +C is set to the names AV. +C is set to the frame AV for the frame CvDEPTH == 1. +C is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). During execution, C and C refer to the live frame of the currently executing sub. @@ -385,27 +567,43 @@ but only by their index allocated at compile time (which is usually in PL_op->op_targ), wasting a name SV for them doesn't make sense. The SVs in the names AV have their PV being the name of the variable. -NV+1..IV inclusive is a range of cop_seq numbers for which the name is -valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the -type. For C lexicals, the type is SVt_PVGV, and GvSTASH points at the -stash of the associated global (so that duplicate C delarations in the -same package can be detected). SvCUR is sometimes hijacked to -store the generation number during compilation. - -If SvFAKE is set on the name SV then slot in the frame AVs are -a REFCNT'ed references to a lexical from "outside". - -If the 'name' is '&' the the corresponding entry in frame AV +xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for +which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH +points at the type. For C lexicals, the type is also SVt_PVMG, with the +SvOURSTASH slot pointing at the stash of the associated global (so that +duplicate C declarations in the same package can be detected). SvUVX is +sometimes hijacked to store the generation number during compilation. + +If SvFAKE is set on the name SV, then that slot in the frame AV is +a REFCNT'ed reference to a lexical from "outside". In this case, +the name SV does not use xlow and xhigh to store a cop_seq range, since it is +in scope throughout. Instead xhigh stores some flags containing info about +the real lexical (is it declared in an anon, and is it capable of being +instantiated multiple times?), and for fake ANONs, xlow contains the index +within the parent's pad where the lexical's value is stored, to make +cloning quicker. + +If the 'name' is '&' the corresponding entry in frame AV is a CV representing a possible closure. (SvFAKE and name of '&' is not a meaningful combination currently but could become so if C is implemented.) +Note that formats are treated as anon subs, and are cloned each time +write is called (if necessary). + +The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, +and set on scope exit. This allows the 'Variable $x is not available' warning +to be generated in evals, such as + + { my $x = 1; sub f { eval '$x'} } f(); + AV * CvPADLIST(CV *cv) =for hackers Found in file pad.c =item cv_clone +X Clone a CV: make a new CV which points to the same code etc, but which has a newly-created pad built by copying the prototype pad and capturing @@ -417,15 +615,17 @@ any outer lexicals. Found in file pad.c =item cv_dump +X dump the contents of a CV - void cv_dump(CV *cv, char *title) + void cv_dump(const CV *cv, const char *title) =for hackers Found in file pad.c =item do_dump_pad +X Dump the contents of a padlist @@ -435,6 +635,7 @@ Dump the contents of a padlist Found in file pad.c =item intro_my +X "Introduce" my variables to visible status. @@ -444,6 +645,7 @@ Found in file pad.c Found in file pad.c =item pad_add_anon +X Add an anon code entry to the current compiling pad @@ -453,27 +655,28 @@ Add an anon code entry to the current compiling pad Found in file pad.c =item pad_add_name +X -Create a new name in the current pad at the specified offset. +Create a new name and associated PADMY SV in the current pad; return the +offset. If C is valid, the name is for a typed lexical; set the name's stash to that value. If C is valid, it's an our lexical, set the name's -GvSTASH to that value - -Also, if the name is @.. or %.., create a new array or hash for that slot +SvOURSTASH to that value If fake, it means we're cloning an existing entry - PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone) + PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state) =for hackers Found in file pad.c =item pad_alloc +X Allocate a new my or tmp pad entry. For a my, simply push a null SV onto the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards -for a slot which has no name and and no active value. +for a slot which has no name and no active value. PADOFFSET pad_alloc(I32 optype, U32 tmptype) @@ -481,6 +684,7 @@ for a slot which has no name and and no active value. Found in file pad.c =item pad_block_start +X Update the pad compilation state variables on entry to a new block @@ -490,6 +694,7 @@ Update the pad compilation state variables on entry to a new block Found in file pad.c =item pad_check_dup +X Check for duplicate declarations: report any of: * a my in the current scope with the same name; @@ -497,24 +702,38 @@ Check for duplicate declarations: report any of: as C C indicates that the name to check is an 'our' declaration - void pad_check_dup(char* name, bool is_our, HV* ourstash) + void pad_check_dup(const char* name, bool is_our, const HV* ourstash) =for hackers Found in file pad.c =item pad_findlex +X Find a named lexical anywhere in a chain of nested pads. Add fake entries -in the inner pads if its found in an outer one. +in the inner pads if it's found in an outer one. + +Returns the offset in the bottom pad of the lex or the fake lex. +cv is the CV in which to start the search, and seq is the current cop_seq +to match against. If warn is true, print appropriate warnings. The out_* +vars return values, and so are pointers to where the returned values +should be stored. out_capture, if non-null, requests that the innermost +instance of the lexical is captured; out_name_sv is set to the innermost +matched namesv or fake namesv; out_flags returns the flags normally +associated with the IVX field of a fake namesv. -If flags == FINDLEX_NOSEARCH we don't bother searching outer contexts. +Note that pad_findlex() is recursive; it recurses up the chain of CVs, +then comes back down, adding fake entries as it goes. It has to be this way +because fake namesvs in anon protoypes have to store in xlow the index into +the parent pad. - PADOFFSET pad_findlex(char* name, PADOFFSET newoff, U32 seq, CV* startcv, I32 cx_ix, I32 saweval, U32 flags) + PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) =for hackers Found in file pad.c =item pad_findmy +X Given a lexical name, try to find its offset, first in the current pad, or failing that, in the pads of any lexically enclosing subs (including @@ -522,15 +741,17 @@ the complications introduced by eval). If the name is found in an outer pad, then a fake entry is added to the current pad. Returns the offset in the current pad, or NOT_IN_PAD on failure. - PADOFFSET pad_findmy(char* name) + PADOFFSET pad_findmy(const char* name) =for hackers Found in file pad.c =item pad_fixup_inner_anons +X For any anon CVs in the pad, change CvOUTSIDE of that CV from -old_cv to new_cv if necessary. +old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be +moved to a pre-existing CV struct. void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) @@ -538,8 +759,9 @@ old_cv to new_cv if necessary. Found in file pad.c =item pad_free +X -Free the SV at offet po in the current pad. +Free the SV at offset po in the current pad. void pad_free(PADOFFSET po) @@ -547,6 +769,7 @@ Free the SV at offet po in the current pad. Found in file pad.c =item pad_leavemy +X Cleanup at end of scope during compilation: set the max seq number for lexicals in this scope and warn of any lexicals that never got introduced. @@ -557,6 +780,7 @@ lexicals in this scope and warn of any lexicals that never got introduced. Found in file pad.c =item pad_new +X Create a new compiling padlist, saving and updating the various global vars at the same time as creating the pad itself. The following flags @@ -566,23 +790,25 @@ can be OR'ed together: padnew_SAVE save old globals padnew_SAVESUB also save extra stuff for start of sub - PADLIST* pad_new(padnew_flags flags) + PADLIST* pad_new(int flags) =for hackers Found in file pad.c =item pad_push +X Push a new pad frame onto the padlist, unless there's already a pad at -this depth, in which case don't bother creating a new one. -If has_args is true, give the new pad an @_ in slot zero. +this depth, in which case don't bother creating a new one. Then give +the new pad an @_ in slot zero. - void pad_push(PADLIST *padlist, int depth, int has_args) + void pad_push(PADLIST *padlist, int depth) =for hackers Found in file pad.c =item pad_reset +X Mark all the current temporaries for reuse @@ -592,6 +818,7 @@ Mark all the current temporaries for reuse Found in file pad.c =item pad_setsv +X Set the entry at offset po in the current pad to sv. Use the macro PAD_SETSV() rather than calling this function directly. @@ -602,6 +829,7 @@ Use the macro PAD_SETSV() rather than calling this function directly. Found in file pad.c =item pad_swipe +X Abandon the tmp in the current pad at offset po and replace with a new one. @@ -612,6 +840,7 @@ new one. Found in file pad.c =item pad_tidy +X Tidy up a pad after we've finished compiling it: * remove most stuff from the pads of anonsub prototypes; @@ -624,14 +853,18 @@ Tidy up a pad after we've finished compiling it: Found in file pad.c =item pad_undef +X Free the padlist associated with a CV. If parts of it happen to be current, we null the relevant PL_*pad* global vars so that we don't have any dangling references left. We also repoint the CvOUTSIDE of any about-to-be-orphaned -inner subs to outercv. +inner subs to the outer of this cv. - void pad_undef(CV* cv, CV* outercv) +(This function should really be called pad_free, but the name was already +taken) + + void pad_undef(CV* cv) =for hackers Found in file pad.c @@ -639,11 +872,98 @@ Found in file pad.c =back +=head1 Per-Interpreter Variables + +=over 8 + +=item PL_DBsingle +X + +When Perl is run in debugging mode, with the B<-d> switch, this SV is a +boolean which indicates whether subs are being single-stepped. +Single-stepping is automatically turned on after every step. This is the C +variable which corresponds to Perl's $DB::single variable. See +C. + + SV * PL_DBsingle + +=for hackers +Found in file intrpvar.h + +=item PL_DBsub +X + +When Perl is run in debugging mode, with the B<-d> switch, this GV contains +the SV which holds the name of the sub being debugged. This is the C +variable which corresponds to Perl's $DB::sub variable. See +C. + + GV * PL_DBsub + +=for hackers +Found in file intrpvar.h + +=item PL_DBtrace +X + +Trace variable used when Perl is run in debugging mode, with the B<-d> +switch. This is the C variable which corresponds to Perl's $DB::trace +variable. See C. + + SV * PL_DBtrace + +=for hackers +Found in file intrpvar.h + +=item PL_dowarn +X + +The C variable which corresponds to Perl's $^W warning variable. + + bool PL_dowarn + +=for hackers +Found in file intrpvar.h + +=item PL_last_in_gv +X + +The GV which was last used for a filehandle input operation. (C<< >>) + + GV* PL_last_in_gv + +=for hackers +Found in file intrpvar.h + +=item PL_ofs_sv +X + +The output field separator - C<$,> in Perl space. + + SV* PL_ofs_sv + +=for hackers +Found in file intrpvar.h + +=item PL_rs +X + +The input record separator - C<$/> in Perl space. + + SV* PL_rs + +=for hackers +Found in file intrpvar.h + + +=back + =head1 Stack Manipulation Macros =over 8 =item djSP +X Declare Just C. This is actually identical to C, and declares a local copy of perl's stack pointer, available via the C macro. @@ -656,6 +976,7 @@ old (Perl 5.005) thread model.) Found in file pp.h =item LVRET +X True if this op will be the return value of an lvalue subroutine @@ -669,16 +990,8 @@ Found in file pp.h =over 8 -=item report_uninit - -Print appropriate "Use of uninitialized variable" warning - - void report_uninit() - -=for hackers -Found in file sv.c - =item sv_add_arena +X Given a chunk of memory, link it to the head of the list of arenas, and split it into a list of free SVs. @@ -689,6 +1002,7 @@ and split it into a list of free SVs. Found in file sv.c =item sv_clean_all +X Decrement the refcnt of each remaining SV, possibly triggering a cleanup. This function may have to be called multiple times to free @@ -700,6 +1014,7 @@ SVs which are in complex self-referential hierarchies. Found in file sv.c =item sv_clean_objs +X Attempt to destroy all objects not yet freed @@ -709,6 +1024,7 @@ Attempt to destroy all objects not yet freed Found in file sv.c =item sv_free_arenas +X Deallocate the memory used by all arenas. Note that all the individual SV heads and bodies within the arenas must already have been freed. @@ -721,6 +1037,64 @@ Found in file sv.c =back +=head1 SV-Body Allocation + +=over 8 + +=item sv_2num +X + +Return an SV with the numeric value of the source SV, doing any necessary +reference or overload conversion. You must use the C macro to +access this function. + + SV* sv_2num(SV* sv) + +=for hackers +Found in file sv.c + + +=back + +=head1 Unicode Support + +=over 8 + +=item find_uninit_var +X + +Find the name of the undefined variable (if any) that caused the operator o +to issue a "Use of uninitialized value" warning. +If match is true, only return a name if it's value matches uninit_sv. +So roughly speaking, if a unary operator (such as OP_COS) generates a +warning, then following the direct child of the op may yield an +OP_PADSV or OP_GV that gives the name of the undefined variable. On the +other hand, with OP_ADD there are two branches to follow, so we only print +the variable name if we get an exact match. + +The name is returned as a mortal SV. + +Assumes that PL_op is the op that originally triggered the error, and that +PL_comppad/PL_curpad points to the currently executing pad. + + SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top) + +=for hackers +Found in file sv.c + +=item report_uninit +X + +Print appropriate "Use of uninitialized variable" warning + + void report_uninit(SV* uninit_sv) + +=for hackers +Found in file sv.c + + +=back + =head1 AUTHORS The autodocumentation system was originally added to the Perl core by @@ -731,3 +1105,6 @@ document their functions. perlguts(1), perlapi(1) +=cut + + ex: set ro: