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