This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
This is 5.7.0.
[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
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
502accessible via @ISA and @UNIVERSAL.
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
507up caching info for this glob. Similarly for all the searched stashes.
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
GS
512the GV directly; instead, you should use the method's CV, which can be
513obtained from the GV with the C<GvCV> macro.
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
534already setup.
535
536The third parameter of C<gv_fetchmethod_autoload> determines whether
537AUTOLOAD lookup is performed if the given method is not present: non-zero
538means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
539Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
540with a non-zero C<autoload> parameter.
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
546created via a side effect to do this.
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
4929bf7b 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
747hash and returned to the caller. The C<klen> is the length of the key.
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
794dereferencing it to a C<SV*>.
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
812store it somewhere.
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
826currently only meaningful for hashes without tie magic.
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
905the call, and decrementing it if the function returned NULL.
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
925decrementing it if the function returned NULL.
926
96f1132b 927See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
928information on how to use this function on tied hashes.
929
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
1256SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
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
954c1994
GS
1265=item newSVrv
1266
1267Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
1268it will be upgraded to one. If C<classname> is non-null then the new SV will
1269be blessed in the specified package. The new SV is returned and its
1270reference count is 1.
1271
1272 SV* newSVrv(SV* rv, const char* classname)
1273
497711e7
GS
1274=for hackers
1275Found in file sv.c
1276
954c1994
GS
1277=item newSVsv
1278
1279Creates a new SV which is an exact duplicate of the original SV.
1280
1281 SV* newSVsv(SV* old)
1282
497711e7
GS
1283=for hackers
1284Found in file sv.c
1285
1a3327fb
JH
1286=item newSVuv
1287
1288Creates a new SV and copies an unsigned integer into it.
1289The reference count for the SV is set to 1.
1290
1291 SV* newSVuv(UV u)
1292
497711e7
GS
1293=for hackers
1294Found in file sv.c
1295
954c1994
GS
1296=item newXS
1297
1298Used by C<xsubpp> to hook up XSUBs as Perl subs.
1299
497711e7
GS
1300=for hackers
1301Found in file op.c
1302
954c1994
GS
1303=item newXSproto
1304
1305Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1306the subs.
1307
497711e7
GS
1308=for hackers
1309Found in file XSUB.h
1310
954c1994
GS
1311=item Newz
1312
1313The XSUB-writer's interface to the C C<malloc> function. The allocated
1314memory is zeroed with C<memzero>.
1315
1316 void Newz(int id, void* ptr, int nitems, type)
1317
497711e7
GS
1318=for hackers
1319Found in file handy.h
1320
954c1994
GS
1321=item Nullav
1322
1323Null AV pointer.
1324
497711e7
GS
1325=for hackers
1326Found in file av.h
1327
954c1994
GS
1328=item Nullch
1329
1330Null character pointer.
1331
497711e7
GS
1332=for hackers
1333Found in file handy.h
1334
954c1994
GS
1335=item Nullcv
1336
1337Null CV pointer.
1338
497711e7
GS
1339=for hackers
1340Found in file cv.h
1341
954c1994
GS
1342=item Nullhv
1343
1344Null HV pointer.
1345
497711e7
GS
1346=for hackers
1347Found in file hv.h
1348
954c1994
GS
1349=item Nullsv
1350
1351Null SV pointer.
1352
497711e7
GS
1353=for hackers
1354Found in file handy.h
1355
954c1994
GS
1356=item ORIGMARK
1357
1358The original stack mark for the XSUB. See C<dORIGMARK>.
1359
497711e7
GS
1360=for hackers
1361Found in file pp.h
1362
954c1994
GS
1363=item perl_alloc
1364
1365Allocates a new Perl interpreter. See L<perlembed>.
1366
1367 PerlInterpreter* perl_alloc()
1368
497711e7
GS
1369=for hackers
1370Found in file perl.c
1371
954c1994
GS
1372=item perl_construct
1373
1374Initializes a new Perl interpreter. See L<perlembed>.
1375
1376 void perl_construct(PerlInterpreter* interp)
1377
497711e7
GS
1378=for hackers
1379Found in file perl.c
1380
954c1994
GS
1381=item perl_destruct
1382
1383Shuts down a Perl interpreter. See L<perlembed>.
1384
1385 void perl_destruct(PerlInterpreter* interp)
1386
497711e7
GS
1387=for hackers
1388Found in file perl.c
1389
954c1994
GS
1390=item perl_free
1391
1392Releases a Perl interpreter. See L<perlembed>.
1393
1394 void perl_free(PerlInterpreter* interp)
1395
497711e7
GS
1396=for hackers
1397Found in file perl.c
1398
954c1994
GS
1399=item perl_parse
1400
1401Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1402
1403 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1404
497711e7
GS
1405=for hackers
1406Found in file perl.c
1407
954c1994
GS
1408=item perl_run
1409
1410Tells a Perl interpreter to run. See L<perlembed>.
1411
1412 int perl_run(PerlInterpreter* interp)
1413
497711e7
GS
1414=for hackers
1415Found in file perl.c
1416
954c1994
GS
1417=item PL_DBsingle
1418
1419When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1420boolean which indicates whether subs are being single-stepped.
1421Single-stepping is automatically turned on after every step. This is the C
1422variable which corresponds to Perl's $DB::single variable. See
1423C<PL_DBsub>.
1424
1425 SV * PL_DBsingle
1426
497711e7
GS
1427=for hackers
1428Found in file intrpvar.h
1429
954c1994
GS
1430=item PL_DBsub
1431
1432When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1433the SV which holds the name of the sub being debugged. This is the C
1434variable which corresponds to Perl's $DB::sub variable. See
1435C<PL_DBsingle>.
1436
1437 GV * PL_DBsub
1438
497711e7
GS
1439=for hackers
1440Found in file intrpvar.h
1441
954c1994
GS
1442=item PL_DBtrace
1443
1444Trace variable used when Perl is run in debugging mode, with the B<-d>
1445switch. This is the C variable which corresponds to Perl's $DB::trace
1446variable. See C<PL_DBsingle>.
1447
1448 SV * PL_DBtrace
1449
497711e7
GS
1450=for hackers
1451Found in file intrpvar.h
1452
954c1994
GS
1453=item PL_dowarn
1454
1455The C variable which corresponds to Perl's $^W warning variable.
1456
1457 bool PL_dowarn
1458
497711e7
GS
1459=for hackers
1460Found in file intrpvar.h
1461
954c1994
GS
1462=item PL_modglobal
1463
1464C<PL_modglobal> is a general purpose, interpreter global HV for use by
1465extensions that need to keep information on a per-interpreter basis.
1466In a pinch, it can also be used as a symbol table for extensions
1467to share data among each other. It is a good idea to use keys
1468prefixed by the package name of the extension that owns the data.
1469
1470 HV* PL_modglobal
1471
497711e7
GS
1472=for hackers
1473Found in file intrpvar.h
1474
954c1994
GS
1475=item PL_na
1476
1477A convenience variable which is typically used with C<SvPV> when one
1478doesn't care about the length of the string. It is usually more efficient
1479to either declare a local variable and use that instead or to use the
1480C<SvPV_nolen> macro.
1481
1482 STRLEN PL_na
1483
497711e7
GS
1484=for hackers
1485Found in file thrdvar.h
1486
954c1994
GS
1487=item PL_sv_no
1488
1489This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1490C<&PL_sv_no>.
1491
1492 SV PL_sv_no
1493
497711e7
GS
1494=for hackers
1495Found in file intrpvar.h
1496
954c1994
GS
1497=item PL_sv_undef
1498
1499This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1500
1501 SV PL_sv_undef
1502
497711e7
GS
1503=for hackers
1504Found in file intrpvar.h
1505
954c1994
GS
1506=item PL_sv_yes
1507
1508This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1509C<&PL_sv_yes>.
1510
1511 SV PL_sv_yes
1512
497711e7
GS
1513=for hackers
1514Found in file intrpvar.h
1515
954c1994
GS
1516=item POPi
1517
1518Pops an integer off the stack.
1519
1520 IV POPi
1521
497711e7
GS
1522=for hackers
1523Found in file pp.h
1524
954c1994
GS
1525=item POPl
1526
1527Pops a long off the stack.
1528
1529 long POPl
1530
497711e7
GS
1531=for hackers
1532Found in file pp.h
1533
954c1994
GS
1534=item POPn
1535
1536Pops a double off the stack.
1537
1538 NV POPn
1539
497711e7
GS
1540=for hackers
1541Found in file pp.h
1542
954c1994
GS
1543=item POPp
1544
1545Pops a string off the stack.
1546
1547 char* POPp
1548
497711e7
GS
1549=for hackers
1550Found in file pp.h
1551
954c1994
GS
1552=item POPs
1553
1554Pops an SV off the stack.
1555
1556 SV* POPs
1557
497711e7
GS
1558=for hackers
1559Found in file pp.h
1560
954c1994
GS
1561=item PUSHi
1562
1563Push an integer onto the stack. The stack must have room for this element.
1564Handles 'set' magic. See C<XPUSHi>.
1565
1566 void PUSHi(IV iv)
1567
497711e7
GS
1568=for hackers
1569Found in file pp.h
1570
954c1994
GS
1571=item PUSHMARK
1572
1573Opening bracket for arguments on a callback. See C<PUTBACK> and
1574L<perlcall>.
1575
1576 PUSHMARK;
1577
497711e7
GS
1578=for hackers
1579Found in file pp.h
1580
954c1994
GS
1581=item PUSHn
1582
1583Push a double onto the stack. The stack must have room for this element.
1584Handles 'set' magic. See C<XPUSHn>.
1585
1586 void PUSHn(NV nv)
1587
497711e7
GS
1588=for hackers
1589Found in file pp.h
1590
954c1994
GS
1591=item PUSHp
1592
1593Push a string onto the stack. The stack must have room for this element.
1594The C<len> indicates the length of the string. Handles 'set' magic. See
1595C<XPUSHp>.
1596
1597 void PUSHp(char* str, STRLEN len)
1598
497711e7
GS
1599=for hackers
1600Found in file pp.h
1601
954c1994
GS
1602=item PUSHs
1603
1604Push an SV onto the stack. The stack must have room for this element.
1605Does not handle 'set' magic. See C<XPUSHs>.
1606
1607 void PUSHs(SV* sv)
1608
497711e7
GS
1609=for hackers
1610Found in file pp.h
1611
954c1994
GS
1612=item PUSHu
1613
1614Push an unsigned integer onto the stack. The stack must have room for this
1615element. See C<XPUSHu>.
1616
1617 void PUSHu(UV uv)
1618
497711e7
GS
1619=for hackers
1620Found in file pp.h
1621
954c1994
GS
1622=item PUTBACK
1623
1624Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1625See C<PUSHMARK> and L<perlcall> for other uses.
1626
1627 PUTBACK;
1628
497711e7
GS
1629=for hackers
1630Found in file pp.h
1631
954c1994
GS
1632=item Renew
1633
1634The XSUB-writer's interface to the C C<realloc> function.
1635
1636 void Renew(void* ptr, int nitems, type)
1637
497711e7
GS
1638=for hackers
1639Found in file handy.h
1640
954c1994
GS
1641=item Renewc
1642
1643The XSUB-writer's interface to the C C<realloc> function, with
1644cast.
1645
1646 void Renewc(void* ptr, int nitems, type, cast)
1647
497711e7
GS
1648=for hackers
1649Found in file handy.h
1650
954c1994
GS
1651=item require_pv
1652
1653Tells Perl to C<require> a module.
1654
1655NOTE: the perl_ form of this function is deprecated.
1656
1657 void require_pv(const char* pv)
1658
497711e7
GS
1659=for hackers
1660Found in file perl.c
1661
954c1994
GS
1662=item RETVAL
1663
1664Variable which is setup by C<xsubpp> to hold the return value for an
1665XSUB. This is always the proper type for the XSUB. See
1666L<perlxs/"The RETVAL Variable">.
1667
1668 (whatever) RETVAL
1669
497711e7
GS
1670=for hackers
1671Found in file XSUB.h
1672
954c1994
GS
1673=item Safefree
1674
1675The XSUB-writer's interface to the C C<free> function.
1676
49b8b560 1677 void Safefree(void* ptr)
954c1994 1678
497711e7
GS
1679=for hackers
1680Found in file handy.h
1681
954c1994
GS
1682=item savepv
1683
1684Copy a string to a safe spot. This does not use an SV.
1685
1686 char* savepv(const char* sv)
1687
497711e7
GS
1688=for hackers
1689Found in file util.c
1690
954c1994
GS
1691=item savepvn
1692
1693Copy a string to a safe spot. The C<len> indicates number of bytes to
1694copy. This does not use an SV.
1695
1696 char* savepvn(const char* sv, I32 len)
1697
497711e7
GS
1698=for hackers
1699Found in file util.c
1700
954c1994
GS
1701=item SAVETMPS
1702
1703Opening bracket for temporaries on a callback. See C<FREETMPS> and
1704L<perlcall>.
1705
1706 SAVETMPS;
1707
497711e7
GS
1708=for hackers
1709Found in file scope.h
1710
954c1994
GS
1711=item SP
1712
1713Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1714C<SPAGAIN>.
1715
497711e7
GS
1716=for hackers
1717Found in file pp.h
1718
954c1994
GS
1719=item SPAGAIN
1720
1721Refetch the stack pointer. Used after a callback. See L<perlcall>.
1722
1723 SPAGAIN;
1724
497711e7
GS
1725=for hackers
1726Found in file pp.h
1727
954c1994
GS
1728=item ST
1729
1730Used to access elements on the XSUB's stack.
1731
1732 SV* ST(int ix)
1733
497711e7
GS
1734=for hackers
1735Found in file XSUB.h
1736
954c1994
GS
1737=item strEQ
1738
1739Test two strings to see if they are equal. Returns true or false.
1740
1741 bool strEQ(char* s1, char* s2)
1742
497711e7
GS
1743=for hackers
1744Found in file handy.h
1745
954c1994
GS
1746=item strGE
1747
1748Test two strings to see if the first, C<s1>, is greater than or equal to
1749the second, C<s2>. Returns true or false.
1750
1751 bool strGE(char* s1, char* s2)
1752
497711e7
GS
1753=for hackers
1754Found in file handy.h
1755
954c1994
GS
1756=item strGT
1757
1758Test two strings to see if the first, C<s1>, is greater than the second,
1759C<s2>. Returns true or false.
1760
1761 bool strGT(char* s1, char* s2)
1762
497711e7
GS
1763=for hackers
1764Found in file handy.h
1765
954c1994
GS
1766=item strLE
1767
1768Test two strings to see if the first, C<s1>, is less than or equal to the
1769second, C<s2>. Returns true or false.
1770
1771 bool strLE(char* s1, char* s2)
1772
497711e7
GS
1773=for hackers
1774Found in file handy.h
1775
954c1994
GS
1776=item strLT
1777
1778Test two strings to see if the first, C<s1>, is less than the second,
1779C<s2>. Returns true or false.
1780
1781 bool strLT(char* s1, char* s2)
1782
497711e7
GS
1783=for hackers
1784Found in file handy.h
1785
954c1994
GS
1786=item strNE
1787
1788Test two strings to see if they are different. Returns true or
1789false.
1790
1791 bool strNE(char* s1, char* s2)
1792
497711e7
GS
1793=for hackers
1794Found in file handy.h
1795
954c1994
GS
1796=item strnEQ
1797
1798Test two strings to see if they are equal. The C<len> parameter indicates
1799the number of bytes to compare. Returns true or false. (A wrapper for
1800C<strncmp>).
1801
1802 bool strnEQ(char* s1, char* s2, STRLEN len)
1803
497711e7
GS
1804=for hackers
1805Found in file handy.h
1806
954c1994
GS
1807=item strnNE
1808
1809Test two strings to see if they are different. The C<len> parameter
1810indicates the number of bytes to compare. Returns true or false. (A
1811wrapper for C<strncmp>).
1812
1813 bool strnNE(char* s1, char* s2, STRLEN len)
1814
497711e7
GS
1815=for hackers
1816Found in file handy.h
1817
954c1994
GS
1818=item StructCopy
1819
4375e838 1820This is an architecture-independent macro to copy one structure to another.
954c1994
GS
1821
1822 void StructCopy(type src, type dest, type)
1823
497711e7
GS
1824=for hackers
1825Found in file handy.h
1826
954c1994
GS
1827=item SvCUR
1828
1829Returns the length of the string which is in the SV. See C<SvLEN>.
1830
1831 STRLEN SvCUR(SV* sv)
1832
497711e7
GS
1833=for hackers
1834Found in file sv.h
1835
954c1994
GS
1836=item SvCUR_set
1837
1838Set the length of the string which is in the SV. See C<SvCUR>.
1839
1840 void SvCUR_set(SV* sv, STRLEN len)
1841
497711e7
GS
1842=for hackers
1843Found in file sv.h
1844
954c1994
GS
1845=item SvEND
1846
1847Returns a pointer to the last character in the string which is in the SV.
1848See C<SvCUR>. Access the character as *(SvEND(sv)).
1849
1850 char* SvEND(SV* sv)
1851
497711e7
GS
1852=for hackers
1853Found in file sv.h
1854
954c1994
GS
1855=item SvGETMAGIC
1856
1857Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1858argument more than once.
1859
1860 void SvGETMAGIC(SV* sv)
1861
497711e7
GS
1862=for hackers
1863Found in file sv.h
1864
954c1994
GS
1865=item SvGROW
1866
1867Expands the character buffer in the SV so that it has room for the
1868indicated number of bytes (remember to reserve space for an extra trailing
1869NUL character). Calls C<sv_grow> to perform the expansion if necessary.
1870Returns a pointer to the character buffer.
1871
1872 void SvGROW(SV* sv, STRLEN len)
1873
497711e7
GS
1874=for hackers
1875Found in file sv.h
1876
954c1994
GS
1877=item SvIOK
1878
1879Returns a boolean indicating whether the SV contains an integer.
1880
1881 bool SvIOK(SV* sv)
1882
497711e7
GS
1883=for hackers
1884Found in file sv.h
1885
954c1994
GS
1886=item SvIOKp
1887
1888Returns a boolean indicating whether the SV contains an integer. Checks
1889the B<private> setting. Use C<SvIOK>.
1890
1891 bool SvIOKp(SV* sv)
1892
497711e7
GS
1893=for hackers
1894Found in file sv.h
1895
954c1994
GS
1896=item SvIOK_off
1897
1898Unsets the IV status of an SV.
1899
1900 void SvIOK_off(SV* sv)
1901
497711e7
GS
1902=for hackers
1903Found in file sv.h
1904
954c1994
GS
1905=item SvIOK_on
1906
1907Tells an SV that it is an integer.
1908
1909 void SvIOK_on(SV* sv)
1910
497711e7
GS
1911=for hackers
1912Found in file sv.h
1913
954c1994
GS
1914=item SvIOK_only
1915
1916Tells an SV that it is an integer and disables all other OK bits.
1917
1918 void SvIOK_only(SV* sv)
1919
497711e7
GS
1920=for hackers
1921Found in file sv.h
1922
954c1994
GS
1923=item SvIV
1924
1925Coerces the given SV to an integer and returns it.
1926
1927 IV SvIV(SV* sv)
1928
497711e7
GS
1929=for hackers
1930Found in file sv.h
1931
954c1994
GS
1932=item SvIVX
1933
1934Returns the integer which is stored in the SV, assuming SvIOK is
1935true.
1936
1937 IV SvIVX(SV* sv)
1938
497711e7
GS
1939=for hackers
1940Found in file sv.h
1941
954c1994
GS
1942=item SvLEN
1943
91e74348
JH
1944Returns the size of the string buffer in the SV, not including any part
1945attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
1946
1947 STRLEN SvLEN(SV* sv)
1948
497711e7
GS
1949=for hackers
1950Found in file sv.h
1951
954c1994
GS
1952=item SvNIOK
1953
1954Returns a boolean indicating whether the SV contains a number, integer or
1955double.
1956
1957 bool SvNIOK(SV* sv)
1958
497711e7
GS
1959=for hackers
1960Found in file sv.h
1961
954c1994
GS
1962=item SvNIOKp
1963
1964Returns a boolean indicating whether the SV contains a number, integer or
1965double. Checks the B<private> setting. Use C<SvNIOK>.
1966
1967 bool SvNIOKp(SV* sv)
1968
497711e7
GS
1969=for hackers
1970Found in file sv.h
1971
954c1994
GS
1972=item SvNIOK_off
1973
1974Unsets the NV/IV status of an SV.
1975
1976 void SvNIOK_off(SV* sv)
1977
497711e7
GS
1978=for hackers
1979Found in file sv.h
1980
954c1994
GS
1981=item SvNOK
1982
1983Returns a boolean indicating whether the SV contains a double.
1984
1985 bool SvNOK(SV* sv)
1986
497711e7
GS
1987=for hackers
1988Found in file sv.h
1989
954c1994
GS
1990=item SvNOKp
1991
1992Returns a boolean indicating whether the SV contains a double. Checks the
1993B<private> setting. Use C<SvNOK>.
1994
1995 bool SvNOKp(SV* sv)
1996
497711e7
GS
1997=for hackers
1998Found in file sv.h
1999
954c1994
GS
2000=item SvNOK_off
2001
2002Unsets the NV status of an SV.
2003
2004 void SvNOK_off(SV* sv)
2005
497711e7
GS
2006=for hackers
2007Found in file sv.h
2008
954c1994
GS
2009=item SvNOK_on
2010
2011Tells an SV that it is a double.
2012
2013 void SvNOK_on(SV* sv)
2014
497711e7
GS
2015=for hackers
2016Found in file sv.h
2017
954c1994
GS
2018=item SvNOK_only
2019
2020Tells an SV that it is a double and disables all other OK bits.
2021
2022 void SvNOK_only(SV* sv)
2023
497711e7
GS
2024=for hackers
2025Found in file sv.h
2026
954c1994
GS
2027=item SvNV
2028
2029Coerce the given SV to a double and return it.
2030
2031 NV SvNV(SV* sv)
2032
497711e7
GS
2033=for hackers
2034Found in file sv.h
2035
954c1994
GS
2036=item SvNVX
2037
2038Returns the double which is stored in the SV, assuming SvNOK is
2039true.
2040
2041 NV SvNVX(SV* sv)
2042
497711e7
GS
2043=for hackers
2044Found in file sv.h
2045
954c1994
GS
2046=item SvOK
2047
2048Returns a boolean indicating whether the value is an SV.
2049
2050 bool SvOK(SV* sv)
2051
497711e7
GS
2052=for hackers
2053Found in file sv.h
2054
954c1994
GS
2055=item SvOOK
2056
2057Returns a boolean indicating whether the SvIVX is a valid offset value for
2058the SvPVX. This hack is used internally to speed up removal of characters
2059from the beginning of a SvPV. When SvOOK is true, then the start of the
2060allocated string buffer is really (SvPVX - SvIVX).
2061
2062 bool SvOOK(SV* sv)
2063
497711e7
GS
2064=for hackers
2065Found in file sv.h
2066
954c1994
GS
2067=item SvPOK
2068
2069Returns a boolean indicating whether the SV contains a character
2070string.
2071
2072 bool SvPOK(SV* sv)
2073
497711e7
GS
2074=for hackers
2075Found in file sv.h
2076
954c1994
GS
2077=item SvPOKp
2078
2079Returns a boolean indicating whether the SV contains a character string.
2080Checks the B<private> setting. Use C<SvPOK>.
2081
2082 bool SvPOKp(SV* sv)
2083
497711e7
GS
2084=for hackers
2085Found in file sv.h
2086
954c1994
GS
2087=item SvPOK_off
2088
2089Unsets the PV status of an SV.
2090
2091 void SvPOK_off(SV* sv)
2092
497711e7
GS
2093=for hackers
2094Found in file sv.h
2095
954c1994
GS
2096=item SvPOK_on
2097
2098Tells an SV that it is a string.
2099
2100 void SvPOK_on(SV* sv)
2101
497711e7
GS
2102=for hackers
2103Found in file sv.h
2104
954c1994
GS
2105=item SvPOK_only
2106
2107Tells an SV that it is a string and disables all other OK bits.
2108
2109 void SvPOK_only(SV* sv)
2110
497711e7
GS
2111=for hackers
2112Found in file sv.h
2113
954c1994
GS
2114=item SvPV
2115
2116Returns a pointer to the string in the SV, or a stringified form of the SV
2117if the SV does not contain a string. Handles 'get' magic.
2118
2119 char* SvPV(SV* sv, STRLEN len)
2120
497711e7
GS
2121=for hackers
2122Found in file sv.h
2123
954c1994
GS
2124=item SvPVX
2125
2126Returns a pointer to the string in the SV. The SV must contain a
2127string.
2128
2129 char* SvPVX(SV* sv)
2130
497711e7
GS
2131=for hackers
2132Found in file sv.h
2133
954c1994
GS
2134=item SvPV_force
2135
2136Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2137force if you are going to update the SvPVX directly.
2138
2139 char* SvPV_force(SV* sv, STRLEN len)
2140
497711e7
GS
2141=for hackers
2142Found in file sv.h
2143
954c1994
GS
2144=item SvPV_nolen
2145
2146Returns a pointer to the string in the SV, or a stringified form of the SV
2147if the SV does not contain a string. Handles 'get' magic.
2148
2149 char* SvPV_nolen(SV* sv)
2150
497711e7
GS
2151=for hackers
2152Found in file sv.h
2153
954c1994
GS
2154=item SvREFCNT
2155
2156Returns the value of the object's reference count.
2157
2158 U32 SvREFCNT(SV* sv)
2159
497711e7
GS
2160=for hackers
2161Found in file sv.h
2162
954c1994
GS
2163=item SvREFCNT_dec
2164
2165Decrements the reference count of the given SV.
2166
2167 void SvREFCNT_dec(SV* sv)
2168
497711e7
GS
2169=for hackers
2170Found in file sv.h
2171
954c1994
GS
2172=item SvREFCNT_inc
2173
2174Increments the reference count of the given SV.
2175
2176 SV* SvREFCNT_inc(SV* sv)
2177
497711e7
GS
2178=for hackers
2179Found in file sv.h
2180
954c1994
GS
2181=item SvROK
2182
2183Tests if the SV is an RV.
2184
2185 bool SvROK(SV* sv)
2186
497711e7
GS
2187=for hackers
2188Found in file sv.h
2189
954c1994
GS
2190=item SvROK_off
2191
2192Unsets the RV status of an SV.
2193
2194 void SvROK_off(SV* sv)
2195
497711e7
GS
2196=for hackers
2197Found in file sv.h
2198
954c1994
GS
2199=item SvROK_on
2200
2201Tells an SV that it is an RV.
2202
2203 void SvROK_on(SV* sv)
2204
497711e7
GS
2205=for hackers
2206Found in file sv.h
2207
954c1994
GS
2208=item SvRV
2209
2210Dereferences an RV to return the SV.
2211
2212 SV* SvRV(SV* sv)
2213
497711e7
GS
2214=for hackers
2215Found in file sv.h
2216
954c1994
GS
2217=item SvSETMAGIC
2218
2219Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2220argument more than once.
2221
2222 void SvSETMAGIC(SV* sv)
2223
497711e7
GS
2224=for hackers
2225Found in file sv.h
2226
954c1994
GS
2227=item SvSetSV
2228
2229Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2230more than once.
2231
2232 void SvSetSV(SV* dsb, SV* ssv)
2233
497711e7
GS
2234=for hackers
2235Found in file sv.h
2236
954c1994
GS
2237=item SvSetSV_nosteal
2238
2239Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2240ssv. May evaluate arguments more than once.
2241
2242 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2243
497711e7
GS
2244=for hackers
2245Found in file sv.h
2246
954c1994
GS
2247=item SvSTASH
2248
2249Returns the stash of the SV.
2250
2251 HV* SvSTASH(SV* sv)
2252
497711e7
GS
2253=for hackers
2254Found in file sv.h
2255
954c1994
GS
2256=item SvTAINT
2257
2258Taints an SV if tainting is enabled
2259
2260 void SvTAINT(SV* sv)
2261
497711e7
GS
2262=for hackers
2263Found in file sv.h
2264
954c1994
GS
2265=item SvTAINTED
2266
2267Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2268not.
2269
2270 bool SvTAINTED(SV* sv)
2271
497711e7
GS
2272=for hackers
2273Found in file sv.h
2274
954c1994
GS
2275=item SvTAINTED_off
2276
2277Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2278some of Perl's fundamental security features. XS module authors should not
2279use this function unless they fully understand all the implications of
2280unconditionally untainting the value. Untainting should be done in the
2281standard perl fashion, via a carefully crafted regexp, rather than directly
2282untainting variables.
2283
2284 void SvTAINTED_off(SV* sv)
2285
497711e7
GS
2286=for hackers
2287Found in file sv.h
2288
954c1994
GS
2289=item SvTAINTED_on
2290
2291Marks an SV as tainted.
2292
2293 void SvTAINTED_on(SV* sv)
2294
497711e7
GS
2295=for hackers
2296Found in file sv.h
2297
954c1994
GS
2298=item SvTRUE
2299
2300Returns a boolean indicating whether Perl would evaluate the SV as true or
2301false, defined or undefined. Does not handle 'get' magic.
2302
2303 bool SvTRUE(SV* sv)
2304
497711e7
GS
2305=for hackers
2306Found in file sv.h
2307
c461cf8f 2308=item svtype
6662521e 2309
c461cf8f
JH
2310An enum of flags for Perl types. These are found in the file B<sv.h>
2311in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
34f7a5fe 2312
497711e7
GS
2313=for hackers
2314Found in file sv.h
2315
c461cf8f 2316=item SvTYPE
954c1994 2317
c461cf8f
JH
2318Returns the type of the SV. See C<svtype>.
2319
2320 svtype SvTYPE(SV* sv)
954c1994 2321
497711e7
GS
2322=for hackers
2323Found in file sv.h
2324
954c1994
GS
2325=item SVt_IV
2326
2327Integer type flag for scalars. See C<svtype>.
2328
497711e7
GS
2329=for hackers
2330Found in file sv.h
2331
954c1994
GS
2332=item SVt_NV
2333
2334Double type flag for scalars. See C<svtype>.
2335
497711e7
GS
2336=for hackers
2337Found in file sv.h
2338
954c1994
GS
2339=item SVt_PV
2340
2341Pointer type flag for scalars. See C<svtype>.
2342
497711e7
GS
2343=for hackers
2344Found in file sv.h
2345
954c1994
GS
2346=item SVt_PVAV
2347
2348Type flag for arrays. See C<svtype>.
2349
497711e7
GS
2350=for hackers
2351Found in file sv.h
2352
954c1994
GS
2353=item SVt_PVCV
2354
2355Type flag for code refs. See C<svtype>.
2356
497711e7
GS
2357=for hackers
2358Found in file sv.h
2359
954c1994
GS
2360=item SVt_PVHV
2361
2362Type flag for hashes. See C<svtype>.
2363
497711e7
GS
2364=for hackers
2365Found in file sv.h
2366
954c1994
GS
2367=item SVt_PVMG
2368
2369Type flag for blessed scalars. See C<svtype>.
2370
497711e7
GS
2371=for hackers
2372Found in file sv.h
2373
954c1994
GS
2374=item SvUPGRADE
2375
2376Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
2377perform the upgrade if necessary. See C<svtype>.
2378
2379 void SvUPGRADE(SV* sv, svtype type)
2380
497711e7
GS
2381=for hackers
2382Found in file sv.h
2383
954c1994
GS
2384=item SvUV
2385
2386Coerces the given SV to an unsigned integer and returns it.
2387
2388 UV SvUV(SV* sv)
2389
497711e7
GS
2390=for hackers
2391Found in file sv.h
2392
954c1994
GS
2393=item SvUVX
2394
2395Returns the unsigned integer which is stored in the SV, assuming SvIOK is
2396true.
2397
2398 UV SvUVX(SV* sv)
2399
497711e7
GS
2400=for hackers
2401Found in file sv.h
2402
954c1994
GS
2403=item sv_2mortal
2404
2405Marks an SV as mortal. The SV will be destroyed when the current context
2406ends.
2407
2408 SV* sv_2mortal(SV* sv)
2409
497711e7
GS
2410=for hackers
2411Found in file sv.c
2412
954c1994
GS
2413=item sv_bless
2414
2415Blesses an SV into a specified package. The SV must be an RV. The package
2416must be designated by its stash (see C<gv_stashpv()>). The reference count
2417of the SV is unaffected.
2418
2419 SV* sv_bless(SV* sv, HV* stash)
2420
497711e7
GS
2421=for hackers
2422Found in file sv.c
2423
954c1994
GS
2424=item sv_catpv
2425
2426Concatenates the string onto the end of the string which is in the SV.
2427Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
2428
2429 void sv_catpv(SV* sv, const char* ptr)
2430
497711e7
GS
2431=for hackers
2432Found in file sv.c
2433
954c1994
GS
2434=item sv_catpvf
2435
2436Processes its arguments like C<sprintf> and appends the formatted output
2437to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
2438typically be called after calling this function to handle 'set' magic.
2439
2440 void sv_catpvf(SV* sv, const char* pat, ...)
2441
497711e7
GS
2442=for hackers
2443Found in file sv.c
2444
954c1994
GS
2445=item sv_catpvf_mg
2446
2447Like C<sv_catpvf>, but also handles 'set' magic.
2448
2449 void sv_catpvf_mg(SV *sv, const char* pat, ...)
2450
497711e7
GS
2451=for hackers
2452Found in file sv.c
2453
954c1994
GS
2454=item sv_catpvn
2455
2456Concatenates the string onto the end of the string which is in the SV. The
2457C<len> indicates number of bytes to copy. Handles 'get' magic, but not
2458'set' magic. See C<sv_catpvn_mg>.
2459
2460 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
2461
497711e7
GS
2462=for hackers
2463Found in file sv.c
2464
954c1994
GS
2465=item sv_catpvn_mg
2466
2467Like C<sv_catpvn>, but also handles 'set' magic.
2468
2469 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
2470
497711e7
GS
2471=for hackers
2472Found in file sv.c
2473
954c1994
GS
2474=item sv_catpv_mg
2475
2476Like C<sv_catpv>, but also handles 'set' magic.
2477
2478 void sv_catpv_mg(SV *sv, const char *ptr)
2479
497711e7
GS
2480=for hackers
2481Found in file sv.c
2482
954c1994
GS
2483=item sv_catsv
2484
2485Concatenates the string from SV C<ssv> onto the end of the string in SV
2486C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
2487
2488 void sv_catsv(SV* dsv, SV* ssv)
2489
497711e7
GS
2490=for hackers
2491Found in file sv.c
2492
954c1994
GS
2493=item sv_catsv_mg
2494
2495Like C<sv_catsv>, but also handles 'set' magic.
2496
2497 void sv_catsv_mg(SV *dstr, SV *sstr)
2498
497711e7
GS
2499=for hackers
2500Found in file sv.c
2501
954c1994
GS
2502=item sv_chop
2503
2504Efficient removal of characters from the beginning of the string buffer.
2505SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
2506the string buffer. The C<ptr> becomes the first character of the adjusted
2507string.
2508
2509 void sv_chop(SV* sv, char* ptr)
2510
497711e7
GS
2511=for hackers
2512Found in file sv.c
2513
c461cf8f
JH
2514=item sv_clear
2515
2516Clear an SV, making it empty. Does not free the memory used by the SV
2517itself.
2518
2519 void sv_clear(SV* sv)
2520
2521=for hackers
2522Found in file sv.c
2523
954c1994
GS
2524=item sv_cmp
2525
2526Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2527string in C<sv1> is less than, equal to, or greater than the string in
2528C<sv2>.
2529
2530 I32 sv_cmp(SV* sv1, SV* sv2)
2531
497711e7
GS
2532=for hackers
2533Found in file sv.c
2534
c461cf8f
JH
2535=item sv_cmp_locale
2536
2537Compares the strings in two SVs in a locale-aware manner. See
2538L</sv_cmp_locale>
2539
2540 I32 sv_cmp_locale(SV* sv1, SV* sv2)
2541
2542=for hackers
2543Found in file sv.c
2544
954c1994
GS
2545=item sv_dec
2546
2547Auto-decrement of the value in the SV.
2548
2549 void sv_dec(SV* sv)
2550
497711e7
GS
2551=for hackers
2552Found in file sv.c
2553
954c1994
GS
2554=item sv_derived_from
2555
2556Returns a boolean indicating whether the SV is derived from the specified
2557class. This is the function that implements C<UNIVERSAL::isa>. It works
2558for class names as well as for objects.
2559
2560 bool sv_derived_from(SV* sv, const char* name)
2561
497711e7
GS
2562=for hackers
2563Found in file universal.c
2564
954c1994
GS
2565=item sv_eq
2566
2567Returns a boolean indicating whether the strings in the two SVs are
2568identical.
2569
2570 I32 sv_eq(SV* sv1, SV* sv2)
2571
497711e7
GS
2572=for hackers
2573Found in file sv.c
2574
c461cf8f
JH
2575=item sv_free
2576
2577Free the memory used by an SV.
2578
2579 void sv_free(SV* sv)
2580
2581=for hackers
2582Found in file sv.c
2583
2584=item sv_gets
2585
2586Get a line from the filehandle and store it into the SV, optionally
2587appending to the currently-stored string.
2588
2589 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
2590
2591=for hackers
2592Found in file sv.c
2593
954c1994
GS
2594=item sv_grow
2595
2596Expands the character buffer in the SV. This will use C<sv_unref> and will
2597upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2598Use C<SvGROW>.
2599
2600 char* sv_grow(SV* sv, STRLEN newlen)
2601
497711e7
GS
2602=for hackers
2603Found in file sv.c
2604
954c1994
GS
2605=item sv_inc
2606
2607Auto-increment of the value in the SV.
2608
2609 void sv_inc(SV* sv)
2610
497711e7
GS
2611=for hackers
2612Found in file sv.c
2613
954c1994
GS
2614=item sv_insert
2615
2616Inserts a string at the specified offset/length within the SV. Similar to
2617the Perl substr() function.
2618
2619 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2620
497711e7
GS
2621=for hackers
2622Found in file sv.c
2623
954c1994
GS
2624=item sv_isa
2625
2626Returns a boolean indicating whether the SV is blessed into the specified
2627class. This does not check for subtypes; use C<sv_derived_from> to verify
2628an inheritance relationship.
2629
2630 int sv_isa(SV* sv, const char* name)
2631
497711e7
GS
2632=for hackers
2633Found in file sv.c
2634
954c1994
GS
2635=item sv_isobject
2636
2637Returns a boolean indicating whether the SV is an RV pointing to a blessed
2638object. If the SV is not an RV, or if the object is not blessed, then this
2639will return false.
2640
2641 int sv_isobject(SV* sv)
2642
497711e7
GS
2643=for hackers
2644Found in file sv.c
2645
954c1994
GS
2646=item sv_len
2647
2648Returns the length of the string in the SV. See also C<SvCUR>.
2649
2650 STRLEN sv_len(SV* sv)
2651
497711e7
GS
2652=for hackers
2653Found in file sv.c
2654
c461cf8f
JH
2655=item sv_len_utf8
2656
2657Returns the number of characters in the string in an SV, counting wide
2658UTF8 bytes as a single character.
2659
2660 STRLEN sv_len_utf8(SV* sv)
2661
2662=for hackers
2663Found in file sv.c
2664
954c1994
GS
2665=item sv_magic
2666
2667Adds magic to an SV.
2668
2669 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2670
497711e7
GS
2671=for hackers
2672Found in file sv.c
2673
954c1994
GS
2674=item sv_mortalcopy
2675
2676Creates a new SV which is a copy of the original SV. The new SV is marked
2677as mortal.
2678
2679 SV* sv_mortalcopy(SV* oldsv)
2680
497711e7
GS
2681=for hackers
2682Found in file sv.c
2683
954c1994
GS
2684=item sv_newmortal
2685
2686Creates a new SV which is mortal. The reference count of the SV is set to 1.
2687
2688 SV* sv_newmortal()
2689
497711e7
GS
2690=for hackers
2691Found in file sv.c
2692
c461cf8f
JH
2693=item sv_pvn_force
2694
2695Get a sensible string out of the SV somehow.
2696
2697 char* sv_pvn_force(SV* sv, STRLEN* lp)
2698
2699=for hackers
2700Found in file sv.c
2701
2702=item sv_pvutf8n_force
2703
2704Get a sensible UTF8-encoded string out of the SV somehow. See
2705L</sv_pvn_force>.
2706
2707 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
2708
2709=for hackers
2710Found in file sv.c
2711
2712=item sv_reftype
2713
2714Returns a string describing what the SV is a reference to.
2715
2716 char* sv_reftype(SV* sv, int ob)
2717
2718=for hackers
2719Found in file sv.c
2720
2721=item sv_replace
2722
2723Make the first argument a copy of the second, then delete the original.
2724
2725 void sv_replace(SV* sv, SV* nsv)
2726
2727=for hackers
2728Found in file sv.c
2729
2730=item sv_rvweaken
2731
2732Weaken a reference.
2733
2734 SV* sv_rvweaken(SV *sv)
2735
2736=for hackers
2737Found in file sv.c
2738
954c1994
GS
2739=item sv_setiv
2740
2741Copies an integer into the given SV. Does not handle 'set' magic. See
2742C<sv_setiv_mg>.
2743
2744 void sv_setiv(SV* sv, IV num)
2745
497711e7
GS
2746=for hackers
2747Found in file sv.c
2748
954c1994
GS
2749=item sv_setiv_mg
2750
2751Like C<sv_setiv>, but also handles 'set' magic.
2752
2753 void sv_setiv_mg(SV *sv, IV i)
2754
497711e7
GS
2755=for hackers
2756Found in file sv.c
2757
954c1994
GS
2758=item sv_setnv
2759
2760Copies a double into the given SV. Does not handle 'set' magic. See
2761C<sv_setnv_mg>.
2762
2763 void sv_setnv(SV* sv, NV num)
2764
497711e7
GS
2765=for hackers
2766Found in file sv.c
2767
954c1994
GS
2768=item sv_setnv_mg
2769
2770Like C<sv_setnv>, but also handles 'set' magic.
2771
2772 void sv_setnv_mg(SV *sv, NV num)
2773
497711e7
GS
2774=for hackers
2775Found in file sv.c
2776
954c1994
GS
2777=item sv_setpv
2778
2779Copies a string into an SV. The string must be null-terminated. Does not
2780handle 'set' magic. See C<sv_setpv_mg>.
2781
2782 void sv_setpv(SV* sv, const char* ptr)
2783
497711e7
GS
2784=for hackers
2785Found in file sv.c
2786
954c1994
GS
2787=item sv_setpvf
2788
2789Processes its arguments like C<sprintf> and sets an SV to the formatted
2790output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
2791
2792 void sv_setpvf(SV* sv, const char* pat, ...)
2793
497711e7
GS
2794=for hackers
2795Found in file sv.c
2796
954c1994
GS
2797=item sv_setpvf_mg
2798
2799Like C<sv_setpvf>, but also handles 'set' magic.
2800
2801 void sv_setpvf_mg(SV *sv, const char* pat, ...)
2802
497711e7
GS
2803=for hackers
2804Found in file sv.c
2805
954c1994
GS
2806=item sv_setpviv
2807
2808Copies an integer into the given SV, also updating its string value.
2809Does not handle 'set' magic. See C<sv_setpviv_mg>.
2810
2811 void sv_setpviv(SV* sv, IV num)
2812
497711e7
GS
2813=for hackers
2814Found in file sv.c
2815
954c1994
GS
2816=item sv_setpviv_mg
2817
2818Like C<sv_setpviv>, but also handles 'set' magic.
2819
2820 void sv_setpviv_mg(SV *sv, IV iv)
2821
497711e7
GS
2822=for hackers
2823Found in file sv.c
2824
954c1994
GS
2825=item sv_setpvn
2826
2827Copies a string into an SV. The C<len> parameter indicates the number of
2828bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
2829
2830 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2831
497711e7
GS
2832=for hackers
2833Found in file sv.c
2834
954c1994
GS
2835=item sv_setpvn_mg
2836
2837Like C<sv_setpvn>, but also handles 'set' magic.
2838
2839 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2840
497711e7
GS
2841=for hackers
2842Found in file sv.c
2843
954c1994
GS
2844=item sv_setpv_mg
2845
2846Like C<sv_setpv>, but also handles 'set' magic.
2847
2848 void sv_setpv_mg(SV *sv, const char *ptr)
2849
497711e7
GS
2850=for hackers
2851Found in file sv.c
2852
954c1994
GS
2853=item sv_setref_iv
2854
2855Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2856argument will be upgraded to an RV. That RV will be modified to point to
2857the new SV. The C<classname> argument indicates the package for the
2858blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2859will be returned and will have a reference count of 1.
2860
2861 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
2862
497711e7
GS
2863=for hackers
2864Found in file sv.c
2865
954c1994
GS
2866=item sv_setref_nv
2867
2868Copies a double 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_nv(SV* rv, const char* classname, NV nv)
2875
497711e7
GS
2876=for hackers
2877Found in file sv.c
2878
954c1994
GS
2879=item sv_setref_pv
2880
2881Copies a pointer 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. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2884into the SV. The C<classname> argument indicates the package for the
2885blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2886will be returned and will have a reference count of 1.
2887
2888Do not use with other Perl types such as HV, AV, SV, CV, because those
2889objects will become corrupted by the pointer copy process.
2890
2891Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2892
2893 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
2894
497711e7
GS
2895=for hackers
2896Found in file sv.c
2897
954c1994
GS
2898=item sv_setref_pvn
2899
2900Copies a string into a new SV, optionally blessing the SV. The length of the
2901string must be specified with C<n>. The C<rv> argument will be upgraded to
2902an RV. That RV will be modified to point to the new SV. The C<classname>
2903argument indicates the package for the blessing. Set C<classname> to
2904C<Nullch> to avoid the blessing. The new SV will be returned and will have
2905a reference count of 1.
2906
2907Note that C<sv_setref_pv> copies the pointer while this copies the string.
2908
2909 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2910
497711e7
GS
2911=for hackers
2912Found in file sv.c
2913
954c1994
GS
2914=item sv_setsv
2915
2916Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2917The source SV may be destroyed if it is mortal. Does not handle 'set'
2918magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
2919C<sv_setsv_mg>.
2920
2921 void sv_setsv(SV* dsv, SV* ssv)
2922
497711e7
GS
2923=for hackers
2924Found in file sv.c
2925
954c1994
GS
2926=item sv_setsv_mg
2927
2928Like C<sv_setsv>, but also handles 'set' magic.
2929
2930 void sv_setsv_mg(SV *dstr, SV *sstr)
2931
497711e7
GS
2932=for hackers
2933Found in file sv.c
2934
954c1994
GS
2935=item sv_setuv
2936
2937Copies an unsigned integer into the given SV. Does not handle 'set' magic.
2938See C<sv_setuv_mg>.
2939
2940 void sv_setuv(SV* sv, UV num)
2941
497711e7
GS
2942=for hackers
2943Found in file sv.c
2944
954c1994
GS
2945=item sv_setuv_mg
2946
2947Like C<sv_setuv>, but also handles 'set' magic.
2948
2949 void sv_setuv_mg(SV *sv, UV u)
2950
497711e7
GS
2951=for hackers
2952Found in file sv.c
2953
c461cf8f
JH
2954=item sv_true
2955
2956Returns true if the SV has a true value by Perl's rules.
2957
2958 I32 sv_true(SV *sv)
2959
2960=for hackers
2961Found in file sv.c
2962
2963=item sv_unmagic
2964
2965Removes magic from an SV.
2966
2967 int sv_unmagic(SV* sv, int type)
2968
2969=for hackers
2970Found in file sv.c
2971
954c1994
GS
2972=item sv_unref
2973
2974Unsets the RV status of the SV, and decrements the reference count of
2975whatever was being referenced by the RV. This can almost be thought of
2976as a reversal of C<newSVrv>. See C<SvROK_off>.
2977
2978 void sv_unref(SV* sv)
2979
497711e7
GS
2980=for hackers
2981Found in file sv.c
2982
954c1994
GS
2983=item sv_upgrade
2984
2985Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
2986C<svtype>.
2987
2988 bool sv_upgrade(SV* sv, U32 mt)
2989
497711e7
GS
2990=for hackers
2991Found in file sv.c
2992
954c1994
GS
2993=item sv_usepvn
2994
2995Tells an SV to use C<ptr> to find its string value. Normally the string is
2996stored inside the SV but sv_usepvn allows the SV to use an outside string.
2997The C<ptr> should point to memory that was allocated by C<malloc>. The
2998string length, C<len>, must be supplied. This function will realloc the
2999memory pointed to by C<ptr>, so that pointer should not be freed or used by
3000the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
3001See C<sv_usepvn_mg>.
3002
3003 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
3004
497711e7
GS
3005=for hackers
3006Found in file sv.c
3007
954c1994
GS
3008=item sv_usepvn_mg
3009
3010Like C<sv_usepvn>, but also handles 'set' magic.
3011
3012 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3013
497711e7
GS
3014=for hackers
3015Found in file sv.c
3016
c461cf8f
JH
3017=item sv_utf8_downgrade
3018
3019Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3020This may not be possible if the PV contains non-byte encoding characters;
3021if this is the case, either returns false or, if C<fail_ok> is not
3022true, croaks.
3023
3024NOTE: this function is experimental and may change or be
3025removed without notice.
3026
3027 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
3028
3029=for hackers
3030Found in file sv.c
3031
3032=item sv_utf8_encode
3033
3034Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
3035flag so that it looks like bytes again. Nothing calls this.
3036
3037NOTE: this function is experimental and may change or be
3038removed without notice.
3039
3040 void sv_utf8_encode(SV *sv)
3041
3042=for hackers
3043Found in file sv.c
3044
3045=item sv_utf8_upgrade
3046
3047Convert the PV of an SV to its UTF8-encoded form.
3048
3049 void sv_utf8_upgrade(SV *sv)
3050
3051=for hackers
3052Found in file sv.c
3053
954c1994
GS
3054=item sv_vcatpvfn
3055
3056Processes its arguments like C<vsprintf> and appends the formatted output
3057to an SV. Uses an array of SVs if the C style variable argument list is
3058missing (NULL). When running with taint checks enabled, indicates via
3059C<maybe_tainted> if results are untrustworthy (often due to the use of
3060locales).
3061
3062 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3063
497711e7
GS
3064=for hackers
3065Found in file sv.c
3066
954c1994
GS
3067=item sv_vsetpvfn
3068
3069Works like C<vcatpvfn> but copies the text into the SV instead of
3070appending it.
3071
3072 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3073
497711e7
GS
3074=for hackers
3075Found in file sv.c
3076
954c1994
GS
3077=item THIS
3078
3079Variable which is setup by C<xsubpp> to designate the object in a C++
3080XSUB. This is always the proper type for the C++ object. See C<CLASS> and
3081L<perlxs/"Using XS With C++">.
3082
3083 (whatever) THIS
3084
497711e7
GS
3085=for hackers
3086Found in file XSUB.h
3087
954c1994
GS
3088=item toLOWER
3089
3090Converts the specified character to lowercase.
3091
3092 char toLOWER(char ch)
3093
497711e7
GS
3094=for hackers
3095Found in file handy.h
3096
954c1994
GS
3097=item toUPPER
3098
3099Converts the specified character to uppercase.
3100
3101 char toUPPER(char ch)
3102
497711e7
GS
3103=for hackers
3104Found in file handy.h
3105
6662521e
GS
3106=item U8 *s
3107
3108Returns true if first C<len> bytes of the given string form valid a UTF8
3109string, false otherwise.
3110
3111 bool_utf8_string U8 *s(STRLEN len)
3112
3113=for hackers
3114Found in file utf8.c
3115
497711e7
GS
3116=item utf8_to_bytes
3117
246fae53
MG
3118Converts a string C<s> of length C<len> from UTF8 into byte encoding.
3119Unlike C<bytes_to_utf8>, this over-writes the original string, and
3120updates len to contain the new length.
3121Returns zero on failure leaving the string and len unchanged
497711e7 3122
246fae53 3123 U8 * utf8_to_bytes(U8 *s, STRLEN *len)
497711e7
GS
3124
3125=for hackers
3126Found in file utf8.c
3127
954c1994
GS
3128=item warn
3129
3130This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3131function the same way you use the C C<printf> function. See
3132C<croak>.
3133
3134 void warn(const char* pat, ...)
3135
497711e7
GS
3136=for hackers
3137Found in file util.c
3138
954c1994
GS
3139=item XPUSHi
3140
3141Push an integer onto the stack, extending the stack if necessary. Handles
3142'set' magic. See C<PUSHi>.
3143
3144 void XPUSHi(IV iv)
3145
497711e7
GS
3146=for hackers
3147Found in file pp.h
3148
954c1994
GS
3149=item XPUSHn
3150
3151Push a double onto the stack, extending the stack if necessary. Handles
3152'set' magic. See C<PUSHn>.
3153
3154 void XPUSHn(NV nv)
3155
497711e7
GS
3156=for hackers
3157Found in file pp.h
3158
954c1994
GS
3159=item XPUSHp
3160
3161Push a string onto the stack, extending the stack if necessary. The C<len>
3162indicates the length of the string. Handles 'set' magic. See
3163C<PUSHp>.
3164
3165 void XPUSHp(char* str, STRLEN len)
3166
497711e7
GS
3167=for hackers
3168Found in file pp.h
3169
954c1994
GS
3170=item XPUSHs
3171
3172Push an SV onto the stack, extending the stack if necessary. Does not
3173handle 'set' magic. See C<PUSHs>.
3174
3175 void XPUSHs(SV* sv)
3176
497711e7
GS
3177=for hackers
3178Found in file pp.h
3179
954c1994
GS
3180=item XPUSHu
3181
3182Push an unsigned integer onto the stack, extending the stack if necessary.
3183See C<PUSHu>.
3184
3185 void XPUSHu(UV uv)
3186
497711e7
GS
3187=for hackers
3188Found in file pp.h
3189
954c1994
GS
3190=item XS
3191
3192Macro to declare an XSUB and its C parameter list. This is handled by
3193C<xsubpp>.
3194
497711e7
GS
3195=for hackers
3196Found in file XSUB.h
3197
954c1994
GS
3198=item XSRETURN
3199
3200Return from XSUB, indicating number of items on the stack. This is usually
3201handled by C<xsubpp>.
3202
3203 void XSRETURN(int nitems)
3204
497711e7
GS
3205=for hackers
3206Found in file XSUB.h
3207
954c1994
GS
3208=item XSRETURN_EMPTY
3209
3210Return an empty list from an XSUB immediately.
3211
3212 XSRETURN_EMPTY;
3213
497711e7
GS
3214=for hackers
3215Found in file XSUB.h
3216
954c1994
GS
3217=item XSRETURN_IV
3218
3219Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3220
3221 void XSRETURN_IV(IV iv)
3222
497711e7
GS
3223=for hackers
3224Found in file XSUB.h
3225
954c1994
GS
3226=item XSRETURN_NO
3227
3228Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3229
3230 XSRETURN_NO;
3231
497711e7
GS
3232=for hackers
3233Found in file XSUB.h
3234
954c1994
GS
3235=item XSRETURN_NV
3236
3237Return an double from an XSUB immediately. Uses C<XST_mNV>.
3238
3239 void XSRETURN_NV(NV nv)
3240
497711e7
GS
3241=for hackers
3242Found in file XSUB.h
3243
954c1994
GS
3244=item XSRETURN_PV
3245
3246Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3247
3248 void XSRETURN_PV(char* str)
3249
497711e7
GS
3250=for hackers
3251Found in file XSUB.h
3252
954c1994
GS
3253=item XSRETURN_UNDEF
3254
3255Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3256
3257 XSRETURN_UNDEF;
3258
497711e7
GS
3259=for hackers
3260Found in file XSUB.h
3261
954c1994
GS
3262=item XSRETURN_YES
3263
3264Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3265
3266 XSRETURN_YES;
3267
497711e7
GS
3268=for hackers
3269Found in file XSUB.h
3270
954c1994
GS
3271=item XST_mIV
3272
3273Place an integer into the specified position C<pos> on the stack. The
3274value is stored in a new mortal SV.
3275
3276 void XST_mIV(int pos, IV iv)
3277
497711e7
GS
3278=for hackers
3279Found in file XSUB.h
3280
954c1994
GS
3281=item XST_mNO
3282
3283Place C<&PL_sv_no> into the specified position C<pos> on the
3284stack.
3285
3286 void XST_mNO(int pos)
3287
497711e7
GS
3288=for hackers
3289Found in file XSUB.h
3290
954c1994
GS
3291=item XST_mNV
3292
3293Place a double into the specified position C<pos> on the stack. The value
3294is stored in a new mortal SV.
3295
3296 void XST_mNV(int pos, NV nv)
3297
497711e7
GS
3298=for hackers
3299Found in file XSUB.h
3300
954c1994
GS
3301=item XST_mPV
3302
3303Place a copy of a string into the specified position C<pos> on the stack.
3304The value is stored in a new mortal SV.
3305
3306 void XST_mPV(int pos, char* str)
3307
497711e7
GS
3308=for hackers
3309Found in file XSUB.h
3310
954c1994
GS
3311=item XST_mUNDEF
3312
3313Place C<&PL_sv_undef> into the specified position C<pos> on the
3314stack.
3315
3316 void XST_mUNDEF(int pos)
3317
497711e7
GS
3318=for hackers
3319Found in file XSUB.h
3320
954c1994
GS
3321=item XST_mYES
3322
3323Place C<&PL_sv_yes> into the specified position C<pos> on the
3324stack.
3325
3326 void XST_mYES(int pos)
3327
497711e7
GS
3328=for hackers
3329Found in file XSUB.h
3330
954c1994
GS
3331=item XS_VERSION
3332
3333The version identifier for an XS module. This is usually
3334handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3335
497711e7
GS
3336=for hackers
3337Found in file XSUB.h
3338
954c1994
GS
3339=item XS_VERSION_BOOTCHECK
3340
3341Macro to verify that a PM module's $VERSION variable matches the XS
3342module's C<XS_VERSION> variable. This is usually handled automatically by
3343C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3344
3345 XS_VERSION_BOOTCHECK;
3346
497711e7
GS
3347=for hackers
3348Found in file XSUB.h
3349
954c1994
GS
3350=item Zero
3351
3352The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
3353destination, C<nitems> is the number of items, and C<type> is the type.
3354
3355 void Zero(void* dest, int nitems, type)
3356
497711e7
GS
3357=for hackers
3358Found in file handy.h
3359
954c1994
GS
3360=back
3361
3362=head1 AUTHORS
3363
3364Until May 1997, this document was maintained by Jeff Okamoto
3365<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3366
3367With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3368Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3369Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3370Stephen McCamant, and Gurusamy Sarathy.
3371
3372API Listing originally by Dean Roehrich <roehrich@cray.com>.
3373
3374Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3375
3376=head1 SEE ALSO
3377
3378perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3379