=head1 SV Flags
=for apidoc AmU||svtype
-An enum of flags for Perl types. These are found in the file B<sv.h>
+An enum of flags for Perl types. These are found in the file F<sv.h>
in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
The types are:
These are most easily explained from the bottom up.
-SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for
-subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays.
+C<SVt_PVIO> is for I/O objects, C<SVt_PVFM> for formats, C<SVt_PVCV> for
+subroutines, C<SVt_PVHV> for hashes and C<SVt_PVAV> for arrays.
All the others are scalar types, that is, things that can be bound to a
C<$> variable. For these, the internal types are mostly orthogonal to
Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether
something is a scalar.
-SVt_PVGV represents a typeglob. If !SvFAKE(sv), then it is a real,
-incoercible typeglob. If SvFAKE(sv), then it is a scalar to which a
+C<SVt_PVGV> represents a typeglob. If C<!SvFAKE(sv)>, then it is a real,
+incoercible typeglob. If C<SvFAKE(sv)>, then it is a scalar to which a
typeglob has been assigned. Assigning to it again will stop it from being
-a typeglob. SVt_PVLV represents a scalar that delegates to another scalar
+a typeglob. C<SVt_PVLV> represents a scalar that delegates to another scalar
behind the scenes. It is used, e.g., for the return value of C<substr> and
for tied hash and array elements. It can hold any scalar value, including
-a typeglob. SVt_REGEXP is for regular
-expressions. SVt_INVLIST is for Perl
+a typeglob. C<SVt_REGEXP> is for regular
+expressions. C<SVt_INVLIST> is for Perl
core internal use only.
-SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression,
+C<SVt_PVMG> represents a "normal" scalar (not a typeglob, regular expression,
or delegate). Since most scalars do not need all the internal fields of a
PVMG, we save memory by allocating smaller structs when possible. All the
-other types are just simpler forms of SVt_PVMG, with fewer internal fields.
- SVt_NULL can only hold undef. SVt_IV can hold undef, an integer, or a
-reference. (SVt_RV is an alias for SVt_IV, which exists for backward
-compatibility.) SVt_NV can hold any of those or a double. SVt_PV can only
-hold undef or a string. SVt_PVIV is a superset of SVt_PV and SVt_IV.
-SVt_PVNV is similar. SVt_PVMG can hold anything SVt_PVNV can hold, but it
+other types are just simpler forms of C<SVt_PVMG>, with fewer internal fields.
+C<SVt_NULL> can only hold undef. C<SVt_IV> can hold undef, an integer, or a
+reference. (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
+compatibility.) C<SVt_NV> can hold any of those or a double. C<SVt_PV> can only
+hold C<undef> or a string. C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
+C<SVt_PVNV> is similar. C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
can, but does not have to, be blessed or magical.
=for apidoc AmU||SVt_NULL
/* *** any alterations to the SV types above need to be reflected in
* SVt_MASK and the various PL_valid_types_* tables. As of this writing those
* tables are in perl.h. There are also two affected names tables in dump.c,
- * one in B.xs, and 'bodies_by_type[]' in sv.c */
+ * one in B.xs, and 'bodies_by_type[]' in sv.c.
+ *
+ * The bits that match 0xf0 are CURRENTLY UNUSED, except that 0xFF means a
+ * freed SV. The bits above that are for flags, like SVf_IOK */
#define SVt_MASK 0xf /* smallest bitmask that covers all types */
#ifndef PERL_CORE
-/* Although Fast Boyer Moore tables are now being stored in PVGVs, for most
- purposes external code wanting to consider PVBM probably needs to think of
- PVMG instead. */
+/* Fast Boyer Moore tables are now stored in magic attached to PVMGs */
# define SVt_PVBM SVt_PVMG
/* Anything wanting to create a reference from clean should ensure that it has
a scalar of type SVt_IV now: */
UV svu_uv; \
_NV_BODYLESS_UNION \
SV* svu_rv; /* pointer to another SV */ \
- struct regexp* svu_rx; \
SV** svu_array; \
HE** svu_hash; \
GP* svu_gp; \
=head1 SV Manipulation Functions
=for apidoc Am|U32|SvREFCNT|SV* sv
-Returns the value of the object's reference count.
+Returns the value of the object's reference count. Exposed
+to perl code via Internals::SvREFCNT().
=for apidoc Am|SV*|SvREFCNT_inc|SV* sv
Increments the reference count of the given SV, returning the SV.
-All of the following SvREFCNT_inc* macros are optimized versions of
-SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
+All of the following C<SvREFCNT_inc>* macros are optimized versions of
+C<SvREFCNT_inc>, and can be replaced with C<SvREFCNT_inc>.
=for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_void|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the
return value. The macro doesn't need to return a meaningful value.
=for apidoc Am|void|SvREFCNT_inc_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple|SV* sv
-Same as SvREFCNT_inc, but can only be used with expressions without side
+Same as C<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.
=for apidoc Am|SV*|SvREFCNT_inc_simple_NN|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc_simple>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_simple_void|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+Same as C<SvREFCNT_inc_simple>, but can only be used if you don't need the
return value. The macro doesn't need to return a meaningful value.
=for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV. I<sv> may be NULL.
+Decrements the reference count of the given SV. C<sv> may be C<NULL>.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
-Same as SvREFCNT_dec, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_dec>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|svtype|SvTYPE|SV* sv
-Returns the type of the SV. See C<svtype>.
+Returns the type of the SV. See C<L</svtype>>.
=for apidoc Am|void|SvUPGRADE|SV* sv|svtype type
Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
-perform the upgrade if necessary. See C<svtype>.
+perform the upgrade if necessary. See C<L</svtype>>.
=cut
*/
#define SVp_IOK 0x00001000 /* has valid non-public integer value */
#define SVp_NOK 0x00002000 /* has valid non-public numeric value */
#define SVp_POK 0x00004000 /* has valid non-public pointer value */
-#define SVp_SCREAM 0x00008000 /* method name is DOES */
- /* eval cx text is ref counted */
+#define SVp_SCREAM 0x00008000 /* currently unused on plain scalars */
#define SVphv_CLONEABLE SVp_SCREAM /* PVHV (stashes) clone its objects */
#define SVpgv_GP SVp_SCREAM /* GV has a valid GP */
#define SVprv_PCS_IMPORTED SVp_SCREAM /* RV is a proxy for a constant
subroutine in another package. Set the
GvIMPORTED_CV_on() if it needs to be
expanded to a real GV */
+
+/* SVf_PROTECT is what SVf_READONLY should have been: i.e. modifying
+ * this SV is completely illegal. However, SVf_READONLY (via
+ * Internals::SvREADONLY()) has come to be seen as a flag that can be
+ * temporarily set and unset by the user to indicate e.g. whether a hash
+ * is "locked". Now, Hash::Util et al only set SVf_READONLY, while core
+ * sets both (SVf_READONLY|SVf_PROTECT) to indicate both to core and user
+ * code that this SV should not be messed with.
+ */
#define SVf_PROTECT 0x00010000 /* very read-only */
#define SVs_PADTMP 0x00020000 /* in use as tmp */
#define SVs_PADSTALE 0x00040000 /* lexical has gone out of scope;
refers to an eval or once only
[CvEVAL(cv), CvSPECIAL(cv)]
3: HV: informally reserved by DAPM
- for vtables */
+ for vtables
+ 4: Together with other flags (or
+ lack thereof) indicates a regex,
+ including PVLV-as-regex. See
+ isREGEXP().
+ */
#define SVf_OOK 0x02000000 /* has valid offset value. For a PVHV this
means that a hv_aux struct is present
after the main array */
#define SVf_BREAK 0x04000000 /* refcnt is artificially low - used by
SVs in final arena cleanup.
Set in S_regtry on PL_reg_curpm, so that
- perl_destruct will skip it. */
+ perl_destruct will skip it.
+ Used for mark and sweep by OP_AASSIGN
+ */
#define SVf_READONLY 0x08000000 /* may not be modified */
#define PRIVSHIFT 4 /* (SVp_?OK >> PRIVSHIFT) == SVf_?OK */
-/* Note that SVf_AMAGIC is now only set on stashes. */
+/* SVf_AMAGIC means that the stash *may* have have overload methods. It's
+ * set each time a function is compiled into a stash, and is reset by the
+ * overload code when called for the first time and finds that there are
+ * no overload methods. Note that this used to be set on the object; but
+ * is now only set on stashes.
+ */
#define SVf_AMAGIC 0x10000000 /* has magical overloaded methods */
#define SVf_IsCOW 0x10000000 /* copy on write (shared hash key if
SvLEN == 0) */
/* Some private flags. */
-/* The SVp_SCREAM|SVpbm_VALID (0x40008000) combination is up for grabs.
- Formerly it was used for pad names, but now it is available. The core
- is careful to avoid setting both flags.
-
- SVf_POK, SVp_POK also set:
- 0x00004400 Normal
- 0x0000C400 method name for DOES (SvSCREAM)
- 0x40004400 FBM compiled (SvVALID)
- 0x4000C400 *** Formerly used for pad names ***
-
- 0x00008000 GV with GP
- 0x00008800 RV with PCS imported
-*/
/* PVAV */
#define SVpav_REAL 0x40000000 /* free old entries */
/* PVHV */
#define SVphv_LAZYDEL 0x40000000 /* entry in xhv_eiter must be deleted */
-/* This is only set true on a PVGV when it's playing "PVBM", but is tested for
- on any regular scalar (anything <= PVLV) */
-#define SVpbm_VALID 0x40000000
-/* Only used in toke.c on an SV stored in PL_lex_repl */
-#define SVrepl_EVAL 0x40000000 /* Replacement part of s///e */
/* IV, PVIV, PVNV, PVMG, PVGV and (I assume) PVLV */
#define SVf_IVisUV 0x80000000 /* use XPVUV instead of XPVIV */
#define SVpav_REIFY 0x80000000 /* can become real */
/* PVHV */
#define SVphv_HASKFLAGS 0x80000000 /* keys have flag byte after hash */
-/* PVGV when SVpbm_VALID is true */
-#define SVpbm_TAIL 0x80000000
/* RV upwards. However, SVf_ROK and SVp_IOK are exclusive */
#define SVprv_WEAKREF 0x80000000 /* Weak reference */
/* pad name vars only */
STRLEN xpv_cur; /* length of svu_pv as a C string */ \
union { \
STRLEN xpvlenu_len; /* allocated size */ \
- char * xpvlenu_pv; /* regexp string */ \
+ struct regexp* xpvlenu_rx; /* regex when SV body is XPVLV */ \
} xpv_len_u
#define xpv_len xpv_len_u.xpvlenu_len
union _xnvu {
NV xnv_nv; /* numeric value, if any */
HV * xgv_stash;
- struct {
- U32 xlow;
- U32 xhigh;
- } xpad_cop_seq; /* used by pad.c for cop_sequence */
+ line_t xnv_lines; /* used internally by S_scan_subst() */
+ bool xnv_bm_tail; /* an SvVALID (BM) SV has an implicit "\n" */
};
union _xivu {
IV xivu_iv; /* integer value */
UV xivu_uv;
HEK * xivu_namehek; /* xpvlv, xpvgv: GvNAME */
+ bool xivu_eval_seen; /* used internally by S_scan_subst() */
+
};
union _xmgu {
SV* xlv_targ;
char xlv_type; /* k=keys .=pos x=substr v=vec /=join/re
* y=alem/helem/iter t=tie T=tied HE */
- char xlv_flags; /* 1 = negative offset 2 = negative len */
+ char xlv_flags; /* 1 = negative offset 2 = negative len
+ 4 = out of range (vec) */
};
#define xlv_targoff xlv_targoff_u.xlvu_targoff
the list, merely toggle this flag */
};
-/* This structure works in 3 ways - regular scalar, GV with GP, or fast
- Boyer-Moore. */
+/* This structure works in 2 ways - regular scalar, or GV with GP */
+
struct xpvgv {
_XPV_HEAD;
union _xivu xiv_u;
* Perl_filter_add() tries to do with the dirp), hence the
* following union trick (as suggested by Gurusamy Sarathy).
* For further information see Geir Johansen's problem report
- * titled [ID 20000612.002] Perl problem on Cray system
+ * titled [ID 20000612.002 (#3366)] Perl problem on Cray system
* The any pointer (known as IoANY()) will also be a good place
* to hang any IO disciplines to.
*/
Unsets the IV status of an SV.
=for apidoc Am|void|SvIOK_only|SV* sv
-Tells an SV that it is an integer and disables all other OK bits.
+Tells an SV that it is an integer and disables all other C<OK> bits.
=for apidoc Am|void|SvIOK_only_UV|SV* sv
-Tells an SV that it is an unsigned integer and disables all other OK bits.
+Tells an SV that it is an unsigned integer and disables all other C<OK> bits.
=for apidoc Am|bool|SvIOK_UV|SV* sv
Returns a boolean indicating whether the SV contains an integer that must be
interpreted as unsigned. A non-negative integer whose value is within the
-range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvUOK|SV* sv
Returns a boolean indicating whether the SV contains an integer that must be
interpreted as unsigned. A non-negative integer whose value is within the
-range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvIOK_notUV|SV* sv
Returns a boolean indicating whether the SV contains a signed integer.
Unsets the PV status of an SV.
=for apidoc Am|void|SvPOK_only|SV* sv
-Tells an SV that it is a string and disables all other OK bits.
+Tells an SV that it is a string and disables all other C<OK> bits.
Will also turn off the UTF-8 status.
=for apidoc Am|bool|SvVOK|SV* sv
=for apidoc Am|U32|SvOOK|SV* sv
Returns a U32 indicating whether the pointer to the string buffer is offset.
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 actually C<SvOOK_offset()> bytes before SvPVX.
-This offset used to be stored in SvIVX, but is now stored within the spare
+beginning of a C<SvPV>. When C<SvOOK> is true, then the start of the
+allocated string buffer is actually C<SvOOK_offset()> bytes before C<SvPVX>.
+This offset used to be stored in C<SvIVX>, but is now stored within the spare
part of the buffer.
=for apidoc Am|U32|SvROK|SV* sv
=for apidoc Am|IV|SvIVX|SV* sv
Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvIV>>.
=for apidoc Am|UV|SvUVX|SV* sv
Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvUV()>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvUV>>.
=for apidoc Am|NV|SvNVX|SV* sv
Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
+Only use when you are sure C<SvNOK> is true. See also C<L</SvNV>>.
=for apidoc Am|char*|SvPVX|SV* sv
Returns a pointer to the physical string in the SV. The SV must contain a
string. Prior to 5.9.3 it is not safe
to execute this macro unless the SV's
-type >= SVt_PV.
+type >= C<SVt_PV>.
This is also used to store the name of an autoloaded subroutine in an XS
AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>.
=for apidoc Am|STRLEN|SvCUR|SV* sv
-Returns the length of the string which is in the SV. See C<SvLEN>.
+Returns the length of the string which is in the SV. See C<L</SvLEN>>.
=for apidoc Am|STRLEN|SvLEN|SV* sv
Returns the size of the string buffer in the SV, not including any part
-attributable to C<SvOOK>. See C<SvCUR>.
+attributable to C<SvOOK>. See C<L</SvCUR>>.
=for apidoc Am|char*|SvEND|SV* sv
Returns a pointer to the spot just after the last character in
the string which is in the SV, where there is usually a trailing
C<NUL> character (even though Perl scalars do not strictly require it).
-See C<SvCUR>. Access the character as *(SvEND(sv)).
+See C<L</SvCUR>>. Access the character as C<*(SvEND(sv))>.
Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to
unallocated memory.
C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
=for apidoc Am|void|SvNV_set|SV* sv|NV val
-Set the value of the NV pointer in sv to val. See C<SvIV_set>.
+Set the value of the NV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvPV_set|SV* sv|char* val
This is probably not what you want to use, you probably wanted
L</sv_usepvn_flags> or L</sv_setpvn> or L</sv_setpvs>.
Set the value of the PV pointer in C<sv> to the Perl allocated
-C<NUL>-terminated string C<val>. See also C<SvIV_set>.
+C<NUL>-terminated string C<val>. See also C<L</SvIV_set>>.
Remember to free the previous PV buffer. There are many things to check.
Beware that the existing pointer may be involved in copy-on-write or other
mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
-C<SvPV_force> (or check the SvIsCOW flag) first to make sure this
+C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
modification is safe. Then finally, if it is not a COW, call C<SvPV_free> to
free the previous PV buffer.
=for apidoc Am|void|SvUV_set|SV* sv|UV val
-Set the value of the UV pointer in sv to val. See C<SvIV_set>.
+Set the value of the UV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvRV_set|SV* sv|SV* val
-Set the value of the RV pointer in sv to val. See C<SvIV_set>.
+Set the value of the RV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvMAGIC_set|SV* sv|MAGIC* val
-Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
+Set the value of the MAGIC pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvSTASH_set|SV* sv|HV* val
-Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
+Set the value of the STASH pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len
-Set the current length of the string which is in the SV. See C<SvCUR>
-and C<SvIV_set>.
+Set the current length of the string which is in the SV. See C<L</SvCUR>>
+and C<SvIV_set>>.
=for apidoc Am|void|SvLEN_set|SV* sv|STRLEN len
-Set the actual length of the string which is in the SV. See C<SvIV_set>.
+Set the size of the string buffer for the SV. See C<L</SvLEN>>.
=cut
*/
#define assert_not_ROK(sv) assert_(!SvROK(sv) || !SvRV(sv))
#define assert_not_glob(sv) assert_(!isGV_with_GP(sv))
-#define SvOK(sv) (SvFLAGS(sv) & SVf_OK || isREGEXP(sv))
+#define SvOK(sv) (SvFLAGS(sv) & SVf_OK)
#define SvOK_off(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
SvFLAGS(sv) &= ~(SVf_OK| \
SVf_IVisUV|SVf_UTF8), \
=for apidoc Am|U32|SvUTF8|SV* sv
Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up
properly, this indicates whether or not the SV contains UTF-8 encoded data.
-You should use this I<after> a call to SvPV() or one of its variants, in
+You should use this I<after> a call to C<SvPV()> or one of its variants, in
case any call to string overloading updates the internal flag.
If you want to take into account the L<bytes> pragma, use C<L</DO_UTF8>>
Do not use frivolously.
=for apidoc Am|void|SvPOK_only_UTF8|SV* sv
-Tells an SV that it is a string and disables all other OK bits,
+Tells an SV that it is a string and disables all other C<OK> bits,
and leaves the UTF-8 status as it was.
=cut
#define SvOOK(sv) (SvFLAGS(sv) & SVf_OOK)
#define SvOOK_on(sv) (SvFLAGS(sv) |= SVf_OOK)
-#define SvOOK_off(sv) ((void)(SvOOK(sv) && sv_backoff(sv)))
+#define SvOOK_off(sv) ((void)(SvOOK(sv) && (sv_backoff(sv),0)))
#define SvFAKE(sv) (SvFLAGS(sv) & SVf_FAKE)
#define SvFAKE_on(sv) (SvFLAGS(sv) |= SVf_FAKE)
/*
=for apidoc m|U32|SvTHINKFIRST|SV *sv
-A quick flag check to see whether an sv should be passed to sv_force_normal
-to be "downgraded" before SvIVX or SvPVX can be modified directly.
+A quick flag check to see whether an C<sv> should be passed to C<sv_force_normal>
+to be "downgraded" before C<SvIVX> or C<SvPVX> can be modified directly.
-For example, if your scalar is a reference and you want to modify the SvIVX
-slot, you can't just do SvROK_off, as that will leak the referent.
+For example, if your scalar is a reference and you want to modify the C<SvIVX>
+slot, you can't just do C<SvROK_off>, as that will leak the referent.
This is used internally by various sv-modifying functions, such as
-sv_setsv, sv_setiv and sv_pvn_force.
+C<sv_setsv>, C<sv_setiv> and C<sv_pvn_force>.
One case that this does not handle is a gv without SvFAKE set. After
it will still be a gv.
-SvTHINKFIRST sometimes produces false positives. In those cases
-sv_force_normal does nothing.
+C<SvTHINKFIRST> sometimes produces false positives. In those cases
+C<sv_force_normal> does nothing.
=cut
*/
#define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT)
#define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT)
+/*
+=for apidoc Am|U32|SvREADONLY|SV* sv
+Returns true if the argument is readonly, otherwise returns false.
+Exposed to to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_on|SV* sv
+Mark an object as readonly. Exactly what this means depends on the object
+type. Exposed to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_off|SV* sv
+Mark an object as not-readonly. Exactly what this mean depends on the
+object type. Exposed to perl code via Internals::SvREADONLY().
+
+=cut
+*/
+
#define SvREADONLY(sv) (SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT))
#ifdef PERL_CORE
# define SvREADONLY_on(sv) (SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT))
# define SvCOMPILED_off(sv)
#endif
-#define SvEVALED(sv) (SvFLAGS(sv) & SVrepl_EVAL)
-#define SvEVALED_on(sv) (SvFLAGS(sv) |= SVrepl_EVAL)
-#define SvEVALED_off(sv) (SvFLAGS(sv) &= ~SVrepl_EVAL)
#if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
-# define SvVALID(sv) ({ const SV *const _svvalid = (const SV*)(sv); \
- if (SvFLAGS(_svvalid) & SVpbm_VALID && !SvSCREAM(_svvalid)) \
- assert(!isGV_with_GP(_svvalid)); \
- (SvFLAGS(_svvalid) & SVpbm_VALID); \
- })
-# define SvVALID_on(sv) ({ SV *const _svvalid = MUTABLE_SV(sv); \
- assert(!isGV_with_GP(_svvalid)); \
- assert(!SvSCREAM(_svvalid)); \
- (SvFLAGS(_svvalid) |= SVpbm_VALID); \
- })
-# define SvVALID_off(sv) ({ SV *const _svvalid = MUTABLE_SV(sv); \
- assert(!isGV_with_GP(_svvalid)); \
- assert(!SvSCREAM(_svvalid)); \
- (SvFLAGS(_svvalid) &= ~SVpbm_VALID); \
- })
-
# define SvTAIL(sv) ({ const SV *const _svtail = (const SV *)(sv); \
assert(SvTYPE(_svtail) != SVt_PVAV); \
assert(SvTYPE(_svtail) != SVt_PVHV); \
- assert(!SvSCREAM(_svtail)); \
- (SvFLAGS(sv) & (SVpbm_TAIL|SVpbm_VALID)) \
- == (SVpbm_TAIL|SVpbm_VALID); \
+ assert(!(SvFLAGS(_svtail) & (SVf_NOK|SVp_NOK))); \
+ assert(SvVALID(_svtail)); \
+ ((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail; \
})
#else
-# define SvVALID(sv) ((SvFLAGS(sv) & SVpbm_VALID) && !SvSCREAM(sv))
-# define SvVALID_on(sv) (SvFLAGS(sv) |= SVpbm_VALID)
-# define SvVALID_off(sv) (SvFLAGS(sv) &= ~SVpbm_VALID)
-# define SvTAIL(sv) ((SvFLAGS(sv) & (SVpbm_TAIL|SVpbm_VALID)) \
- == (SVpbm_TAIL|SVpbm_VALID))
-
+# define SvTAIL(_svtail) (((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail)
#endif
-#define SvTAIL_on(sv) (SvFLAGS(sv) |= SVpbm_TAIL)
-#define SvTAIL_off(sv) (SvFLAGS(sv) &= ~SVpbm_TAIL)
+
+/* Does the SV have a Boyer-Moore table attached as magic?
+ * 'VALID' is a poor name, but is kept for historical reasons. */
+#define SvVALID(_svvalid) ( \
+ SvPOKp(_svvalid) \
+ && SvSMAGICAL(_svvalid) \
+ && SvMAGIC(_svvalid) \
+ && (SvMAGIC(_svvalid)->mg_type == PERL_MAGIC_bm \
+ || mg_find(_svvalid, PERL_MAGIC_bm)) \
+ )
#define SvRVx(sv) SvRV(sv)
}))
# define SvCUR(sv) \
(*({ const SV *const _svcur = (const SV *)(sv); \
- assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK] \
- || SvTYPE(_svcur) == SVt_REGEXP); \
+ assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]); \
assert(!isGV_with_GP(_svcur)); \
assert(!(SvTYPE(_svcur) == SVt_PVIO \
&& !(IoFLAGS(_svcur) & IOf_FAKE_DIRP))); \
(((XPVMG*) SvANY(sv))->xmg_stash = (val)); } STMT_END
#define SvCUR_set(sv, val) \
STMT_START { \
- assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK] \
- || SvTYPE(sv) == SVt_REGEXP); \
+ assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]); \
assert(!isGV_with_GP(sv)); \
assert(!(SvTYPE(sv) == SVt_PVIO \
&& !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
#define LvTARGLEN(sv) ((XPVLV*) SvANY(sv))->xlv_targlen
#define LvFLAGS(sv) ((XPVLV*) SvANY(sv))->xlv_flags
+#define LVf_NEG_OFF 0x1
+#define LVf_NEG_LEN 0x2
+#define LVf_OUT_OF_RANGE 0x4
+
#define IoIFP(sv) (sv)->sv_u.svu_fp
#define IoOFP(sv) ((XPVIO*) SvANY(sv))->xio_ofp
#define IoDIRP(sv) ((XPVIO*) SvANY(sv))->xio_dirp
#define SvTAINT(sv) \
STMT_START { \
- if (UNLIKELY(TAINTING_get)) { \
- if (UNLIKELY(TAINT_get)) \
- SvTAINTED_on(sv); \
- } \
+ assert(TAINTING_get || !TAINT_get); \
+ if (UNLIKELY(TAINT_get)) \
+ SvTAINTED_on(sv); \
} STMT_END
/*
the SV if the SV does not contain a string. The SV may cache the
stringified version becoming C<SvPOK>. Handles 'get' magic. The
C<len> variable will be set to the length of the string (this is a macro, so
-don't use C<&len>). See also C<SvPVx> for a version which guarantees to
-evaluate sv only once.
+don't use C<&len>). See also C<L</SvPVx>> for a version which guarantees to
+evaluate C<sv> only once.
Note that there is no guarantee that the return value of C<SvPV()> is
equal to C<SvPVX(sv)>, or that C<SvPVX(sv)> contains valid data, or that
successive calls to C<SvPV(sv)> will return the same pointer value each
time. This is due to the way that things like overloading and
Copy-On-Write are handled. In these cases, the return value may point to
-a temporary buffer or similar. If you absolutely need the SvPVX field to
+a temporary buffer or similar. If you absolutely need the C<SvPVX> field to
be valid (for example, if you intend to write to it), then see
-L</SvPV_force>.
+C<L</SvPV_force>>.
=for apidoc Am|char*|SvPVx|SV* sv|STRLEN len
A version of C<SvPV> which guarantees to evaluate C<sv> only once.
Like C<SvPV_nolen> but doesn't process magic.
=for apidoc Am|IV|SvIV|SV* sv
-Coerces the given SV to an integer and returns it. See C<SvIVx> for a
-version which guarantees to evaluate sv only once.
+Coerces the given SV to IV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s IV slot, but not in all cases. (Use
+C<L</sv_setiv>> to make sure it does).
+
+See C<L</SvIVx>> for a version which guarantees to evaluate C<sv> only once.
=for apidoc Am|IV|SvIV_nomg|SV* sv
Like C<SvIV> but doesn't process magic.
=for apidoc Am|IV|SvIVx|SV* sv
-Coerces the given SV to an integer and returns it.
-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<SvIV>.
+Coerces the given SV to IV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s IV slot, but not in all cases. (Use
+C<L</sv_setiv>> to make sure it does).
+
+This form 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<SvIV>.
=for apidoc Am|NV|SvNV|SV* sv
-Coerce the given SV to a double and return it. See C<SvNVx> for a version
-which guarantees to evaluate sv only once.
+Coerces the given SV to NV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s NV slot, but not in all cases. (Use
+C<L</sv_setnv>> to make sure it does).
+
+See C<L</SvNVx>> for a version which guarantees to evaluate C<sv> only once.
=for apidoc Am|NV|SvNV_nomg|SV* sv
Like C<SvNV> but doesn't process magic.
=for apidoc Am|NV|SvNVx|SV* sv
-Coerces the given SV to a double and returns it.
-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<SvNV>.
+Coerces the given SV to NV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s NV slot, but not in all cases. (Use
+C<L</sv_setnv>> to make sure it does).
+
+This form 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<SvNV>.
=for apidoc Am|UV|SvUV|SV* sv
-Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
-for a version which guarantees to evaluate sv only once.
+Coerces the given SV to UV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s UV slot, but not in all cases. (Use
+C<L</sv_setuv>> to make sure it does).
+
+See C<L</SvUVx>> for a version which guarantees to evaluate C<sv> only once.
=for apidoc Am|UV|SvUV_nomg|SV* sv
Like C<SvUV> but doesn't process magic.
=for apidoc Am|UV|SvUVx|SV* sv
-Coerces the given SV to an unsigned integer and
-returns it. 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<SvUV>.
+Coerces the given SV to UV and returns it. The returned value in many
+circumstances will get stored in C<sv>'s UV slot, but not in all cases. (Use
+C<L</sv_setuv>> to make sure it does).
+
+This form 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<SvUV>.
=for apidoc Am|bool|SvTRUE|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Handles 'get' magic
-unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the
+false. See C<L</SvOK>> for a defined/undefined test. Handles 'get' magic
+unless the scalar is already C<SvPOK>, C<SvIOK> or C<SvNOK> (the public, not the
private flags).
=for apidoc Am|bool|SvTRUE_nomg|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Does not handle 'get' magic.
+false. See C<L</SvOK>> for a defined/undefined test. Does not handle 'get' magic.
=for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
+Like C<SvPV>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVutf8_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
+Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8_force>
otherwise.
=for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
+Like C<SvPV>, but converts C<sv> to UTF-8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8>
otherwise.
=for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte_force>
otherwise.
=for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte>
otherwise.
=for apidoc Am|U32|SvIsCOW|SV* sv
=for apidoc Amdb|STRLEN|sv_utf8_upgrade_nomg|NN SV *sv
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
+Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
=cut
*/
#define SvSHARED_HASH(sv) (0 + SvSHARED_HEK_FROM_PV(SvPVX_const(sv))->hek_hash)
/* flag values for sv_*_flags functions */
+#define SV_UTF8_NO_ENCODING 0 /* No longer used */
#define SV_IMMEDIATE_UNREF 1
#define SV_GMAGIC 2
#define SV_COW_DROP_PV 4
-#define SV_UTF8_NO_ENCODING 8
#define SV_NOSTEAL 16
#define SV_CONST_RETURN 32
#define SV_MUTABLE_RETURN 64
#define newRV_inc(sv) newRV(sv)
-/* the following macros update any magic values this sv is associated with */
+/* the following macros update any magic values this C<sv> is associated with */
/*
=head1 Magical Functions
argument more than once.
=for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+Calls C<sv_setsv> if C<dsv> is not the same as C<ssv>. May evaluate arguments
more than once. Does not handle 'set' magic on the destination SV.
=for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
+Calls a non-destructive version of C<sv_setsv> if C<dsv> is not the same as
+C<ssv>. May evaluate arguments more than once.
=for apidoc Am|void|SvSetMagicSV|SV* dsv|SV* ssv
Like C<SvSetSV>, but does any set magic required afterwards.
Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
=for apidoc Am|void|SvSHARE|SV* sv
-Arranges for sv to be shared between threads if a suitable module
+Arranges for C<sv> to be shared between threads if a suitable module
has been loaded.
=for apidoc Am|void|SvLOCK|SV* sv
-Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+Arranges for a mutual exclusion lock to be obtained on C<sv> if a suitable module
has been loaded.
=for apidoc Am|void|SvUNLOCK|SV* sv
-Releases a mutual exclusion lock on sv if a suitable module
+Releases a mutual exclusion lock on C<sv> if a suitable module
has been loaded.
=head1 SV Manipulation Functions
indicated number of bytes (remember to reserve space for an extra trailing
C<NUL> character). Calls C<sv_grow> to perform the expansion if necessary.
Returns a pointer to the character
-buffer. SV must be of type >= SVt_PV. One
+buffer. SV must be of type >= C<SVt_PV>. One
alternative is to call C<sv_grow> if you are not sure of the type of SV.
+You might mistakenly think that C<len> is the number of bytes to add to the
+existing size, but instead it is the total size C<sv> should be.
+
+=for apidoc Am|char *|SvPVCLEAR|SV* sv
+Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
+properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
+
=cut
*/
+#define SvPVCLEAR(sv) sv_setpv_bufsize(sv,0,0)
#define SvSHARE(sv) PL_sharehook(aTHX_ sv)
#define SvLOCK(sv) PL_lockhook(aTHX_ sv)
#define SvUNLOCK(sv) PL_unlockhook(aTHX_ sv)
#define SvPEEK(sv) ""
#endif
-#define SvIMMORTAL(sv) (SvREADONLY(sv) && ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no || (sv)==&PL_sv_placeholder))
+#define SvIMMORTAL(sv) (SvREADONLY(sv) && ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no || (sv)==&PL_sv_zero || (sv)==&PL_sv_placeholder))
#ifdef DEBUGGING
/* exercise the immortal resurrection code in sv_free2() */
Returns a true SV if C<b> is a true value, or a false SV if C<b> is 0.
-See also C<PL_sv_yes> and C<PL_sv_no>.
+See also C<L</PL_sv_yes>> and C<L</PL_sv_no>>.
=cut
*/
} STMT_END
#define isREGEXP(sv) \
(SvTYPE(sv) == SVt_REGEXP \
- || (SvFLAGS(sv) & (SVTYPEMASK|SVp_POK|SVpgv_GP|SVf_FAKE)) \
+ || (SvFLAGS(sv) & (SVTYPEMASK|SVpgv_GP|SVf_FAKE)) \
== (SVt_PVLV|SVf_FAKE))
=for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8
Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
-characters) into it. If utf8 is true, calls
+characters) into it. If C<utf8> is true, calls
C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
=cut
/*
=for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
-Reads into I<len> the offset from SvPVX back to the true start of the
+Reads into C<len> the offset from C<SvPVX> back to the true start of the
allocated buffer, which will be non-zero if C<sv_chop> has been used to
efficiently remove characters from start of the buffer. Implemented as a
-macro, which takes the address of I<len>, which must be of type C<STRLEN>.
-Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
+macro, which takes the address of C<len>, which must be of type C<STRLEN>.
+Evaluates C<sv> more than once. Sets C<len> to 0 if C<SvOOK(sv)> is false.
=cut
*/
#define SV_CONSTS_COUNT 35
/*
+ * Bodyless IVs and NVs!
+ *
+ * Since 5.9.2, we can avoid allocating a body for SVt_IV-type SVs.
+ * Since the larger IV-holding variants of SVs store their integer
+ * values in their respective bodies, the family of SvIV() accessor
+ * macros would naively have to branch on the SV type to find the
+ * integer value either in the HEAD or BODY. In order to avoid this
+ * expensive branch, a clever soul has deployed a great hack:
+ * We set up the SvANY pointer such that instead of pointing to a
+ * real body, it points into the memory before the location of the
+ * head. We compute this pointer such that the location of
+ * the integer member of the hypothetical body struct happens to
+ * be the same as the location of the integer member of the bodyless
+ * SV head. This now means that the SvIV() family of accessors can
+ * always read from the (hypothetical or real) body via SvANY.
+ *
+ * Since the 5.21 dev series, we employ the same trick for NVs
+ * if the architecture can support it (NVSIZE <= IVSIZE).
+ */
+
+/* The following two macros compute the necessary offsets for the above
+ * trick and store them in SvANY for SvIV() (and friends) to use. */
+
+#ifdef PERL_CORE
+# define SET_SVANY_FOR_BODYLESS_IV(sv) \
+ SvANY(sv) = (XPVIV*)((char*)&(sv->sv_u.svu_iv) \
+ - STRUCT_OFFSET(XPVIV, xiv_iv))
+
+# define SET_SVANY_FOR_BODYLESS_NV(sv) \
+ SvANY(sv) = (XPVNV*)((char*)&(sv->sv_u.svu_nv) \
+ - STRUCT_OFFSET(XPVNV, xnv_u.xnv_nv))
+#endif
+
+/*
* ex: set ts=8 sts=4 sw=4 et:
*/
https://perl5.git.perl.org / perl5.git / blobdiff