This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Changes.
[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
444155da 1204space is allocated.) The reference count for the new SV is set to 1.
954c1994
GS
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
e331fc52
JH
1909=item SvIOK_notUV
1910
1911Returns a boolean indicating whether the SV contains an signed integer.
1912
1913 void SvIOK_notUV(SV* sv)
1914
1915=for hackers
1916Found in file sv.h
1917
954c1994
GS
1918=item SvIOK_off
1919
1920Unsets the IV status of an SV.
1921
1922 void SvIOK_off(SV* sv)
1923
497711e7
GS
1924=for hackers
1925Found in file sv.h
1926
954c1994
GS
1927=item SvIOK_on
1928
1929Tells an SV that it is an integer.
1930
1931 void SvIOK_on(SV* sv)
1932
497711e7
GS
1933=for hackers
1934Found in file sv.h
1935
954c1994
GS
1936=item SvIOK_only
1937
1938Tells an SV that it is an integer and disables all other OK bits.
1939
1940 void SvIOK_only(SV* sv)
1941
497711e7
GS
1942=for hackers
1943Found in file sv.h
1944
e331fc52
JH
1945=item SvIOK_only_UV
1946
1947Tells and SV that it is an unsigned integer and disables all other OK bits.
1948
1949 void SvIOK_only_UV(SV* sv)
1950
1951=for hackers
1952Found in file sv.h
1953
1954=item SvIOK_UV
1955
1956Returns a boolean indicating whether the SV contains an unsigned integer.
1957
1958 void SvIOK_UV(SV* sv)
1959
1960=for hackers
1961Found in file sv.h
1962
954c1994
GS
1963=item SvIV
1964
1965Coerces the given SV to an integer and returns it.
1966
1967 IV SvIV(SV* sv)
1968
497711e7
GS
1969=for hackers
1970Found in file sv.h
1971
954c1994
GS
1972=item SvIVX
1973
1974Returns the integer which is stored in the SV, assuming SvIOK is
1975true.
1976
1977 IV SvIVX(SV* sv)
1978
497711e7
GS
1979=for hackers
1980Found in file sv.h
1981
954c1994
GS
1982=item SvLEN
1983
91e74348
JH
1984Returns the size of the string buffer in the SV, not including any part
1985attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
1986
1987 STRLEN SvLEN(SV* sv)
1988
497711e7
GS
1989=for hackers
1990Found in file sv.h
1991
954c1994
GS
1992=item SvNIOK
1993
1994Returns a boolean indicating whether the SV contains a number, integer or
1995double.
1996
1997 bool SvNIOK(SV* sv)
1998
497711e7
GS
1999=for hackers
2000Found in file sv.h
2001
954c1994
GS
2002=item SvNIOKp
2003
2004Returns a boolean indicating whether the SV contains a number, integer or
2005double. Checks the B<private> setting. Use C<SvNIOK>.
2006
2007 bool SvNIOKp(SV* sv)
2008
497711e7
GS
2009=for hackers
2010Found in file sv.h
2011
954c1994
GS
2012=item SvNIOK_off
2013
2014Unsets the NV/IV status of an SV.
2015
2016 void SvNIOK_off(SV* sv)
2017
497711e7
GS
2018=for hackers
2019Found in file sv.h
2020
954c1994
GS
2021=item SvNOK
2022
2023Returns a boolean indicating whether the SV contains a double.
2024
2025 bool SvNOK(SV* sv)
2026
497711e7
GS
2027=for hackers
2028Found in file sv.h
2029
954c1994
GS
2030=item SvNOKp
2031
2032Returns a boolean indicating whether the SV contains a double. Checks the
2033B<private> setting. Use C<SvNOK>.
2034
2035 bool SvNOKp(SV* sv)
2036
497711e7
GS
2037=for hackers
2038Found in file sv.h
2039
954c1994
GS
2040=item SvNOK_off
2041
2042Unsets the NV status of an SV.
2043
2044 void SvNOK_off(SV* sv)
2045
497711e7
GS
2046=for hackers
2047Found in file sv.h
2048
954c1994
GS
2049=item SvNOK_on
2050
2051Tells an SV that it is a double.
2052
2053 void SvNOK_on(SV* sv)
2054
497711e7
GS
2055=for hackers
2056Found in file sv.h
2057
954c1994
GS
2058=item SvNOK_only
2059
2060Tells an SV that it is a double and disables all other OK bits.
2061
2062 void SvNOK_only(SV* sv)
2063
497711e7
GS
2064=for hackers
2065Found in file sv.h
2066
954c1994
GS
2067=item SvNV
2068
2069Coerce the given SV to a double and return it.
2070
2071 NV SvNV(SV* sv)
2072
497711e7
GS
2073=for hackers
2074Found in file sv.h
2075
954c1994
GS
2076=item SvNVX
2077
2078Returns the double which is stored in the SV, assuming SvNOK is
2079true.
2080
2081 NV SvNVX(SV* sv)
2082
497711e7
GS
2083=for hackers
2084Found in file sv.h
2085
954c1994
GS
2086=item SvOK
2087
2088Returns a boolean indicating whether the value is an SV.
2089
2090 bool SvOK(SV* sv)
2091
497711e7
GS
2092=for hackers
2093Found in file sv.h
2094
954c1994
GS
2095=item SvOOK
2096
2097Returns a boolean indicating whether the SvIVX is a valid offset value for
2098the SvPVX. This hack is used internally to speed up removal of characters
2099from the beginning of a SvPV. When SvOOK is true, then the start of the
2100allocated string buffer is really (SvPVX - SvIVX).
2101
2102 bool SvOOK(SV* sv)
2103
497711e7
GS
2104=for hackers
2105Found in file sv.h
2106
954c1994
GS
2107=item SvPOK
2108
2109Returns a boolean indicating whether the SV contains a character
2110string.
2111
2112 bool SvPOK(SV* sv)
2113
497711e7
GS
2114=for hackers
2115Found in file sv.h
2116
954c1994
GS
2117=item SvPOKp
2118
2119Returns a boolean indicating whether the SV contains a character string.
2120Checks the B<private> setting. Use C<SvPOK>.
2121
2122 bool SvPOKp(SV* sv)
2123
497711e7
GS
2124=for hackers
2125Found in file sv.h
2126
954c1994
GS
2127=item SvPOK_off
2128
2129Unsets the PV status of an SV.
2130
2131 void SvPOK_off(SV* sv)
2132
497711e7
GS
2133=for hackers
2134Found in file sv.h
2135
954c1994
GS
2136=item SvPOK_on
2137
2138Tells an SV that it is a string.
2139
2140 void SvPOK_on(SV* sv)
2141
497711e7
GS
2142=for hackers
2143Found in file sv.h
2144
954c1994
GS
2145=item SvPOK_only
2146
2147Tells an SV that it is a string and disables all other OK bits.
2148
2149 void SvPOK_only(SV* sv)
2150
497711e7
GS
2151=for hackers
2152Found in file sv.h
2153
914184e1
JH
2154=item SvPOK_only_UTF8
2155
2156Tells an SV that it is a UTF8 string (do not use frivolously)
2157and disables all other OK bits.
2158
2159 void SvPOK_only_UTF8(SV* sv)
2160
2161=for hackers
2162Found in file sv.h
2163
954c1994
GS
2164=item SvPV
2165
2166Returns a pointer to the string in the SV, or a stringified form of the SV
2167if the SV does not contain a string. Handles 'get' magic.
2168
2169 char* SvPV(SV* sv, STRLEN len)
2170
497711e7
GS
2171=for hackers
2172Found in file sv.h
2173
954c1994
GS
2174=item SvPVX
2175
2176Returns a pointer to the string in the SV. The SV must contain a
2177string.
2178
2179 char* SvPVX(SV* sv)
2180
497711e7
GS
2181=for hackers
2182Found in file sv.h
2183
954c1994
GS
2184=item SvPV_force
2185
2186Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2187force if you are going to update the SvPVX directly.
2188
2189 char* SvPV_force(SV* sv, STRLEN len)
2190
497711e7
GS
2191=for hackers
2192Found in file sv.h
2193
954c1994
GS
2194=item SvPV_nolen
2195
2196Returns a pointer to the string in the SV, or a stringified form of the SV
2197if the SV does not contain a string. Handles 'get' magic.
2198
2199 char* SvPV_nolen(SV* sv)
2200
497711e7
GS
2201=for hackers
2202Found in file sv.h
2203
954c1994
GS
2204=item SvREFCNT
2205
2206Returns the value of the object's reference count.
2207
2208 U32 SvREFCNT(SV* sv)
2209
497711e7
GS
2210=for hackers
2211Found in file sv.h
2212
954c1994
GS
2213=item SvREFCNT_dec
2214
2215Decrements the reference count of the given SV.
2216
2217 void SvREFCNT_dec(SV* sv)
2218
497711e7
GS
2219=for hackers
2220Found in file sv.h
2221
954c1994
GS
2222=item SvREFCNT_inc
2223
2224Increments the reference count of the given SV.
2225
2226 SV* SvREFCNT_inc(SV* sv)
2227
497711e7
GS
2228=for hackers
2229Found in file sv.h
2230
954c1994
GS
2231=item SvROK
2232
2233Tests if the SV is an RV.
2234
2235 bool SvROK(SV* sv)
2236
497711e7
GS
2237=for hackers
2238Found in file sv.h
2239
954c1994
GS
2240=item SvROK_off
2241
2242Unsets the RV status of an SV.
2243
2244 void SvROK_off(SV* sv)
2245
497711e7
GS
2246=for hackers
2247Found in file sv.h
2248
954c1994
GS
2249=item SvROK_on
2250
2251Tells an SV that it is an RV.
2252
2253 void SvROK_on(SV* sv)
2254
497711e7
GS
2255=for hackers
2256Found in file sv.h
2257
954c1994
GS
2258=item SvRV
2259
2260Dereferences an RV to return the SV.
2261
2262 SV* SvRV(SV* sv)
2263
497711e7
GS
2264=for hackers
2265Found in file sv.h
2266
954c1994
GS
2267=item SvSETMAGIC
2268
2269Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2270argument more than once.
2271
2272 void SvSETMAGIC(SV* sv)
2273
497711e7
GS
2274=for hackers
2275Found in file sv.h
2276
954c1994
GS
2277=item SvSetSV
2278
2279Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2280more than once.
2281
2282 void SvSetSV(SV* dsb, SV* ssv)
2283
497711e7
GS
2284=for hackers
2285Found in file sv.h
2286
954c1994
GS
2287=item SvSetSV_nosteal
2288
2289Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2290ssv. May evaluate arguments more than once.
2291
2292 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2293
497711e7
GS
2294=for hackers
2295Found in file sv.h
2296
954c1994
GS
2297=item SvSTASH
2298
2299Returns the stash of the SV.
2300
2301 HV* SvSTASH(SV* sv)
2302
497711e7
GS
2303=for hackers
2304Found in file sv.h
2305
954c1994
GS
2306=item SvTAINT
2307
2308Taints an SV if tainting is enabled
2309
2310 void SvTAINT(SV* sv)
2311
497711e7
GS
2312=for hackers
2313Found in file sv.h
2314
954c1994
GS
2315=item SvTAINTED
2316
2317Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2318not.
2319
2320 bool SvTAINTED(SV* sv)
2321
497711e7
GS
2322=for hackers
2323Found in file sv.h
2324
954c1994
GS
2325=item SvTAINTED_off
2326
2327Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2328some of Perl's fundamental security features. XS module authors should not
2329use this function unless they fully understand all the implications of
2330unconditionally untainting the value. Untainting should be done in the
2331standard perl fashion, via a carefully crafted regexp, rather than directly
2332untainting variables.
2333
2334 void SvTAINTED_off(SV* sv)
2335
497711e7
GS
2336=for hackers
2337Found in file sv.h
2338
954c1994
GS
2339=item SvTAINTED_on
2340
2341Marks an SV as tainted.
2342
2343 void SvTAINTED_on(SV* sv)
2344
497711e7
GS
2345=for hackers
2346Found in file sv.h
2347
954c1994
GS
2348=item SvTRUE
2349
2350Returns a boolean indicating whether Perl would evaluate the SV as true or
2351false, defined or undefined. Does not handle 'get' magic.
2352
2353 bool SvTRUE(SV* sv)
2354
497711e7
GS
2355=for hackers
2356Found in file sv.h
2357
444155da 2358=item svtype
8e84507e 2359
444155da
JH
2360An enum of flags for Perl types. These are found in the file B<sv.h>
2361in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
34f7a5fe 2362
497711e7
GS
2363=for hackers
2364Found in file sv.h
2365
444155da 2366=item SvTYPE
b6b716fe 2367
444155da
JH
2368Returns the type of the SV. See C<svtype>.
2369
2370 svtype SvTYPE(SV* sv)
954c1994 2371
497711e7
GS
2372=for hackers
2373Found in file sv.h
2374
954c1994
GS
2375=item SVt_IV
2376
2377Integer type flag for scalars. See C<svtype>.
2378
497711e7
GS
2379=for hackers
2380Found in file sv.h
2381
954c1994
GS
2382=item SVt_NV
2383
2384Double type flag for scalars. See C<svtype>.
2385
497711e7
GS
2386=for hackers
2387Found in file sv.h
2388
954c1994
GS
2389=item SVt_PV
2390
2391Pointer type flag for scalars. See C<svtype>.
2392
497711e7
GS
2393=for hackers
2394Found in file sv.h
2395
954c1994
GS
2396=item SVt_PVAV
2397
2398Type flag for arrays. See C<svtype>.
2399
497711e7
GS
2400=for hackers
2401Found in file sv.h
2402
954c1994
GS
2403=item SVt_PVCV
2404
2405Type flag for code refs. See C<svtype>.
2406
497711e7
GS
2407=for hackers
2408Found in file sv.h
2409
954c1994
GS
2410=item SVt_PVHV
2411
2412Type flag for hashes. See C<svtype>.
2413
497711e7
GS
2414=for hackers
2415Found in file sv.h
2416
954c1994
GS
2417=item SVt_PVMG
2418
2419Type flag for blessed scalars. See C<svtype>.
2420
497711e7
GS
2421=for hackers
2422Found in file sv.h
2423
954c1994
GS
2424=item SvUPGRADE
2425
2426Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
2427perform the upgrade if necessary. See C<svtype>.
2428
2429 void SvUPGRADE(SV* sv, svtype type)
2430
497711e7
GS
2431=for hackers
2432Found in file sv.h
2433
914184e1
JH
2434=item SvUTF8
2435
2436Returns a boolean indicating whether the SV contains UTF-8 encoded data.
2437
2438 void SvUTF8(SV* sv)
2439
2440=for hackers
2441Found in file sv.h
2442
2443=item SvUTF8_off
2444
2445Unsets the UTF8 status of an SV.
2446
2447 void SvUTF8_off(SV *sv)
2448
2449=for hackers
2450Found in file sv.h
2451
2452=item SvUTF8_on
2453
2454Tells an SV that it is a string and encoded in UTF8. Do not use frivolously.
2455
2456 void SvUTF8_on(SV *sv)
2457
2458=for hackers
2459Found in file sv.h
2460
954c1994
GS
2461=item SvUV
2462
2463Coerces the given SV to an unsigned integer and returns it.
2464
2465 UV SvUV(SV* sv)
2466
497711e7
GS
2467=for hackers
2468Found in file sv.h
2469
954c1994
GS
2470=item SvUVX
2471
2472Returns the unsigned integer which is stored in the SV, assuming SvIOK is
2473true.
2474
2475 UV SvUVX(SV* sv)
2476
497711e7
GS
2477=for hackers
2478Found in file sv.h
2479
954c1994
GS
2480=item sv_2mortal
2481
2482Marks an SV as mortal. The SV will be destroyed when the current context
2483ends.
2484
2485 SV* sv_2mortal(SV* sv)
2486
497711e7
GS
2487=for hackers
2488Found in file sv.c
2489
954c1994
GS
2490=item sv_bless
2491
2492Blesses an SV into a specified package. The SV must be an RV. The package
2493must be designated by its stash (see C<gv_stashpv()>). The reference count
2494of the SV is unaffected.
2495
2496 SV* sv_bless(SV* sv, HV* stash)
2497
497711e7
GS
2498=for hackers
2499Found in file sv.c
2500
954c1994
GS
2501=item sv_catpv
2502
2503Concatenates the string onto the end of the string which is in the SV.
2504Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
2505
2506 void sv_catpv(SV* sv, const char* ptr)
2507
497711e7
GS
2508=for hackers
2509Found in file sv.c
2510
954c1994
GS
2511=item sv_catpvf
2512
2513Processes its arguments like C<sprintf> and appends the formatted output
2514to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
2515typically be called after calling this function to handle 'set' magic.
2516
2517 void sv_catpvf(SV* sv, const char* pat, ...)
2518
497711e7
GS
2519=for hackers
2520Found in file sv.c
2521
954c1994
GS
2522=item sv_catpvf_mg
2523
2524Like C<sv_catpvf>, but also handles 'set' magic.
2525
2526 void sv_catpvf_mg(SV *sv, const char* pat, ...)
2527
497711e7
GS
2528=for hackers
2529Found in file sv.c
2530
954c1994
GS
2531=item sv_catpvn
2532
2533Concatenates the string onto the end of the string which is in the SV. The
2534C<len> indicates number of bytes to copy. Handles 'get' magic, but not
2535'set' magic. See C<sv_catpvn_mg>.
2536
2537 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
2538
497711e7
GS
2539=for hackers
2540Found in file sv.c
2541
954c1994
GS
2542=item sv_catpvn_mg
2543
2544Like C<sv_catpvn>, but also handles 'set' magic.
2545
2546 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
2547
497711e7
GS
2548=for hackers
2549Found in file sv.c
2550
954c1994
GS
2551=item sv_catpv_mg
2552
2553Like C<sv_catpv>, but also handles 'set' magic.
2554
2555 void sv_catpv_mg(SV *sv, const char *ptr)
2556
497711e7
GS
2557=for hackers
2558Found in file sv.c
2559
954c1994
GS
2560=item sv_catsv
2561
2562Concatenates the string from SV C<ssv> onto the end of the string in SV
2563C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
2564
2565 void sv_catsv(SV* dsv, SV* ssv)
2566
497711e7
GS
2567=for hackers
2568Found in file sv.c
2569
954c1994
GS
2570=item sv_catsv_mg
2571
2572Like C<sv_catsv>, but also handles 'set' magic.
2573
2574 void sv_catsv_mg(SV *dstr, SV *sstr)
2575
497711e7
GS
2576=for hackers
2577Found in file sv.c
2578
954c1994
GS
2579=item sv_chop
2580
1c846c1f 2581Efficient removal of characters from the beginning of the string buffer.
954c1994
GS
2582SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
2583the string buffer. The C<ptr> becomes the first character of the adjusted
2584string.
2585
2586 void sv_chop(SV* sv, char* ptr)
2587
497711e7
GS
2588=for hackers
2589Found in file sv.c
2590
c461cf8f
JH
2591=item sv_clear
2592
2593Clear an SV, making it empty. Does not free the memory used by the SV
2594itself.
2595
2596 void sv_clear(SV* sv)
2597
2598=for hackers
2599Found in file sv.c
2600
954c1994
GS
2601=item sv_cmp
2602
2603Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2604string in C<sv1> is less than, equal to, or greater than the string in
2605C<sv2>.
2606
2607 I32 sv_cmp(SV* sv1, SV* sv2)
2608
497711e7
GS
2609=for hackers
2610Found in file sv.c
2611
c461cf8f
JH
2612=item sv_cmp_locale
2613
2614Compares the strings in two SVs in a locale-aware manner. See
2615L</sv_cmp_locale>
2616
2617 I32 sv_cmp_locale(SV* sv1, SV* sv2)
2618
2619=for hackers
2620Found in file sv.c
2621
954c1994
GS
2622=item sv_dec
2623
2624Auto-decrement of the value in the SV.
2625
2626 void sv_dec(SV* sv)
2627
497711e7
GS
2628=for hackers
2629Found in file sv.c
2630
954c1994
GS
2631=item sv_derived_from
2632
2633Returns a boolean indicating whether the SV is derived from the specified
2634class. This is the function that implements C<UNIVERSAL::isa>. It works
2635for class names as well as for objects.
2636
2637 bool sv_derived_from(SV* sv, const char* name)
2638
497711e7
GS
2639=for hackers
2640Found in file universal.c
2641
954c1994
GS
2642=item sv_eq
2643
2644Returns a boolean indicating whether the strings in the two SVs are
2645identical.
2646
2647 I32 sv_eq(SV* sv1, SV* sv2)
2648
497711e7
GS
2649=for hackers
2650Found in file sv.c
2651
c461cf8f
JH
2652=item sv_free
2653
2654Free the memory used by an SV.
2655
2656 void sv_free(SV* sv)
2657
2658=for hackers
2659Found in file sv.c
2660
2661=item sv_gets
2662
2663Get a line from the filehandle and store it into the SV, optionally
2664appending to the currently-stored string.
2665
2666 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
2667
2668=for hackers
2669Found in file sv.c
2670
954c1994
GS
2671=item sv_grow
2672
2673Expands the character buffer in the SV. This will use C<sv_unref> and will
2674upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2675Use C<SvGROW>.
2676
2677 char* sv_grow(SV* sv, STRLEN newlen)
2678
497711e7
GS
2679=for hackers
2680Found in file sv.c
2681
954c1994
GS
2682=item sv_inc
2683
2684Auto-increment of the value in the SV.
2685
2686 void sv_inc(SV* sv)
2687
497711e7
GS
2688=for hackers
2689Found in file sv.c
2690
954c1994
GS
2691=item sv_insert
2692
2693Inserts a string at the specified offset/length within the SV. Similar to
2694the Perl substr() function.
2695
2696 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2697
497711e7
GS
2698=for hackers
2699Found in file sv.c
2700
954c1994
GS
2701=item sv_isa
2702
2703Returns a boolean indicating whether the SV is blessed into the specified
2704class. This does not check for subtypes; use C<sv_derived_from> to verify
2705an inheritance relationship.
2706
2707 int sv_isa(SV* sv, const char* name)
2708
497711e7
GS
2709=for hackers
2710Found in file sv.c
2711
954c1994
GS
2712=item sv_isobject
2713
2714Returns a boolean indicating whether the SV is an RV pointing to a blessed
2715object. If the SV is not an RV, or if the object is not blessed, then this
2716will return false.
2717
2718 int sv_isobject(SV* sv)
2719
497711e7
GS
2720=for hackers
2721Found in file sv.c
2722
954c1994
GS
2723=item sv_len
2724
2725Returns the length of the string in the SV. See also C<SvCUR>.
2726
2727 STRLEN sv_len(SV* sv)
2728
497711e7
GS
2729=for hackers
2730Found in file sv.c
2731
c461cf8f
JH
2732=item sv_len_utf8
2733
2734Returns the number of characters in the string in an SV, counting wide
2735UTF8 bytes as a single character.
2736
2737 STRLEN sv_len_utf8(SV* sv)
2738
2739=for hackers
2740Found in file sv.c
2741
954c1994
GS
2742=item sv_magic
2743
2744Adds magic to an SV.
2745
2746 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2747
497711e7
GS
2748=for hackers
2749Found in file sv.c
2750
954c1994
GS
2751=item sv_mortalcopy
2752
2753Creates a new SV which is a copy of the original SV. The new SV is marked
2754as mortal.
2755
2756 SV* sv_mortalcopy(SV* oldsv)
2757
497711e7
GS
2758=for hackers
2759Found in file sv.c
2760
954c1994
GS
2761=item sv_newmortal
2762
2763Creates a new SV which is mortal. The reference count of the SV is set to 1.
2764
2765 SV* sv_newmortal()
2766
497711e7
GS
2767=for hackers
2768Found in file sv.c
2769
c461cf8f
JH
2770=item sv_pvn_force
2771
2772Get a sensible string out of the SV somehow.
2773
2774 char* sv_pvn_force(SV* sv, STRLEN* lp)
2775
2776=for hackers
2777Found in file sv.c
2778
2779=item sv_pvutf8n_force
2780
2781Get a sensible UTF8-encoded string out of the SV somehow. See
2782L</sv_pvn_force>.
2783
2784 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
2785
2786=for hackers
2787Found in file sv.c
2788
2789=item sv_reftype
2790
2791Returns a string describing what the SV is a reference to.
2792
2793 char* sv_reftype(SV* sv, int ob)
2794
2795=for hackers
2796Found in file sv.c
2797
2798=item sv_replace
2799
2800Make the first argument a copy of the second, then delete the original.
2801
2802 void sv_replace(SV* sv, SV* nsv)
2803
2804=for hackers
2805Found in file sv.c
2806
2807=item sv_rvweaken
2808
2809Weaken a reference.
2810
2811 SV* sv_rvweaken(SV *sv)
2812
2813=for hackers
2814Found in file sv.c
2815
954c1994
GS
2816=item sv_setiv
2817
2818Copies an integer into the given SV. Does not handle 'set' magic. See
2819C<sv_setiv_mg>.
2820
2821 void sv_setiv(SV* sv, IV num)
2822
497711e7
GS
2823=for hackers
2824Found in file sv.c
2825
954c1994
GS
2826=item sv_setiv_mg
2827
2828Like C<sv_setiv>, but also handles 'set' magic.
2829
2830 void sv_setiv_mg(SV *sv, IV i)
2831
497711e7
GS
2832=for hackers
2833Found in file sv.c
2834
954c1994
GS
2835=item sv_setnv
2836
2837Copies a double into the given SV. Does not handle 'set' magic. See
2838C<sv_setnv_mg>.
2839
2840 void sv_setnv(SV* sv, NV num)
2841
497711e7
GS
2842=for hackers
2843Found in file sv.c
2844
954c1994
GS
2845=item sv_setnv_mg
2846
2847Like C<sv_setnv>, but also handles 'set' magic.
2848
2849 void sv_setnv_mg(SV *sv, NV num)
2850
497711e7
GS
2851=for hackers
2852Found in file sv.c
2853
954c1994
GS
2854=item sv_setpv
2855
2856Copies a string into an SV. The string must be null-terminated. Does not
2857handle 'set' magic. See C<sv_setpv_mg>.
2858
2859 void sv_setpv(SV* sv, const char* ptr)
2860
497711e7
GS
2861=for hackers
2862Found in file sv.c
2863
954c1994
GS
2864=item sv_setpvf
2865
2866Processes its arguments like C<sprintf> and sets an SV to the formatted
2867output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
2868
2869 void sv_setpvf(SV* sv, const char* pat, ...)
2870
497711e7
GS
2871=for hackers
2872Found in file sv.c
2873
954c1994
GS
2874=item sv_setpvf_mg
2875
2876Like C<sv_setpvf>, but also handles 'set' magic.
2877
2878 void sv_setpvf_mg(SV *sv, const char* pat, ...)
2879
497711e7
GS
2880=for hackers
2881Found in file sv.c
2882
954c1994
GS
2883=item sv_setpviv
2884
2885Copies an integer into the given SV, also updating its string value.
2886Does not handle 'set' magic. See C<sv_setpviv_mg>.
2887
2888 void sv_setpviv(SV* sv, IV num)
2889
497711e7
GS
2890=for hackers
2891Found in file sv.c
2892
954c1994
GS
2893=item sv_setpviv_mg
2894
2895Like C<sv_setpviv>, but also handles 'set' magic.
2896
2897 void sv_setpviv_mg(SV *sv, IV iv)
2898
497711e7
GS
2899=for hackers
2900Found in file sv.c
2901
954c1994
GS
2902=item sv_setpvn
2903
2904Copies a string into an SV. The C<len> parameter indicates the number of
2905bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
2906
2907 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2908
497711e7
GS
2909=for hackers
2910Found in file sv.c
2911
954c1994
GS
2912=item sv_setpvn_mg
2913
2914Like C<sv_setpvn>, but also handles 'set' magic.
2915
2916 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2917
497711e7
GS
2918=for hackers
2919Found in file sv.c
2920
954c1994
GS
2921=item sv_setpv_mg
2922
2923Like C<sv_setpv>, but also handles 'set' magic.
2924
2925 void sv_setpv_mg(SV *sv, const char *ptr)
2926
497711e7
GS
2927=for hackers
2928Found in file sv.c
2929
954c1994
GS
2930=item sv_setref_iv
2931
2932Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2933argument will be upgraded to an RV. That RV will be modified to point to
2934the new SV. The C<classname> argument indicates the package for the
2935blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2936will be returned and will have a reference count of 1.
2937
2938 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
2939
497711e7
GS
2940=for hackers
2941Found in file sv.c
2942
954c1994
GS
2943=item sv_setref_nv
2944
2945Copies a double into a new SV, optionally blessing the SV. The C<rv>
2946argument will be upgraded to an RV. That RV will be modified to point to
2947the new SV. The C<classname> argument indicates the package for the
2948blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2949will be returned and will have a reference count of 1.
2950
2951 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
2952
497711e7
GS
2953=for hackers
2954Found in file sv.c
2955
954c1994
GS
2956=item sv_setref_pv
2957
2958Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2959argument will be upgraded to an RV. That RV will be modified to point to
2960the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2961into the SV. The C<classname> argument indicates the package for the
2962blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2963will be returned and will have a reference count of 1.
2964
2965Do not use with other Perl types such as HV, AV, SV, CV, because those
2966objects will become corrupted by the pointer copy process.
2967
2968Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2969
2970 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
2971
497711e7
GS
2972=for hackers
2973Found in file sv.c
2974
954c1994
GS
2975=item sv_setref_pvn
2976
2977Copies a string into a new SV, optionally blessing the SV. The length of the
2978string must be specified with C<n>. The C<rv> argument will be upgraded to
2979an RV. That RV will be modified to point to the new SV. The C<classname>
2980argument indicates the package for the blessing. Set C<classname> to
2981C<Nullch> to avoid the blessing. The new SV will be returned and will have
2982a reference count of 1.
2983
2984Note that C<sv_setref_pv> copies the pointer while this copies the string.
2985
2986 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2987
497711e7
GS
2988=for hackers
2989Found in file sv.c
2990
954c1994
GS
2991=item sv_setsv
2992
2993Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2994The source SV may be destroyed if it is mortal. Does not handle 'set'
2995magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
2996C<sv_setsv_mg>.
2997
2998 void sv_setsv(SV* dsv, SV* ssv)
2999
497711e7
GS
3000=for hackers
3001Found in file sv.c
3002
954c1994
GS
3003=item sv_setsv_mg
3004
3005Like C<sv_setsv>, but also handles 'set' magic.
3006
3007 void sv_setsv_mg(SV *dstr, SV *sstr)
3008
497711e7
GS
3009=for hackers
3010Found in file sv.c
3011
954c1994
GS
3012=item sv_setuv
3013
3014Copies an unsigned integer into the given SV. Does not handle 'set' magic.
3015See C<sv_setuv_mg>.
3016
3017 void sv_setuv(SV* sv, UV num)
3018
497711e7
GS
3019=for hackers
3020Found in file sv.c
3021
954c1994
GS
3022=item sv_setuv_mg
3023
3024Like C<sv_setuv>, but also handles 'set' magic.
3025
3026 void sv_setuv_mg(SV *sv, UV u)
3027
497711e7
GS
3028=for hackers
3029Found in file sv.c
3030
c461cf8f
JH
3031=item sv_true
3032
3033Returns true if the SV has a true value by Perl's rules.
3034
3035 I32 sv_true(SV *sv)
3036
3037=for hackers
3038Found in file sv.c
3039
3040=item sv_unmagic
3041
3042Removes magic from an SV.
3043
3044 int sv_unmagic(SV* sv, int type)
3045
3046=for hackers
3047Found in file sv.c
3048
954c1994
GS
3049=item sv_unref
3050
3051Unsets the RV status of the SV, and decrements the reference count of
3052whatever was being referenced by the RV. This can almost be thought of
3053as a reversal of C<newSVrv>. See C<SvROK_off>.
3054
3055 void sv_unref(SV* sv)
3056
497711e7
GS
3057=for hackers
3058Found in file sv.c
3059
954c1994
GS
3060=item sv_upgrade
3061
3062Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
3063C<svtype>.
3064
3065 bool sv_upgrade(SV* sv, U32 mt)
3066
497711e7
GS
3067=for hackers
3068Found in file sv.c
3069
954c1994
GS
3070=item sv_usepvn
3071
3072Tells an SV to use C<ptr> to find its string value. Normally the string is
1c846c1f 3073stored inside the SV but sv_usepvn allows the SV to use an outside string.
954c1994
GS
3074The C<ptr> should point to memory that was allocated by C<malloc>. The
3075string length, C<len>, must be supplied. This function will realloc the
3076memory pointed to by C<ptr>, so that pointer should not be freed or used by
3077the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
3078See C<sv_usepvn_mg>.
3079
3080 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
3081
497711e7
GS
3082=for hackers
3083Found in file sv.c
3084
954c1994
GS
3085=item sv_usepvn_mg
3086
3087Like C<sv_usepvn>, but also handles 'set' magic.
3088
3089 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3090
497711e7
GS
3091=for hackers
3092Found in file sv.c
3093
c461cf8f
JH
3094=item sv_utf8_downgrade
3095
3096Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3097This may not be possible if the PV contains non-byte encoding characters;
3098if this is the case, either returns false or, if C<fail_ok> is not
3099true, croaks.
3100
3101NOTE: this function is experimental and may change or be
3102removed without notice.
3103
3104 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
3105
3106=for hackers
3107Found in file sv.c
3108
3109=item sv_utf8_encode
3110
3111Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
1c846c1f 3112flag so that it looks like bytes again. Nothing calls this.
c461cf8f
JH
3113
3114NOTE: this function is experimental and may change or be
3115removed without notice.
3116
3117 void sv_utf8_encode(SV *sv)
3118
3119=for hackers
3120Found in file sv.c
3121
3122=item sv_utf8_upgrade
3123
3124Convert the PV of an SV to its UTF8-encoded form.
3125
3126 void sv_utf8_upgrade(SV *sv)
3127
3128=for hackers
3129Found in file sv.c
3130
954c1994
GS
3131=item sv_vcatpvfn
3132
3133Processes its arguments like C<vsprintf> and appends the formatted output
3134to an SV. Uses an array of SVs if the C style variable argument list is
3135missing (NULL). When running with taint checks enabled, indicates via
3136C<maybe_tainted> if results are untrustworthy (often due to the use of
3137locales).
3138
3139 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3140
497711e7
GS
3141=for hackers
3142Found in file sv.c
3143
954c1994
GS
3144=item sv_vsetpvfn
3145
3146Works like C<vcatpvfn> but copies the text into the SV instead of
3147appending it.
3148
3149 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3150
497711e7
GS
3151=for hackers
3152Found in file sv.c
3153
954c1994
GS
3154=item THIS
3155
3156Variable which is setup by C<xsubpp> to designate the object in a C++
3157XSUB. This is always the proper type for the C++ object. See C<CLASS> and
3158L<perlxs/"Using XS With C++">.
3159
3160 (whatever) THIS
3161
497711e7
GS
3162=for hackers
3163Found in file XSUB.h
3164
954c1994
GS
3165=item toLOWER
3166
3167Converts the specified character to lowercase.
3168
3169 char toLOWER(char ch)
3170
497711e7
GS
3171=for hackers
3172Found in file handy.h
3173
954c1994
GS
3174=item toUPPER
3175
3176Converts the specified character to uppercase.
3177
3178 char toUPPER(char ch)
3179
497711e7
GS
3180=for hackers
3181Found in file handy.h
3182
6662521e
GS
3183=item U8 *s
3184
b6b716fe
SC
3185Returns true if first C<len> bytes of the given string form valid a UTF8
3186string, false otherwise.
67e989fb 3187
b6b716fe 3188 is_utf8_string U8 *s(STRLEN len)
6662521e
GS
3189
3190=for hackers
3191Found in file utf8.c
3192
497711e7
GS
3193=item utf8_to_bytes
3194
246fae53
MG
3195Converts a string C<s> of length C<len> from UTF8 into byte encoding.
3196Unlike C<bytes_to_utf8>, this over-writes the original string, and
3197updates len to contain the new length.
67e989fb 3198Returns zero on failure, setting C<len> to -1.
497711e7 3199
246fae53 3200 U8 * utf8_to_bytes(U8 *s, STRLEN *len)
497711e7
GS
3201
3202=for hackers
3203Found in file utf8.c
3204
b6b716fe
SC
3205=item utf8_to_uv
3206
3207Returns the character value of the first character in the string C<s>
3208which is assumed to be in UTF8 encoding; C<retlen> will be set to the
3209length, in bytes, of that character, and the pointer C<s> will be
3210advanced to the end of the character.
3211
444155da
JH
3212If C<s> does not point to a well-formed UTF8 character, an optional UTF8
3213warning is produced.
3214
3215 U8* s utf8_to_uv(I32 *retlen)
3216
3217=for hackers
3218Found in file utf8.c
3219
3220=item utf8_to_uv_chk
3221
3222Returns the character value of the first character in the string C<s>
3223which is assumed to be in UTF8 encoding; C<retlen> will be set to the
3224length, in bytes, of that character, and the pointer C<s> will be
3225advanced to the end of the character.
3226
b6b716fe
SC
3227If C<s> does not point to a well-formed UTF8 character, the behaviour
3228is dependent on the value of C<checking>: if this is true, it is
3229assumed that the caller will raise a warning, and this function will
3230set C<retlen> to C<-1> and return. If C<checking> is not true, an optional UTF8
3231warning is produced.
3232
444155da 3233 U8* s utf8_to_uv_chk(I32 *retlen, I32 checking)
b6b716fe
SC
3234
3235=for hackers
3236Found in file utf8.c
3237
954c1994
GS
3238=item warn
3239
3240This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3241function the same way you use the C C<printf> function. See
3242C<croak>.
3243
3244 void warn(const char* pat, ...)
3245
497711e7
GS
3246=for hackers
3247Found in file util.c
3248
954c1994
GS
3249=item XPUSHi
3250
3251Push an integer onto the stack, extending the stack if necessary. Handles
3252'set' magic. See C<PUSHi>.
3253
3254 void XPUSHi(IV iv)
3255
497711e7
GS
3256=for hackers
3257Found in file pp.h
3258
954c1994
GS
3259=item XPUSHn
3260
3261Push a double onto the stack, extending the stack if necessary. Handles
3262'set' magic. See C<PUSHn>.
3263
3264 void XPUSHn(NV nv)
3265
497711e7
GS
3266=for hackers
3267Found in file pp.h
3268
954c1994
GS
3269=item XPUSHp
3270
3271Push a string onto the stack, extending the stack if necessary. The C<len>
3272indicates the length of the string. Handles 'set' magic. See
3273C<PUSHp>.
3274
3275 void XPUSHp(char* str, STRLEN len)
3276
497711e7
GS
3277=for hackers
3278Found in file pp.h
3279
954c1994
GS
3280=item XPUSHs
3281
3282Push an SV onto the stack, extending the stack if necessary. Does not
3283handle 'set' magic. See C<PUSHs>.
3284
3285 void XPUSHs(SV* sv)
3286
497711e7
GS
3287=for hackers
3288Found in file pp.h
3289
954c1994
GS
3290=item XPUSHu
3291
1c846c1f 3292Push an unsigned integer onto the stack, extending the stack if necessary.
954c1994
GS
3293See C<PUSHu>.
3294
3295 void XPUSHu(UV uv)
3296
497711e7
GS
3297=for hackers
3298Found in file pp.h
3299
954c1994
GS
3300=item XS
3301
3302Macro to declare an XSUB and its C parameter list. This is handled by
3303C<xsubpp>.
3304
497711e7
GS
3305=for hackers
3306Found in file XSUB.h
3307
954c1994
GS
3308=item XSRETURN
3309
3310Return from XSUB, indicating number of items on the stack. This is usually
3311handled by C<xsubpp>.
3312
3313 void XSRETURN(int nitems)
3314
497711e7
GS
3315=for hackers
3316Found in file XSUB.h
3317
954c1994
GS
3318=item XSRETURN_EMPTY
3319
3320Return an empty list from an XSUB immediately.
3321
3322 XSRETURN_EMPTY;
3323
497711e7
GS
3324=for hackers
3325Found in file XSUB.h
3326
954c1994
GS
3327=item XSRETURN_IV
3328
3329Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3330
3331 void XSRETURN_IV(IV iv)
3332
497711e7
GS
3333=for hackers
3334Found in file XSUB.h
3335
954c1994
GS
3336=item XSRETURN_NO
3337
3338Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3339
3340 XSRETURN_NO;
3341
497711e7
GS
3342=for hackers
3343Found in file XSUB.h
3344
954c1994
GS
3345=item XSRETURN_NV
3346
3347Return an double from an XSUB immediately. Uses C<XST_mNV>.
3348
3349 void XSRETURN_NV(NV nv)
3350
497711e7
GS
3351=for hackers
3352Found in file XSUB.h
3353
954c1994
GS
3354=item XSRETURN_PV
3355
3356Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3357
3358 void XSRETURN_PV(char* str)
3359
497711e7
GS
3360=for hackers
3361Found in file XSUB.h
3362
954c1994
GS
3363=item XSRETURN_UNDEF
3364
3365Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3366
3367 XSRETURN_UNDEF;
3368
497711e7
GS
3369=for hackers
3370Found in file XSUB.h
3371
954c1994
GS
3372=item XSRETURN_YES
3373
3374Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3375
3376 XSRETURN_YES;
3377
497711e7
GS
3378=for hackers
3379Found in file XSUB.h
3380
954c1994
GS
3381=item XST_mIV
3382
3383Place an integer into the specified position C<pos> on the stack. The
3384value is stored in a new mortal SV.
3385
3386 void XST_mIV(int pos, IV iv)
3387
497711e7
GS
3388=for hackers
3389Found in file XSUB.h
3390
954c1994
GS
3391=item XST_mNO
3392
3393Place C<&PL_sv_no> into the specified position C<pos> on the
3394stack.
3395
3396 void XST_mNO(int pos)
3397
497711e7
GS
3398=for hackers
3399Found in file XSUB.h
3400
954c1994
GS
3401=item XST_mNV
3402
3403Place a double into the specified position C<pos> on the stack. The value
3404is stored in a new mortal SV.
3405
3406 void XST_mNV(int pos, NV nv)
3407
497711e7
GS
3408=for hackers
3409Found in file XSUB.h
3410
954c1994
GS
3411=item XST_mPV
3412
3413Place a copy of a string into the specified position C<pos> on the stack.
3414The value is stored in a new mortal SV.
3415
3416 void XST_mPV(int pos, char* str)
3417
497711e7
GS
3418=for hackers
3419Found in file XSUB.h
3420
954c1994
GS
3421=item XST_mUNDEF
3422
3423Place C<&PL_sv_undef> into the specified position C<pos> on the
3424stack.
3425
3426 void XST_mUNDEF(int pos)
3427
497711e7
GS
3428=for hackers
3429Found in file XSUB.h
3430
954c1994
GS
3431=item XST_mYES
3432
3433Place C<&PL_sv_yes> into the specified position C<pos> on the
3434stack.
3435
3436 void XST_mYES(int pos)
3437
497711e7
GS
3438=for hackers
3439Found in file XSUB.h
3440
954c1994
GS
3441=item XS_VERSION
3442
3443The version identifier for an XS module. This is usually
3444handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3445
497711e7
GS
3446=for hackers
3447Found in file XSUB.h
3448
954c1994
GS
3449=item XS_VERSION_BOOTCHECK
3450
3451Macro to verify that a PM module's $VERSION variable matches the XS
3452module's C<XS_VERSION> variable. This is usually handled automatically by
3453C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3454
3455 XS_VERSION_BOOTCHECK;
3456
497711e7
GS
3457=for hackers
3458Found in file XSUB.h
3459
954c1994
GS
3460=item Zero
3461
3462The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
3463destination, C<nitems> is the number of items, and C<type> is the type.
3464
3465 void Zero(void* dest, int nitems, type)
3466
497711e7
GS
3467=for hackers
3468Found in file handy.h
3469
954c1994
GS
3470=back
3471
3472=head1 AUTHORS
3473
3474Until May 1997, this document was maintained by Jeff Okamoto
3475<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3476
3477With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3478Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3479Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3480Stephen McCamant, and Gurusamy Sarathy.
3481
3482API Listing originally by Dean Roehrich <roehrich@cray.com>.
3483
3484Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3485
3486=head1 SEE ALSO
3487
3488perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3489