This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
The test requires perlio.
[perl5.git] / sv.h
CommitLineData
a0d0e21e 1/* sv.h
79072805 2 *
eb1102fc 3 * Copyright (c) 1991-2002, Larry Wall
79072805
LW
4 *
5 * You may distribute under the terms of either the GNU General Public
6 * License or the Artistic License, as specified in the README file.
7 *
79072805
LW
8 */
9
a0d0e21e
LW
10#ifdef sv_flags
11#undef sv_flags /* Convex has this in <signal.h> for sigvec() */
12#endif
13
954c1994 14/*
ccfc67b7
JH
15=head1 SV Flags
16
954c1994 17=for apidoc AmU||svtype
8cf8f3d1 18An enum of flags for Perl types. These are found in the file B<sv.h>
954c1994
GS
19in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
20
21=for apidoc AmU||SVt_PV
22Pointer type flag for scalars. See C<svtype>.
23
24=for apidoc AmU||SVt_IV
25Integer type flag for scalars. See C<svtype>.
26
27=for apidoc AmU||SVt_NV
28Double type flag for scalars. See C<svtype>.
29
30=for apidoc AmU||SVt_PVMG
31Type flag for blessed scalars. See C<svtype>.
32
33=for apidoc AmU||SVt_PVAV
34Type flag for arrays. See C<svtype>.
35
36=for apidoc AmU||SVt_PVHV
37Type flag for hashes. See C<svtype>.
38
39=for apidoc AmU||SVt_PVCV
40Type flag for code refs. See C<svtype>.
41
42=cut
43*/
44
79072805 45typedef enum {
a0d0e21e
LW
46 SVt_NULL, /* 0 */
47 SVt_IV, /* 1 */
48 SVt_NV, /* 2 */
49 SVt_RV, /* 3 */
50 SVt_PV, /* 4 */
51 SVt_PVIV, /* 5 */
52 SVt_PVNV, /* 6 */
53 SVt_PVMG, /* 7 */
54 SVt_PVBM, /* 8 */
55 SVt_PVLV, /* 9 */
56 SVt_PVAV, /* 10 */
57 SVt_PVHV, /* 11 */
58 SVt_PVCV, /* 12 */
59 SVt_PVGV, /* 13 */
60 SVt_PVFM, /* 14 */
61 SVt_PVIO /* 15 */
79072805
LW
62} svtype;
63
79072805
LW
64/* Using C's structural equivalence to help emulate C++ inheritance here... */
65
5e045b90 66struct STRUCT_SV { /* struct sv { */
463ee0b2 67 void* sv_any; /* pointer to something */
79072805 68 U32 sv_refcnt; /* how many references to us */
8990e307 69 U32 sv_flags; /* what we are */
79072805
LW
70};
71
72struct gv {
463ee0b2 73 XPVGV* sv_any; /* pointer to something */
79072805 74 U32 sv_refcnt; /* how many references to us */
8990e307 75 U32 sv_flags; /* what we are */
79072805
LW
76};
77
78struct cv {
232e078e 79 XPVCV* sv_any; /* pointer to something */
79072805 80 U32 sv_refcnt; /* how many references to us */
8990e307 81 U32 sv_flags; /* what we are */
79072805
LW
82};
83
84struct av {
463ee0b2 85 XPVAV* sv_any; /* pointer to something */
79072805 86 U32 sv_refcnt; /* how many references to us */
8990e307 87 U32 sv_flags; /* what we are */
79072805
LW
88};
89
90struct hv {
463ee0b2 91 XPVHV* sv_any; /* pointer to something */
79072805 92 U32 sv_refcnt; /* how many references to us */
8990e307
LW
93 U32 sv_flags; /* what we are */
94};
95
96struct io {
97 XPVIO* sv_any; /* pointer to something */
98 U32 sv_refcnt; /* how many references to us */
99 U32 sv_flags; /* what we are */
79072805
LW
100};
101
954c1994 102/*
ccfc67b7
JH
103=head1 SV Manipulation Functions
104
954c1994
GS
105=for apidoc Am|U32|SvREFCNT|SV* sv
106Returns the value of the object's reference count.
107
108=for apidoc Am|SV*|SvREFCNT_inc|SV* sv
109Increments the reference count of the given SV.
110
111=for apidoc Am|void|SvREFCNT_dec|SV* sv
112Decrements the reference count of the given SV.
113
114=for apidoc Am|svtype|SvTYPE|SV* sv
115Returns the type of the SV. See C<svtype>.
116
117=for apidoc Am|void|SvUPGRADE|SV* sv|svtype type
118Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
119perform the upgrade if necessary. See C<svtype>.
120
121=cut
122*/
123
463ee0b2 124#define SvANY(sv) (sv)->sv_any
79072805 125#define SvFLAGS(sv) (sv)->sv_flags
aeea060c 126#define SvREFCNT(sv) (sv)->sv_refcnt
a863c7d1 127
4d1ff10f 128#ifdef USE_5005THREADS
dce16143 129
3d35f11b
GS
130# if defined(VMS)
131# define ATOMIC_INC(count) __ATOMIC_INCREMENT_LONG(&count)
132# define ATOMIC_DEC_AND_TEST(res,count) res=(1==__ATOMIC_DECREMENT_LONG(&count))
133 # else
134# ifdef EMULATE_ATOMIC_REFCOUNTS
135 # define ATOMIC_INC(count) STMT_START { \
136 MUTEX_LOCK(&PL_svref_mutex); \
137 ++count; \
138 MUTEX_UNLOCK(&PL_svref_mutex); \
139 } STMT_END
140# define ATOMIC_DEC_AND_TEST(res,count) STMT_START { \
141 MUTEX_LOCK(&PL_svref_mutex); \
142 res = (--count == 0); \
143 MUTEX_UNLOCK(&PL_svref_mutex); \
144 } STMT_END
145# else
146# define ATOMIC_INC(count) atomic_inc(&count)
147# define ATOMIC_DEC_AND_TEST(res,count) (res = atomic_dec_and_test(&count))
148# endif /* EMULATE_ATOMIC_REFCOUNTS */
149# endif /* VMS */
dce16143
MB
150#else
151# define ATOMIC_INC(count) (++count)
83b0a010 152# define ATOMIC_DEC_AND_TEST(res, count) (res = (--count == 0))
4d1ff10f 153#endif /* USE_5005THREADS */
dce16143 154
a863c7d1 155#ifdef __GNUC__
dce16143
MB
156# define SvREFCNT_inc(sv) \
157 ({ \
158 SV *nsv = (SV*)(sv); \
159 if (nsv) \
160 ATOMIC_INC(SvREFCNT(nsv)); \
161 nsv; \
162 })
8990e307 163#else
4d1ff10f 164# if defined(CRIPPLED_CC) || defined(USE_5005THREADS)
3d35f11b
GS
165# if defined(VMS) && defined(__ALPHA)
166# define SvREFCNT_inc(sv) \
167 (PL_Sv=(SV*)(sv), (PL_Sv && __ATOMIC_INCREMENT_LONG(&(SvREFCNT(PL_Sv)))), (SV *)PL_Sv)
168# else
169# define SvREFCNT_inc(sv) sv_newref((SV*)sv)
170# endif
a863c7d1 171# else
dce16143 172# define SvREFCNT_inc(sv) \
6b88bc9c 173 ((PL_Sv=(SV*)(sv)), (PL_Sv && ATOMIC_INC(SvREFCNT(PL_Sv))), (SV*)PL_Sv)
a863c7d1 174# endif
8990e307
LW
175#endif
176
a863c7d1
MB
177#define SvREFCNT_dec(sv) sv_free((SV*)sv)
178
8990e307
LW
179#define SVTYPEMASK 0xff
180#define SvTYPE(sv) ((sv)->sv_flags & SVTYPEMASK)
79072805
LW
181
182#define SvUPGRADE(sv, mt) (SvTYPE(sv) >= mt || sv_upgrade(sv, mt))
183
8990e307
LW
184#define SVs_PADBUSY 0x00000100 /* reserved for tmp or my already */
185#define SVs_PADTMP 0x00000200 /* in use as tmp */
186#define SVs_PADMY 0x00000400 /* in use a "my" variable */
187#define SVs_TEMP 0x00000800 /* string is stealable? */
188#define SVs_OBJECT 0x00001000 /* is "blessed" */
189#define SVs_GMG 0x00002000 /* has magical get method */
190#define SVs_SMG 0x00004000 /* has magical set method */
191#define SVs_RMG 0x00008000 /* has random magical methods */
192
193#define SVf_IOK 0x00010000 /* has valid public integer value */
194#define SVf_NOK 0x00020000 /* has valid public numeric value */
195#define SVf_POK 0x00040000 /* has valid public pointer value */
196#define SVf_ROK 0x00080000 /* has a valid reference pointer */
a0d0e21e 197
748a9306 198#define SVf_FAKE 0x00100000 /* glob or lexical is just a copy */
8990e307 199#define SVf_OOK 0x00200000 /* has valid offset value */
645c22ef
DM
200#define SVf_BREAK 0x00400000 /* refcnt is artificially low - used
201 * by SV's in final arena cleanup */
8990e307
LW
202#define SVf_READONLY 0x00800000 /* may not be modified */
203
a0d0e21e 204
8990e307
LW
205#define SVp_IOK 0x01000000 /* has valid non-public integer value */
206#define SVp_NOK 0x02000000 /* has valid non-public numeric value */
207#define SVp_POK 0x04000000 /* has valid non-public pointer value */
208#define SVp_SCREAM 0x08000000 /* has been studied? */
209
5bc28da9
NIS
210#define SVf_UTF8 0x20000000 /* SvPVX is UTF-8 encoded */
211
430eacda 212#define SVf_THINKFIRST (SVf_READONLY|SVf_ROK|SVf_FAKE)
5bc28da9 213
a0d0e21e
LW
214#define SVf_OK (SVf_IOK|SVf_NOK|SVf_POK|SVf_ROK| \
215 SVp_IOK|SVp_NOK|SVp_POK)
216
9e7bc3e8 217#define SVf_AMAGIC 0x10000000 /* has magical overloaded methods */
a0d0e21e 218
8990e307
LW
219#define PRIVSHIFT 8
220
221/* Some private flags. */
222
f472eb5c 223/* SVpad_OUR may be set on SVt_PV{NV,MG,GV} types */
032d6771 224#define SVpad_OUR 0x80000000 /* pad name is "our" instead of "my" */
524189f1 225#define SVpad_TYPED 0x40000000 /* Typed Lexical */
032d6771 226
25da4f38
IZ
227#define SVf_IVisUV 0x80000000 /* use XPVUV instead of XPVIV */
228
229#define SVpfm_COMPILED 0x80000000 /* FORMLINE is compiled */
8990e307
LW
230
231#define SVpbm_VALID 0x80000000
bbce6d69 232#define SVpbm_TAIL 0x40000000
8990e307 233
25da4f38
IZ
234#define SVrepl_EVAL 0x40000000 /* Replacement part of s///e */
235
6bfc225d 236#define SVphv_SHAREKEYS 0x20000000 /* keys live on shared string table */
51594c39 237#define SVphv_LAZYDEL 0x40000000 /* entry in xhv_eiter must be deleted */
bf6bd887 238
810b8aa5
GS
239#define SVprv_WEAKREF 0x80000000 /* Weak reference */
240
ed6116ce
LW
241struct xrv {
242 SV * xrv_rv; /* pointer to another SV */
243};
244
79072805 245struct xpv {
ed6116ce
LW
246 char * xpv_pv; /* pointer to malloced string */
247 STRLEN xpv_cur; /* length of xpv_pv as a C string */
248 STRLEN xpv_len; /* allocated size */
79072805
LW
249};
250
251struct xpviv {
ed6116ce
LW
252 char * xpv_pv; /* pointer to malloced string */
253 STRLEN xpv_cur; /* length of xpv_pv as a C string */
254 STRLEN xpv_len; /* allocated size */
a0d0e21e 255 IV xiv_iv; /* integer value or pv offset */
79072805
LW
256};
257
ff68c719
PP
258struct xpvuv {
259 char * xpv_pv; /* pointer to malloced string */
260 STRLEN xpv_cur; /* length of xpv_pv as a C string */
261 STRLEN xpv_len; /* allocated size */
262 UV xuv_uv; /* unsigned value or pv offset */
263};
264
79072805 265struct xpvnv {
ed6116ce
LW
266 char * xpv_pv; /* pointer to malloced string */
267 STRLEN xpv_cur; /* length of xpv_pv as a C string */
268 STRLEN xpv_len; /* allocated size */
a0d0e21e 269 IV xiv_iv; /* integer value or pv offset */
65202027 270 NV xnv_nv; /* numeric value, if any */
79072805
LW
271};
272
6ee623d5 273/* These structure must match the beginning of struct xpvhv in hv.h. */
79072805 274struct xpvmg {
ed6116ce
LW
275 char * xpv_pv; /* pointer to malloced string */
276 STRLEN xpv_cur; /* length of xpv_pv as a C string */
277 STRLEN xpv_len; /* allocated size */
a0d0e21e 278 IV xiv_iv; /* integer value or pv offset */
65202027 279 NV xnv_nv; /* numeric value, if any */
79072805
LW
280 MAGIC* xmg_magic; /* linked list of magicalness */
281 HV* xmg_stash; /* class package */
282};
283
284struct xpvlv {
ed6116ce
LW
285 char * xpv_pv; /* pointer to malloced string */
286 STRLEN xpv_cur; /* length of xpv_pv as a C string */
287 STRLEN xpv_len; /* allocated size */
a0d0e21e 288 IV xiv_iv; /* integer value or pv offset */
65202027 289 NV xnv_nv; /* numeric value, if any */
79072805
LW
290 MAGIC* xmg_magic; /* linked list of magicalness */
291 HV* xmg_stash; /* class package */
8990e307 292
79072805
LW
293 STRLEN xlv_targoff;
294 STRLEN xlv_targlen;
295 SV* xlv_targ;
296 char xlv_type;
297};
298
299struct xpvgv {
ed6116ce
LW
300 char * xpv_pv; /* pointer to malloced string */
301 STRLEN xpv_cur; /* length of xpv_pv as a C string */
302 STRLEN xpv_len; /* allocated size */
a0d0e21e 303 IV xiv_iv; /* integer value or pv offset */
65202027 304 NV xnv_nv; /* numeric value, if any */
79072805
LW
305 MAGIC* xmg_magic; /* linked list of magicalness */
306 HV* xmg_stash; /* class package */
8990e307 307
79072805
LW
308 GP* xgv_gp;
309 char* xgv_name;
310 STRLEN xgv_namelen;
311 HV* xgv_stash;
a5f75d66 312 U8 xgv_flags;
79072805
LW
313};
314
315struct xpvbm {
ed6116ce
LW
316 char * xpv_pv; /* pointer to malloced string */
317 STRLEN xpv_cur; /* length of xpv_pv as a C string */
318 STRLEN xpv_len; /* allocated size */
a0d0e21e 319 IV xiv_iv; /* integer value or pv offset */
65202027 320 NV xnv_nv; /* numeric value, if any */
79072805
LW
321 MAGIC* xmg_magic; /* linked list of magicalness */
322 HV* xmg_stash; /* class package */
8990e307 323
79072805
LW
324 I32 xbm_useful; /* is this constant pattern being useful? */
325 U16 xbm_previous; /* how many characters in string before rare? */
326 U8 xbm_rare; /* rarest character in string */
327};
328
d22779f5 329/* This structure much match XPVCV in cv.h */
44a8e56a 330
77a005ab
MB
331typedef U16 cv_flags_t;
332
79072805 333struct xpvfm {
ed6116ce
LW
334 char * xpv_pv; /* pointer to malloced string */
335 STRLEN xpv_cur; /* length of xpv_pv as a C string */
336 STRLEN xpv_len; /* allocated size */
a0d0e21e 337 IV xiv_iv; /* integer value or pv offset */
65202027 338 NV xnv_nv; /* numeric value, if any */
79072805
LW
339 MAGIC* xmg_magic; /* linked list of magicalness */
340 HV* xmg_stash; /* class package */
8990e307 341
79072805
LW
342 HV * xcv_stash;
343 OP * xcv_start;
344 OP * xcv_root;
acfe0abc 345 void (*xcv_xsub)(pTHX_ CV*);
a0d0e21e
LW
346 ANY xcv_xsubany;
347 GV * xcv_gv;
57843af0 348 char * xcv_file;
b195d487 349 long xcv_depth; /* >= 2 indicates recursive call */
79072805 350 AV * xcv_padlist;
748a9306 351 CV * xcv_outside;
4d1ff10f 352#ifdef USE_5005THREADS
f6d98b14 353 perl_mutex *xcv_mutexp; /* protects xcv_owner */
52e1cb5e 354 struct perl_thread *xcv_owner; /* current owner thread */
4d1ff10f 355#endif /* USE_5005THREADS */
77a005ab 356 cv_flags_t xcv_flags;
44a8e56a 357
11a7ac70 358 IV xfm_lines;
79072805
LW
359};
360
8990e307
LW
361struct xpvio {
362 char * xpv_pv; /* pointer to malloced string */
363 STRLEN xpv_cur; /* length of xpv_pv as a C string */
364 STRLEN xpv_len; /* allocated size */
a0d0e21e 365 IV xiv_iv; /* integer value or pv offset */
65202027 366 NV xnv_nv; /* numeric value, if any */
8990e307
LW
367 MAGIC* xmg_magic; /* linked list of magicalness */
368 HV* xmg_stash; /* class package */
369
760ac839
LW
370 PerlIO * xio_ifp; /* ifp and ofp are normally the same */
371 PerlIO * xio_ofp; /* but sockets need separate streams */
4755096e
GS
372 /* Cray addresses everything by word boundaries (64 bits) and
373 * code and data pointers cannot be mixed (which is exactly what
374 * Perl_filter_add() tries to do with the dirp), hence the following
375 * union trick (as suggested by Gurusamy Sarathy).
376 * For further information see Geir Johansen's problem report titled
377 [ID 20000612.002] Perl problem on Cray system
378 * The any pointer (known as IoANY()) will also be a good place
379 * to hang any IO disciplines to.
380 */
381 union {
382 DIR * xiou_dirp; /* for opendir, readdir, etc */
383 void * xiou_any; /* for alignment */
384 } xio_dirpu;
11a7ac70
JH
385 IV xio_lines; /* $. */
386 IV xio_page; /* $% */
387 IV xio_page_len; /* $= */
388 IV xio_lines_left; /* $- */
8990e307
LW
389 char * xio_top_name; /* $^ */
390 GV * xio_top_gv; /* $^ */
391 char * xio_fmt_name; /* $~ */
392 GV * xio_fmt_gv; /* $~ */
393 char * xio_bottom_name;/* $^B */
394 GV * xio_bottom_gv; /* $^B */
395 short xio_subprocess; /* -| or |- */
396 char xio_type;
397 char xio_flags;
398};
4755096e
GS
399#define xio_dirp xio_dirpu.xiou_dirp
400#define xio_any xio_dirpu.xiou_any
8990e307 401
e0c19803
GS
402#define IOf_ARGV 1 /* this fp iterates over ARGV */
403#define IOf_START 2 /* check for null ARGV and substitute '-' */
404#define IOf_FLUSH 4 /* this fp wants a flush after write op */
405#define IOf_DIDTOP 8 /* just did top of form */
406#define IOf_UNTAINT 16 /* consider this fp (and its data) "safe" */
407#define IOf_NOLINE 32 /* slurped a pseudo-line from empty file */
408#define IOf_FAKE_DIRP 64 /* xio_dirp is fake (source filters kludge) */
8990e307 409
ed6116ce
LW
410/* The following macros define implementation-independent predicates on SVs. */
411
954c1994
GS
412/*
413=for apidoc Am|bool|SvNIOK|SV* sv
414Returns a boolean indicating whether the SV contains a number, integer or
415double.
416
417=for apidoc Am|bool|SvNIOKp|SV* sv
418Returns a boolean indicating whether the SV contains a number, integer or
419double. Checks the B<private> setting. Use C<SvNIOK>.
420
421=for apidoc Am|void|SvNIOK_off|SV* sv
422Unsets the NV/IV status of an SV.
423
424=for apidoc Am|bool|SvOK|SV* sv
425Returns a boolean indicating whether the value is an SV.
426
427=for apidoc Am|bool|SvIOKp|SV* sv
428Returns a boolean indicating whether the SV contains an integer. Checks
429the B<private> setting. Use C<SvIOK>.
430
431=for apidoc Am|bool|SvNOKp|SV* sv
432Returns a boolean indicating whether the SV contains a double. Checks the
433B<private> setting. Use C<SvNOK>.
434
435=for apidoc Am|bool|SvPOKp|SV* sv
436Returns a boolean indicating whether the SV contains a character string.
437Checks the B<private> setting. Use C<SvPOK>.
438
439=for apidoc Am|bool|SvIOK|SV* sv
440Returns a boolean indicating whether the SV contains an integer.
441
442=for apidoc Am|void|SvIOK_on|SV* sv
443Tells an SV that it is an integer.
444
445=for apidoc Am|void|SvIOK_off|SV* sv
446Unsets the IV status of an SV.
447
448=for apidoc Am|void|SvIOK_only|SV* sv
449Tells an SV that it is an integer and disables all other OK bits.
450
e331fc52
JH
451=for apidoc Am|void|SvIOK_only_UV|SV* sv
452Tells and SV that it is an unsigned integer and disables all other OK bits.
453
454=for apidoc Am|void|SvIOK_UV|SV* sv
455Returns a boolean indicating whether the SV contains an unsigned integer.
456
28e5dec8
JH
457=for apidoc Am|void|SvUOK|SV* sv
458Returns a boolean indicating whether the SV contains an unsigned integer.
459
e331fc52 460=for apidoc Am|void|SvIOK_notUV|SV* sv
d1be9408 461Returns a boolean indicating whether the SV contains a signed integer.
e331fc52 462
954c1994
GS
463=for apidoc Am|bool|SvNOK|SV* sv
464Returns a boolean indicating whether the SV contains a double.
465
466=for apidoc Am|void|SvNOK_on|SV* sv
467Tells an SV that it is a double.
468
469=for apidoc Am|void|SvNOK_off|SV* sv
470Unsets the NV status of an SV.
471
472=for apidoc Am|void|SvNOK_only|SV* sv
473Tells an SV that it is a double and disables all other OK bits.
474
475=for apidoc Am|bool|SvPOK|SV* sv
476Returns a boolean indicating whether the SV contains a character
477string.
478
479=for apidoc Am|void|SvPOK_on|SV* sv
480Tells an SV that it is a string.
481
482=for apidoc Am|void|SvPOK_off|SV* sv
483Unsets the PV status of an SV.
484
485=for apidoc Am|void|SvPOK_only|SV* sv
486Tells an SV that it is a string and disables all other OK bits.
d5ce4a7c 487Will also turn off the UTF8 status.
954c1994
GS
488
489=for apidoc Am|bool|SvOOK|SV* sv
490Returns a boolean indicating whether the SvIVX is a valid offset value for
491the SvPVX. This hack is used internally to speed up removal of characters
492from the beginning of a SvPV. When SvOOK is true, then the start of the
493allocated string buffer is really (SvPVX - SvIVX).
494
495=for apidoc Am|bool|SvROK|SV* sv
496Tests if the SV is an RV.
497
498=for apidoc Am|void|SvROK_on|SV* sv
499Tells an SV that it is an RV.
500
501=for apidoc Am|void|SvROK_off|SV* sv
502Unsets the RV status of an SV.
503
504=for apidoc Am|SV*|SvRV|SV* sv
505Dereferences an RV to return the SV.
506
507=for apidoc Am|IV|SvIVX|SV* sv
645c22ef
DM
508Returns the raw value in the SV's IV slot, without checks or conversions.
509Only use when you are sure SvIOK is true. See also C<SvIV()>.
954c1994
GS
510
511=for apidoc Am|UV|SvUVX|SV* sv
645c22ef
DM
512Returns the raw value in the SV's UV slot, without checks or conversions.
513Only use when you are sure SvIOK is true. See also C<SvUV()>.
954c1994
GS
514
515=for apidoc Am|NV|SvNVX|SV* sv
645c22ef
DM
516Returns the raw value in the SV's NV slot, without checks or conversions.
517Only use when you are sure SvNOK is true. See also C<SvNV()>.
954c1994
GS
518
519=for apidoc Am|char*|SvPVX|SV* sv
645c22ef 520Returns a pointer to the physical string in the SV. The SV must contain a
954c1994
GS
521string.
522
523=for apidoc Am|STRLEN|SvCUR|SV* sv
524Returns the length of the string which is in the SV. See C<SvLEN>.
525
526=for apidoc Am|STRLEN|SvLEN|SV* sv
659239a4
MG
527Returns the size of the string buffer in the SV, not including any part
528attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
529
530=for apidoc Am|char*|SvEND|SV* sv
531Returns a pointer to the last character in the string which is in the SV.
532See C<SvCUR>. Access the character as *(SvEND(sv)).
533
534=for apidoc Am|HV*|SvSTASH|SV* sv
535Returns the stash of the SV.
536
537=for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len
538Set the length of the string which is in the SV. See C<SvCUR>.
539
540=cut
541*/
542
79072805 543#define SvNIOK(sv) (SvFLAGS(sv) & (SVf_IOK|SVf_NOK))
748a9306 544#define SvNIOKp(sv) (SvFLAGS(sv) & (SVp_IOK|SVp_NOK))
a0d0e21e 545#define SvNIOK_off(sv) (SvFLAGS(sv) &= ~(SVf_IOK|SVf_NOK| \
25da4f38 546 SVp_IOK|SVp_NOK|SVf_IVisUV))
79072805 547
463ee0b2 548#define SvOK(sv) (SvFLAGS(sv) & SVf_OK)
25da4f38 549#define SvOK_off(sv) (SvFLAGS(sv) &= ~(SVf_OK|SVf_AMAGIC| \
d41ff1b8 550 SVf_IVisUV|SVf_UTF8), \
25da4f38 551 SvOOK_off(sv))
d41ff1b8
GS
552#define SvOK_off_exc_UV(sv) (SvFLAGS(sv) &= ~(SVf_OK|SVf_AMAGIC| \
553 SVf_UTF8), \
a0d0e21e 554 SvOOK_off(sv))
79072805 555
8990e307
LW
556#define SvOKp(sv) (SvFLAGS(sv) & (SVp_IOK|SVp_NOK|SVp_POK))
557#define SvIOKp(sv) (SvFLAGS(sv) & SVp_IOK)
155aba94 558#define SvIOKp_on(sv) ((void)SvOOK_off(sv), SvFLAGS(sv) |= SVp_IOK)
8990e307
LW
559#define SvNOKp(sv) (SvFLAGS(sv) & SVp_NOK)
560#define SvNOKp_on(sv) (SvFLAGS(sv) |= SVp_NOK)
561#define SvPOKp(sv) (SvFLAGS(sv) & SVp_POK)
562#define SvPOKp_on(sv) (SvFLAGS(sv) |= SVp_POK)
463ee0b2 563
79072805 564#define SvIOK(sv) (SvFLAGS(sv) & SVf_IOK)
155aba94 565#define SvIOK_on(sv) ((void)SvOOK_off(sv), \
a0d0e21e 566 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
25da4f38 567#define SvIOK_off(sv) (SvFLAGS(sv) &= ~(SVf_IOK|SVp_IOK|SVf_IVisUV))
155aba94 568#define SvIOK_only(sv) ((void)SvOK_off(sv), \
a0d0e21e 569 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
155aba94 570#define SvIOK_only_UV(sv) ((void)SvOK_off_exc_UV(sv), \
25da4f38 571 SvFLAGS(sv) |= (SVf_IOK|SVp_IOK))
70401c6b 572
25da4f38
IZ
573#define SvIOK_UV(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV)) \
574 == (SVf_IOK|SVf_IVisUV))
28e5dec8 575#define SvUOK(sv) SvIOK_UV(sv)
25da4f38
IZ
576#define SvIOK_notUV(sv) ((SvFLAGS(sv) & (SVf_IOK|SVf_IVisUV)) \
577 == SVf_IOK)
578
579#define SvIsUV(sv) (SvFLAGS(sv) & SVf_IVisUV)
580#define SvIsUV_on(sv) (SvFLAGS(sv) |= SVf_IVisUV)
581#define SvIsUV_off(sv) (SvFLAGS(sv) &= ~SVf_IVisUV)
79072805
LW
582
583#define SvNOK(sv) (SvFLAGS(sv) & SVf_NOK)
a0d0e21e 584#define SvNOK_on(sv) (SvFLAGS(sv) |= (SVf_NOK|SVp_NOK))
8990e307 585#define SvNOK_off(sv) (SvFLAGS(sv) &= ~(SVf_NOK|SVp_NOK))
155aba94 586#define SvNOK_only(sv) ((void)SvOK_off(sv), \
a0d0e21e 587 SvFLAGS(sv) |= (SVf_NOK|SVp_NOK))
79072805 588
914184e1
JH
589/*
590=for apidoc Am|void|SvUTF8|SV* sv
591Returns a boolean indicating whether the SV contains UTF-8 encoded data.
592
593=for apidoc Am|void|SvUTF8_on|SV *sv
d5ce4a7c
GA
594Turn on the UTF8 status of an SV (the data is not changed, just the flag).
595Do not use frivolously.
914184e1
JH
596
597=for apidoc Am|void|SvUTF8_off|SV *sv
598Unsets the UTF8 status of an SV.
599
600=for apidoc Am|void|SvPOK_only_UTF8|SV* sv
d5ce4a7c
GA
601Tells an SV that it is a string and disables all other OK bits,
602and leaves the UTF8 status as it was.
f1a1024e 603
914184e1
JH
604=cut
605 */
606
a7cb1f99
GS
607#define SvUTF8(sv) (SvFLAGS(sv) & SVf_UTF8)
608#define SvUTF8_on(sv) (SvFLAGS(sv) |= (SVf_UTF8))
609#define SvUTF8_off(sv) (SvFLAGS(sv) &= ~(SVf_UTF8))
5bc28da9 610
79072805 611#define SvPOK(sv) (SvFLAGS(sv) & SVf_POK)
a0d0e21e 612#define SvPOK_on(sv) (SvFLAGS(sv) |= (SVf_POK|SVp_POK))
8990e307 613#define SvPOK_off(sv) (SvFLAGS(sv) &= ~(SVf_POK|SVp_POK))
d41ff1b8
GS
614#define SvPOK_only(sv) (SvFLAGS(sv) &= ~(SVf_OK|SVf_AMAGIC| \
615 SVf_IVisUV|SVf_UTF8), \
616 SvFLAGS(sv) |= (SVf_POK|SVp_POK))
617#define SvPOK_only_UTF8(sv) (SvFLAGS(sv) &= ~(SVf_OK|SVf_AMAGIC| \
618 SVf_IVisUV), \
a0d0e21e 619 SvFLAGS(sv) |= (SVf_POK|SVp_POK))
79072805
LW
620
621#define SvOOK(sv) (SvFLAGS(sv) & SVf_OOK)
155aba94 622#define SvOOK_on(sv) ((void)SvIOK_off(sv), SvFLAGS(sv) |= SVf_OOK)
79072805 623#define SvOOK_off(sv) (SvOOK(sv) && sv_backoff(sv))
79072805 624
a0d0e21e
LW
625#define SvFAKE(sv) (SvFLAGS(sv) & SVf_FAKE)
626#define SvFAKE_on(sv) (SvFLAGS(sv) |= SVf_FAKE)
627#define SvFAKE_off(sv) (SvFLAGS(sv) &= ~SVf_FAKE)
628
ed6116ce 629#define SvROK(sv) (SvFLAGS(sv) & SVf_ROK)
a0d0e21e 630#define SvROK_on(sv) (SvFLAGS(sv) |= SVf_ROK)
a0d0e21e 631#define SvROK_off(sv) (SvFLAGS(sv) &= ~(SVf_ROK|SVf_AMAGIC))
79072805 632
8990e307
LW
633#define SvMAGICAL(sv) (SvFLAGS(sv) & (SVs_GMG|SVs_SMG|SVs_RMG))
634#define SvMAGICAL_on(sv) (SvFLAGS(sv) |= (SVs_GMG|SVs_SMG|SVs_RMG))
635#define SvMAGICAL_off(sv) (SvFLAGS(sv) &= ~(SVs_GMG|SVs_SMG|SVs_RMG))
79072805 636
8990e307
LW
637#define SvGMAGICAL(sv) (SvFLAGS(sv) & SVs_GMG)
638#define SvGMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_GMG)
639#define SvGMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_GMG)
ed6116ce 640
8990e307
LW
641#define SvSMAGICAL(sv) (SvFLAGS(sv) & SVs_SMG)
642#define SvSMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_SMG)
643#define SvSMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_SMG)
ed6116ce 644
8990e307
LW
645#define SvRMAGICAL(sv) (SvFLAGS(sv) & SVs_RMG)
646#define SvRMAGICAL_on(sv) (SvFLAGS(sv) |= SVs_RMG)
647#define SvRMAGICAL_off(sv) (SvFLAGS(sv) &= ~SVs_RMG)
ed6116ce 648
9e7bc3e8
JD
649#define SvAMAGIC(sv) (SvFLAGS(sv) & SVf_AMAGIC)
650#define SvAMAGIC_on(sv) (SvFLAGS(sv) |= SVf_AMAGIC)
651#define SvAMAGIC_off(sv) (SvFLAGS(sv) &= ~SVf_AMAGIC)
a0d0e21e 652
8cf8f3d1 653#define SvGAMAGIC(sv) (SvFLAGS(sv) & (SVs_GMG|SVf_AMAGIC))
1426bbf4 654
a0d0e21e
LW
655/*
656#define Gv_AMG(stash) \
657 (HV_AMAGICmb(stash) && \
658 ((!HV_AMAGICbad(stash) && HV_AMAGIC(stash)) || Gv_AMupdate(stash)))
659*/
3280af22 660#define Gv_AMG(stash) (PL_amagic_generation && Gv_AMupdate(stash))
a0d0e21e 661
810b8aa5
GS
662#define SvWEAKREF(sv) ((SvFLAGS(sv) & (SVf_ROK|SVprv_WEAKREF)) \
663 == (SVf_ROK|SVprv_WEAKREF))
664#define SvWEAKREF_on(sv) (SvFLAGS(sv) |= (SVf_ROK|SVprv_WEAKREF))
665#define SvWEAKREF_off(sv) (SvFLAGS(sv) &= ~(SVf_ROK|SVprv_WEAKREF))
666
a0d0e21e 667#define SvTHINKFIRST(sv) (SvFLAGS(sv) & SVf_THINKFIRST)
ed6116ce 668
8990e307 669#define SvPADBUSY(sv) (SvFLAGS(sv) & SVs_PADBUSY)
ed6116ce 670
8990e307
LW
671#define SvPADTMP(sv) (SvFLAGS(sv) & SVs_PADTMP)
672#define SvPADTMP_on(sv) (SvFLAGS(sv) |= SVs_PADTMP|SVs_PADBUSY)
673#define SvPADTMP_off(sv) (SvFLAGS(sv) &= ~SVs_PADTMP)
ed6116ce 674
8990e307
LW
675#define SvPADMY(sv) (SvFLAGS(sv) & SVs_PADMY)
676#define SvPADMY_on(sv) (SvFLAGS(sv) |= SVs_PADMY|SVs_PADBUSY)
ed6116ce 677
8990e307
LW
678#define SvTEMP(sv) (SvFLAGS(sv) & SVs_TEMP)
679#define SvTEMP_on(sv) (SvFLAGS(sv) |= SVs_TEMP)
680#define SvTEMP_off(sv) (SvFLAGS(sv) &= ~SVs_TEMP)
79072805 681
8990e307
LW
682#define SvOBJECT(sv) (SvFLAGS(sv) & SVs_OBJECT)
683#define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT)
684#define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT)
79072805 685
8990e307
LW
686#define SvREADONLY(sv) (SvFLAGS(sv) & SVf_READONLY)
687#define SvREADONLY_on(sv) (SvFLAGS(sv) |= SVf_READONLY)
688#define SvREADONLY_off(sv) (SvFLAGS(sv) &= ~SVf_READONLY)
79072805 689
8990e307
LW
690#define SvSCREAM(sv) (SvFLAGS(sv) & SVp_SCREAM)
691#define SvSCREAM_on(sv) (SvFLAGS(sv) |= SVp_SCREAM)
692#define SvSCREAM_off(sv) (SvFLAGS(sv) &= ~SVp_SCREAM)
79072805 693
8990e307
LW
694#define SvCOMPILED(sv) (SvFLAGS(sv) & SVpfm_COMPILED)
695#define SvCOMPILED_on(sv) (SvFLAGS(sv) |= SVpfm_COMPILED)
696#define SvCOMPILED_off(sv) (SvFLAGS(sv) &= ~SVpfm_COMPILED)
79072805 697
25da4f38
IZ
698#define SvEVALED(sv) (SvFLAGS(sv) & SVrepl_EVAL)
699#define SvEVALED_on(sv) (SvFLAGS(sv) |= SVrepl_EVAL)
700#define SvEVALED_off(sv) (SvFLAGS(sv) &= ~SVrepl_EVAL)
701
8990e307
LW
702#define SvTAIL(sv) (SvFLAGS(sv) & SVpbm_TAIL)
703#define SvTAIL_on(sv) (SvFLAGS(sv) |= SVpbm_TAIL)
704#define SvTAIL_off(sv) (SvFLAGS(sv) &= ~SVpbm_TAIL)
705
8990e307
LW
706#define SvVALID(sv) (SvFLAGS(sv) & SVpbm_VALID)
707#define SvVALID_on(sv) (SvFLAGS(sv) |= SVpbm_VALID)
708#define SvVALID_off(sv) (SvFLAGS(sv) &= ~SVpbm_VALID)
709
1cc8b4c5
AB
710#ifdef USE_ITHREADS
711/* The following uses the FAKE flag to show that a regex pointer is infact
8ca6097c 712 its own offset in the regexpad for ithreads */
1cc8b4c5
AB
713#define SvREPADTMP(sv) (SvFLAGS(sv) & SVf_FAKE)
714#define SvREPADTMP_on(sv) (SvFLAGS(sv) |= SVf_FAKE)
715#define SvREPADTMP_off(sv) (SvFLAGS(sv) &= ~SVf_FAKE)
716#endif
717
ed6116ce
LW
718#define SvRV(sv) ((XRV*) SvANY(sv))->xrv_rv
719#define SvRVx(sv) SvRV(sv)
720
463ee0b2
LW
721#define SvIVX(sv) ((XPVIV*) SvANY(sv))->xiv_iv
722#define SvIVXx(sv) SvIVX(sv)
ff68c719
PP
723#define SvUVX(sv) ((XPVUV*) SvANY(sv))->xuv_uv
724#define SvUVXx(sv) SvUVX(sv)
463ee0b2
LW
725#define SvNVX(sv) ((XPVNV*)SvANY(sv))->xnv_nv
726#define SvNVXx(sv) SvNVX(sv)
727#define SvPVX(sv) ((XPV*) SvANY(sv))->xpv_pv
728#define SvPVXx(sv) SvPVX(sv)
79072805 729#define SvCUR(sv) ((XPV*) SvANY(sv))->xpv_cur
79072805
LW
730#define SvLEN(sv) ((XPV*) SvANY(sv))->xpv_len
731#define SvLENx(sv) SvLEN(sv)
732#define SvEND(sv)(((XPV*) SvANY(sv))->xpv_pv + ((XPV*)SvANY(sv))->xpv_cur)
6b88bc9c 733#define SvENDx(sv) ((PL_Sv = (sv)), SvEND(PL_Sv))
79072805
LW
734#define SvMAGIC(sv) ((XPVMG*) SvANY(sv))->xmg_magic
735#define SvSTASH(sv) ((XPVMG*) SvANY(sv))->xmg_stash
736
28e5dec8
JH
737/* Ask a scalar nicely to try to become an IV, if possible.
738 Not guaranteed to stay returning void */
739/* Macro won't actually call sv_2iv if already IOK */
740#define SvIV_please(sv) \
741 STMT_START {if (!SvIOKp(sv) && (SvNOK(sv) || SvPOK(sv))) \
742 (void) SvIV(sv); } STMT_END
79072805 743#define SvIV_set(sv, val) \
80b92232
PP
744 STMT_START { assert(SvTYPE(sv) == SVt_IV || SvTYPE(sv) >= SVt_PVIV); \
745 (((XPVIV*) SvANY(sv))->xiv_iv = val); } STMT_END
79072805 746#define SvNV_set(sv, val) \
80b92232
PP
747 STMT_START { assert(SvTYPE(sv) == SVt_NV || SvTYPE(sv) >= SVt_PVNV); \
748 (((XPVNV*) SvANY(sv))->xnv_nv = val); } STMT_END
79072805 749#define SvPV_set(sv, val) \
80b92232
PP
750 STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
751 (((XPV*) SvANY(sv))->xpv_pv = val); } STMT_END
79072805 752#define SvCUR_set(sv, val) \
80b92232
PP
753 STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
754 (((XPV*) SvANY(sv))->xpv_cur = val); } STMT_END
79072805 755#define SvLEN_set(sv, val) \
80b92232
PP
756 STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
757 (((XPV*) SvANY(sv))->xpv_len = val); } STMT_END
79072805 758#define SvEND_set(sv, val) \
80b92232
PP
759 STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
760 (((XPV*) SvANY(sv))->xpv_cur = val - SvPVX(sv)); } STMT_END
79072805
LW
761
762#define BmRARE(sv) ((XPVBM*) SvANY(sv))->xbm_rare
763#define BmUSEFUL(sv) ((XPVBM*) SvANY(sv))->xbm_useful
764#define BmPREVIOUS(sv) ((XPVBM*) SvANY(sv))->xbm_previous
765
766#define FmLINES(sv) ((XPVFM*) SvANY(sv))->xfm_lines
767
768#define LvTYPE(sv) ((XPVLV*) SvANY(sv))->xlv_type
769#define LvTARG(sv) ((XPVLV*) SvANY(sv))->xlv_targ
770#define LvTARGOFF(sv) ((XPVLV*) SvANY(sv))->xlv_targoff
771#define LvTARGLEN(sv) ((XPVLV*) SvANY(sv))->xlv_targlen
772
8990e307
LW
773#define IoIFP(sv) ((XPVIO*) SvANY(sv))->xio_ifp
774#define IoOFP(sv) ((XPVIO*) SvANY(sv))->xio_ofp
775#define IoDIRP(sv) ((XPVIO*) SvANY(sv))->xio_dirp
4755096e 776#define IoANY(sv) ((XPVIO*) SvANY(sv))->xio_any
8990e307
LW
777#define IoLINES(sv) ((XPVIO*) SvANY(sv))->xio_lines
778#define IoPAGE(sv) ((XPVIO*) SvANY(sv))->xio_page
779#define IoPAGE_LEN(sv) ((XPVIO*) SvANY(sv))->xio_page_len
780#define IoLINES_LEFT(sv)((XPVIO*) SvANY(sv))->xio_lines_left
781#define IoTOP_NAME(sv) ((XPVIO*) SvANY(sv))->xio_top_name
782#define IoTOP_GV(sv) ((XPVIO*) SvANY(sv))->xio_top_gv
783#define IoFMT_NAME(sv) ((XPVIO*) SvANY(sv))->xio_fmt_name
784#define IoFMT_GV(sv) ((XPVIO*) SvANY(sv))->xio_fmt_gv
785#define IoBOTTOM_NAME(sv)((XPVIO*) SvANY(sv))->xio_bottom_name
786#define IoBOTTOM_GV(sv) ((XPVIO*) SvANY(sv))->xio_bottom_gv
787#define IoSUBPROCESS(sv)((XPVIO*) SvANY(sv))->xio_subprocess
788#define IoTYPE(sv) ((XPVIO*) SvANY(sv))->xio_type
789#define IoFLAGS(sv) ((XPVIO*) SvANY(sv))->xio_flags
790
50952442
JH
791/* IoTYPE(sv) is a single character telling the type of I/O connection. */
792#define IoTYPE_RDONLY '<'
793#define IoTYPE_WRONLY '>'
794#define IoTYPE_RDWR '+'
795#define IoTYPE_APPEND 'a'
796#define IoTYPE_PIPE '|'
797#define IoTYPE_STD '-' /* stdin or stdout */
798#define IoTYPE_SOCKET 's'
799#define IoTYPE_CLOSED ' '
03fcf2fc
GS
800
801/*
954c1994
GS
802=for apidoc Am|bool|SvTAINTED|SV* sv
803Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
804not.
805
806=for apidoc Am|void|SvTAINTED_on|SV* sv
807Marks an SV as tainted.
808
809=for apidoc Am|void|SvTAINTED_off|SV* sv
810Untaints an SV. Be I<very> careful with this routine, as it short-circuits
811some of Perl's fundamental security features. XS module authors should not
812use this function unless they fully understand all the implications of
813unconditionally untainting the value. Untainting should be done in the
814standard perl fashion, via a carefully crafted regexp, rather than directly
815untainting variables.
816
817=for apidoc Am|void|SvTAINT|SV* sv
818Taints an SV if tainting is enabled
819
820=cut
821*/
822
bbce6d69 823#define SvTAINTED(sv) (SvMAGICAL(sv) && sv_tainted(sv))
3280af22
NIS
824#define SvTAINTED_on(sv) STMT_START{ if(PL_tainting){sv_taint(sv);} }STMT_END
825#define SvTAINTED_off(sv) STMT_START{ if(PL_tainting){sv_untaint(sv);} }STMT_END
bbce6d69 826
c6ee37c5
MB
827#define SvTAINT(sv) \
828 STMT_START { \
3280af22 829 if (PL_tainting) { \
3280af22 830 if (PL_tainted) \
c6ee37c5
MB
831 SvTAINTED_on(sv); \
832 } \
833 } STMT_END
79072805 834
954c1994
GS
835/*
836=for apidoc Am|char*|SvPV_force|SV* sv|STRLEN len
837Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
838force if you are going to update the SvPVX directly.
839
645c22ef
DM
840=for apidoc Am|char*|SvPV_force_nomg|SV* sv|STRLEN len
841Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
842force if you are going to update the SvPVX directly. Doesn't process magic.
843
954c1994
GS
844=for apidoc Am|char*|SvPV|SV* sv|STRLEN len
845Returns a pointer to the string in the SV, or a stringified form of the SV
645c22ef
DM
846if the SV does not contain a string. Handles 'get' magic. See also
847C<SvPVx> for a version which guarantees to evaluate sv only once.
848
849=for apidoc Am|char*|SvPVx|SV* sv|STRLEN len
850A version of C<SvPV> which guarantees to evaluate sv only once.
954c1994
GS
851
852=for apidoc Am|char*|SvPV_nolen|SV* sv
853Returns a pointer to the string in the SV, or a stringified form of the SV
854if the SV does not contain a string. Handles 'get' magic.
855
856=for apidoc Am|IV|SvIV|SV* sv
645c22ef
DM
857Coerces the given SV to an integer and returns it. See C<SvIVx> for a
858version which guarantees to evaluate sv only once.
859
860=for apidoc Am|IV|SvIVx|SV* sv
861Coerces the given SV to an integer and returns it. Guarantees to evaluate
d1be9408 862sv only once. Use the more efficient C<SvIV> otherwise.
954c1994
GS
863
864=for apidoc Am|NV|SvNV|SV* sv
645c22ef
DM
865Coerce the given SV to a double and return it. See C<SvNVx> for a version
866which guarantees to evaluate sv only once.
867
868=for apidoc Am|NV|SvNVx|SV* sv
869Coerces the given SV to a double and returns it. Guarantees to evaluate
d1be9408 870sv only once. Use the more efficient C<SvNV> otherwise.
954c1994
GS
871
872=for apidoc Am|UV|SvUV|SV* sv
645c22ef
DM
873Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
874for a version which guarantees to evaluate sv only once.
875
876=for apidoc Am|UV|SvUVx|SV* sv
877Coerces the given SV to an unsigned integer and returns it. Guarantees to
d1be9408 878evaluate sv only once. Use the more efficient C<SvUV> otherwise.
954c1994
GS
879
880=for apidoc Am|bool|SvTRUE|SV* sv
881Returns a boolean indicating whether Perl would evaluate the SV as true or
882false, defined or undefined. Does not handle 'get' magic.
883
645c22ef 884=for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
b70b15d2 885Like C<SvPV_force>, but converts sv to utf8 first if necessary.
645c22ef
DM
886
887=for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len
b70b15d2 888Like C<SvPV>, but converts sv to utf8 first if necessary.
645c22ef 889
b70b15d2
TJ
890=for apidoc Am|char*|SvPVutf8_nolen|SV* sv
891Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
645c22ef
DM
892
893=for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
894Like C<SvPV_force>, but converts sv to byte representation first if necessary.
895
896=for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
897Like C<SvPV>, but converts sv to byte representation first if necessary.
898
b70b15d2 899=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
645c22ef
DM
900Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
901
902=for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len
b70b15d2 903Like C<SvPV_force>, but converts sv to utf8 first if necessary.
d1be9408 904Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
645c22ef
DM
905otherwise.
906
907=for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len
b70b15d2 908Like C<SvPV>, but converts sv to utf8 first if necessary.
d1be9408 909Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
645c22ef
DM
910otherwise.
911
912=for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
913Like C<SvPV_force>, but converts sv to byte representation first if necessary.
d1be9408 914Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
645c22ef
DM
915otherwise.
916
917=for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
918Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 919Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
920otherwise.
921
922
954c1994
GS
923=cut
924*/
925
a0d0e21e 926#define SvPV_force(sv, lp) sv_pvn_force(sv, &lp)
463ee0b2 927#define SvPV(sv, lp) sv_pvn(sv, &lp)
1fa8b10d 928#define SvPV_nolen(sv) sv_pv(sv)
6e9d1081
NC
929#define SvPV_nomg(sv, lp) sv_pvn_nomg(sv, &lp)
930#define SvPV_force_flags(sv, lp, flags) sv_pvn_force_flags(sv, &lp, flags)
5bc28da9
NIS
931
932#define SvPVutf8_force(sv, lp) sv_pvutf8n_force(sv, &lp)
933#define SvPVutf8(sv, lp) sv_pvutf8n(sv, &lp)
934#define SvPVutf8_nolen(sv) sv_pvutf8(sv)
935
936#define SvPVbyte_force(sv, lp) sv_pvbyte_force(sv, &lp)
937#define SvPVbyte(sv, lp) sv_pvbyten(sv, &lp)
938#define SvPVbyte_nolen(sv) sv_pvbyte(sv)
939
940#define SvPVx(sv, lp) sv_pvn(sv, &lp)
941#define SvPVx_force(sv, lp) sv_pvn_force(sv, &lp)
942#define SvPVutf8x(sv, lp) sv_pvutf8n(sv, &lp)
943#define SvPVutf8x_force(sv, lp) sv_pvutf8n_force(sv, &lp)
944#define SvPVbytex(sv, lp) sv_pvbyten(sv, &lp)
945#define SvPVbytex_force(sv, lp) sv_pvbyten_force(sv, &lp)
946
4e35701f
NIS
947#define SvIVx(sv) sv_iv(sv)
948#define SvUVx(sv) sv_uv(sv)
949#define SvNVx(sv) sv_nv(sv)
5bc28da9 950
4e35701f
NIS
951#define SvTRUEx(sv) sv_true(sv)
952
953#define SvIV(sv) SvIVx(sv)
954#define SvNV(sv) SvNVx(sv)
25da4f38 955#define SvUV(sv) SvUVx(sv)
4e35701f 956#define SvTRUE(sv) SvTRUEx(sv)
79072805 957
6e9d1081
NC
958/* flag values for sv_*_flags functions */
959#define SV_IMMEDIATE_UNREF 1
960#define SV_GMAGIC 2
961
962#define sv_pvn_force_nomg(sv, lp) sv_pvn_force_flags(sv, lp, 0)
963#define sv_utf8_upgrade_nomg(sv) sv_utf8_upgrade_flags(sv, 0)
964#define sv_catpvn_nomg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, 0)
965
a80f87c4
GS
966#ifndef CRIPPLED_CC
967/* redefine some things to more efficient inlined versions */
79072805 968
25da4f38 969/* Let us hope that bitmaps for UV and IV are the same */
ff68c719 970#undef SvIV
463ee0b2 971#define SvIV(sv) (SvIOK(sv) ? SvIVX(sv) : sv_2iv(sv))
79072805 972
ff68c719
PP
973#undef SvUV
974#define SvUV(sv) (SvIOK(sv) ? SvUVX(sv) : sv_2uv(sv))
975
976#undef SvNV
463ee0b2 977#define SvNV(sv) (SvNOK(sv) ? SvNVX(sv) : sv_2nv(sv))
79072805 978
af3c7592 979#define sv_setsv(dsv, ssv) sv_setsv_flags(dsv, ssv, SV_GMAGIC)
8d6d96c1 980#define sv_setsv_nomg(dsv, ssv) sv_setsv_flags(dsv, ssv, 0)
af3c7592 981#define sv_catsv(dsv, ssv) sv_catsv_flags(dsv, ssv, SV_GMAGIC)
8d6d96c1 982#define sv_catsv_nomg(dsv, ssv) sv_catsv_flags(dsv, ssv, 0)
af3c7592
NIS
983#define sv_catpvn(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC)
984#define sv_2pv(sv, lp) sv_2pv_flags(sv, lp, SV_GMAGIC)
8d6d96c1 985#define sv_2pv_nomg(sv, lp) sv_2pv_flags(sv, lp, 0)
af3c7592
NIS
986#define sv_pvn_force(sv, lp) sv_pvn_force_flags(sv, lp, SV_GMAGIC)
987#define sv_utf8_upgrade(sv) sv_utf8_upgrade_flags(sv, SV_GMAGIC)
8d6d96c1 988
ff68c719 989#undef SvPV
8d6d96c1
HS
990#define SvPV(sv, lp) SvPV_flags(sv, lp, SV_GMAGIC)
991
992#undef SvPV_nomg
993#define SvPV_nomg(sv, lp) SvPV_flags(sv, lp, 0)
70401c6b 994
8d6d96c1
HS
995#undef SvPV_flags
996#define SvPV_flags(sv, lp, flags) \
997 ((SvFLAGS(sv) & (SVf_POK)) == SVf_POK \
998 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pv_flags(sv, &lp, flags))
79072805 999
ff68c719 1000#undef SvPV_force
8d6d96c1
HS
1001#define SvPV_force(sv, lp) SvPV_force_flags(sv, lp, SV_GMAGIC)
1002#undef SvPV_force_nomg
1003#define SvPV_force_nomg(sv, lp) SvPV_force_flags(sv, lp, 0)
1004
1005#undef SvPV_force_flags
1006#define SvPV_force_flags(sv, lp, flags) \
ff68c719 1007 ((SvFLAGS(sv) & (SVf_POK|SVf_THINKFIRST)) == SVf_POK \
8d6d96c1 1008 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvn_force_flags(sv, &lp, flags))
a0d0e21e 1009
1fa8b10d
JD
1010#undef SvPV_nolen
1011#define SvPV_nolen(sv) \
5bc28da9
NIS
1012 ((SvFLAGS(sv) & (SVf_POK)) == SVf_POK \
1013 ? SvPVX(sv) : sv_2pv_nolen(sv))
70401c6b 1014
5bc28da9
NIS
1015#undef SvPVutf8
1016#define SvPVutf8(sv, lp) \
1017 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK|SVf_UTF8) \
1018 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8(sv, &lp))
70401c6b 1019
5bc28da9
NIS
1020#undef SvPVutf8_force
1021#define SvPVutf8_force(sv, lp) \
70401c6b 1022 ((SvFLAGS(sv) & (SVf_POK|SVf_THINKFIRST)) == (SVf_POK|SVf_UTF8) \
5bc28da9
NIS
1023 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvutf8n_force(sv, &lp))
1024
1025#undef SvPVutf8_nolen
1026#define SvPVutf8_nolen(sv) \
70401c6b 1027 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK|SVf_UTF8)\
5bc28da9 1028 ? SvPVX(sv) : sv_2pvutf8_nolen(sv))
70401c6b 1029
5bc28da9
NIS
1030#undef SvPVutf8
1031#define SvPVutf8(sv, lp) \
1032 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK|SVf_UTF8) \
1033 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8(sv, &lp))
70401c6b 1034
5bc28da9
NIS
1035#undef SvPVutf8_force
1036#define SvPVutf8_force(sv, lp) \
70401c6b 1037 ((SvFLAGS(sv) & (SVf_POK|SVf_THINKFIRST)) == (SVf_POK|SVf_UTF8) \
5bc28da9
NIS
1038 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvutf8n_force(sv, &lp))
1039
1040#undef SvPVutf8_nolen
1041#define SvPVutf8_nolen(sv) \
1042 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK|SVf_UTF8)\
1043 ? SvPVX(sv) : sv_2pvutf8_nolen(sv))
70401c6b 1044
5bc28da9
NIS
1045#undef SvPVbyte
1046#define SvPVbyte(sv, lp) \
1047 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK) \
1048 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte(sv, &lp))
70401c6b 1049
5bc28da9
NIS
1050#undef SvPVbyte_force
1051#define SvPVbyte_force(sv, lp) \
1052 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8|SVf_THINKFIRST)) == (SVf_POK) \
1053 ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvbyte_force(sv, &lp))
1054
1055#undef SvPVbyte_nolen
1056#define SvPVbyte_nolen(sv) \
1057 ((SvFLAGS(sv) & (SVf_POK|SVf_UTF8)) == (SVf_POK)\
1058 ? SvPVX(sv) : sv_2pvbyte_nolen(sv))
70401c6b 1059
1fa8b10d 1060
a80f87c4
GS
1061#ifdef __GNUC__
1062# undef SvIVx
1063# undef SvUVx
1064# undef SvNVx
1065# undef SvPVx
5bc28da9
NIS
1066# undef SvPVutf8x
1067# undef SvPVbytex
a80f87c4
GS
1068# undef SvTRUE
1069# undef SvTRUEx
1070# define SvIVx(sv) ({SV *nsv = (SV*)(sv); SvIV(nsv); })
1071# define SvUVx(sv) ({SV *nsv = (SV*)(sv); SvUV(nsv); })
1072# define SvNVx(sv) ({SV *nsv = (SV*)(sv); SvNV(nsv); })
1073# define SvPVx(sv, lp) ({SV *nsv = (sv); SvPV(nsv, lp); })
5bc28da9
NIS
1074# define SvPVutf8x(sv, lp) ({SV *nsv = (sv); SvPVutf8(nsv, lp); })
1075# define SvPVbytex(sv, lp) ({SV *nsv = (sv); SvPVbyte(nsv, lp); })
a80f87c4 1076# define SvTRUE(sv) ( \
8990e307
LW
1077 !sv \
1078 ? 0 \
1079 : SvPOK(sv) \
a80f87c4
GS
1080 ? (({XPV *nxpv = (XPV*)SvANY(sv); \
1081 nxpv && \
c2f1de04 1082 (nxpv->xpv_cur > 1 || \
a80f87c4 1083 (nxpv->xpv_cur && *nxpv->xpv_pv != '0')); }) \
79072805
LW
1084 ? 1 \
1085 : 0) \
1086 : \
1087 SvIOK(sv) \
463ee0b2 1088 ? SvIVX(sv) != 0 \
79072805 1089 : SvNOK(sv) \
463ee0b2
LW
1090 ? SvNVX(sv) != 0.0 \
1091 : sv_2bool(sv) )
a80f87c4
GS
1092# define SvTRUEx(sv) ({SV *nsv = (sv); SvTRUE(nsv); })
1093#else /* __GNUC__ */
4d1ff10f 1094#ifndef USE_5005THREADS
a80f87c4
GS
1095/* These inlined macros use globals, which will require a thread
1096 * declaration in user code, so we avoid them under threads */
1097
1098# undef SvIVx
1099# undef SvUVx
1100# undef SvNVx
1101# undef SvPVx
5bc28da9
NIS
1102# undef SvPVutf8x
1103# undef SvPVbytex
a80f87c4
GS
1104# undef SvTRUE
1105# undef SvTRUEx
6b88bc9c
GS
1106# define SvIVx(sv) ((PL_Sv = (sv)), SvIV(PL_Sv))
1107# define SvUVx(sv) ((PL_Sv = (sv)), SvUV(PL_Sv))
1108# define SvNVx(sv) ((PL_Sv = (sv)), SvNV(PL_Sv))
1109# define SvPVx(sv, lp) ((PL_Sv = (sv)), SvPV(PL_Sv, lp))
5bc28da9 1110# define SvPVutf8x(sv, lp) ((PL_Sv = (sv)), SvPVutf8(PL_Sv, lp))
f83ee824 1111# define SvPVbytex(sv, lp) ((PL_Sv = (sv)), SvPVbyte(PL_Sv, lp))
a80f87c4
GS
1112# define SvTRUE(sv) ( \
1113 !sv \
1114 ? 0 \
1115 : SvPOK(sv) \
6b88bc9c 1116 ? ((PL_Xpv = (XPV*)SvANY(sv)) && \
c2f1de04 1117 (PL_Xpv->xpv_cur > 1 || \
6b88bc9c 1118 (PL_Xpv->xpv_cur && *PL_Xpv->xpv_pv != '0')) \
a80f87c4
GS
1119 ? 1 \
1120 : 0) \
1121 : \
1122 SvIOK(sv) \
1123 ? SvIVX(sv) != 0 \
1124 : SvNOK(sv) \
1125 ? SvNVX(sv) != 0.0 \
1126 : sv_2bool(sv) )
6b88bc9c 1127# define SvTRUEx(sv) ((PL_Sv = (sv)), SvTRUE(PL_Sv))
4d1ff10f 1128#endif /* !USE_5005THREADS */
a80f87c4
GS
1129#endif /* !__GNU__ */
1130#endif /* !CRIPPLED_CC */
79072805 1131
954c1994
GS
1132/*
1133=for apidoc Am|SV*|newRV_inc|SV* sv
1134
1135Creates an RV wrapper for an SV. The reference count for the original SV is
1136incremented.
1137
1138=cut
1139*/
1140
5f05dabc 1141#define newRV_inc(sv) newRV(sv)
5f05dabc 1142
ef50df4b 1143/* the following macros update any magic values this sv is associated with */
79072805 1144
954c1994 1145/*
ccfc67b7
JH
1146=head1 Magical Functions
1147
954c1994
GS
1148=for apidoc Am|void|SvGETMAGIC|SV* sv
1149Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1150argument more than once.
1151
1152=for apidoc Am|void|SvSETMAGIC|SV* sv
1153Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
1154argument more than once.
1155
1156=for apidoc Am|void|SvSetSV|SV* dsb|SV* ssv
1157Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
1158more than once.
1159
1160=for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv
1161Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1162ssv. May evaluate arguments more than once.
1163
645c22ef
DM
1164=for apidoc Am|void|SvSetMagicSV|SV* dsb|SV* ssv
1165Like C<SvSetSV>, but does any set magic required afterwards.
1166
1167=for apidoc Am|void|SvSetMagicSV_nosteal|SV* dsv|SV* ssv
1168Like C<SvSetMagicSV>, but does any set magic required afterwards.
1169
68795e93
NIS
1170=for apidoc Am|void|SvSHARE|SV* sv
1171Arranges for sv to be shared between threads if a suitable module
1172has been loaded.
1173
1174=for apidoc Am|void|SvLOCK|SV* sv
1175Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1176has been loaded.
1177
1178=for apidoc Am|void|SvUNLOCK|SV* sv
1179Releases a mutual exclusion lock on sv if a suitable module
1180has been loaded.
1181
ccfc67b7
JH
1182=head1 SV Manipulation Functions
1183
679ac26e 1184=for apidoc Am|char *|SvGROW|SV* sv|STRLEN len
954c1994
GS
1185Expands the character buffer in the SV so that it has room for the
1186indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 1187NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
1188Returns a pointer to the character buffer.
1189
1190=cut
1191*/
1192
68795e93
NIS
1193#define SvSHARE(sv) CALL_FPTR(PL_sharehook)(aTHX_ sv)
1194#define SvLOCK(sv) CALL_FPTR(PL_lockhook)(aTHX_ sv)
1195#define SvUNLOCK(sv) CALL_FPTR(PL_unlockhook)(aTHX_ sv)
1196
189b2af5
GS
1197#define SvGETMAGIC(x) STMT_START { if (SvGMAGICAL(x)) mg_get(x); } STMT_END
1198#define SvSETMAGIC(x) STMT_START { if (SvSMAGICAL(x)) mg_set(x); } STMT_END
79072805 1199
54310121 1200#define SvSetSV_and(dst,src,finally) \
189b2af5 1201 STMT_START { \
54310121
PP
1202 if ((dst) != (src)) { \
1203 sv_setsv(dst, src); \
1204 finally; \
189b2af5
GS
1205 } \
1206 } STMT_END
54310121 1207#define SvSetSV_nosteal_and(dst,src,finally) \
189b2af5 1208 STMT_START { \
8ebc5c01
PP
1209 if ((dst) != (src)) { \
1210 U32 tMpF = SvFLAGS(src) & SVs_TEMP; \
1211 SvTEMP_off(src); \
1212 sv_setsv(dst, src); \
1213 SvFLAGS(src) |= tMpF; \
54310121 1214 finally; \
189b2af5
GS
1215 } \
1216 } STMT_END
79072805 1217
54310121 1218#define SvSetSV(dst,src) \
c9d716f7 1219 SvSetSV_and(dst,src,/*nothing*/;)
54310121 1220#define SvSetSV_nosteal(dst,src) \
c9d716f7 1221 SvSetSV_nosteal_and(dst,src,/*nothing*/;)
54310121
PP
1222
1223#define SvSetMagicSV(dst,src) \
1224 SvSetSV_and(dst,src,SvSETMAGIC(dst))
1225#define SvSetMagicSV_nosteal(dst,src) \
1226 SvSetSV_nosteal_and(dst,src,SvSETMAGIC(dst))
1227
3967c732 1228#ifdef DEBUGGING
79072805 1229#define SvPEEK(sv) sv_peek(sv)
3967c732
JD
1230#else
1231#define SvPEEK(sv) ""
1232#endif
79072805 1233
3280af22 1234#define SvIMMORTAL(sv) ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no)
36477c24 1235
3280af22 1236#define boolSV(b) ((b) ? &PL_sv_yes : &PL_sv_no)
54310121 1237
79072805
LW
1238#define isGV(sv) (SvTYPE(sv) == SVt_PVGV)
1239
933fea7f
GS
1240#define SvGROW(sv,len) (SvLEN(sv) < (len) ? sv_grow(sv,len) : SvPVX(sv))
1241#define Sv_Grow sv_grow
3d35f11b 1242
a0739874
DM
1243#define CLONEf_COPY_STACKS 1
1244#define CLONEf_KEEP_PTR_TABLE 2
c43294b8 1245#define CLONEf_CLONE_HOST 4
a0739874 1246
8cf8f3d1 1247struct clone_params {
d2d73c3e
AB
1248 AV* stashes;
1249 UV flags;
8cf8f3d1 1250};