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