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