In the C<SvPV> macro, the length of the string returned is placed into the
variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
-care what the length of the data is, use the global variable C<na>. Remember,
+care what the length of the data is, use the global variable C<PL_na>. Remember,
however, that Perl allows arbitrary strings of data that may both contain
NULs and might not be terminated by a NUL.
SvOK(SV*)
-The scalar C<undef> value is stored in an SV instance called C<sv_undef>. Its
+The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>. Its
address can be used whenever an C<SV*> is needed.
-There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
-TRUE and FALSE values, respectively. Like C<sv_undef>, their addresses can
+There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
+TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their addresses can
be used whenever an C<SV*> is needed.
-Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
+Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
Take this code:
SV* sv = (SV*) 0;
This code tries to return a new SV (which contains the value 42) if it should
return a real value, or undef otherwise. Instead it has returned a NULL
pointer which, somewhere down the line, will cause a segmentation violation,
-bus error, or just weird results. Change the zero to C<&sv_undef> in the first
+bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the first
line and all will be well.
To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
Format
Subroutine
-There is a single stash called "defstash" that holds the items that exist
+There is a single stash called "PL_defstash" that holds the items that exist
in the "main" package. To get at the items in other packages, append the
string "::" to the package name. The items in the "Foo" package are in
-the stash "Foo::" in defstash. The items in the "Bar::Baz" package are
+the stash "Foo::" in PL_defstash. The items in the "Bar::Baz" package are
in the stash "Baz::" in "Bar::"'s stash.
To get the stash pointer for a particular package, use the function:
short-lived storage, the corresponding string may be reallocated like
this:
- SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf));
+ SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
=item C<SAVEDESTRUCTOR(f,p)>
This is a listing of functions, macros, flags, and variables that may be
useful to extension writers or that may be found while reading other
extensions.
+
+Note that all Perl API global variables must be referenced with the C<PL_>
+prefix. Some macros are provided for compatibility with the older,
+unadorned names, but this support will be removed in a future release.
+
+It is strongly recommended that all Perl API functions that don't begin
+with C<perl> be referenced with an explicit C<Perl_> prefix.
+
The sort order of the listing is case insensitive, with any
occurrences of '_' ignored for the the purpose of sorting.
=item av_pop
-Pops an SV off the end of the array. Returns C<&sv_undef> if the array is
+Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is
empty.
SV* av_pop (AV* ar)
HV* CvSTASH( SV* sv )
-=item DBsingle
+=item 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.
Single-stepping is automatically turned on after every step. This is the C
-variable which corresponds to Perl's $DB::single variable. See C<DBsub>.
+variable which corresponds to Perl's $DB::single variable. See C<PL_DBsub>.
-=item DBsub
+=item 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
-variable which corresponds to Perl's $DB::sub variable. See C<DBsingle>.
+variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>.
The sub name can be found by
- SvPV( GvSV( DBsub ), na )
+ SvPV( GvSV( PL_DBsub ), PL_na )
-=item DBtrace
+=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<DBsingle>.
+variable. See C<PL_DBsingle>.
=item dMARK
Saves the original stack mark for the XSUB. See C<ORIGMARK>.
-=item dowarn
+=item PL_dowarn
The C variable which corresponds to Perl's $^W warning variable.
Returns the glob with the given C<name> and a defined subroutine or
C<NULL>. The glob lives in the given C<stash>, or in the stashes
-accessable via @ISA and @UNIVERSAL.
+accessible via @ISA and @UNIVERSAL.
The argument C<level> should be either 0 or -1. If C<level==0>, as a
side-effect creates a glob with the given C<name> in the given
necessary dereferencing of possibly C<SV*> keys. The length of
the string is placed in C<len> (this is a macro, so do I<not> use
C<&len>). If you do not care about what the length of the key is,
-you may use the global variable C<na>. Remember though, that hash
+you may use the global variable C<PL_na>. Remember though, that hash
keys in perl are free to contain embedded nulls, so using C<strlen()>
or similar is not a good way to find the length of hash keys.
This is very similar to the C<SvPV()> macro described elsewhere in
void Move( s, d, n, t )
-=item na
+=item PL_na
A variable which may be used with C<SvPV> to tell Perl to calculate the
string length.
int SvNIOKp (SV* SV)
-=item sv_no
+=item PL_sv_no
-This is the C<false> SV. See C<sv_yes>. Always refer to this as C<&sv_no>.
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as C<&PL_sv_no>.
=item SvNOK
characters from the beginning of a SvPV. When SvOOK is true, then the
start of the allocated string buffer is really (SvPVX - SvIVX).
- int SvOOK(Sv* sv)
+ int SvOOK(SV* sv)
=item SvPOK
=item SvPV
Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string. If C<len> is C<na> then Perl will
+if the SV does not contain a string. If C<len> is C<PL_na> then Perl will
handle the length on its own. Handles 'get' magic.
char* SvPV (SV* sv, int len )
Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
+the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
into the SV. The C<classname> argument indicates the package for the
blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
will be returned and will have a reference count of 1.
An enum of flags for Perl types. These are found in the file B<sv.h> in the
C<svtype> enum. Test these flags with the C<SvTYPE> macro.
-=item sv_undef
+=item PL_sv_undef
-This is the C<undef> SV. Always refer to this as C<&sv_undef>.
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
=item sv_unref
UV SvUVX(SV* sv)
-=item sv_yes
+=item PL_sv_yes
-This is the C<true> SV. See C<sv_no>. Always refer to this as C<&sv_yes>.
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as C<&PL_sv_yes>.
=item THIS
=item XSRETURN_NO
-Return C<&sv_no> from an XSUB immediately. Uses C<XST_mNO>.
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
XSRETURN_NO;
=item XSRETURN_UNDEF
-Return C<&sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
XSRETURN_UNDEF;
=item XSRETURN_YES
-Return C<&sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
XSRETURN_YES;
=item XST_mNO
-Place C<&sv_no> into the specified position C<i> on the stack.
+Place C<&PL_sv_no> into the specified position C<i> on the stack.
XST_mNO( int i )
=item XST_mUNDEF
-Place C<&sv_undef> into the specified position C<i> on the stack.
+Place C<&PL_sv_undef> into the specified position C<i> on the stack.
XST_mUNDEF( int i )
=item XST_mYES
-Place C<&sv_yes> into the specified position C<i> on the stack.
+Place C<&PL_sv_yes> into the specified position C<i> on the stack.
XST_mYES( int i )
projects / p5sagit/p5-mst-13.2.git / blobdiff