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