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