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