This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: END {} blocks run in perl_run
[perl5.git] / pod / perlapi.pod
CommitLineData
954c1994
GS
1=head1 NAME
2
3perlapi - autogenerated documentation for the perl public API
4
5=head1 DESCRIPTION
6
1c846c1f
NIS
7This file contains the documentation of the perl public API generated by
8embed.pl, specifically a listing of functions, macros, flags, and variables
9that may be used by extension writers. The interfaces of any functions that
954c1994
GS
10are not listed here are subject to change without notice. For this reason,
11blindly using functions listed in proto.h is to be avoided when writing
12extensions.
13
14Note that all Perl API global variables must be referenced with the C<PL_>
15prefix. Some macros are provided for compatibility with the older,
16unadorned names, but this support may be disabled in a future release.
17
18The listing is alphabetical, case insensitive.
19
20=over 8
21
22=item AvFILL
23
24Same as C<av_len()>. Deprecated, use C<av_len()> instead.
25
26 int AvFILL(AV* av)
27
497711e7
GS
28=for hackers
29Found in file av.h
30
954c1994
GS
31=item av_clear
32
33Clears an array, making it empty. Does not free the memory used by the
34array itself.
35
36 void av_clear(AV* ar)
37
497711e7
GS
38=for hackers
39Found in file av.c
40
f3b76584
SC
41=item av_delete
42
43Deletes the element indexed by C<key> from the array. Returns the
44deleted element. C<flags> is currently ignored.
45
46 SV* av_delete(AV* ar, I32 key, I32 flags)
47
48=for hackers
49Found in file av.c
50
51=item av_exists
52
53Returns true if the element indexed by C<key> has been initialized.
54
55This relies on the fact that uninitialized array elements are set to
56C<&PL_sv_undef>.
57
58 bool av_exists(AV* ar, I32 key)
59
60=for hackers
61Found in file av.c
62
954c1994
GS
63=item av_extend
64
65Pre-extend an array. The C<key> is the index to which the array should be
66extended.
67
68 void av_extend(AV* ar, I32 key)
69
497711e7
GS
70=for hackers
71Found in file av.c
72
954c1994
GS
73=item av_fetch
74
75Returns the SV at the specified index in the array. The C<key> is the
76index. If C<lval> is set then the fetch will be part of a store. Check
77that the return value is non-null before dereferencing it to a C<SV*>.
78
96f1132b
GS
79See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
80more information on how to use this function on tied arrays.
954c1994
GS
81
82 SV** av_fetch(AV* ar, I32 key, I32 lval)
83
497711e7
GS
84=for hackers
85Found in file av.c
86
f3b76584
SC
87=item av_fill
88
89Ensure than an array has a given number of elements, equivalent to
90Perl's C<$#array = $fill;>.
91
92 void av_fill(AV* ar, I32 fill)
93
94=for hackers
95Found in file av.c
96
954c1994
GS
97=item av_len
98
99Returns the highest index in the array. Returns -1 if the array is
100empty.
101
102 I32 av_len(AV* ar)
103
497711e7
GS
104=for hackers
105Found in file av.c
106
954c1994
GS
107=item av_make
108
109Creates a new AV and populates it with a list of SVs. The SVs are copied
110into the array, so they may be freed after the call to av_make. The new AV
111will have a reference count of 1.
112
113 AV* av_make(I32 size, SV** svp)
114
497711e7
GS
115=for hackers
116Found in file av.c
117
954c1994
GS
118=item av_pop
119
120Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
121is empty.
122
123 SV* av_pop(AV* ar)
124
497711e7
GS
125=for hackers
126Found in file av.c
127
954c1994
GS
128=item av_push
129
130Pushes an SV onto the end of the array. The array will grow automatically
131to accommodate the addition.
132
133 void av_push(AV* ar, SV* val)
134
497711e7
GS
135=for hackers
136Found in file av.c
137
954c1994
GS
138=item av_shift
139
140Shifts an SV off the beginning of the array.
141
142 SV* av_shift(AV* ar)
143
497711e7
GS
144=for hackers
145Found in file av.c
146
954c1994
GS
147=item av_store
148
149Stores an SV in an array. The array index is specified as C<key>. The
150return value will be NULL if the operation failed or if the value did not
151need to be actually stored within the array (as in the case of tied
152arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
153that the caller is responsible for suitably incrementing the reference
154count of C<val> before the call, and decrementing it if the function
155returned NULL.
156
96f1132b 157See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
954c1994
GS
158more information on how to use this function on tied arrays.
159
160 SV** av_store(AV* ar, I32 key, SV* val)
161
497711e7
GS
162=for hackers
163Found in file av.c
164
954c1994
GS
165=item av_undef
166
167Undefines the array. Frees the memory used by the array itself.
168
169 void av_undef(AV* ar)
170
497711e7
GS
171=for hackers
172Found in file av.c
173
954c1994
GS
174=item av_unshift
175
176Unshift the given number of C<undef> values onto the beginning of the
177array. The array will grow automatically to accommodate the addition. You
178must then use C<av_store> to assign values to these new elements.
179
180 void av_unshift(AV* ar, I32 num)
181
497711e7
GS
182=for hackers
183Found in file av.c
184
9f2ea798
DM
185=item ax
186
187Variable which is setup by C<xsubpp> to indicate the stack base offset,
188used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
189must be called prior to setup the C<MARK> variable.
190
191 I32 ax
192
193=for hackers
194Found in file XSUB.h
195
f9a63242
JH
196=item bytes_from_utf8
197
198Converts a string C<s> of length C<len> from UTF8 into byte encoding.
199Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
ef9edfd0
JH
200the newly-created string, and updates C<len> to contain the new
201length. Returns the original string if no conversion occurs, C<len>
202is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
2030 if C<s> is converted or contains all 7bit characters.
f9a63242
JH
204
205NOTE: this function is experimental and may change or be
206removed without notice.
207
208 U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
209
210=for hackers
211Found in file utf8.c
212
497711e7
GS
213=item bytes_to_utf8
214
215Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
6662521e
GS
216Returns a pointer to the newly-created string, and sets C<len> to
217reflect the new length.
497711e7 218
eebe1485
SC
219NOTE: this function is experimental and may change or be
220removed without notice.
221
222 U8* bytes_to_utf8(U8 *s, STRLEN *len)
497711e7
GS
223
224=for hackers
225Found in file utf8.c
226
954c1994
GS
227=item call_argv
228
229Performs a callback to the specified Perl sub. See L<perlcall>.
230
231NOTE: the perl_ form of this function is deprecated.
232
233 I32 call_argv(const char* sub_name, I32 flags, char** argv)
234
497711e7
GS
235=for hackers
236Found in file perl.c
237
954c1994
GS
238=item call_method
239
240Performs a callback to the specified Perl method. The blessed object must
241be on the stack. See L<perlcall>.
242
243NOTE: the perl_ form of this function is deprecated.
244
245 I32 call_method(const char* methname, I32 flags)
246
497711e7
GS
247=for hackers
248Found in file perl.c
249
954c1994
GS
250=item call_pv
251
252Performs a callback to the specified Perl sub. See L<perlcall>.
253
254NOTE: the perl_ form of this function is deprecated.
255
256 I32 call_pv(const char* sub_name, I32 flags)
257
497711e7
GS
258=for hackers
259Found in file perl.c
260
954c1994
GS
261=item call_sv
262
263Performs a callback to the Perl sub whose name is in the SV. See
264L<perlcall>.
265
266NOTE: the perl_ form of this function is deprecated.
267
268 I32 call_sv(SV* sv, I32 flags)
269
497711e7
GS
270=for hackers
271Found in file perl.c
272
954c1994
GS
273=item CLASS
274
275Variable which is setup by C<xsubpp> to indicate the
276class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
277
278 char* CLASS
279
497711e7
GS
280=for hackers
281Found in file XSUB.h
282
954c1994
GS
283=item Copy
284
285The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
286source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
287the type. May fail on overlapping copies. See also C<Move>.
288
289 void Copy(void* src, void* dest, int nitems, type)
290
497711e7
GS
291=for hackers
292Found in file handy.h
293
954c1994
GS
294=item croak
295
c9d5ac95
GS
296This is the XSUB-writer's interface to Perl's C<die> function.
297Normally use this function the same way you use the C C<printf>
298function. See C<warn>.
299
300If you want to throw an exception object, assign the object to
301C<$@> and then pass C<Nullch> to croak():
302
303 errsv = get_sv("@", TRUE);
304 sv_setsv(errsv, exception_object);
305 croak(Nullch);
954c1994
GS
306
307 void croak(const char* pat, ...)
308
497711e7
GS
309=for hackers
310Found in file util.c
311
954c1994
GS
312=item CvSTASH
313
314Returns the stash of the CV.
315
316 HV* CvSTASH(CV* cv)
317
497711e7
GS
318=for hackers
319Found in file cv.h
320
beab0874
JT
321=item cv_const_sv
322
323If C<cv> is a constant sub eligible for inlining. returns the constant
324value returned by the sub. Otherwise, returns NULL.
325
326Constant subs can be created with C<newCONSTSUB> or as described in
327L<perlsub/"Constant Functions">.
328
329 SV* cv_const_sv(CV* cv)
330
331=for hackers
fa519979 332Found in file op.c
beab0874 333
9f2ea798
DM
334=item dAX
335
336Sets up the C<ax> variable.
337This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
338
339 dAX;
340
341=for hackers
342Found in file XSUB.h
343
344=item dITEMS
345
346Sets up the C<items> variable.
347This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
348
349 dITEMS;
350
351=for hackers
352Found in file XSUB.h
353
954c1994
GS
354=item dMARK
355
356Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
357C<dORIGMARK>.
358
359 dMARK;
360
497711e7
GS
361=for hackers
362Found in file pp.h
363
954c1994
GS
364=item dORIGMARK
365
366Saves the original stack mark for the XSUB. See C<ORIGMARK>.
367
368 dORIGMARK;
369
497711e7
GS
370=for hackers
371Found in file pp.h
372
954c1994
GS
373=item dSP
374
375Declares a local copy of perl's stack pointer for the XSUB, available via
376the C<SP> macro. See C<SP>.
377
378 dSP;
379
497711e7
GS
380=for hackers
381Found in file pp.h
382
954c1994
GS
383=item dXSARGS
384
9f2ea798
DM
385Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
386Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
387This is usually handled automatically by C<xsubpp>.
954c1994
GS
388
389 dXSARGS;
390
497711e7
GS
391=for hackers
392Found in file XSUB.h
393
954c1994
GS
394=item dXSI32
395
396Sets up the C<ix> variable for an XSUB which has aliases. This is usually
397handled automatically by C<xsubpp>.
398
399 dXSI32;
400
497711e7
GS
401=for hackers
402Found in file XSUB.h
403
954c1994
GS
404=item ENTER
405
406Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
407
408 ENTER;
409
497711e7
GS
410=for hackers
411Found in file scope.h
412
954c1994
GS
413=item eval_pv
414
415Tells Perl to C<eval> the given string and return an SV* result.
416
417NOTE: the perl_ form of this function is deprecated.
418
419 SV* eval_pv(const char* p, I32 croak_on_error)
420
497711e7
GS
421=for hackers
422Found in file perl.c
423
954c1994
GS
424=item eval_sv
425
426Tells Perl to C<eval> the string in the SV.
427
428NOTE: the perl_ form of this function is deprecated.
429
430 I32 eval_sv(SV* sv, I32 flags)
431
497711e7
GS
432=for hackers
433Found in file perl.c
434
954c1994
GS
435=item EXTEND
436
437Used to extend the argument stack for an XSUB's return values. Once
4375e838 438used, guarantees that there is room for at least C<nitems> to be pushed
954c1994
GS
439onto the stack.
440
441 void EXTEND(SP, int nitems)
442
497711e7
GS
443=for hackers
444Found in file pp.h
445
954c1994
GS
446=item fbm_compile
447
448Analyses the string in order to make fast searches on it using fbm_instr()
449-- the Boyer-Moore algorithm.
450
451 void fbm_compile(SV* sv, U32 flags)
452
497711e7
GS
453=for hackers
454Found in file util.c
455
954c1994
GS
456=item fbm_instr
457
458Returns the location of the SV in the string delimited by C<str> and
459C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
460does not have to be fbm_compiled, but the search will not be as fast
461then.
462
463 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
464
497711e7
GS
465=for hackers
466Found in file util.c
467
954c1994
GS
468=item FREETMPS
469
470Closing bracket for temporaries on a callback. See C<SAVETMPS> and
471L<perlcall>.
472
473 FREETMPS;
474
497711e7
GS
475=for hackers
476Found in file scope.h
477
89423764
GS
478=item getcwd_sv
479
480Fill the sv with current working directory
481
482 int getcwd_sv(SV* sv)
483
484=for hackers
485Found in file util.c
486
954c1994
GS
487=item get_av
488
489Returns the AV of the specified Perl array. If C<create> is set and the
490Perl variable does not exist then it will be created. If C<create> is not
491set and the variable does not exist then NULL is returned.
492
493NOTE: the perl_ form of this function is deprecated.
494
495 AV* get_av(const char* name, I32 create)
496
497711e7
GS
497=for hackers
498Found in file perl.c
499
954c1994
GS
500=item get_cv
501
502Returns the CV of the specified Perl subroutine. If C<create> is set and
503the Perl subroutine does not exist then it will be declared (which has the
504same effect as saying C<sub name;>). If C<create> is not set and the
505subroutine does not exist then NULL is returned.
506
507NOTE: the perl_ form of this function is deprecated.
508
509 CV* get_cv(const char* name, I32 create)
510
497711e7
GS
511=for hackers
512Found in file perl.c
513
954c1994
GS
514=item get_hv
515
516Returns the HV of the specified Perl hash. If C<create> is set and the
517Perl variable does not exist then it will be created. If C<create> is not
518set and the variable does not exist then NULL is returned.
519
520NOTE: the perl_ form of this function is deprecated.
521
522 HV* get_hv(const char* name, I32 create)
523
497711e7
GS
524=for hackers
525Found in file perl.c
526
954c1994
GS
527=item get_sv
528
529Returns the SV of the specified Perl scalar. If C<create> is set and the
530Perl variable does not exist then it will be created. If C<create> is not
531set and the variable does not exist then NULL is returned.
532
533NOTE: the perl_ form of this function is deprecated.
534
535 SV* get_sv(const char* name, I32 create)
536
497711e7
GS
537=for hackers
538Found in file perl.c
539
954c1994
GS
540=item GIMME
541
542A backward-compatible version of C<GIMME_V> which can only return
543C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
544Deprecated. Use C<GIMME_V> instead.
545
546 U32 GIMME
547
497711e7
GS
548=for hackers
549Found in file op.h
550
954c1994
GS
551=item GIMME_V
552
553The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
90fdbbb7 554C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
954c1994
GS
555respectively.
556
557 U32 GIMME_V
558
497711e7
GS
559=for hackers
560Found in file op.h
561
dd5dc04f
JH
562=item grok_number
563
564Recognise (or not) a number. The type of the number is returned
565(0 if unrecognised), otherwise it is a bit-ORed combination of
566IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
793edb8a 567IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
d42b51ea
JH
568
569If the value of the number can fit an in UV, it is returned in the *valuep
570IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
571will never be set unless *valuep is valid, but *valuep may have been assigned
572to during processing even though IS_NUMBER_IN_UV is not set on return.
573If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
574valuep is non-NULL, but no actual assignment (or SEGV) will occur.
575
576IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
577seen (in which case *valuep gives the true value truncated to an integer), and
578IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
579absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
580number is larger than a UV.
dd5dc04f
JH
581
582 int grok_number(const char *pv, STRLEN len, UV *valuep)
583
584=for hackers
98994639 585Found in file numeric.c
dd5dc04f
JH
586
587=item grok_numeric_radix
588
589Scan and skip for a numeric decimal separator (radix).
590
591 bool grok_numeric_radix(const char **sp, const char *send)
592
593=for hackers
98994639 594Found in file numeric.c
dd5dc04f 595
954c1994
GS
596=item GvSV
597
598Return the SV from the GV.
599
600 SV* GvSV(GV* gv)
601
497711e7
GS
602=for hackers
603Found in file gv.h
604
954c1994
GS
605=item gv_fetchmeth
606
607Returns the glob with the given C<name> and a defined subroutine or
608C<NULL>. The glob lives in the given C<stash>, or in the stashes
a453c169 609accessible via @ISA and UNIVERSAL::.
954c1994
GS
610
611The argument C<level> should be either 0 or -1. If C<level==0>, as a
612side-effect creates a glob with the given C<name> in the given C<stash>
613which in the case of success contains an alias for the subroutine, and sets
1c846c1f 614up caching info for this glob. Similarly for all the searched stashes.
954c1994
GS
615
616This function grants C<"SUPER"> token as a postfix of the stash name. The
617GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
4929bf7b 618visible to Perl code. So when calling C<call_sv>, you should not use
954c1994 619the GV directly; instead, you should use the method's CV, which can be
1c846c1f 620obtained from the GV with the C<GvCV> macro.
954c1994
GS
621
622 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
623
497711e7
GS
624=for hackers
625Found in file gv.c
626
954c1994
GS
627=item gv_fetchmethod
628
6d0f518e 629See L<gv_fetchmethod_autoload>.
954c1994
GS
630
631 GV* gv_fetchmethod(HV* stash, const char* name)
632
497711e7
GS
633=for hackers
634Found in file gv.c
635
954c1994
GS
636=item gv_fetchmethod_autoload
637
638Returns the glob which contains the subroutine to call to invoke the method
639on the C<stash>. In fact in the presence of autoloading this may be the
640glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
1c846c1f 641already setup.
954c1994
GS
642
643The third parameter of C<gv_fetchmethod_autoload> determines whether
644AUTOLOAD lookup is performed if the given method is not present: non-zero
1c846c1f 645means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
954c1994 646Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1c846c1f 647with a non-zero C<autoload> parameter.
954c1994
GS
648
649These functions grant C<"SUPER"> token as a prefix of the method name. Note
650that if you want to keep the returned glob for a long time, you need to
651check for it being "AUTOLOAD", since at the later time the call may load a
652different subroutine due to $AUTOLOAD changing its value. Use the glob
1c846c1f 653created via a side effect to do this.
954c1994
GS
654
655These functions have the same side-effects and as C<gv_fetchmeth> with
656C<level==0>. C<name> should be writable if contains C<':'> or C<'
657''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1c846c1f 658C<call_sv> apply equally to these functions.
954c1994
GS
659
660 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
661
497711e7
GS
662=for hackers
663Found in file gv.c
664
954c1994
GS
665=item gv_stashpv
666
386d01d6
GS
667Returns a pointer to the stash for a specified package. C<name> should
668be a valid UTF-8 string. If C<create> is set then the package will be
669created if it does not already exist. If C<create> is not set and the
670package does not exist then NULL is returned.
954c1994
GS
671
672 HV* gv_stashpv(const char* name, I32 create)
673
497711e7
GS
674=for hackers
675Found in file gv.c
676
954c1994
GS
677=item gv_stashsv
678
386d01d6
GS
679Returns a pointer to the stash for a specified package, which must be a
680valid UTF-8 string. See C<gv_stashpv>.
954c1994
GS
681
682 HV* gv_stashsv(SV* sv, I32 create)
683
497711e7
GS
684=for hackers
685Found in file gv.c
686
954c1994
GS
687=item G_ARRAY
688
90fdbbb7 689Used to indicate list context. See C<GIMME_V>, C<GIMME> and
954c1994
GS
690L<perlcall>.
691
497711e7
GS
692=for hackers
693Found in file cop.h
694
954c1994
GS
695=item G_DISCARD
696
697Indicates that arguments returned from a callback should be discarded. See
698L<perlcall>.
699
497711e7
GS
700=for hackers
701Found in file cop.h
702
954c1994
GS
703=item G_EVAL
704
705Used to force a Perl C<eval> wrapper around a callback. See
706L<perlcall>.
707
497711e7
GS
708=for hackers
709Found in file cop.h
710
954c1994
GS
711=item G_NOARGS
712
713Indicates that no arguments are being sent to a callback. See
714L<perlcall>.
715
497711e7
GS
716=for hackers
717Found in file cop.h
718
954c1994
GS
719=item G_SCALAR
720
721Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
722L<perlcall>.
723
497711e7
GS
724=for hackers
725Found in file cop.h
726
954c1994
GS
727=item G_VOID
728
729Used to indicate void context. See C<GIMME_V> and L<perlcall>.
730
497711e7
GS
731=for hackers
732Found in file cop.h
733
954c1994
GS
734=item HEf_SVKEY
735
736This flag, used in the length slot of hash entries and magic structures,
737specifies the structure contains a C<SV*> pointer where a C<char*> pointer
738is to be expected. (For information only--not to be used).
739
497711e7
GS
740=for hackers
741Found in file hv.h
742
954c1994
GS
743=item HeHASH
744
745Returns the computed hash stored in the hash entry.
746
747 U32 HeHASH(HE* he)
748
497711e7
GS
749=for hackers
750Found in file hv.h
751
954c1994
GS
752=item HeKEY
753
754Returns the actual pointer stored in the key slot of the hash entry. The
755pointer may be either C<char*> or C<SV*>, depending on the value of
756C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
757usually preferable for finding the value of a key.
758
759 void* HeKEY(HE* he)
760
497711e7
GS
761=for hackers
762Found in file hv.h
763
954c1994
GS
764=item HeKLEN
765
766If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
767holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
768be assigned to. The C<HePV()> macro is usually preferable for finding key
769lengths.
770
771 STRLEN HeKLEN(HE* he)
772
497711e7
GS
773=for hackers
774Found in file hv.h
775
954c1994
GS
776=item HePV
777
778Returns the key slot of the hash entry as a C<char*> value, doing any
779necessary dereferencing of possibly C<SV*> keys. The length of the string
780is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
781not care about what the length of the key is, you may use the global
782variable C<PL_na>, though this is rather less efficient than using a local
783variable. Remember though, that hash keys in perl are free to contain
784embedded nulls, so using C<strlen()> or similar is not a good way to find
785the length of hash keys. This is very similar to the C<SvPV()> macro
786described elsewhere in this document.
787
788 char* HePV(HE* he, STRLEN len)
789
497711e7
GS
790=for hackers
791Found in file hv.h
792
954c1994
GS
793=item HeSVKEY
794
795Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
796contain an C<SV*> key.
797
798 SV* HeSVKEY(HE* he)
799
497711e7
GS
800=for hackers
801Found in file hv.h
802
954c1994
GS
803=item HeSVKEY_force
804
805Returns the key as an C<SV*>. Will create and return a temporary mortal
806C<SV*> if the hash entry contains only a C<char*> key.
807
808 SV* HeSVKEY_force(HE* he)
809
497711e7
GS
810=for hackers
811Found in file hv.h
812
954c1994
GS
813=item HeSVKEY_set
814
815Sets the key to a given C<SV*>, taking care to set the appropriate flags to
816indicate the presence of an C<SV*> key, and returns the same
817C<SV*>.
818
819 SV* HeSVKEY_set(HE* he, SV* sv)
820
497711e7
GS
821=for hackers
822Found in file hv.h
823
954c1994
GS
824=item HeVAL
825
826Returns the value slot (type C<SV*>) stored in the hash entry.
827
828 SV* HeVAL(HE* he)
829
497711e7
GS
830=for hackers
831Found in file hv.h
832
954c1994
GS
833=item HvNAME
834
835Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
836
837 char* HvNAME(HV* stash)
838
497711e7
GS
839=for hackers
840Found in file hv.h
841
954c1994
GS
842=item hv_clear
843
844Clears a hash, making it empty.
845
846 void hv_clear(HV* tb)
847
497711e7
GS
848=for hackers
849Found in file hv.c
850
954c1994
GS
851=item hv_delete
852
853Deletes a key/value pair in the hash. The value SV is removed from the
1c846c1f 854hash and returned to the caller. The C<klen> is the length of the key.
954c1994
GS
855The C<flags> value will normally be zero; if set to G_DISCARD then NULL
856will be returned.
857
da58a35d 858 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
954c1994 859
497711e7
GS
860=for hackers
861Found in file hv.c
862
954c1994
GS
863=item hv_delete_ent
864
865Deletes a key/value pair in the hash. The value SV is removed from the
866hash and returned to the caller. The C<flags> value will normally be zero;
867if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
868precomputed hash value, or 0 to ask for it to be computed.
869
870 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
871
497711e7
GS
872=for hackers
873Found in file hv.c
874
954c1994
GS
875=item hv_exists
876
877Returns a boolean indicating whether the specified hash key exists. The
878C<klen> is the length of the key.
879
da58a35d 880 bool hv_exists(HV* tb, const char* key, I32 klen)
954c1994 881
497711e7
GS
882=for hackers
883Found in file hv.c
884
954c1994
GS
885=item hv_exists_ent
886
887Returns a boolean indicating whether the specified hash key exists. C<hash>
888can be a valid precomputed hash value, or 0 to ask for it to be
889computed.
890
891 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
892
497711e7
GS
893=for hackers
894Found in file hv.c
895
954c1994
GS
896=item hv_fetch
897
898Returns the SV which corresponds to the specified key in the hash. The
899C<klen> is the length of the key. If C<lval> is set then the fetch will be
900part of a store. Check that the return value is non-null before
1c846c1f 901dereferencing it to a C<SV*>.
954c1994 902
96f1132b 903See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
904information on how to use this function on tied hashes.
905
da58a35d 906 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
954c1994 907
497711e7
GS
908=for hackers
909Found in file hv.c
910
954c1994
GS
911=item hv_fetch_ent
912
913Returns the hash entry which corresponds to the specified key in the hash.
914C<hash> must be a valid precomputed hash number for the given C<key>, or 0
915if you want the function to compute it. IF C<lval> is set then the fetch
916will be part of a store. Make sure the return value is non-null before
917accessing it. The return value when C<tb> is a tied hash is a pointer to a
918static location, so be sure to make a copy of the structure if you need to
1c846c1f 919store it somewhere.
954c1994 920
96f1132b 921See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
922information on how to use this function on tied hashes.
923
924 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
925
497711e7
GS
926=for hackers
927Found in file hv.c
928
954c1994
GS
929=item hv_iterinit
930
931Prepares a starting point to traverse a hash table. Returns the number of
932keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1c846c1f 933currently only meaningful for hashes without tie magic.
954c1994
GS
934
935NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
936hash buckets that happen to be in use. If you still need that esoteric
937value, you can get it through the macro C<HvFILL(tb)>.
938
939 I32 hv_iterinit(HV* tb)
940
497711e7
GS
941=for hackers
942Found in file hv.c
943
954c1994
GS
944=item hv_iterkey
945
946Returns the key from the current position of the hash iterator. See
947C<hv_iterinit>.
948
949 char* hv_iterkey(HE* entry, I32* retlen)
950
497711e7
GS
951=for hackers
952Found in file hv.c
953
954c1994
GS
954=item hv_iterkeysv
955
956Returns the key as an C<SV*> from the current position of the hash
957iterator. The return value will always be a mortal copy of the key. Also
958see C<hv_iterinit>.
959
960 SV* hv_iterkeysv(HE* entry)
961
497711e7
GS
962=for hackers
963Found in file hv.c
964
954c1994
GS
965=item hv_iternext
966
967Returns entries from a hash iterator. See C<hv_iterinit>.
968
969 HE* hv_iternext(HV* tb)
970
497711e7
GS
971=for hackers
972Found in file hv.c
973
954c1994
GS
974=item hv_iternextsv
975
976Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
977operation.
978
979 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
980
497711e7
GS
981=for hackers
982Found in file hv.c
983
954c1994
GS
984=item hv_iterval
985
986Returns the value from the current position of the hash iterator. See
987C<hv_iterkey>.
988
989 SV* hv_iterval(HV* tb, HE* entry)
990
497711e7
GS
991=for hackers
992Found in file hv.c
993
954c1994
GS
994=item hv_magic
995
996Adds magic to a hash. See C<sv_magic>.
997
998 void hv_magic(HV* hv, GV* gv, int how)
999
497711e7
GS
1000=for hackers
1001Found in file hv.c
1002
954c1994
GS
1003=item hv_store
1004
1005Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1006the length of the key. The C<hash> parameter is the precomputed hash
1007value; if it is zero then Perl will compute it. The return value will be
1008NULL if the operation failed or if the value did not need to be actually
1009stored within the hash (as in the case of tied hashes). Otherwise it can
1010be dereferenced to get the original C<SV*>. Note that the caller is
1011responsible for suitably incrementing the reference count of C<val> before
1c846c1f 1012the call, and decrementing it if the function returned NULL.
954c1994 1013
96f1132b 1014See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1015information on how to use this function on tied hashes.
1016
da58a35d 1017 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
954c1994 1018
497711e7
GS
1019=for hackers
1020Found in file hv.c
1021
954c1994
GS
1022=item hv_store_ent
1023
1024Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1025parameter is the precomputed hash value; if it is zero then Perl will
1026compute it. The return value is the new hash entry so created. It will be
1027NULL if the operation failed or if the value did not need to be actually
1028stored within the hash (as in the case of tied hashes). Otherwise the
f22d8e4b 1029contents of the return value can be accessed using the C<He?> macros
954c1994
GS
1030described here. Note that the caller is responsible for suitably
1031incrementing the reference count of C<val> before the call, and
1c846c1f 1032decrementing it if the function returned NULL.
954c1994 1033
96f1132b 1034See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1035information on how to use this function on tied hashes.
1036
1037 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1038
497711e7
GS
1039=for hackers
1040Found in file hv.c
1041
954c1994
GS
1042=item hv_undef
1043
1044Undefines the hash.
1045
1046 void hv_undef(HV* tb)
1047
497711e7
GS
1048=for hackers
1049Found in file hv.c
1050
954c1994
GS
1051=item isALNUM
1052
4375e838 1053Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
f1cbbd6e 1054character (including underscore) or digit.
954c1994
GS
1055
1056 bool isALNUM(char ch)
1057
497711e7
GS
1058=for hackers
1059Found in file handy.h
1060
954c1994
GS
1061=item isALPHA
1062
4375e838 1063Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
954c1994
GS
1064character.
1065
1066 bool isALPHA(char ch)
1067
497711e7
GS
1068=for hackers
1069Found in file handy.h
1070
954c1994
GS
1071=item isDIGIT
1072
4375e838 1073Returns a boolean indicating whether the C C<char> is an ASCII
954c1994
GS
1074digit.
1075
1076 bool isDIGIT(char ch)
1077
497711e7
GS
1078=for hackers
1079Found in file handy.h
1080
954c1994
GS
1081=item isLOWER
1082
1083Returns a boolean indicating whether the C C<char> is a lowercase
1084character.
1085
1086 bool isLOWER(char ch)
1087
497711e7
GS
1088=for hackers
1089Found in file handy.h
1090
954c1994
GS
1091=item isSPACE
1092
1093Returns a boolean indicating whether the C C<char> is whitespace.
1094
1095 bool isSPACE(char ch)
1096
497711e7
GS
1097=for hackers
1098Found in file handy.h
1099
954c1994
GS
1100=item isUPPER
1101
1102Returns a boolean indicating whether the C C<char> is an uppercase
1103character.
1104
1105 bool isUPPER(char ch)
1106
497711e7
GS
1107=for hackers
1108Found in file handy.h
1109
eebe1485
SC
1110=item is_utf8_char
1111
5da9da9e 1112Tests if some arbitrary number of bytes begins in a valid UTF-8
4d4e713d 1113character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
5da9da9e
JH
1114The actual number of bytes in the UTF-8 character will be returned if
1115it is valid, otherwise 0.
282f25c9 1116
eebe1485
SC
1117 STRLEN is_utf8_char(U8 *p)
1118
1119=for hackers
1120Found in file utf8.c
1121
1122=item is_utf8_string
1123
5da9da9e
JH
1124Returns true if first C<len> bytes of the given string form a valid UTF8
1125string, false otherwise. Note that 'a valid UTF8 string' does not mean
1126'a string that contains UTF8' because a valid ASCII string is a valid
1127UTF8 string.
eebe1485
SC
1128
1129 bool is_utf8_string(U8 *s, STRLEN len)
1130
1131=for hackers
1132Found in file utf8.c
1133
954c1994
GS
1134=item items
1135
1136Variable which is setup by C<xsubpp> to indicate the number of
1137items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
1138
1139 I32 items
1140
497711e7
GS
1141=for hackers
1142Found in file XSUB.h
1143
954c1994
GS
1144=item ix
1145
1146Variable which is setup by C<xsubpp> to indicate which of an
1147XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
1148
1149 I32 ix
1150
497711e7
GS
1151=for hackers
1152Found in file XSUB.h
1153
954c1994
GS
1154=item LEAVE
1155
1156Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1157
1158 LEAVE;
1159
497711e7
GS
1160=for hackers
1161Found in file scope.h
1162
7d3fb230
BS
1163=item load_module
1164
1165Loads the module whose name is pointed to by the string part of name.
1166Note that the actual module name, not its filename, should be given.
1167Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
1168PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
1169(or 0 for no flags). ver, if specified, provides version semantics
1170similar to C<use Foo::Bar VERSION>. The optional trailing SV*
1171arguments can be used to specify arguments to the module's import()
1172method, similar to C<use Foo::Bar VERSION LIST>.
1173
1174 void load_module(U32 flags, SV* name, SV* ver, ...)
1175
1176=for hackers
1177Found in file op.c
1178
954c1994
GS
1179=item looks_like_number
1180
645c22ef
DM
1181Test if the content of an SV looks like a number (or is a number).
1182C<Inf> and C<Infinity> are treated as numbers (so will not issue a
1183non-numeric warning), even if your atof() doesn't grok them.
954c1994
GS
1184
1185 I32 looks_like_number(SV* sv)
1186
497711e7
GS
1187=for hackers
1188Found in file sv.c
1189
954c1994
GS
1190=item MARK
1191
1192Stack marker variable for the XSUB. See C<dMARK>.
1193
497711e7
GS
1194=for hackers
1195Found in file pp.h
1196
954c1994
GS
1197=item mg_clear
1198
1199Clear something magical that the SV represents. See C<sv_magic>.
1200
1201 int mg_clear(SV* sv)
1202
497711e7
GS
1203=for hackers
1204Found in file mg.c
1205
954c1994
GS
1206=item mg_copy
1207
1208Copies the magic from one SV to another. See C<sv_magic>.
1209
1210 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1211
497711e7
GS
1212=for hackers
1213Found in file mg.c
1214
954c1994
GS
1215=item mg_find
1216
1217Finds the magic pointer for type matching the SV. See C<sv_magic>.
1218
1219 MAGIC* mg_find(SV* sv, int type)
1220
497711e7
GS
1221=for hackers
1222Found in file mg.c
1223
954c1994
GS
1224=item mg_free
1225
1226Free any magic storage used by the SV. See C<sv_magic>.
1227
1228 int mg_free(SV* sv)
1229
497711e7
GS
1230=for hackers
1231Found in file mg.c
1232
954c1994
GS
1233=item mg_get
1234
1235Do magic after a value is retrieved from the SV. See C<sv_magic>.
1236
1237 int mg_get(SV* sv)
1238
497711e7
GS
1239=for hackers
1240Found in file mg.c
1241
954c1994
GS
1242=item mg_length
1243
1244Report on the SV's length. See C<sv_magic>.
1245
1246 U32 mg_length(SV* sv)
1247
497711e7
GS
1248=for hackers
1249Found in file mg.c
1250
954c1994
GS
1251=item mg_magical
1252
1253Turns on the magical status of an SV. See C<sv_magic>.
1254
1255 void mg_magical(SV* sv)
1256
497711e7
GS
1257=for hackers
1258Found in file mg.c
1259
954c1994
GS
1260=item mg_set
1261
1262Do magic after a value is assigned to the SV. See C<sv_magic>.
1263
1264 int mg_set(SV* sv)
1265
497711e7
GS
1266=for hackers
1267Found in file mg.c
1268
954c1994
GS
1269=item Move
1270
1271The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
1272source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1273the type. Can do overlapping moves. See also C<Copy>.
1274
1275 void Move(void* src, void* dest, int nitems, type)
1276
497711e7
GS
1277=for hackers
1278Found in file handy.h
1279
954c1994
GS
1280=item New
1281
1282The XSUB-writer's interface to the C C<malloc> function.
1283
1284 void New(int id, void* ptr, int nitems, type)
1285
497711e7
GS
1286=for hackers
1287Found in file handy.h
1288
954c1994
GS
1289=item newAV
1290
1291Creates a new AV. The reference count is set to 1.
1292
1293 AV* newAV()
1294
497711e7
GS
1295=for hackers
1296Found in file av.c
1297
954c1994
GS
1298=item Newc
1299
1300The XSUB-writer's interface to the C C<malloc> function, with
1301cast.
1302
1303 void Newc(int id, void* ptr, int nitems, type, cast)
1304
497711e7
GS
1305=for hackers
1306Found in file handy.h
1307
954c1994
GS
1308=item newCONSTSUB
1309
1310Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1311eligible for inlining at compile-time.
1312
beab0874 1313 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
954c1994 1314
497711e7 1315=for hackers
fa519979 1316Found in file op.c
497711e7 1317
954c1994
GS
1318=item newHV
1319
1320Creates a new HV. The reference count is set to 1.
1321
1322 HV* newHV()
1323
497711e7
GS
1324=for hackers
1325Found in file hv.c
1326
954c1994
GS
1327=item newRV_inc
1328
1329Creates an RV wrapper for an SV. The reference count for the original SV is
1330incremented.
1331
1332 SV* newRV_inc(SV* sv)
1333
497711e7
GS
1334=for hackers
1335Found in file sv.h
1336
954c1994
GS
1337=item newRV_noinc
1338
1339Creates an RV wrapper for an SV. The reference count for the original
1340SV is B<not> incremented.
1341
1342 SV* newRV_noinc(SV *sv)
1343
497711e7
GS
1344=for hackers
1345Found in file sv.c
1346
954c1994
GS
1347=item NEWSV
1348
1349Creates a new SV. A non-zero C<len> parameter indicates the number of
1350bytes of preallocated string space the SV should have. An extra byte for a
1351tailing NUL is also reserved. (SvPOK is not set for the SV even if string
444155da 1352space is allocated.) The reference count for the new SV is set to 1.
954c1994
GS
1353C<id> is an integer id between 0 and 1299 (used to identify leaks).
1354
1355 SV* NEWSV(int id, STRLEN len)
1356
497711e7
GS
1357=for hackers
1358Found in file handy.h
1359
e5dd39fc
AB
1360=item newSV
1361
1362Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
1363with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
1364macro.
1365
1366 SV* newSV(STRLEN len)
1367
1368=for hackers
1369Found in file sv.c
1370
954c1994
GS
1371=item newSViv
1372
1373Creates a new SV and copies an integer into it. The reference count for the
1374SV is set to 1.
1375
1376 SV* newSViv(IV i)
1377
497711e7
GS
1378=for hackers
1379Found in file sv.c
1380
954c1994
GS
1381=item newSVnv
1382
1383Creates a new SV and copies a floating point value into it.
1384The reference count for the SV is set to 1.
1385
1386 SV* newSVnv(NV n)
1387
497711e7
GS
1388=for hackers
1389Found in file sv.c
1390
954c1994
GS
1391=item newSVpv
1392
1393Creates a new SV and copies a string into it. The reference count for the
1394SV is set to 1. If C<len> is zero, Perl will compute the length using
1395strlen(). For efficiency, consider using C<newSVpvn> instead.
1396
1397 SV* newSVpv(const char* s, STRLEN len)
1398
497711e7
GS
1399=for hackers
1400Found in file sv.c
1401
954c1994
GS
1402=item newSVpvf
1403
645c22ef 1404Creates a new SV and initializes it with the string formatted like
954c1994
GS
1405C<sprintf>.
1406
1407 SV* newSVpvf(const char* pat, ...)
1408
497711e7
GS
1409=for hackers
1410Found in file sv.c
1411
954c1994
GS
1412=item newSVpvn
1413
1414Creates a new SV and copies a string into it. The reference count for the
1c846c1f 1415SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
954c1994
GS
1416string. You are responsible for ensuring that the source string is at least
1417C<len> bytes long.
1418
1419 SV* newSVpvn(const char* s, STRLEN len)
1420
497711e7
GS
1421=for hackers
1422Found in file sv.c
1423
1c846c1f
NIS
1424=item newSVpvn_share
1425
645c22ef
DM
1426Creates a new SV with its SvPVX pointing to a shared string in the string
1427table. If the string does not already exist in the table, it is created
1428first. Turns on READONLY and FAKE. The string's hash is stored in the UV
1429slot of the SV; if the C<hash> parameter is non-zero, that value is used;
1430otherwise the hash is computed. The idea here is that as the string table
1431is used for shared hash keys these strings will have SvPVX == HeKEY and
1432hash lookup will avoid string compare.
1c846c1f 1433
ae154d6d 1434 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
1c846c1f
NIS
1435
1436=for hackers
1437Found in file sv.c
1438
954c1994
GS
1439=item newSVrv
1440
1441Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
1442it will be upgraded to one. If C<classname> is non-null then the new SV will
1443be blessed in the specified package. The new SV is returned and its
1444reference count is 1.
1445
1446 SV* newSVrv(SV* rv, const char* classname)
1447
497711e7
GS
1448=for hackers
1449Found in file sv.c
1450
954c1994
GS
1451=item newSVsv
1452
1453Creates a new SV which is an exact duplicate of the original SV.
645c22ef 1454(Uses C<sv_setsv>).
954c1994
GS
1455
1456 SV* newSVsv(SV* old)
1457
497711e7
GS
1458=for hackers
1459Found in file sv.c
1460
1a3327fb
JH
1461=item newSVuv
1462
1463Creates a new SV and copies an unsigned integer into it.
1464The reference count for the SV is set to 1.
1465
1466 SV* newSVuv(UV u)
1467
497711e7
GS
1468=for hackers
1469Found in file sv.c
1470
954c1994
GS
1471=item newXS
1472
1473Used by C<xsubpp> to hook up XSUBs as Perl subs.
1474
497711e7 1475=for hackers
fa519979 1476Found in file op.c
497711e7 1477
954c1994
GS
1478=item newXSproto
1479
1480Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1481the subs.
1482
497711e7
GS
1483=for hackers
1484Found in file XSUB.h
1485
954c1994
GS
1486=item Newz
1487
1488The XSUB-writer's interface to the C C<malloc> function. The allocated
1489memory is zeroed with C<memzero>.
1490
1491 void Newz(int id, void* ptr, int nitems, type)
1492
497711e7
GS
1493=for hackers
1494Found in file handy.h
1495
954c1994
GS
1496=item Nullav
1497
1498Null AV pointer.
1499
497711e7
GS
1500=for hackers
1501Found in file av.h
1502
954c1994
GS
1503=item Nullch
1504
1505Null character pointer.
1506
497711e7
GS
1507=for hackers
1508Found in file handy.h
1509
954c1994
GS
1510=item Nullcv
1511
1512Null CV pointer.
1513
497711e7
GS
1514=for hackers
1515Found in file cv.h
1516
954c1994
GS
1517=item Nullhv
1518
1519Null HV pointer.
1520
497711e7
GS
1521=for hackers
1522Found in file hv.h
1523
954c1994
GS
1524=item Nullsv
1525
1526Null SV pointer.
1527
497711e7
GS
1528=for hackers
1529Found in file handy.h
1530
954c1994
GS
1531=item ORIGMARK
1532
1533The original stack mark for the XSUB. See C<dORIGMARK>.
1534
497711e7
GS
1535=for hackers
1536Found in file pp.h
1537
954c1994
GS
1538=item perl_alloc
1539
1540Allocates a new Perl interpreter. See L<perlembed>.
1541
1542 PerlInterpreter* perl_alloc()
1543
497711e7
GS
1544=for hackers
1545Found in file perl.c
1546
645c22ef
DM
1547=item perl_clone
1548
1549Create and return a new interpreter by cloning the current one.
1550
1551 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
1552
1553=for hackers
1554Found in file sv.c
1555
954c1994
GS
1556=item perl_construct
1557
1558Initializes a new Perl interpreter. See L<perlembed>.
1559
1560 void perl_construct(PerlInterpreter* interp)
1561
497711e7
GS
1562=for hackers
1563Found in file perl.c
1564
954c1994
GS
1565=item perl_destruct
1566
1567Shuts down a Perl interpreter. See L<perlembed>.
1568
1569 void perl_destruct(PerlInterpreter* interp)
1570
497711e7
GS
1571=for hackers
1572Found in file perl.c
1573
954c1994
GS
1574=item perl_free
1575
1576Releases a Perl interpreter. See L<perlembed>.
1577
1578 void perl_free(PerlInterpreter* interp)
1579
497711e7
GS
1580=for hackers
1581Found in file perl.c
1582
954c1994
GS
1583=item perl_parse
1584
1585Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1586
1587 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1588
497711e7
GS
1589=for hackers
1590Found in file perl.c
1591
954c1994
GS
1592=item perl_run
1593
1594Tells a Perl interpreter to run. See L<perlembed>.
1595
1596 int perl_run(PerlInterpreter* interp)
1597
497711e7
GS
1598=for hackers
1599Found in file perl.c
1600
954c1994
GS
1601=item PL_modglobal
1602
ae154d6d 1603C<PL_modglobal> is a general purpose, interpreter global HV for use by
954c1994 1604extensions that need to keep information on a per-interpreter basis.
ae154d6d
JH
1605In a pinch, it can also be used as a symbol table for extensions
1606to share data among each other. It is a good idea to use keys
954c1994
GS
1607prefixed by the package name of the extension that owns the data.
1608
1609 HV* PL_modglobal
1610
497711e7
GS
1611=for hackers
1612Found in file intrpvar.h
1613
954c1994
GS
1614=item PL_na
1615
1616A convenience variable which is typically used with C<SvPV> when one
1617doesn't care about the length of the string. It is usually more efficient
1618to either declare a local variable and use that instead or to use the
1619C<SvPV_nolen> macro.
1620
1621 STRLEN PL_na
1622
497711e7
GS
1623=for hackers
1624Found in file thrdvar.h
1625
954c1994
GS
1626=item PL_sv_no
1627
1628This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1629C<&PL_sv_no>.
1630
1631 SV PL_sv_no
1632
497711e7
GS
1633=for hackers
1634Found in file intrpvar.h
1635
954c1994
GS
1636=item PL_sv_undef
1637
1638This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1639
1640 SV PL_sv_undef
1641
497711e7
GS
1642=for hackers
1643Found in file intrpvar.h
1644
954c1994
GS
1645=item PL_sv_yes
1646
1647This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1648C<&PL_sv_yes>.
1649
1650 SV PL_sv_yes
1651
497711e7
GS
1652=for hackers
1653Found in file intrpvar.h
1654
954c1994
GS
1655=item POPi
1656
1657Pops an integer off the stack.
1658
1659 IV POPi
1660
497711e7
GS
1661=for hackers
1662Found in file pp.h
1663
954c1994
GS
1664=item POPl
1665
1666Pops a long off the stack.
1667
1668 long POPl
1669
497711e7
GS
1670=for hackers
1671Found in file pp.h
1672
954c1994
GS
1673=item POPn
1674
1675Pops a double off the stack.
1676
1677 NV POPn
1678
497711e7
GS
1679=for hackers
1680Found in file pp.h
1681
954c1994
GS
1682=item POPp
1683
fa519979
JH
1684Pops a string off the stack. Deprecated. New code should provide
1685a STRLEN n_a and use POPpx.
954c1994
GS
1686
1687 char* POPp
1688
497711e7
GS
1689=for hackers
1690Found in file pp.h
1691
fa519979
JH
1692=item POPpbytex
1693
1694Pops a string off the stack which must consist of bytes i.e. characters < 256.
1695Requires a variable STRLEN n_a in scope.
1696
1697 char* POPpbytex
1698
1699=for hackers
1700Found in file pp.h
1701
1702=item POPpx
1703
1704Pops a string off the stack.
1705Requires a variable STRLEN n_a in scope.
1706
1707 char* POPpx
1708
1709=for hackers
1710Found in file pp.h
1711
954c1994
GS
1712=item POPs
1713
1714Pops an SV off the stack.
1715
1716 SV* POPs
1717
497711e7
GS
1718=for hackers
1719Found in file pp.h
1720
954c1994
GS
1721=item PUSHi
1722
1723Push an integer onto the stack. The stack must have room for this element.
1724Handles 'set' magic. See C<XPUSHi>.
1725
1726 void PUSHi(IV iv)
1727
497711e7
GS
1728=for hackers
1729Found in file pp.h
1730
954c1994
GS
1731=item PUSHMARK
1732
1733Opening bracket for arguments on a callback. See C<PUTBACK> and
1734L<perlcall>.
1735
1736 PUSHMARK;
1737
497711e7
GS
1738=for hackers
1739Found in file pp.h
1740
954c1994
GS
1741=item PUSHn
1742
1743Push a double onto the stack. The stack must have room for this element.
1744Handles 'set' magic. See C<XPUSHn>.
1745
1746 void PUSHn(NV nv)
1747
497711e7
GS
1748=for hackers
1749Found in file pp.h
1750
954c1994
GS
1751=item PUSHp
1752
1753Push a string onto the stack. The stack must have room for this element.
1754The C<len> indicates the length of the string. Handles 'set' magic. See
1755C<XPUSHp>.
1756
1757 void PUSHp(char* str, STRLEN len)
1758
497711e7
GS
1759=for hackers
1760Found in file pp.h
1761
954c1994
GS
1762=item PUSHs
1763
1c846c1f 1764Push an SV onto the stack. The stack must have room for this element.
954c1994
GS
1765Does not handle 'set' magic. See C<XPUSHs>.
1766
1767 void PUSHs(SV* sv)
1768
497711e7
GS
1769=for hackers
1770Found in file pp.h
1771
954c1994
GS
1772=item PUSHu
1773
1774Push an unsigned integer onto the stack. The stack must have room for this
1775element. See C<XPUSHu>.
1776
1777 void PUSHu(UV uv)
1778
497711e7
GS
1779=for hackers
1780Found in file pp.h
1781
954c1994
GS
1782=item PUTBACK
1783
1784Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1785See C<PUSHMARK> and L<perlcall> for other uses.
1786
1787 PUTBACK;
1788
497711e7
GS
1789=for hackers
1790Found in file pp.h
1791
954c1994
GS
1792=item Renew
1793
1794The XSUB-writer's interface to the C C<realloc> function.
1795
1796 void Renew(void* ptr, int nitems, type)
1797
497711e7
GS
1798=for hackers
1799Found in file handy.h
1800
954c1994
GS
1801=item Renewc
1802
1803The XSUB-writer's interface to the C C<realloc> function, with
1804cast.
1805
1806 void Renewc(void* ptr, int nitems, type, cast)
1807
497711e7
GS
1808=for hackers
1809Found in file handy.h
1810
954c1994
GS
1811=item require_pv
1812
7d3fb230
BS
1813Tells Perl to C<require> the file named by the string argument. It is
1814analogous to the Perl code C<eval "require '$file'">. It's even
1815implemented that way; consider using Perl_load_module instead.
954c1994
GS
1816
1817NOTE: the perl_ form of this function is deprecated.
1818
1819 void require_pv(const char* pv)
1820
497711e7
GS
1821=for hackers
1822Found in file perl.c
1823
954c1994
GS
1824=item RETVAL
1825
1826Variable which is setup by C<xsubpp> to hold the return value for an
1827XSUB. This is always the proper type for the XSUB. See
1828L<perlxs/"The RETVAL Variable">.
1829
1830 (whatever) RETVAL
1831
497711e7
GS
1832=for hackers
1833Found in file XSUB.h
1834
954c1994
GS
1835=item Safefree
1836
1837The XSUB-writer's interface to the C C<free> function.
1838
49b8b560 1839 void Safefree(void* ptr)
954c1994 1840
497711e7
GS
1841=for hackers
1842Found in file handy.h
1843
954c1994
GS
1844=item savepv
1845
1846Copy a string to a safe spot. This does not use an SV.
1847
1848 char* savepv(const char* sv)
1849
497711e7
GS
1850=for hackers
1851Found in file util.c
1852
954c1994
GS
1853=item savepvn
1854
1855Copy a string to a safe spot. The C<len> indicates number of bytes to
1856copy. This does not use an SV.
1857
1858 char* savepvn(const char* sv, I32 len)
1859
497711e7
GS
1860=for hackers
1861Found in file util.c
1862
954c1994
GS
1863=item SAVETMPS
1864
1865Opening bracket for temporaries on a callback. See C<FREETMPS> and
1866L<perlcall>.
1867
1868 SAVETMPS;
1869
497711e7
GS
1870=for hackers
1871Found in file scope.h
1872
954c1994
GS
1873=item SP
1874
1875Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1876C<SPAGAIN>.
1877
497711e7
GS
1878=for hackers
1879Found in file pp.h
1880
954c1994
GS
1881=item SPAGAIN
1882
1883Refetch the stack pointer. Used after a callback. See L<perlcall>.
1884
1885 SPAGAIN;
1886
497711e7
GS
1887=for hackers
1888Found in file pp.h
1889
954c1994
GS
1890=item ST
1891
1892Used to access elements on the XSUB's stack.
1893
1894 SV* ST(int ix)
1895
497711e7
GS
1896=for hackers
1897Found in file XSUB.h
1898
954c1994
GS
1899=item strEQ
1900
1901Test two strings to see if they are equal. Returns true or false.
1902
1903 bool strEQ(char* s1, char* s2)
1904
497711e7
GS
1905=for hackers
1906Found in file handy.h
1907
954c1994
GS
1908=item strGE
1909
1910Test two strings to see if the first, C<s1>, is greater than or equal to
1911the second, C<s2>. Returns true or false.
1912
1913 bool strGE(char* s1, char* s2)
1914
497711e7
GS
1915=for hackers
1916Found in file handy.h
1917
954c1994
GS
1918=item strGT
1919
1920Test two strings to see if the first, C<s1>, is greater than the second,
1921C<s2>. Returns true or false.
1922
1923 bool strGT(char* s1, char* s2)
1924
497711e7
GS
1925=for hackers
1926Found in file handy.h
1927
954c1994
GS
1928=item strLE
1929
1930Test two strings to see if the first, C<s1>, is less than or equal to the
1931second, C<s2>. Returns true or false.
1932
1933 bool strLE(char* s1, char* s2)
1934
497711e7
GS
1935=for hackers
1936Found in file handy.h
1937
954c1994
GS
1938=item strLT
1939
1940Test two strings to see if the first, C<s1>, is less than the second,
1941C<s2>. Returns true or false.
1942
1943 bool strLT(char* s1, char* s2)
1944
497711e7
GS
1945=for hackers
1946Found in file handy.h
1947
954c1994
GS
1948=item strNE
1949
1950Test two strings to see if they are different. Returns true or
1951false.
1952
1953 bool strNE(char* s1, char* s2)
1954
497711e7
GS
1955=for hackers
1956Found in file handy.h
1957
954c1994
GS
1958=item strnEQ
1959
1960Test two strings to see if they are equal. The C<len> parameter indicates
1961the number of bytes to compare. Returns true or false. (A wrapper for
1962C<strncmp>).
1963
1964 bool strnEQ(char* s1, char* s2, STRLEN len)
1965
497711e7
GS
1966=for hackers
1967Found in file handy.h
1968
954c1994
GS
1969=item strnNE
1970
1971Test two strings to see if they are different. The C<len> parameter
1972indicates the number of bytes to compare. Returns true or false. (A
1973wrapper for C<strncmp>).
1974
1975 bool strnNE(char* s1, char* s2, STRLEN len)
1976
497711e7
GS
1977=for hackers
1978Found in file handy.h
1979
954c1994
GS
1980=item StructCopy
1981
4375e838 1982This is an architecture-independent macro to copy one structure to another.
954c1994
GS
1983
1984 void StructCopy(type src, type dest, type)
1985
497711e7
GS
1986=for hackers
1987Found in file handy.h
1988
954c1994
GS
1989=item SvCUR
1990
1991Returns the length of the string which is in the SV. See C<SvLEN>.
1992
1993 STRLEN SvCUR(SV* sv)
1994
497711e7
GS
1995=for hackers
1996Found in file sv.h
1997
954c1994
GS
1998=item SvCUR_set
1999
2000Set the length of the string which is in the SV. See C<SvCUR>.
2001
2002 void SvCUR_set(SV* sv, STRLEN len)
2003
497711e7
GS
2004=for hackers
2005Found in file sv.h
2006
954c1994
GS
2007=item SvEND
2008
2009Returns a pointer to the last character in the string which is in the SV.
2010See C<SvCUR>. Access the character as *(SvEND(sv)).
2011
2012 char* SvEND(SV* sv)
2013
497711e7
GS
2014=for hackers
2015Found in file sv.h
2016
954c1994
GS
2017=item SvGETMAGIC
2018
2019Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2020argument more than once.
2021
2022 void SvGETMAGIC(SV* sv)
2023
497711e7
GS
2024=for hackers
2025Found in file sv.h
2026
954c1994
GS
2027=item SvGROW
2028
2029Expands the character buffer in the SV so that it has room for the
2030indicated number of bytes (remember to reserve space for an extra trailing
2031NUL character). Calls C<sv_grow> to perform the expansion if necessary.
2032Returns a pointer to the character buffer.
2033
679ac26e 2034 char * SvGROW(SV* sv, STRLEN len)
954c1994 2035
497711e7
GS
2036=for hackers
2037Found in file sv.h
2038
954c1994
GS
2039=item SvIOK
2040
2041Returns a boolean indicating whether the SV contains an integer.
2042
2043 bool SvIOK(SV* sv)
2044
497711e7
GS
2045=for hackers
2046Found in file sv.h
2047
954c1994
GS
2048=item SvIOKp
2049
2050Returns a boolean indicating whether the SV contains an integer. Checks
2051the B<private> setting. Use C<SvIOK>.
2052
2053 bool SvIOKp(SV* sv)
2054
497711e7
GS
2055=for hackers
2056Found in file sv.h
2057
e331fc52
JH
2058=item SvIOK_notUV
2059
2060Returns a boolean indicating whether the SV contains an signed integer.
2061
2062 void SvIOK_notUV(SV* sv)
2063
2064=for hackers
2065Found in file sv.h
2066
954c1994
GS
2067=item SvIOK_off
2068
2069Unsets the IV status of an SV.
2070
2071 void SvIOK_off(SV* sv)
2072
497711e7
GS
2073=for hackers
2074Found in file sv.h
2075
954c1994
GS
2076=item SvIOK_on
2077
2078Tells an SV that it is an integer.
2079
2080 void SvIOK_on(SV* sv)
2081
497711e7
GS
2082=for hackers
2083Found in file sv.h
2084
954c1994
GS
2085=item SvIOK_only
2086
2087Tells an SV that it is an integer and disables all other OK bits.
2088
2089 void SvIOK_only(SV* sv)
2090
497711e7
GS
2091=for hackers
2092Found in file sv.h
2093
e331fc52
JH
2094=item SvIOK_only_UV
2095
2096Tells and SV that it is an unsigned integer and disables all other OK bits.
2097
2098 void SvIOK_only_UV(SV* sv)
2099
2100=for hackers
2101Found in file sv.h
2102
2103=item SvIOK_UV
2104
2105Returns a boolean indicating whether the SV contains an unsigned integer.
2106
2107 void SvIOK_UV(SV* sv)
2108
2109=for hackers
2110Found in file sv.h
2111
954c1994
GS
2112=item SvIV
2113
645c22ef
DM
2114Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2115version which guarantees to evaluate sv only once.
954c1994
GS
2116
2117 IV SvIV(SV* sv)
2118
497711e7
GS
2119=for hackers
2120Found in file sv.h
2121
e5dd39fc 2122=item SvIVx
954c1994 2123
e5dd39fc
AB
2124Coerces the given SV to an integer and returns it. Guarantees to evaluate
2125sv only once. Use the more efficent C<SvIV> otherwise.
954c1994 2126
e5dd39fc 2127 IV SvIVx(SV* sv)
954c1994 2128
497711e7
GS
2129=for hackers
2130Found in file sv.h
2131
e5dd39fc 2132=item SvIVX
645c22ef 2133
e5dd39fc
AB
2134Returns the raw value in the SV's IV slot, without checks or conversions.
2135Only use when you are sure SvIOK is true. See also C<SvIV()>.
645c22ef 2136
e5dd39fc 2137 IV SvIVX(SV* sv)
645c22ef
DM
2138
2139=for hackers
2140Found in file sv.h
2141
954c1994
GS
2142=item SvLEN
2143
91e74348
JH
2144Returns the size of the string buffer in the SV, not including any part
2145attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
2146
2147 STRLEN SvLEN(SV* sv)
2148
497711e7
GS
2149=for hackers
2150Found in file sv.h
2151
954c1994
GS
2152=item SvNIOK
2153
2154Returns a boolean indicating whether the SV contains a number, integer or
2155double.
2156
2157 bool SvNIOK(SV* sv)
2158
497711e7
GS
2159=for hackers
2160Found in file sv.h
2161
954c1994
GS
2162=item SvNIOKp
2163
2164Returns a boolean indicating whether the SV contains a number, integer or
2165double. Checks the B<private> setting. Use C<SvNIOK>.
2166
2167 bool SvNIOKp(SV* sv)
2168
497711e7
GS
2169=for hackers
2170Found in file sv.h
2171
954c1994
GS
2172=item SvNIOK_off
2173
2174Unsets the NV/IV status of an SV.
2175
2176 void SvNIOK_off(SV* sv)
2177
497711e7
GS
2178=for hackers
2179Found in file sv.h
2180
954c1994
GS
2181=item SvNOK
2182
2183Returns a boolean indicating whether the SV contains a double.
2184
2185 bool SvNOK(SV* sv)
2186
497711e7
GS
2187=for hackers
2188Found in file sv.h
2189
954c1994
GS
2190=item SvNOKp
2191
2192Returns a boolean indicating whether the SV contains a double. Checks the
2193B<private> setting. Use C<SvNOK>.
2194
2195 bool SvNOKp(SV* sv)
2196
497711e7
GS
2197=for hackers
2198Found in file sv.h
2199
954c1994
GS
2200=item SvNOK_off
2201
2202Unsets the NV status of an SV.
2203
2204 void SvNOK_off(SV* sv)
2205
497711e7
GS
2206=for hackers
2207Found in file sv.h
2208
954c1994
GS
2209=item SvNOK_on
2210
2211Tells an SV that it is a double.
2212
2213 void SvNOK_on(SV* sv)
2214
497711e7
GS
2215=for hackers
2216Found in file sv.h
2217
954c1994
GS
2218=item SvNOK_only
2219
2220Tells an SV that it is a double and disables all other OK bits.
2221
2222 void SvNOK_only(SV* sv)
2223
497711e7
GS
2224=for hackers
2225Found in file sv.h
2226
954c1994
GS
2227=item SvNV
2228
645c22ef
DM
2229Coerce the given SV to a double and return it. See C<SvNVx> for a version
2230which guarantees to evaluate sv only once.
954c1994
GS
2231
2232 NV SvNV(SV* sv)
2233
497711e7
GS
2234=for hackers
2235Found in file sv.h
2236
8eceec63 2237=item SvNVx
645c22ef 2238
8eceec63
SC
2239Coerces the given SV to a double and returns it. Guarantees to evaluate
2240sv only once. Use the more efficent C<SvNV> otherwise.
645c22ef 2241
8eceec63 2242 NV SvNVx(SV* sv)
645c22ef
DM
2243
2244=for hackers
2245Found in file sv.h
2246
8eceec63 2247=item SvNVX
954c1994 2248
8eceec63
SC
2249Returns the raw value in the SV's NV slot, without checks or conversions.
2250Only use when you are sure SvNOK is true. See also C<SvNV()>.
954c1994 2251
8eceec63 2252 NV SvNVX(SV* sv)
954c1994 2253
497711e7
GS
2254=for hackers
2255Found in file sv.h
2256
954c1994
GS
2257=item SvOK
2258
2259Returns a boolean indicating whether the value is an SV.
2260
2261 bool SvOK(SV* sv)
2262
497711e7
GS
2263=for hackers
2264Found in file sv.h
2265
954c1994
GS
2266=item SvOOK
2267
2268Returns a boolean indicating whether the SvIVX is a valid offset value for
2269the SvPVX. This hack is used internally to speed up removal of characters
2270from the beginning of a SvPV. When SvOOK is true, then the start of the
2271allocated string buffer is really (SvPVX - SvIVX).
2272
2273 bool SvOOK(SV* sv)
2274
497711e7
GS
2275=for hackers
2276Found in file sv.h
2277
954c1994
GS
2278=item SvPOK
2279
2280Returns a boolean indicating whether the SV contains a character
2281string.
2282
2283 bool SvPOK(SV* sv)
2284
497711e7
GS
2285=for hackers
2286Found in file sv.h
2287
954c1994
GS
2288=item SvPOKp
2289
2290Returns a boolean indicating whether the SV contains a character string.
2291Checks the B<private> setting. Use C<SvPOK>.
2292
2293 bool SvPOKp(SV* sv)
2294
497711e7
GS
2295=for hackers
2296Found in file sv.h
2297
954c1994
GS
2298=item SvPOK_off
2299
2300Unsets the PV status of an SV.
2301
2302 void SvPOK_off(SV* sv)
2303
497711e7
GS
2304=for hackers
2305Found in file sv.h
2306
954c1994
GS
2307=item SvPOK_on
2308
2309Tells an SV that it is a string.
2310
2311 void SvPOK_on(SV* sv)
2312
497711e7
GS
2313=for hackers
2314Found in file sv.h
2315
954c1994
GS
2316=item SvPOK_only
2317
2318Tells an SV that it is a string and disables all other OK bits.
d5ce4a7c 2319Will also turn off the UTF8 status.
954c1994
GS
2320
2321 void SvPOK_only(SV* sv)
2322
497711e7
GS
2323=for hackers
2324Found in file sv.h
2325
914184e1
JH
2326=item SvPOK_only_UTF8
2327
d5ce4a7c
GA
2328Tells an SV that it is a string and disables all other OK bits,
2329and leaves the UTF8 status as it was.
f1a1024e 2330
914184e1
JH
2331 void SvPOK_only_UTF8(SV* sv)
2332
2333=for hackers
2334Found in file sv.h
2335
954c1994
GS
2336=item SvPV
2337
2338Returns a pointer to the string in the SV, or a stringified form of the SV
645c22ef
DM
2339if the SV does not contain a string. Handles 'get' magic. See also
2340C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
2341
2342 char* SvPV(SV* sv, STRLEN len)
2343
497711e7
GS
2344=for hackers
2345Found in file sv.h
2346
645c22ef
DM
2347=item SvPVbyte
2348
2349Like C<SvPV>, but converts sv to byte representation first if necessary.
2350
2351 char* SvPVbyte(SV* sv, STRLEN len)
2352
2353=for hackers
2354Found in file sv.h
2355
2356=item SvPVbytex
2357
2358Like C<SvPV>, but converts sv to byte representation first if necessary.
2359Guarantees to evalute sv only once; use the more efficient C<SvPVbyte>
2360otherwise.
2361
2362
2363 char* SvPVbytex(SV* sv, STRLEN len)
2364
2365=for hackers
2366Found in file sv.h
2367
2368=item SvPVbytex_force
2369
2370Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2371Guarantees to evalute sv only once; use the more efficient C<SvPVbyte_force>
2372otherwise.
2373
2374 char* SvPVbytex_force(SV* sv, STRLEN len)
2375
2376=for hackers
2377Found in file sv.h
2378
2379=item SvPVbyte_force
2380
2381Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2382
2383 char* SvPVbyte_force(SV* sv, STRLEN len)
2384
2385=for hackers
2386Found in file sv.h
2387
2388=item SvPVbyte_nolen
2389
2390Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2391
2392 char* SvPVbyte_nolen(SV* sv, STRLEN len)
2393
2394=for hackers
2395Found in file sv.h
2396
2397=item SvPVutf8
2398
2399Like C<SvPV>, but converts sv to uft8 first if necessary.
2400
2401 char* SvPVutf8(SV* sv, STRLEN len)
2402
2403=for hackers
2404Found in file sv.h
2405
2406=item SvPVutf8x
2407
2408Like C<SvPV>, but converts sv to uft8 first if necessary.
2409Guarantees to evalute sv only once; use the more efficient C<SvPVutf8>
2410otherwise.
2411
2412 char* SvPVutf8x(SV* sv, STRLEN len)
2413
2414=for hackers
2415Found in file sv.h
2416
2417=item SvPVutf8x_force
2418
2419Like C<SvPV_force>, but converts sv to uft8 first if necessary.
2420Guarantees to evalute sv only once; use the more efficient C<SvPVutf8_force>
2421otherwise.
2422
2423 char* SvPVutf8x_force(SV* sv, STRLEN len)
2424
2425=for hackers
2426Found in file sv.h
2427
2428=item SvPVutf8_force
2429
2430Like C<SvPV_force>, but converts sv to uft8 first if necessary.
2431
2432 char* SvPVutf8_force(SV* sv, STRLEN len)
2433
2434=for hackers
2435Found in file sv.h
2436
2437=item SvPVutf8_nolen
2438
2439Like C<SvPV_nolen>, but converts sv to uft8 first if necessary.
2440
2441 char* SvPVutf8_nolen(SV* sv, STRLEN len)
2442
2443=for hackers
2444Found in file sv.h
2445
e5dd39fc 2446=item SvPVx
645c22ef 2447
e5dd39fc 2448A version of C<SvPV> which guarantees to evaluate sv only once.
645c22ef 2449
e5dd39fc 2450 char* SvPVx(SV* sv, STRLEN len)
645c22ef
DM
2451
2452=for hackers
2453Found in file sv.h
2454
e5dd39fc 2455=item SvPVX
954c1994 2456
e5dd39fc
AB
2457Returns a pointer to the physical string in the SV. The SV must contain a
2458string.
954c1994 2459
e5dd39fc 2460 char* SvPVX(SV* sv)
954c1994 2461
497711e7
GS
2462=for hackers
2463Found in file sv.h
2464
954c1994
GS
2465=item SvPV_force
2466
2467Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2468force if you are going to update the SvPVX directly.
2469
2470 char* SvPV_force(SV* sv, STRLEN len)
2471
497711e7
GS
2472=for hackers
2473Found in file sv.h
2474
645c22ef
DM
2475=item SvPV_force_nomg
2476
2477Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2478force if you are going to update the SvPVX directly. Doesn't process magic.
2479
2480 char* SvPV_force_nomg(SV* sv, STRLEN len)
2481
2482=for hackers
2483Found in file sv.h
2484
954c1994
GS
2485=item SvPV_nolen
2486
2487Returns a pointer to the string in the SV, or a stringified form of the SV
2488if the SV does not contain a string. Handles 'get' magic.
2489
2490 char* SvPV_nolen(SV* sv)
2491
497711e7
GS
2492=for hackers
2493Found in file sv.h
2494
954c1994
GS
2495=item SvREFCNT
2496
2497Returns the value of the object's reference count.
2498
2499 U32 SvREFCNT(SV* sv)
2500
497711e7
GS
2501=for hackers
2502Found in file sv.h
2503
954c1994
GS
2504=item SvREFCNT_dec
2505
2506Decrements the reference count of the given SV.
2507
2508 void SvREFCNT_dec(SV* sv)
2509
497711e7
GS
2510=for hackers
2511Found in file sv.h
2512
954c1994
GS
2513=item SvREFCNT_inc
2514
2515Increments the reference count of the given SV.
2516
2517 SV* SvREFCNT_inc(SV* sv)
2518
497711e7
GS
2519=for hackers
2520Found in file sv.h
2521
954c1994
GS
2522=item SvROK
2523
2524Tests if the SV is an RV.
2525
2526 bool SvROK(SV* sv)
2527
497711e7
GS
2528=for hackers
2529Found in file sv.h
2530
954c1994
GS
2531=item SvROK_off
2532
2533Unsets the RV status of an SV.
2534
2535 void SvROK_off(SV* sv)
2536
497711e7
GS
2537=for hackers
2538Found in file sv.h
2539
954c1994
GS
2540=item SvROK_on
2541
2542Tells an SV that it is an RV.
2543
2544 void SvROK_on(SV* sv)
2545
497711e7
GS
2546=for hackers
2547Found in file sv.h
2548
954c1994
GS
2549=item SvRV
2550
2551Dereferences an RV to return the SV.
2552
2553 SV* SvRV(SV* sv)
2554
497711e7
GS
2555=for hackers
2556Found in file sv.h
2557
954c1994
GS
2558=item SvSETMAGIC
2559
2560Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2561argument more than once.
2562
2563 void SvSETMAGIC(SV* sv)
2564
497711e7
GS
2565=for hackers
2566Found in file sv.h
2567
645c22ef
DM
2568=item SvSetMagicSV
2569
2570Like C<SvSetSV>, but does any set magic required afterwards.
2571
2572 void SvSetMagicSV(SV* dsb, SV* ssv)
2573
2574=for hackers
2575Found in file sv.h
2576
2577=item SvSetMagicSV_nosteal
2578
2579Like C<SvSetMagicSV>, but does any set magic required afterwards.
2580
2581 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2582
2583=for hackers
2584Found in file sv.h
2585
954c1994
GS
2586=item SvSetSV
2587
2588Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2589more than once.
2590
2591 void SvSetSV(SV* dsb, SV* ssv)
2592
497711e7
GS
2593=for hackers
2594Found in file sv.h
2595
954c1994
GS
2596=item SvSetSV_nosteal
2597
2598Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2599ssv. May evaluate arguments more than once.
2600
2601 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2602
497711e7
GS
2603=for hackers
2604Found in file sv.h
2605
954c1994
GS
2606=item SvSTASH
2607
2608Returns the stash of the SV.
2609
2610 HV* SvSTASH(SV* sv)
2611
497711e7
GS
2612=for hackers
2613Found in file sv.h
2614
954c1994
GS
2615=item SvTAINT
2616
2617Taints an SV if tainting is enabled
2618
2619 void SvTAINT(SV* sv)
2620
497711e7
GS
2621=for hackers
2622Found in file sv.h
2623
954c1994
GS
2624=item SvTAINTED
2625
2626Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2627not.
2628
2629 bool SvTAINTED(SV* sv)
2630
497711e7
GS
2631=for hackers
2632Found in file sv.h
2633
954c1994
GS
2634=item SvTAINTED_off
2635
2636Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2637some of Perl's fundamental security features. XS module authors should not
2638use this function unless they fully understand all the implications of
2639unconditionally untainting the value. Untainting should be done in the
2640standard perl fashion, via a carefully crafted regexp, rather than directly
2641untainting variables.
2642
2643 void SvTAINTED_off(SV* sv)
2644
497711e7
GS
2645=for hackers
2646Found in file sv.h
2647
954c1994
GS
2648=item SvTAINTED_on
2649
2650Marks an SV as tainted.
2651
2652 void SvTAINTED_on(SV* sv)
2653
497711e7
GS
2654=for hackers
2655Found in file sv.h
2656
954c1994
GS
2657=item SvTRUE
2658
2659Returns a boolean indicating whether Perl would evaluate the SV as true or
2660false, defined or undefined. Does not handle 'get' magic.
2661
2662 bool SvTRUE(SV* sv)
2663
497711e7
GS
2664=for hackers
2665Found in file sv.h
2666
e5dd39fc 2667=item SvTYPE
59075ca9 2668
e5dd39fc
AB
2669Returns the type of the SV. See C<svtype>.
2670
2671 svtype SvTYPE(SV* sv)
34f7a5fe 2672
497711e7
GS
2673=for hackers
2674Found in file sv.h
2675
e5dd39fc 2676=item svtype
1fcf4c12 2677
e5dd39fc
AB
2678An enum of flags for Perl types. These are found in the file B<sv.h>
2679in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2680
497711e7
GS
2681=for hackers
2682Found in file sv.h
2683
954c1994
GS
2684=item SVt_IV
2685
2686Integer type flag for scalars. See C<svtype>.
2687
497711e7
GS
2688=for hackers
2689Found in file sv.h
2690
954c1994
GS
2691=item SVt_NV
2692
2693Double type flag for scalars. See C<svtype>.
2694
497711e7
GS
2695=for hackers
2696Found in file sv.h
2697
954c1994
GS
2698=item SVt_PV
2699
2700Pointer type flag for scalars. See C<svtype>.
2701
497711e7
GS
2702=for hackers
2703Found in file sv.h
2704
954c1994
GS
2705=item SVt_PVAV
2706
2707Type flag for arrays. See C<svtype>.
2708
497711e7
GS
2709=for hackers
2710Found in file sv.h
2711
954c1994
GS
2712=item SVt_PVCV
2713
2714Type flag for code refs. See C<svtype>.
2715
497711e7
GS
2716=for hackers
2717Found in file sv.h
2718
954c1994
GS
2719=item SVt_PVHV
2720
2721Type flag for hashes. See C<svtype>.
2722
497711e7
GS
2723=for hackers
2724Found in file sv.h
2725
954c1994
GS
2726=item SVt_PVMG
2727
2728Type flag for blessed scalars. See C<svtype>.
2729
497711e7
GS
2730=for hackers
2731Found in file sv.h
2732
a8586c98
JH
2733=item SvUOK
2734
2735Returns a boolean indicating whether the SV contains an unsigned integer.
2736
2737 void SvUOK(SV* sv)
2738
2739=for hackers
2740Found in file sv.h
2741
954c1994
GS
2742=item SvUPGRADE
2743
2744Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
2745perform the upgrade if necessary. See C<svtype>.
2746
2747 void SvUPGRADE(SV* sv, svtype type)
2748
497711e7
GS
2749=for hackers
2750Found in file sv.h
2751
914184e1
JH
2752=item SvUTF8
2753
2754Returns a boolean indicating whether the SV contains UTF-8 encoded data.
2755
2756 void SvUTF8(SV* sv)
2757
2758=for hackers
2759Found in file sv.h
2760
2761=item SvUTF8_off
2762
2763Unsets the UTF8 status of an SV.
2764
2765 void SvUTF8_off(SV *sv)
2766
2767=for hackers
2768Found in file sv.h
2769
2770=item SvUTF8_on
2771
d5ce4a7c
GA
2772Turn on the UTF8 status of an SV (the data is not changed, just the flag).
2773Do not use frivolously.
914184e1
JH
2774
2775 void SvUTF8_on(SV *sv)
2776
2777=for hackers
2778Found in file sv.h
2779
954c1994
GS
2780=item SvUV
2781
645c22ef
DM
2782Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
2783for a version which guarantees to evaluate sv only once.
954c1994
GS
2784
2785 UV SvUV(SV* sv)
2786
497711e7
GS
2787=for hackers
2788Found in file sv.h
2789
89423764 2790=item SvUVX
954c1994 2791
89423764
GS
2792Returns the raw value in the SV's UV slot, without checks or conversions.
2793Only use when you are sure SvIOK is true. See also C<SvUV()>.
954c1994 2794
89423764 2795 UV SvUVX(SV* sv)
954c1994 2796
497711e7
GS
2797=for hackers
2798Found in file sv.h
2799
89423764 2800=item SvUVx
645c22ef 2801
89423764
GS
2802Coerces the given SV to an unsigned integer and returns it. Guarantees to
2803evaluate sv only once. Use the more efficent C<SvUV> otherwise.
645c22ef 2804
89423764 2805 UV SvUVx(SV* sv)
645c22ef
DM
2806
2807=for hackers
2808Found in file sv.h
2809
2810=item sv_2bool
2811
2812This function is only called on magical items, and is only used by
2813sv_true() or its macro equivalent.
2814
2815 bool sv_2bool(SV* sv)
2816
2817=for hackers
2818Found in file sv.c
2819
2820=item sv_2cv
2821
2822Using various gambits, try to get a CV from an SV; in addition, try if
2823possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
2824
2825 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
2826
2827=for hackers
2828Found in file sv.c
2829
2830=item sv_2io
2831
2832Using various gambits, try to get an IO from an SV: the IO slot if its a
2833GV; or the recursive result if we're an RV; or the IO slot of the symbol
2834named after the PV if we're a string.
2835
2836 IO* sv_2io(SV* sv)
2837
2838=for hackers
2839Found in file sv.c
2840
2841=item sv_2iv
2842
2843Return the integer value of an SV, doing any necessary string conversion,
2844magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
2845
2846 IV sv_2iv(SV* sv)
2847
2848=for hackers
2849Found in file sv.c
2850
954c1994
GS
2851=item sv_2mortal
2852
793edb8a
JH
2853Marks an existing SV as mortal. The SV will be destroyed "soon", either
2854by an explicit call to FREETMPS, or by an implicit call at places such as
2855statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
954c1994
GS
2856
2857 SV* sv_2mortal(SV* sv)
2858
497711e7
GS
2859=for hackers
2860Found in file sv.c
2861
645c22ef
DM
2862=item sv_2nv
2863
2864Return the num value of an SV, doing any necessary string or integer
2865conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
2866macros.
2867
2868 NV sv_2nv(SV* sv)
2869
2870=for hackers
2871Found in file sv.c
2872
451be7b1
DM
2873=item sv_2pvbyte
2874
2875Return a pointer to the byte-encoded representation of the SV, and set *lp
2876to its length. May cause the SV to be downgraded from UTF8 as a
2877side-effect.
2878
2879Usually accessed via the C<SvPVbyte> macro.
2880
2881 char* sv_2pvbyte(SV* sv, STRLEN* lp)
2882
2883=for hackers
2884Found in file sv.c
2885
645c22ef
DM
2886=item sv_2pvbyte_nolen
2887
2888Return a pointer to the byte-encoded representation of the SV.
2889May cause the SV to be downgraded from UTF8 as a side-effect.
2890
2891Usually accessed via the C<SvPVbyte_nolen> macro.
2892
2893 char* sv_2pvbyte_nolen(SV* sv)
2894
2895=for hackers
2896Found in file sv.c
2897
451be7b1
DM
2898=item sv_2pvutf8
2899
2900Return a pointer to the UTF8-encoded representation of the SV, and set *lp
2901to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
2902
2903Usually accessed via the C<SvPVutf8> macro.
2904
2905 char* sv_2pvutf8(SV* sv, STRLEN* lp)
2906
2907=for hackers
2908Found in file sv.c
2909
645c22ef
DM
2910=item sv_2pvutf8_nolen
2911
2912Return a pointer to the UTF8-encoded representation of the SV.
2913May cause the SV to be upgraded to UTF8 as a side-effect.
2914
2915Usually accessed via the C<SvPVutf8_nolen> macro.
2916
2917 char* sv_2pvutf8_nolen(SV* sv)
2918
2919=for hackers
2920Found in file sv.c
2921
2922=item sv_2pv_flags
2923
ff276b08 2924Returns a pointer to the string value of an SV, and sets *lp to its length.
645c22ef
DM
2925If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
2926if necessary.
2927Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
2928usually end up here too.
2929
2930 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
2931
2932=for hackers
2933Found in file sv.c
2934
2935=item sv_2pv_nolen
2936
2937Like C<sv_2pv()>, but doesn't return the length too. You should usually
2938use the macro wrapper C<SvPV_nolen(sv)> instead.
2939 char* sv_2pv_nolen(SV* sv)
2940
2941=for hackers
2942Found in file sv.c
2943
2944=item sv_2uv
2945
2946Return the unsigned integer value of an SV, doing any necessary string
2947conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
2948macros.
2949
2950 UV sv_2uv(SV* sv)
2951
2952=for hackers
2953Found in file sv.c
2954
2955=item sv_backoff
2956
2957Remove any string offset. You should normally use the C<SvOOK_off> macro
2958wrapper instead.
2959
2960 int sv_backoff(SV* sv)
2961
2962=for hackers
2963Found in file sv.c
2964
954c1994
GS
2965=item sv_bless
2966
2967Blesses an SV into a specified package. The SV must be an RV. The package
2968must be designated by its stash (see C<gv_stashpv()>). The reference count
2969of the SV is unaffected.
2970
2971 SV* sv_bless(SV* sv, HV* stash)
2972
497711e7
GS
2973=for hackers
2974Found in file sv.c
2975
954c1994
GS
2976=item sv_catpv
2977
2978Concatenates the string onto the end of the string which is in the SV.
d5ce4a7c
GA
2979If the SV has the UTF8 status set, then the bytes appended should be
2980valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
954c1994
GS
2981
2982 void sv_catpv(SV* sv, const char* ptr)
2983
497711e7
GS
2984=for hackers
2985Found in file sv.c
2986
954c1994
GS
2987=item sv_catpvf
2988
d5ce4a7c
GA
2989Processes its arguments like C<sprintf> and appends the formatted
2990output to an SV. If the appended data contains "wide" characters
2991(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
2992and characters >255 formatted with %c), the original SV might get
2993upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
2994C<SvSETMAGIC()> must typically be called after calling this function
2995to handle 'set' magic.
954c1994
GS
2996
2997 void sv_catpvf(SV* sv, const char* pat, ...)
2998
497711e7
GS
2999=for hackers
3000Found in file sv.c
3001
954c1994
GS
3002=item sv_catpvf_mg
3003
3004Like C<sv_catpvf>, but also handles 'set' magic.
3005
3006 void sv_catpvf_mg(SV *sv, const char* pat, ...)
3007
497711e7
GS
3008=for hackers
3009Found in file sv.c
3010
954c1994
GS
3011=item sv_catpvn
3012
3013Concatenates the string onto the end of the string which is in the SV. The
d5ce4a7c
GA
3014C<len> indicates number of bytes to copy. If the SV has the UTF8
3015status set, then the bytes appended should be valid UTF8.
3016Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
954c1994
GS
3017
3018 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3019
497711e7
GS
3020=for hackers
3021Found in file sv.c
3022
8d6d96c1
HS
3023=item sv_catpvn_flags
3024
3025Concatenates the string onto the end of the string which is in the SV. The
3026C<len> indicates number of bytes to copy. If the SV has the UTF8
3027status set, then the bytes appended should be valid UTF8.
3028If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3029appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3030in terms of this function.
3031
3032 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3033
3034=for hackers
3035Found in file sv.c
3036
954c1994
GS
3037=item sv_catpvn_mg
3038
3039Like C<sv_catpvn>, but also handles 'set' magic.
3040
3041 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3042
497711e7
GS
3043=for hackers
3044Found in file sv.c
3045
954c1994
GS
3046=item sv_catpv_mg
3047
3048Like C<sv_catpv>, but also handles 'set' magic.
3049
3050 void sv_catpv_mg(SV *sv, const char *ptr)
3051
497711e7
GS
3052=for hackers
3053Found in file sv.c
3054
954c1994
GS
3055=item sv_catsv
3056
1aa99e6b
IH
3057Concatenates the string from SV C<ssv> onto the end of the string in
3058SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
3059not 'set' magic. See C<sv_catsv_mg>.
954c1994
GS
3060
3061 void sv_catsv(SV* dsv, SV* ssv)
3062
497711e7
GS
3063=for hackers
3064Found in file sv.c
3065
8d6d96c1
HS
3066=item sv_catsv_flags
3067
3068Concatenates the string from SV C<ssv> onto the end of the string in
3069SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
3070bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3071and C<sv_catsv_nomg> are implemented in terms of this function.
3072
3073 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3074
3075=for hackers
3076Found in file sv.c
3077
954c1994
GS
3078=item sv_catsv_mg
3079
3080Like C<sv_catsv>, but also handles 'set' magic.
3081
3082 void sv_catsv_mg(SV *dstr, SV *sstr)
3083
497711e7
GS
3084=for hackers
3085Found in file sv.c
3086
954c1994
GS
3087=item sv_chop
3088
1c846c1f 3089Efficient removal of characters from the beginning of the string buffer.
954c1994
GS
3090SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3091the string buffer. The C<ptr> becomes the first character of the adjusted
645c22ef 3092string. Uses the "OOK hack".
954c1994
GS
3093
3094 void sv_chop(SV* sv, char* ptr)
3095
497711e7
GS
3096=for hackers
3097Found in file sv.c
3098
c461cf8f
JH
3099=item sv_clear
3100
645c22ef
DM
3101Clear an SV: call any destructors, free up any memory used by the body,
3102and free the body itself. The SV's head is I<not> freed, although
3103its type is set to all 1's so that it won't inadvertently be assumed
3104to be live during global destruction etc.
3105This function should only be called when REFCNT is zero. Most of the time
3106you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3107instead.
c461cf8f
JH
3108
3109 void sv_clear(SV* sv)
3110
3111=for hackers
3112Found in file sv.c
3113
954c1994
GS
3114=item sv_cmp
3115
3116Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
3117string in C<sv1> is less than, equal to, or greater than the string in
645c22ef
DM
3118C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3119coerce its args to strings if necessary. See also C<sv_cmp_locale>.
954c1994
GS
3120
3121 I32 sv_cmp(SV* sv1, SV* sv2)
3122
497711e7
GS
3123=for hackers
3124Found in file sv.c
3125
c461cf8f
JH
3126=item sv_cmp_locale
3127
645c22ef
DM
3128Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3129'use bytes' aware, handles get magic, and will coerce its args to strings
3130if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
c461cf8f
JH
3131
3132 I32 sv_cmp_locale(SV* sv1, SV* sv2)
3133
3134=for hackers
3135Found in file sv.c
3136
645c22ef
DM
3137=item sv_collxfrm
3138
3139Add Collate Transform magic to an SV if it doesn't already have it.
3140
3141Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3142scalar data of the variable, but transformed to such a format that a normal
3143memory comparison can be used to compare the data according to the locale
3144settings.
3145
3146 char* sv_collxfrm(SV* sv, STRLEN* nxp)
3147
3148=for hackers
3149Found in file sv.c
3150
954c1994
GS
3151=item sv_dec
3152
645c22ef
DM
3153Auto-decrement of the value in the SV, doing string to numeric conversion
3154if necessary. Handles 'get' magic.
954c1994
GS
3155
3156 void sv_dec(SV* sv)
3157
497711e7
GS
3158=for hackers
3159Found in file sv.c
3160
954c1994
GS
3161=item sv_derived_from
3162
3163Returns a boolean indicating whether the SV is derived from the specified
3164class. This is the function that implements C<UNIVERSAL::isa>. It works
3165for class names as well as for objects.
3166
3167 bool sv_derived_from(SV* sv, const char* name)
3168
497711e7
GS
3169=for hackers
3170Found in file universal.c
3171
954c1994
GS
3172=item sv_eq
3173
3174Returns a boolean indicating whether the strings in the two SVs are
645c22ef
DM
3175identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3176coerce its args to strings if necessary.
954c1994
GS
3177
3178 I32 sv_eq(SV* sv1, SV* sv2)
3179
497711e7
GS
3180=for hackers
3181Found in file sv.c
3182
645c22ef
DM
3183=item sv_force_normal
3184
3185Undo various types of fakery on an SV: if the PV is a shared string, make
3186a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3187an xpvmg. See also C<sv_force_normal_flags>.
3188
3189 void sv_force_normal(SV *sv)
3190
3191=for hackers
3192Found in file sv.c
3193
3194=item sv_force_normal_flags
3195
3196Undo various types of fakery on an SV: if the PV is a shared string, make
3197a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3198an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
3199when unrefing. C<sv_force_normal> calls this function with flags set to 0.
3200
3201 void sv_force_normal_flags(SV *sv, U32 flags)
3202
3203=for hackers
3204Found in file sv.c
3205
c461cf8f
JH
3206=item sv_free
3207
645c22ef
DM
3208Decrement an SV's reference count, and if it drops to zero, call
3209C<sv_clear> to invoke destructors and free up any memory used by
3210the body; finally, deallocate the SV's head itself.
3211Normally called via a wrapper macro C<SvREFCNT_dec>.
c461cf8f
JH
3212
3213 void sv_free(SV* sv)
3214
3215=for hackers
3216Found in file sv.c
3217
3218=item sv_gets
3219
3220Get a line from the filehandle and store it into the SV, optionally
3221appending to the currently-stored string.
3222
3223 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
3224
3225=for hackers
3226Found in file sv.c
3227
954c1994
GS
3228=item sv_grow
3229
645c22ef
DM
3230Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
3231upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
3232Use the C<SvGROW> wrapper instead.
954c1994
GS
3233
3234 char* sv_grow(SV* sv, STRLEN newlen)
3235
497711e7
GS
3236=for hackers
3237Found in file sv.c
3238
954c1994
GS
3239=item sv_inc
3240
645c22ef
DM
3241Auto-increment of the value in the SV, doing string to numeric conversion
3242if necessary. Handles 'get' magic.
954c1994
GS
3243
3244 void sv_inc(SV* sv)
3245
497711e7
GS
3246=for hackers
3247Found in file sv.c
3248
954c1994
GS
3249=item sv_insert
3250
3251Inserts a string at the specified offset/length within the SV. Similar to
3252the Perl substr() function.
3253
3254 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3255
497711e7
GS
3256=for hackers
3257Found in file sv.c
3258
954c1994
GS
3259=item sv_isa
3260
3261Returns a boolean indicating whether the SV is blessed into the specified
3262class. This does not check for subtypes; use C<sv_derived_from> to verify
3263an inheritance relationship.
3264
3265 int sv_isa(SV* sv, const char* name)
3266
497711e7
GS
3267=for hackers
3268Found in file sv.c
3269
954c1994
GS
3270=item sv_isobject
3271
3272Returns a boolean indicating whether the SV is an RV pointing to a blessed
3273object. If the SV is not an RV, or if the object is not blessed, then this
3274will return false.
3275
3276 int sv_isobject(SV* sv)
3277
497711e7
GS
3278=for hackers
3279Found in file sv.c
3280
645c22ef
DM
3281=item sv_iv
3282
3283A private implementation of the C<SvIVx> macro for compilers which can't
3284cope with complex macro expressions. Always use the macro instead.
3285
3286 IV sv_iv(SV* sv)
3287
3288=for hackers
3289Found in file sv.c
3290
954c1994
GS
3291=item sv_len
3292
645c22ef
DM
3293Returns the length of the string in the SV. Handles magic and type
3294coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
954c1994
GS
3295
3296 STRLEN sv_len(SV* sv)
3297
497711e7
GS
3298=for hackers
3299Found in file sv.c
3300
c461cf8f
JH
3301=item sv_len_utf8
3302
3303Returns the number of characters in the string in an SV, counting wide
645c22ef 3304UTF8 bytes as a single character. Handles magic and type coercion.
c461cf8f
JH
3305
3306 STRLEN sv_len_utf8(SV* sv)
3307
3308=for hackers
3309Found in file sv.c
3310
954c1994
GS
3311=item sv_magic
3312
645c22ef
DM
3313Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3314then adds a new magic item of type C<how> to the head of the magic list.
3315
3316C<name> is assumed to contain an C<SV*> if C<(name && namelen == HEf_SVKEY)>
954c1994
GS
3317
3318 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3319
497711e7
GS
3320=for hackers
3321Found in file sv.c
3322
954c1994
GS
3323=item sv_mortalcopy
3324
645c22ef 3325Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
793edb8a
JH
3326The new SV is marked as mortal. It will be destroyed "soon", either by an
3327explicit call to FREETMPS, or by an implicit call at places such as
3328statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
954c1994
GS
3329
3330 SV* sv_mortalcopy(SV* oldsv)
3331
497711e7
GS
3332=for hackers
3333Found in file sv.c
3334
954c1994
GS
3335=item sv_newmortal
3336
645c22ef 3337Creates a new null SV which is mortal. The reference count of the SV is
793edb8a
JH
3338set to 1. It will be destroyed "soon", either by an explicit call to
3339FREETMPS, or by an implicit call at places such as statement boundaries.
3340See also C<sv_mortalcopy> and C<sv_2mortal>.
954c1994
GS
3341
3342 SV* sv_newmortal()
3343
497711e7
GS
3344=for hackers
3345Found in file sv.c
3346
645c22ef
DM
3347=item sv_newref
3348
3349Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3350instead.
3351
3352 SV* sv_newref(SV* sv)
3353
3354=for hackers
3355Found in file sv.c
3356
3357=item sv_nv
3358
3359A private implementation of the C<SvNVx> macro for compilers which can't
3360cope with complex macro expressions. Always use the macro instead.
3361
3362 NV sv_nv(SV* sv)
3363
3364=for hackers
3365Found in file sv.c
3366
3367=item sv_pos_b2u
3368
3369Converts the value pointed to by offsetp from a count of bytes from the
3370start of the string, to a count of the equivalent number of UTF8 chars.
3371Handles magic and type coercion.
3372
3373 void sv_pos_b2u(SV* sv, I32* offsetp)
3374
3375=for hackers
3376Found in file sv.c
3377
3378=item sv_pos_u2b
3379
3380Converts the value pointed to by offsetp from a count of UTF8 chars from
3381the start of the string, to a count of the equivalent number of bytes; if
3382lenp is non-zero, it does the same to lenp, but this time starting from
3383the offset, rather than from the start of the string. Handles magic and
3384type coercion.
3385
3386 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3387
3388=for hackers
3389Found in file sv.c
3390
451be7b1
DM
3391=item sv_pv
3392
3393A private implementation of the C<SvPV_nolen> macro for compilers which can't
3394cope with complex macro expressions. Always use the macro instead.
3395
3396 char* sv_pv(SV *sv)
3397
3398=for hackers
3399Found in file sv.c
3400
645c22ef
DM
3401=item sv_pvbyte
3402
3403A private implementation of the C<SvPVbyte_nolen> macro for compilers
3404which can't cope with complex macro expressions. Always use the macro
3405instead.
3406
3407 char* sv_pvbyte(SV *sv)
3408
3409=for hackers
3410Found in file sv.c
3411
3412=item sv_pvbyten
3413
3414A private implementation of the C<SvPVbyte> macro for compilers
3415which can't cope with complex macro expressions. Always use the macro
3416instead.
3417
3418 char* sv_pvbyten(SV *sv, STRLEN *len)
3419
3420=for hackers
3421Found in file sv.c
3422
3423=item sv_pvbyten_force
3424
3425A private implementation of the C<SvPVbytex_force> macro for compilers
3426which can't cope with complex macro expressions. Always use the macro
3427instead.
3428
3429 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
3430
3431=for hackers
3432Found in file sv.c
3433
451be7b1
DM
3434=item sv_pvn
3435
3436A private implementation of the C<SvPV> macro for compilers which can't
3437cope with complex macro expressions. Always use the macro instead.
3438
3439 char* sv_pvn(SV *sv, STRLEN *len)
3440
3441=for hackers
3442Found in file sv.c
3443
c461cf8f
JH
3444=item sv_pvn_force
3445
3446Get a sensible string out of the SV somehow.
645c22ef
DM
3447A private implementation of the C<SvPV_force> macro for compilers which
3448can't cope with complex macro expressions. Always use the macro instead.
c461cf8f
JH
3449
3450 char* sv_pvn_force(SV* sv, STRLEN* lp)
3451
3452=for hackers
3453Found in file sv.c
3454
8d6d96c1
HS
3455=item sv_pvn_force_flags
3456
3457Get a sensible string out of the SV somehow.
3458If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
3459appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
3460implemented in terms of this function.
645c22ef
DM
3461You normally want to use the various wrapper macros instead: see
3462C<SvPV_force> and C<SvPV_force_nomg>
8d6d96c1
HS
3463
3464 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3465
3466=for hackers
3467Found in file sv.c
3468
645c22ef
DM
3469=item sv_pvutf8
3470
3471A private implementation of the C<SvPVutf8_nolen> macro for compilers
3472which can't cope with complex macro expressions. Always use the macro
3473instead.
3474
3475 char* sv_pvutf8(SV *sv)
3476
3477=for hackers
3478Found in file sv.c
3479
3480=item sv_pvutf8n
3481
3482A private implementation of the C<SvPVutf8> macro for compilers
3483which can't cope with complex macro expressions. Always use the macro
3484instead.
3485
3486 char* sv_pvutf8n(SV *sv, STRLEN *len)
3487
3488=for hackers
3489Found in file sv.c
3490
c461cf8f
JH
3491=item sv_pvutf8n_force
3492
645c22ef
DM
3493A private implementation of the C<SvPVutf8_force> macro for compilers
3494which can't cope with complex macro expressions. Always use the macro
3495instead.
c461cf8f
JH
3496
3497 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
3498
3499=for hackers
3500Found in file sv.c
3501
3502=item sv_reftype
3503
3504Returns a string describing what the SV is a reference to.
3505
3506 char* sv_reftype(SV* sv, int ob)
3507
3508=for hackers
3509Found in file sv.c
3510
3511=item sv_replace
3512
3513Make the first argument a copy of the second, then delete the original.
645c22ef
DM
3514The target SV physically takes over ownership of the body of the source SV
3515and inherits its flags; however, the target keeps any magic it owns,
3516and any magic in the source is discarded.
ff276b08 3517Note that this is a rather specialist SV copying operation; most of the
645c22ef 3518time you'll want to use C<sv_setsv> or one of its many macro front-ends.
c461cf8f
JH
3519
3520 void sv_replace(SV* sv, SV* nsv)
3521
3522=for hackers
3523Found in file sv.c
3524
645c22ef
DM
3525=item sv_report_used
3526
3527Dump the contents of all SVs not yet freed. (Debugging aid).
3528
3529 void sv_report_used()
3530
3531=for hackers
3532Found in file sv.c
3533
451be7b1
DM
3534=item sv_reset
3535
3536Underlying implementation for the C<reset> Perl function.
3537Note that the perl-level function is vaguely deprecated.
3538
3539 void sv_reset(char* s, HV* stash)
3540
3541=for hackers
3542Found in file sv.c
3543
c461cf8f
JH
3544=item sv_rvweaken
3545
645c22ef
DM
3546Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
3547referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
3548push a back-reference to this RV onto the array of backreferences
3549associated with that magic.
c461cf8f
JH
3550
3551 SV* sv_rvweaken(SV *sv)
3552
3553=for hackers
3554Found in file sv.c
3555
954c1994
GS
3556=item sv_setiv
3557
645c22ef
DM
3558Copies an integer into the given SV, upgrading first if necessary.
3559Does not handle 'set' magic. See also C<sv_setiv_mg>.
954c1994
GS
3560
3561 void sv_setiv(SV* sv, IV num)
3562
497711e7
GS
3563=for hackers
3564Found in file sv.c
3565
954c1994
GS
3566=item sv_setiv_mg
3567
3568Like C<sv_setiv>, but also handles 'set' magic.
3569
3570 void sv_setiv_mg(SV *sv, IV i)
3571
497711e7
GS
3572=for hackers
3573Found in file sv.c
3574
954c1994
GS
3575=item sv_setnv
3576
645c22ef
DM
3577Copies a double into the given SV, upgrading first if necessary.
3578Does not handle 'set' magic. See also C<sv_setnv_mg>.
954c1994
GS
3579
3580 void sv_setnv(SV* sv, NV num)
3581
497711e7
GS
3582=for hackers
3583Found in file sv.c
3584
954c1994
GS
3585=item sv_setnv_mg
3586
3587Like C<sv_setnv>, but also handles 'set' magic.
3588
3589 void sv_setnv_mg(SV *sv, NV num)
3590
497711e7
GS
3591=for hackers
3592Found in file sv.c
3593
954c1994
GS
3594=item sv_setpv
3595
3596Copies a string into an SV. The string must be null-terminated. Does not
3597handle 'set' magic. See C<sv_setpv_mg>.
3598
3599 void sv_setpv(SV* sv, const char* ptr)
3600
497711e7
GS
3601=for hackers
3602Found in file sv.c
3603
954c1994
GS
3604=item sv_setpvf
3605
3606Processes its arguments like C<sprintf> and sets an SV to the formatted
3607output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
3608
3609 void sv_setpvf(SV* sv, const char* pat, ...)
3610
497711e7
GS
3611=for hackers
3612Found in file sv.c
3613
954c1994
GS
3614=item sv_setpvf_mg
3615
3616Like C<sv_setpvf>, but also handles 'set' magic.
3617
3618 void sv_setpvf_mg(SV *sv, const char* pat, ...)
3619
497711e7
GS
3620=for hackers
3621Found in file sv.c
3622
954c1994
GS
3623=item sv_setpviv
3624
3625Copies an integer into the given SV, also updating its string value.
3626Does not handle 'set' magic. See C<sv_setpviv_mg>.
3627
3628 void sv_setpviv(SV* sv, IV num)
3629
497711e7
GS
3630=for hackers
3631Found in file sv.c
3632
954c1994
GS
3633=item sv_setpviv_mg
3634
3635Like C<sv_setpviv>, but also handles 'set' magic.
3636
3637 void sv_setpviv_mg(SV *sv, IV iv)
3638
497711e7
GS
3639=for hackers
3640Found in file sv.c
3641
954c1994
GS
3642=item sv_setpvn
3643
3644Copies a string into an SV. The C<len> parameter indicates the number of
3645bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
3646
3647 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
3648
497711e7
GS
3649=for hackers
3650Found in file sv.c
3651
954c1994
GS
3652=item sv_setpvn_mg
3653
3654Like C<sv_setpvn>, but also handles 'set' magic.
3655
3656 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
3657
497711e7
GS
3658=for hackers
3659Found in file sv.c
3660
954c1994
GS
3661=item sv_setpv_mg
3662
3663Like C<sv_setpv>, but also handles 'set' magic.
3664
3665 void sv_setpv_mg(SV *sv, const char *ptr)
3666
497711e7
GS
3667=for hackers
3668Found in file sv.c
3669
954c1994
GS
3670=item sv_setref_iv
3671
3672Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3673argument will be upgraded to an RV. That RV will be modified to point to
3674the new SV. The C<classname> argument indicates the package for the
3675blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3676will be returned and will have a reference count of 1.
3677
3678 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
3679
497711e7
GS
3680=for hackers
3681Found in file sv.c
3682
954c1994
GS
3683=item sv_setref_nv
3684
3685Copies a double into a new SV, optionally blessing the SV. The C<rv>
3686argument will be upgraded to an RV. That RV will be modified to point to
3687the new SV. The C<classname> argument indicates the package for the
3688blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3689will be returned and will have a reference count of 1.
3690
3691 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
3692
497711e7
GS
3693=for hackers
3694Found in file sv.c
3695
954c1994
GS
3696=item sv_setref_pv
3697
3698Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3699argument will be upgraded to an RV. That RV will be modified to point to
3700the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
3701into the SV. The C<classname> argument indicates the package for the
3702blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3703will be returned and will have a reference count of 1.
3704
3705Do not use with other Perl types such as HV, AV, SV, CV, because those
3706objects will become corrupted by the pointer copy process.
3707
3708Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3709
3710 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
3711
497711e7
GS
3712=for hackers
3713Found in file sv.c
3714
954c1994
GS
3715=item sv_setref_pvn
3716
3717Copies a string into a new SV, optionally blessing the SV. The length of the
3718string must be specified with C<n>. The C<rv> argument will be upgraded to
3719an RV. That RV will be modified to point to the new SV. The C<classname>
3720argument indicates the package for the blessing. Set C<classname> to
3721C<Nullch> to avoid the blessing. The new SV will be returned and will have
3722a reference count of 1.
3723
3724Note that C<sv_setref_pv> copies the pointer while this copies the string.
3725
3726 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
3727
497711e7
GS
3728=for hackers
3729Found in file sv.c
3730
e1c57cef
JH
3731=item sv_setref_uv
3732
3733Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
3734argument will be upgraded to an RV. That RV will be modified to point to
3735the new SV. The C<classname> argument indicates the package for the
3736blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3737will be returned and will have a reference count of 1.
3738
3739 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
3740
3741=for hackers
3742Found in file sv.c
3743
954c1994
GS
3744=item sv_setsv
3745
645c22ef
DM
3746Copies the contents of the source SV C<ssv> into the destination SV
3747C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
3748function if the source SV needs to be reused. Does not handle 'set' magic.
3749Loosely speaking, it performs a copy-by-value, obliterating any previous
3750content of the destination.
3751
3752You probably want to use one of the assortment of wrappers, such as
3753C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
3754C<SvSetMagicSV_nosteal>.
3755
954c1994
GS
3756
3757 void sv_setsv(SV* dsv, SV* ssv)
3758
497711e7
GS
3759=for hackers
3760Found in file sv.c
3761
8d6d96c1
HS
3762=item sv_setsv_flags
3763
645c22ef
DM
3764Copies the contents of the source SV C<ssv> into the destination SV
3765C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
3766function if the source SV needs to be reused. Does not handle 'set' magic.
3767Loosely speaking, it performs a copy-by-value, obliterating any previous
3768content of the destination.
3769If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
3770C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
3771implemented in terms of this function.
3772
3773You probably want to use one of the assortment of wrappers, such as
3774C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
3775C<SvSetMagicSV_nosteal>.
3776
3777This is the primary function for copying scalars, and most other
3778copy-ish functions and macros use this underneath.
8d6d96c1
HS
3779
3780 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
3781
3782=for hackers
3783Found in file sv.c
3784
954c1994
GS
3785=item sv_setsv_mg
3786
3787Like C<sv_setsv>, but also handles 'set' magic.
3788
3789 void sv_setsv_mg(SV *dstr, SV *sstr)
3790
497711e7
GS
3791=for hackers
3792Found in file sv.c
3793
954c1994
GS
3794=item sv_setuv
3795
645c22ef
DM
3796Copies an unsigned integer into the given SV, upgrading first if necessary.
3797Does not handle 'set' magic. See also C<sv_setuv_mg>.
954c1994
GS
3798
3799 void sv_setuv(SV* sv, UV num)
3800
497711e7
GS
3801=for hackers
3802Found in file sv.c
3803
954c1994
GS
3804=item sv_setuv_mg
3805
3806Like C<sv_setuv>, but also handles 'set' magic.
3807
3808 void sv_setuv_mg(SV *sv, UV u)
3809
497711e7
GS
3810=for hackers
3811Found in file sv.c
3812
645c22ef
DM
3813=item sv_taint
3814
3815Taint an SV. Use C<SvTAINTED_on> instead.
3816 void sv_taint(SV* sv)
3817
3818=for hackers
3819Found in file sv.c
3820
451be7b1
DM
3821=item sv_tainted
3822
3823Test an SV for taintedness. Use C<SvTAINTED> instead.
3824 bool sv_tainted(SV* sv)
3825
3826=for hackers
3827Found in file sv.c
3828
c461cf8f
JH
3829=item sv_true
3830
3831Returns true if the SV has a true value by Perl's rules.
645c22ef
DM
3832Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
3833instead use an in-line version.
c461cf8f
JH
3834
3835 I32 sv_true(SV *sv)
3836
3837=for hackers
3838Found in file sv.c
3839
3840=item sv_unmagic
3841
645c22ef 3842Removes all magic of type C<type> from an SV.
c461cf8f
JH
3843
3844 int sv_unmagic(SV* sv, int type)
3845
3846=for hackers
3847Found in file sv.c
3848
954c1994
GS
3849=item sv_unref
3850
3851Unsets the RV status of the SV, and decrements the reference count of
3852whatever was being referenced by the RV. This can almost be thought of
b06226ff 3853as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
ae154d6d 3854being zero. See C<SvROK_off>.
954c1994
GS
3855
3856 void sv_unref(SV* sv)
3857
497711e7
GS
3858=for hackers
3859Found in file sv.c
3860
840a7b70
IZ
3861=item sv_unref_flags
3862
3863Unsets the RV status of the SV, and decrements the reference count of
3864whatever was being referenced by the RV. This can almost be thought of
3865as a reversal of C<newSVrv>. The C<cflags> argument can contain
3866C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
3867(otherwise the decrementing is conditional on the reference count being
3868different from one or the reference being a readonly SV).
ae154d6d 3869See C<SvROK_off>.
840a7b70
IZ
3870
3871 void sv_unref_flags(SV* sv, U32 flags)
3872
3873=for hackers
3874Found in file sv.c
3875
451be7b1
DM
3876=item sv_untaint
3877
3878Untaint an SV. Use C<SvTAINTED_off> instead.
3879 void sv_untaint(SV* sv)
3880
3881=for hackers
3882Found in file sv.c
3883
954c1994
GS
3884=item sv_upgrade
3885
ff276b08 3886Upgrade an SV to a more complex form. Generally adds a new body type to the
645c22ef 3887SV, then copies across as much information as possible from the old body.
ff276b08 3888You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
954c1994
GS
3889
3890 bool sv_upgrade(SV* sv, U32 mt)
3891
497711e7
GS
3892=for hackers
3893Found in file sv.c
3894
954c1994
GS
3895=item sv_usepvn
3896
3897Tells an SV to use C<ptr> to find its string value. Normally the string is
1c846c1f 3898stored inside the SV but sv_usepvn allows the SV to use an outside string.
954c1994
GS
3899The C<ptr> should point to memory that was allocated by C<malloc>. The
3900string length, C<len>, must be supplied. This function will realloc the
3901memory pointed to by C<ptr>, so that pointer should not be freed or used by
3902the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
3903See C<sv_usepvn_mg>.
3904
3905 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
3906
497711e7
GS
3907=for hackers
3908Found in file sv.c
3909
954c1994
GS
3910=item sv_usepvn_mg
3911
3912Like C<sv_usepvn>, but also handles 'set' magic.
3913
3914 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3915
497711e7
GS
3916=for hackers
3917Found in file sv.c
3918
2457d041
JH
3919=item sv_utf8_decode
3920
3921Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
645c22ef 3922turn off SvUTF8 if needed so that we see characters. Used as a building block
2457d041
JH
3923for decode_utf8 in Encode.xs
3924
3925NOTE: this function is experimental and may change or be
3926removed without notice.
3927
3928 bool sv_utf8_decode(SV *sv)
3929
3930=for hackers
3931Found in file sv.c
3932
c461cf8f
JH
3933=item sv_utf8_downgrade
3934
3935Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3936This may not be possible if the PV contains non-byte encoding characters;
3937if this is the case, either returns false or, if C<fail_ok> is not
3938true, croaks.
3939
3940