This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
-x (was Re: [PATCH] new tests for command-line switches)
[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,
797specifies the structure contains a C<SV*> pointer where a C<char*> pointer
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
1c846c1f 961dereferencing it to a 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
954c1994
GS
1407=item NEWSV
1408
1409Creates a new SV. A non-zero C<len> parameter indicates the number of
1410bytes of preallocated string space the SV should have. An extra byte for a
1411tailing NUL is also reserved. (SvPOK is not set for the SV even if string
444155da 1412space is allocated.) The reference count for the new SV is set to 1.
954c1994
GS
1413C<id> is an integer id between 0 and 1299 (used to identify leaks).
1414
1415 SV* NEWSV(int id, STRLEN len)
1416
497711e7
GS
1417=for hackers
1418Found in file handy.h
1419
9f4817db
JH
1420=item newSV
1421
1422Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
1423with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
1424macro.
1425
1426 SV* newSV(STRLEN len)
1427
1428=for hackers
1429Found in file sv.c
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
954c1994
GS
1556=item Nullav
1557
1558Null AV pointer.
1559
497711e7
GS
1560=for hackers
1561Found in file av.h
1562
954c1994
GS
1563=item Nullch
1564
1565Null character pointer.
1566
497711e7
GS
1567=for hackers
1568Found in file handy.h
1569
954c1994
GS
1570=item Nullcv
1571
1572Null CV pointer.
1573
497711e7
GS
1574=for hackers
1575Found in file cv.h
1576
954c1994
GS
1577=item Nullhv
1578
1579Null HV pointer.
1580
497711e7
GS
1581=for hackers
1582Found in file hv.h
1583
954c1994
GS
1584=item Nullsv
1585
1586Null SV pointer.
1587
497711e7
GS
1588=for hackers
1589Found in file handy.h
1590
954c1994
GS
1591=item ORIGMARK
1592
1593The original stack mark for the XSUB. See C<dORIGMARK>.
1594
497711e7
GS
1595=for hackers
1596Found in file pp.h
1597
954c1994
GS
1598=item perl_alloc
1599
1600Allocates a new Perl interpreter. See L<perlembed>.
1601
1602 PerlInterpreter* perl_alloc()
1603
497711e7
GS
1604=for hackers
1605Found in file perl.c
1606
645c22ef
DM
1607=item perl_clone
1608
1609Create and return a new interpreter by cloning the current one.
1610
1611 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
1612
1613=for hackers
1614Found in file sv.c
1615
954c1994
GS
1616=item perl_construct
1617
1618Initializes a new Perl interpreter. See L<perlembed>.
1619
1620 void perl_construct(PerlInterpreter* interp)
1621
497711e7
GS
1622=for hackers
1623Found in file perl.c
1624
954c1994
GS
1625=item perl_destruct
1626
1627Shuts down a Perl interpreter. See L<perlembed>.
1628
d9f424b2 1629 int perl_destruct(PerlInterpreter* interp)
954c1994 1630
497711e7
GS
1631=for hackers
1632Found in file perl.c
1633
954c1994
GS
1634=item perl_free
1635
1636Releases a Perl interpreter. See L<perlembed>.
1637
1638 void perl_free(PerlInterpreter* interp)
1639
497711e7
GS
1640=for hackers
1641Found in file perl.c
1642
954c1994
GS
1643=item perl_parse
1644
1645Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1646
1647 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1648
497711e7
GS
1649=for hackers
1650Found in file perl.c
1651
954c1994
GS
1652=item perl_run
1653
1654Tells a Perl interpreter to run. See L<perlembed>.
1655
1656 int perl_run(PerlInterpreter* interp)
1657
497711e7
GS
1658=for hackers
1659Found in file perl.c
1660
954c1994
GS
1661=item PL_modglobal
1662
ae154d6d 1663C<PL_modglobal> is a general purpose, interpreter global HV for use by
954c1994 1664extensions that need to keep information on a per-interpreter basis.
ae154d6d
JH
1665In a pinch, it can also be used as a symbol table for extensions
1666to share data among each other. It is a good idea to use keys
954c1994
GS
1667prefixed by the package name of the extension that owns the data.
1668
1669 HV* PL_modglobal
1670
497711e7
GS
1671=for hackers
1672Found in file intrpvar.h
1673
954c1994
GS
1674=item PL_na
1675
1676A convenience variable which is typically used with C<SvPV> when one
1677doesn't care about the length of the string. It is usually more efficient
1678to either declare a local variable and use that instead or to use the
1679C<SvPV_nolen> macro.
1680
1681 STRLEN PL_na
1682
497711e7
GS
1683=for hackers
1684Found in file thrdvar.h
1685
954c1994
GS
1686=item PL_sv_no
1687
1688This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1689C<&PL_sv_no>.
1690
1691 SV PL_sv_no
1692
497711e7
GS
1693=for hackers
1694Found in file intrpvar.h
1695
954c1994
GS
1696=item PL_sv_undef
1697
1698This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1699
1700 SV PL_sv_undef
1701
497711e7
GS
1702=for hackers
1703Found in file intrpvar.h
1704
954c1994
GS
1705=item PL_sv_yes
1706
1707This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1708C<&PL_sv_yes>.
1709
1710 SV PL_sv_yes
1711
497711e7
GS
1712=for hackers
1713Found in file intrpvar.h
1714
954c1994
GS
1715=item POPi
1716
1717Pops an integer off the stack.
1718
1719 IV POPi
1720
497711e7
GS
1721=for hackers
1722Found in file pp.h
1723
954c1994
GS
1724=item POPl
1725
1726Pops a long off the stack.
1727
1728 long POPl
1729
497711e7
GS
1730=for hackers
1731Found in file pp.h
1732
954c1994
GS
1733=item POPn
1734
1735Pops a double off the stack.
1736
1737 NV POPn
1738
497711e7
GS
1739=for hackers
1740Found in file pp.h
1741
954c1994
GS
1742=item POPp
1743
fa519979
JH
1744Pops a string off the stack. Deprecated. New code should provide
1745a STRLEN n_a and use POPpx.
954c1994
GS
1746
1747 char* POPp
1748
497711e7
GS
1749=for hackers
1750Found in file pp.h
1751
fa519979
JH
1752=item POPpbytex
1753
1754Pops a string off the stack which must consist of bytes i.e. characters < 256.
1755Requires a variable STRLEN n_a in scope.
1756
1757 char* POPpbytex
1758
1759=for hackers
1760Found in file pp.h
1761
1762=item POPpx
1763
1764Pops a string off the stack.
1765Requires a variable STRLEN n_a in scope.
1766
1767 char* POPpx
1768
1769=for hackers
1770Found in file pp.h
1771
954c1994
GS
1772=item POPs
1773
1774Pops an SV off the stack.
1775
1776 SV* POPs
1777
497711e7
GS
1778=for hackers
1779Found in file pp.h
1780
954c1994
GS
1781=item PUSHi
1782
1783Push an integer onto the stack. The stack must have room for this element.
1784Handles 'set' magic. See C<XPUSHi>.
1785
1786 void PUSHi(IV iv)
1787
497711e7
GS
1788=for hackers
1789Found in file pp.h
1790
954c1994
GS
1791=item PUSHMARK
1792
1793Opening bracket for arguments on a callback. See C<PUTBACK> and
1794L<perlcall>.
1795
1796 PUSHMARK;
1797
497711e7
GS
1798=for hackers
1799Found in file pp.h
1800
954c1994
GS
1801=item PUSHn
1802
1803Push a double onto the stack. The stack must have room for this element.
1804Handles 'set' magic. See C<XPUSHn>.
1805
1806 void PUSHn(NV nv)
1807
497711e7
GS
1808=for hackers
1809Found in file pp.h
1810
954c1994
GS
1811=item PUSHp
1812
1813Push a string onto the stack. The stack must have room for this element.
1814The C<len> indicates the length of the string. Handles 'set' magic. See
1815C<XPUSHp>.
1816
1817 void PUSHp(char* str, STRLEN len)
1818
497711e7
GS
1819=for hackers
1820Found in file pp.h
1821
954c1994
GS
1822=item PUSHs
1823
1c846c1f 1824Push an SV onto the stack. The stack must have room for this element.
954c1994
GS
1825Does not handle 'set' magic. See C<XPUSHs>.
1826
1827 void PUSHs(SV* sv)
1828
497711e7
GS
1829=for hackers
1830Found in file pp.h
1831
954c1994
GS
1832=item PUSHu
1833
1834Push an unsigned integer onto the stack. The stack must have room for this
1835element. See C<XPUSHu>.
1836
1837 void PUSHu(UV uv)
1838
497711e7
GS
1839=for hackers
1840Found in file pp.h
1841
954c1994
GS
1842=item PUTBACK
1843
1844Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1845See C<PUSHMARK> and L<perlcall> for other uses.
1846
1847 PUTBACK;
1848
497711e7
GS
1849=for hackers
1850Found in file pp.h
1851
954c1994
GS
1852=item Renew
1853
1854The XSUB-writer's interface to the C C<realloc> function.
1855
1856 void Renew(void* ptr, int nitems, type)
1857
497711e7
GS
1858=for hackers
1859Found in file handy.h
1860
954c1994
GS
1861=item Renewc
1862
1863The XSUB-writer's interface to the C C<realloc> function, with
1864cast.
1865
1866 void Renewc(void* ptr, int nitems, type, cast)
1867
497711e7
GS
1868=for hackers
1869Found in file handy.h
1870
954c1994
GS
1871=item require_pv
1872
7d3fb230
BS
1873Tells Perl to C<require> the file named by the string argument. It is
1874analogous to the Perl code C<eval "require '$file'">. It's even
1875implemented that way; consider using Perl_load_module instead.
954c1994
GS
1876
1877NOTE: the perl_ form of this function is deprecated.
1878
1879 void require_pv(const char* pv)
1880
497711e7
GS
1881=for hackers
1882Found in file perl.c
1883
954c1994
GS
1884=item RETVAL
1885
1886Variable which is setup by C<xsubpp> to hold the return value for an
1887XSUB. This is always the proper type for the XSUB. See
1888L<perlxs/"The RETVAL Variable">.
1889
1890 (whatever) RETVAL
1891
497711e7
GS
1892=for hackers
1893Found in file XSUB.h
1894
954c1994
GS
1895=item Safefree
1896
1897The XSUB-writer's interface to the C C<free> function.
1898
49b8b560 1899 void Safefree(void* ptr)
954c1994 1900
497711e7
GS
1901=for hackers
1902Found in file handy.h
1903
954c1994
GS
1904=item savepv
1905
1906Copy a string to a safe spot. This does not use an SV.
1907
1908 char* savepv(const char* sv)
1909
497711e7
GS
1910=for hackers
1911Found in file util.c
1912
954c1994
GS
1913=item savepvn
1914
1915Copy a string to a safe spot. The C<len> indicates number of bytes to
1916copy. This does not use an SV.
1917
1918 char* savepvn(const char* sv, I32 len)
1919
497711e7
GS
1920=for hackers
1921Found in file util.c
1922
954c1994
GS
1923=item SAVETMPS
1924
1925Opening bracket for temporaries on a callback. See C<FREETMPS> and
1926L<perlcall>.
1927
1928 SAVETMPS;
1929
497711e7
GS
1930=for hackers
1931Found in file scope.h
1932
6e9d1081
NC
1933=item scan_bin
1934
1935For backwards compatibility. Use C<grok_bin> instead.
1936
1937 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
1938
1939=for hackers
1940Found in file numeric.c
1941
1942=item scan_hex
1943
1944For backwards compatibility. Use C<grok_hex> instead.
1945
1946 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
1947
1948=for hackers
1949Found in file numeric.c
1950
1951=item scan_oct
1952
1953For backwards compatibility. Use C<grok_oct> instead.
1954
1955 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
1956
1957=for hackers
1958Found in file numeric.c
1959
cd1ee231
JH
1960=item sharedsv_find
1961
1962Tries to find if a given SV has a shared backend, either by
1963looking at magic, or by checking if it is tied again threads::shared.
1964
1965 shared_sv* sharedsv_find(SV* sv)
1966
1967=for hackers
1968Found in file sharedsv.c
1969
1970=item sharedsv_init
1971
1972Saves a space for keeping SVs wider than an interpreter,
1973currently only stores a pointer to the first interpreter.
1974
1975 void sharedsv_init()
1976
1977=for hackers
1978Found in file sharedsv.c
1979
1980=item sharedsv_lock
1981
1982Recursive locks on a sharedsv.
1983Locks are dynamicly scoped at the level of the first lock.
1984 void sharedsv_lock(shared_sv* ssv)
1985
1986=for hackers
1987Found in file sharedsv.c
1988
1989=item sharedsv_new
1990
1991Allocates a new shared sv struct, you must yourself create the SV/AV/HV.
1992 shared_sv* sharedsv_new()
1993
1994=for hackers
1995Found in file sharedsv.c
1996
1997=item sharedsv_thrcnt_dec
1998
1999Decrements the threadcount of a shared sv. When a threads frontend is freed
2000this function should be called.
2001
2002 void sharedsv_thrcnt_dec(shared_sv* ssv)
2003
2004=for hackers
2005Found in file sharedsv.c
2006
2007=item sharedsv_thrcnt_inc
2008
2009Increments the threadcount of a sharedsv.
2010 void sharedsv_thrcnt_inc(shared_sv* ssv)
2011
2012=for hackers
2013Found in file sharedsv.c
2014
2015=item sharedsv_unlock
2016
2017Recursively unlocks a shared sv.
2018
2019 void sharedsv_unlock(shared_sv* ssv)
2020
2021=for hackers
2022Found in file sharedsv.c
2023
8d344e3e
BI
2024=item sortsv
2025
2026
15c78202 2027Sort an array. Here is an example:
8d344e3e
BI
2028
2029 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
2030
2031 void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t f)
2032
2033=for hackers
2034Found in file pp_ctl.c
2035
954c1994
GS
2036=item SP
2037
2038Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2039C<SPAGAIN>.
2040
497711e7
GS
2041=for hackers
2042Found in file pp.h
2043
954c1994
GS
2044=item SPAGAIN
2045
2046Refetch the stack pointer. Used after a callback. See L<perlcall>.
2047
2048 SPAGAIN;
2049
497711e7
GS
2050=for hackers
2051Found in file pp.h
2052
954c1994
GS
2053=item ST
2054
2055Used to access elements on the XSUB's stack.
2056
2057 SV* ST(int ix)
2058
497711e7
GS
2059=for hackers
2060Found in file XSUB.h
2061
954c1994
GS
2062=item strEQ
2063
2064Test two strings to see if they are equal. Returns true or false.
2065
2066 bool strEQ(char* s1, char* s2)
2067
497711e7
GS
2068=for hackers
2069Found in file handy.h
2070
954c1994
GS
2071=item strGE
2072
2073Test two strings to see if the first, C<s1>, is greater than or equal to
2074the second, C<s2>. Returns true or false.
2075
2076 bool strGE(char* s1, char* s2)
2077
497711e7
GS
2078=for hackers
2079Found in file handy.h
2080
954c1994
GS
2081=item strGT
2082
2083Test two strings to see if the first, C<s1>, is greater than the second,
2084C<s2>. Returns true or false.
2085
2086 bool strGT(char* s1, char* s2)
2087
497711e7
GS
2088=for hackers
2089Found in file handy.h
2090
954c1994
GS
2091=item strLE
2092
2093Test two strings to see if the first, C<s1>, is less than or equal to the
2094second, C<s2>. Returns true or false.
2095
2096 bool strLE(char* s1, char* s2)
2097
497711e7
GS
2098=for hackers
2099Found in file handy.h
2100
954c1994
GS
2101=item strLT
2102
2103Test two strings to see if the first, C<s1>, is less than the second,
2104C<s2>. Returns true or false.
2105
2106 bool strLT(char* s1, char* s2)
2107
497711e7
GS
2108=for hackers
2109Found in file handy.h
2110
954c1994
GS
2111=item strNE
2112
2113Test two strings to see if they are different. Returns true or
2114false.
2115
2116 bool strNE(char* s1, char* s2)
2117
497711e7
GS
2118=for hackers
2119Found in file handy.h
2120
954c1994
GS
2121=item strnEQ
2122
2123Test two strings to see if they are equal. The C<len> parameter indicates
2124the number of bytes to compare. Returns true or false. (A wrapper for
2125C<strncmp>).
2126
2127 bool strnEQ(char* s1, char* s2, STRLEN len)
2128
497711e7
GS
2129=for hackers
2130Found in file handy.h
2131
954c1994
GS
2132=item strnNE
2133
2134Test two strings to see if they are different. The C<len> parameter
2135indicates the number of bytes to compare. Returns true or false. (A
2136wrapper for C<strncmp>).
2137
2138 bool strnNE(char* s1, char* s2, STRLEN len)
2139
497711e7
GS
2140=for hackers
2141Found in file handy.h
2142
954c1994
GS
2143=item StructCopy
2144
4375e838 2145This is an architecture-independent macro to copy one structure to another.
954c1994
GS
2146
2147 void StructCopy(type src, type dest, type)
2148
497711e7
GS
2149=for hackers
2150Found in file handy.h
2151
954c1994
GS
2152=item SvCUR
2153
2154Returns the length of the string which is in the SV. See C<SvLEN>.
2155
2156 STRLEN SvCUR(SV* sv)
2157
497711e7
GS
2158=for hackers
2159Found in file sv.h
2160
954c1994
GS
2161=item SvCUR_set
2162
2163Set the length of the string which is in the SV. See C<SvCUR>.
2164
2165 void SvCUR_set(SV* sv, STRLEN len)
2166
497711e7
GS
2167=for hackers
2168Found in file sv.h
2169
954c1994
GS
2170=item SvEND
2171
2172Returns a pointer to the last character in the string which is in the SV.
2173See C<SvCUR>. Access the character as *(SvEND(sv)).
2174
2175 char* SvEND(SV* sv)
2176
497711e7
GS
2177=for hackers
2178Found in file sv.h
2179
954c1994
GS
2180=item SvGETMAGIC
2181
2182Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2183argument more than once.
2184
2185 void SvGETMAGIC(SV* sv)
2186
497711e7
GS
2187=for hackers
2188Found in file sv.h
2189
954c1994
GS
2190=item SvGROW
2191
2192Expands the character buffer in the SV so that it has room for the
2193indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 2194NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
2195Returns a pointer to the character buffer.
2196
679ac26e 2197 char * SvGROW(SV* sv, STRLEN len)
954c1994 2198
497711e7
GS
2199=for hackers
2200Found in file sv.h
2201
954c1994
GS
2202=item SvIOK
2203
2204Returns a boolean indicating whether the SV contains an integer.
2205
2206 bool SvIOK(SV* sv)
2207
497711e7
GS
2208=for hackers
2209Found in file sv.h
2210
954c1994
GS
2211=item SvIOKp
2212
2213Returns a boolean indicating whether the SV contains an integer. Checks
2214the B<private> setting. Use C<SvIOK>.
2215
2216 bool SvIOKp(SV* sv)
2217
497711e7
GS
2218=for hackers
2219Found in file sv.h
2220
e331fc52
JH
2221=item SvIOK_notUV
2222
2223Returns a boolean indicating whether the SV contains an signed integer.
2224
2225 void SvIOK_notUV(SV* sv)
2226
2227=for hackers
2228Found in file sv.h
2229
954c1994
GS
2230=item SvIOK_off
2231
2232Unsets the IV status of an SV.
2233
2234 void SvIOK_off(SV* sv)
2235
497711e7
GS
2236=for hackers
2237Found in file sv.h
2238
954c1994
GS
2239=item SvIOK_on
2240
2241Tells an SV that it is an integer.
2242
2243 void SvIOK_on(SV* sv)
2244
497711e7
GS
2245=for hackers
2246Found in file sv.h
2247
954c1994
GS
2248=item SvIOK_only
2249
2250Tells an SV that it is an integer and disables all other OK bits.
2251
2252 void SvIOK_only(SV* sv)
2253
497711e7
GS
2254=for hackers
2255Found in file sv.h
2256
e331fc52
JH
2257=item SvIOK_only_UV
2258
2259Tells and SV that it is an unsigned integer and disables all other OK bits.
2260
2261 void SvIOK_only_UV(SV* sv)
2262
2263=for hackers
2264Found in file sv.h
2265
2266=item SvIOK_UV
2267
2268Returns a boolean indicating whether the SV contains an unsigned integer.
2269
2270 void SvIOK_UV(SV* sv)
2271
2272=for hackers
2273Found in file sv.h
2274
954c1994
GS
2275=item SvIV
2276
645c22ef
DM
2277Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2278version which guarantees to evaluate sv only once.
954c1994
GS
2279
2280 IV SvIV(SV* sv)
2281
497711e7
GS
2282=for hackers
2283Found in file sv.h
2284
9f4817db 2285=item SvIVx
954c1994 2286
9f4817db 2287Coerces the given SV to an integer and returns it. Guarantees to evaluate
d1be9408 2288sv only once. Use the more efficient C<SvIV> otherwise.
954c1994 2289
9f4817db 2290 IV SvIVx(SV* sv)
954c1994 2291
497711e7
GS
2292=for hackers
2293Found in file sv.h
2294
9f4817db 2295=item SvIVX
645c22ef 2296
9f4817db
JH
2297Returns the raw value in the SV's IV slot, without checks or conversions.
2298Only use when you are sure SvIOK is true. See also C<SvIV()>.
645c22ef 2299
9f4817db 2300 IV SvIVX(SV* sv)
645c22ef
DM
2301
2302=for hackers
2303Found in file sv.h
2304
954c1994
GS
2305=item SvLEN
2306
91e74348
JH
2307Returns the size of the string buffer in the SV, not including any part
2308attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
2309
2310 STRLEN SvLEN(SV* sv)
2311
497711e7
GS
2312=for hackers
2313Found in file sv.h
2314
954c1994
GS
2315=item SvNIOK
2316
2317Returns a boolean indicating whether the SV contains a number, integer or
2318double.
2319
2320 bool SvNIOK(SV* sv)
2321
497711e7
GS
2322=for hackers
2323Found in file sv.h
2324
954c1994
GS
2325=item SvNIOKp
2326
2327Returns a boolean indicating whether the SV contains a number, integer or
2328double. Checks the B<private> setting. Use C<SvNIOK>.
2329
2330 bool SvNIOKp(SV* sv)
2331
497711e7
GS
2332=for hackers
2333Found in file sv.h
2334
954c1994
GS
2335=item SvNIOK_off
2336
2337Unsets the NV/IV status of an SV.
2338
2339 void SvNIOK_off(SV* sv)
2340
497711e7
GS
2341=for hackers
2342Found in file sv.h
2343
954c1994
GS
2344=item SvNOK
2345
2346Returns a boolean indicating whether the SV contains a double.
2347
2348 bool SvNOK(SV* sv)
2349
497711e7
GS
2350=for hackers
2351Found in file sv.h
2352
954c1994
GS
2353=item SvNOKp
2354
2355Returns a boolean indicating whether the SV contains a double. Checks the
2356B<private> setting. Use C<SvNOK>.
2357
2358 bool SvNOKp(SV* sv)
2359
497711e7
GS
2360=for hackers
2361Found in file sv.h
2362
954c1994
GS
2363=item SvNOK_off
2364
2365Unsets the NV status of an SV.
2366
2367 void SvNOK_off(SV* sv)
2368
497711e7
GS
2369=for hackers
2370Found in file sv.h
2371
954c1994
GS
2372=item SvNOK_on
2373
2374Tells an SV that it is a double.
2375
2376 void SvNOK_on(SV* sv)
2377
497711e7
GS
2378=for hackers
2379Found in file sv.h
2380
954c1994
GS
2381=item SvNOK_only
2382
2383Tells an SV that it is a double and disables all other OK bits.
2384
2385 void SvNOK_only(SV* sv)
2386
497711e7
GS
2387=for hackers
2388Found in file sv.h
2389
954c1994
GS
2390=item SvNV
2391
645c22ef
DM
2392Coerce the given SV to a double and return it. See C<SvNVx> for a version
2393which guarantees to evaluate sv only once.
954c1994
GS
2394
2395 NV SvNV(SV* sv)
2396
497711e7
GS
2397=for hackers
2398Found in file sv.h
2399
a1ea730d 2400=item SvNVX
645c22ef 2401
a1ea730d
NIS
2402Returns the raw value in the SV's NV slot, without checks or conversions.
2403Only use when you are sure SvNOK is true. See also C<SvNV()>.
645c22ef 2404
a1ea730d 2405 NV SvNVX(SV* sv)
645c22ef
DM
2406
2407=for hackers
2408Found in file sv.h
2409
a1ea730d 2410=item SvNVx
954c1994 2411
a1ea730d 2412Coerces the given SV to a double and returns it. Guarantees to evaluate
d1be9408 2413sv only once. Use the more efficient C<SvNV> otherwise.
954c1994 2414
a1ea730d 2415 NV SvNVx(SV* sv)
954c1994 2416
497711e7
GS
2417=for hackers
2418Found in file sv.h
2419
954c1994
GS
2420=item SvOK
2421
2422Returns a boolean indicating whether the value is an SV.
2423
2424 bool SvOK(SV* sv)
2425
497711e7
GS
2426=for hackers
2427Found in file sv.h
2428
954c1994
GS
2429=item SvOOK
2430
2431Returns a boolean indicating whether the SvIVX is a valid offset value for
2432the SvPVX. This hack is used internally to speed up removal of characters
2433from the beginning of a SvPV. When SvOOK is true, then the start of the
2434allocated string buffer is really (SvPVX - SvIVX).
2435
2436 bool SvOOK(SV* sv)
2437
497711e7
GS
2438=for hackers
2439Found in file sv.h
2440
954c1994
GS
2441=item SvPOK
2442
2443Returns a boolean indicating whether the SV contains a character
2444string.
2445
2446 bool SvPOK(SV* sv)
2447
497711e7
GS
2448=for hackers
2449Found in file sv.h
2450
954c1994
GS
2451=item SvPOKp
2452
2453Returns a boolean indicating whether the SV contains a character string.
2454Checks the B<private> setting. Use C<SvPOK>.
2455
2456 bool SvPOKp(SV* sv)
2457
497711e7
GS
2458=for hackers
2459Found in file sv.h
2460
954c1994
GS
2461=item SvPOK_off
2462
2463Unsets the PV status of an SV.
2464
2465 void SvPOK_off(SV* sv)
2466
497711e7
GS
2467=for hackers
2468Found in file sv.h
2469
954c1994
GS
2470=item SvPOK_on
2471
2472Tells an SV that it is a string.
2473
2474 void SvPOK_on(SV* sv)
2475
497711e7
GS
2476=for hackers
2477Found in file sv.h
2478
954c1994
GS
2479=item SvPOK_only
2480
2481Tells an SV that it is a string and disables all other OK bits.
d5ce4a7c 2482Will also turn off the UTF8 status.
954c1994
GS
2483
2484 void SvPOK_only(SV* sv)
2485
497711e7
GS
2486=for hackers
2487Found in file sv.h
2488
914184e1
JH
2489=item SvPOK_only_UTF8
2490
d5ce4a7c
GA
2491Tells an SV that it is a string and disables all other OK bits,
2492and leaves the UTF8 status as it was.
f1a1024e 2493
914184e1
JH
2494 void SvPOK_only_UTF8(SV* sv)
2495
2496=for hackers
2497Found in file sv.h
2498
954c1994
GS
2499=item SvPV
2500
2501Returns a pointer to the string in the SV, or a stringified form of the SV
645c22ef
DM
2502if the SV does not contain a string. Handles 'get' magic. See also
2503C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
2504
2505 char* SvPV(SV* sv, STRLEN len)
2506
497711e7
GS
2507=for hackers
2508Found in file sv.h
2509
645c22ef
DM
2510=item SvPVbyte
2511
2512Like C<SvPV>, but converts sv to byte representation first if necessary.
2513
2514 char* SvPVbyte(SV* sv, STRLEN len)
2515
2516=for hackers
2517Found in file sv.h
2518
2519=item SvPVbytex
2520
2521Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 2522Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
2523otherwise.
2524
2525
2526 char* SvPVbytex(SV* sv, STRLEN len)
2527
2528=for hackers
2529Found in file sv.h
2530
2531=item SvPVbytex_force
2532
2533Like C<SvPV_force>, but converts sv to byte representation first if necessary.
d1be9408 2534Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
645c22ef
DM
2535otherwise.
2536
2537 char* SvPVbytex_force(SV* sv, STRLEN len)
2538
2539=for hackers
2540Found in file sv.h
2541
2542=item SvPVbyte_force
2543
2544Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2545
2546 char* SvPVbyte_force(SV* sv, STRLEN len)
2547
2548=for hackers
2549Found in file sv.h
2550
2551=item SvPVbyte_nolen
2552
2553Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2554
1fdc5aa6 2555 char* SvPVbyte_nolen(SV* sv)
645c22ef
DM
2556
2557=for hackers
2558Found in file sv.h
2559
2560=item SvPVutf8
2561
1fdc5aa6 2562Like C<SvPV>, but converts sv to utf8 first if necessary.
645c22ef
DM
2563
2564 char* SvPVutf8(SV* sv, STRLEN len)
2565
2566=for hackers
2567Found in file sv.h
2568
2569=item SvPVutf8x
2570
1fdc5aa6 2571Like C<SvPV>, but converts sv to utf8 first if necessary.
d1be9408 2572Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
645c22ef
DM
2573otherwise.
2574
2575 char* SvPVutf8x(SV* sv, STRLEN len)
2576
2577=for hackers
2578Found in file sv.h
2579
2580=item SvPVutf8x_force
2581
1fdc5aa6 2582Like C<SvPV_force>, but converts sv to utf8 first if necessary.
d1be9408 2583Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
645c22ef
DM
2584otherwise.
2585
2586 char* SvPVutf8x_force(SV* sv, STRLEN len)
2587
2588=for hackers
2589Found in file sv.h
2590
2591=item SvPVutf8_force
2592
1fdc5aa6 2593Like C<SvPV_force>, but converts sv to utf8 first if necessary.
645c22ef
DM
2594
2595 char* SvPVutf8_force(SV* sv, STRLEN len)
2596
2597=for hackers
2598Found in file sv.h
2599
2600=item SvPVutf8_nolen
2601
1fdc5aa6 2602Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
645c22ef 2603
1fdc5aa6 2604 char* SvPVutf8_nolen(SV* sv)
645c22ef
DM
2605
2606=for hackers
2607Found in file sv.h
2608
9f4817db 2609=item SvPVX
645c22ef 2610
9f4817db
JH
2611Returns a pointer to the physical string in the SV. The SV must contain a
2612string.
645c22ef 2613
9f4817db 2614 char* SvPVX(SV* sv)
645c22ef
DM
2615
2616=for hackers
2617Found in file sv.h
2618
9f4817db 2619=item SvPVx
954c1994 2620
9f4817db 2621A version of C<SvPV> which guarantees to evaluate sv only once.
954c1994 2622
9f4817db 2623 char* SvPVx(SV* sv, STRLEN len)
954c1994 2624
497711e7
GS
2625=for hackers
2626Found in file sv.h
2627
954c1994
GS
2628=item SvPV_force
2629
2630Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2631force if you are going to update the SvPVX directly.
2632
2633 char* SvPV_force(SV* sv, STRLEN len)
2634
497711e7
GS
2635=for hackers
2636Found in file sv.h
2637
645c22ef
DM
2638=item SvPV_force_nomg
2639
2640Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2641force if you are going to update the SvPVX directly. Doesn't process magic.
2642
2643 char* SvPV_force_nomg(SV* sv, STRLEN len)
2644
2645=for hackers
2646Found in file sv.h
2647
954c1994
GS
2648=item SvPV_nolen
2649
2650Returns a pointer to the string in the SV, or a stringified form of the SV
2651if the SV does not contain a string. Handles 'get' magic.
2652
2653 char* SvPV_nolen(SV* sv)
2654
497711e7
GS
2655=for hackers
2656Found in file sv.h
2657
954c1994
GS
2658=item SvREFCNT
2659
2660Returns the value of the object's reference count.
2661
2662 U32 SvREFCNT(SV* sv)
2663
497711e7
GS
2664=for hackers
2665Found in file sv.h
2666
954c1994
GS
2667=item SvREFCNT_dec
2668
2669Decrements the reference count of the given SV.
2670
2671 void SvREFCNT_dec(SV* sv)
2672
497711e7
GS
2673=for hackers
2674Found in file sv.h
2675
954c1994
GS
2676=item SvREFCNT_inc
2677
2678Increments the reference count of the given SV.
2679
2680 SV* SvREFCNT_inc(SV* sv)
2681
497711e7
GS
2682=for hackers
2683Found in file sv.h
2684
954c1994
GS
2685=item SvROK
2686
2687Tests if the SV is an RV.
2688
2689 bool SvROK(SV* sv)
2690
497711e7
GS
2691=for hackers
2692Found in file sv.h
2693
954c1994
GS
2694=item SvROK_off
2695
2696Unsets the RV status of an SV.
2697
2698 void SvROK_off(SV* sv)
2699
497711e7
GS
2700=for hackers
2701Found in file sv.h
2702
954c1994
GS
2703=item SvROK_on
2704
2705Tells an SV that it is an RV.
2706
2707 void SvROK_on(SV* sv)
2708
497711e7
GS
2709=for hackers
2710Found in file sv.h
2711
954c1994
GS
2712=item SvRV
2713
2714Dereferences an RV to return the SV.
2715
2716 SV* SvRV(SV* sv)
2717
497711e7
GS
2718=for hackers
2719Found in file sv.h
2720
954c1994
GS
2721=item SvSETMAGIC
2722
2723Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2724argument more than once.
2725
2726 void SvSETMAGIC(SV* sv)
2727
497711e7
GS
2728=for hackers
2729Found in file sv.h
2730
645c22ef
DM
2731=item SvSetMagicSV
2732
2733Like C<SvSetSV>, but does any set magic required afterwards.
2734
2735 void SvSetMagicSV(SV* dsb, SV* ssv)
2736
2737=for hackers
2738Found in file sv.h
2739
2740=item SvSetMagicSV_nosteal
2741
2742Like C<SvSetMagicSV>, but does any set magic required afterwards.
2743
2744 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2745
2746=for hackers
2747Found in file sv.h
2748
954c1994
GS
2749=item SvSetSV
2750
2751Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2752more than once.
2753
2754 void SvSetSV(SV* dsb, SV* ssv)
2755
497711e7
GS
2756=for hackers
2757Found in file sv.h
2758
954c1994
GS
2759=item SvSetSV_nosteal
2760
2761Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2762ssv. May evaluate arguments more than once.
2763
2764 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2765
497711e7
GS
2766=for hackers
2767Found in file sv.h
2768
954c1994
GS
2769=item SvSTASH
2770
2771Returns the stash of the SV.
2772
2773 HV* SvSTASH(SV* sv)
2774
497711e7
GS
2775=for hackers
2776Found in file sv.h
2777
954c1994
GS
2778=item SvTAINT
2779
2780Taints an SV if tainting is enabled
2781
2782 void SvTAINT(SV* sv)
2783
497711e7
GS
2784=for hackers
2785Found in file sv.h
2786
954c1994
GS
2787=item SvTAINTED
2788
2789Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2790not.
2791
2792 bool SvTAINTED(SV* sv)
2793
497711e7
GS
2794=for hackers
2795Found in file sv.h
2796
954c1994
GS
2797=item SvTAINTED_off
2798
2799Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2800some of Perl's fundamental security features. XS module authors should not
2801use this function unless they fully understand all the implications of
2802unconditionally untainting the value. Untainting should be done in the
2803standard perl fashion, via a carefully crafted regexp, rather than directly
2804untainting variables.
2805
2806 void SvTAINTED_off(SV* sv)
2807
497711e7
GS
2808=for hackers
2809Found in file sv.h
2810
954c1994
GS
2811=item SvTAINTED_on
2812
2813Marks an SV as tainted.
2814
2815 void SvTAINTED_on(SV* sv)
2816
497711e7
GS
2817=for hackers
2818Found in file sv.h
2819
954c1994
GS
2820=item SvTRUE
2821
2822Returns a boolean indicating whether Perl would evaluate the SV as true or
2823false, defined or undefined. Does not handle 'get' magic.
2824
2825 bool SvTRUE(SV* sv)
2826
497711e7
GS
2827=for hackers
2828Found in file sv.h
2829
9f4817db 2830=item svtype
e37d999d 2831
9f4817db
JH
2832An enum of flags for Perl types. These are found in the file B<sv.h>
2833in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
34f7a5fe 2834
497711e7
GS
2835=for hackers
2836Found in file sv.h
2837
9f4817db 2838=item SvTYPE
af3c7592 2839
9f4817db
JH
2840Returns the type of the SV. See C<svtype>.
2841
2842 svtype SvTYPE(SV* sv)
954c1994 2843
497711e7
GS
2844=for hackers
2845Found in file sv.h
2846
954c1994
GS
2847=item SVt_IV
2848
2849Integer type flag for scalars. See C<svtype>.
2850
497711e7
GS
2851=for hackers
2852Found in file sv.h
2853
954c1994
GS
2854=item SVt_NV
2855
2856Double type flag for scalars. See C<svtype>.
2857
497711e7
GS
2858=for hackers
2859Found in file sv.h
2860
954c1994
GS
2861=item SVt_PV
2862
2863Pointer type flag for scalars. See C<svtype>.
2864
497711e7
GS
2865=for hackers
2866Found in file sv.h
2867
954c1994
GS
2868=item SVt_PVAV
2869
2870Type flag for arrays. See C<svtype>.
2871
497711e7
GS
2872=for hackers
2873Found in file sv.h
2874
954c1994
GS
2875=item SVt_PVCV
2876
2877Type flag for code refs. See C<svtype>.
2878
497711e7
GS
2879=for hackers
2880Found in file sv.h
2881
954c1994
GS
2882=item SVt_PVHV
2883
2884Type flag for hashes. See C<svtype>.
2885
497711e7
GS
2886=for hackers
2887Found in file sv.h
2888
954c1994
GS
2889=item SVt_PVMG
2890
2891Type flag for blessed scalars. See C<svtype>.
2892
497711e7
GS
2893=for hackers
2894Found in file sv.h
2895
a8586c98
JH
2896=item SvUOK
2897
2898Returns a boolean indicating whether the SV contains an unsigned integer.
2899
2900 void SvUOK(SV* sv)
2901
2902=for hackers
2903Found in file sv.h
2904
954c1994
GS
2905=item SvUPGRADE
2906
2907Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
2908perform the upgrade if necessary. See C<svtype>.
2909
2910 void SvUPGRADE(SV* sv, svtype type)
2911
497711e7
GS
2912=for hackers
2913Found in file sv.h
2914
914184e1
JH
2915=item SvUTF8
2916
2917Returns a boolean indicating whether the SV contains UTF-8 encoded data.
2918
2919 void SvUTF8(SV* sv)
2920
2921=for hackers
2922Found in file sv.h
2923
2924=item SvUTF8_off
2925
2926Unsets the UTF8 status of an SV.
2927
2928 void SvUTF8_off(SV *sv)
2929
2930=for hackers
2931Found in file sv.h
2932
2933=item SvUTF8_on
2934
d5ce4a7c
GA
2935Turn on the UTF8 status of an SV (the data is not changed, just the flag).
2936Do not use frivolously.
914184e1
JH
2937
2938 void SvUTF8_on(SV *sv)
2939
2940=for hackers
2941Found in file sv.h
2942
954c1994
GS
2943=item SvUV
2944
645c22ef
DM
2945Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
2946for a version which guarantees to evaluate sv only once.
954c1994
GS
2947
2948 UV SvUV(SV* sv)
2949
497711e7
GS
2950=for hackers
2951Found in file sv.h
2952
9f4817db 2953=item SvUVx
954c1994 2954
9f4817db 2955Coerces the given SV to an unsigned integer and returns it. Guarantees to
d1be9408 2956evaluate sv only once. Use the more efficient C<SvUV> otherwise.
954c1994 2957
9f4817db 2958 UV SvUVx(SV* sv)
954c1994 2959
497711e7
GS
2960=for hackers
2961Found in file sv.h
2962
9f4817db 2963=item SvUVX
645c22ef 2964
9f4817db
JH
2965Returns the raw value in the SV's UV slot, without checks or conversions.
2966Only use when you are sure SvIOK is true. See also C<SvUV()>.
645c22ef 2967
9f4817db 2968 UV SvUVX(SV* sv)
645c22ef
DM
2969
2970=for hackers
2971Found in file sv.h
2972
2973=item sv_2bool
2974
2975This function is only called on magical items, and is only used by
8cf8f3d1 2976sv_true() or its macro equivalent.
645c22ef
DM
2977
2978 bool sv_2bool(SV* sv)
2979
2980=for hackers
2981Found in file sv.c
2982
2983=item sv_2cv
2984
2985Using various gambits, try to get a CV from an SV; in addition, try if
2986possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
2987
2988 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
2989
2990=for hackers
2991Found in file sv.c
2992
2993=item sv_2io
2994
2995Using various gambits, try to get an IO from an SV: the IO slot if its a
2996GV; or the recursive result if we're an RV; or the IO slot of the symbol
2997named after the PV if we're a string.
2998
2999 IO* sv_2io(SV* sv)
3000
3001=for hackers
3002Found in file sv.c
3003
3004=item sv_2iv
3005
3006Return the integer value of an SV, doing any necessary string conversion,
3007magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3008
3009 IV sv_2iv(SV* sv)
3010
3011=for hackers
3012Found in file sv.c
3013
954c1994
GS
3014=item sv_2mortal
3015
793edb8a
JH
3016Marks an existing SV as mortal. The SV will be destroyed "soon", either
3017by an explicit call to FREETMPS, or by an implicit call at places such as
3018statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
954c1994
GS
3019
3020 SV* sv_2mortal(SV* sv)
3021
497711e7
GS
3022=for hackers
3023Found in file sv.c
3024
645c22ef
DM
3025=item sv_2nv
3026
3027Return the num value of an SV, doing any necessary string or integer
3028conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3029macros.
3030
3031 NV sv_2nv(SV* sv)
3032
3033=for hackers
3034Found in file sv.c
3035
451be7b1
DM
3036=item sv_2pvbyte
3037
3038Return a pointer to the byte-encoded representation of the SV, and set *lp
3039to its length. May cause the SV to be downgraded from UTF8 as a
3040side-effect.
3041
3042Usually accessed via the C<SvPVbyte> macro.
3043
3044 char* sv_2pvbyte(SV* sv, STRLEN* lp)
3045
3046=for hackers
3047Found in file sv.c
3048
645c22ef
DM
3049=item sv_2pvbyte_nolen
3050
3051Return a pointer to the byte-encoded representation of the SV.
3052May cause the SV to be downgraded from UTF8 as a side-effect.
3053
3054Usually accessed via the C<SvPVbyte_nolen> macro.
3055
3056 char* sv_2pvbyte_nolen(SV* sv)
3057
3058=for hackers
3059Found in file sv.c
3060
451be7b1
DM
3061=item sv_2pvutf8
3062
3063Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3064to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
3065
3066Usually accessed via the C<SvPVutf8> macro.
3067
3068 char* sv_2pvutf8(SV* sv, STRLEN* lp)
3069
3070=for hackers
3071Found in file sv.c
3072
645c22ef
DM
3073=item sv_2pvutf8_nolen
3074
3075Return a pointer to the UTF8-encoded representation of the SV.
3076May cause the SV to be upgraded to UTF8 as a side-effect.
3077
3078Usually accessed via the C<SvPVutf8_nolen> macro.
3079
3080 char* sv_2pvutf8_nolen(SV* sv)
3081
3082=for hackers
3083Found in file sv.c
3084
3085=item sv_2pv_flags
3086
ff276b08 3087Returns a pointer to the string value of an SV, and sets *lp to its length.
645c22ef
DM
3088If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3089if necessary.
3090Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3091usually end up here too.
3092
3093 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3094
3095=for hackers
3096Found in file sv.c
3097
3098=item sv_2pv_nolen
3099
3100Like C<sv_2pv()>, but doesn't return the length too. You should usually
3101use the macro wrapper C<SvPV_nolen(sv)> instead.
3102 char* sv_2pv_nolen(SV* sv)
3103
3104=for hackers
3105Found in file sv.c
3106
3107=item sv_2uv
3108
3109Return the unsigned integer value of an SV, doing any necessary string
3110conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3111macros.
3112
3113 UV sv_2uv(SV* sv)
3114
3115=for hackers
3116Found in file sv.c
3117
3118=item sv_backoff
3119
3120Remove any string offset. You should normally use the C<SvOOK_off> macro
3121wrapper instead.
3122
3123 int sv_backoff(SV* sv)
3124
3125=for hackers
3126Found in file sv.c
3127
954c1994
GS
3128=item sv_bless
3129
3130Blesses an SV into a specified package. The SV must be an RV. The package
3131must be designated by its stash (see C<gv_stashpv()>). The reference count
3132of the SV is unaffected.
3133
3134 SV* sv_bless(SV* sv, HV* stash)
3135
497711e7
GS
3136=for hackers
3137Found in file sv.c
3138
954c1994
GS
3139=item sv_catpv
3140
3141Concatenates the string onto the end of the string which is in the SV.
d5ce4a7c
GA
3142If the SV has the UTF8 status set, then the bytes appended should be
3143valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
954c1994
GS
3144
3145 void sv_catpv(SV* sv, const char* ptr)
3146
497711e7
GS
3147=for hackers
3148Found in file sv.c
3149
954c1994
GS
3150=item sv_catpvf
3151
d5ce4a7c
GA
3152Processes its arguments like C<sprintf> and appends the formatted
3153output to an SV. If the appended data contains "wide" characters
3154(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3155and characters >255 formatted with %c), the original SV might get
3156upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
3157C<SvSETMAGIC()> must typically be called after calling this function
3158to handle 'set' magic.
954c1994
GS
3159
3160 void sv_catpvf(SV* sv, const char* pat, ...)
3161
497711e7
GS
3162=for hackers
3163Found in file sv.c
3164
954c1994
GS
3165=item sv_catpvf_mg
3166
3167Like C<sv_catpvf>, but also handles 'set' magic.
3168
3169 void sv_catpvf_mg(SV *sv, const char* pat, ...)
3170
497711e7
GS
3171=for hackers
3172Found in file sv.c
3173
954c1994
GS
3174=item sv_catpvn
3175
3176Concatenates the string onto the end of the string which is in the SV. The
d5ce4a7c
GA
3177C<len> indicates number of bytes to copy. If the SV has the UTF8
3178status set, then the bytes appended should be valid UTF8.
3179Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
954c1994
GS
3180
3181 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3182
497711e7
GS
3183=for hackers
3184Found in file sv.c
3185
8d6d96c1
HS
3186=item sv_catpvn_flags
3187
3188Concatenates the string onto the end of the string which is in the SV. The
3189C<len> indicates number of bytes to copy. If the SV has the UTF8
3190status set, then the bytes appended should be valid UTF8.
3191If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3192appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3193in terms of this function.
3194
3195 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3196
3197=for hackers
3198Found in file sv.c
3199
954c1994
GS
3200=item sv_catpvn_mg
3201
3202Like C<sv_catpvn>, but also handles 'set' magic.
3203
3204 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3205
497711e7
GS
3206=for hackers
3207Found in file sv.c
3208
954c1994
GS
3209=item sv_catpv_mg
3210
3211Like C<sv_catpv>, but also handles 'set' magic.
3212
3213 void sv_catpv_mg(SV *sv, const char *ptr)
3214
497711e7
GS
3215=for hackers
3216Found in file sv.c
3217
954c1994
GS
3218=item sv_catsv
3219
1aa99e6b
IH
3220Concatenates the string from SV C<ssv> onto the end of the string in
3221SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
3222not 'set' magic. See C<sv_catsv_mg>.
954c1994
GS
3223
3224 void sv_catsv(SV* dsv, SV* ssv)
3225
497711e7
GS
3226=for hackers
3227Found in file sv.c
3228
8d6d96c1
HS
3229=item sv_catsv_flags
3230
3231Concatenates the string from SV C<ssv> onto the end of the string in
3232SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
3233bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3234and C<sv_catsv_nomg> are implemented in terms of this function.
3235
3236 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3237
3238=for hackers
3239Found in file sv.c
3240
954c1994
GS
3241=item sv_catsv_mg
3242
3243Like C<sv_catsv>, but also handles 'set' magic.
3244
3245 void sv_catsv_mg(SV *dstr, SV *sstr)
3246
497711e7
GS
3247=for hackers
3248Found in file sv.c
3249
954c1994
GS
3250=item sv_chop
3251
1c846c1f 3252Efficient removal of characters from the beginning of the string buffer.
954c1994
GS
3253SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3254the string buffer. The C<ptr> becomes the first character of the adjusted
645c22ef 3255string. Uses the "OOK hack".
954c1994
GS
3256
3257 void sv_chop(SV* sv, char* ptr)
3258
497711e7
GS
3259=for hackers
3260Found in file sv.c
3261
c461cf8f
JH
3262=item sv_clear
3263
645c22ef
DM
3264Clear an SV: call any destructors, free up any memory used by the body,
3265and free the body itself. The SV's head is I<not> freed, although
3266its type is set to all 1's so that it won't inadvertently be assumed
3267to be live during global destruction etc.
3268This function should only be called when REFCNT is zero. Most of the time
3269you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3270instead.
c461cf8f
JH
3271
3272 void sv_clear(SV* sv)
3273
3274=for hackers
3275Found in file sv.c
3276
954c1994
GS
3277=item sv_cmp
3278
3279Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
3280string in C<sv1> is less than, equal to, or greater than the string in
645c22ef
DM
3281C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3282coerce its args to strings if necessary. See also C<sv_cmp_locale>.
954c1994
GS
3283
3284 I32 sv_cmp(SV* sv1, SV* sv2)
3285
497711e7
GS
3286=for hackers
3287Found in file sv.c
3288
c461cf8f
JH
3289=item sv_cmp_locale
3290
645c22ef
DM
3291Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3292'use bytes' aware, handles get magic, and will coerce its args to strings
3293if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
c461cf8f
JH
3294
3295 I32 sv_cmp_locale(SV* sv1, SV* sv2)
3296
3297=for hackers
3298Found in file sv.c
3299
645c22ef
DM
3300=item sv_collxfrm
3301
3302Add Collate Transform magic to an SV if it doesn't already have it.
3303
3304Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3305scalar data of the variable, but transformed to such a format that a normal
3306memory comparison can be used to compare the data according to the locale
3307settings.
3308
3309 char* sv_collxfrm(SV* sv, STRLEN* nxp)
3310
3311=for hackers
3312Found in file sv.c
3313
954c1994
GS
3314=item sv_dec
3315
645c22ef
DM
3316Auto-decrement of the value in the SV, doing string to numeric conversion
3317if necessary. Handles 'get' magic.
954c1994
GS
3318
3319 void sv_dec(SV* sv)
3320
497711e7
GS
3321=for hackers
3322Found in file sv.c
3323
954c1994
GS
3324=item sv_derived_from
3325
3326Returns a boolean indicating whether the SV is derived from the specified
3327class. This is the function that implements C<UNIVERSAL::isa>. It works
3328for class names as well as for objects.
3329
3330 bool sv_derived_from(SV* sv, const char* name)
3331
497711e7
GS
3332=for hackers
3333Found in file universal.c
3334
954c1994
GS
3335=item sv_eq
3336
3337Returns a boolean indicating whether the strings in the two SVs are
645c22ef
DM
3338identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3339coerce its args to strings if necessary.
954c1994
GS
3340
3341 I32 sv_eq(SV* sv1, SV* sv2)
3342
497711e7
GS
3343=for hackers
3344Found in file sv.c
3345
645c22ef
DM
3346=item sv_force_normal
3347
3348Undo various types of fakery on an SV: if the PV is a shared string, make
3349a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3350an xpvmg. See also C<sv_force_normal_flags>.
3351
3352 void sv_force_normal(SV *sv)
3353
3354=for hackers
3355Found in file sv.c
3356
3357=item sv_force_normal_flags
3358
3359Undo various types of fakery on an SV: if the PV is a shared string, make
3360a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3361an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
3362when unrefing. C<sv_force_normal> calls this function with flags set to 0.
3363
3364 void sv_force_normal_flags(SV *sv, U32 flags)
3365
3366=for hackers
3367Found in file sv.c
3368
c461cf8f
JH
3369=item sv_free
3370
645c22ef
DM
3371Decrement an SV's reference count, and if it drops to zero, call
3372C<sv_clear> to invoke destructors and free up any memory used by
3373the body; finally, deallocate the SV's head itself.
3374Normally called via a wrapper macro C<SvREFCNT_dec>.
c461cf8f
JH
3375
3376 void sv_free(SV* sv)
3377
3378=for hackers
3379Found in file sv.c
3380
3381=item sv_gets
3382
3383Get a line from the filehandle and store it into the SV, optionally
3384appending to the currently-stored string.
3385
3386 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
3387
3388=for hackers
3389Found in file sv.c
3390
954c1994
GS
3391=item sv_grow
3392
645c22ef
DM
3393Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
3394upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
3395Use the C<SvGROW> wrapper instead.
954c1994
GS
3396
3397 char* sv_grow(SV* sv, STRLEN newlen)
3398
497711e7
GS
3399=for hackers
3400Found in file sv.c
3401
954c1994
GS
3402=item sv_inc
3403
645c22ef
DM
3404Auto-increment of the value in the SV, doing string to numeric conversion
3405if necessary. Handles 'get' magic.
954c1994
GS
3406
3407 void sv_inc(SV* sv)
3408
497711e7
GS
3409=for hackers
3410Found in file sv.c
3411
954c1994
GS
3412=item sv_insert
3413
3414Inserts a string at the specified offset/length within the SV. Similar to
3415the Perl substr() function.
3416
3417 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3418
497711e7
GS
3419=for hackers
3420Found in file sv.c
3421
954c1994
GS
3422=item sv_isa
3423
3424Returns a boolean indicating whether the SV is blessed into the specified
3425class. This does not check for subtypes; use C<sv_derived_from> to verify
3426an inheritance relationship.
3427
3428 int sv_isa(SV* sv, const char* name)
3429
497711e7
GS
3430=for hackers
3431Found in file sv.c
3432
954c1994
GS
3433=item sv_isobject
3434
3435Returns a boolean indicating whether the SV is an RV pointing to a blessed
3436object. If the SV is not an RV, or if the object is not blessed, then this
3437will return false.
3438
3439 int sv_isobject(SV* sv)
3440
497711e7
GS
3441=for hackers
3442Found in file sv.c
3443
645c22ef
DM
3444=item sv_iv
3445
3446A private implementation of the C<SvIVx> macro for compilers which can't
3447cope with complex macro expressions. Always use the macro instead.
3448
3449 IV sv_iv(SV* sv)
3450
3451=for hackers
3452Found in file sv.c
3453
954c1994
GS
3454=item sv_len
3455
645c22ef
DM
3456Returns the length of the string in the SV. Handles magic and type
3457coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
954c1994
GS
3458
3459 STRLEN sv_len(SV* sv)
3460
497711e7
GS
3461=for hackers
3462Found in file sv.c
3463
c461cf8f
JH
3464=item sv_len_utf8
3465
3466Returns the number of characters in the string in an SV, counting wide
645c22ef 3467UTF8 bytes as a single character. Handles magic and type coercion.
c461cf8f
JH
3468
3469 STRLEN sv_len_utf8(SV* sv)
3470
3471=for hackers
3472Found in file sv.c
3473
954c1994
GS
3474=item sv_magic
3475
645c22ef
DM
3476Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3477then adds a new magic item of type C<how> to the head of the magic list.
3478
3479C<name> is assumed to contain an C<SV*> if C<(name && namelen == HEf_SVKEY)>
954c1994
GS
3480
3481 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3482
497711e7
GS
3483=for hackers
3484Found in file sv.c
3485
954c1994
GS
3486=item sv_mortalcopy
3487
645c22ef 3488Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
793edb8a
JH
3489The new SV is marked as mortal. It will be destroyed "soon", either by an
3490explicit call to FREETMPS, or by an implicit call at places such as
3491statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
954c1994
GS
3492
3493 SV* sv_mortalcopy(SV* oldsv)
3494
497711e7
GS
3495=for hackers
3496Found in file sv.c
3497
954c1994
GS
3498=item sv_newmortal
3499
645c22ef 3500Creates a new null SV which is mortal. The reference count of the SV is
793edb8a
JH
3501set to 1. It will be destroyed "soon", either by an explicit call to
3502FREETMPS, or by an implicit call at places such as statement boundaries.
3503See also C<sv_mortalcopy> and C<sv_2mortal>.
954c1994
GS
3504
3505 SV* sv_newmortal()
3506
497711e7
GS
3507=for hackers
3508Found in file sv.c
3509
645c22ef
DM
3510=item sv_newref
3511
3512Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3513instead.
3514
3515 SV* sv_newref(SV* sv)
3516
3517=for hackers
3518Found in file sv.c
3519
3520=item sv_nv
3521
3522A private implementation of the C<SvNVx> macro for compilers which can't
3523cope with complex macro expressions. Always use the macro instead.
3524
3525 NV sv_nv(SV* sv)
3526
3527=for hackers
3528Found in file sv.c
3529
3530=item sv_pos_b2u
3531
3532Converts the value pointed to by offsetp from a count of bytes from the
3533start of the string, to a count of the equivalent number of UTF8 chars.
3534Handles magic and type coercion.
3535
3536 void sv_pos_b2u(SV* sv, I32* offsetp)
3537
3538=for hackers
3539Found in file sv.c
3540
3541=item sv_pos_u2b
3542
3543Converts the value pointed to by offsetp from a count of UTF8 chars from
3544the start of the string, to a count of the equivalent number of bytes; if
3545lenp is non-zero, it does the same to lenp, but this time starting from
3546the offset, rather than from the start of the string. Handles magic and
3547type coercion.
3548
3549 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3550
3551=for hackers
3552Found in file sv.c
3553
451be7b1
DM
3554=item sv_pv
3555
3556A private implementation of the C<SvPV_nolen> macro for compilers which can't
3557cope with complex macro expressions. Always use the macro instead.
3558
3559 char* sv_pv(SV *sv)
3560
3561=for hackers
3562Found in file sv.c
3563
645c22ef
DM
3564=item sv_pvbyte
3565
3566A private implementation of the C<SvPVbyte_nolen> macro for compilers
3567which can't cope with complex macro expressions. Always use the macro
3568instead.
3569
3570 char* sv_pvbyte(SV *sv)
3571
3572=for hackers
3573Found in file sv.c
3574
3575=item sv_pvbyten
3576
3577A private implementation of the C<SvPVbyte> macro for compilers
3578which can't cope with complex macro expressions. Always use the macro
3579instead.
3580
3581 char* sv_pvbyten(SV *sv, STRLEN *len)
3582
3583=for hackers
3584Found in file sv.c
3585
3586=item sv_pvbyten_force
3587
3588A private implementation of the C<SvPVbytex_force> macro for compilers
3589which can't cope with complex macro expressions. Always use the macro
3590instead.
3591
3592 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
3593
3594=for hackers
3595Found in file sv.c
3596
451be7b1
DM
3597=item sv_pvn
3598
3599A private implementation of the C<SvPV> macro for compilers which can't
3600cope with complex macro expressions. Always use the macro instead.
3601
3602 char* sv_pvn(SV *sv, STRLEN *len)
3603
3604=for hackers
3605Found in file sv.c
3606
c461cf8f
JH
3607=item sv_pvn_force
3608
3609Get a sensible string out of the SV somehow.
645c22ef
DM
3610A private implementation of the C<SvPV_force> macro for compilers which
3611can't cope with complex macro expressions. Always use the macro instead.
c461cf8f
JH
3612
3613 char* sv_pvn_force(SV* sv, STRLEN* lp)
3614
3615=for hackers
3616Found in file sv.c
3617
8d6d96c1
HS
3618=item sv_pvn_force_flags
3619
3620Get a sensible string out of the SV somehow.
3621If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
3622appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
3623implemented in terms of this function.
645c22ef
DM
3624You normally want to use the various wrapper macros instead: see
3625C<SvPV_force> and C<SvPV_force_nomg>
8d6d96c1
HS
3626
3627 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3628
3629=for hackers
3630Found in file sv.c
3631
645c22ef
DM
3632=item sv_pvutf8
3633
3634A private implementation of the C<SvPVutf8_nolen> macro for compilers
3635which can't cope with complex macro expressions. Always use the macro
3636instead.
3637
3638 char* sv_pvutf8(SV *sv)
3639
3640=for hackers
3641Found in file sv.c
3642
3643=item sv_pvutf8n
3644
3645A private implementation of the C<SvPVutf8> macro for compilers
3646which can't cope with complex macro expressions. Always use the macro
3647instead.
3648
3649 char* sv_pvutf8n(SV *sv, STRLEN *len)
3650
3651=for hackers
3652Found in file sv.c
3653
c461cf8f
JH
3654=item sv_pvutf8n_force
3655
645c22ef
DM
3656A private implementation of the C<SvPVutf8_force> macro for compilers
3657which can't cope with complex macro expressions. Always use the macro
3658instead.
c461cf8f
JH
3659
3660 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
3661
3662=for hackers
3663Found in file sv.c
3664
9f4817db
JH
3665=item sv_recode_to_utf8
3666
5d170f3a
JH
3667The encoding is assumed to be an Encode object, on entry the PV
3668of the sv is assumed to be octets in that encoding, and the sv
3669will be converted into Unicode (and UTF-8).
9f4817db 3670
5d170f3a 3671If the sv already is UTF-8 (or if it is not POK), or if the encoding
1768d7eb
JH
3672is not a reference, nothing is done to the sv. If the encoding is not
3673an C<Encode::XS> Encoding object, bad things will happen.
3674(See F<lib/encoding.pm> and L<Encode>).
5d170f3a
JH
3675
3676The PV of the sv is returned.
3677
1768d7eb 3678 char* sv_recode_to_utf8(SV* sv, SV *encoding)
9f4817db
JH
3679
3680=for hackers
3681Found in file sv.c
3682
c461cf8f
JH
3683=item sv_reftype
3684
3685Returns a string describing what the SV is a reference to.
3686
3687 char* sv_reftype(SV* sv, int ob)
3688
3689=for hackers
3690Found in file sv.c
3691
3692=item sv_replace
3693
3694Make the first argument a copy of the second, then delete the original.
645c22ef
DM
3695The target SV physically takes over ownership of the body of the source SV
3696and inherits its flags; however, the target keeps any magic it owns,
3697and any magic in the source is discarded.
ff276b08 3698Note that this is a rather specialist SV copying operation; most of the
645c22ef 3699time you'll want to use C<sv_setsv> or one of its many macro front-ends.
c461cf8f
JH
3700
3701 void sv_replace(SV* sv, SV* nsv)
3702
3703=for hackers
3704Found in file sv.c
3705
645c22ef
DM
3706=item sv_report_used
3707
3708Dump the contents of all SVs not yet freed. (Debugging aid).
3709
3710 void sv_report_used()
3711
3712=for hackers
3713Found in file sv.c
3714
451be7b1
DM
3715=item sv_reset
3716
3717Underlying implementation for the C<reset> Perl function.
3718Note that the perl-level function is vaguely deprecated.
3719
3720 void sv_reset(char* s, HV* stash)
3721
3722=for hackers
3723Found in file sv.c
3724
c461cf8f
JH
3725=item sv_rvweaken
3726
645c22ef
DM
3727Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
3728referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
3729push a back-reference to this RV onto the array of backreferences
3730associated with that magic.
c461cf8f
JH
3731
3732 SV* sv_rvweaken(SV *sv)
3733
3734=for hackers
3735Found in file sv.c
3736
954c1994
GS
3737=item sv_setiv
3738
645c22ef
DM
3739Copies an integer into the given SV, upgrading first if necessary.
3740Does not handle 'set' magic. See also C<sv_setiv_mg>.
954c1994
GS
3741
3742 void sv_setiv(SV* sv, IV num)
3743
497711e7
GS
3744=for hackers
3745Found in file sv.c
3746
954c1994
GS
3747=item sv_setiv_mg
3748
3749Like C<sv_setiv>, but also handles 'set' magic.
3750
3751 void sv_setiv_mg(SV *sv, IV i)
3752
497711e7
GS
3753=for hackers
3754Found in file sv.c
3755
954c1994
GS
3756=item sv_setnv
3757
645c22ef
DM
3758Copies a double into the given SV, upgrading first if necessary.
3759Does not handle 'set' magic. See also C<sv_setnv_mg>.
954c1994
GS
3760
3761 void sv_setnv(SV* sv, NV num)
3762
497711e7
GS
3763=for hackers
3764Found in file sv.c
3765
954c1994
GS
3766=item sv_setnv_mg
3767
3768Like C<sv_setnv>, but also handles 'set' magic.
3769
3770 void sv_setnv_mg(SV *sv, NV num)
3771
497711e7
GS
3772=for hackers
3773Found in file sv.c
3774
954c1994
GS
3775=item sv_setpv
3776
3777Copies a string into an SV. The string must be null-terminated. Does not
3778handle 'set' magic. See C<sv_setpv_mg>.
3779
3780 void sv_setpv(SV* sv, const char* ptr)
3781
497711e7
GS
3782=for hackers
3783Found in file sv.c
3784
954c1994
GS
3785=item sv_setpvf
3786
3787Processes its arguments like C<sprintf> and sets an SV to the formatted
3788output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
3789
3790 void sv_setpvf(SV* sv, const char* pat, ...)
3791
497711e7
GS
3792=for hackers
3793Found in file sv.c
3794
954c1994
GS
3795=item sv_setpvf_mg
3796
3797Like C<sv_setpvf>, but also handles 'set' magic.
3798
3799 void sv_setpvf_mg(SV *sv, const char* pat, ...)
3800
497711e7
GS
3801=for hackers
3802Found in file sv.c
3803
954c1994
GS
3804=item sv_setpviv
3805
3806Copies an integer into the given SV, also updating its string value.
3807Does not handle 'set' magic. See C<sv_setpviv_mg>.
3808
3809 void sv_setpviv(SV* sv, IV num)
3810
497711e7
GS
3811=for hackers
3812Found in file sv.c
3813
954c1994
GS
3814=item sv_setpviv_mg
3815
3816Like C<sv_setpviv>, but also handles 'set' magic.
3817
3818 void sv_setpviv_mg(SV *sv, IV iv)
3819
497711e7
GS
3820=for hackers
3821Found in file sv.c
3822
954c1994
GS
3823=item sv_setpvn
3824
3825Copies a string into an SV. The C<len> parameter indicates the number of
3826bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
3827
3828 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
3829
497711e7
GS
3830=for hackers
3831Found in file sv.c
3832
954c1994
GS
3833=item sv_setpvn_mg
3834
3835Like C<sv_setpvn>, but also handles 'set' magic.
3836
3837 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
3838
497711e7
GS
3839=for hackers
3840Found in file sv.c
3841
954c1994
GS
3842=item sv_setpv_mg
3843
3844Like C<sv_setpv>, but also handles 'set' magic.
3845
3846 void sv_setpv_mg(SV *sv, const char *ptr)
3847
497711e7
GS
3848=for hackers
3849Found in file sv.c
3850
954c1994
GS
3851=item sv_setref_iv
3852
3853Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3854argument will be upgraded to an RV. That RV will be modified to point to
3855the new SV. The C<classname> argument indicates the package for the
3856blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3857will be returned and will have a reference count of 1.
3858
3859 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
3860
497711e7
GS
3861=for hackers
3862Found in file sv.c
3863
954c1994
GS
3864=item sv_setref_nv
3865
3866Copies a double into a new SV, optionally blessing the SV. The C<rv>
3867argument will be upgraded to an RV. That RV will be modified to point to
3868the new SV. The C<classname> argument indicates the package for the
3869blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3870will be returned and will have a reference count of 1.
3871
3872 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
3873
497711e7
GS
3874=for hackers
3875Found in file sv.c
3876
954c1994
GS
3877=item sv_setref_pv
3878
3879Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3880argument will be upgraded to an RV. That RV will be modified to point to
3881the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
3882into the SV. The C<classname> argument indicates the package for the
3883blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3884will be returned and will have a reference count of 1.
3885
3886Do not use with other Perl types such as HV, AV, SV, CV, because those
3887objects will become corrupted by the pointer copy process.
3888
3889Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3890
3891 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
3892
497711e7
GS
3893=for hackers
3894Found in file sv.c
3895
954c1994
GS
3896=item sv_setref_pvn
3897
3898Copies a string into a new SV, optionally blessing the SV. The length of the
3899string must be specified with C<n>. The C<rv> argument will be upgraded to
3900an RV. That RV will be modified to point to the new SV. The C<classname>
3901argument indicates the package for the blessing. Set C<classname> to
3902C<Nullch> to avoid the blessing. The new SV will be returned and will have
3903a reference count of 1.
3904
3905Note that C<sv_setref_pv> copies the pointer while this copies the string.
3906
3907 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
3908
497711e7
GS
3909=for hackers
3910Found in file sv.c
3911
e1c57cef
JH
3912=item sv_setref_uv
3913
3914Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
3915argument will be upgraded to an RV. That RV will be modified to point to
3916the new SV. The C<classname> argument indicates the package for the
3917blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3918will be returned and will have a reference count of 1.
3919
3920 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
3921
3922=for hackers
3923Found in file sv.c
3924
954c1994
GS
3925=item sv_setsv
3926
645c22ef
DM
3927Copies the contents of the source SV C<ssv> into the destination SV
3928C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
3929function if the source SV needs to be reused. Does not handle 'set' magic.
3930Loosely speaking, it performs a copy-by-value, obliterating any previous
3931content of the destination.
3932
3933You probably want to use one of the assortment of wrappers, such as
3934C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
3935C<SvSetMagicSV_nosteal>