This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
s/perl56delta/perldelta/g
[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
28=item av_clear
29
30Clears an array, making it empty. Does not free the memory used by the
31array itself.
32
33 void av_clear(AV* ar)
34
35=item av_extend
36
37Pre-extend an array. The C<key> is the index to which the array should be
38extended.
39
40 void av_extend(AV* ar, I32 key)
41
42=item av_fetch
43
44Returns the SV at the specified index in the array. The C<key> is the
45index. If C<lval> is set then the fetch will be part of a store. Check
46that the return value is non-null before dereferencing it to a C<SV*>.
47
96f1132b
GS
48See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
49more information on how to use this function on tied arrays.
954c1994
GS
50
51 SV** av_fetch(AV* ar, I32 key, I32 lval)
52
53=item av_len
54
55Returns the highest index in the array. Returns -1 if the array is
56empty.
57
58 I32 av_len(AV* ar)
59
60=item av_make
61
62Creates a new AV and populates it with a list of SVs. The SVs are copied
63into the array, so they may be freed after the call to av_make. The new AV
64will have a reference count of 1.
65
66 AV* av_make(I32 size, SV** svp)
67
68=item av_pop
69
70Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
71is empty.
72
73 SV* av_pop(AV* ar)
74
75=item av_push
76
77Pushes an SV onto the end of the array. The array will grow automatically
78to accommodate the addition.
79
80 void av_push(AV* ar, SV* val)
81
82=item av_shift
83
84Shifts an SV off the beginning of the array.
85
86 SV* av_shift(AV* ar)
87
88=item av_store
89
90Stores an SV in an array. The array index is specified as C<key>. The
91return value will be NULL if the operation failed or if the value did not
92need to be actually stored within the array (as in the case of tied
93arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
94that the caller is responsible for suitably incrementing the reference
95count of C<val> before the call, and decrementing it if the function
96returned NULL.
97
96f1132b 98See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
954c1994
GS
99more information on how to use this function on tied arrays.
100
101 SV** av_store(AV* ar, I32 key, SV* val)
102
103=item av_undef
104
105Undefines the array. Frees the memory used by the array itself.
106
107 void av_undef(AV* ar)
108
109=item av_unshift
110
111Unshift the given number of C<undef> values onto the beginning of the
112array. The array will grow automatically to accommodate the addition. You
113must then use C<av_store> to assign values to these new elements.
114
115 void av_unshift(AV* ar, I32 num)
116
117=item call_argv
118
119Performs a callback to the specified Perl sub. See L<perlcall>.
120
121NOTE: the perl_ form of this function is deprecated.
122
123 I32 call_argv(const char* sub_name, I32 flags, char** argv)
124
125=item call_method
126
127Performs a callback to the specified Perl method. The blessed object must
128be on the stack. See L<perlcall>.
129
130NOTE: the perl_ form of this function is deprecated.
131
132 I32 call_method(const char* methname, I32 flags)
133
134=item call_pv
135
136Performs a callback to the specified Perl sub. See L<perlcall>.
137
138NOTE: the perl_ form of this function is deprecated.
139
140 I32 call_pv(const char* sub_name, I32 flags)
141
142=item call_sv
143
144Performs a callback to the Perl sub whose name is in the SV. See
145L<perlcall>.
146
147NOTE: the perl_ form of this function is deprecated.
148
149 I32 call_sv(SV* sv, I32 flags)
150
151=item CLASS
152
153Variable which is setup by C<xsubpp> to indicate the
154class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
155
156 char* CLASS
157
158=item Copy
159
160The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
161source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
162the type. May fail on overlapping copies. See also C<Move>.
163
164 void Copy(void* src, void* dest, int nitems, type)
165
166=item croak
167
c9d5ac95
GS
168This is the XSUB-writer's interface to Perl's C<die> function.
169Normally use this function the same way you use the C C<printf>
170function. See C<warn>.
171
172If you want to throw an exception object, assign the object to
173C<$@> and then pass C<Nullch> to croak():
174
175 errsv = get_sv("@", TRUE);
176 sv_setsv(errsv, exception_object);
177 croak(Nullch);
954c1994
GS
178
179 void croak(const char* pat, ...)
180
181=item CvSTASH
182
183Returns the stash of the CV.
184
185 HV* CvSTASH(CV* cv)
186
187=item dMARK
188
189Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
190C<dORIGMARK>.
191
192 dMARK;
193
194=item dORIGMARK
195
196Saves the original stack mark for the XSUB. See C<ORIGMARK>.
197
198 dORIGMARK;
199
200=item dSP
201
202Declares a local copy of perl's stack pointer for the XSUB, available via
203the C<SP> macro. See C<SP>.
204
205 dSP;
206
207=item dXSARGS
208
209Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This
210is usually handled automatically by C<xsubpp>. Declares the C<items>
211variable to indicate the number of items on the stack.
212
213 dXSARGS;
214
215=item dXSI32
216
217Sets up the C<ix> variable for an XSUB which has aliases. This is usually
218handled automatically by C<xsubpp>.
219
220 dXSI32;
221
222=item ENTER
223
224Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
225
226 ENTER;
227
228=item eval_pv
229
230Tells Perl to C<eval> the given string and return an SV* result.
231
232NOTE: the perl_ form of this function is deprecated.
233
234 SV* eval_pv(const char* p, I32 croak_on_error)
235
236=item eval_sv
237
238Tells Perl to C<eval> the string in the SV.
239
240NOTE: the perl_ form of this function is deprecated.
241
242 I32 eval_sv(SV* sv, I32 flags)
243
244=item EXTEND
245
246Used to extend the argument stack for an XSUB's return values. Once
4375e838 247used, guarantees that there is room for at least C<nitems> to be pushed
954c1994
GS
248onto the stack.
249
250 void EXTEND(SP, int nitems)
251
252=item fbm_compile
253
254Analyses the string in order to make fast searches on it using fbm_instr()
255-- the Boyer-Moore algorithm.
256
257 void fbm_compile(SV* sv, U32 flags)
258
259=item fbm_instr
260
261Returns the location of the SV in the string delimited by C<str> and
262C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
263does not have to be fbm_compiled, but the search will not be as fast
264then.
265
266 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
267
268=item FREETMPS
269
270Closing bracket for temporaries on a callback. See C<SAVETMPS> and
271L<perlcall>.
272
273 FREETMPS;
274
275=item get_av
276
277Returns the AV of the specified Perl array. If C<create> is set and the
278Perl variable does not exist then it will be created. If C<create> is not
279set and the variable does not exist then NULL is returned.
280
281NOTE: the perl_ form of this function is deprecated.
282
283 AV* get_av(const char* name, I32 create)
284
285=item get_cv
286
287Returns the CV of the specified Perl subroutine. If C<create> is set and
288the Perl subroutine does not exist then it will be declared (which has the
289same effect as saying C<sub name;>). If C<create> is not set and the
290subroutine does not exist then NULL is returned.
291
292NOTE: the perl_ form of this function is deprecated.
293
294 CV* get_cv(const char* name, I32 create)
295
296=item get_hv
297
298Returns the HV of the specified Perl hash. If C<create> is set and the
299Perl variable does not exist then it will be created. If C<create> is not
300set and the variable does not exist then NULL is returned.
301
302NOTE: the perl_ form of this function is deprecated.
303
304 HV* get_hv(const char* name, I32 create)
305
306=item get_sv
307
308Returns the SV of the specified Perl scalar. If C<create> is set and the
309Perl variable does not exist then it will be created. If C<create> is not
310set and the variable does not exist then NULL is returned.
311
312NOTE: the perl_ form of this function is deprecated.
313
314 SV* get_sv(const char* name, I32 create)
315
316=item GIMME
317
318A backward-compatible version of C<GIMME_V> which can only return
319C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
320Deprecated. Use C<GIMME_V> instead.
321
322 U32 GIMME
323
324=item GIMME_V
325
326The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
327C<G_SCALAR> or C<G_ARRAY> for void, scalar or array context,
328respectively.
329
330 U32 GIMME_V
331
332=item GvSV
333
334Return the SV from the GV.
335
336 SV* GvSV(GV* gv)
337
338=item gv_fetchmeth
339
340Returns the glob with the given C<name> and a defined subroutine or
341C<NULL>. The glob lives in the given C<stash>, or in the stashes
342accessible via @ISA and @UNIVERSAL.
343
344The argument C<level> should be either 0 or -1. If C<level==0>, as a
345side-effect creates a glob with the given C<name> in the given C<stash>
346which in the case of success contains an alias for the subroutine, and sets
347up caching info for this glob. Similarly for all the searched stashes.
348
349This function grants C<"SUPER"> token as a postfix of the stash name. The
350GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
4929bf7b 351visible to Perl code. So when calling C<call_sv>, you should not use
954c1994
GS
352the GV directly; instead, you should use the method's CV, which can be
353obtained from the GV with the C<GvCV> macro.
354
355 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
356
357=item gv_fetchmethod
358
6d0f518e 359See L<gv_fetchmethod_autoload>.
954c1994
GS
360
361 GV* gv_fetchmethod(HV* stash, const char* name)
362
363=item gv_fetchmethod_autoload
364
365Returns the glob which contains the subroutine to call to invoke the method
366on the C<stash>. In fact in the presence of autoloading this may be the
367glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
368already setup.
369
370The third parameter of C<gv_fetchmethod_autoload> determines whether
371AUTOLOAD lookup is performed if the given method is not present: non-zero
372means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
373Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
374with a non-zero C<autoload> parameter.
375
376These functions grant C<"SUPER"> token as a prefix of the method name. Note
377that if you want to keep the returned glob for a long time, you need to
378check for it being "AUTOLOAD", since at the later time the call may load a
379different subroutine due to $AUTOLOAD changing its value. Use the glob
380created via a side effect to do this.
381
382These functions have the same side-effects and as C<gv_fetchmeth> with
383C<level==0>. C<name> should be writable if contains C<':'> or C<'
384''>. The warning against passing the GV returned by C<gv_fetchmeth> to
4929bf7b 385C<call_sv> apply equally to these functions.
954c1994
GS
386
387 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
388
389=item gv_stashpv
390
386d01d6
GS
391Returns a pointer to the stash for a specified package. C<name> should
392be a valid UTF-8 string. If C<create> is set then the package will be
393created if it does not already exist. If C<create> is not set and the
394package does not exist then NULL is returned.
954c1994
GS
395
396 HV* gv_stashpv(const char* name, I32 create)
397
398=item gv_stashsv
399
386d01d6
GS
400Returns a pointer to the stash for a specified package, which must be a
401valid UTF-8 string. See C<gv_stashpv>.
954c1994
GS
402
403 HV* gv_stashsv(SV* sv, I32 create)
404
405=item G_ARRAY
406
407Used to indicate array context. See C<GIMME_V>, C<GIMME> and
408L<perlcall>.
409
410=item G_DISCARD
411
412Indicates that arguments returned from a callback should be discarded. See
413L<perlcall>.
414
415=item G_EVAL
416
417Used to force a Perl C<eval> wrapper around a callback. See
418L<perlcall>.
419
420=item G_NOARGS
421
422Indicates that no arguments are being sent to a callback. See
423L<perlcall>.
424
425=item G_SCALAR
426
427Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
428L<perlcall>.
429
430=item G_VOID
431
432Used to indicate void context. See C<GIMME_V> and L<perlcall>.
433
434=item HEf_SVKEY
435
436This flag, used in the length slot of hash entries and magic structures,
437specifies the structure contains a C<SV*> pointer where a C<char*> pointer
438is to be expected. (For information only--not to be used).
439
440=item HeHASH
441
442Returns the computed hash stored in the hash entry.
443
444 U32 HeHASH(HE* he)
445
446=item HeKEY
447
448Returns the actual pointer stored in the key slot of the hash entry. The
449pointer may be either C<char*> or C<SV*>, depending on the value of
450C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
451usually preferable for finding the value of a key.
452
453 void* HeKEY(HE* he)
454
455=item HeKLEN
456
457If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
458holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
459be assigned to. The C<HePV()> macro is usually preferable for finding key
460lengths.
461
462 STRLEN HeKLEN(HE* he)
463
464=item HePV
465
466Returns the key slot of the hash entry as a C<char*> value, doing any
467necessary dereferencing of possibly C<SV*> keys. The length of the string
468is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
469not care about what the length of the key is, you may use the global
470variable C<PL_na>, though this is rather less efficient than using a local
471variable. Remember though, that hash keys in perl are free to contain
472embedded nulls, so using C<strlen()> or similar is not a good way to find
473the length of hash keys. This is very similar to the C<SvPV()> macro
474described elsewhere in this document.
475
476 char* HePV(HE* he, STRLEN len)
477
478=item HeSVKEY
479
480Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
481contain an C<SV*> key.
482
483 SV* HeSVKEY(HE* he)
484
485=item HeSVKEY_force
486
487Returns the key as an C<SV*>. Will create and return a temporary mortal
488C<SV*> if the hash entry contains only a C<char*> key.
489
490 SV* HeSVKEY_force(HE* he)
491
492=item HeSVKEY_set
493
494Sets the key to a given C<SV*>, taking care to set the appropriate flags to
495indicate the presence of an C<SV*> key, and returns the same
496C<SV*>.
497
498 SV* HeSVKEY_set(HE* he, SV* sv)
499
500=item HeVAL
501
502Returns the value slot (type C<SV*>) stored in the hash entry.
503
504 SV* HeVAL(HE* he)
505
506=item HvNAME
507
508Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
509
510 char* HvNAME(HV* stash)
511
512=item hv_clear
513
514Clears a hash, making it empty.
515
516 void hv_clear(HV* tb)
517
518=item hv_delete
519
520Deletes a key/value pair in the hash. The value SV is removed from the
521hash and returned to the caller. The C<klen> is the length of the key.
522The C<flags> value will normally be zero; if set to G_DISCARD then NULL
523will be returned.
524
525 SV* hv_delete(HV* tb, const char* key, U32 klen, I32 flags)
526
527=item hv_delete_ent
528
529Deletes a key/value pair in the hash. The value SV is removed from the
530hash and returned to the caller. The C<flags> value will normally be zero;
531if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
532precomputed hash value, or 0 to ask for it to be computed.
533
534 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
535
536=item hv_exists
537
538Returns a boolean indicating whether the specified hash key exists. The
539C<klen> is the length of the key.
540
541 bool hv_exists(HV* tb, const char* key, U32 klen)
542
543=item hv_exists_ent
544
545Returns a boolean indicating whether the specified hash key exists. C<hash>
546can be a valid precomputed hash value, or 0 to ask for it to be
547computed.
548
549 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
550
551=item hv_fetch
552
553Returns the SV which corresponds to the specified key in the hash. The
554C<klen> is the length of the key. If C<lval> is set then the fetch will be
555part of a store. Check that the return value is non-null before
556dereferencing it to a C<SV*>.
557
96f1132b 558See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
559information on how to use this function on tied hashes.
560
561 SV** hv_fetch(HV* tb, const char* key, U32 klen, I32 lval)
562
563=item hv_fetch_ent
564
565Returns the hash entry which corresponds to the specified key in the hash.
566C<hash> must be a valid precomputed hash number for the given C<key>, or 0
567if you want the function to compute it. IF C<lval> is set then the fetch
568will be part of a store. Make sure the return value is non-null before
569accessing it. The return value when C<tb> is a tied hash is a pointer to a
570static location, so be sure to make a copy of the structure if you need to
571store it somewhere.
572
96f1132b 573See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
574information on how to use this function on tied hashes.
575
576 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
577
578=item hv_iterinit
579
580Prepares a starting point to traverse a hash table. Returns the number of
581keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
582currently only meaningful for hashes without tie magic.
583
584NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
585hash buckets that happen to be in use. If you still need that esoteric
586value, you can get it through the macro C<HvFILL(tb)>.
587
588 I32 hv_iterinit(HV* tb)
589
590=item hv_iterkey
591
592Returns the key from the current position of the hash iterator. See
593C<hv_iterinit>.
594
595 char* hv_iterkey(HE* entry, I32* retlen)
596
597=item hv_iterkeysv
598
599Returns the key as an C<SV*> from the current position of the hash
600iterator. The return value will always be a mortal copy of the key. Also
601see C<hv_iterinit>.
602
603 SV* hv_iterkeysv(HE* entry)
604
605=item hv_iternext
606
607Returns entries from a hash iterator. See C<hv_iterinit>.
608
609 HE* hv_iternext(HV* tb)
610
611=item hv_iternextsv
612
613Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
614operation.
615
616 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
617
618=item hv_iterval
619
620Returns the value from the current position of the hash iterator. See
621C<hv_iterkey>.
622
623 SV* hv_iterval(HV* tb, HE* entry)
624
625=item hv_magic
626
627Adds magic to a hash. See C<sv_magic>.
628
629 void hv_magic(HV* hv, GV* gv, int how)
630
631=item hv_store
632
633Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
634the length of the key. The C<hash> parameter is the precomputed hash
635value; if it is zero then Perl will compute it. The return value will be
636NULL if the operation failed or if the value did not need to be actually
637stored within the hash (as in the case of tied hashes). Otherwise it can
638be dereferenced to get the original C<SV*>. Note that the caller is
639responsible for suitably incrementing the reference count of C<val> before
640the call, and decrementing it if the function returned NULL.
641
96f1132b 642See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
643information on how to use this function on tied hashes.
644
645 SV** hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash)
646
647=item hv_store_ent
648
649Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
650parameter is the precomputed hash value; if it is zero then Perl will
651compute it. The return value is the new hash entry so created. It will be
652NULL if the operation failed or if the value did not need to be actually
653stored within the hash (as in the case of tied hashes). Otherwise the
654contents of the return value can be accessed using the C<He???> macros
655described here. Note that the caller is responsible for suitably
656incrementing the reference count of C<val> before the call, and
657decrementing it if the function returned NULL.
658
96f1132b 659See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
660information on how to use this function on tied hashes.
661
662 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
663
664=item hv_undef
665
666Undefines the hash.
667
668 void hv_undef(HV* tb)
669
670=item isALNUM
671
4375e838 672Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
f1cbbd6e 673character (including underscore) or digit.
954c1994
GS
674
675 bool isALNUM(char ch)
676
677=item isALPHA
678
4375e838 679Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
954c1994
GS
680character.
681
682 bool isALPHA(char ch)
683
684=item isDIGIT
685
4375e838 686Returns a boolean indicating whether the C C<char> is an ASCII
954c1994
GS
687digit.
688
689 bool isDIGIT(char ch)
690
691=item isLOWER
692
693Returns a boolean indicating whether the C C<char> is a lowercase
694character.
695
696 bool isLOWER(char ch)
697
698=item isSPACE
699
700Returns a boolean indicating whether the C C<char> is whitespace.
701
702 bool isSPACE(char ch)
703
704=item isUPPER
705
706Returns a boolean indicating whether the C C<char> is an uppercase
707character.
708
709 bool isUPPER(char ch)
710
711=item items
712
713Variable which is setup by C<xsubpp> to indicate the number of
714items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
715
716 I32 items
717
718=item ix
719
720Variable which is setup by C<xsubpp> to indicate which of an
721XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
722
723 I32 ix
724
725=item LEAVE
726
727Closing bracket on a callback. See C<ENTER> and L<perlcall>.
728
729 LEAVE;
730
731=item looks_like_number
732
733Test if an the content of an SV looks like a number (or is a
734number).
735
736 I32 looks_like_number(SV* sv)
737
738=item MARK
739
740Stack marker variable for the XSUB. See C<dMARK>.
741
742=item mg_clear
743
744Clear something magical that the SV represents. See C<sv_magic>.
745
746 int mg_clear(SV* sv)
747
748=item mg_copy
749
750Copies the magic from one SV to another. See C<sv_magic>.
751
752 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
753
754=item mg_find
755
756Finds the magic pointer for type matching the SV. See C<sv_magic>.
757
758 MAGIC* mg_find(SV* sv, int type)
759
760=item mg_free
761
762Free any magic storage used by the SV. See C<sv_magic>.
763
764 int mg_free(SV* sv)
765
766=item mg_get
767
768Do magic after a value is retrieved from the SV. See C<sv_magic>.
769
770 int mg_get(SV* sv)
771
772=item mg_length
773
774Report on the SV's length. See C<sv_magic>.
775
776 U32 mg_length(SV* sv)
777
778=item mg_magical
779
780Turns on the magical status of an SV. See C<sv_magic>.
781
782 void mg_magical(SV* sv)
783
784=item mg_set
785
786Do magic after a value is assigned to the SV. See C<sv_magic>.
787
788 int mg_set(SV* sv)
789
790=item Move
791
792The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
793source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
794the type. Can do overlapping moves. See also C<Copy>.
795
796 void Move(void* src, void* dest, int nitems, type)
797
798=item New
799
800The XSUB-writer's interface to the C C<malloc> function.
801
802 void New(int id, void* ptr, int nitems, type)
803
804=item newAV
805
806Creates a new AV. The reference count is set to 1.
807
808 AV* newAV()
809
810=item Newc
811
812The XSUB-writer's interface to the C C<malloc> function, with
813cast.
814
815 void Newc(int id, void* ptr, int nitems, type, cast)
816
817=item newCONSTSUB
818
819Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
820eligible for inlining at compile-time.
821
822 void newCONSTSUB(HV* stash, char* name, SV* sv)
823
824=item newHV
825
826Creates a new HV. The reference count is set to 1.
827
828 HV* newHV()
829
830=item newRV_inc
831
832Creates an RV wrapper for an SV. The reference count for the original SV is
833incremented.
834
835 SV* newRV_inc(SV* sv)
836
837=item newRV_noinc
838
839Creates an RV wrapper for an SV. The reference count for the original
840SV is B<not> incremented.
841
842 SV* newRV_noinc(SV *sv)
843
844=item NEWSV
845
846Creates a new SV. A non-zero C<len> parameter indicates the number of
847bytes of preallocated string space the SV should have. An extra byte for a
848tailing NUL is also reserved. (SvPOK is not set for the SV even if string
849space is allocated.) The reference count for the new SV is set to 1.
850C<id> is an integer id between 0 and 1299 (used to identify leaks).
851
852 SV* NEWSV(int id, STRLEN len)
853
854=item newSViv
855
856Creates a new SV and copies an integer into it. The reference count for the
857SV is set to 1.
858
859 SV* newSViv(IV i)
860
861=item newSVnv
862
863Creates a new SV and copies a floating point value into it.
864The reference count for the SV is set to 1.
865
866 SV* newSVnv(NV n)
867
868=item newSVpv
869
870Creates a new SV and copies a string into it. The reference count for the
871SV is set to 1. If C<len> is zero, Perl will compute the length using
872strlen(). For efficiency, consider using C<newSVpvn> instead.
873
874 SV* newSVpv(const char* s, STRLEN len)
875
876=item newSVpvf
877
878Creates a new SV an initialize it with the string formatted like
879C<sprintf>.
880
881 SV* newSVpvf(const char* pat, ...)
882
883=item newSVpvn
884
885Creates a new SV and copies a string into it. The reference count for the
886SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
887string. You are responsible for ensuring that the source string is at least
888C<len> bytes long.
889
890 SV* newSVpvn(const char* s, STRLEN len)
891
892=item newSVrv
893
894Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
895it will be upgraded to one. If C<classname> is non-null then the new SV will
896be blessed in the specified package. The new SV is returned and its
897reference count is 1.
898
899 SV* newSVrv(SV* rv, const char* classname)
900
901=item newSVsv
902
903Creates a new SV which is an exact duplicate of the original SV.
904
905 SV* newSVsv(SV* old)
906
1a3327fb
JH
907=item newSVuv
908
909Creates a new SV and copies an unsigned integer into it.
910The reference count for the SV is set to 1.
911
912 SV* newSVuv(UV u)
913
954c1994
GS
914=item newXS
915
916Used by C<xsubpp> to hook up XSUBs as Perl subs.
917
918=item newXSproto
919
920Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
921the subs.
922
923=item Newz
924
925The XSUB-writer's interface to the C C<malloc> function. The allocated
926memory is zeroed with C<memzero>.
927
928 void Newz(int id, void* ptr, int nitems, type)
929
930=item Nullav
931
932Null AV pointer.
933
934=item Nullch
935
936Null character pointer.
937
938=item Nullcv
939
940Null CV pointer.
941
942=item Nullhv
943
944Null HV pointer.
945
946=item Nullsv
947
948Null SV pointer.
949
950=item ORIGMARK
951
952The original stack mark for the XSUB. See C<dORIGMARK>.
953
954=item perl_alloc
955
956Allocates a new Perl interpreter. See L<perlembed>.
957
958 PerlInterpreter* perl_alloc()
959
960=item perl_construct
961
962Initializes a new Perl interpreter. See L<perlembed>.
963
964 void perl_construct(PerlInterpreter* interp)
965
966=item perl_destruct
967
968Shuts down a Perl interpreter. See L<perlembed>.
969
970 void perl_destruct(PerlInterpreter* interp)
971
972=item perl_free
973
974Releases a Perl interpreter. See L<perlembed>.
975
976 void perl_free(PerlInterpreter* interp)
977
978=item perl_parse
979
980Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
981
982 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
983
984=item perl_run
985
986Tells a Perl interpreter to run. See L<perlembed>.
987
988 int perl_run(PerlInterpreter* interp)
989
990=item PL_DBsingle
991
992When Perl is run in debugging mode, with the B<-d> switch, this SV is a
993boolean which indicates whether subs are being single-stepped.
994Single-stepping is automatically turned on after every step. This is the C
995variable which corresponds to Perl's $DB::single variable. See
996C<PL_DBsub>.
997
998 SV * PL_DBsingle
999
1000=item PL_DBsub
1001
1002When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1003the SV which holds the name of the sub being debugged. This is the C
1004variable which corresponds to Perl's $DB::sub variable. See
1005C<PL_DBsingle>.
1006
1007 GV * PL_DBsub
1008
1009=item PL_DBtrace
1010
1011Trace variable used when Perl is run in debugging mode, with the B<-d>
1012switch. This is the C variable which corresponds to Perl's $DB::trace
1013variable. See C<PL_DBsingle>.
1014
1015 SV * PL_DBtrace
1016
1017=item PL_dowarn
1018
1019The C variable which corresponds to Perl's $^W warning variable.
1020
1021 bool PL_dowarn
1022
1023=item PL_modglobal
1024
1025C<PL_modglobal> is a general purpose, interpreter global HV for use by
1026extensions that need to keep information on a per-interpreter basis.
1027In a pinch, it can also be used as a symbol table for extensions
1028to share data among each other. It is a good idea to use keys
1029prefixed by the package name of the extension that owns the data.
1030
1031 HV* PL_modglobal
1032
1033=item PL_na
1034
1035A convenience variable which is typically used with C<SvPV> when one
1036doesn't care about the length of the string. It is usually more efficient
1037to either declare a local variable and use that instead or to use the
1038C<SvPV_nolen> macro.
1039
1040 STRLEN PL_na
1041
1042=item PL_sv_no
1043
1044This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1045C<&PL_sv_no>.
1046
1047 SV PL_sv_no
1048
1049=item PL_sv_undef
1050
1051This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1052
1053 SV PL_sv_undef
1054
1055=item PL_sv_yes
1056
1057This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1058C<&PL_sv_yes>.
1059
1060 SV PL_sv_yes
1061
1062=item POPi
1063
1064Pops an integer off the stack.
1065
1066 IV POPi
1067
1068=item POPl
1069
1070Pops a long off the stack.
1071
1072 long POPl
1073
1074=item POPn
1075
1076Pops a double off the stack.
1077
1078 NV POPn
1079
1080=item POPp
1081
1082Pops a string off the stack.
1083
1084 char* POPp
1085
1086=item POPs
1087
1088Pops an SV off the stack.
1089
1090 SV* POPs
1091
1092=item PUSHi
1093
1094Push an integer onto the stack. The stack must have room for this element.
1095Handles 'set' magic. See C<XPUSHi>.
1096
1097 void PUSHi(IV iv)
1098
1099=item PUSHMARK
1100
1101Opening bracket for arguments on a callback. See C<PUTBACK> and
1102L<perlcall>.
1103
1104 PUSHMARK;
1105
1106=item PUSHn
1107
1108Push a double onto the stack. The stack must have room for this element.
1109Handles 'set' magic. See C<XPUSHn>.
1110
1111 void PUSHn(NV nv)
1112
1113=item PUSHp
1114
1115Push a string onto the stack. The stack must have room for this element.
1116The C<len> indicates the length of the string. Handles 'set' magic. See
1117C<XPUSHp>.
1118
1119 void PUSHp(char* str, STRLEN len)
1120
1121=item PUSHs
1122
1123Push an SV onto the stack. The stack must have room for this element.
1124Does not handle 'set' magic. See C<XPUSHs>.
1125
1126 void PUSHs(SV* sv)
1127
1128=item PUSHu
1129
1130Push an unsigned integer onto the stack. The stack must have room for this
1131element. See C<XPUSHu>.
1132
1133 void PUSHu(UV uv)
1134
1135=item PUTBACK
1136
1137Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1138See C<PUSHMARK> and L<perlcall> for other uses.
1139
1140 PUTBACK;
1141
1142=item Renew
1143
1144The XSUB-writer's interface to the C C<realloc> function.
1145
1146 void Renew(void* ptr, int nitems, type)
1147
1148=item Renewc
1149
1150The XSUB-writer's interface to the C C<realloc> function, with
1151cast.
1152
1153 void Renewc(void* ptr, int nitems, type, cast)
1154
1155=item require_pv
1156
1157Tells Perl to C<require> a module.
1158
1159NOTE: the perl_ form of this function is deprecated.
1160
1161 void require_pv(const char* pv)
1162
1163=item RETVAL
1164
1165Variable which is setup by C<xsubpp> to hold the return value for an
1166XSUB. This is always the proper type for the XSUB. See
1167L<perlxs/"The RETVAL Variable">.
1168
1169 (whatever) RETVAL
1170
1171=item Safefree
1172
1173The XSUB-writer's interface to the C C<free> function.
1174
1175 void Safefree(void* src, void* dest, int nitems, type)
1176
1177=item savepv
1178
1179Copy a string to a safe spot. This does not use an SV.
1180
1181 char* savepv(const char* sv)
1182
1183=item savepvn
1184
1185Copy a string to a safe spot. The C<len> indicates number of bytes to
1186copy. This does not use an SV.
1187
1188 char* savepvn(const char* sv, I32 len)
1189
1190=item SAVETMPS
1191
1192Opening bracket for temporaries on a callback. See C<FREETMPS> and
1193L<perlcall>.
1194
1195 SAVETMPS;
1196
1197=item SP
1198
1199Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1200C<SPAGAIN>.
1201
1202=item SPAGAIN
1203
1204Refetch the stack pointer. Used after a callback. See L<perlcall>.
1205
1206 SPAGAIN;
1207
1208=item ST
1209
1210Used to access elements on the XSUB's stack.
1211
1212 SV* ST(int ix)
1213
1214=item strEQ
1215
1216Test two strings to see if they are equal. Returns true or false.
1217
1218 bool strEQ(char* s1, char* s2)
1219
1220=item strGE
1221
1222Test two strings to see if the first, C<s1>, is greater than or equal to
1223the second, C<s2>. Returns true or false.
1224
1225 bool strGE(char* s1, char* s2)
1226
1227=item strGT
1228
1229Test two strings to see if the first, C<s1>, is greater than the second,
1230C<s2>. Returns true or false.
1231
1232 bool strGT(char* s1, char* s2)
1233
1234=item strLE
1235
1236Test two strings to see if the first, C<s1>, is less than or equal to the
1237second, C<s2>. Returns true or false.
1238
1239 bool strLE(char* s1, char* s2)
1240
1241=item strLT
1242
1243Test two strings to see if the first, C<s1>, is less than the second,
1244C<s2>. Returns true or false.
1245
1246 bool strLT(char* s1, char* s2)
1247
1248=item strNE
1249
1250Test two strings to see if they are different. Returns true or
1251false.
1252
1253 bool strNE(char* s1, char* s2)
1254
1255=item strnEQ
1256
1257Test two strings to see if they are equal. The C<len> parameter indicates
1258the number of bytes to compare. Returns true or false. (A wrapper for
1259C<strncmp>).
1260
1261 bool strnEQ(char* s1, char* s2, STRLEN len)
1262
1263=item strnNE
1264
1265Test two strings to see if they are different. The C<len> parameter
1266indicates the number of bytes to compare. Returns true or false. (A
1267wrapper for C<strncmp>).
1268
1269 bool strnNE(char* s1, char* s2, STRLEN len)
1270
1271=item StructCopy
1272
4375e838 1273This is an architecture-independent macro to copy one structure to another.
954c1994
GS
1274
1275 void StructCopy(type src, type dest, type)
1276
1277=item SvCUR
1278
1279Returns the length of the string which is in the SV. See C<SvLEN>.
1280
1281 STRLEN SvCUR(SV* sv)
1282
1283=item SvCUR_set
1284
1285Set the length of the string which is in the SV. See C<SvCUR>.
1286
1287 void SvCUR_set(SV* sv, STRLEN len)
1288
1289=item SvEND
1290
1291Returns a pointer to the last character in the string which is in the SV.
1292See C<SvCUR>. Access the character as *(SvEND(sv)).
1293
1294 char* SvEND(SV* sv)
1295
1296=item SvGETMAGIC
1297
1298Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1299argument more than once.
1300
1301 void SvGETMAGIC(SV* sv)
1302
1303=item SvGROW
1304
1305Expands the character buffer in the SV so that it has room for the
1306indicated number of bytes (remember to reserve space for an extra trailing
1307NUL character). Calls C<sv_grow> to perform the expansion if necessary.
1308Returns a pointer to the character buffer.
1309
1310 void SvGROW(SV* sv, STRLEN len)
1311
1312=item SvIOK
1313
1314Returns a boolean indicating whether the SV contains an integer.
1315
1316 bool SvIOK(SV* sv)
1317
1318=item SvIOKp
1319
1320Returns a boolean indicating whether the SV contains an integer. Checks
1321the B<private> setting. Use C<SvIOK>.
1322
1323 bool SvIOKp(SV* sv)
1324
1325=item SvIOK_off
1326
1327Unsets the IV status of an SV.
1328
1329 void SvIOK_off(SV* sv)
1330
1331=item SvIOK_on
1332
1333Tells an SV that it is an integer.
1334
1335 void SvIOK_on(SV* sv)
1336
1337=item SvIOK_only
1338
1339Tells an SV that it is an integer and disables all other OK bits.
1340
1341 void SvIOK_only(SV* sv)
1342
1343=item SvIV
1344
1345Coerces the given SV to an integer and returns it.
1346
1347 IV SvIV(SV* sv)
1348
1349=item SvIVX
1350
1351Returns the integer which is stored in the SV, assuming SvIOK is
1352true.
1353
1354 IV SvIVX(SV* sv)
1355
1356=item SvLEN
1357
1358Returns the size of the string buffer in the SV. See C<SvCUR>.
1359
1360 STRLEN SvLEN(SV* sv)
1361
1362=item SvNIOK
1363
1364Returns a boolean indicating whether the SV contains a number, integer or
1365double.
1366
1367 bool SvNIOK(SV* sv)
1368
1369=item SvNIOKp
1370
1371Returns a boolean indicating whether the SV contains a number, integer or
1372double. Checks the B<private> setting. Use C<SvNIOK>.
1373
1374 bool SvNIOKp(SV* sv)
1375
1376=item SvNIOK_off
1377
1378Unsets the NV/IV status of an SV.
1379
1380 void SvNIOK_off(SV* sv)
1381
1382=item SvNOK
1383
1384Returns a boolean indicating whether the SV contains a double.
1385
1386 bool SvNOK(SV* sv)
1387
1388=item SvNOKp
1389
1390Returns a boolean indicating whether the SV contains a double. Checks the
1391B<private> setting. Use C<SvNOK>.
1392
1393 bool SvNOKp(SV* sv)
1394
1395=item SvNOK_off
1396
1397Unsets the NV status of an SV.
1398
1399 void SvNOK_off(SV* sv)
1400
1401=item SvNOK_on
1402
1403Tells an SV that it is a double.
1404
1405 void SvNOK_on(SV* sv)
1406
1407=item SvNOK_only
1408
1409Tells an SV that it is a double and disables all other OK bits.
1410
1411 void SvNOK_only(SV* sv)
1412
1413=item SvNV
1414
1415Coerce the given SV to a double and return it.
1416
1417 NV SvNV(SV* sv)
1418
1419=item SvNVX
1420
1421Returns the double which is stored in the SV, assuming SvNOK is
1422true.
1423
1424 NV SvNVX(SV* sv)
1425
1426=item SvOK
1427
1428Returns a boolean indicating whether the value is an SV.
1429
1430 bool SvOK(SV* sv)
1431
1432=item SvOOK
1433
1434Returns a boolean indicating whether the SvIVX is a valid offset value for
1435the SvPVX. This hack is used internally to speed up removal of characters
1436from the beginning of a SvPV. When SvOOK is true, then the start of the
1437allocated string buffer is really (SvPVX - SvIVX).
1438
1439 bool SvOOK(SV* sv)
1440
1441=item SvPOK
1442
1443Returns a boolean indicating whether the SV contains a character
1444string.
1445
1446 bool SvPOK(SV* sv)
1447
1448=item SvPOKp
1449
1450Returns a boolean indicating whether the SV contains a character string.
1451Checks the B<private> setting. Use C<SvPOK>.
1452
1453 bool SvPOKp(SV* sv)
1454
1455=item SvPOK_off
1456
1457Unsets the PV status of an SV.
1458
1459 void SvPOK_off(SV* sv)
1460
1461=item SvPOK_on
1462
1463Tells an SV that it is a string.
1464
1465 void SvPOK_on(SV* sv)
1466
1467=item SvPOK_only
1468
1469Tells an SV that it is a string and disables all other OK bits.
1470
1471 void SvPOK_only(SV* sv)
1472
1473=item SvPV
1474
1475Returns a pointer to the string in the SV, or a stringified form of the SV
1476if the SV does not contain a string. Handles 'get' magic.
1477
1478 char* SvPV(SV* sv, STRLEN len)
1479
1480=item SvPVX
1481
1482Returns a pointer to the string in the SV. The SV must contain a
1483string.
1484
1485 char* SvPVX(SV* sv)
1486
1487=item SvPV_force
1488
1489Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
1490force if you are going to update the SvPVX directly.
1491
1492 char* SvPV_force(SV* sv, STRLEN len)
1493
1494=item SvPV_nolen
1495
1496Returns a pointer to the string in the SV, or a stringified form of the SV
1497if the SV does not contain a string. Handles 'get' magic.
1498
1499 char* SvPV_nolen(SV* sv)
1500
1501=item SvREFCNT
1502
1503Returns the value of the object's reference count.
1504
1505 U32 SvREFCNT(SV* sv)
1506
1507=item SvREFCNT_dec
1508
1509Decrements the reference count of the given SV.
1510
1511 void SvREFCNT_dec(SV* sv)
1512
1513=item SvREFCNT_inc
1514
1515Increments the reference count of the given SV.
1516
1517 SV* SvREFCNT_inc(SV* sv)
1518
1519=item SvROK
1520
1521Tests if the SV is an RV.
1522
1523 bool SvROK(SV* sv)
1524
1525=item SvROK_off
1526
1527Unsets the RV status of an SV.
1528
1529 void SvROK_off(SV* sv)
1530
1531=item SvROK_on
1532
1533Tells an SV that it is an RV.
1534
1535 void SvROK_on(SV* sv)
1536
1537=item SvRV
1538
1539Dereferences an RV to return the SV.
1540
1541 SV* SvRV(SV* sv)
1542
1543=item SvSETMAGIC
1544
1545Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
1546argument more than once.
1547
1548 void SvSETMAGIC(SV* sv)
1549
1550=item SvSetSV
1551
1552Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
1553more than once.
1554
1555 void SvSetSV(SV* dsb, SV* ssv)
1556
1557=item SvSetSV_nosteal
1558
1559Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1560ssv. May evaluate arguments more than once.
1561
1562 void SvSetSV_nosteal(SV* dsv, SV* ssv)
1563
1564=item SvSTASH
1565
1566Returns the stash of the SV.
1567
1568 HV* SvSTASH(SV* sv)
1569
1570=item SvTAINT
1571
1572Taints an SV if tainting is enabled
1573
1574 void SvTAINT(SV* sv)
1575
1576=item SvTAINTED
1577
1578Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
1579not.
1580
1581 bool SvTAINTED(SV* sv)
1582
1583=item SvTAINTED_off
1584
1585Untaints an SV. Be I<very> careful with this routine, as it short-circuits
1586some of Perl's fundamental security features. XS module authors should not
1587use this function unless they fully understand all the implications of
1588unconditionally untainting the value. Untainting should be done in the
1589standard perl fashion, via a carefully crafted regexp, rather than directly
1590untainting variables.
1591
1592 void SvTAINTED_off(SV* sv)
1593
1594=item SvTAINTED_on
1595
1596Marks an SV as tainted.
1597
1598 void SvTAINTED_on(SV* sv)
1599
1600=item SvTRUE
1601
1602Returns a boolean indicating whether Perl would evaluate the SV as true or
1603false, defined or undefined. Does not handle 'get' magic.
1604
1605 bool SvTRUE(SV* sv)
1606
0dff5aa1
GS
1607=item svtype
1608
1609An enum of flags for Perl types. These are found in the file B<sv.h>
1610in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
1611
954c1994
GS
1612=item SvTYPE
1613
1614Returns the type of the SV. See C<svtype>.
1615
1616 svtype SvTYPE(SV* sv)
1617
954c1994
GS
1618=item SVt_IV
1619
1620Integer type flag for scalars. See C<svtype>.
1621
1622=item SVt_NV
1623
1624Double type flag for scalars. See C<svtype>.
1625
1626=item SVt_PV
1627
1628Pointer type flag for scalars. See C<svtype>.
1629
1630=item SVt_PVAV
1631
1632Type flag for arrays. See C<svtype>.
1633
1634=item SVt_PVCV
1635
1636Type flag for code refs. See C<svtype>.
1637
1638=item SVt_PVHV
1639
1640Type flag for hashes. See C<svtype>.
1641
1642=item SVt_PVMG
1643
1644Type flag for blessed scalars. See C<svtype>.
1645
1646=item SvUPGRADE
1647
1648Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
1649perform the upgrade if necessary. See C<svtype>.
1650
1651 void SvUPGRADE(SV* sv, svtype type)
1652
1653=item SvUV
1654
1655Coerces the given SV to an unsigned integer and returns it.
1656
1657 UV SvUV(SV* sv)
1658
1659=item SvUVX
1660
1661Returns the unsigned integer which is stored in the SV, assuming SvIOK is
1662true.
1663
1664 UV SvUVX(SV* sv)
1665
1666=item sv_2mortal
1667
1668Marks an SV as mortal. The SV will be destroyed when the current context
1669ends.
1670
1671 SV* sv_2mortal(SV* sv)
1672
1673=item sv_bless
1674
1675Blesses an SV into a specified package. The SV must be an RV. The package
1676must be designated by its stash (see C<gv_stashpv()>). The reference count
1677of the SV is unaffected.
1678
1679 SV* sv_bless(SV* sv, HV* stash)
1680
1681=item sv_catpv
1682
1683Concatenates the string onto the end of the string which is in the SV.
1684Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
1685
1686 void sv_catpv(SV* sv, const char* ptr)
1687
1688=item sv_catpvf
1689
1690Processes its arguments like C<sprintf> and appends the formatted output
1691to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
1692typically be called after calling this function to handle 'set' magic.
1693
1694 void sv_catpvf(SV* sv, const char* pat, ...)
1695
1696=item sv_catpvf_mg
1697
1698Like C<sv_catpvf>, but also handles 'set' magic.
1699
1700 void sv_catpvf_mg(SV *sv, const char* pat, ...)
1701
1702=item sv_catpvn
1703
1704Concatenates the string onto the end of the string which is in the SV. The
1705C<len> indicates number of bytes to copy. Handles 'get' magic, but not
1706'set' magic. See C<sv_catpvn_mg>.
1707
1708 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
1709
1710=item sv_catpvn_mg
1711
1712Like C<sv_catpvn>, but also handles 'set' magic.
1713
1714 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
1715
1716=item sv_catpv_mg
1717
1718Like C<sv_catpv>, but also handles 'set' magic.
1719
1720 void sv_catpv_mg(SV *sv, const char *ptr)
1721
1722=item sv_catsv
1723
1724Concatenates the string from SV C<ssv> onto the end of the string in SV
1725C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
1726
1727 void sv_catsv(SV* dsv, SV* ssv)
1728
1729=item sv_catsv_mg
1730
1731Like C<sv_catsv>, but also handles 'set' magic.
1732
1733 void sv_catsv_mg(SV *dstr, SV *sstr)
1734
1735=item sv_chop
1736
1737Efficient removal of characters from the beginning of the string buffer.
1738SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
1739the string buffer. The C<ptr> becomes the first character of the adjusted
1740string.
1741
1742 void sv_chop(SV* sv, char* ptr)
1743
1744=item sv_cmp
1745
1746Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1747string in C<sv1> is less than, equal to, or greater than the string in
1748C<sv2>.
1749
1750 I32 sv_cmp(SV* sv1, SV* sv2)
1751
1752=item sv_dec
1753
1754Auto-decrement of the value in the SV.
1755
1756 void sv_dec(SV* sv)
1757
1758=item sv_derived_from
1759
1760Returns a boolean indicating whether the SV is derived from the specified
1761class. This is the function that implements C<UNIVERSAL::isa>. It works
1762for class names as well as for objects.
1763
1764 bool sv_derived_from(SV* sv, const char* name)
1765
1766=item sv_eq
1767
1768Returns a boolean indicating whether the strings in the two SVs are
1769identical.
1770
1771 I32 sv_eq(SV* sv1, SV* sv2)
1772
1773=item sv_grow
1774
1775Expands the character buffer in the SV. This will use C<sv_unref> and will
1776upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
1777Use C<SvGROW>.
1778
1779 char* sv_grow(SV* sv, STRLEN newlen)
1780
1781=item sv_inc
1782
1783Auto-increment of the value in the SV.
1784
1785 void sv_inc(SV* sv)
1786
1787=item sv_insert
1788
1789Inserts a string at the specified offset/length within the SV. Similar to
1790the Perl substr() function.
1791
1792 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
1793
1794=item sv_isa
1795
1796Returns a boolean indicating whether the SV is blessed into the specified
1797class. This does not check for subtypes; use C<sv_derived_from> to verify
1798an inheritance relationship.
1799
1800 int sv_isa(SV* sv, const char* name)
1801
1802=item sv_isobject
1803
1804Returns a boolean indicating whether the SV is an RV pointing to a blessed
1805object. If the SV is not an RV, or if the object is not blessed, then this
1806will return false.
1807
1808 int sv_isobject(SV* sv)
1809
1810=item sv_len
1811
1812Returns the length of the string in the SV. See also C<SvCUR>.
1813
1814 STRLEN sv_len(SV* sv)
1815
1816=item sv_magic
1817
1818Adds magic to an SV.
1819
1820 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
1821
1822=item sv_mortalcopy
1823
1824Creates a new SV which is a copy of the original SV. The new SV is marked
1825as mortal.
1826
1827 SV* sv_mortalcopy(SV* oldsv)
1828
1829=item sv_newmortal
1830
1831Creates a new SV which is mortal. The reference count of the SV is set to 1.
1832
1833 SV* sv_newmortal()
1834
1835=item sv_setiv
1836
1837Copies an integer into the given SV. Does not handle 'set' magic. See
1838C<sv_setiv_mg>.
1839
1840 void sv_setiv(SV* sv, IV num)
1841
1842=item sv_setiv_mg
1843
1844Like C<sv_setiv>, but also handles 'set' magic.
1845
1846 void sv_setiv_mg(SV *sv, IV i)
1847
1848=item sv_setnv
1849
1850Copies a double into the given SV. Does not handle 'set' magic. See
1851C<sv_setnv_mg>.
1852
1853 void sv_setnv(SV* sv, NV num)
1854
1855=item sv_setnv_mg
1856
1857Like C<sv_setnv>, but also handles 'set' magic.
1858
1859 void sv_setnv_mg(SV *sv, NV num)
1860
1861=item sv_setpv
1862
1863Copies a string into an SV. The string must be null-terminated. Does not
1864handle 'set' magic. See C<sv_setpv_mg>.
1865
1866 void sv_setpv(SV* sv, const char* ptr)
1867
1868=item sv_setpvf
1869
1870Processes its arguments like C<sprintf> and sets an SV to the formatted
1871output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
1872
1873 void sv_setpvf(SV* sv, const char* pat, ...)
1874
1875=item sv_setpvf_mg
1876
1877Like C<sv_setpvf>, but also handles 'set' magic.
1878
1879 void sv_setpvf_mg(SV *sv, const char* pat, ...)
1880
1881=item sv_setpviv
1882
1883Copies an integer into the given SV, also updating its string value.
1884Does not handle 'set' magic. See C<sv_setpviv_mg>.
1885
1886 void sv_setpviv(SV* sv, IV num)
1887
1888=item sv_setpviv_mg
1889
1890Like C<sv_setpviv>, but also handles 'set' magic.
1891
1892 void sv_setpviv_mg(SV *sv, IV iv)
1893
1894=item sv_setpvn
1895
1896Copies a string into an SV. The C<len> parameter indicates the number of
1897bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
1898
1899 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
1900
1901=item sv_setpvn_mg
1902
1903Like C<sv_setpvn>, but also handles 'set' magic.
1904
1905 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
1906
1907=item sv_setpv_mg
1908
1909Like C<sv_setpv>, but also handles 'set' magic.
1910
1911 void sv_setpv_mg(SV *sv, const char *ptr)
1912
1913=item sv_setref_iv
1914
1915Copies an integer into a new SV, optionally blessing the SV. The C<rv>
1916argument will be upgraded to an RV. That RV will be modified to point to
1917the new SV. The C<classname> argument indicates the package for the
1918blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1919will be returned and will have a reference count of 1.
1920
1921 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
1922
1923=item sv_setref_nv
1924
1925Copies a double into a new SV, optionally blessing the SV. The C<rv>
1926argument will be upgraded to an RV. That RV will be modified to point to
1927the new SV. The C<classname> argument indicates the package for the
1928blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1929will be returned and will have a reference count of 1.
1930
1931 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
1932
1933=item sv_setref_pv
1934
1935Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
1936argument will be upgraded to an RV. That RV will be modified to point to
1937the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
1938into the SV. The C<classname> argument indicates the package for the
1939blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1940will be returned and will have a reference count of 1.
1941
1942Do not use with other Perl types such as HV, AV, SV, CV, because those
1943objects will become corrupted by the pointer copy process.
1944
1945Note that C<sv_setref_pvn> copies the string while this copies the pointer.
1946
1947 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
1948
1949=item sv_setref_pvn
1950
1951Copies a string into a new SV, optionally blessing the SV. The length of the
1952string must be specified with C<n>. The C<rv> argument will be upgraded to
1953an RV. That RV will be modified to point to the new SV. The C<classname>
1954argument indicates the package for the blessing. Set C<classname> to
1955C<Nullch> to avoid the blessing. The new SV will be returned and will have
1956a reference count of 1.
1957
1958Note that C<sv_setref_pv> copies the pointer while this copies the string.
1959
1960 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
1961
1962=item sv_setsv
1963
1964Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
1965The source SV may be destroyed if it is mortal. Does not handle 'set'
1966magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
1967C<sv_setsv_mg>.
1968
1969 void sv_setsv(SV* dsv, SV* ssv)
1970
1971=item sv_setsv_mg
1972
1973Like C<sv_setsv>, but also handles 'set' magic.
1974
1975 void sv_setsv_mg(SV *dstr, SV *sstr)
1976
1977=item sv_setuv
1978
1979Copies an unsigned integer into the given SV. Does not handle 'set' magic.
1980See C<sv_setuv_mg>.
1981
1982 void sv_setuv(SV* sv, UV num)
1983
1984=item sv_setuv_mg
1985
1986Like C<sv_setuv>, but also handles 'set' magic.
1987
1988 void sv_setuv_mg(SV *sv, UV u)
1989
1990=item sv_unref
1991
1992Unsets the RV status of the SV, and decrements the reference count of
1993whatever was being referenced by the RV. This can almost be thought of
1994as a reversal of C<newSVrv>. See C<SvROK_off>.
1995
1996 void sv_unref(SV* sv)
1997
1998=item sv_upgrade
1999
2000Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
2001C<svtype>.
2002
2003 bool sv_upgrade(SV* sv, U32 mt)
2004
2005=item sv_usepvn
2006
2007Tells an SV to use C<ptr> to find its string value. Normally the string is
2008stored inside the SV but sv_usepvn allows the SV to use an outside string.
2009The C<ptr> should point to memory that was allocated by C<malloc>. The
2010string length, C<len>, must be supplied. This function will realloc the
2011memory pointed to by C<ptr>, so that pointer should not be freed or used by
2012the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
2013See C<sv_usepvn_mg>.
2014
2015 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
2016
2017=item sv_usepvn_mg
2018
2019Like C<sv_usepvn>, but also handles 'set' magic.
2020
2021 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
2022
2023=item sv_vcatpvfn
2024
2025Processes its arguments like C<vsprintf> and appends the formatted output
2026to an SV. Uses an array of SVs if the C style variable argument list is
2027missing (NULL). When running with taint checks enabled, indicates via
2028C<maybe_tainted> if results are untrustworthy (often due to the use of
2029locales).
2030
2031 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2032
2033=item sv_vsetpvfn
2034
2035Works like C<vcatpvfn> but copies the text into the SV instead of
2036appending it.
2037
2038 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2039
2040=item THIS
2041
2042Variable which is setup by C<xsubpp> to designate the object in a C++
2043XSUB. This is always the proper type for the C++ object. See C<CLASS> and
2044L<perlxs/"Using XS With C++">.
2045
2046 (whatever) THIS
2047
2048=item toLOWER
2049
2050Converts the specified character to lowercase.
2051
2052 char toLOWER(char ch)
2053
2054=item toUPPER
2055
2056Converts the specified character to uppercase.
2057
2058 char toUPPER(char ch)
2059
2060=item warn
2061
2062This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2063function the same way you use the C C<printf> function. See
2064C<croak>.
2065
2066 void warn(const char* pat, ...)
2067
2068=item XPUSHi
2069
2070Push an integer onto the stack, extending the stack if necessary. Handles
2071'set' magic. See C<PUSHi>.
2072
2073 void XPUSHi(IV iv)
2074
2075=item XPUSHn
2076
2077Push a double onto the stack, extending the stack if necessary. Handles
2078'set' magic. See C<PUSHn>.
2079
2080 void XPUSHn(NV nv)
2081
2082=item XPUSHp
2083
2084Push a string onto the stack, extending the stack if necessary. The C<len>
2085indicates the length of the string. Handles 'set' magic. See
2086C<PUSHp>.
2087
2088 void XPUSHp(char* str, STRLEN len)
2089
2090=item XPUSHs
2091
2092Push an SV onto the stack, extending the stack if necessary. Does not
2093handle 'set' magic. See C<PUSHs>.
2094
2095 void XPUSHs(SV* sv)
2096
2097=item XPUSHu
2098
2099Push an unsigned integer onto the stack, extending the stack if necessary.
2100See C<PUSHu>.
2101
2102 void XPUSHu(UV uv)
2103
2104=item XS
2105
2106Macro to declare an XSUB and its C parameter list. This is handled by
2107C<xsubpp>.
2108
2109=item XSRETURN
2110
2111Return from XSUB, indicating number of items on the stack. This is usually
2112handled by C<xsubpp>.
2113
2114 void XSRETURN(int nitems)
2115
2116=item XSRETURN_EMPTY
2117
2118Return an empty list from an XSUB immediately.
2119
2120 XSRETURN_EMPTY;
2121
2122=item XSRETURN_IV
2123
2124Return an integer from an XSUB immediately. Uses C<XST_mIV>.
2125
2126 void XSRETURN_IV(IV iv)
2127
2128=item XSRETURN_NO
2129
2130Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
2131
2132 XSRETURN_NO;
2133
2134=item XSRETURN_NV
2135
2136Return an double from an XSUB immediately. Uses C<XST_mNV>.
2137
2138 void XSRETURN_NV(NV nv)
2139
2140=item XSRETURN_PV
2141
2142Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2143
2144 void XSRETURN_PV(char* str)
2145
2146=item XSRETURN_UNDEF
2147
2148Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2149
2150 XSRETURN_UNDEF;
2151
2152=item XSRETURN_YES
2153
2154Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2155
2156 XSRETURN_YES;
2157
2158=item XST_mIV
2159
2160Place an integer into the specified position C<pos> on the stack. The
2161value is stored in a new mortal SV.
2162
2163 void XST_mIV(int pos, IV iv)
2164
2165=item XST_mNO
2166
2167Place C<&PL_sv_no> into the specified position C<pos> on the
2168stack.
2169
2170 void XST_mNO(int pos)
2171
2172=item XST_mNV
2173
2174Place a double into the specified position C<pos> on the stack. The value
2175is stored in a new mortal SV.
2176
2177 void XST_mNV(int pos, NV nv)
2178
2179=item XST_mPV
2180
2181Place a copy of a string into the specified position C<pos> on the stack.
2182The value is stored in a new mortal SV.
2183
2184 void XST_mPV(int pos, char* str)
2185
2186=item XST_mUNDEF
2187
2188Place C<&PL_sv_undef> into the specified position C<pos> on the
2189stack.
2190
2191 void XST_mUNDEF(int pos)
2192
2193=item XST_mYES
2194
2195Place C<&PL_sv_yes> into the specified position C<pos> on the
2196stack.
2197
2198 void XST_mYES(int pos)
2199
2200=item XS_VERSION
2201
2202The version identifier for an XS module. This is usually
2203handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
2204
2205=item XS_VERSION_BOOTCHECK
2206
2207Macro to verify that a PM module's $VERSION variable matches the XS
2208module's C<XS_VERSION> variable. This is usually handled automatically by
2209C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
2210
2211 XS_VERSION_BOOTCHECK;
2212
2213=item Zero
2214
2215The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
2216destination, C<nitems> is the number of items, and C<type> is the type.
2217
2218 void Zero(void* dest, int nitems, type)
2219
2220=back
2221
2222=head1 AUTHORS
2223
2224Until May 1997, this document was maintained by Jeff Okamoto
2225<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
2226
2227With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2228Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2229Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
2230Stephen McCamant, and Gurusamy Sarathy.
2231
2232API Listing originally by Dean Roehrich <roehrich@cray.com>.
2233
2234Updated to be autogenerated from comments in the source by Benjamin Stuhl.
2235
2236=head1 SEE ALSO
2237
2238perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
2239