Re: XS-assisted SWASHGET (esp. for t/uni/class.t speedup)
[p5sagit/p5-mst-13.2.git] / pod / perlintern.pod
index d256e7e..4e6119d 100644 (file)
@@ -4,6 +4,7 @@ perlintern - autogenerated documentation of purely B<internal>
                 Perl functions
 
 =head1 DESCRIPTION
+X<internal Perl functions> X<interpreter functions>
 
 This file is the autogenerated documentation of functions in the
 Perl interpreter that are documented using Perl's internal documentation
@@ -11,12 +12,75 @@ format but are not marked as part of the Perl API. In other words,
 B<they are not for use in extensions>!
 
 
+=head1 CV reference counts and CvOUTSIDE
+
+=over 8
+
+=item CvWEAKOUTSIDE
+X<CvWEAKOUTSIDE>
+
+Each CV has a pointer, C<CvOUTSIDE()>, 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<CvOUTSIDE> in the I<one specific instance> that the parent
+has a C<&> pad slot pointing back to us. In this case, we set the
+C<CvWEAKOUTSIDE> 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<CvWEAKOUTSIDE> 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<eval '$x'> causes the chain of C<CvOUTSIDE>s 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<CvOUTSIDE> 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<undef &foo>. In this case, its refcount may
+not have reached zero, but we still delete its pad and its C<CvROOT> etc.
+Since various children may still have their C<CvOUTSIDE> pointing at this
+undefined CV, we keep its own C<CvOUTSIDE> 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<CX_CURPAD_SAVE>
 
 Save the current pad in the given context block structure.
 
@@ -26,25 +90,28 @@ Save the current pad in the given context block structure.
 Found in file pad.h
 
 =item CX_CURPAD_SV
+X<CX_CURPAD_SV>
 
 Access the SV at offset po in the saved current pad in the given
 context block structure (can be used as an lvalue).
 
-       PAD *   CX_CURPAD_SV(struct context, PADOFFSET po)
+       SV *    CX_CURPAD_SV(struct context, PADOFFSET po)
 
 =for hackers
 Found in file pad.h
 
-=item PAD_BASE_SV      
+=item PAD_BASE_SV
+X<PAD_BASE_SV>
 
 Get the value from slot C<po> 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<PAD_CLONE_VARS>
 
 |CLONE_PARAMS* param
 Clone the state variables associated with running and compiling pads.
@@ -55,6 +122,7 @@ Clone the state variables associated with running and compiling pads.
 Found in file pad.h
 
 =item PAD_COMPNAME_FLAGS
+X<PAD_COMPNAME_FLAGS>
 
 Return the flags for the current compiling pad name
 at offset C<po>. Assumes a valid slot entry.
@@ -65,6 +133,7 @@ at offset C<po>. Assumes a valid slot entry.
 Found in file pad.h
 
 =item PAD_COMPNAME_GEN
+X<PAD_COMPNAME_GEN>
 
 The generation number of the name at offset C<po> in the current
 compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
@@ -74,7 +143,19 @@ compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
 =for hackers
 Found in file pad.h
 
+=item PAD_COMPNAME_GEN_set
+X<PAD_COMPNAME_GEN_set>
+
+Sets the generation number of the name at offset C<po> in the current
+ling pad (lvalue) to C<gen>.  Note that C<SvCUR_set> 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<PAD_COMPNAME_OURSTASH>
 
 Return the stash associated with an C<our> variable.
 Assumes the slot entry is a valid C<our> lexical.
@@ -85,6 +166,7 @@ Assumes the slot entry is a valid C<our> lexical.
 Found in file pad.h
 
 =item PAD_COMPNAME_PV
+X<PAD_COMPNAME_PV>
 
 Return the name of the current compiling pad name
 at offset C<po>. Assumes a valid slot entry.
@@ -95,6 +177,7 @@ at offset C<po>. Assumes a valid slot entry.
 Found in file pad.h
 
 =item PAD_COMPNAME_TYPE
+X<PAD_COMPNAME_TYPE>
 
 Return the type (stash) of the current compiling pad name at offset
 C<po>. Must be a valid name. Returns null if not typed.
@@ -105,6 +188,7 @@ C<po>. Must be a valid name. Returns null if not typed.
 Found in file pad.h
 
 =item PAD_DUP
+X<PAD_DUP>
 
 Clone a padlist.
 
@@ -113,7 +197,29 @@ Clone a padlist.
 =for hackers
 Found in file pad.h
 
+=item PAD_RESTORE_LOCAL
+X<PAD_RESTORE_LOCAL>
+
+Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
+
+       void    PAD_RESTORE_LOCAL(PAD *opad)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SAVE_LOCAL
+X<PAD_SAVE_LOCAL>
+
+Save the current pad to the local variable opad, then make the
+current pad equal to npad
+
+       void    PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
+
+=for hackers
+Found in file pad.h
+
 =item PAD_SAVE_SETNULLPAD
+X<PAD_SAVE_SETNULLPAD>
 
 Save the current pad then set it to null.
 
@@ -122,93 +228,121 @@ Save the current pad then set it to null.
 =for hackers
 Found in file pad.h
 
-=item PAD_SETSV        
+=item PAD_SETSV
+X<PAD_SETSV>
 
 Set the slot at offset C<po> in the current pad to C<sv>
 
-       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<PAD_SET_CUR>
 
 Set the current pad to be pad C<n> 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<PAD_SET_CUR_NOSAVE>
+
+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<PAD_SV>
 
 Get the value at offset C<po> 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<PAD_SVl>
 
 Lightweight and lvalue version of C<PAD_SV>.
 Get or set the value at offset C<po> in the current pad.
 Unlike C<PAD_SV>, 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 PAD_UPDATE_CURPAD
+=item SAVECLEARSV
+X<SAVECLEARSV>
 
-Set PL_curpad from the value of PL_comppad.
+Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
 
-       void    PAD_UPDATE_CURPAD()
+       void    SAVECLEARSV(SV **svp)
 
 =for hackers
 Found in file pad.h
 
-=item SAVECLEARSV      
+=item SAVECOMPPAD
+X<SAVECOMPPAD>
 
-Clear the pointed to pad value on scope exit. (ie the runtime action of 'my')
+save PL_comppad and PL_curpad
 
-       void    SAVECLEARSV     (SV **svp)
 
-=for hackers
-Found in file pad.h
 
-=item SAVECOMPPAD
 
-save PL_comppad and PL_curpad
 
        void    SAVECOMPPAD()
 
 =for hackers
 Found in file pad.h
 
-=item SAVEFREEOP       
+=item SAVEPADSV
+X<SAVEPADSV>
+
+Save a pad slot (used to restore after an iteration)
 
-Free the op on scope exit. At the same time, reset PL_curpad
+XXX DAPM it would make more sense to make the arg a PADOFFSET
+       void    SAVEPADSV(PADOFFSET po)
 
+=for hackers
+Found in file pad.h
 
 
+=back
 
-       void    SAVEFREEOP      (OP *o)
+=head1 Functions in file pp_ctl.c
 
-=for hackers
-Found in file pad.h
 
-=item SAVEPADSV        
+=over 8
 
-Save a pad slot (used to restore after an iteration)
+=item find_runcv
+X<find_runcv>
+
+Locate the CV corresponding to the currently executing sub or eval.
+If db_seqp is non_null, skip CVs that are in the DB package and populate
+*db_seqp with the cop sequence number at the point that the DB:: code was
+entered. (allows debuggers to eval in the scope of the breakpoint rather
+than in the scope of the debugger itself).
 
-       void    SAVEPADSV       (PADOFFSET po)
+       CV*     find_runcv(U32 *db_seqp)
 
 =for hackers
-Found in file pad.h
+Found in file pp_ctl.c
 
 
 =back
@@ -218,6 +352,7 @@ Found in file pad.h
 =over 8
 
 =item PL_DBsingle
+X<PL_DBsingle>
 
 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.
@@ -231,6 +366,7 @@ C<PL_DBsub>.
 Found in file intrpvar.h
 
 =item PL_DBsub
+X<PL_DBsub>
 
 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
@@ -243,6 +379,7 @@ C<PL_DBsingle>.
 Found in file intrpvar.h
 
 =item PL_DBtrace
+X<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
@@ -254,6 +391,7 @@ variable.  See C<PL_DBsingle>.
 Found in file intrpvar.h
 
 =item PL_dowarn
+X<PL_dowarn>
 
 The C variable which corresponds to Perl's $^W warning variable.
 
@@ -263,6 +401,7 @@ The C variable which corresponds to Perl's $^W warning variable.
 Found in file intrpvar.h
 
 =item PL_last_in_gv
+X<PL_last_in_gv>
 
 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
 
@@ -272,6 +411,7 @@ The GV which was last used for a filehandle input operation. (C<< <FH> >>)
 Found in file thrdvar.h
 
 =item PL_ofs_sv
+X<PL_ofs_sv>
 
 The output field separator - C<$,> in Perl space.
 
@@ -281,6 +421,7 @@ The output field separator - C<$,> in Perl space.
 Found in file thrdvar.h
 
 =item PL_rs
+X<PL_rs>
 
 The input record separator - C<$/> in Perl space.
 
@@ -297,6 +438,7 @@ Found in file thrdvar.h
 =over 8
 
 =item is_gv_magical
+X<is_gv_magical>
 
 Returns C<TRUE> if given the name of a magical GV.
 
@@ -306,7 +448,21 @@ created even in rvalue contexts.
 C<flags> is not used at present but available for future extension to
 allow selecting particular classes of magical variable.
 
-       bool    is_gv_magical(char *name, STRLEN len, U32 flags)
+Currently assumes that C<name> 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 gv.c
+
+=item is_gv_magical_sv
+X<is_gv_magical_sv>
+
+Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical.
+
+       bool    is_gv_magical_sv(SV *name, U32 flags)
 
 =for hackers
 Found in file gv.c
@@ -319,6 +475,7 @@ Found in file gv.c
 =over 8
 
 =item start_glob
+X<start_glob>
 
 Function called by C<do_readline> to spawn a glob (or do the glob inside
 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
@@ -333,24 +490,45 @@ Found in file doio.c
 
 =back
 
+=head1 Magical Functions
+
+=over 8
+
+=item mg_localize
+X<mg_localize>
+
+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 mg.c
+
+
+=back
+
 =head1 Pad Data Structures
 
 =over 8
 
 =item CvPADLIST
+X<CvPADLIST>
 
 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
 every entersub).
 
 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
-is managed "manual" (mostly in op.c) rather than normal av.c rules.
+is managed "manual" (mostly in pad.c) rather than normal av.c rules.
 The items in the AV are not SVs as for a normal AV, but other AVs:
 
 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
@@ -362,11 +540,14 @@ 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<PL_comppad_name> is set the the the names AV.
-C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
-C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
+C<PL_comppad_name> is set to the names AV.
+C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
+C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
+
+During execution, C<PL_comppad> and C<PL_curpad> refer to the live
+frame of the currently executing sub.
 
-Itterating over the names AV itterates over all possible pad
+Iterating over the names AV iterates over all possible pad
 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
 &PL_sv_undef "names" (see pad_alloc()).
 
@@ -382,27 +563,43 @@ 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<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
-stash of the associated global (so that duplicate C<our> delarations in the
+stash of the associated global (so that duplicate C<our> declarations 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 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 NVX and IVX to store a cop_seq range, since it is
+in scope throughout. Instead IVX 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, NVX contains the index
+within the parent's pad where the lexical's value is stored, to make
+cloning quicker.
 
-If the 'name' is '&' the the corresponding entry in frame AV
+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<my sub foo {}> 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<cv_clone>
 
 Clone a CV: make a new CV which points to the same code etc, but which
-has a newly-created pad done by copying the prototype pad and capturing
+has a newly-created pad built by copying the prototype pad and capturing
 any outer lexicals.
 
        CV*     cv_clone(CV* proto)
@@ -411,15 +608,17 @@ any outer lexicals.
 Found in file pad.c
 
 =item cv_dump
+X<cv_dump>
 
 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<do_dump_pad>
 
 Dump the contents of a padlist
 
@@ -429,6 +628,7 @@ Dump the contents of a padlist
 Found in file pad.c
 
 =item intro_my
+X<intro_my>
 
 "Introduce" my variables to visible status.
 
@@ -438,6 +638,7 @@ Found in file pad.c
 Found in file pad.c
 
 =item pad_add_anon
+X<pad_add_anon>
 
 Add an anon code entry to the current compiling pad
 
@@ -447,27 +648,28 @@ Add an anon code entry to the current compiling pad
 Found in file pad.c
 
 =item pad_add_name
+X<pad_add_name>
 
-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<typestash> is valid, the name is for a typed lexical; set the
 name's stash to that value.
 If C<ourstash> 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
-
 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)
 
 =for hackers
 Found in file pad.c
 
 =item pad_alloc
+X<pad_alloc>
 
 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)
 
@@ -475,6 +677,7 @@ for a slot which has no name and and no active value.
 Found in file pad.c
 
 =item pad_block_start
+X<pad_block_start>
 
 Update the pad compilation state variables on entry to a new block
 
@@ -484,6 +687,7 @@ Update the pad compilation state variables on entry to a new block
 Found in file pad.c
 
 =item pad_check_dup
+X<pad_check_dup>
 
 Check for duplicate declarations: report any of:
      * a my in the current scope with the same name;
@@ -491,40 +695,56 @@ Check for duplicate declarations: report any of:
        as C<ourstash>
 C<is_our> 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<pad_findlex>
 
 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.
 
-If flags == FINDLEX_NOSEARCH we don't bother searching outer contexts.
+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.
 
-       PADOFFSET       pad_findlex(char* name, PADOFFSET newoff, U32 seq, CV* startcv, I32 cx_ix, I32 saweval, U32 flags)
+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 NVX the index into
+the parent pad.
+
+       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<pad_findmy>
 
-Given a lexical name, try to find it's offset, first in the current pad,
+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
-the complications introduced by eval). If the name is found in an outer pad, then a fake entry is added to the current pad.
+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<pad_fixup_inner_anons>
 
 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)
 
@@ -532,8 +752,9 @@ old_cv to new_cv if necessary.
 Found in file pad.c
 
 =item pad_free
+X<pad_free>
 
-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)
 
@@ -541,6 +762,7 @@ Free the SV at offet po in the current pad.
 Found in file pad.c
 
 =item pad_leavemy
+X<pad_leavemy>
 
 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.
@@ -551,8 +773,9 @@ lexicals in this scope and warn of any lexicals that never got introduced.
 Found in file pad.c
 
 =item pad_new
+X<pad_new>
 
-Create a new comnpiling padlist, saving and updating the various global
+Create a new compiling padlist, saving and updating the various global
 vars at the same time as creating the pad itself. The following flags
 can be OR'ed together:
 
@@ -560,23 +783,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<pad_push>
 
 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<pad_reset>
 
 Mark all the current temporaries for reuse
 
@@ -586,6 +811,7 @@ Mark all the current temporaries for reuse
 Found in file pad.c
 
 =item pad_setsv
+X<pad_setsv>
 
 Set the entry at offset po in the current pad to sv.
 Use the macro PAD_SETSV() rather than calling this function directly.
@@ -596,6 +822,7 @@ Use the macro PAD_SETSV() rather than calling this function directly.
 Found in file pad.c
 
 =item pad_swipe
+X<pad_swipe>
 
 Abandon the tmp in the current pad at offset po and replace with a
 new one.
@@ -606,6 +833,7 @@ new one.
 Found in file pad.c
 
 =item pad_tidy
+X<pad_tidy>
 
 Tidy up a pad after we've finished compiling it:
     * remove most stuff from the pads of anonsub prototypes;
@@ -618,14 +846,18 @@ Tidy up a pad after we've finished compiling it:
 Found in file pad.c
 
 =item pad_undef
+X<pad_undef>
 
 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.
+
+(This function should really be called pad_free, but the name was already
+taken)
 
-       void    pad_undef(CV* cv, CV* outercv)
+       void    pad_undef(CV* cv)
 
 =for hackers
 Found in file pad.c
@@ -638,6 +870,7 @@ Found in file pad.c
 =over 8
 
 =item djSP
+X<djSP>
 
 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
 a local copy of perl's stack pointer, available via the C<SP> macro.
@@ -650,6 +883,7 @@ old (Perl 5.005) thread model.)
 Found in file pp.h
 
 =item LVRET
+X<LVRET>
 
 True if this op will be the return value of an lvalue subroutine
 
@@ -663,16 +897,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<sv_add_arena>
 
 Given a chunk of memory, link it to the head of the list of arenas,
 and split it into a list of free SVs.
@@ -683,6 +909,7 @@ and split it into a list of free SVs.
 Found in file sv.c
 
 =item sv_clean_all
+X<sv_clean_all>
 
 Decrement the refcnt of each remaining SV, possibly triggering a
 cleanup. This function may have to be called multiple times to free
@@ -694,6 +921,7 @@ SVs which are in complex self-referential hierarchies.
 Found in file sv.c
 
 =item sv_clean_objs
+X<sv_clean_objs>
 
 Attempt to destroy all objects not yet freed
 
@@ -703,6 +931,7 @@ Attempt to destroy all objects not yet freed
 Found in file sv.c
 
 =item sv_free_arenas
+X<sv_free_arenas>
 
 Deallocate the memory used by all arenas. Note that all the individual SV
 heads and bodies within the arenas must already have been freed.
@@ -715,6 +944,45 @@ Found in file sv.c
 
 =back
 
+=head1 Unicode Support
+
+=over 8
+
+=item find_uninit_var
+X<find_uninit_var>
+
+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<report_uninit>
+
+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