This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl5db: add tests for v command
[perl5.git] / sv.h
CommitLineData
a0d0e21e 1/* sv.h
79072805 2 *
1129b882 3 * Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
83706693 4 * 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 by Larry Wall and others
79072805
LW
5 *
6 * You may distribute under the terms of either the GNU General Public
7 * License or the Artistic License, as specified in the README file.
8 *
79072805
LW
9 */
10
a0d0e21e
LW
11#ifdef sv_flags
12#undef sv_flags /* Convex has this in <signal.h> for sigvec() */
13#endif
14
954c1994 15/*
3f620621 16=for apidoc_section $SV_flags
ccfc67b7 17
e17573c0 18=for apidoc Ay||svtype
75af9d73 19An enum of flags for Perl types. These are found in the file F<sv.h>
954c1994
GS
20in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
21
a5e62da0
FC
22The types are:
23
24 SVt_NULL
a5e62da0
FC
25 SVt_IV
26 SVt_NV
27 SVt_RV
28 SVt_PV
29 SVt_PVIV
30 SVt_PVNV
31 SVt_PVMG
e94d9b54 32 SVt_INVLIST
a5e62da0
FC
33 SVt_REGEXP
34 SVt_PVGV
35 SVt_PVLV
36 SVt_PVAV
37 SVt_PVHV
38 SVt_PVCV
39 SVt_PVFM
40 SVt_PVIO
41
42These are most easily explained from the bottom up.
43
796b6530
KW
44C<SVt_PVIO> is for I/O objects, C<SVt_PVFM> for formats, C<SVt_PVCV> for
45subroutines, C<SVt_PVHV> for hashes and C<SVt_PVAV> for arrays.
a5e62da0
FC
46
47All the others are scalar types, that is, things that can be bound to a
48C<$> variable. For these, the internal types are mostly orthogonal to
49types in the Perl language.
50
51Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether
52something is a scalar.
53
796b6530
KW
54C<SVt_PVGV> represents a typeglob. If C<!SvFAKE(sv)>, then it is a real,
55incoercible typeglob. If C<SvFAKE(sv)>, then it is a scalar to which a
a5e62da0 56typeglob has been assigned. Assigning to it again will stop it from being
796b6530 57a typeglob. C<SVt_PVLV> represents a scalar that delegates to another scalar
a5e62da0
FC
58behind the scenes. It is used, e.g., for the return value of C<substr> and
59for tied hash and array elements. It can hold any scalar value, including
796b6530
KW
60a typeglob. C<SVt_REGEXP> is for regular
61expressions. C<SVt_INVLIST> is for Perl
e94d9b54 62core internal use only.
a5e62da0 63
796b6530 64C<SVt_PVMG> represents a "normal" scalar (not a typeglob, regular expression,
a5e62da0
FC
65or delegate). Since most scalars do not need all the internal fields of a
66PVMG, we save memory by allocating smaller structs when possible. All the
796b6530
KW
67other types are just simpler forms of C<SVt_PVMG>, with fewer internal fields.
68C<SVt_NULL> can only hold undef. C<SVt_IV> can hold undef, an integer, or a
69reference. (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
70compatibility.) C<SVt_NV> can hold any of those or a double. C<SVt_PV> can only
71hold C<undef> or a string. C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
72C<SVt_PVNV> is similar. C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
a5e62da0
FC
73can, but does not have to, be blessed or magical.
74
78342678 75=for apidoc AmnU||SVt_NULL
a5e62da0 76Type flag for scalars. See L</svtype>.
954c1994 77
78342678 78=for apidoc AmnU||SVt_IV
a5e62da0 79Type flag for scalars. See L</svtype>.
954c1994 80
78342678 81=for apidoc AmnU||SVt_NV
a5e62da0
FC
82Type flag for scalars. See L</svtype>.
83
78342678 84=for apidoc AmnU||SVt_PV
a5e62da0
FC
85Type flag for scalars. See L</svtype>.
86
78342678 87=for apidoc AmnU||SVt_PVIV
a5e62da0
FC
88Type flag for scalars. See L</svtype>.
89
78342678 90=for apidoc AmnU||SVt_PVNV
a5e62da0 91Type flag for scalars. See L</svtype>.
954c1994 92
78342678 93=for apidoc AmnU||SVt_PVMG
a5e62da0
FC
94Type flag for scalars. See L</svtype>.
95
f85ae787
KW
96=for apidoc CmnU||SVt_INVLIST
97Type flag for scalars. See L<perlapi/svtype>.
e94d9b54 98
78342678 99=for apidoc AmnU||SVt_REGEXP
a5e62da0
FC
100Type flag for regular expressions. See L</svtype>.
101
78342678 102=for apidoc AmnU||SVt_PVGV
a5e62da0
FC
103Type flag for typeglobs. See L</svtype>.
104
78342678 105=for apidoc AmnU||SVt_PVLV
a5e62da0 106Type flag for scalars. See L</svtype>.
954c1994 107
78342678 108=for apidoc AmnU||SVt_PVAV
a5e62da0 109Type flag for arrays. See L</svtype>.
954c1994 110
78342678 111=for apidoc AmnU||SVt_PVHV
a5e62da0 112Type flag for hashes. See L</svtype>.
954c1994 113
78342678 114=for apidoc AmnU||SVt_PVCV
a5e62da0
FC
115Type flag for subroutines. See L</svtype>.
116
78342678 117=for apidoc AmnU||SVt_PVFM
a5e62da0
FC
118Type flag for formats. See L</svtype>.
119
78342678 120=for apidoc AmnU||SVt_PVIO
a5e62da0 121Type flag for I/O objects. See L</svtype>.
954c1994
GS
122
123=cut
1078c6a2
KW
124
125 These are ordered so that the simpler types have a lower value; SvUPGRADE
126 doesn't allow you to upgrade from a higher numbered type to a lower numbered
127 one; also there is code that assumes that anything that has as a PV component
128 has a type numbered >= SVt_PV.
954c1994
GS
129*/
130
1078c6a2 131
79072805 132typedef enum {
1f4fbd3b
MS
133 SVt_NULL, /* 0 */
134 /* BIND was here, before INVLIST replaced it. */
135 SVt_IV, /* 1 */
136 SVt_NV, /* 2 */
137 /* RV was here, before it was merged with IV. */
138 SVt_PV, /* 3 */
139 SVt_INVLIST, /* 4, implemented as a PV */
140 SVt_PVIV, /* 5 */
141 SVt_PVNV, /* 6 */
142 SVt_PVMG, /* 7 */
143 SVt_REGEXP, /* 8 */
144 /* PVBM was here, before BIND replaced it. */
145 SVt_PVGV, /* 9 */
146 SVt_PVLV, /* 10 */
147 SVt_PVAV, /* 11 */
148 SVt_PVHV, /* 12 */
149 SVt_PVCV, /* 13 */
150 SVt_PVFM, /* 14 */
151 SVt_PVIO, /* 15 */
90ba01ad
KW
152 /* 16-31: Unused, though one should be reserved for a
153 * freed sv, if the other 3 bits below the flags ones
154 * get allocated */
1f4fbd3b 155 SVt_LAST /* keep last in enum. used to size arrays */
79072805
LW
156} svtype;
157
f1fb8741 158/* *** any alterations to the SV types above need to be reflected in
e94d9b54
KW
159 * SVt_MASK and the various PL_valid_types_* tables. As of this writing those
160 * tables are in perl.h. There are also two affected names tables in dump.c,
f40abc99
KW
161 * one in B.xs, and 'bodies_by_type[]' in sv.c.
162 *
90ba01ad
KW
163 * The bits that match 0xe0 are CURRENTLY UNUSED
164 * The bits above that are for flags, like SVf_IOK */
f1fb8741 165
90ba01ad 166#define SVt_MASK 0x1f /* smallest bitmask that covers all types */
f1fb8741 167
cecf5685 168#ifndef PERL_CORE
a5c7cb08 169/* Fast Boyer Moore tables are now stored in magic attached to PVMGs */
cecf5685 170# define SVt_PVBM SVt_PVMG
4df7f6af
NC
171/* Anything wanting to create a reference from clean should ensure that it has
172 a scalar of type SVt_IV now: */
173# define SVt_RV SVt_IV
cecf5685
NC
174#endif
175
d2a0f284 176/* There is collusion here with sv_clear - sv_clear exits early for SVt_NULL
db93c0c4
NC
177 so never reaches the clause at the end that uses sv_type_details->body_size
178 to determine whether to call safefree(). Hence body_size can be set
179 non-zero to record the size of HEs, without fear of bogus frees. */
6a93a7e5
NC
180#if defined(PERL_IN_HV_C) || defined(PERL_IN_XS_APITEST)
181#define HE_SVSLOT SVt_NULL
182#endif
ff121dc6
DD
183#ifdef PERL_IN_SV_C
184# define SVt_FIRST SVt_NULL /* the type of SV that new_SV() in sv.c returns */
185#endif
43e6e717 186
232d1c15
NC
187#define PERL_ARENA_ROOTS_SIZE (SVt_LAST)
188
43e6e717
NC
189/* typedefs to eliminate some typing */
190typedef struct he HE;
191typedef struct hek HEK;
192
79072805
LW
193/* Using C's structural equivalence to help emulate C++ inheritance here... */
194
30153bd2
JC
195/* start with 2 sv-head building blocks */
196#define _SV_HEAD(ptrtype) \
197 ptrtype sv_any; /* pointer to body */ \
198 U32 sv_refcnt; /* how many references to us */ \
199 U32 sv_flags /* what we are */
200
5b306eef
DD
201#if NVSIZE <= IVSIZE
202# define _NV_BODYLESS_UNION NV svu_nv;
203#else
204# define _NV_BODYLESS_UNION
205#endif
206
30153bd2
JC
207#define _SV_HEAD_UNION \
208 union { \
1f4fbd3b
MS
209 char* svu_pv; /* pointer to malloced string */ \
210 IV svu_iv; \
211 UV svu_uv; \
212 _NV_BODYLESS_UNION \
213 SV* svu_rv; /* pointer to another SV */ \
214 SV** svu_array; \
215 HE** svu_hash; \
216 GP* svu_gp; \
217 PerlIO *svu_fp; \
bb3b7d7b
DD
218 } sv_u \
219 _SV_HEAD_DEBUG
30153bd2 220
bb3b7d7b
DD
221#ifdef DEBUG_LEAKING_SCALARS
222#define _SV_HEAD_DEBUG ;\
223 PERL_BITFIELD32 sv_debug_optype:9; /* the type of OP that allocated us */ \
224 PERL_BITFIELD32 sv_debug_inpad:1; /* was allocated in a pad for an OP */ \
225 PERL_BITFIELD32 sv_debug_line:16; /* the line where we were allocated */ \
226 UV sv_debug_serial; /* serial number of sv allocation */ \
227 char * sv_debug_file; /* the file where we were allocated */ \
228 SV * sv_debug_parent /* what we were cloned from (ithreads)*/
229#else
230#define _SV_HEAD_DEBUG
231#endif
30153bd2 232
5e045b90 233struct STRUCT_SV { /* struct sv { */
30153bd2
JC
234 _SV_HEAD(void*);
235 _SV_HEAD_UNION;
79072805
LW
236};
237
238struct gv {
30153bd2
JC
239 _SV_HEAD(XPVGV*); /* pointer to xpvgv body */
240 _SV_HEAD_UNION;
79072805
LW
241};
242
243struct cv {
30153bd2
JC
244 _SV_HEAD(XPVCV*); /* pointer to xpvcv body */
245 _SV_HEAD_UNION;
79072805
LW
246};
247
248struct av {
0f7b1ae0 249 _SV_HEAD(XPVAV*); /* pointer to xpvav body */
30153bd2 250 _SV_HEAD_UNION;
79072805
LW
251};
252
253struct hv {
30153bd2
JC
254 _SV_HEAD(XPVHV*); /* pointer to xpvhv body */
255 _SV_HEAD_UNION;
8990e307
LW
256};
257
258struct io {
30153bd2
JC
259 _SV_HEAD(XPVIO*); /* pointer to xpvio body */
260 _SV_HEAD_UNION;
79072805
LW
261};
262
d2f13c59
NC
263struct p5rx {
264 _SV_HEAD(struct regexp*); /* pointer to regexp body */
265 _SV_HEAD_UNION;
266};
267
47e6c6d9
N
268struct invlist {
269 _SV_HEAD(XINVLIST*); /* pointer to xpvinvlist body */
270 _SV_HEAD_UNION;
271};
272
30153bd2 273#undef _SV_HEAD
0f7b1ae0 274#undef _SV_HEAD_UNION /* ensure no pollution */
30153bd2 275
954c1994 276/*
3f620621 277=for apidoc_section $SV
ccfc67b7 278
954c1994 279=for apidoc Am|U32|SvREFCNT|SV* sv
cb198164
YO
280Returns the value of the object's reference count. Exposed
281to perl code via Internals::SvREFCNT().
954c1994 282
3f2f854a 283=for apidoc SvREFCNT_inc
52f0fcf7
KW
284=for apidoc_item SvREFCNT_inc_NN
285=for apidoc_item SvREFCNT_inc_void
286=for apidoc_item |void|SvREFCNT_inc_void_NN|SV* sv
287=for apidoc_item |SV*|SvREFCNT_inc_simple|SV* sv
288=for apidoc_item |SV*|SvREFCNT_inc_simple_NN|SV* sv
289=for apidoc_item |void|SvREFCNT_inc_simple_void|SV* sv
290=for apidoc_item |void|SvREFCNT_inc_simple_void_NN|SV* sv
954c1994 291
52f0fcf7
KW
292These all increment the reference count of the given SV.
293The ones without C<void> in their names return the SV.
b37c2d43 294
52f0fcf7
KW
295C<SvREFCNT_inc> is the base operation; the rest are optimizations if various
296input constraints are known to be true; hence, all can be replaced with
297C<SvREFCNT_inc>.
298
299C<SvREFCNT_inc_NN> can only be used if you know C<sv> is not C<NULL>. Since we
300don't have to check the NULLness, it's faster and smaller.
b37c2d43 301
52f0fcf7 302C<SvREFCNT_inc_void> can only be used if you don't need the
b37c2d43
AL
303return value. The macro doesn't need to return a meaningful value.
304
52f0fcf7
KW
305C<SvREFCNT_inc_void_NN> can only be used if you both don't need the return
306value, and you know that C<sv> is not C<NULL>. The macro doesn't need to
307return a meaningful value, or check for NULLness, so it's smaller and faster.
b37c2d43 308
52f0fcf7 309C<SvREFCNT_inc_simple> can only be used with expressions without side
4ea561bc 310effects. Since we don't have to store a temporary value, it's faster.
b37c2d43 311
52f0fcf7
KW
312C<SvREFCNT_inc_simple_NN> can only be used with expressions without side
313effects and you know C<sv> is not C<NULL>. Since we don't have to store a
314temporary value, nor check for NULLness, it's faster and smaller.
b37c2d43 315
52f0fcf7
KW
316C<SvREFCNT_inc_simple_void> can only be used with expressions without side
317effects and you don't need the return value.
b37c2d43 318
52f0fcf7
KW
319C<SvREFCNT_inc_simple_void_NN> can only be used with expressions without side
320effects, you don't need the return value, and you know C<sv> is not C<NULL>.
b37c2d43 321
3f2f854a 322=for apidoc SvREFCNT_dec
b29c03ae 323=for apidoc_item SvREFCNT_dec_NN
954c1994 324
b29c03ae
KW
325These decrement the reference count of the given SV.
326
327C<SvREFCNT_dec_NN> may only be used when C<sv> is known to not be C<NULL>.
4a9a56a7 328
954c1994 329=for apidoc Am|svtype|SvTYPE|SV* sv
fbe13c60 330Returns the type of the SV. See C<L</svtype>>.
954c1994
GS
331
332=for apidoc Am|void|SvUPGRADE|SV* sv|svtype type
333Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
fbe13c60 334perform the upgrade if necessary. See C<L</svtype>>.
954c1994
GS
335
336=cut
337*/
338
463ee0b2 339#define SvANY(sv) (sv)->sv_any
79072805 340#define SvFLAGS(sv) (sv)->sv_flags
aeea060c 341#define SvREFCNT(sv) (sv)->sv_refcnt
a863c7d1 342
c9182d9c 343#define SvREFCNT_inc(sv) Perl_SvREFCNT_inc(MUTABLE_SV(sv))
27669aa4 344#define SvREFCNT_inc_simple(sv) SvREFCNT_inc(sv)
c9182d9c
KW
345#define SvREFCNT_inc_NN(sv) Perl_SvREFCNT_inc_NN(MUTABLE_SV(sv))
346#define SvREFCNT_inc_void(sv) Perl_SvREFCNT_inc_void(MUTABLE_SV(sv))
8990e307 347
b37c2d43 348/* These guys don't need the curly blocks */
e638c624 349#define SvREFCNT_inc_simple_void(sv) STMT_START { if (sv) SvREFCNT(sv)++; } STMT_END
b1bc3f34
NC
350#define SvREFCNT_inc_simple_NN(sv) (++(SvREFCNT(sv)),MUTABLE_SV(sv))
351#define SvREFCNT_inc_void_NN(sv) (void)(++SvREFCNT(MUTABLE_SV(sv)))
352#define SvREFCNT_inc_simple_void_NN(sv) (void)(++SvREFCNT(MUTABLE_SV(sv)))
b37c2d43 353
c9182d9c
KW
354#define SvREFCNT_dec(sv) Perl_SvREFCNT_dec(aTHX_ MUTABLE_SV(sv))
355#define SvREFCNT_dec_NN(sv) Perl_SvREFCNT_dec_NN(aTHX_ MUTABLE_SV(sv))
a863c7d1 356
8990e307 357#define SVTYPEMASK 0xff
1fef4616 358#define SvTYPE(sv) ((svtype)((sv)->sv_flags & SVTYPEMASK))
79072805 359
0565a181
NC
360/* Sadly there are some parts of the core that have pointers to already-freed
361 SV heads, and rely on being able to tell that they are now free. So mark
362 them all by using a consistent macro. */
7667e7f1 363#define SvIS_FREED(sv) UNLIKELY(((sv)->sv_flags == SVTYPEMASK))
0565a181 364
24e08842
DM
365/* this is defined in this peculiar way to avoid compiler warnings.
366 * See the <20121213131428.GD1842@iabyn.com> thread in p5p */
463ea229 367#define SvUPGRADE(sv, mt) \
24e08842 368 ((void)(SvTYPE(sv) >= (mt) || (sv_upgrade(sv, mt),1)))
79072805 369
3f7ef1d4
NC
370#define SVf_IOK 0x00000100 /* has valid public integer value */
371#define SVf_NOK 0x00000200 /* has valid public numeric value */
372#define SVf_POK 0x00000400 /* has valid public pointer value */
373#define SVf_ROK 0x00000800 /* has a valid reference pointer */
374
375#define SVp_IOK 0x00001000 /* has valid non-public integer value */
376#define SVp_NOK 0x00002000 /* has valid non-public numeric value */
377#define SVp_POK 0x00004000 /* has valid non-public pointer value */
9a70c74b 378#define SVp_SCREAM 0x00008000 /* currently unused on plain scalars */
2e5b91de
NC
379#define SVphv_CLONEABLE SVp_SCREAM /* PVHV (stashes) clone its objects */
380#define SVpgv_GP SVp_SCREAM /* GV has a valid GP */
1ccdb730 381#define SVprv_PCS_IMPORTED SVp_SCREAM /* RV is a proxy for a constant
1f4fbd3b
MS
382 subroutine in another package. Set the
383 GvIMPORTED_CV_on() if it needs to be
384 expanded to a real GV */
cc25b9e2
DM
385
386/* SVf_PROTECT is what SVf_READONLY should have been: i.e. modifying
387 * this SV is completely illegal. However, SVf_READONLY (via
388 * Internals::SvREADONLY()) has come to be seen as a flag that can be
389 * temporarily set and unset by the user to indicate e.g. whether a hash
390 * is "locked". Now, Hash::Util et al only set SVf_READONLY, while core
391 * sets both (SVf_READONLY|SVf_PROTECT) to indicate both to core and user
392 * code that this SV should not be messed with.
393 */
fd01b4b7 394#define SVf_PROTECT 0x00010000 /* very read-only */
c0683843 395#define SVs_PADTMP 0x00020000 /* in use as tmp */
c0683843 396#define SVs_PADSTALE 0x00040000 /* lexical has gone out of scope;
1f4fbd3b 397 only used when !PADTMP */
2c39754a 398#define SVs_TEMP 0x00080000 /* mortal (implies string is stealable) */
3f7ef1d4
NC
399#define SVs_OBJECT 0x00100000 /* is "blessed" */
400#define SVs_GMG 0x00200000 /* has magical get method */
401#define SVs_SMG 0x00400000 /* has magical set method */
402#define SVs_RMG 0x00800000 /* has random magical methods */
403
fea3622c 404#define SVf_FAKE 0x01000000 /* 0: glob is just a copy
1f4fbd3b
MS
405 1: SV head arena wasn't malloc()ed
406 2: For PVCV, whether CvUNIQUE(cv)
407 refers to an eval or once only
408 [CvEVAL(cv), CvSPECIAL(cv)]
0f94cb1f 409 3: HV: informally reserved by DAPM
df6b4bd5
DM
410 for vtables
411 4: Together with other flags (or
412 lack thereof) indicates a regex,
413 including PVLV-as-regex. See
414 isREGEXP().
415 */
3f7ef1d4 416#define SVf_OOK 0x02000000 /* has valid offset value. For a PVHV this
1f4fbd3b
MS
417 means that a hv_aux struct is present
418 after the main array */
3f7ef1d4 419#define SVf_BREAK 0x04000000 /* refcnt is artificially low - used by
1f4fbd3b
MS
420 SVs in final arena cleanup.
421 Set in S_regtry on PL_reg_curpm, so that
422 perl_destruct will skip it.
a5f48505
DM
423 Used for mark and sweep by OP_AASSIGN
424 */
3f7ef1d4 425#define SVf_READONLY 0x08000000 /* may not be modified */
8990e307 426
a0d0e21e 427
8990e307 428
5bc28da9 429
a623f893 430#define SVf_THINKFIRST (SVf_READONLY|SVf_PROTECT|SVf_ROK|SVf_FAKE \
1f4fbd3b 431 |SVs_RMG|SVf_IsCOW)
5bc28da9 432
a0d0e21e 433#define SVf_OK (SVf_IOK|SVf_NOK|SVf_POK|SVf_ROK| \
1f4fbd3b 434 SVp_IOK|SVp_NOK|SVp_POK|SVpgv_GP)
a0d0e21e 435
7a77f1af 436#define PRIVSHIFT 4 /* (SVp_?OK >> PRIVSHIFT) == SVf_?OK */
8990e307 437
a3815e44 438/* SVf_AMAGIC means that the stash *may* have overload methods. It's
d3d326f2
DM
439 * set each time a function is compiled into a stash, and is reset by the
440 * overload code when called for the first time and finds that there are
441 * no overload methods. Note that this used to be set on the object; but
442 * is now only set on stashes.
443 */
cd028baa 444#define SVf_AMAGIC 0x10000000 /* has magical overloaded methods */
45eaf8af 445#define SVf_IsCOW 0x10000000 /* copy on write (shared hash key if
1f4fbd3b 446 SvLEN == 0) */
70bc21b7 447
44b2d6d6
FC
448/* Ensure this value does not clash with the GV_ADD* flags in gv.h, or the
449 CV_CKPROTO_* flags in op.c, or the padadd_* flags in pad.h: */
cd028baa 450#define SVf_UTF8 0x20000000 /* SvPV is UTF-8 encoded
1f4fbd3b
MS
451 This is also set on RVs whose overloaded
452 stringification is UTF-8. This might
453 only happen as a side effect of SvPV() */
70bc21b7
DM
454/* PVHV */
455#define SVphv_SHAREKEYS 0x20000000 /* PVHV keys live on shared string table */
8990e307 456
2e9f07a2
NC
457/* PVAV could probably use 0x2000000 without conflict. I assume that PVFM can
458 be UTF-8 encoded, and PVCVs could well have UTF-8 prototypes. PVIOs haven't
459 been restructured, so sometimes get used as string buffers. */
460
70bc21b7
DM
461
462/* Some private flags. */
463
e1dcbbca 464
26a32e18 465/* PVAV */
3f7ef1d4 466#define SVpav_REAL 0x40000000 /* free old entries */
26a32e18 467/* PVHV */
3f7ef1d4 468#define SVphv_LAZYDEL 0x40000000 /* entry in xhv_eiter must be deleted */
25da4f38 469
26a32e18 470/* IV, PVIV, PVNV, PVMG, PVGV and (I assume) PVLV */
3f7ef1d4 471#define SVf_IVisUV 0x80000000 /* use XPVUV instead of XPVIV */
26a32e18 472/* PVAV */
3f7ef1d4 473#define SVpav_REIFY 0x80000000 /* can become real */
26a32e18 474/* PVHV */
3f7ef1d4 475#define SVphv_HASKFLAGS 0x80000000 /* keys have flag byte after hash */
26a32e18 476/* RV upwards. However, SVf_ROK and SVp_IOK are exclusive */
3f7ef1d4 477#define SVprv_WEAKREF 0x80000000 /* Weak reference */
d3ce79bd 478/* pad name vars only */
810b8aa5 479
6e128786
NC
480#define _XPV_HEAD \
481 HV* xmg_stash; /* class package */ \
482 union _xmgu xmg_u; \
8de47657 483 STRLEN xpv_cur; /* length of svu_pv as a C string */ \
8d919b0a 484 union { \
1f4fbd3b 485 STRLEN xpvlenu_len; /* allocated size */ \
df6b4bd5 486 struct regexp* xpvlenu_rx; /* regex when SV body is XPVLV */ \
1f4fbd3b 487 } xpv_len_u
8d919b0a
FC
488
489#define xpv_len xpv_len_u.xpvlenu_len
bb02a38f 490
20f4945e
MHM
491union _xnvu {
492 NV xnv_nv; /* numeric value, if any */
493 HV * xgv_stash;
9420b268 494 line_t xnv_lines; /* used internally by S_scan_subst() */
b4204fb6 495 bool xnv_bm_tail; /* an SvVALID (BM) SV has an implicit "\n" */
20f4945e
MHM
496};
497
498union _xivu {
499 IV xivu_iv; /* integer value */
20f4945e 500 UV xivu_uv;
20f4945e 501 HEK * xivu_namehek; /* xpvlv, xpvgv: GvNAME */
6432a58a 502 bool xivu_eval_seen; /* used internally by S_scan_subst() */
b4204fb6 503
20f4945e
MHM
504};
505
506union _xmgu {
507 MAGIC* xmg_magic; /* linked list of magicalness */
5bec93be 508 STRLEN xmg_hash_index; /* used while freeing hash entries */
9b7476d7 509};
11ca45c0 510
79072805 511struct xpv {
20f4945e 512 _XPV_HEAD;
79072805
LW
513};
514
515struct xpviv {
20f4945e
MHM
516 _XPV_HEAD;
517 union _xivu xiv_u;
79072805
LW
518};
519
311a25d9
NC
520#define xiv_iv xiv_u.xivu_iv
521
ff68c719 522struct xpvuv {
20f4945e
MHM
523 _XPV_HEAD;
524 union _xivu xuv_u;
ff68c719
PP
525};
526
20f4945e 527#define xuv_uv xuv_u.xivu_uv
311a25d9 528
79072805 529struct xpvnv {
20f4945e
MHM
530 _XPV_HEAD;
531 union _xivu xiv_u;
6e128786 532 union _xnvu xnv_u;
79072805
LW
533};
534
3cd3be43 535/* This structure must match the beginning of struct xpvhv in hv.h. */
79072805 536struct xpvmg {
20f4945e 537 _XPV_HEAD;
6e128786
NC
538 union _xivu xiv_u;
539 union _xnvu xnv_u;
79072805
LW
540};
541
542struct xpvlv {
20f4945e 543 _XPV_HEAD;
6e128786
NC
544 union _xivu xiv_u;
545 union _xnvu xnv_u;
bbfdc870 546 union {
1f4fbd3b
MS
547 STRLEN xlvu_targoff;
548 SSize_t xlvu_stargoff;
bbfdc870 549 } xlv_targoff_u;
79072805
LW
550 STRLEN xlv_targlen;
551 SV* xlv_targ;
dd28f7bb 552 char xlv_type; /* k=keys .=pos x=substr v=vec /=join/re
1f4fbd3b 553 * y=alem/helem/iter t=tie T=tied HE */
1b92e694
DM
554 char xlv_flags; /* 1 = negative offset 2 = negative len
555 4 = out of range (vec) */
79072805
LW
556};
557
bbfdc870
FC
558#define xlv_targoff xlv_targoff_u.xlvu_targoff
559
d361b004
KW
560struct xpvinvlist {
561 _XPV_HEAD;
da62e549
KW
562 IV prev_index; /* caches result of previous invlist_search() */
563 STRLEN iterator; /* Stores where we are in iterating */
564 bool is_offset; /* The data structure for all inversion lists
565 begins with an element for code point U+0000.
566 If this bool is set, the actual list contains
567 that 0; otherwise, the list actually begins
568 with the following element. Thus to invert
569 the list, merely toggle this flag */
d361b004
KW
570};
571
a5c7cb08
DM
572/* This structure works in 2 ways - regular scalar, or GV with GP */
573
79072805 574struct xpvgv {
20f4945e 575 _XPV_HEAD;
6e128786
NC
576 union _xivu xiv_u;
577 union _xnvu xnv_u;
79072805
LW
578};
579
51c78f1b 580typedef U32 cv_flags_t;
77a005ab 581
20f4945e
MHM
582#define _XPVCV_COMMON \
583 HV * xcv_stash; \
584 union { \
1f4fbd3b
MS
585 OP * xcv_start; \
586 ANY xcv_xsubany; \
20f4945e
MHM
587 } xcv_start_u; \
588 union { \
1f4fbd3b
MS
589 OP * xcv_root; \
590 void (*xcv_xsub) (pTHX_ CV*); \
20f4945e 591 } xcv_root_u; \
b290562e 592 union { \
1f4fbd3b
MS
593 GV * xcv_gv; \
594 HEK * xcv_hek; \
b290562e 595 } xcv_gv_u; \
20f4945e 596 char * xcv_file; \
eacbb379 597 union { \
1f4fbd3b
MS
598 PADLIST * xcv_padlist; \
599 void * xcv_hscxt; \
eacbb379 600 } xcv_padlist_u; \
20f4945e
MHM
601 CV * xcv_outside; \
602 U32 xcv_outside_seq; /* the COP sequence (at the point of our \
1f4fbd3b
MS
603 * compilation) in the lexically enclosing \
604 * sub */ \
8de47657
FC
605 cv_flags_t xcv_flags; \
606 I32 xcv_depth /* >= 2 indicates recursive call */
8990e307 607
0d856a3a
FC
608/* This structure must match XPVCV in cv.h */
609
20f4945e
MHM
610struct xpvfm {
611 _XPV_HEAD;
20f4945e 612 _XPVCV_COMMON;
79072805
LW
613};
614
167f2c4d 615
8990e307 616struct xpvio {
20f4945e 617 _XPV_HEAD;
6e128786 618 union _xivu xiv_u;
6f7e8353
NC
619 /* ifp and ofp are normally the same, but sockets need separate streams */
620 PerlIO * xio_ofp;
c951e2ad
NC
621 /* Cray addresses everything by word boundaries (64 bits) and
622 * code and data pointers cannot be mixed (which is exactly what
623 * Perl_filter_add() tries to do with the dirp), hence the
624 * following union trick (as suggested by Gurusamy Sarathy).
625 * For further information see Geir Johansen's problem report
4fe48737 626 * titled [ID 20000612.002 (#3366)] Perl problem on Cray system
c951e2ad
NC
627 * The any pointer (known as IoANY()) will also be a good place
628 * to hang any IO disciplines to.
629 */
630 union {
1f4fbd3b
MS
631 DIR * xiou_dirp; /* for opendir, readdir, etc */
632 void * xiou_any; /* for alignment */
c951e2ad
NC
633 } xio_dirpu;
634 /* IV xio_lines is now in IVX $. */
635 IV xio_page; /* $% */
636 IV xio_page_len; /* $= */
637 IV xio_lines_left; /* $- */
638 char * xio_top_name; /* $^ */
639 GV * xio_top_gv; /* $^ */
640 char * xio_fmt_name; /* $~ */
641 GV * xio_fmt_gv; /* $~ */
642 char * xio_bottom_name;/* $^B */
643 GV * xio_bottom_gv; /* $^B */
644 char xio_type;
645 U8 xio_flags;
8990e307 646};
167f2c4d 647
4755096e
GS
648#define xio_dirp xio_dirpu.xiou_dirp
649#define xio_any xio_dirpu.xiou_any
8990e307 650
e0c19803
GS
651#define IOf_ARGV 1 /* this fp iterates over ARGV */
652#define IOf_START 2 /* check for null ARGV and substitute '-' */
653#define IOf_FLUSH 4 /* this fp wants a flush after write op */
654#define IOf_DIDTOP 8 /* just did top of form */
655#define IOf_UNTAINT 16 /* consider this fp (and its data) "safe" */
656#define IOf_NOLINE 32 /* slurped a pseudo-line from empty file */
5bb89d25 657#define IOf_FAKE_DIRP 64 /* xio_dirp is fake (source filters kludge)
1f4fbd3b 658 Also, when this is set, SvPVX() is valid */
8990e307 659
ed6116ce
LW
660/* The following macros define implementation-independent predicates on SVs. */
661
954c1994 662/*
fbf9f983
RGS
663=for apidoc Am|U32|SvNIOK|SV* sv
664Returns a U32 value indicating whether the SV contains a number, integer or
954c1994
GS
665double.
666
fbf9f983
RGS
667=for apidoc Am|U32|SvNIOKp|SV* sv
668Returns a U32 value indicating whether the SV contains a number, integer or
fe749c9a 669double. Checks the B<private> setting. Use C<SvNIOK> instead.
954c1994
GS
670
671=for apidoc Am|void|SvNIOK_off|SV* sv
672Unsets the NV/IV status of an SV.
673
fbf9f983 674=for apidoc Am|U32|SvOK|SV* sv
72d33970 675Returns a U32 value indicating whether the value is defined. This is
c0b6140e 676only meaningful for scalars.
954c1994 677
fbf9f983
RGS
678=for apidoc Am|U32|SvIOKp|SV* sv
679Returns a U32 value indicating whether the SV contains an integer. Checks
fe749c9a 680the B<private> setting. Use C<SvIOK> instead.
954c1994 681
fbf9f983
RGS
682=for apidoc Am|U32|SvNOKp|SV* sv
683Returns a U32 value indicating whether the SV contains a double. Checks the
fe749c9a 684B<private> setting. Use C<SvNOK> instead.
954c1994 685
fbf9f983
RGS
686=for apidoc Am|U32|SvPOKp|SV* sv
687Returns a U32 value indicating whether the SV contains a character string.
fe749c9a 688Checks the B<private> setting. Use C<SvPOK> instead.
954c1994 689
fbf9f983
RGS
690=for apidoc Am|U32|SvIOK|SV* sv
691Returns a U32 value indicating whether the SV contains an integer.
954c1994
GS
692
693=for apidoc Am|void|SvIOK_on|SV* sv
694Tells an SV that it is an integer.
695
696=for apidoc Am|void|SvIOK_off|SV* sv
697Unsets the IV status of an SV.
698
699=for apidoc Am|void|SvIOK_only|SV* sv
796b6530 700Tells an SV that it is an integer and disables all other C<OK> bits.
954c1994 701
e331fc52 702=for apidoc Am|void|SvIOK_only_UV|SV* sv
796b6530 703Tells an SV that it is an unsigned integer and disables all other C<OK> bits.
e331fc52 704
12fa07df 705=for apidoc Am|bool|SvIOK_UV|SV* sv
a6ceea06
KW
706Returns a boolean indicating whether the SV contains an integer that must be
707interpreted as unsigned. A non-negative integer whose value is within the
a3815e44 708range of both an IV and a UV may be flagged as either C<SvUOK> or C<SvIOK>.
e331fc52 709
fbf9f983 710=for apidoc Am|bool|SvUOK|SV* sv
a6ceea06
KW
711Returns a boolean indicating whether the SV contains an integer that must be
712interpreted as unsigned. A non-negative integer whose value is within the
a3815e44 713range of both an IV and a UV may be flagged as either C<SvUOK> or C<SvIOK>.
28e5dec8 714
12fa07df 715=for apidoc Am|bool|SvIOK_notUV|SV* sv
d1be9408 716Returns a boolean indicating whether the SV contains a signed integer.
e331fc52 717
fbf9f983
RGS
718=for apidoc Am|U32|SvNOK|SV* sv
719Returns a U32 value indicating whether the SV contains a double.
954c1994
GS
720
721=for apidoc Am|void|SvNOK_on|SV* sv
722Tells an SV that it is a double.
723
724=for apidoc Am|void|SvNOK_off|SV* sv
725Unsets the NV status of an SV.
726
727=for apidoc Am|void|SvNOK_only|SV* sv
728Tells an SV that it is a double and disables all other OK bits.
729
fbf9f983
RGS
730=for apidoc Am|U32|SvPOK|SV* sv
731Returns a U32 value indicating whether the SV contains a character
954c1994
GS
732string.
733
734=for apidoc Am|void|SvPOK_on|SV* sv
735Tells an SV that it is a string.
736
737=for apidoc Am|void|SvPOK_off|SV* sv
738Unsets the PV status of an SV.
739
740=for apidoc Am|void|SvPOK_only|SV* sv
796b6530 741Tells an SV that it is a string and disables all other C<OK> bits.
1e54db1a 742Will also turn off the UTF-8 status.
954c1994 743
b0f01acb
JP
744=for apidoc Am|bool|SvVOK|SV* sv
745Returns a boolean indicating whether the SV contains a v-string.
746
fbf9f983 747=for apidoc Am|U32|SvOOK|SV* sv
69240efd
NC
748Returns a U32 indicating whether the pointer to the string buffer is offset.
749This hack is used internally to speed up removal of characters from the
de343f44 750beginning of a C<L</SvPV>>. When C<SvOOK> is true, then the start of the
796b6530
KW
751allocated string buffer is actually C<SvOOK_offset()> bytes before C<SvPVX>.
752This offset used to be stored in C<SvIVX>, but is now stored within the spare
69240efd 753part of the buffer.
954c1994 754
fbf9f983 755=for apidoc Am|U32|SvROK|SV* sv
954c1994
GS
756Tests if the SV is an RV.
757
758=for apidoc Am|void|SvROK_on|SV* sv
759Tells an SV that it is an RV.
760
761=for apidoc Am|void|SvROK_off|SV* sv
762Unsets the RV status of an SV.
763
764=for apidoc Am|SV*|SvRV|SV* sv
765Dereferences an RV to return the SV.
766
767=for apidoc Am|IV|SvIVX|SV* sv
645c22ef 768Returns the raw value in the SV's IV slot, without checks or conversions.
796b6530 769Only use when you are sure C<SvIOK> is true. See also C<L</SvIV>>.
954c1994
GS
770
771=for apidoc Am|UV|SvUVX|SV* sv
645c22ef 772Returns the raw value in the SV's UV slot, without checks or conversions.
796b6530 773Only use when you are sure C<SvIOK> is true. See also C<L</SvUV>>.
954c1994 774
b7822a6d
KW
775=for apidoc AmD|UV|SvUVXx|SV* sv
776This is an unnecessary synonym for L</SvUVX>
777
954c1994 778=for apidoc Am|NV|SvNVX|SV* sv
645c22ef 779Returns the raw value in the SV's NV slot, without checks or conversions.
796b6530 780Only use when you are sure C<SvNOK> is true. See also C<L</SvNV>>.
954c1994
GS
781
782=for apidoc Am|char*|SvPVX|SV* sv
c2b527b3
KW
783=for apidoc_item |char*|SvPVXx|SV* sv
784=for apidoc_item |const char*|SvPVX_const|SV* sv
785=for apidoc_item |char*|SvPVX_mutable|SV* sv
786
787These return a pointer to the physical string in the SV. The SV must contain a
788string. Prior to 5.9.3 it is not safe to execute these unless the SV's
796b6530 789type >= C<SVt_PV>.
954c1994 790
c2b527b3 791These are also used to store the name of an autoloaded subroutine in an XS
5b36e945 792AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>.
89fc9e2a 793
c2b527b3
KW
794C<SvPVXx> is identical to C<SvPVX>.
795
796C<SvPVX_mutable> is merely a synonym for C<SvPVX>, but its name emphasizes that
797the string is modifiable by the caller.
798
799C<SvPVX_const> differs in that the return value has been cast so that the
800compiler will complain if you were to try to modify the contents of the string,
801(unless you cast away const yourself).
802
954c1994 803=for apidoc Am|STRLEN|SvCUR|SV* sv
3c3f883d
FG
804Returns the length, in bytes, of the PV inside the SV.
805Note that this may not match Perl's C<length>; for that, use
806C<sv_len_utf8(sv)>. See C<L</SvLEN>> also.
954c1994
GS
807
808=for apidoc Am|STRLEN|SvLEN|SV* sv
659239a4 809Returns the size of the string buffer in the SV, not including any part
fbe13c60 810attributable to C<SvOOK>. See C<L</SvCUR>>.
954c1994
GS
811
812=for apidoc Am|char*|SvEND|SV* sv
f990ea3e
FC
813Returns a pointer to the spot just after the last character in
814the string which is in the SV, where there is usually a trailing
417b32ce 815C<NUL> character (even though Perl scalars do not strictly require it).
796b6530 816See C<L</SvCUR>>. Access the character as C<*(SvEND(sv))>.
954c1994 817
f990ea3e
FC
818Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to
819unallocated memory.
820
954c1994
GS
821=for apidoc Am|HV*|SvSTASH|SV* sv
822Returns the stash of the SV.
823
672994ce 824=for apidoc Am|void|SvIV_set|SV* sv|IV val
20799e15
SP
825Set the value of the IV pointer in sv to val. It is possible to perform
826the same function of this macro with an lvalue assignment to C<SvIVX>.
1f4fbd3b 827With future Perls, however, it will be more efficient to use
20799e15 828C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
672994ce
SP
829
830=for apidoc Am|void|SvNV_set|SV* sv|NV val
796b6530 831Set the value of the NV pointer in C<sv> to val. See C<L</SvIV_set>>.
672994ce
SP
832
833=for apidoc Am|void|SvPV_set|SV* sv|char* val
f2979eac
DD
834This is probably not what you want to use, you probably wanted
835L</sv_usepvn_flags> or L</sv_setpvn> or L</sv_setpvs>.
235fc044 836
f2979eac 837Set the value of the PV pointer in C<sv> to the Perl allocated
fbe13c60 838C<NUL>-terminated string C<val>. See also C<L</SvIV_set>>.
f2979eac
DD
839
840Remember to free the previous PV buffer. There are many things to check.
235fc044
FC
841Beware that the existing pointer may be involved in copy-on-write or other
842mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
796b6530 843C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
d54acd4f
KW
844modification is safe. Then finally, if it is not a COW, call
845C<L</SvPV_free>> to free the previous PV buffer.
672994ce
SP
846
847=for apidoc Am|void|SvUV_set|SV* sv|UV val
796b6530 848Set the value of the UV pointer in C<sv> to val. See C<L</SvIV_set>>.
672994ce
SP
849
850=for apidoc Am|void|SvRV_set|SV* sv|SV* val
796b6530 851Set the value of the RV pointer in C<sv> to val. See C<L</SvIV_set>>.
672994ce
SP
852
853=for apidoc Am|void|SvMAGIC_set|SV* sv|MAGIC* val
796b6530 854Set the value of the MAGIC pointer in C<sv> to val. See C<L</SvIV_set>>.
672994ce 855
b6f4de24 856=for apidoc Am|void|SvSTASH_set|SV* sv|HV* val
796b6530 857Set the value of the STASH pointer in C<sv> to val. See C<L</SvIV_set>>.
672994ce 858
954c1994 859=for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len
3c3f883d
FG
860Sets the current length, in bytes, of the C string which is in the SV.
861See C<L</SvCUR>> and C<SvIV_set>>.
672994ce
SP
862
863=for apidoc Am|void|SvLEN_set|SV* sv|STRLEN len
0ff57aee 864Set the size of the string buffer for the SV. See C<L</SvLEN>>.
954c1994
GS
865
866=cut
867*/
868
79072805 869#define SvNIOK(sv) (SvFLAGS(sv) & (SVf_IOK|SVf_NOK))
748a9306 870#define SvNIOKp(sv) (SvFLAGS(sv) & (SVp_IOK|SVp_NOK))
a0d0e21e 871#define SvNIOK_off(sv) (SvFLAGS(sv) &= ~(SVf_IOK|SVf_NOK| \
1f4fbd3b 872 SVp_IOK|SVp_NOK|SVf_IVisUV))
79072805 873
c7724415
FC
874#define assert_not_ROK(sv) assert_(!SvROK(sv) || !SvRV(sv))
875#define assert_not_glob(sv) assert_(!isGV_with_GP(sv))
906ed6d6 876
df6b4bd5 877#define SvOK(sv) (SvFLAGS(sv) & SVf_OK)
f7877b28 878#define SvOK_off(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
1f4fbd3b
MS
879 SvFLAGS(sv) &= ~(SVf_OK| \
880 SVf_IVisUV|SVf_UTF8), \
881 SvOOK_off(sv))
54866b45 882#define SvOK_off_exc_UV(sv) (assert_not_ROK(sv) \
1f4fbd3b
MS
883 SvFLAGS(sv) &= ~(SVf_OK| \
884 SVf_UTF8), \
885 SvOOK_off(sv))
79072805 886
8990e307
LW
887#define SvOKp(sv) (SvFLAGS(sv) & (SVp_IOK|SVp_NOK|SVp_POK))
888#define SvIOKp(sv) (SvFLAGS(sv) & SVp_IOK)
b326ddff 889#define SvIOKp_on(sv) (assert_not_glob(sv) \
1f4fbd3b 890 SvFLAGS(sv) |= SVp_IOK)
8990e307 891#define SvNOKp(sv) (SvFLAGS(sv) & SVp_NOK)
f7877b28 892#define SvNOKp_on(sv) (assert_not_glob(sv) SvFLAGS(sv) |= SVp_NOK)
8990e307 893#define SvPOKp(sv) (SvFLAGS(sv) & SVp_POK)
f7877b28 894#define SvPOKp_on(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
1f4fbd3b 895 SvFLAGS(sv) |= SVp_POK)
463ee0b2 896
79072805 897#define SvIOK(sv) (SvFLAGS(sv) & SVf_IOK)
b326ddff 898#define SvIOK_on(sv) (assert_not_glob(sv) \
1f4fbd3b 899 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
25da4f38 900#define SvIOK_off(sv) (SvFLAGS(sv) &= ~(SVf_IOK|SVp_IOK|SVf_IVisUV))
0c34ef67 901#define SvIOK_only(sv) (SvOK_off(sv), \
1f4fbd3b 902 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
f7877b28 903#define SvIOK_only_UV(sv) (assert_not_glob(sv) SvOK_off_exc_UV(sv), \
1f4fbd3b 904 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
70401c6b 905
25da4f38 906#define SvIOK_UV(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV)) \
1f4fbd3b 907 == (SVf_IOK|SVf_IVisUV))
28e5dec8 908#define SvUOK(sv) SvIOK_UV(sv)
25da4f38 909#define SvIOK_notUV(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV)) \
1f4fbd3b 910 == SVf_IOK)
25da4f38
IZ
911
912#define SvIsUV(sv) (SvFLAGS(sv) & SVf_IVisUV)
913#define SvIsUV_on(sv) (SvFLAGS(sv) |= SVf_IVisUV)
914#define SvIsUV_off(sv) (SvFLAGS(sv) &= ~SVf_IVisUV)
79072805
LW
915
916#define SvNOK(sv) (SvFLAGS(sv) & SVf_NOK)
f7877b28 917#define SvNOK_on(sv) (assert_not_glob(sv) \
1f4fbd3b 918 SvFLAGS(sv) |= (SVf_NOK|SVp_NOK))
8990e307 919#define SvNOK_off(sv) (SvFLAGS(sv) &= ~(SVf_NOK|SVp_NOK))
0c34ef67 920#define SvNOK_only(sv) (SvOK_off(sv), \
1f4fbd3b 921 SvFLAGS(sv) |= (SVf_NOK|SVp_NOK))
79072805 922
914184e1 923/*
fbf9f983 924=for apidoc Am|U32|SvUTF8|SV* sv
3c813ed0
KW
925Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up
926properly, this indicates whether or not the SV contains UTF-8 encoded data.
de343f44 927You should use this I<after> a call to C<L</SvPV>> or one of its variants, in
fd142383 928case any call to string overloading updates the internal flag.
914184e1 929
119bc988
KW
930If you want to take into account the L<bytes> pragma, use C<L</DO_UTF8>>
931instead.
932
914184e1 933=for apidoc Am|void|SvUTF8_on|SV *sv
1e54db1a 934Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
d5ce4a7c 935Do not use frivolously.
914184e1
JH
936
937=for apidoc Am|void|SvUTF8_off|SV *sv
3c813ed0
KW
938Unsets the UTF-8 status of an SV (the data is not changed, just the flag).
939Do not use frivolously.
914184e1
JH
940
941=for apidoc Am|void|SvPOK_only_UTF8|SV* sv
796b6530 942Tells an SV that it is a string and disables all other C<OK> bits,
1e54db1a 943and leaves the UTF-8 status as it was.
f1a1024e 944
914184e1
JH
945=cut
946 */
947
7a5fd60d
NC
948/* Ensure the return value of this macro does not clash with the GV_ADD* flags
949in gv.h: */
a7cb1f99
GS
950#define SvUTF8(sv) (SvFLAGS(sv) & SVf_UTF8)
951#define SvUTF8_on(sv) (SvFLAGS(sv) |= (SVf_UTF8))
952#define SvUTF8_off(sv) (SvFLAGS(sv) &= ~(SVf_UTF8))
5bc28da9 953
79072805 954#define SvPOK(sv) (SvFLAGS(sv) & SVf_POK)
f7877b28 955#define SvPOK_on(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
1f4fbd3b 956 SvFLAGS(sv) |= (SVf_POK|SVp_POK))
8990e307 957#define SvPOK_off(sv) (SvFLAGS(sv) &= ~(SVf_POK|SVp_POK))
f7877b28 958#define SvPOK_only(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
1f4fbd3b
MS
959 SvFLAGS(sv) &= ~(SVf_OK| \
960 SVf_IVisUV|SVf_UTF8), \
961 SvFLAGS(sv) |= (SVf_POK|SVp_POK))
f7877b28 962#define SvPOK_only_UTF8(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
1f4fbd3b
MS
963 SvFLAGS(sv) &= ~(SVf_OK| \
964 SVf_IVisUV), \
965 SvFLAGS(sv) |= (SVf_POK|SVp_POK))
79072805 966
4f2da183 967#define SvVOK(sv) (SvMAGICAL(sv) \
1f4fbd3b 968 && mg_find(sv,PERL_MAGIC_vstring))
c4d5dfab
KW
969/*
970=for apidoc Am|MAGIC*|SvVSTRING_mg|SV * sv
971
972Returns the vstring magic, or NULL if none
973
974=cut
975*/
b0a11fe1 976#define SvVSTRING_mg(sv) (SvMAGICAL(sv) \
1f4fbd3b 977 ? mg_find(sv,PERL_MAGIC_vstring) : NULL)
b0a11fe1 978
79072805 979#define SvOOK(sv) (SvFLAGS(sv) & SVf_OOK)
a4f658f7 980#define SvOOK_on(sv) (SvFLAGS(sv) |= SVf_OOK)
13cc62f5
KW
981
982
983/*
984=for apidoc Am|void|SvOOK_off|SV * sv
985
986Remove any string offset.
987
988=cut
989*/
990
fa7a1e49 991#define SvOOK_off(sv) ((void)(SvOOK(sv) && (sv_backoff(sv),0)))
79072805 992
a0d0e21e
LW
993#define SvFAKE(sv) (SvFLAGS(sv) & SVf_FAKE)
994#define SvFAKE_on(sv) (SvFLAGS(sv) |= SVf_FAKE)
995#define SvFAKE_off(sv) (SvFLAGS(sv) &= ~SVf_FAKE)
996
ed6116ce 997#define SvROK(sv) (SvFLAGS(sv) & SVf_ROK)
a0d0e21e 998#define SvROK_on(sv) (SvFLAGS(sv) |= SVf_ROK)
dd2eae66 999#define SvROK_off(sv) (SvFLAGS(sv) &= ~(SVf_ROK))
79072805 1000
8990e307
LW
1001#define SvMAGICAL(sv) (SvFLAGS(sv) & (SVs_GMG|SVs_SMG|SVs_RMG))
1002#define SvMAGICAL_on(sv) (SvFLAGS(sv) |= (SVs_GMG|SVs_SMG|SVs_RMG))
1003#define SvMAGICAL_off(sv) (SvFLAGS(sv) &= ~(SVs_GMG|SVs_SMG|SVs_RMG))
79072805 1004
8990e307
LW
1005#define SvGMAGICAL(sv) (SvFLAGS(sv) & SVs_GMG)
1006#define SvGMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_GMG)
1007#define SvGMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_GMG)
ed6116ce 1008
8990e307
LW
1009#define SvSMAGICAL(sv) (SvFLAGS(sv) & SVs_SMG)
1010#define SvSMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_SMG)
1011#define SvSMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_SMG)
ed6116ce 1012
8990e307
LW
1013#define SvRMAGICAL(sv) (SvFLAGS(sv) & SVs_RMG)
1014#define SvRMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_RMG)
1015#define SvRMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_RMG)
ed6116ce 1016
a1cd65be 1017#define SvAMAGIC(sv) (SvROK(sv) && SvOBJECT(SvRV(sv)) && \
1f4fbd3b 1018 HvAMAGIC(SvSTASH(SvRV(sv))))
a0d0e21e 1019
0adc25b0
FC
1020/* To be used on the stashes themselves: */
1021#define HvAMAGIC(hv) (SvFLAGS(hv) & SVf_AMAGIC)
1022#define HvAMAGIC_on(hv) (SvFLAGS(hv) |= SVf_AMAGIC)
1023#define HvAMAGIC_off(hv) (SvFLAGS(hv) &=~ SVf_AMAGIC)
1024
4bac9ae4 1025
1078c6a2 1026/* "nog" means "doesn't have get magic" */
4bac9ae4
CS
1027#define SvPOK_nog(sv) ((SvFLAGS(sv) & (SVf_POK|SVs_GMG)) == SVf_POK)
1028#define SvIOK_nog(sv) ((SvFLAGS(sv) & (SVf_IOK|SVs_GMG)) == SVf_IOK)
1029#define SvUOK_nog(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV|SVs_GMG)) == (SVf_IOK|SVf_IVisUV))
1030#define SvNOK_nog(sv) ((SvFLAGS(sv) & (SVf_NOK|SVs_GMG)) == SVf_NOK)
1031#define SvNIOK_nog(sv) (SvNIOK(sv) && !(SvFLAGS(sv) & SVs_GMG))
1032
1033#define SvPOK_nogthink(sv) ((SvFLAGS(sv) & (SVf_POK|SVf_THINKFIRST|SVs_GMG)) == SVf_POK)
1034#define SvIOK_nogthink(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_THINKFIRST|SVs_GMG)) == SVf_IOK)
1035#define SvUOK_nogthink(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV|SVf_THINKFIRST|SVs_GMG)) == (SVf_IOK|SVf_IVisUV))
1036#define SvNOK_nogthink(sv) ((SvFLAGS(sv) & (SVf_NOK|SVf_THINKFIRST|SVs_GMG)) == SVf_NOK)
1037#define SvNIOK_nogthink(sv) (SvNIOK(sv) && !(SvFLAGS(sv) & (SVf_THINKFIRST|SVs_GMG)))
1038
1039#define SvPOK_utf8_nog(sv) ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVs_GMG)) == (SVf_POK|SVf_UTF8))
1040#define SvPOK_utf8_nogthink(sv) ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVf_THINKFIRST|SVs_GMG)) == (SVf_POK|SVf_UTF8))
1041
1042#define SvPOK_byte_nog(sv) ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVs_GMG)) == SVf_POK)
1043#define SvPOK_byte_nogthink(sv) ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVf_THINKFIRST|SVs_GMG)) == SVf_POK)
1044
8bb025ae
CS
1045#define SvPOK_pure_nogthink(sv) \
1046 ((SvFLAGS(sv) & (SVf_POK|SVf_IOK|SVf_NOK|SVf_ROK|SVpgv_GP|SVf_THINKFIRST|SVs_GMG)) == SVf_POK)
1047#define SvPOK_utf8_pure_nogthink(sv) \
1048 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVf_IOK|SVf_NOK|SVf_ROK|SVpgv_GP|SVf_THINKFIRST|SVs_GMG)) == (SVf_POK|SVf_UTF8))
1049#define SvPOK_byte_pure_nogthink(sv) \
1050 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVf_IOK|SVf_NOK|SVf_ROK|SVpgv_GP|SVf_THINKFIRST|SVs_GMG)) == SVf_POK)
1051
d34786ba 1052/*
458b44e7 1053=for apidoc Am|U32|SvGAMAGIC|SV* sv
d34786ba 1054
8554e7a0
FC
1055Returns true if the SV has get magic or
1056overloading. If either is true then
d34786ba 1057the scalar is active data, and has the potential to return a new value every
8554e7a0
FC
1058time it is accessed. Hence you must be careful to
1059only read it once per user logical operation and work
1060with that returned value. If neither is true then
d34786ba
NC
1061the scalar's value cannot change unless written to.
1062
1063=cut
1064*/
1065
dd2eae66 1066#define SvGAMAGIC(sv) (SvGMAGICAL(sv) || SvAMAGIC(sv))
1426bbf4 1067
9299023c 1068#define Gv_AMG(stash) \
1f4fbd3b
MS
1069 (HvNAME(stash) && Gv_AMupdate(stash,FALSE) \
1070 ? 1 \
1071 : (HvAMAGIC_off(stash), 0))
a0d0e21e 1072
810b8aa5 1073#define SvWEAKREF(sv) ((SvFLAGS(sv) & (SVf_ROK|SVprv_WEAKREF)) \
1f4fbd3b 1074 == (SVf_ROK|SVprv_WEAKREF))
810b8aa5
GS
1075#define SvWEAKREF_on(sv) (SvFLAGS(sv) |= (SVf_ROK|SVprv_WEAKREF))
1076#define SvWEAKREF_off(sv) (SvFLAGS(sv) &= ~(SVf_ROK|SVprv_WEAKREF))
1077
1ccdb730 1078#define SvPCS_IMPORTED(sv) ((SvFLAGS(sv) & (SVf_ROK|SVprv_PCS_IMPORTED)) \
1f4fbd3b 1079 == (SVf_ROK|SVprv_PCS_IMPORTED))
1ccdb730
NC
1080#define SvPCS_IMPORTED_on(sv) (SvFLAGS(sv) |= (SVf_ROK|SVprv_PCS_IMPORTED))
1081#define SvPCS_IMPORTED_off(sv) (SvFLAGS(sv) &= ~(SVf_ROK|SVprv_PCS_IMPORTED))
1082
a11eaecb
FC
1083/*
1084=for apidoc m|U32|SvTHINKFIRST|SV *sv
1085
796b6530
KW
1086A quick flag check to see whether an C<sv> should be passed to C<sv_force_normal>
1087to be "downgraded" before C<SvIVX> or C<SvPVX> can be modified directly.
a11eaecb 1088
796b6530
KW
1089For example, if your scalar is a reference and you want to modify the C<SvIVX>
1090slot, you can't just do C<SvROK_off>, as that will leak the referent.
a11eaecb
FC
1091
1092This is used internally by various sv-modifying functions, such as
ef058b33 1093C<sv_setsv>, C<sv_setiv> and C<sv_pvn_force>.
a11eaecb
FC
1094
1095One case that this does not handle is a gv without SvFAKE set. After
1096
1097 if (SvTHINKFIRST(gv)) sv_force_normal(gv);
1098
1099it will still be a gv.
1100
796b6530
KW
1101C<SvTHINKFIRST> sometimes produces false positives. In those cases
1102C<sv_force_normal> does nothing.
a11eaecb
FC
1103
1104=cut
1105*/
1106
a0d0e21e 1107#define SvTHINKFIRST(sv) (SvFLAGS(sv) & SVf_THINKFIRST)
ed6116ce 1108
c0683843
FC
1109#define SVs_PADMY 0
1110#define SvPADMY(sv) !(SvFLAGS(sv) & SVs_PADTMP)
145bf8ee
FC
1111#ifndef PERL_CORE
1112# define SvPADMY_on(sv) SvPADTMP_off(sv)
1113#endif
d9d18af6 1114
c0683843
FC
1115#define SvPADTMP(sv) (SvFLAGS(sv) & (SVs_PADTMP))
1116#define SvPADSTALE(sv) (SvFLAGS(sv) & (SVs_PADSTALE))
62bb6514 1117
145bf8ee
FC
1118#define SvPADTMP_on(sv) (SvFLAGS(sv) |= SVs_PADTMP)
1119#define SvPADTMP_off(sv) (SvFLAGS(sv) &= ~SVs_PADTMP)
c9182d9c
KW
1120#define SvPADSTALE_on(sv) Perl_SvPADSTALE_on(MUTABLE_SV(sv))
1121#define SvPADSTALE_off(sv) Perl_SvPADSTALE_off(MUTABLE_SV(sv))
ed6116ce 1122
8990e307
LW
1123#define SvTEMP(sv) (SvFLAGS(sv) & SVs_TEMP)
1124#define SvTEMP_on(sv) (SvFLAGS(sv) |= SVs_TEMP)
1125#define SvTEMP_off(sv) (SvFLAGS(sv) &= ~SVs_TEMP)
79072805 1126
8990e307
LW
1127#define SvOBJECT(sv) (SvFLAGS(sv) & SVs_OBJECT)
1128#define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT)
1129#define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT)
79072805 1130
cb198164
YO
1131/*
1132=for apidoc Am|U32|SvREADONLY|SV* sv
1133Returns true if the argument is readonly, otherwise returns false.
a3815e44 1134Exposed to perl code via Internals::SvREADONLY().
cb198164
YO
1135
1136=for apidoc Am|U32|SvREADONLY_on|SV* sv
1137Mark an object as readonly. Exactly what this means depends on the object
1138type. Exposed to perl code via Internals::SvREADONLY().
1139
1140=for apidoc Am|U32|SvREADONLY_off|SV* sv
1141Mark an object as not-readonly. Exactly what this mean depends on the
1142object type. Exposed to perl code via Internals::SvREADONLY().
1143
1144=cut
1145*/
1146
a623f893
FC
1147#define SvREADONLY(sv) (SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT))
1148#ifdef PERL_CORE
1149# define SvREADONLY_on(sv) (SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT))
1150# define SvREADONLY_off(sv) (SvFLAGS(sv) &=~(SVf_READONLY|SVf_PROTECT))
1151#else
1152# define SvREADONLY_on(sv) (SvFLAGS(sv) |= SVf_READONLY)
1153# define SvREADONLY_off(sv) (SvFLAGS(sv) &= ~SVf_READONLY)
1154#endif
79072805 1155
180488f8 1156#define SvSCREAM(sv) ((SvFLAGS(sv) & (SVp_SCREAM|SVp_POK)) == (SVp_SCREAM|SVp_POK))
8990e307
LW
1157#define SvSCREAM_on(sv) (SvFLAGS(sv) |= SVp_SCREAM)
1158#define SvSCREAM_off(sv) (SvFLAGS(sv) &= ~SVp_SCREAM)
79072805 1159
74e0ddf7
NC
1160#ifndef PERL_CORE
1161# define SvCOMPILED(sv) 0
1162# define SvCOMPILED_on(sv)
1163# define SvCOMPILED_off(sv)
1164#endif
79072805 1165
85ffbbb0 1166
041c1a23 1167#if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
e9726144 1168# define SvTAIL(sv) ({ const SV *const _svtail = (const SV *)(sv); \
1f4fbd3b
MS
1169 assert(SvTYPE(_svtail) != SVt_PVAV); \
1170 assert(SvTYPE(_svtail) != SVt_PVHV); \
1171 assert(!(SvFLAGS(_svtail) & (SVf_NOK|SVp_NOK))); \
1172 assert(SvVALID(_svtail)); \
b4204fb6 1173 ((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail; \
1f4fbd3b 1174 })
85efc3a5 1175#else
b4204fb6 1176# define SvTAIL(_svtail) (((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail)
85efc3a5 1177#endif
8990e307 1178
a5c7cb08
DM
1179/* Does the SV have a Boyer-Moore table attached as magic?
1180 * 'VALID' is a poor name, but is kept for historical reasons. */
1181#define SvVALID(_svvalid) ( \
4e8879f3
DM
1182 SvPOKp(_svvalid) \
1183 && SvSMAGICAL(_svvalid) \
a5c7cb08
DM
1184 && SvMAGIC(_svvalid) \
1185 && (SvMAGIC(_svvalid)->mg_type == PERL_MAGIC_bm \
1186 || mg_find(_svvalid, PERL_MAGIC_bm)) \
1187 )
1188
ed6116ce
LW
1189#define SvRVx(sv) SvRV(sv)
1190
f599b64b 1191#ifdef PERL_DEBUG_COW
8ed30cc1
DD
1192/* Need -0.0 for SvNVX to preserve IEEE FP "negative zero" because
1193 +0.0 + -0.0 => +0.0 but -0.0 + -0.0 => -0.0 */
771ba71a
NC
1194# define SvIVX(sv) (0 + ((XPVIV*) SvANY(sv))->xiv_iv)
1195# define SvUVX(sv) (0 + ((XPVUV*) SvANY(sv))->xuv_uv)
58430790 1196# define SvNVX(sv) (-0.0 + ((XPVNV*) SvANY(sv))->xnv_u.xnv_nv)
ac09da3b 1197# define SvRV(sv) (0 + (sv)->sv_u.svu_rv)
f19a12a3 1198# define SvRV_const(sv) (0 + (sv)->sv_u.svu_rv)
c0e1089a 1199/* Don't test the core XS code yet. */
771ba71a 1200# if defined (PERL_CORE) && PERL_DEBUG_COW > 1
c7724415 1201# define SvPVX(sv) (0 + (assert_(!SvREADONLY(sv)) (sv)->sv_u.svu_pv))
771ba71a
NC
1202# else
1203# define SvPVX(sv) SvPVX_mutable(sv)
1204# endif
771ba71a
NC
1205# define SvCUR(sv) (0 + ((XPV*) SvANY(sv))->xpv_cur)
1206# define SvLEN(sv) (0 + ((XPV*) SvANY(sv))->xpv_len)
1207# define SvEND(sv) ((sv)->sv_u.svu_pv + ((XPV*)SvANY(sv))->xpv_cur)
1208
c7724415
FC
1209# define SvMAGIC(sv) (0 + *(assert_(SvTYPE(sv) >= SVt_PVMG) &((XPVMG*) SvANY(sv))->xmg_u.xmg_magic))
1210# define SvSTASH(sv) (0 + *(assert_(SvTYPE(sv) >= SVt_PVMG) &((XPVMG*) SvANY(sv))->xmg_stash))
f3476b0f 1211#else /* Below is not PERL_DEBUG_COW */
2324bdb9
DIM
1212# ifdef PERL_CORE
1213# define SvLEN(sv) (0 + ((XPV*) SvANY(sv))->xpv_len)
1214# else
771ba71a 1215# define SvLEN(sv) ((XPV*) SvANY(sv))->xpv_len
2324bdb9 1216# endif
771ba71a
NC
1217# define SvEND(sv) ((sv)->sv_u.svu_pv + ((XPV*)SvANY(sv))->xpv_cur)
1218
041c1a23 1219# if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
05ef5f8f 1220/* These get expanded inside other macros that already use a variable _sv */
f7877b28 1221# define SvPVX(sv) \
1f4fbd3b
MS
1222 (*({ SV *const _svpvx = MUTABLE_SV(sv); \
1223 assert(PL_valid_types_PVX[SvTYPE(_svpvx) & SVt_MASK]); \
1224 assert(!isGV_with_GP(_svpvx)); \
1225 assert(!(SvTYPE(_svpvx) == SVt_PVIO \
1226 && !(IoFLAGS(_svpvx) & IOf_FAKE_DIRP))); \
1227 &((_svpvx)->sv_u.svu_pv); \
1228 }))
2324bdb9
DIM
1229# ifdef PERL_CORE
1230# define SvCUR(sv) \
1f4fbd3b
MS
1231 ({ const SV *const _svcur = (const SV *)(sv); \
1232 assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]); \
1233 assert(!isGV_with_GP(_svcur)); \
1234 assert(!(SvTYPE(_svcur) == SVt_PVIO \
1235 && !(IoFLAGS(_svcur) & IOf_FAKE_DIRP))); \
1236 (((XPV*) MUTABLE_PTR(SvANY(_svcur)))->xpv_cur); \
1237 })
2324bdb9 1238# else
08002bbf 1239# define SvCUR(sv) \
1f4fbd3b
MS
1240 (*({ const SV *const _svcur = (const SV *)(sv); \
1241 assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]); \
1242 assert(!isGV_with_GP(_svcur)); \
1243 assert(!(SvTYPE(_svcur) == SVt_PVIO \
1244 && !(IoFLAGS(_svcur) & IOf_FAKE_DIRP))); \
1245 &(((XPV*) MUTABLE_PTR(SvANY(_svcur)))->xpv_cur); \
1246 }))
2324bdb9 1247# endif
05ef5f8f 1248# define SvIVX(sv) \
1f4fbd3b
MS
1249 (*({ const SV *const _svivx = (const SV *)(sv); \
1250 assert(PL_valid_types_IVX[SvTYPE(_svivx) & SVt_MASK]); \
1251 assert(!isGV_with_GP(_svivx)); \
1252 &(((XPVIV*) MUTABLE_PTR(SvANY(_svivx)))->xiv_iv); \
1253 }))
05ef5f8f 1254# define SvUVX(sv) \
1f4fbd3b
MS
1255 (*({ const SV *const _svuvx = (const SV *)(sv); \
1256 assert(PL_valid_types_IVX[SvTYPE(_svuvx) & SVt_MASK]); \
1257 assert(!isGV_with_GP(_svuvx)); \
1258 &(((XPVUV*) MUTABLE_PTR(SvANY(_svuvx)))->xuv_uv); \
1259 }))
05ef5f8f 1260# define SvNVX(sv) \
1f4fbd3b
MS
1261 (*({ const SV *const _svnvx = (const SV *)(sv); \
1262 assert(PL_valid_types_NVX[SvTYPE(_svnvx) & SVt_MASK]); \
1263 assert(!isGV_with_GP(_svnvx)); \
1264 &(((XPVNV*) MUTABLE_PTR(SvANY(_svnvx)))->xnv_u.xnv_nv); \
1265 }))
ac09da3b 1266# define SvRV(sv) \
1f4fbd3b
MS
1267 (*({ SV *const _svrv = MUTABLE_SV(sv); \
1268 assert(PL_valid_types_RV[SvTYPE(_svrv) & SVt_MASK]); \
1269 assert(!isGV_with_GP(_svrv)); \
1270 assert(!(SvTYPE(_svrv) == SVt_PVIO \
1271 && !(IoFLAGS(_svrv) & IOf_FAKE_DIRP))); \
1272 &((_svrv)->sv_u.svu_rv); \
1273 }))
f19a12a3 1274# define SvRV_const(sv) \
1f4fbd3b
MS
1275 ({ const SV *const _svrv = (const SV *)(sv); \
1276 assert(PL_valid_types_RV[SvTYPE(_svrv) & SVt_MASK]); \
1277 assert(!isGV_with_GP(_svrv)); \
1278 assert(!(SvTYPE(_svrv) == SVt_PVIO \
1279 && !(IoFLAGS(_svrv) & IOf_FAKE_DIRP))); \
1280 (_svrv)->sv_u.svu_rv; \
1281 })
05ef5f8f 1282# define SvMAGIC(sv) \
1f4fbd3b
MS
1283 (*({ const SV *const _svmagic = (const SV *)(sv); \
1284 assert(SvTYPE(_svmagic) >= SVt_PVMG); \
1285 &(((XPVMG*) MUTABLE_PTR(SvANY(_svmagic)))->xmg_u.xmg_magic); \
1286 }))
05ef5f8f 1287# define SvSTASH(sv) \
1f4fbd3b
MS
1288 (*({ const SV *const _svstash = (const SV *)(sv); \
1289 assert(SvTYPE(_svstash) >= SVt_PVMG); \
1290 &(((XPVMG*) MUTABLE_PTR(SvANY(_svstash)))->xmg_stash); \
1291 }))
f3476b0f 1292# else /* Below is not DEBUGGING or can't use brace groups */
08002bbf
NC
1293# define SvPVX(sv) ((sv)->sv_u.svu_pv)
1294# define SvCUR(sv) ((XPV*) SvANY(sv))->xpv_cur
05ef5f8f
NC
1295# define SvIVX(sv) ((XPVIV*) SvANY(sv))->xiv_iv
1296# define SvUVX(sv) ((XPVUV*) SvANY(sv))->xuv_uv
58430790 1297# define SvNVX(sv) ((XPVNV*) SvANY(sv))->xnv_u.xnv_nv
ac09da3b 1298# define SvRV(sv) ((sv)->sv_u.svu_rv)
f19a12a3 1299# define SvRV_const(sv) (0 + (sv)->sv_u.svu_rv)
e736a858 1300# define SvMAGIC(sv) ((XPVMG*) SvANY(sv))->xmg_u.xmg_magic
771ba71a 1301# define SvSTASH(sv) ((XPVMG*) SvANY(sv))->xmg_stash
03687789 1302# endif
62703e72
NC
1303#endif
1304
06c0cc96 1305#ifndef PERL_POISON
bb496845 1306/* Given that these two are new, there can't be any existing code using them
3968dd31 1307 * as LVALUEs, so prevent that from happening */
06c0cc96
NC
1308# define SvPVX_mutable(sv) (0 + (sv)->sv_u.svu_pv)
1309# define SvPVX_const(sv) ((const char*)(0 + (sv)->sv_u.svu_pv))
1310#else
1311/* Except for the poison code, which uses & to scribble over the pointer after
1312 free() is called. */
1313# define SvPVX_mutable(sv) ((sv)->sv_u.svu_pv)
1314# define SvPVX_const(sv) ((const char*)((sv)->sv_u.svu_pv))
1315#endif
bb496845 1316
62703e72
NC
1317#define SvIVXx(sv) SvIVX(sv)
1318#define SvUVXx(sv) SvUVX(sv)
1319#define SvNVXx(sv) SvNVX(sv)
1320#define SvPVXx(sv) SvPVX(sv)
1321#define SvLENx(sv) SvLEN(sv)
1322#define SvENDx(sv) ((PL_Sv = (sv)), SvEND(PL_Sv))
1323
1324
28e5dec8
JH
1325/* Ask a scalar nicely to try to become an IV, if possible.
1326 Not guaranteed to stay returning void */
1327/* Macro won't actually call sv_2iv if already IOK */
1328#define SvIV_please(sv) \
1f4fbd3b
MS
1329 STMT_START {if (!SvIOKp(sv) && (SvFLAGS(sv) & (SVf_NOK|SVf_POK))) \
1330 (void) SvIV(sv); } STMT_END
6f1401dc 1331#define SvIV_please_nomg(sv) \
1f4fbd3b
MS
1332 (!(SvFLAGS(sv) & (SVf_IOK|SVp_IOK)) && (SvFLAGS(sv) & (SVf_NOK|SVf_POK)) \
1333 ? (sv_2iv_flags(sv, 0), SvIOK(sv)) \
1334 : SvIOK(sv))
79072805 1335#define SvIV_set(sv, val) \
1f4fbd3b
MS
1336 STMT_START { \
1337 assert(PL_valid_types_IV_set[SvTYPE(sv) & SVt_MASK]); \
1338 assert(!isGV_with_GP(sv)); \
1339 (((XPVIV*) SvANY(sv))->xiv_iv = (val)); } STMT_END
79072805 1340#define SvNV_set(sv, val) \
1f4fbd3b
MS
1341 STMT_START { \
1342 assert(PL_valid_types_NV_set[SvTYPE(sv) & SVt_MASK]); \
1343 assert(!isGV_with_GP(sv)); \
1344 (((XPVNV*)SvANY(sv))->xnv_u.xnv_nv = (val)); } STMT_END
79072805 1345#define SvPV_set(sv, val) \
1f4fbd3b
MS
1346 STMT_START { \
1347 assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]); \
1348 assert(!isGV_with_GP(sv)); \
1349 assert(!(SvTYPE(sv) == SVt_PVIO \
1350 && !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
1351 ((sv)->sv_u.svu_pv = (val)); } STMT_END
607fa7f2 1352#define SvUV_set(sv, val) \
1f4fbd3b
MS
1353 STMT_START { \
1354 assert(PL_valid_types_IV_set[SvTYPE(sv) & SVt_MASK]); \
1355 assert(!isGV_with_GP(sv)); \
1356 (((XPVUV*)SvANY(sv))->xuv_uv = (val)); } STMT_END
b162af07 1357#define SvRV_set(sv, val) \
f1fb8741 1358 STMT_START { \
1f4fbd3b
MS
1359 assert(PL_valid_types_RV[SvTYPE(sv) & SVt_MASK]); \
1360 assert(!isGV_with_GP(sv)); \
1361 assert(!(SvTYPE(sv) == SVt_PVIO \
1362 && !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
339049b0 1363 ((sv)->sv_u.svu_rv = (val)); } STMT_END
b162af07
SP
1364#define SvMAGIC_set(sv, val) \
1365 STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
e736a858 1366 (((XPVMG*)SvANY(sv))->xmg_u.xmg_magic = (val)); } STMT_END
b162af07
SP
1367#define SvSTASH_set(sv, val) \
1368 STMT_START { assert(SvTYPE(sv) >= SVt_PVMG); \
1369 (((XPVMG*) SvANY(sv))->xmg_stash = (val)); } STMT_END
79072805 1370#define SvCUR_set(sv, val) \
1f4fbd3b
MS
1371 STMT_START { \
1372 assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]); \
1373 assert(!isGV_with_GP(sv)); \
1374 assert(!(SvTYPE(sv) == SVt_PVIO \
1375 && !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
1376 (((XPV*) SvANY(sv))->xpv_cur = (val)); } STMT_END
79072805 1377#define SvLEN_set(sv, val) \
1f4fbd3b
MS
1378 STMT_START { \
1379 assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]); \
1380 assert(!isGV_with_GP(sv)); \
1381 assert(!(SvTYPE(sv) == SVt_PVIO \
1382 && !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
1383 (((XPV*) SvANY(sv))->xpv_len = (val)); } STMT_END
7ae8ee9e 1384#define SvEND_set(sv, val) \
1f4fbd3b
MS
1385 STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
1386 SvCUR_set(sv, (val) - SvPVX(sv)); } STMT_END
79072805 1387
cd188aff
KW
1388/*
1389=for apidoc Am|void|SvPV_renew|SV* sv|STRLEN len
1390Low level micro optimization of C<L</SvGROW>>. It is generally better to use
1391C<SvGROW> instead. This is because C<SvPV_renew> ignores potential issues that
1392C<SvGROW> handles. C<sv> needs to have a real C<PV> that is unencombered by
cbcd1db3
KW
1393things like COW. Using C<SV_CHECK_THINKFIRST> or
1394C<SV_CHECK_THINKFIRST_COW_DROP> before calling this should clean it up, but
cd188aff
KW
1395why not just use C<SvGROW> if you're not sure about the provenance?
1396
1397=cut
1398*/
b7e9a5c2 1399#define SvPV_renew(sv,n) \
1f4fbd3b
MS
1400 STMT_START { SvLEN_set(sv, n); \
1401 SvPV_set((sv), (MEM_WRAP_CHECK_(n,char) \
1402 (char*)saferealloc((Malloc_t)SvPVX(sv), \
1403 (MEM_SIZE)((n))))); \
1404 } STMT_END
1da4ca5f
NC
1405
1406#define SvPV_shrink_to_cur(sv) STMT_START { \
1f4fbd3b
MS
1407 const STRLEN _lEnGtH = SvCUR(sv) + 1; \
1408 SvPV_renew(sv, _lEnGtH); \
1409 } STMT_END
b7e9a5c2 1410
d54acd4f
KW
1411/*
1412=for apidoc Am|void|SvPV_free|SV * sv
1413
1414Frees the PV buffer in C<sv>, leaving things in a precarious state, so should
1415only be used as part of a larger operation
1416
1417=cut
1418*/
771ba71a
NC
1419#define SvPV_free(sv) \
1420 STMT_START { \
1f4fbd3b
MS
1421 assert(SvTYPE(sv) >= SVt_PV); \
1422 if (SvLEN(sv)) { \
1423 assert(!SvROK(sv)); \
1424 if(UNLIKELY(SvOOK(sv))) { \
1425 STRLEN zok; \
1426 SvOOK_offset(sv, zok); \
1427 SvPV_set(sv, SvPVX_mutable(sv) - zok); \
1428 SvFLAGS(sv) &= ~SVf_OOK; \
1429 } \
1430 Safefree(SvPVX(sv)); \
1431 } \
1432 } STMT_END
8bd4d4c5 1433
43230e26
NC
1434#ifdef PERL_CORE
1435/* Code that crops up in three places to take a scalar and ready it to hold
1436 a reference */
1437# define prepare_SV_for_RV(sv) \
1438 STMT_START { \
1f4fbd3b
MS
1439 if (SvTYPE(sv) < SVt_PV && SvTYPE(sv) != SVt_IV) \
1440 sv_upgrade(sv, SVt_IV); \
1441 else if (SvTYPE(sv) >= SVt_PV) { \
1442 SvPV_free(sv); \
1443 SvLEN_set(sv, 0); \
43230e26 1444 SvCUR_set(sv, 0); \
1f4fbd3b
MS
1445 } \
1446 } STMT_END
43230e26 1447#endif
373b357f 1448
cffe132d
NC
1449#ifndef PERL_CORE
1450# define BmFLAGS(sv) (SvTAIL(sv) ? FBMcf_TAIL : 0)
1451#endif
6976cee3 1452
041c1a23 1453#if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
60c8298a 1454# define BmUSEFUL(sv) \
1f4fbd3b
MS
1455 (*({ SV *const _bmuseful = MUTABLE_SV(sv); \
1456 assert(SvTYPE(_bmuseful) >= SVt_PVIV); \
1457 assert(SvVALID(_bmuseful)); \
1458 assert(!SvIOK(_bmuseful)); \
1459 &(((XPVIV*) SvANY(_bmuseful))->xiv_u.xivu_iv); \
1460 }))
60c8298a 1461#else
50c7be83 1462# define BmUSEFUL(sv) ((XPVIV*) SvANY(sv))->xiv_u.xivu_iv
b4f6c04b 1463
60c8298a 1464#endif
79072805 1465
8922e438
FC
1466#ifndef PERL_CORE
1467# define BmRARE(sv) 0
1468# define BmPREVIOUS(sv) 0
1469#endif
1470
f2da823f 1471#define FmLINES(sv) ((XPVIV*) SvANY(sv))->xiv_iv
79072805
LW
1472
1473#define LvTYPE(sv) ((XPVLV*) SvANY(sv))->xlv_type
1474#define LvTARG(sv) ((XPVLV*) SvANY(sv))->xlv_targ
1475#define LvTARGOFF(sv) ((XPVLV*) SvANY(sv))->xlv_targoff
bbfdc870 1476#define LvSTARGOFF(sv) ((XPVLV*) SvANY(sv))->xlv_targoff_u.xlvu_stargoff
79072805 1477#define LvTARGLEN(sv) ((XPVLV*) SvANY(sv))->xlv_targlen
83f78d1a 1478#define LvFLAGS(sv) ((XPVLV*) SvANY(sv))->xlv_flags
79072805 1479
b063b0a8
DIM
1480#define LVf_NEG_OFF 0x1
1481#define LVf_NEG_LEN 0x2
1482#define LVf_OUT_OF_RANGE 0x4
1483
6f7e8353 1484#define IoIFP(sv) (sv)->sv_u.svu_fp
8990e307
LW
1485#define IoOFP(sv) ((XPVIO*) SvANY(sv))->xio_ofp
1486#define IoDIRP(sv) ((XPVIO*) SvANY(sv))->xio_dirp
4755096e 1487#define IoANY(sv) ((XPVIO*) SvANY(sv))->xio_any
c490b21c 1488#define IoLINES(sv) ((XPVIO*) SvANY(sv))->xiv_u.xivu_iv
8990e307
LW
1489#define IoPAGE(sv) ((XPVIO*) SvANY(sv))->xio_page
1490#define IoPAGE_LEN(sv) ((XPVIO*) SvANY(sv))->xio_page_len
1491#define IoLINES_LEFT(sv)((XPVIO*) SvANY(sv))->xio_lines_left
1492#define IoTOP_NAME(sv) ((XPVIO*) SvANY(sv))->xio_top_name
1493#define IoTOP_GV(sv) ((XPVIO*) SvANY(sv))->xio_top_gv
1494#define IoFMT_NAME(sv) ((XPVIO*) SvANY(sv))->xio_fmt_name
1495#define IoFMT_GV(sv) ((XPVIO*) SvANY(sv))->xio_fmt_gv
1496#define IoBOTTOM_NAME(sv)((XPVIO*) SvANY(sv))->xio_bottom_name
1497#define IoBOTTOM_GV(sv) ((XPVIO*) SvANY(sv))->xio_bottom_gv
8990e307
LW
1498#define IoTYPE(sv) ((XPVIO*) SvANY(sv))->xio_type
1499#define IoFLAGS(sv) ((XPVIO*) SvANY(sv))->xio_flags
1500
50952442 1501/* IoTYPE(sv) is a single character telling the type of I/O connection. */
3b6c1aba
JH
1502#define IoTYPE_RDONLY '<'
1503#define IoTYPE_WRONLY '>'
1504#define IoTYPE_RDWR '+'
1505#define IoTYPE_APPEND 'a'
1506#define IoTYPE_PIPE '|'
1507#define IoTYPE_STD '-' /* stdin or stdout */
1508#define IoTYPE_SOCKET 's'
1509#define IoTYPE_CLOSED ' '
1510#define IoTYPE_IMPLICIT 'I' /* stdin or stdout or stderr */
1511#define IoTYPE_NUMERIC '#' /* fdopen */
03fcf2fc
GS
1512
1513/*
954c1994 1514=for apidoc Am|bool|SvTAINTED|SV* sv
8554e7a0 1515Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
954c1994
GS
1516not.
1517
1518=for apidoc Am|void|SvTAINTED_on|SV* sv
c55831ac 1519Marks an SV as tainted if tainting is enabled.
954c1994
GS
1520
1521=for apidoc Am|void|SvTAINTED_off|SV* sv
8554e7a0
FC
1522Untaints an SV. Be I<very> careful with this routine, as it short-circuits
1523some of Perl's fundamental security features. XS module authors should not
954c1994 1524use this function unless they fully understand all the implications of
72d33970 1525unconditionally untainting the value. Untainting should be done in the
954c1994
GS
1526standard perl fashion, via a carefully crafted regexp, rather than directly
1527untainting variables.
1528
1529=for apidoc Am|void|SvTAINT|SV* sv
c98cdb04
FC
1530Taints an SV if tainting is enabled, and if some input to the current
1531expression is tainted--usually a variable, but possibly also implicit
1532inputs such as locale settings. C<SvTAINT> propagates that taintedness to
1533the outputs of an expression in a pessimistic fashion; i.e., without paying
1534attention to precisely which outputs are influenced by which inputs.
954c1994
GS
1535
1536=cut
1537*/
1538
a0714e2c 1539#define sv_taint(sv) sv_magic((sv), NULL, PERL_MAGIC_taint, NULL, 0)
aae9cea0 1540
dc6d7f5c 1541#ifdef NO_TAINT_SUPPORT
284167a5
SM
1542# define SvTAINTED(sv) 0
1543#else
1544# define SvTAINTED(sv) (SvMAGICAL(sv) && sv_tainted(sv))
1545#endif
5d9574c1
DM
1546#define SvTAINTED_on(sv) STMT_START{ if(UNLIKELY(TAINTING_get)){sv_taint(sv);} }STMT_END
1547#define SvTAINTED_off(sv) STMT_START{ if(UNLIKELY(TAINTING_get)){sv_untaint(sv);} }STMT_END
bbce6d69 1548
c6ee37c5
MB
1549#define SvTAINT(sv) \
1550 STMT_START { \
d48c660d
DM
1551 assert(TAINTING_get || !TAINT_get); \
1552 if (UNLIKELY(TAINT_get)) \
1553 SvTAINTED_on(sv); \
c6ee37c5 1554 } STMT_END
79072805 1555
954c1994
GS
1556/*
1557=for apidoc Am|char*|SvPV_force|SV* sv|STRLEN len
26d1d7c7
KW
1558=for apidoc_item ||SvPV_force_nolen|SV* sv
1559=for apidoc_item ||SvPVx_force|SV* sv|STRLEN len
1560=for apidoc_item ||SvPV_force_nomg|SV* sv|STRLEN len
1561=for apidoc_item ||SvPV_force_nomg_nolen|SV * sv
1562=for apidoc_item ||SvPV_force_mutable|SV * sv|STRLEN len
1563=for apidoc_item ||SvPV_force_flags|SV * sv|STRLEN len|U32 flags
1564=for apidoc_item ||SvPV_force_flags_nolen|SV * sv|U32 flags
1565=for apidoc_item ||SvPV_force_flags_mutable|SV * sv|STRLEN len|U32 flags
1566=for apidoc_item ||SvPVbyte_force
1567=for apidoc_item ||SvPVbytex_force
1568=for apidoc_item ||SvPVutf8_force
1569=for apidoc_item ||SvPVutf8x_force
1570
e97ba882
KW
1571These are like C<L</SvPV>>, returning the string in the SV, but will force the
1572SV into containing a string (C<L</SvPOK>>), and only a string
1573(C<L</SvPOK_only>>), by hook or by crook. You need to use one of these
1574C<force> routines if you are going to update the C<L</SvPVX>> directly.
954c1994 1575
fd142383 1576Note that coercing an arbitrary scalar into a plain PV will potentially
72d33970 1577strip useful data from it. For example if the SV was C<SvROK>, then the
fd142383
DM
1578referent will have its reference count decremented, and the SV itself may
1579be converted to an C<SvPOK> scalar with a string buffer containing a value
1580such as C<"ARRAY(0x1234)">.
1581
26d1d7c7
KW
1582The differences between the forms are:
1583
1584The forms with C<flags> in their names allow you to use the C<flags> parameter
1585to specify to perform 'get' magic (by setting the C<SV_GMAGIC> flag) or to skip
1586'get' magic (by clearing it). The other forms do perform 'get' magic, except
1587for the ones with C<nomg> in their names, which skip 'get' magic.
1588
e97ba882
KW
1589The forms that take a C<len> parameter will set that variable to the byte
1590length of the resultant string (these are macros, so don't use C<&len>).
1591
1592The forms with C<nolen> in their names indicate they don't have a C<len>
1593parameter. They should be used only when it is known that the PV is a C
1594string, terminated by a NUL byte, and without intermediate NUL characters; or
1595when you don't care about its length.
26d1d7c7
KW
1596
1597The forms with C<mutable> in their names are effectively the same as those without,
1598but the name emphasizes that the string is modifiable by the caller, which it is
1599in all the forms.
1600
1601C<SvPVutf8_force> is like C<SvPV_force>, but converts C<sv> to UTF-8 first if
1602not already UTF-8.
1603
1604C<SvPVutf8x_force> is like C<SvPVutf8_force>, but guarantees to evaluate C<sv>
1605only once; use the more efficient C<SvPVutf8_force> otherwise.
1606
1607C<SvPVbyte_force> is like C<SvPV_force>, but converts C<sv> to byte
1608representation first if currently encoded as UTF-8. If the SV cannot be
1609downgraded from UTF-8, this croaks.
1610
1611C<SvPVbytex_force> is like C<SvPVbyte_force>, but guarantees to evaluate C<sv>
1612only once; use the more efficient C<SvPVbyte_force> otherwise.
645c22ef 1613
954c1994 1614=for apidoc Am|char*|SvPV|SV* sv|STRLEN len
1e0eb5c5
KW
1615=for apidoc_item |char*|SvPVx|SV* sv|STRLEN len
1616=for apidoc_item |char*|SvPV_nomg|SV* sv|STRLEN len
1617=for apidoc_item |char*|SvPV_nolen|SV* sv
1618=for apidoc_item |char*|SvPVx_nolen|SV* sv
1619=for apidoc_item |char*|SvPV_nomg_nolen|SV* sv
1620=for apidoc_item |char*|SvPV_mutable|SV* sv|STRLEN len
1621=for apidoc_item |const char*|SvPV_const|SV* sv|STRLEN len
1622=for apidoc_item |const char*|SvPVx_const|SV* sv|STRLEN len
1623=for apidoc_item |const char*|SvPV_nolen_const|SV* sv
1624=for apidoc_item |const char*|SvPVx_nolen_const|SV* sv
1625=for apidoc_item |const char*|SvPV_nomg_const|SV* sv|STRLEN len
1626=for apidoc_item |const char*|SvPV_nomg_const_nolen|SV* sv
1627=for apidoc_item |char *|SvPV_flags|SV * sv|STRLEN len|U32 flags
1628=for apidoc_item |const char *|SvPV_flags_const|SV * sv|STRLEN len|U32 flags
1629=for apidoc_item |char *|SvPV_flags_mutable|SV * sv|STRLEN len|U32 flags
1630=for apidoc_item |char*|SvPVbyte|SV* sv|STRLEN len
1631=for apidoc_item |char*|SvPVbyte_nomg|SV* sv|STRLEN len
1632=for apidoc_item |char*|SvPVbyte_nolen|SV* sv
1633=for apidoc_item |char*|SvPVbytex_nolen|SV* sv
1634=for apidoc_item |char*|SvPVbytex|SV* sv|STRLEN len
1635=for apidoc_item |char*|SvPVbyte_or_null|SV* sv|STRLEN len
1636=for apidoc_item |char*|SvPVbyte_or_null_nomg|SV* sv|STRLEN len
1637=for apidoc_item |char*|SvPVutf8|SV* sv|STRLEN len
1638=for apidoc_item |char*|SvPVutf8x|SV* sv|STRLEN len
1639=for apidoc_item |char*|SvPVutf8_nomg|SV* sv|STRLEN len
1640=for apidoc_item |char*|SvPVutf8_nolen|SV* sv
1641=for apidoc_item |char*|SvPVutf8_or_null|SV* sv|STRLEN len
1642=for apidoc_item |char*|SvPVutf8_or_null_nomg|SV* sv|STRLEN len
1643
1644All these return a pointer to the string in C<sv>, or a stringified form of
1645C<sv> if it does not contain a string. The SV may cache the stringified
1646version becoming C<SvPOK>.
1647
1648This is a very basic and common operation, so there are lots of slightly
1649different versions of it.
1650
1651Note that there is no guarantee that the return value of C<SvPV(sv)>, for
1652example, is equal to C<SvPVX(sv)>, or that C<SvPVX(sv)> contains valid data, or
1653that successive calls to C<SvPV(sv)> (or another of these forms) will return
1654the same pointer value each time. This is due to the way that things like
1655overloading and Copy-On-Write are handled. In these cases, the return value
1656may point to a temporary buffer or similar. If you absolutely need the
1657C<SvPVX> field to be valid (for example, if you intend to write to it), then
1658see C<L</SvPV_force>>.
1659
1660The differences between the forms are:
1661
3c3f883d
FG
1662The forms with neither C<byte> nor C<utf8> in their names (e.g., C<SvPV> or
1663C<SvPV_nolen>) can expose the SV's internal string buffer. If
1664that buffer consists entirely of bytes 0-255 and includes any bytes above
1665127, then you B<MUST> consult C<SvUTF8> to determine the actual code points
1666the string is meant to contain. Generally speaking, it is probably safer to
1667prefer C<SvPVbyte>, C<SvPVutf8>, and the like. See
1668L<perlguts/How do I pass a Perl string to a C library?> for more details.
1669
1e0eb5c5
KW
1670The forms with C<flags> in their names allow you to use the C<flags> parameter
1671to specify to process 'get' magic (by setting the C<SV_GMAGIC> flag) or to skip
1672'get' magic (by clearing it). The other forms process 'get' magic, except for
1673the ones with C<nomg> in their names, which skip 'get' magic.
1674
1675The forms that take a C<len> parameter will set that variable to the byte
1676length of the resultant string (these are macros, so don't use C<&len>).
1677
1678The forms with C<nolen> in their names indicate they don't have a C<len>
1679parameter. They should be used only when it is known that the PV is a C
1680string, terminated by a NUL byte, and without intermediate NUL characters; or
1681when you don't care about its length.
1682
1683The forms with C<const> in their names return S<C<const char *>> so that the
1684compiler will hopefully complain if you were to try to modify the contents of
1685the string (unless you cast away const yourself).
1686
1687The other forms return a mutable pointer so that the string is modifiable by
1688the caller; this is emphasized for the ones with C<mutable> in their names.
1689
1690The forms whose name ends in C<x> are the same as the corresponding form
1691without the C<x>, but the C<x> form is guaranteed to evaluate C<sv> exactly
1692once, with a slight loss of efficiency. Use this if C<sv> is an expression
1693with side effects.
1694
1695C<SvPVutf8> is like C<SvPV>, but converts C<sv> to UTF-8 first if not already
1696UTF-8. Similiarly, the other forms with C<utf8> in their names correspond to
1697their respective forms without.
1698
1699C<SvPVutf8_or_null> and C<SvPVutf8_or_null_nomg> don't have corresponding
1700non-C<utf8> forms. Instead they are like C<SvPVutf8_nomg>, but when C<sv> is
1701undef, they return C<NULL>.
1702
1703C<SvPVbyte> is like C<SvPV>, but converts C<sv> to byte representation first if
1704currently encoded as UTF-8. If C<sv> cannot be downgraded from UTF-8, it
1705croaks. Similiarly, the other forms with C<byte> in their names correspond to
1706their respective forms without.
1707
1708C<SvPVbyte_or_null> doesn't have a corresponding non-C<byte> form. Instead it
1709is like C<SvPVbyte>, but when C<sv> is undef, it returns C<NULL>.
71eb6d8c 1710
954c1994 1711=for apidoc Am|IV|SvIV|SV* sv
5fcca646
KW
1712=for apidoc_item SvIVx
1713=for apidoc_item SvIV_nomg
891f9566 1714
5fcca646 1715These coerce the given SV to IV and return it. The returned value in many
04e8f319
P
1716circumstances will get stored in C<sv>'s IV slot, but not in all cases. (Use
1717C<L</sv_setiv>> to make sure it does).
1718
5fcca646
KW
1719C<SvIVx> is different from the others in that it is guaranteed to evaluate
1720C<sv> exactly once; the others may evaluate it multiple times. Only use this
1721form if C<sv> is an expression with side effects, otherwise use the more
1722efficient C<SvIV>.
04e8f319 1723
5fcca646 1724C<SvIV_nomg> is the same as C<SvIV>, but does not perform 'get' magic.
645c22ef 1725
5fcca646
KW
1726=for apidoc Am|NV|SvNV|SV* sv
1727=for apidoc_item SvNVx
1728=for apidoc_item SvNV_nomg
6f1401dc 1729
5fcca646 1730These coerce the given SV to NV and return it. The returned value in many
04e8f319
P
1731circumstances will get stored in C<sv>'s NV slot, but not in all cases. (Use
1732C<L</sv_setnv>> to make sure it does).
1733
5fcca646
KW
1734C<SvNVx> is different from the others in that it is guaranteed to evaluate
1735C<sv> exactly once; the others may evaluate it multiple times. Only use this
1736form if C<sv> is an expression with side effects, otherwise use the more
1737efficient C<SvNV>.
954c1994 1738
5fcca646 1739C<SvNV_nomg> is the same as C<SvNV>, but does not perform 'get' magic.
04e8f319 1740
5fcca646
KW
1741=for apidoc Am|UV|SvUV|SV* sv
1742=for apidoc_item SvUVx
1743=for apidoc_item SvUV_nomg
891f9566 1744
5fcca646 1745These coerce the given SV to UV and return it. The returned value in many
04e8f319
P
1746circumstances will get stored in C<sv>'s UV slot, but not in all cases. (Use
1747C<L</sv_setuv>> to make sure it does).
1748
5fcca646
KW
1749C<SvUVx> is different from the others in that it is guaranteed to evaluate
1750C<sv> exactly once; the others may evaluate it multiple times. Only use this
1751form if C<sv> is an expression with side effects, otherwise use the more
1752efficient C<SvUV>.
1753
1754C<SvUV_nomg> is the same as C<SvUV>, but does not perform 'get' magic.
954c1994 1755
4eff5eb8
KW
1756=for apidoc SvTRUE
1757=for apidoc_item SvTRUEx
1758=for apidoc_item SvTRUE_nomg
1759=for apidoc_item SvTRUE_NN
1760=for apidoc_item SvTRUE_nomg_NN
06c841cf 1761
4eff5eb8
KW
1762These return a boolean indicating whether Perl would evaluate the SV as true or
1763false. See C<L</SvOK>> for a defined/undefined test.
3127113c 1764
4eff5eb8
KW
1765As of Perl 5.32, all are guaranteed to evaluate C<sv> only once. Prior to that
1766release, only C<SvTRUEx> guaranteed single evaluation; now C<SvTRUEx> is
1767identical to C<SvTRUE>.
954c1994 1768
4eff5eb8
KW
1769C<SvTRUE_nomg> and C<TRUE_nomg_NN> do not perform 'get' magic; the others do
1770unless the scalar is already C<SvPOK>, C<SvIOK>, or C<SvNOK> (the public, not
1771the private flags).
1772
1773C<SvTRUE_NN> is like C<L</SvTRUE>>, but C<sv> is assumed to be
1774non-null (NN). If there is a possibility that it is NULL, use plain
1775C<SvTRUE>.
1776
1777C<SvTRUE_nomg_NN> is like C<L</SvTRUE_nomg>>, but C<sv> is assumed to be
1778non-null (NN). If there is a possibility that it is NULL, use plain
1779C<SvTRUE_nomg>.
1780
645c22ef 1781=for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
4a4088c4 1782Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
645c22ef
DM
1783
1784=for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len
4a4088c4 1785Like C<SvPV>, but converts C<sv> to UTF-8 first if necessary.
645c22ef 1786
757fc329
P
1787=for apidoc Am|char*|SvPVutf8_nomg|SV* sv|STRLEN len
1788Like C<SvPVutf8>, but does not process get magic.
1789
3e13e8f6 1790=for apidoc Am|char*|SvPVutf8_or_null|SV* sv|STRLEN len
abd18c6d 1791Like C<SvPVutf8>, but when C<sv> is undef, returns C<NULL>.
3e13e8f6
P
1792
1793=for apidoc Am|char*|SvPVutf8_or_null_nomg|SV* sv|STRLEN len
1794Like C<SvPVutf8_or_null>, but does not process get magic.
1795
b70b15d2 1796=for apidoc Am|char*|SvPVutf8_nolen|SV* sv
4a4088c4 1797Like C<SvPV_nolen>, but converts C<sv> to UTF-8 first if necessary.
645c22ef
DM
1798
1799=for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
b661dc90
KW
1800Like C<SvPV_force>, but converts C<sv> to byte representation first if
1801necessary. If the SV cannot be downgraded from UTF-8, this croaks.
645c22ef
DM
1802
1803=for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
b661dc90
KW
1804Like C<SvPV>, but converts C<sv> to byte representation first if necessary. If
1805the SV cannot be downgraded from UTF-8, this croaks.
645c22ef 1806
757fc329
P
1807=for apidoc Am|char*|SvPVbyte_nomg|SV* sv|STRLEN len
1808Like C<SvPVbyte>, but does not process get magic.
1809
3e13e8f6 1810=for apidoc Am|char*|SvPVbyte_or_null|SV* sv|STRLEN len
abd18c6d 1811Like C<SvPVbyte>, but when C<sv> is undef, returns C<NULL>.
3e13e8f6
P
1812
1813=for apidoc Am|char*|SvPVbyte_or_null_nomg|SV* sv|STRLEN len
1814Like C<SvPVbyte_or_null>, but does not process get magic.
1815
b70b15d2 1816=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
b661dc90
KW
1817Like C<SvPV_nolen>, but converts C<sv> to byte representation first if
1818necessary. If the SV cannot be downgraded from UTF-8, this croaks.
645c22ef 1819
df8dcb28
DD
1820=for apidoc Am|U32|SvIsCOW|SV* sv
1821Returns a U32 value indicating whether the SV is Copy-On-Write (either shared
19dbb8f1 1822hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
8554e7a0 1823COW).
19dbb8f1
NC
1824
1825=for apidoc Am|bool|SvIsCOW_shared_hash|SV* sv
1826Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
1827scalar.
645c22ef 1828
954c1994
GS
1829=cut
1830*/
1831
25da4f38 1832/* Let us hope that bitmaps for UV and IV are the same */
4bac9ae4
CS
1833#define SvIV(sv) (SvIOK_nog(sv) ? SvIVX(sv) : sv_2iv(sv))
1834#define SvUV(sv) (SvUOK_nog(sv) ? SvUVX(sv) : sv_2uv(sv))
1835#define SvNV(sv) (SvNOK_nog(sv) ? SvNVX(sv) : sv_2nv(sv))
79072805 1836
891f9566 1837#define SvIV_nomg(sv) (SvIOK(sv) ? SvIVX(sv) : sv_2iv_flags(sv, 0))
530e9296 1838#define SvUV_nomg(sv) (SvUOK(sv) ? SvUVX(sv) : sv_2uv_flags(sv, 0))
6f1401dc 1839#define SvNV_nomg(sv) (SvNOK(sv) ? SvNVX(sv) : sv_2nv_flags(sv, 0))
891f9566 1840
baca2b92 1841/* ----*/
8d6d96c1 1842
3629b4ec
KW
1843#define SvPV(sv, len) SvPV_flags(sv, len, SV_GMAGIC)
1844#define SvPV_const(sv, len) SvPV_flags_const(sv, len, SV_GMAGIC)
1845#define SvPV_mutable(sv, len) SvPV_flags_mutable(sv, len, SV_GMAGIC)
8d6d96c1 1846
3629b4ec 1847#define SvPV_flags(sv, len, flags) \
4bac9ae4 1848 (SvPOK_nog(sv) \
3629b4ec
KW
1849 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pv_flags(sv, &len, flags))
1850#define SvPV_flags_const(sv, len, flags) \
4bac9ae4 1851 (SvPOK_nog(sv) \
3629b4ec
KW
1852 ? ((len = SvCUR(sv)), SvPVX_const(sv)) : \
1853 (const char*) sv_2pv_flags(sv, &len, (flags|SV_CONST_RETURN)))
2596d9fe 1854#define SvPV_flags_const_nolen(sv, flags) \
4bac9ae4 1855 (SvPOK_nog(sv) \
2596d9fe 1856 ? SvPVX_const(sv) : \
c77ed9ca 1857 (const char*) sv_2pv_flags(sv, 0, (flags|SV_CONST_RETURN)))
3629b4ec 1858#define SvPV_flags_mutable(sv, len, flags) \
4bac9ae4 1859 (SvPOK_nog(sv) \
3629b4ec
KW
1860 ? ((len = SvCUR(sv)), SvPVX_mutable(sv)) : \
1861 sv_2pv_flags(sv, &len, (flags|SV_MUTABLE_RETURN)))
79072805 1862
3629b4ec 1863#define SvPV_force(sv, len) SvPV_force_flags(sv, len, SV_GMAGIC)
13c5b33c 1864#define SvPV_force_nolen(sv) SvPV_force_flags_nolen(sv, SV_GMAGIC)
3629b4ec 1865#define SvPV_force_mutable(sv, len) SvPV_force_flags_mutable(sv, len, SV_GMAGIC)
baca2b92 1866
3629b4ec 1867#define SvPV_force_nomg(sv, len) SvPV_force_flags(sv, len, 0)
2596d9fe 1868#define SvPV_force_nomg_nolen(sv) SvPV_force_flags_nolen(sv, 0)
8d6d96c1 1869
3629b4ec 1870#define SvPV_force_flags(sv, len, flags) \
8bb025ae 1871 (SvPOK_pure_nogthink(sv) \
3629b4ec 1872 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvn_force_flags(sv, &len, flags))
4bac9ae4 1873
13c5b33c 1874#define SvPV_force_flags_nolen(sv, flags) \
8bb025ae 1875 (SvPOK_pure_nogthink(sv) \
4bac9ae4
CS
1876 ? SvPVX(sv) : sv_pvn_force_flags(sv, 0, flags))
1877
3629b4ec 1878#define SvPV_force_flags_mutable(sv, len, flags) \
8bb025ae 1879 (SvPOK_pure_nogthink(sv) \
3629b4ec
KW
1880 ? ((len = SvCUR(sv)), SvPVX_mutable(sv)) \
1881 : sv_pvn_force_flags(sv, &len, flags|SV_MUTABLE_RETURN))
a0d0e21e 1882
1fa8b10d 1883#define SvPV_nolen(sv) \
4bac9ae4 1884 (SvPOK_nog(sv) \
dafda6d1 1885 ? SvPVX(sv) : sv_2pv_flags(sv, 0, SV_GMAGIC))
70401c6b 1886
0334097d 1887/* "_nomg" in these defines means no mg_get() */
71eb6d8c 1888#define SvPV_nomg_nolen(sv) \
4bac9ae4 1889 (SvPOK_nog(sv) \
71eb6d8c
TC
1890 ? SvPVX(sv) : sv_2pv_flags(sv, 0, 0))
1891
9ce348e8 1892#define SvPV_nolen_const(sv) \
4bac9ae4 1893 (SvPOK_nog(sv) \
9ce348e8
NC
1894 ? SvPVX_const(sv) : sv_2pv_flags(sv, 0, SV_GMAGIC|SV_CONST_RETURN))
1895
3629b4ec
KW
1896#define SvPV_nomg(sv, len) SvPV_flags(sv, len, 0)
1897#define SvPV_nomg_const(sv, len) SvPV_flags_const(sv, len, 0)
2596d9fe 1898#define SvPV_nomg_const_nolen(sv) SvPV_flags_const_nolen(sv, 0)
5bc28da9 1899
baca2b92 1900/* ----*/
70401c6b 1901
3629b4ec 1902#define SvPVutf8(sv, len) \
4bac9ae4 1903 (SvPOK_utf8_nog(sv) \
3629b4ec 1904 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8(sv, &len))
70401c6b 1905
3629b4ec 1906#define SvPVutf8_or_null(sv, len) \
3e13e8f6 1907 (SvPOK_utf8_nog(sv) \
3629b4ec
KW
1908 ? ((len = SvCUR(sv)), SvPVX(sv)) : (SvGETMAGIC(sv), SvOK(sv)) \
1909 ? sv_2pvutf8_flags(sv, &len, 0) : ((len = 0), NULL))
3e13e8f6 1910
3629b4ec 1911#define SvPVutf8_nomg(sv, len) \
757fc329 1912 (SvPOK_utf8_nog(sv) \
3629b4ec 1913 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8_flags(sv, &len, 0))
757fc329 1914
3629b4ec 1915#define SvPVutf8_or_null_nomg(sv, len) \
3e13e8f6 1916 (SvPOK_utf8_nog(sv) \
3629b4ec
KW
1917 ? ((len = SvCUR(sv)), SvPVX(sv)) : SvOK(sv) \
1918 ? sv_2pvutf8_flags(sv, &len, 0) : ((len = 0), NULL))
3e13e8f6 1919
3629b4ec 1920#define SvPVutf8_force(sv, len) \
8bb025ae 1921 (SvPOK_utf8_pure_nogthink(sv) \
3629b4ec 1922 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvutf8n_force(sv, &len))
5bc28da9 1923
5bc28da9 1924#define SvPVutf8_nolen(sv) \
4bac9ae4 1925 (SvPOK_utf8_nog(sv) \
dafda6d1 1926 ? SvPVX(sv) : sv_2pvutf8(sv, 0))
70401c6b 1927
baca2b92
DM
1928/* ----*/
1929
3629b4ec 1930#define SvPVbyte(sv, len) \
4bac9ae4 1931 (SvPOK_byte_nog(sv) \
3629b4ec 1932 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte(sv, &len))
70401c6b 1933
3629b4ec 1934#define SvPVbyte_or_null(sv, len) \
3e13e8f6 1935 (SvPOK_byte_nog(sv) \
3629b4ec
KW
1936 ? ((len = SvCUR(sv)), SvPVX(sv)) : (SvGETMAGIC(sv), SvOK(sv)) \
1937 ? sv_2pvbyte_flags(sv, &len, 0) : ((len = 0), NULL))
3e13e8f6 1938
3629b4ec 1939#define SvPVbyte_nomg(sv, len) \
757fc329 1940 (SvPOK_byte_nog(sv) \
3629b4ec 1941 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte_flags(sv, &len, 0))
757fc329 1942
3629b4ec 1943#define SvPVbyte_or_null_nomg(sv, len) \
3e13e8f6 1944 (SvPOK_utf8_nog(sv) \
3629b4ec
KW
1945 ? ((len = SvCUR(sv)), SvPVX(sv)) : SvOK(sv) \
1946 ? sv_2pvbyte_flags(sv, &len, 0) : ((len = 0), NULL))
3e13e8f6 1947
3629b4ec 1948#define SvPVbyte_force(sv, len) \
8bb025ae 1949 (SvPOK_byte_pure_nogthink(sv) \
3629b4ec 1950 ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvbyten_force(sv, &len))
5bc28da9 1951
5bc28da9 1952#define SvPVbyte_nolen(sv) \
4bac9ae4 1953 (SvPOK_byte_nog(sv) \
dafda6d1 1954 ? SvPVX(sv) : sv_2pvbyte(sv, 0))
70401c6b 1955
1f4fbd3b 1956
baca2b92
DM
1957/* define FOOx(): idempotent versions of FOO(). If possible, use a local
1958 * var to evaluate the arg once; failing that, use a global if possible;
1959 * failing that, call a function to do the work
1960 */
1961
3629b4ec
KW
1962#define SvPVx_force(sv, len) sv_pvn_force(sv, &len)
1963#define SvPVutf8x_force(sv, len) sv_pvutf8n_force(sv, &len)
1964#define SvPVbytex_force(sv, len) sv_pvbyten_force(sv, &len)
baca2b92 1965
7358a4d1 1966#define SvTRUEx(sv) SvTRUE(sv)
4eff5eb8
KW
1967#define SvTRUEx_nomg(sv) SvTRUE_nomg(sv)
1968#define SvTRUE_nomg_NN(sv) SvTRUE_common(sv, TRUE)
4bac9ae4 1969
041c1a23 1970#if defined(PERL_USE_GCC_BRACE_GROUPS)
baca2b92 1971
b1bc3f34
NC
1972# define SvIVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvIV(_sv); })
1973# define SvUVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvUV(_sv); })
1974# define SvNVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvNV(_sv); })
3629b4ec
KW
1975# define SvPVx(sv, len) ({SV *_sv = (sv); SvPV(_sv, len); })
1976# define SvPVx_const(sv, len) ({SV *_sv = (sv); SvPV_const(_sv, len); })
002e4c74 1977# define SvPVx_nolen(sv) ({SV *_sv = (sv); SvPV_nolen(_sv); })
9ce348e8 1978# define SvPVx_nolen_const(sv) ({SV *_sv = (sv); SvPV_nolen_const(_sv); })
3629b4ec
KW
1979# define SvPVutf8x(sv, len) ({SV *_sv = (sv); SvPVutf8(_sv, len); })
1980# define SvPVbytex(sv, len) ({SV *_sv = (sv); SvPVbyte(_sv, len); })
002e4c74 1981# define SvPVbytex_nolen(sv) ({SV *_sv = (sv); SvPVbyte_nolen(_sv); })
baca2b92 1982
a80f87c4 1983#else /* __GNUC__ */
baca2b92 1984
a80f87c4
GS
1985/* These inlined macros use globals, which will require a thread
1986 * declaration in user code, so we avoid them under threads */
1987
3db8f154
MB
1988# define SvIVx(sv) ((PL_Sv = (sv)), SvIV(PL_Sv))
1989# define SvUVx(sv) ((PL_Sv = (sv)), SvUV(PL_Sv))
1990# define SvNVx(sv) ((PL_Sv = (sv)), SvNV(PL_Sv))
3629b4ec
KW
1991# define SvPVx(sv, len) ((PL_Sv = (sv)), SvPV(PL_Sv, len))
1992# define SvPVx_const(sv, len) ((PL_Sv = (sv)), SvPV_const(PL_Sv, len))
002e4c74 1993# define SvPVx_nolen(sv) ((PL_Sv = (sv)), SvPV_nolen(PL_Sv))
5f1478c3 1994# define SvPVx_nolen_const(sv) ((PL_Sv = (sv)), SvPV_nolen_const(PL_Sv))
3629b4ec
KW
1995# define SvPVutf8x(sv, len) ((PL_Sv = (sv)), SvPVutf8(PL_Sv, len))
1996# define SvPVbytex(sv, len) ((PL_Sv = (sv)), SvPVbyte(PL_Sv, len))
002e4c74 1997# define SvPVbytex_nolen(sv) ((PL_Sv = (sv)), SvPVbyte_nolen(PL_Sv))
baca2b92
DM
1998#endif /* __GNU__ */
1999
630b72b0
DD
2000#define SvPVXtrue(sv) ( \
2001 ((XPV*)SvANY((sv))) \
2002 && ( \
1f4fbd3b
MS
2003 ((XPV*)SvANY((sv)))->xpv_cur > 1 \
2004 || ( \
2005 ((XPV*)SvANY((sv)))->xpv_cur \
2006 && *(sv)->sv_u.svu_pv != '0' \
2007 ) \
630b72b0
DD
2008 ) \
2009)
2010
e3918bb7
FC
2011#define SvIsCOW(sv) (SvFLAGS(sv) & SVf_IsCOW)
2012#define SvIsCOW_on(sv) (SvFLAGS(sv) |= SVf_IsCOW)
2013#define SvIsCOW_off(sv) (SvFLAGS(sv) &= ~SVf_IsCOW)
46187eeb 2014#define SvIsCOW_shared_hash(sv) (SvIsCOW(sv) && SvLEN(sv) == 0)
baca2b92 2015
bdd68bc3 2016#define SvSHARED_HEK_FROM_PV(pvx) \
1f4fbd3b 2017 ((struct hek*)(pvx - STRUCT_OFFSET(struct hek, hek_key)))
fb857162
KW
2018/*
2019=for apidoc Am|struct hek*|SvSHARED_HASH|SV * sv
2020Returns the hash for C<sv> created by C<L</newSVpvn_share>>.
2021
2022=cut
2023*/
0a356b31 2024#define SvSHARED_HASH(sv) (0 + SvSHARED_HEK_FROM_PV(SvPVX_const(sv))->hek_hash)
c158a4fd 2025
baca2b92 2026/* flag values for sv_*_flags functions */
5dfbfbd5 2027#define SV_UTF8_NO_ENCODING 0 /* No longer used */
49e7c422
KW
2028
2029/*
2030=for apidoc AmnhD||SV_UTF8_NO_ENCODING
2031
2032=cut
2033*/
2034
baca2b92
DM
2035#define SV_IMMEDIATE_UNREF 1
2036#define SV_GMAGIC 2
765f542d 2037#define SV_COW_DROP_PV 4
5fcdf167 2038#define SV_NOSTEAL 16
32a5c6ec
NC
2039#define SV_CONST_RETURN 32
2040#define SV_MUTABLE_RETURN 64
bddd5118 2041#define SV_SMAGIC 128
c1c21316 2042#define SV_HAS_TRAILING_NUL 256
34482cd6 2043#define SV_COW_SHARED_HASH_KEYS 512
cb23d5b1 2044/* This one is only enabled for PERL_OLD_COPY_ON_WRITE */
b7adcee4
FC
2045/* XXX This flag actually enabled for any COW. But it appears not to do
2046 anything. Can we just remove it? Or will it serve some future
2047 purpose. */
cb23d5b1 2048#define SV_COW_OTHER_PVS 1024
9f621bb0
NC
2049/* Make sv_2pv_flags return NULL if something is undefined. */
2050#define SV_UNDEF_RETURNS_NULL 2048
b3ab6785
KW
2051/* Tell sv_utf8_upgrade() to not check to see if an upgrade is really needed.
2052 * This is used when the caller has already determined it is, and avoids
2053 * redundant work */
2054#define SV_FORCE_UTF8_UPGRADE 4096
aee036bb
DM
2055/* if (after resolving magic etc), the SV is found to be overloaded,
2056 * don't call the overload magic, just return as-is */
2057#define SV_SKIP_OVERLOAD 8192
20c88bf7
FC
2058#define SV_CATBYTES 16384
2059#define SV_CATUTF8 32768
34482cd6
NC
2060
2061/* The core is safe for this COW optimisation. XS code on CPAN may not be.
2062 So only default to doing the COW setup if we're in the core.
2063 */
2064#ifdef PERL_CORE
2065# ifndef SV_DO_COW_SVSETSV
cb23d5b1 2066# define SV_DO_COW_SVSETSV SV_COW_SHARED_HASH_KEYS|SV_COW_OTHER_PVS
34482cd6
NC
2067# endif
2068#endif
2069
2070#ifndef SV_DO_COW_SVSETSV
2071# define SV_DO_COW_SVSETSV 0
2072#endif
2073
765f542d 2074
5abc721d
NC
2075#define sv_unref(sv) sv_unref_flags(sv, 0)
2076#define sv_force_normal(sv) sv_force_normal_flags(sv, 0)
47518d95
NC
2077#define sv_usepvn(sv, p, l) sv_usepvn_flags(sv, p, l, 0)
2078#define sv_usepvn_mg(sv, p, l) sv_usepvn_flags(sv, p, l, SV_SMAGIC)
174c73e3 2079
46187eeb
NC
2080/* We are about to replace the SV's current value. So if it's copy on write
2081 we need to normalise it. Use the SV_COW_DROP_PV flag hint to say that
2082 the value is about to get thrown away, so drop the PV rather than go to
2083 the effort of making a read-write copy only for it to get immediately
2084 discarded. */
765f542d
NC
2085
2086#define SV_CHECK_THINKFIRST_COW_DROP(sv) if (SvTHINKFIRST(sv)) \
1f4fbd3b 2087 sv_force_normal_flags(sv, SV_COW_DROP_PV)
46187eeb 2088
93c10d60 2089#ifdef PERL_COPY_ON_WRITE
db2c6cb3 2090# define SvCANCOW(sv) \
1f4fbd3b
MS
2091 (SvIsCOW(sv) \
2092 ? SvLEN(sv) ? CowREFCNT(sv) != SV_COW_REFCNT_MAX : 1 \
2093 : (SvFLAGS(sv) & CAN_COW_MASK) == CAN_COW_FLAGS \
2094 && SvCUR(sv)+1 < SvLEN(sv))
db2c6cb3
FC
2095 /* Note: To allow 256 COW "copies", a refcnt of 0 means 1. */
2096# define CowREFCNT(sv) (*(U8 *)(SvPVX(sv)+SvLEN(sv)-1))
1381ccb1 2097# define SV_COW_REFCNT_MAX nBIT_UMAX(sizeof(U8) * CHARBITS)
f7a8268c 2098# define CAN_COW_MASK (SVf_POK|SVf_ROK|SVp_POK|SVf_FAKE| \
1f4fbd3b 2099 SVf_OOK|SVf_BREAK|SVf_READONLY|SVf_PROTECT)
b7adcee4 2100#endif
ed252734 2101
ed252734
NC
2102#define CAN_COW_FLAGS (SVp_POK|SVf_POK)
2103
765f542d 2104#define SV_CHECK_THINKFIRST(sv) if (SvTHINKFIRST(sv)) \
1f4fbd3b 2105 sv_force_normal_flags(sv, 0)
765f542d
NC
2106
2107
baca2b92
DM
2108/* all these 'functions' are now just macros */
2109
2110#define sv_pv(sv) SvPV_nolen(sv)
2111#define sv_pvutf8(sv) SvPVutf8_nolen(sv)
2112#define sv_pvbyte(sv) SvPVbyte_nolen(sv)
2113
2114#define sv_pvn_force_nomg(sv, lp) sv_pvn_force_flags(sv, lp, 0)
b3ab6785 2115#define sv_utf8_upgrade_flags(sv, flags) sv_utf8_upgrade_flags_grow(sv, flags, 0)
baca2b92 2116#define sv_utf8_upgrade_nomg(sv) sv_utf8_upgrade_flags(sv, 0)
423ce623
P
2117#define sv_utf8_downgrade(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, SV_GMAGIC)
2118#define sv_utf8_downgrade_nomg(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, 0)
baca2b92 2119#define sv_catpvn_nomg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, 0)
9dcc53ea 2120#define sv_catpv_nomg(dsv, sstr) sv_catpv_flags(dsv, sstr, 0)
34482cd6 2121#define sv_setsv(dsv, ssv) \
1f4fbd3b 2122 sv_setsv_flags(dsv, ssv, SV_GMAGIC|SV_DO_COW_SVSETSV)
34482cd6 2123#define sv_setsv_nomg(dsv, ssv) sv_setsv_flags(dsv, ssv, SV_DO_COW_SVSETSV)
baca2b92
DM
2124#define sv_catsv(dsv, ssv) sv_catsv_flags(dsv, ssv, SV_GMAGIC)
2125#define sv_catsv_nomg(dsv, ssv) sv_catsv_flags(dsv, ssv, 0)
b347df82 2126#define sv_catsv_mg(dsv, ssv) sv_catsv_flags(dsv, ssv, SV_GMAGIC|SV_SMAGIC)
baca2b92 2127#define sv_catpvn(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC)
37ee558d 2128#define sv_catpvn_mg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC|SV_SMAGIC);
4bac9ae4
CS
2129#define sv_copypv(dsv, ssv) sv_copypv_flags(dsv, ssv, SV_GMAGIC)
2130#define sv_copypv_nomg(dsv, ssv) sv_copypv_flags(dsv, ssv, 0)
baca2b92 2131#define sv_2pv(sv, lp) sv_2pv_flags(sv, lp, SV_GMAGIC)
cb2f1b7b 2132#define sv_2pv_nolen(sv) sv_2pv(sv, 0)
757fc329 2133#define sv_2pvbyte(sv, lp) sv_2pvbyte_flags(sv, lp, SV_GMAGIC)
cb2f1b7b 2134#define sv_2pvbyte_nolen(sv) sv_2pvbyte(sv, 0)
757fc329 2135#define sv_2pvutf8(sv, lp) sv_2pvutf8_flags(sv, lp, SV_GMAGIC)
cb2f1b7b 2136#define sv_2pvutf8_nolen(sv) sv_2pvutf8(sv, 0)
baca2b92
DM
2137#define sv_2pv_nomg(sv, lp) sv_2pv_flags(sv, lp, 0)
2138#define sv_pvn_force(sv, lp) sv_pvn_force_flags(sv, lp, SV_GMAGIC)
2139#define sv_utf8_upgrade(sv) sv_utf8_upgrade_flags(sv, SV_GMAGIC)
891f9566
YST
2140#define sv_2iv(sv) sv_2iv_flags(sv, SV_GMAGIC)
2141#define sv_2uv(sv) sv_2uv_flags(sv, SV_GMAGIC)
39d5de13 2142#define sv_2nv(sv) sv_2nv_flags(sv, SV_GMAGIC)
078504b2 2143#define sv_eq(sv1, sv2) sv_eq_flags(sv1, sv2, SV_GMAGIC)
e8c9c9d4
NC
2144#define sv_cmp(sv1, sv2) sv_cmp_flags(sv1, sv2, SV_GMAGIC)
2145#define sv_cmp_locale(sv1, sv2) sv_cmp_locale_flags(sv1, sv2, SV_GMAGIC)
e17dadf3 2146#define sv_collxfrm(sv, nxp) sv_collxfrm_flags(sv, nxp, SV_GMAGIC)
06c841cf 2147#define sv_2bool(sv) sv_2bool_flags(sv, SV_GMAGIC)
4bac9ae4 2148#define sv_2bool_nomg(sv) sv_2bool_flags(sv, 0)
84335ee9 2149#define sv_insert(bigstr, offset, len, little, littlelen) \
1f4fbd3b
MS
2150 Perl_sv_insert_flags(aTHX_ (bigstr),(offset), (len), (little), \
2151 (littlelen), SV_GMAGIC)
108cb980 2152#define sv_mortalcopy(sv) \
1f4fbd3b 2153 Perl_sv_mortalcopy_flags(aTHX_ sv, SV_GMAGIC|SV_DO_COW_SVSETSV)
f34d8cdd 2154#define sv_cathek(sv,hek) \
1f4fbd3b
MS
2155 STMT_START { \
2156 HEK * const bmxk = hek; \
2157 sv_catpvn_flags(sv, HEK_KEY(bmxk), HEK_LEN(bmxk), \
2158 HEK_UTF8(bmxk) ? SV_CATUTF8 : SV_CATBYTES); \
2159 } STMT_END
baca2b92 2160
db79b45b 2161/* Should be named SvCatPVN_utf8_upgrade? */
4bac9ae4 2162#define sv_catpvn_nomg_utf8_upgrade(dsv, sstr, slen, nsv) \
1f4fbd3b
MS
2163 STMT_START { \
2164 if (!(nsv)) \
2165 nsv = newSVpvn_flags(sstr, slen, SVs_TEMP); \
2166 else \
2167 sv_setpvn(nsv, sstr, slen); \
2168 SvUTF8_off(nsv); \
2169 sv_utf8_upgrade(nsv); \
2170 sv_catsv_nomg(dsv, nsv); \
2171 } STMT_END
64534138 2172#define sv_catpvn_nomg_maybeutf8(dsv, sstr, slen, is_utf8) \
1f4fbd3b 2173 sv_catpvn_flags(dsv, sstr, slen, (is_utf8)?SV_CATUTF8:SV_CATBYTES)
79072805 2174
25fdce4a 2175#if defined(PERL_CORE) || defined(PERL_EXT)
aec43834
FC
2176# define sv_or_pv_len_utf8(sv, pv, bytelen) \
2177 (SvGAMAGIC(sv) \
1f4fbd3b
MS
2178 ? utf8_length((U8 *)(pv), (U8 *)(pv)+(bytelen)) \
2179 : sv_len_utf8(sv))
aec43834
FC
2180#endif
2181
954c1994 2182/*
ac950c89
KW
2183=for apidoc newRV
2184=for apidoc_item ||newRV_inc|
954c1994 2185
ac950c89
KW
2186These are identical. They create an RV wrapper for an SV. The reference count
2187for the original SV is incremented.
954c1994
GS
2188
2189=cut
2190*/
2191
5f05dabc 2192#define newRV_inc(sv) newRV(sv)
5f05dabc 2193
796b6530 2194/* the following macros update any magic values this C<sv> is associated with */
79072805 2195
954c1994 2196/*
574e093e 2197=for apidoc_section $SV
ccfc67b7 2198
954c1994 2199=for apidoc Am|void|SvGETMAGIC|SV* sv
8890fded 2200Invokes C<L</mg_get>> on an SV if it has 'get' magic. For example, this
f7e029ab 2201will call C<FETCH> on a tied variable. This macro evaluates its
954c1994
GS
2202argument more than once.
2203
2204=for apidoc Am|void|SvSETMAGIC|SV* sv
8890fded 2205Invokes C<L</mg_set>> on an SV if it has 'set' magic. This is necessary
f7e029ab
FC
2206after modifying a scalar, in case it is a magical variable like C<$|>
2207or a tied variable (it calls C<STORE>). This macro evaluates its
954c1994
GS
2208argument more than once.
2209
87ef9da8 2210=for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv
574e093e
KW
2211=for apidoc_item SvSetMagicSV
2212=for apidoc_item SvSetSV_nosteal
2213=for apidoc_item SvSetMagicSV_nosteal
2214
2215if C<dsv> is the same as C<ssv>, these do nothing. Otherwise they all call
2216some form of C<L</sv_setsv>>. They may evaluate their arguments more than
2217once.
954c1994 2218
574e093e 2219The only differences are:
954c1994 2220
574e093e
KW
2221C<SvSetMagicSV> and C<SvSetMagicSV_nosteal> perform any required 'set' magic
2222afterwards on the destination SV; C<SvSetSV> and C<SvSetSV_nosteal> do not.
645c22ef 2223
574e093e
KW
2224C<SvSetSV_nosteal> C<SvSetMagicSV_nosteal> call a non-destructive version of
2225C<sv_setsv>.
645c22ef 2226
68795e93 2227=for apidoc Am|void|SvSHARE|SV* sv
796b6530 2228Arranges for C<sv> to be shared between threads if a suitable module
68795e93
NIS
2229has been loaded.
2230
2231=for apidoc Am|void|SvLOCK|SV* sv
796b6530 2232Arranges for a mutual exclusion lock to be obtained on C<sv> if a suitable module
68795e93
NIS
2233has been loaded.
2234
2235=for apidoc Am|void|SvUNLOCK|SV* sv
796b6530 2236Releases a mutual exclusion lock on C<sv> if a suitable module
68795e93
NIS
2237has been loaded.
2238
3f620621 2239=for apidoc_section $SV
ccfc67b7 2240
679ac26e 2241=for apidoc Am|char *|SvGROW|SV* sv|STRLEN len
954c1994
GS
2242Expands the character buffer in the SV so that it has room for the
2243indicated number of bytes (remember to reserve space for an extra trailing
6602b933 2244C<NUL> character). Calls C<sv_grow> to perform the expansion if necessary.
72d33970 2245Returns a pointer to the character
796b6530 2246buffer. SV must be of type >= C<SVt_PV>. One
4b1e7f06 2247alternative is to call C<sv_grow> if you are not sure of the type of SV.
954c1994 2248
d8732c60
KW
2249You might mistakenly think that C<len> is the number of bytes to add to the
2250existing size, but instead it is the total size C<sv> should be.
2251
45661033
YO
2252=for apidoc Am|char *|SvPVCLEAR|SV* sv
2253Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
2254properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
2255
954c1994
GS
2256=cut
2257*/
2258
45661033 2259#define SvPVCLEAR(sv) sv_setpv_bufsize(sv,0,0)
16c91539
BM
2260#define SvSHARE(sv) PL_sharehook(aTHX_ sv)
2261#define SvLOCK(sv) PL_lockhook(aTHX_ sv)
2262#define SvUNLOCK(sv) PL_unlockhook(aTHX_ sv)
2263#define SvDESTROYABLE(sv) PL_destroyhook(aTHX_ sv)
68795e93 2264
5d9574c1
DM
2265#define SvGETMAGIC(x) ((void)(UNLIKELY(SvGMAGICAL(x)) && mg_get(x)))
2266#define SvSETMAGIC(x) STMT_START { if (UNLIKELY(SvSMAGICAL(x))) mg_set(x); } STMT_END
79072805 2267
54310121 2268#define SvSetSV_and(dst,src,finally) \
1f4fbd3b
MS
2269 STMT_START { \
2270 if (LIKELY((dst) != (src))) { \
2271 sv_setsv(dst, src); \
2272 finally; \
2273 } \
2274 } STMT_END
54310121 2275#define SvSetSV_nosteal_and(dst,src,finally) \
1f4fbd3b
MS
2276 STMT_START { \
2277 if (LIKELY((dst) != (src))) { \
2278 sv_setsv_flags(dst, src, SV_GMAGIC | SV_NOSTEAL | SV_DO_COW_SVSETSV); \
2279 finally; \
2280 } \
2281 } STMT_END
79072805 2282
54310121 2283#define SvSetSV(dst,src) \
1f4fbd3b 2284 SvSetSV_and(dst,src,/*nothing*/;)
54310121 2285#define SvSetSV_nosteal(dst,src) \
1f4fbd3b 2286 SvSetSV_nosteal_and(dst,src,/*nothing*/;)
54310121
PP
2287
2288#define SvSetMagicSV(dst,src) \
1f4fbd3b 2289 SvSetSV_and(dst,src,SvSETMAGIC(dst))
54310121 2290#define SvSetMagicSV_nosteal(dst,src) \
1f4fbd3b 2291 SvSetSV_nosteal_and(dst,src,SvSETMAGIC(dst))
54310121 2292
db79b45b 2293
1045810a 2294#if !defined(SKIP_DEBUGGING)
79072805 2295#define SvPEEK(sv) sv_peek(sv)
3967c732
JD
2296#else
2297#define SvPEEK(sv) ""
2298#endif
79072805 2299
7c123f9d
DM
2300/* Is this a per-interpreter immortal SV (rather than global)?
2301 * These should either occupy adjacent entries in the interpreter struct
2302 * (MULTIPLICITY) or adjacent elements of PL_sv_immortals[] otherwise.
2303 * The unsigned (Size_t) cast avoids the need for a second < 0 condition.
2304 */
2305#define SvIMMORTAL_INTERP(sv) ((Size_t)((sv) - &PL_sv_yes) < 4)
2306
2307/* Does this immortal have a true value? Currently only PL_sv_yes does. */
2308#define SvIMMORTAL_TRUE(sv) ((sv) == &PL_sv_yes)
2309
2310/* the SvREADONLY() test is to quickly reject most SVs */
2311#define SvIMMORTAL(sv) \
2312 ( SvREADONLY(sv) \
2313 && (SvIMMORTAL_INTERP(sv) || (sv) == &PL_sv_placeholder))
36477c24 2314
fe54beba
DM
2315#ifdef DEBUGGING
2316 /* exercise the immortal resurrection code in sv_free2() */
2317# define SvREFCNT_IMMORTAL 1000
2318#else
2319# define SvREFCNT_IMMORTAL ((~(U32)0)/2)
2320#endif
2321
567f3b56
TC
2322/*
2323=for apidoc Am|SV *|boolSV|bool b
2324
2325Returns a true SV if C<b> is a true value, or a false SV if C<b> is 0.
2326
fbe13c60 2327See also C<L</PL_sv_yes>> and C<L</PL_sv_no>>.
567f3b56
TC
2328
2329=cut
2330*/
2331
3280af22 2332#define boolSV(b) ((b) ? &PL_sv_yes : &PL_sv_no)
54310121 2333
79072805 2334#define isGV(sv) (SvTYPE(sv) == SVt_PVGV)
f7877b28
NC
2335/* If I give every macro argument a different name, then there won't be bugs
2336 where nested macros get confused. Been there, done that. */
1d31276d
KW
2337/*
2338=for apidoc Am|bool|isGV_with_GP|SV * sv
2339Returns a boolean as to whether or not C<sv> is a GV with a pointer to a GP
2340(glob pointer).
2341
2342=cut
2343*/
f7877b28 2344#define isGV_with_GP(pwadak) \
1f4fbd3b
MS
2345 (((SvFLAGS(pwadak) & (SVp_POK|SVpgv_GP)) == SVpgv_GP) \
2346 && (SvTYPE(pwadak) == SVt_PVGV || SvTYPE(pwadak) == SVt_PVLV))
2e5b91de 2347#define isGV_with_GP_on(sv) STMT_START { \
1f4fbd3b
MS
2348 assert (SvTYPE(sv) == SVt_PVGV || SvTYPE(sv) == SVt_PVLV); \
2349 assert (!SvPOKp(sv)); \
2350 assert (!SvIOKp(sv)); \
2351 (SvFLAGS(sv) |= SVpgv_GP); \
2e5b91de
NC
2352 } STMT_END
2353#define isGV_with_GP_off(sv) STMT_START { \
1f4fbd3b
MS
2354 assert (SvTYPE(sv) == SVt_PVGV || SvTYPE(sv) == SVt_PVLV); \
2355 assert (!SvPOKp(sv)); \
2356 assert (!SvIOKp(sv)); \
2357 (SvFLAGS(sv) &= ~SVpgv_GP); \
2e5b91de 2358 } STMT_END
f5b4df4d
FC
2359#ifdef PERL_CORE
2360# define isGV_or_RVCV(kadawp) \
2361 (isGV(kadawp) || (SvROK(kadawp) && SvTYPE(SvRV(kadawp)) == SVt_PVCV))
2362#endif
8d919b0a
FC
2363#define isREGEXP(sv) \
2364 (SvTYPE(sv) == SVt_REGEXP \
df6b4bd5 2365 || (SvFLAGS(sv) & (SVTYPEMASK|SVpgv_GP|SVf_FAKE)) \
1f4fbd3b 2366 == (SVt_PVLV|SVf_FAKE))
2e5b91de 2367
79072805 2368
bba82a09 2369#ifdef PERL_ANY_COW
db2c6cb3 2370# define SvGROW(sv,len) \
1f4fbd3b 2371 (SvIsCOW(sv) || SvLEN(sv) < (len) ? sv_grow(sv,len) : SvPVX(sv))
db2c6cb3 2372#else
6bbd724f 2373# define SvGROW(sv,len) (SvLEN(sv) < (len) ? sv_grow(sv,len) : SvPVX(sv))
db2c6cb3 2374#endif
6bbd724f
DM
2375#define SvGROW_mutable(sv,len) \
2376 (SvLEN(sv) < (len) ? sv_grow(sv,len) : SvPVX_mutable(sv))
933fea7f 2377#define Sv_Grow sv_grow
3d35f11b 2378
a0739874
DM
2379#define CLONEf_COPY_STACKS 1
2380#define CLONEf_KEEP_PTR_TABLE 2
c43294b8 2381#define CLONEf_CLONE_HOST 4
0405e91e 2382#define CLONEf_JOIN_IN 8
a0739874 2383
8cf8f3d1 2384struct clone_params {
d2d73c3e
AB
2385 AV* stashes;
2386 UV flags;
59b40662 2387 PerlInterpreter *proto_perl;
1db366cc 2388 PerlInterpreter *new_perl;
d08d57ef 2389 AV *unreferenced;
8cf8f3d1 2390};
102d3b8a 2391
238f2c13
P
2392/* SV_NOSTEAL prevents TEMP buffers being, well, stolen, and saves games
2393 with SvTEMP_off and SvTEMP_on round a call to sv_setsv. */
2394#define newSVsv(sv) newSVsv_flags((sv), SV_GMAGIC|SV_NOSTEAL)
2395#define newSVsv_nomg(sv) newSVsv_flags((sv), SV_NOSTEAL)
2396
102d3b8a 2397/*
d106cb46 2398=for apidoc Am|SV*|newSVpvn_utf8|const char* s|STRLEN len|U32 utf8
740cce10 2399
30a15352 2400Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
796b6530 2401characters) into it. If C<utf8> is true, calls
740cce10
NC
2402C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
2403
2404=cut
2405*/
2406
2407#define newSVpvn_utf8(s, len, u) newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
2408
2409/*
35e035cc
FC
2410=for apidoc Amx|SV*|newSVpadname|PADNAME *pn
2411
0f94cb1f 2412Creates a new SV containing the pad name.
35e035cc
FC
2413
2414=cut
2415*/
2416
0f94cb1f 2417#define newSVpadname(pn) newSVpvn_utf8(PadnamePV(pn), PadnameLEN(pn), TRUE)
35e035cc
FC
2418
2419/*
d106cb46 2420=for apidoc Am|void|SvOOK_offset|SV*sv|STRLEN len
69240efd 2421
796b6530 2422Reads into C<len> the offset from C<SvPVX> back to the true start of the
69240efd 2423allocated buffer, which will be non-zero if C<sv_chop> has been used to
8554e7a0 2424efficiently remove characters from start of the buffer. Implemented as a
2d7f6611
KW
2425macro, which takes the address of C<len>, which must be of type C<STRLEN>.
2426Evaluates C<sv> more than once. Sets C<len> to 0 if C<SvOOK(sv)> is false.
69240efd
NC
2427
2428=cut
2429*/
2430
2431#ifdef DEBUGGING
2432/* Does the bot know something I don't?
243310:28 <@Nicholas> metabatman
243410:28 <+meta> Nicholas: crash
2435*/
2436# define SvOOK_offset(sv, offset) STMT_START { \
1f4fbd3b
MS
2437 STATIC_ASSERT_STMT(sizeof(offset) == sizeof(STRLEN)); \
2438 if (SvOOK(sv)) { \
2439 const U8 *_crash = (U8*)SvPVX_const(sv); \
2440 (offset) = *--_crash; \
2441 if (!(offset)) { \
2442 _crash -= sizeof(STRLEN); \
2443 Copy(_crash, (U8 *)&(offset), sizeof(STRLEN), U8); \
2444 } \
2445 { \
2446 /* Validate the preceding buffer's sentinels to \
2447 verify that no-one is using it. */ \
2448 const U8 *const _bonk = (U8*)SvPVX_const(sv) - (offset);\
2449 while (_crash > _bonk) { \
2450 --_crash; \
2451 assert (*_crash == (U8)PTR2UV(_crash)); \
2452 } \
2453 } \
2454 } else { \
2455 (offset) = 0; \
2456 } \
69240efd
NC
2457 } STMT_END
2458#else
2459 /* This is the same code, but avoids using any temporary variables: */
2460# define SvOOK_offset(sv, offset) STMT_START { \
1f4fbd3b
MS
2461 STATIC_ASSERT_STMT(sizeof(offset) == sizeof(STRLEN)); \
2462 if (SvOOK(sv)) { \
2463 (offset) = ((U8*)SvPVX_const(sv))[-1]; \
2464 if (!(offset)) { \
2465 Copy(SvPVX_const(sv) - 1 - sizeof(STRLEN), \
2466 (U8*)&(offset), sizeof(STRLEN), U8); \
2467 } \
2468 } else { \
2469 (offset) = 0; \
2470 } \
69240efd
NC
2471 } STMT_END
2472#endif
85dca89a
NC
2473
2474#define newIO() MUTABLE_IO(newSV_type(SVt_PVIO))
2475
d5722fbc
KW
2476#if defined(PERL_CORE) || defined(PERL_EXT)
2477
2478# define SV_CONST(name) \
1f4fbd3b
MS
2479 PL_sv_consts[SV_CONST_##name] \
2480 ? PL_sv_consts[SV_CONST_##name] \
2481 : (PL_sv_consts[SV_CONST_##name] = newSVpv_share(#name, 0))
a38ab475 2482
d5722fbc
KW
2483# define SV_CONST_TIESCALAR 0
2484# define SV_CONST_TIEARRAY 1
2485# define SV_CONST_TIEHASH 2
2486# define SV_CONST_TIEHANDLE 3
2487
2488# define SV_CONST_FETCH 4
2489# define SV_CONST_FETCHSIZE 5
2490# define SV_CONST_STORE 6
2491# define SV_CONST_STORESIZE 7
2492# define SV_CONST_EXISTS 8
2493
2494# define SV_CONST_PUSH 9
2495# define SV_CONST_POP 10
2496# define SV_CONST_SHIFT 11
2497# define SV_CONST_UNSHIFT 12
2498# define SV_CONST_SPLICE 13
2499# define SV_CONST_EXTEND 14
2500
2501# define SV_CONST_FIRSTKEY 15
2502# define SV_CONST_NEXTKEY 16
2503# define SV_CONST_SCALAR 17
2504
2505# define SV_CONST_OPEN 18
2506# define SV_CONST_WRITE 19
2507# define SV_CONST_PRINT 20
2508# define SV_CONST_PRINTF 21
2509# define SV_CONST_READ 22
2510# define SV_CONST_READLINE 23
2511# define SV_CONST_GETC 24
2512# define SV_CONST_SEEK 25
2513# define SV_CONST_TELL 26
2514# define SV_CONST_EOF 27
2515# define SV_CONST_BINMODE 28
2516# define SV_CONST_FILENO 29
2517# define SV_CONST_CLOSE 30
2518
2519# define SV_CONST_DELETE 31
2520# define SV_CONST_CLEAR 32
2521# define SV_CONST_UNTIE 33
2522# define SV_CONST_DESTROY 34
2523#endif
a38ab475
RZ
2524
2525#define SV_CONSTS_COUNT 35
2526
69240efd 2527/*
82fce3d0
DM
2528 * Bodyless IVs and NVs!
2529 *
2530 * Since 5.9.2, we can avoid allocating a body for SVt_IV-type SVs.
2531 * Since the larger IV-holding variants of SVs store their integer
2532 * values in their respective bodies, the family of SvIV() accessor
2533 * macros would naively have to branch on the SV type to find the
2534 * integer value either in the HEAD or BODY. In order to avoid this
2535 * expensive branch, a clever soul has deployed a great hack:
2536 * We set up the SvANY pointer such that instead of pointing to a
2537 * real body, it points into the memory before the location of the
2538 * head. We compute this pointer such that the location of
2539 * the integer member of the hypothetical body struct happens to
2540 * be the same as the location of the integer member of the bodyless
2541 * SV head. This now means that the SvIV() family of accessors can
2542 * always read from the (hypothetical or real) body via SvANY.
2543 *
2544 * Since the 5.21 dev series, we employ the same trick for NVs
2545 * if the architecture can support it (NVSIZE <= IVSIZE).
2546 */
2547
2548/* The following two macros compute the necessary offsets for the above
2549 * trick and store them in SvANY for SvIV() (and friends) to use. */
2550
2551#ifdef PERL_CORE
2552# define SET_SVANY_FOR_BODYLESS_IV(sv) \
1f4fbd3b 2553 SvANY(sv) = (XPVIV*)((char*)&(sv->sv_u.svu_iv) \
82fce3d0
DM
2554 - STRUCT_OFFSET(XPVIV, xiv_iv))
2555
2556# define SET_SVANY_FOR_BODYLESS_NV(sv) \
1f4fbd3b 2557 SvANY(sv) = (XPVNV*)((char*)&(sv->sv_u.svu_nv) \
82fce3d0
DM
2558 - STRUCT_OFFSET(XPVNV, xnv_u.xnv_nv))
2559#endif
2560
2561/*
14d04a33 2562 * ex: set ts=8 sts=4 sw=4 et:
102d3b8a 2563 */