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