This file is the autogenerated documentation of functions in the
Perl interpreter that are documented using Perl's internal documentation
-format but are not marked as part of the Perl API. In other words,
+format but are not marked as part of the Perl API. In other words,
B<they are not for use in extensions>!
END
=head1 AUTHORS
The autodocumentation system was originally added to the Perl core by
-Benjamin Stuhl. Documentation is by whoever was kind enough to
+Benjamin Stuhl. Documentation is by whoever was kind enough to
document their functions.
=head1 SEE ALSO
=head1 CV Manipulation Functions
This section documents functions to manipulate CVs which are code-values,
-or subroutines. For more information, see L<perlguts>.
+or subroutines.
For more information, see L<perlguts>.
=for apidoc Am|HV*|CvSTASH|CV* cv
Returns the stash of the CV. A stash is the symbol table hash, containing
=for apidoc m|bool|CvWEAKOUTSIDE|CV *cv
Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
-CV (if any). Because pointers to anonymous sub prototypes are
+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
+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
+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
+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
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
+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
+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
+the chain of lexical scopes is unbroken. For example, the following
should print 123:
my $x = 123;
=for apidoc 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>
+perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
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.
=for apidoc mn|GV*|PL_last_in_gv
-The GV which was last used for a filehandle input operation. (C<< <FH> >>)
+The GV which was last used for a filehandle input operation. (C<< <FH> >>)
=for apidoc mn|GV*|PL_ofsgv
"Magic" is special data attached to SV structures in order to give them
"magical" properties. When any Perl code tries to read from, or assign to,
an SV marked as magical, it calls the 'get' or 'set' function associated
-with that SV's magic. A get is called prior to reading an SV, in order to
+with that SV's magic. A get is called prior to reading an SV, in order to
give it a chance to update its internal value (get on $. writes the line
number of the last read filehandle into to the SV's IV slot), while
set is called after an SV has been written to, in order to allow it to make
PL_rs global variable).
Magic is implemented as a linked list of MAGIC structures attached to the
-SV. Each MAGIC struct holds the type of the magic, a pointer to an array
+SV. Each MAGIC struct holds the type of the magic, a pointer to an array
of functions that implement the get(), set(), length() etc functions,
-plus space for some flags and pointers. For example, a tied variable has
+plus space for some flags and pointers. For example, a tied variable has
a MAGIC structure that contains a pointer to the object associated with the
tie.
=for apidoc 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
+SV. Container magic (eg %ENV, $1, tie)
+gets copied, value magic doesn't (eg
taint, pos).
If setmagic is false then no set magic will be called on the new (empty) SV.
Call this function to signal to a stash that it has been assigned to
another spot in the stash hierarchy. C<stash> is the stash that has been
-assigned. C<oldstash> is the stash it replaces, if any. C<gv> is the glob
+assigned.
C<oldstash> is the stash it replaces, if any. C<gv> is the glob
that is actually being assigned to.
This can also be called with a null first argument to
XXX DAPM it would make more sense to make the arg a PADOFFSET
=for apidoc m|void|SAVECLEARSV |SV **svp
-Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
+Clear the pointed to pad value on scope exit. (i.e. the runtime action of
+'my')
=for apidoc m|void|SAVECOMPPAD
save PL_comppad and PL_curpad
=for apidoc m|void|PAD_SET_CUR |PADLIST padlist|I32 n
Set the current pad to be pad C<n> in the padlist, saving
-the previous current pad. NB currently this macro expands to a string too
+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();
/*
=for apidoc m|U32|PAD_COMPNAME_FLAGS|PADOFFSET po
Return the flags for the current compiling pad name
-at offset C<po>. Assumes a valid slot entry.
+at offset C<po>. Assumes a valid slot entry.
=for apidoc m|char *|PAD_COMPNAME_PV|PADOFFSET po
Return the name of the current compiling pad name
-at offset C<po>. Assumes a valid slot entry.
+at offset C<po>. Assumes a valid slot entry.
=for apidoc m|HV *|PAD_COMPNAME_TYPE|PADOFFSET po
Return the type (stash) of the current compiling pad name at offset
-C<po>. Must be a valid name. Returns null if not typed.
+C<po>. Must be a valid name. Returns null if not typed.
=for apidoc m|HV *|PAD_COMPNAME_OURSTASH|PADOFFSET po
Return the stash associated with an C<our> variable.
=for apidoc m|STRLEN|PAD_COMPNAME_GEN|PADOFFSET po
The generation number of the name at offset C<po> in the current
-compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
+compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
=for apidoc m|STRLEN|PAD_COMPNAME_GEN_set|PADOFFSET po|int gen
Sets the generation number of the name at offset C<po> in the current
=for apidoc ms||djSP
-Declare Just C<SP>. This is actually identical to C<dSP>, and declares
+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.
See C<SP>. (Available for backward source code compatibility with the
old (Perl 5.005) thread model.)
projects / platform / upstream / perl.git / commitdiff