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