=for hackers
Found in file av.c
+=item av_create_and_push
+X<av_create_and_push>
+
+Push an SV onto the end of the array, creating the array if necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ void av_create_and_push(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
+=item av_create_and_unshift_one
+X<av_create_and_unshift_one>
+
+Unshifts an SV onto the beginning of the array, creating the array if
+necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ SV** av_create_and_unshift_one(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
=item av_delete
X<av_delete>
with it we copy the stacks and the new perl interpreter is
ready to run at the exact same point as the previous one.
The pseudo-fork code uses COPY_STACKS while the
-threads->new doesn't.
+threads->create doesn't.
CLONEf_KEEP_PTR_TABLE
perl_clone keeps a ptr_table with the pointer of the old
=item get_cv
X<get_cv>
-Returns the CV of the specified Perl subroutine. If C<create> is set and
-the Perl subroutine does not exist then it will be declared (which has the
-same effect as saying C<sub name;>). If C<create> is not set and the
-subroutine does not exist then NULL is returned.
+Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
NOTE: the perl_ form of this function is deprecated.
- CV* get_cv(const char* name, I32 create)
+ CV* get_cv(const char* name, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item get_cvn_flags
+X<get_cvn_flags>
+
+Returns the CV of the specified Perl subroutine. C<flags> are passed to
+C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
+exist then it will be declared (which has the same effect as saying
+C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
+then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
=for hackers
Found in file perl.c
Normally the SV will be cleared before the escaped string is prepared,
but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
-If PERL_PV_ESCAPE_UNI is set then the input string is treated as unicode,
+If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
-using C<is_utf8_string()> to determine if it is unicode.
+using C<is_utf8_string()> to determine if it is Unicode.
If PERL_PV_ESCAPE_ALL is set then all input chars will be output
using C<\x01F1> style escapes, otherwise only chars above 255 will be
|const U32 flags
Converts a string into something presentable, handling escaping via
-pv_escape() and supporting quoting and elipses.
+pv_escape() and supporting quoting and ellipses.
If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
double quoted with any double quotes in the string escaped. Otherwise
if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
angle brackets.
-If the PERL_PV_PRETTY_ELIPSES flag is set and not all characters in
-string were output then an elipses C<...> will be appended to the
+If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
+string were output then an ellipsis C<...> will be appended to the
string. Note that this happens AFTER it has been quoted.
If start_color is non-null then it will be inserted after the opening
quote (if there is one) but before the escaped text. If end_color
is non-null then it will be inserted after the escaped text but before
-any quotes or elipses.
+any quotes or ellipses.
Returns a pointer to the prettified text as held by dsv.
=back
+=head1 Functions in file pp_ctl.c
+
+
+=over 8
+
+=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).
+
+ CV* find_runcv(U32 *db_seqp)
+
+=for hackers
+Found in file pp_ctl.c
+
+
+=back
+
=head1 Functions in file pp_pack.c
=back
-=head1 Global Variables
-
-=over 8
-
-=item PL_modglobal
-X<PL_modglobal>
-
-C<PL_modglobal> is a general purpose, interpreter global HV for use by
-extensions that need to keep information on a per-interpreter basis.
-In a pinch, it can also be used as a symbol table for extensions
-to share data among each other. It is a good idea to use keys
-prefixed by the package name of the extension that owns the data.
-
- HV* PL_modglobal
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_na
-X<PL_na>
-
-A convenience variable which is typically used with C<SvPV> when one
-doesn't care about the length of the string. It is usually more efficient
-to either declare a local variable and use that instead or to use the
-C<SvPV_nolen> macro.
-
- STRLEN PL_na
-
-=for hackers
-Found in file thrdvar.h
-
-=item PL_sv_no
-X<PL_sv_no>
-
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
-
- SV PL_sv_no
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_undef
-X<PL_sv_undef>
-
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
-
- SV PL_sv_undef
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_yes
-X<PL_sv_yes>
-
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
-
- SV PL_sv_yes
-
-=for hackers
-Found in file intrpvar.h
-
-
-=back
-
=head1 GV Functions
=over 8
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 C<stash>
which in the case of success contains an alias for the subroutine, and sets
-up caching info for this glob. Similarly for all the searched stashes.
+up caching info for this glob.
This function grants C<"SUPER"> token as a postfix of the stash name. The
GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
=item gv_stashpv
X<gv_stashpv>
-Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string and must be null-terminated. If C<create> is set
-then the package will be created if it does not already exist. If C<create>
-is not set and the package does not exist then NULL is returned.
+Returns a pointer to the stash for a specified package. Uses C<strlen> to
+determine the length of C<name>, then calls C<gv_stashpvn()>.
- HV* gv_stashpv(const char* name, I32 create)
+ HV* gv_stashpv(const char* name, I32 flags)
=for hackers
Found in file gv.c
=item gv_stashpvn
X<gv_stashpvn>
-Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string. The C<namelen> parameter indicates the length of
-the C<name>, in bytes. If C<create> is set then the package will be
-created if it does not already exist. If C<create> is not set and the
-package does not exist then NULL is returned.
+Returns a pointer to the stash for a specified package. The C<namelen>
+parameter indicates the length of the C<name>, in bytes. C<flags> is passed
+to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
+created if it does not already exist. If the package does not exist and
+C<flags> is 0 (or any other setting that does not create packages) then NULL
+is returned.
- HV* gv_stashpvn(const char* name, U32 namelen, I32 create)
+
+ HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
=for hackers
Found in file gv.c
=item gv_stashsv
X<gv_stashsv>
-Returns a pointer to the stash for a specified package, which must be a
-valid UTF-8 string. See C<gv_stashpv>.
+Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
- HV* gv_stashsv(SV* sv, I32 create)
+ HV* gv_stashsv(SV* sv, I32 flags)
=for hackers
Found in file gv.c
=for hackers
Found in file util.c
+=item savesharedpvn
+X<savesharedpvn>
+
+A version of C<savepvn()> which allocates the duplicate string in memory
+which is shared between threads. (With the specific difference that a NULL
+pointer is not acceptable)
+
+ char* savesharedpvn(const char *const pv, const STRLEN len)
+
+=for hackers
+Found in file util.c
+
=item savesvpv
X<savesvpv>
Function must be called with an already existing SV like
sv = newSV(0);
- s = scan_version(s,SV *sv, bool qv);
+ s = scan_version(s, SV *sv, bool qv);
Performs some preprocessing to the string to ensure that
it has the correct characteristics of a version. Flags the
object if it contains an underscore (which denotes this
-is a alpha version). The boolean qv denotes that the version
+is an alpha version). The boolean qv denotes that the version
should be interpreted as if it had multiple decimals, even if
it doesn't.
=for hackers
Found in file handy.h
+=item sv_destroyable
+X<sv_destroyable>
+
+Dummy routine which reports that object can be destroyed when there is no
+sharing module present. It ignores its single SV argument, and returns
+'true'. Exists to avoid test for a NULL function pointer and because it
+could potentially warn under some level of strict-ness.
+
+ bool sv_destroyable(SV *sv)
+
+=for hackers
+Found in file util.c
+
=item sv_nosharing
X<sv_nosharing>
In-place upgrade of the supplied SV to a version object.
- SV *sv = upg_version(SV *sv);
+ SV *sv = upg_version(SV *sv, bool qv);
-Returns a pointer to the upgraded SV.
+Returns a pointer to the upgraded SV. Set the boolean qv if you want
+to force this SV to be interpreted as an "extended" version.
- SV* upg_version(SV *ver)
+ SV* upg_version(SV *ver, bool qv)
=for hackers
Found in file util.c
=back
+=head1 MRO Functions
+
+=over 8
+
+=item mro_get_linear_isa
+X<mro_get_linear_isa>
+
+Returns either C<mro_get_linear_isa_c3> or
+C<mro_get_linear_isa_dfs> for the given stash,
+dependant upon which MRO is in effect
+for that stash. The return value is a
+read-only AV*.
+
+You are responsible for C<SvREFCNT_inc()> 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(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+=item mro_method_changed_in
+X<mro_method_changed_in>
+
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
+
+Ideally, all instances of C<PL_sub_generation++> in
+perl source outside of C<mro.c> should be
+replaced by calls to this.
+
+Perl automatically handles most of the common
+ways a method might be redefined. However, there
+are a few ways you could change a method in a stash
+without the cache code noticing, in which case you
+need to call this method afterwards:
+
+1) Directly manipulating the stash HV entries from
+XS code.
+
+2) Assigning a reference to a readonly scalar
+constant into a stash entry in order to create
+a constant subroutine (like constant.pm
+does).
+
+This same method is available from pure perl
+via, C<mro::method_changed_in(classname)>.
+
+ void mro_method_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
=head1 Multicall Functions
=over 8
=for hackers
Found in file numeric.c
+=item Perl_signbit
+X<Perl_signbit>
+
+Return a non-zero integer if the sign bit on an NV is set, and 0 if
+it is not.
+
+If Configure detects this system has a signbit() that will work with
+our NVs, then we just use it via the #define in perl.h. Otherwise,
+fall back on this implementation. As a first pass, this gets everything
+right except -0.0. Alas, catching -0.0 is the main use for this function,
+so this is not too helpful yet. Still, at least we have the scaffolding
+in place to support other systems, should that prove useful.
+
+
+Configure notes: This function is called 'Perl_signbit' instead of a
+plain 'signbit' because it is easy to imagine a system having a signbit()
+function or macro that doesn't happen to work with our particular choice
+of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
+the standard system headers to be happy. Also, this is a no-context
+function (no pTHX_) because Perl_signbit() is usually re-#defined in
+perl.h as a simple macro call to the system's signbit().
+Users should just always call Perl_signbit().
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ int Perl_signbit(NV f)
+
+=for hackers
+Found in file numeric.c
+
=item scan_bin
X<scan_bin>
=back
+=head1 Per-Interpreter Variables
+
+=over 8
+
+=item PL_modglobal
+X<PL_modglobal>
+
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
+ HV* PL_modglobal
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_na
+X<PL_na>
+
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_no
+X<PL_sv_no>
+
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_undef
+X<PL_sv_undef>
+
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_yes
+X<PL_sv_yes>
+
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
+
+=for hackers
+Found in file intrpvar.h
+
+
+=back
+
+=head1 REGEXP Functions
+
+=over 8
+
+=item SvRX
+X<SvRX>
+
+Convenience macro to get the REGEXP from a SV. This is approximately
+equivalent to the following snippet:
+
+ if (SvMAGICAL(sv))
+ mg_get(sv);
+ if (SvROK(sv) &&
+ (tmpsv = (SV*)SvRV(sv)) &&
+ SvTYPE(tmpsv) == SVt_PVMG &&
+ (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
+ {
+ return (REGEXP *)tmpmg->mg_obj;
+ }
+
+NULL will be returned if a REGEXP* is not found.
+
+ REGEXP * SvRX(SV *sv)
+
+=for hackers
+Found in file regexp.h
+
+=item SvRXOK
+X<SvRXOK>
+
+Returns a boolean indicating whether the SV contains qr magic
+(PERL_MAGIC_qr).
+
+If you want to do something with the REGEXP* later use SvRX instead
+and check for NULL.
+
+ bool SvRXOK(SV* sv)
+
+=for hackers
+Found in file regexp.h
+
+
+=back
+
=head1 Simple Exception Handling Macros
=over 8
=item SvIOK
X<SvIOK>
-Returns a boolean indicating whether the SV contains an integer.
+Returns a U32 value indicating whether the SV contains an integer.
- bool SvIOK(SV* sv)
+ U32 SvIOK(SV* sv)
=for hackers
Found in file sv.h
=item SvIOKp
X<SvIOKp>
-Returns a boolean indicating whether the SV contains an integer. Checks
+Returns a U32 value indicating whether the SV contains an integer. Checks
the B<private> setting. Use C<SvIOK>.
- bool SvIOKp(SV* sv)
+ U32 SvIOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvIV
X<SvIV>
-Coerces the given SV to an integer and returns it. See C<SvIVx> for a
+Coerces the given SV to an integer and returns it. See C<SvIVx> for a
version which guarantees to evaluate sv only once.
IV SvIV(SV* sv)
X<SvIVx>
Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvIV> otherwise.
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvIV>.
IV SvIVx(SV* sv)
=item SvNIOK
X<SvNIOK>
-Returns a boolean indicating whether the SV contains a number, integer or
+Returns a U32 value indicating whether the SV contains a number, integer or
double.
- bool SvNIOK(SV* sv)
+ U32 SvNIOK(SV* sv)
=for hackers
Found in file sv.h
=item SvNIOKp
X<SvNIOKp>
-Returns a boolean indicating whether the SV contains a number, integer or
+Returns a U32 value indicating whether the SV contains a number, integer or
double. Checks the B<private> setting. Use C<SvNIOK>.
- bool SvNIOKp(SV* sv)
+ U32 SvNIOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvNOK
X<SvNOK>
-Returns a boolean indicating whether the SV contains a double.
+Returns a U32 value indicating whether the SV contains a double.
- bool SvNOK(SV* sv)
+ U32 SvNOK(SV* sv)
=for hackers
Found in file sv.h
=item SvNOKp
X<SvNOKp>
-Returns a boolean indicating whether the SV contains a double. Checks the
+Returns a U32 value indicating whether the SV contains a double. Checks the
B<private> setting. Use C<SvNOK>.
- bool SvNOKp(SV* sv)
+ U32 SvNOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvNV
X<SvNV>
-Coerce the given SV to a double and return it. See C<SvNVx> for a version
+Coerce the given SV to a double and return it. See C<SvNVx> for a version
which guarantees to evaluate sv only once.
NV SvNV(SV* sv)
X<SvNVx>
Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvNV> otherwise.
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvNV>.
NV SvNVx(SV* sv)
=item SvOK
X<SvOK>
-Returns a boolean indicating whether the value is an SV. It also tells
+Returns a U32 value indicating whether the value is an SV. It also tells
whether the value is defined or not.
- bool SvOK(SV* sv)
+ U32 SvOK(SV* sv)
=for hackers
Found in file sv.h
=item SvOOK
X<SvOOK>
-Returns a boolean indicating whether the SvIVX is a valid offset value for
+Returns a U32 indicating whether the SvIVX is a valid offset value for
the SvPVX. This hack is used internally to speed up removal of characters
from the beginning of a SvPV. When SvOOK is true, then the start of the
allocated string buffer is really (SvPVX - SvIVX).
- bool SvOOK(SV* sv)
+ U32 SvOOK(SV* sv)
=for hackers
Found in file sv.h
=item SvPOK
X<SvPOK>
-Returns a boolean indicating whether the SV contains a character
+Returns a U32 value indicating whether the SV contains a character
string.
- bool SvPOK(SV* sv)
+ U32 SvPOK(SV* sv)
=for hackers
Found in file sv.h
=item SvPOKp
X<SvPOKp>
-Returns a boolean indicating whether the SV contains a character string.
+Returns a U32 value indicating whether the SV contains a character string.
Checks the B<private> setting. Use C<SvPOK>.
- bool SvPOKp(SV* sv)
+ U32 SvPOKp(SV* sv)
=for hackers
Found in file sv.h
=item SvPVx
X<SvPVx>
-A version of C<SvPV> which guarantees to evaluate sv only once.
+A version of C<SvPV> which guarantees to evaluate C<sv> only once.
+Only use this if C<sv> is an expression with side effects, otherwise use the
+more efficient C<SvPVX>.
char* SvPVx(SV* sv, STRLEN len)
=item SvREFCNT_inc_simple
X<SvREFCNT_inc_simple>
-Same as SvREFCNT_inc, but can only be used with simple variables, not
-expressions or pointer dereferences. Since we don't have to store a
-temporary value, it's faster.
+Same as SvREFCNT_inc, but can only be used with expressions without side
+effects. Since we don't have to store a temporary value, it's faster.
SV* SvREFCNT_inc_simple(SV* sv)
Tests if the SV is an RV.
- bool SvROK(SV* sv)
+ U32 SvROK(SV* sv)
=for hackers
Found in file sv.h
Returns a boolean indicating whether the SV contains an unsigned integer.
- void SvUOK(SV* sv)
+ bool SvUOK(SV* sv)
=for hackers
Found in file sv.h
=item SvUTF8
X<SvUTF8>
-Returns a boolean indicating whether the SV contains UTF-8 encoded data.
+Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
Call this after SvPV() in case any call to string overloading updates the
internal flag.
- bool SvUTF8(SV* sv)
+ U32 SvUTF8(SV* sv)
=for hackers
Found in file sv.h
X<SvUVx>
Coerces the given SV to an unsigned integer and returns it. Guarantees to
-evaluate sv only once. Use the more efficient C<SvUV> otherwise.
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvUV>.
UV SvUVx(SV* sv)
Creates a new SV with its SvPVX_const pointing to a shared string in the string
table. If the string does not already exist in the table, it is created
-first. Turns on READONLY and FAKE. The string's hash is stored in the UV
-slot of the SV; if the C<hash> parameter is non-zero, that value is used;
-otherwise the hash is computed. The idea here is that as the string table
-is used for shared hash keys these strings will have SvPVX_const == HeKEY and
-hash lookup will avoid string compare.
+first. Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
+value is used; otherwise the hash is computed. The string's hash can be later
+be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
+that as the string table is used for shared hash keys these strings will have
+SvPVX_const == HeKEY and hash lookup will avoid string compare.
SV* newSVpvn_share(const char* s, I32 len, U32 hash)
=for hackers
Found in file sv.c
+=item newSV_type
+X<newSV_type>
+
+Creates a new SV, of the type specified. The reference count for the new SV
+is set to 1.
+
+ SV* newSV_type(svtype type)
+
+=for hackers
+Found in file sv.c
+
=item sv_2bool
X<sv_2bool>
Copies a stringified representation of the source SV into the
destination SV. Automatically performs any necessary mg_get and
coercion of numeric values into strings. Guaranteed to preserve
-UTF-8 flag even from overloaded objects. Similar in nature to
+UTF8 flag even from overloaded objects. Similar in nature to
sv_2pv[_flags] but operates directly on an SV instead of just the
string. Mostly uses sv_2pv_flags to do its work, except when that
would lose the UTF-8'ness of the PV.
X<utf8n_to_uvuni>
Bottom level UTF-8 decode routine.
-Returns the unicode code point value of the first character in the string C<s>
+Returns the Unicode code point value of the first character in the string C<s>
which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
C<retlen> will be set to the length, in bytes, of that character.