This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
lib/b test fixes from Peter Prymmer.
[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
497711e7
GS
28=for hackers
29Found in file av.h
30
954c1994
GS
31=item av_clear
32
33Clears an array, making it empty. Does not free the memory used by the
34array itself.
35
36 void av_clear(AV* ar)
37
497711e7
GS
38=for hackers
39Found in file av.c
40
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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.
6662521e
GS
156Returns a pointer to the newly-created string, and sets C<len> to
157reflect the new length.
497711e7 158
6662521e 159 U8 * bytes_to_utf8(U8 *s, STRLEN *len)
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
GS
1286=for hackers
1287Found in file handy.h
1288
954c1994
GS
1289=item Nullav
1290
1291Null AV pointer.
1292
497711e7
GS
1293=for hackers
1294Found in file av.h
1295
954c1994
GS
1296=item Nullch
1297
1298Null character pointer.
1299
497711e7
GS
1300=for hackers
1301Found in file handy.h
1302
954c1994
GS
1303=item Nullcv
1304
1305Null CV pointer.
1306
497711e7
GS
1307=for hackers
1308Found in file cv.h
1309
954c1994
GS
1310=item Nullhv
1311
1312Null HV pointer.
1313
497711e7
GS
1314=for hackers
1315Found in file hv.h
1316
954c1994
GS
1317=item Nullsv
1318
1319Null SV pointer.
1320
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
GS
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
GS
2272=for hackers
2273Found in file sv.h
2274
6662521e 2275=item SvTYPE
34f7a5fe 2276
6662521e
GS
2277Returns the type of the SV. See C<svtype>.
2278
2279 svtype SvTYPE(SV* sv)
34f7a5fe 2280
497711e7
GS
2281=for hackers
2282Found in file sv.h
2283
6662521e 2284=item svtype
954c1994 2285
6662521e
GS
2286An enum of flags for Perl types. These are found in the file B<sv.h>
2287in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2288
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
GS
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
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
497711e7
GS
2478=for hackers
2479Found in file sv.c
2480
954c1994
GS
2481=item sv_cmp
2482
2483Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2484string in C<sv1> is less than, equal to, or greater than the string in
2485C<sv2>.
2486
2487 I32 sv_cmp(SV* sv1, SV* sv2)
2488
497711e7
GS
2489=for hackers
2490Found in file sv.c
2491
954c1994
GS
2492=item sv_dec
2493
2494Auto-decrement of the value in the SV.
2495
2496 void sv_dec(SV* sv)
2497
497711e7
GS
2498=for hackers
2499Found in file sv.c
2500
954c1994
GS
2501=item sv_derived_from
2502
2503Returns a boolean indicating whether the SV is derived from the specified
2504class. This is the function that implements C<UNIVERSAL::isa>. It works
2505for class names as well as for objects.
2506
2507 bool sv_derived_from(SV* sv, const char* name)
2508
497711e7
GS
2509=for hackers
2510Found in file universal.c
2511
954c1994
GS
2512=item sv_eq
2513
2514Returns a boolean indicating whether the strings in the two SVs are
2515identical.
2516
2517 I32 sv_eq(SV* sv1, SV* sv2)
2518
497711e7
GS
2519=for hackers
2520Found in file sv.c
2521
954c1994
GS
2522=item sv_grow
2523
2524Expands the character buffer in the SV. This will use C<sv_unref> and will
2525upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2526Use C<SvGROW>.
2527
2528 char* sv_grow(SV* sv, STRLEN newlen)
2529
497711e7
GS
2530=for hackers
2531Found in file sv.c
2532
954c1994
GS
2533=item sv_inc
2534
2535Auto-increment of the value in the SV.
2536
2537 void sv_inc(SV* sv)
2538
497711e7
GS
2539=for hackers
2540Found in file sv.c
2541
954c1994
GS
2542=item sv_insert
2543
2544Inserts a string at the specified offset/length within the SV. Similar to
2545the Perl substr() function.
2546
2547 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2548
497711e7
GS
2549=for hackers
2550Found in file sv.c
2551
954c1994
GS
2552=item sv_isa
2553
2554Returns a boolean indicating whether the SV is blessed into the specified
2555class. This does not check for subtypes; use C<sv_derived_from> to verify
2556an inheritance relationship.
2557
2558 int sv_isa(SV* sv, const char* name)
2559
497711e7
GS
2560=for hackers
2561Found in file sv.c
2562
954c1994
GS
2563=item sv_isobject
2564
2565Returns a boolean indicating whether the SV is an RV pointing to a blessed
2566object. If the SV is not an RV, or if the object is not blessed, then this
2567will return false.
2568
2569 int sv_isobject(SV* sv)
2570
497711e7
GS
2571=for hackers
2572Found in file sv.c
2573
954c1994
GS
2574=item sv_len
2575
2576Returns the length of the string in the SV. See also C<SvCUR>.
2577
2578 STRLEN sv_len(SV* sv)
2579
497711e7
GS
2580=for hackers
2581Found in file sv.c
2582
954c1994
GS
2583=item sv_magic
2584
2585Adds magic to an SV.
2586
2587 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2588
497711e7
GS
2589=for hackers
2590Found in file sv.c
2591
954c1994
GS
2592=item sv_mortalcopy
2593
2594Creates a new SV which is a copy of the original SV. The new SV is marked
2595as mortal.
2596
2597 SV* sv_mortalcopy(SV* oldsv)
2598
497711e7
GS
2599=for hackers
2600Found in file sv.c
2601
954c1994
GS
2602=item sv_newmortal
2603
2604Creates a new SV which is mortal. The reference count of the SV is set to 1.
2605
2606 SV* sv_newmortal()
2607
497711e7
GS
2608=for hackers
2609Found in file sv.c
2610
954c1994
GS
2611=item sv_setiv
2612
2613Copies an integer into the given SV. Does not handle 'set' magic. See
2614C<sv_setiv_mg>.
2615
2616 void sv_setiv(SV* sv, IV num)
2617
497711e7
GS
2618=for hackers
2619Found in file sv.c
2620
954c1994
GS
2621=item sv_setiv_mg
2622
2623Like C<sv_setiv>, but also handles 'set' magic.
2624
2625 void sv_setiv_mg(SV *sv, IV i)
2626
497711e7
GS
2627=for hackers
2628Found in file sv.c
2629
954c1994
GS
2630=item sv_setnv
2631
2632Copies a double into the given SV. Does not handle 'set' magic. See
2633C<sv_setnv_mg>.
2634
2635 void sv_setnv(SV* sv, NV num)
2636
497711e7
GS
2637=for hackers
2638Found in file sv.c
2639
954c1994
GS
2640=item sv_setnv_mg
2641
2642Like C<sv_setnv>, but also handles 'set' magic.
2643
2644 void sv_setnv_mg(SV *sv, NV num)
2645
497711e7
GS
2646=for hackers
2647Found in file sv.c
2648
954c1994
GS
2649=item sv_setpv
2650
2651Copies a string into an SV. The string must be null-terminated. Does not
2652handle 'set' magic. See C<sv_setpv_mg>.
2653
2654 void sv_setpv(SV* sv, const char* ptr)
2655
497711e7
GS
2656=for hackers
2657Found in file sv.c
2658
954c1994
GS
2659=item sv_setpvf
2660
2661Processes its arguments like C<sprintf> and sets an SV to the formatted
2662output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
2663
2664 void sv_setpvf(SV* sv, const char* pat, ...)
2665
497711e7
GS
2666=for hackers
2667Found in file sv.c
2668
954c1994
GS
2669=item sv_setpvf_mg
2670
2671Like C<sv_setpvf>, but also handles 'set' magic.
2672
2673 void sv_setpvf_mg(SV *sv, const char* pat, ...)
2674
497711e7
GS
2675=for hackers
2676Found in file sv.c
2677
954c1994
GS
2678=item sv_setpviv
2679
2680Copies an integer into the given SV, also updating its string value.
2681Does not handle 'set' magic. See C<sv_setpviv_mg>.
2682
2683 void sv_setpviv(SV* sv, IV num)
2684
497711e7
GS
2685=for hackers
2686Found in file sv.c
2687
954c1994
GS
2688=item sv_setpviv_mg
2689
2690Like C<sv_setpviv>, but also handles 'set' magic.
2691
2692 void sv_setpviv_mg(SV *sv, IV iv)
2693
497711e7
GS
2694=for hackers
2695Found in file sv.c
2696
954c1994
GS
2697=item sv_setpvn
2698
2699Copies a string into an SV. The C<len> parameter indicates the number of
2700bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
2701
2702 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2703
497711e7
GS
2704=for hackers
2705Found in file sv.c
2706
954c1994
GS
2707=item sv_setpvn_mg
2708
2709Like C<sv_setpvn>, but also handles 'set' magic.
2710
2711 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2712
497711e7
GS
2713=for hackers
2714Found in file sv.c
2715
954c1994
GS
2716=item sv_setpv_mg
2717
2718Like C<sv_setpv>, but also handles 'set' magic.
2719
2720 void sv_setpv_mg(SV *sv, const char *ptr)
2721
497711e7
GS
2722=for hackers
2723Found in file sv.c
2724
954c1994
GS
2725=item sv_setref_iv
2726
2727Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2728argument will be upgraded to an RV. That RV will be modified to point to
2729the new SV. The C<classname> argument indicates the package for the
2730blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2731will be returned and will have a reference count of 1.
2732
2733 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
2734
497711e7
GS
2735=for hackers
2736Found in file sv.c
2737
954c1994
GS
2738=item sv_setref_nv
2739
2740Copies a double into a new SV, optionally blessing the SV. The C<rv>
2741argument will be upgraded to an RV. That RV will be modified to point to
2742the new SV. The C<classname> argument indicates the package for the
2743blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2744will be returned and will have a reference count of 1.
2745
2746 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
2747
497711e7
GS
2748=for hackers
2749Found in file sv.c
2750
954c1994
GS
2751=item sv_setref_pv
2752
2753Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2754argument will be upgraded to an RV. That RV will be modified to point to
2755the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2756into the SV. The C<classname> argument indicates the package for the
2757blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2758will be returned and will have a reference count of 1.
2759
2760Do not use with other Perl types such as HV, AV, SV, CV, because those
2761objects will become corrupted by the pointer copy process.
2762
2763Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2764
2765 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
2766
497711e7
GS
2767=for hackers
2768Found in file sv.c
2769
954c1994
GS
2770=item sv_setref_pvn
2771
2772Copies a string into a new SV, optionally blessing the SV. The length of the
2773string must be specified with C<n>. The C<rv> argument will be upgraded to
2774an RV. That RV will be modified to point to the new SV. The C<classname>
2775argument indicates the package for the blessing. Set C<classname> to
2776C<Nullch> to avoid the blessing. The new SV will be returned and will have
2777a reference count of 1.
2778
2779Note that C<sv_setref_pv> copies the pointer while this copies the string.
2780
2781 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2782
497711e7
GS
2783=for hackers
2784Found in file sv.c
2785
954c1994
GS
2786=item sv_setsv
2787
2788Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2789The source SV may be destroyed if it is mortal. Does not handle 'set'
2790magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
2791C<sv_setsv_mg>.
2792
2793 void sv_setsv(SV* dsv, SV* ssv)
2794
497711e7
GS
2795=for hackers
2796Found in file sv.c
2797
954c1994
GS
2798=item sv_setsv_mg
2799
2800Like C<sv_setsv>, but also handles 'set' magic.
2801
2802 void sv_setsv_mg(SV *dstr, SV *sstr)
2803
497711e7
GS
2804=for hackers
2805Found in file sv.c
2806
954c1994
GS
2807=item sv_setuv
2808
2809Copies an unsigned integer into the given SV. Does not handle 'set' magic.
2810See C<sv_setuv_mg>.
2811
2812 void sv_setuv(SV* sv, UV num)
2813
497711e7
GS
2814=for hackers
2815Found in file sv.c
2816
954c1994
GS
2817=item sv_setuv_mg
2818
2819Like C<sv_setuv>, but also handles 'set' magic.
2820
2821 void sv_setuv_mg(SV *sv, UV u)
2822
497711e7
GS
2823=for hackers
2824Found in file sv.c
2825
954c1994
GS
2826=item sv_unref
2827
2828Unsets the RV status of the SV, and decrements the reference count of
2829whatever was being referenced by the RV. This can almost be thought of
2830as a reversal of C<newSVrv>. See C<SvROK_off>.
2831
2832 void sv_unref(SV* sv)
2833
497711e7
GS
2834=for hackers
2835Found in file sv.c
2836
954c1994
GS
2837=item sv_upgrade
2838
2839Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
2840C<svtype>.
2841
2842 bool sv_upgrade(SV* sv, U32 mt)
2843
497711e7
GS
2844=for hackers
2845Found in file sv.c
2846
954c1994
GS
2847=item sv_usepvn
2848
2849Tells an SV to use C<ptr> to find its string value. Normally the string is
2850stored inside the SV but sv_usepvn allows the SV to use an outside string.
2851The C<ptr> should point to memory that was allocated by C<malloc>. The
2852string length, C<len>, must be supplied. This function will realloc the
2853memory pointed to by C<ptr>, so that pointer should not be freed or used by
2854the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
2855See C<sv_usepvn_mg>.
2856
2857 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
2858
497711e7
GS
2859=for hackers
2860Found in file sv.c
2861
954c1994
GS
2862=item sv_usepvn_mg
2863
2864Like C<sv_usepvn>, but also handles 'set' magic.
2865
2866 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
2867
497711e7
GS
2868=for hackers
2869Found in file sv.c
2870
954c1994
GS
2871=item sv_vcatpvfn
2872
2873Processes its arguments like C<vsprintf> and appends the formatted output
2874to an SV. Uses an array of SVs if the C style variable argument list is
2875missing (NULL). When running with taint checks enabled, indicates via
2876C<maybe_tainted> if results are untrustworthy (often due to the use of
2877locales).
2878
2879 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2880
497711e7
GS
2881=for hackers
2882Found in file sv.c
2883
954c1994
GS
2884=item sv_vsetpvfn
2885
2886Works like C<vcatpvfn> but copies the text into the SV instead of
2887appending it.
2888
2889 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
2890
497711e7
GS
2891=for hackers
2892Found in file sv.c
2893
954c1994
GS
2894=item THIS
2895
2896Variable which is setup by C<xsubpp> to designate the object in a C++
2897XSUB. This is always the proper type for the C++ object. See C<CLASS> and
2898L<perlxs/"Using XS With C++">.
2899
2900 (whatever) THIS
2901
497711e7
GS
2902=for hackers
2903Found in file XSUB.h
2904
954c1994
GS
2905=item toLOWER
2906
2907Converts the specified character to lowercase.
2908
2909 char toLOWER(char ch)
2910
497711e7
GS
2911=for hackers
2912Found in file handy.h
2913
954c1994
GS
2914=item toUPPER
2915
2916Converts the specified character to uppercase.
2917
2918 char toUPPER(char ch)
2919
497711e7
GS
2920=for hackers
2921Found in file handy.h
2922
6662521e
GS
2923=item U8 *s
2924
2925Returns true if first C<len> bytes of the given string form valid a UTF8
2926string, false otherwise.
2927
2928 bool_utf8_string U8 *s(STRLEN len)
2929
2930=for hackers
2931Found in file utf8.c
2932
497711e7
GS
2933=item utf8_to_bytes
2934
2935Converts a string C<s> of length C<len> from UTF8 into ASCII encoding.
2936Unlike C<bytes_to_utf8>, this over-writes the original string.
6662521e 2937Returns zero on failure after converting as much as possible.
497711e7
GS
2938
2939 U8 * utf8_to_bytes(U8 *s, STRLEN len)
2940
2941=for hackers
2942Found in file utf8.c
2943
954c1994
GS
2944=item warn
2945
2946This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2947function the same way you use the C C<printf> function. See
2948C<croak>.
2949
2950 void warn(const char* pat, ...)
2951
497711e7
GS
2952=for hackers
2953Found in file util.c
2954
954c1994
GS
2955=item XPUSHi
2956
2957Push an integer onto the stack, extending the stack if necessary. Handles
2958'set' magic. See C<PUSHi>.
2959
2960 void XPUSHi(IV iv)
2961
497711e7
GS
2962=for hackers
2963Found in file pp.h
2964
954c1994
GS
2965=item XPUSHn
2966
2967Push a double onto the stack, extending the stack if necessary. Handles
2968'set' magic. See C<PUSHn>.
2969
2970 void XPUSHn(NV nv)
2971
497711e7
GS
2972=for hackers
2973Found in file pp.h
2974
954c1994
GS
2975=item XPUSHp
2976
2977Push a string onto the stack, extending the stack if necessary. The C<len>
2978indicates the length of the string. Handles 'set' magic. See
2979C<PUSHp>.
2980
2981 void XPUSHp(char* str, STRLEN len)
2982
497711e7
GS
2983=for hackers
2984Found in file pp.h
2985
954c1994
GS
2986=item XPUSHs
2987
2988Push an SV onto the stack, extending the stack if necessary. Does not
2989handle 'set' magic. See C<PUSHs>.
2990
2991 void XPUSHs(SV* sv)
2992
497711e7
GS
2993=for hackers
2994Found in file pp.h
2995
954c1994
GS
2996=item XPUSHu
2997
2998Push an unsigned integer onto the stack, extending the stack if necessary.
2999See C<PUSHu>.
3000
3001 void XPUSHu(UV uv)
3002
497711e7
GS
3003=for hackers
3004Found in file pp.h
3005
954c1994
GS
3006=item XS
3007
3008Macro to declare an XSUB and its C parameter list. This is handled by
3009C<xsubpp>.
3010
497711e7
GS
3011=for hackers
3012Found in file XSUB.h
3013
954c1994
GS
3014=item XSRETURN
3015
3016Return from XSUB, indicating number of items on the stack. This is usually
3017handled by C<xsubpp>.
3018
3019 void XSRETURN(int nitems)
3020
497711e7
GS
3021=for hackers
3022Found in file XSUB.h
3023
954c1994
GS
3024=item XSRETURN_EMPTY
3025
3026Return an empty list from an XSUB immediately.
3027
3028 XSRETURN_EMPTY;
3029
497711e7
GS
3030=for hackers
3031Found in file XSUB.h
3032
954c1994
GS
3033=item XSRETURN_IV
3034
3035Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3036
3037 void XSRETURN_IV(IV iv)
3038
497711e7
GS
3039=for hackers
3040Found in file XSUB.h
3041
954c1994
GS
3042=item XSRETURN_NO
3043
3044Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3045
3046 XSRETURN_NO;
3047
497711e7
GS
3048=for hackers
3049Found in file XSUB.h
3050
954c1994
GS
3051=item XSRETURN_NV
3052
3053Return an double from an XSUB immediately. Uses C<XST_mNV>.
3054
3055 void XSRETURN_NV(NV nv)
3056
497711e7
GS
3057=for hackers
3058Found in file XSUB.h
3059
954c1994
GS
3060=item XSRETURN_PV
3061
3062Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3063
3064 void XSRETURN_PV(char* str)
3065
497711e7
GS
3066=for hackers
3067Found in file XSUB.h
3068
954c1994
GS
3069=item XSRETURN_UNDEF
3070
3071Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3072
3073 XSRETURN_UNDEF;
3074
497711e7
GS
3075=for hackers
3076Found in file XSUB.h
3077
954c1994
GS
3078=item XSRETURN_YES
3079
3080Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3081
3082 XSRETURN_YES;
3083
497711e7
GS
3084=for hackers
3085Found in file XSUB.h
3086
954c1994
GS
3087=item XST_mIV
3088
3089Place an integer into the specified position C<pos> on the stack. The
3090value is stored in a new mortal SV.
3091
3092 void XST_mIV(int pos, IV iv)
3093
497711e7
GS
3094=for hackers
3095Found in file XSUB.h
3096
954c1994
GS
3097=item XST_mNO
3098
3099Place C<&PL_sv_no> into the specified position C<pos> on the
3100stack.
3101
3102 void XST_mNO(int pos)
3103
497711e7
GS
3104=for hackers
3105Found in file XSUB.h
3106
954c1994
GS
3107=item XST_mNV
3108
3109Place a double into the specified position C<pos> on the stack. The value
3110is stored in a new mortal SV.
3111
3112 void XST_mNV(int pos, NV nv)
3113
497711e7
GS
3114=for hackers
3115Found in file XSUB.h
3116
954c1994
GS
3117=item XST_mPV
3118
3119Place a copy of a string into the specified position C<pos> on the stack.
3120The value is stored in a new mortal SV.
3121
3122 void XST_mPV(int pos, char* str)
3123
497711e7
GS
3124=for hackers
3125Found in file XSUB.h
3126
954c1994
GS
3127=item XST_mUNDEF
3128
3129Place C<&PL_sv_undef> into the specified position C<pos> on the
3130stack.
3131
3132 void XST_mUNDEF(int pos)
3133
497711e7
GS
3134=for hackers
3135Found in file XSUB.h
3136
954c1994
GS
3137=item XST_mYES
3138
3139Place C<&PL_sv_yes> into the specified position C<pos> on the
3140stack.
3141
3142 void XST_mYES(int pos)
3143
497711e7
GS
3144=for hackers
3145Found in file XSUB.h
3146
954c1994
GS
3147=item XS_VERSION
3148
3149The version identifier for an XS module. This is usually
3150handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3151
497711e7
GS
3152=for hackers
3153Found in file XSUB.h
3154
954c1994
GS
3155=item XS_VERSION_BOOTCHECK
3156
3157Macro to verify that a PM module's $VERSION variable matches the XS
3158module's C<XS_VERSION> variable. This is usually handled automatically by
3159C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3160
3161 XS_VERSION_BOOTCHECK;
3162
497711e7
GS
3163=for hackers
3164Found in file XSUB.h
3165
954c1994
GS
3166=item Zero
3167
3168The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
3169destination, C<nitems> is the number of items, and C<type> is the type.
3170
3171 void Zero(void* dest, int nitems, type)
3172
497711e7
GS
3173=for hackers
3174Found in file handy.h
3175
954c1994
GS
3176=back
3177
3178=head1 AUTHORS
3179
3180Until May 1997, this document was maintained by Jeff Okamoto
3181<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3182
3183With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3184Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3185Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3186Stephen McCamant, and Gurusamy Sarathy.
3187
3188API Listing originally by Dean Roehrich <roehrich@cray.com>.
3189
3190Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3191
3192=head1 SEE ALSO
3193
3194perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3195