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