This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
get PERL_OBJECT build going again on windows
[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
fea65482 1168Found in file op.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
fea65482 1301Found in file op.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
feb4a48f 2345=item svtype
006d23df 2346
feb4a48f
JH
2347An enum of flags for Perl types. These are found in the file B<sv.h>
2348in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
0dff5aa1 2349
1a5780eb
GS
2350=for hackers
2351Found in file sv.h
2352
feb4a48f 2353=item SvTYPE
109a0973 2354
feb4a48f
JH
2355Returns the type of the SV. See C<svtype>.
2356
2357 svtype SvTYPE(SV* sv)
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
a8ae6a0b
JH
2549Concatenates the string from SV C<ssv> onto the end of the string in
2550SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
2551not 'set' magic. See C<sv_catsv_mg>.
954c1994
GS
2552
2553 void sv_catsv(SV* dsv, SV* ssv)
2554
1a5780eb
GS
2555=for hackers
2556Found in file sv.c
2557
954c1994
GS
2558=item sv_catsv_mg
2559
2560Like C<sv_catsv>, but also handles 'set' magic.
2561
2562 void sv_catsv_mg(SV *dstr, SV *sstr)
2563
1a5780eb
GS
2564=for hackers
2565Found in file sv.c
2566
954c1994
GS
2567=item sv_chop
2568
2569Efficient removal of characters from the beginning of the string buffer.
2570SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
2571the string buffer. The C<ptr> becomes the first character of the adjusted
2572string.
2573
2574 void sv_chop(SV* sv, char* ptr)
2575
1a5780eb
GS
2576=for hackers
2577Found in file sv.c
2578
a40b7efc
HS
2579=item sv_clear
2580
2581Clear an SV, making it empty. Does not free the memory used by the SV
2582itself.
2583
2584 void sv_clear(SV* sv)
2585
2586=for hackers
2587Found in file sv.c
2588
954c1994
GS
2589=item sv_cmp
2590
2591Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2592string in C<sv1> is less than, equal to, or greater than the string in
2593C<sv2>.
2594
2595 I32 sv_cmp(SV* sv1, SV* sv2)
2596
1a5780eb
GS
2597=for hackers
2598Found in file sv.c
2599
a40b7efc
HS
2600=item sv_cmp_locale
2601
2602Compares the strings in two SVs in a locale-aware manner. See
2603L</sv_cmp_locale>
2604
2605 I32 sv_cmp_locale(SV* sv1, SV* sv2)
2606
2607=for hackers
2608Found in file sv.c
2609
954c1994
GS
2610=item sv_dec
2611
2612Auto-decrement of the value in the SV.
2613
2614 void sv_dec(SV* sv)
2615
1a5780eb
GS
2616=for hackers
2617Found in file sv.c
2618
954c1994
GS
2619=item sv_derived_from
2620
2621Returns a boolean indicating whether the SV is derived from the specified
2622class. This is the function that implements C<UNIVERSAL::isa>. It works
2623for class names as well as for objects.
2624
2625 bool sv_derived_from(SV* sv, const char* name)
2626
1a5780eb
GS
2627=for hackers
2628Found in file universal.c
2629
954c1994
GS
2630=item sv_eq
2631
2632Returns a boolean indicating whether the strings in the two SVs are
2633identical.
2634
2635 I32 sv_eq(SV* sv1, SV* sv2)
2636
1a5780eb
GS
2637=for hackers
2638Found in file sv.c
2639
a40b7efc
HS
2640=item sv_free
2641
2642Free the memory used by an SV.
2643
2644 void sv_free(SV* sv)
2645
2646=for hackers
2647Found in file sv.c
2648
2649=item sv_gets
2650
2651Get a line from the filehandle and store it into the SV, optionally
2652appending to the currently-stored string.
2653
2654 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
2655
2656=for hackers
2657Found in file sv.c
2658
954c1994
GS
2659=item sv_grow
2660
2661Expands the character buffer in the SV. This will use C<sv_unref> and will
2662upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2663Use C<SvGROW>.
2664
2665 char* sv_grow(SV* sv, STRLEN newlen)
2666
1a5780eb
GS
2667=for hackers
2668Found in file sv.c
2669
954c1994
GS
2670=item sv_inc
2671
2672Auto-increment of the value in the SV.
2673
2674 void sv_inc(SV* sv)
2675
1a5780eb
GS
2676=for hackers
2677Found in file sv.c
2678
954c1994
GS
2679=item sv_insert
2680
2681Inserts a string at the specified offset/length within the SV. Similar to
2682the Perl substr() function.
2683
2684 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2685
1a5780eb
GS
2686=for hackers
2687Found in file sv.c
2688
954c1994
GS
2689=item sv_isa
2690
2691Returns a boolean indicating whether the SV is blessed into the specified
2692class. This does not check for subtypes; use C<sv_derived_from> to verify
2693an inheritance relationship.
2694
2695 int sv_isa(SV* sv, const char* name)
2696
1a5780eb
GS
2697=for hackers
2698Found in file sv.c
2699
954c1994
GS
2700=item sv_isobject
2701
2702Returns a boolean indicating whether the SV is an RV pointing to a blessed
2703object. If the SV is not an RV, or if the object is not blessed, then this
2704will return false.
2705
2706 int sv_isobject(SV* sv)
2707
1a5780eb
GS
2708=for hackers
2709Found in file sv.c
2710
954c1994
GS
2711=item sv_len
2712
2713Returns the length of the string in the SV. See also C<SvCUR>.
2714
2715 STRLEN sv_len(SV* sv)
2716
1a5780eb
GS
2717=for hackers
2718Found in file sv.c
2719
a40b7efc
HS
2720=item sv_len_utf8
2721
2722Returns the number of characters in the string in an SV, counting wide
2723UTF8 bytes as a single character.
2724
2725 STRLEN sv_len_utf8(SV* sv)
2726
2727=for hackers
2728Found in file sv.c
2729
954c1994
GS
2730=item sv_magic
2731
2732Adds magic to an SV.
2733
2734 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2735
1a5780eb
GS
2736=for hackers
2737Found in file sv.c
2738
954c1994
GS
2739=item sv_mortalcopy
2740
2741Creates a new SV which is a copy of the original SV. The new SV is marked
2742as mortal.
2743
2744 SV* sv_mortalcopy(SV* oldsv)
2745
1a5780eb
GS
2746=for hackers
2747Found in file sv.c
2748
954c1994
GS
2749=item sv_newmortal
2750
2751Creates a new SV which is mortal. The reference count of the SV is set to 1.
2752
2753 SV* sv_newmortal()
2754
1a5780eb
GS
2755=for hackers
2756Found in file sv.c
2757
a40b7efc
HS
2758=item sv_pvn_force
2759
2760Get a sensible string out of the SV somehow.
2761
2762 char* sv_pvn_force(SV* sv, STRLEN* lp)
2763
2764=for hackers
2765Found in file sv.c
2766
2767=item sv_pvutf8n_force
2768
2769Get a sensible UTF8-encoded string out of the SV somehow. See
2770L</sv_pvn_force>.
2771
2772 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
2773
2774=for hackers
2775Found in file sv.c
2776
2777=item sv_reftype
2778
2779Returns a string describing what the SV is a reference to.
2780
2781 char* sv_reftype(SV* sv, int ob)
2782
2783=for hackers
2784Found in file sv.c
2785
2786=item sv_replace
2787
2788Make the first argument a copy of the second, then delete the original.
2789
2790 void sv_replace(SV* sv, SV* nsv)
2791
2792=for hackers
2793Found in file sv.c
2794
2795=item sv_rvweaken
2796
2797Weaken a reference.
2798
2799 SV* sv_rvweaken(SV *sv)
2800
2801=for hackers
2802Found in file sv.c
2803
954c1994
GS
2804=item sv_setiv
2805
2806Copies an integer into the given SV. Does not handle 'set' magic. See
2807C<sv_setiv_mg>.
2808
2809 void sv_setiv(SV* sv, IV num)
2810
1a5780eb
GS
2811=for hackers
2812Found in file sv.c
2813
954c1994
GS
2814=item sv_setiv_mg
2815
2816Like C<sv_setiv>, but also handles 'set' magic.
2817
2818 void sv_setiv_mg(SV *sv, IV i)
2819
1a5780eb
GS
2820=for hackers
2821Found in file sv.c
2822
954c1994
GS
2823=item sv_setnv
2824
2825Copies a double into the given SV. Does not handle 'set' magic. See
2826C<sv_setnv_mg>.
2827
2828 void sv_setnv(SV* sv, NV num)
2829
1a5780eb
GS
2830=for hackers
2831Found in file sv.c
2832
954c1994
GS
2833=item sv_setnv_mg
2834
2835Like C<sv_setnv>, but also handles 'set' magic.
2836
2837 void sv_setnv_mg(SV *sv, NV num)
2838
1a5780eb
GS
2839=for hackers
2840Found in file sv.c
2841
954c1994
GS
2842=item sv_setpv
2843
2844Copies a string into an SV. The string must be null-terminated. Does not
2845handle 'set' magic. See C<sv_setpv_mg>.
2846
2847 void sv_setpv(SV* sv, const char* ptr)
2848
1a5780eb
GS
2849=for hackers
2850Found in file sv.c
2851
954c1994
GS
2852=item sv_setpvf
2853
2854Processes its arguments like C<sprintf> and sets an SV to the formatted
2855output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
2856
2857 void sv_setpvf(SV* sv, const char* pat, ...)
2858
1a5780eb
GS
2859=for hackers
2860Found in file sv.c
2861
954c1994
GS
2862=item sv_setpvf_mg
2863
2864Like C<sv_setpvf>, but also handles 'set' magic.
2865
2866 void sv_setpvf_mg(SV *sv, const char* pat, ...)
2867
1a5780eb
GS
2868=for hackers
2869Found in file sv.c
2870
954c1994
GS
2871=item sv_setpviv
2872
2873Copies an integer into the given SV, also updating its string value.
2874Does not handle 'set' magic. See C<sv_setpviv_mg>.
2875
2876 void sv_setpviv(SV* sv, IV num)
2877
1a5780eb
GS
2878=for hackers
2879Found in file sv.c
2880
954c1994
GS
2881=item sv_setpviv_mg
2882
2883Like C<sv_setpviv>, but also handles 'set' magic.
2884
2885 void sv_setpviv_mg(SV *sv, IV iv)
2886
1a5780eb
GS
2887=for hackers
2888Found in file sv.c
2889
954c1994
GS
2890=item sv_setpvn
2891
2892Copies a string into an SV. The C<len> parameter indicates the number of
2893bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
2894
2895 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2896
1a5780eb
GS
2897=for hackers
2898Found in file sv.c
2899
954c1994
GS
2900=item sv_setpvn_mg
2901
2902Like C<sv_setpvn>, but also handles 'set' magic.
2903
2904 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2905
1a5780eb
GS
2906=for hackers
2907Found in file sv.c
2908
954c1994
GS
2909=item sv_setpv_mg
2910
2911Like C<sv_setpv>, but also handles 'set' magic.
2912
2913 void sv_setpv_mg(SV *sv, const char *ptr)
2914
1a5780eb
GS
2915=for hackers
2916Found in file sv.c
2917
954c1994
GS
2918=item sv_setref_iv
2919
2920Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2921argument will be upgraded to an RV. That RV will be modified to point to
2922the new SV. The C<classname> argument indicates the package for the
2923blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2924will be returned and will have a reference count of 1.
2925
2926 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
2927
1a5780eb
GS
2928=for hackers
2929Found in file sv.c
2930
954c1994
GS
2931=item sv_setref_nv
2932
2933Copies a double into a new SV, optionally blessing the SV. The C<rv>
2934argument will be upgraded to an RV. That RV will be modified to point to
2935the new SV. The C<classname> argument indicates the package for the
2936blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2937will be returned and will have a reference count of 1.
2938
2939 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
2940
1a5780eb
GS
2941=for hackers
2942Found in file sv.c
2943
954c1994
GS
2944=item sv_setref_pv
2945
2946Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2947argument will be upgraded to an RV. That RV will be modified to point to
2948the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2949into the SV. The C<classname> argument indicates the package for the
2950blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2951will be returned and will have a reference count of 1.
2952
2953Do not use with other Perl types such as HV, AV, SV, CV, because those
2954objects will become corrupted by the pointer copy process.
2955
2956Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2957
2958 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
2959
1a5780eb
GS
2960=for hackers
2961Found in file sv.c
2962
954c1994
GS
2963=item sv_setref_pvn
2964
2965Copies a string into a new SV, optionally blessing the SV. The length of the
2966string must be specified with C<n>. The C<rv> argument will be upgraded to
2967an RV. That RV will be modified to point to the new SV. The C<classname>
2968argument indicates the package for the blessing. Set C<classname> to
2969C<Nullch> to avoid the blessing. The new SV will be returned and will have
2970a reference count of 1.
2971
2972Note that C<sv_setref_pv> copies the pointer while this copies the string.
2973
2974 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2975
1a5780eb
GS
2976=for hackers
2977Found in file sv.c
2978
954c1994
GS
2979=item sv_setsv
2980
2981Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2982The source SV may be destroyed if it is mortal. Does not handle 'set'
2983magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
2984C<sv_setsv_mg>.
2985
2986 void sv_setsv(SV* dsv, SV* ssv)
2987
1a5780eb
GS
2988=for hackers
2989Found in file sv.c
2990
954c1994
GS
2991=item sv_setsv_mg
2992
2993Like C<sv_setsv>, but also handles 'set' magic.
2994
2995 void sv_setsv_mg(SV *dstr, SV *sstr)
2996
1a5780eb
GS
2997=for hackers
2998Found in file sv.c
2999
954c1994
GS
3000=item sv_setuv
3001
3002Copies an unsigned integer into the given SV. Does not handle 'set' magic.
3003See C<sv_setuv_mg>.
3004
3005 void sv_setuv(SV* sv, UV num)
3006
1a5780eb
GS
3007=for hackers
3008Found in file sv.c
3009
954c1994
GS
3010=item sv_setuv_mg
3011
3012Like C<sv_setuv>, but also handles 'set' magic.
3013
3014 void sv_setuv_mg(SV *sv, UV u)
3015
1a5780eb
GS
3016=for hackers
3017Found in file sv.c
3018
a40b7efc
HS
3019=item sv_true
3020
3021Returns true if the SV has a true value by Perl's rules.
3022
3023 I32 sv_true(SV *sv)
3024
3025=for hackers
3026Found in file sv.c
3027
3028=item sv_unmagic
3029
3030Removes magic from an SV.
3031
3032 int sv_unmagic(SV* sv, int type)
3033
3034=for hackers
3035Found in file sv.c
3036
954c1994
GS
3037=item sv_unref
3038
3039Unsets the RV status of the SV, and decrements the reference count of
3040whatever was being referenced by the RV. This can almost be thought of
3041as a reversal of C<newSVrv>. See C<SvROK_off>.
3042
3043 void sv_unref(SV* sv)
3044
1a5780eb
GS
3045=for hackers
3046Found in file sv.c
3047
954c1994
GS
3048=item sv_upgrade
3049
3050Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
3051C<svtype>.
3052
3053 bool sv_upgrade(SV* sv, U32 mt)
3054
1a5780eb
GS
3055=for hackers
3056Found in file sv.c
3057
954c1994
GS
3058=item sv_usepvn
3059
3060Tells an SV to use C<ptr> to find its string value. Normally the string is
3061stored inside the SV but sv_usepvn allows the SV to use an outside string.
3062The C<ptr> should point to memory that was allocated by C<malloc>. The
3063string length, C<len>, must be supplied. This function will realloc the
3064memory pointed to by C<ptr>, so that pointer should not be freed or used by
3065the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
3066See C<sv_usepvn_mg>.
3067
3068 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
3069
1a5780eb
GS
3070=for hackers
3071Found in file sv.c
3072
954c1994
GS
3073=item sv_usepvn_mg
3074
3075Like C<sv_usepvn>, but also handles 'set' magic.
3076
3077 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3078
1a5780eb
GS
3079=for hackers
3080Found in file sv.c
3081
a40b7efc
HS
3082=item sv_utf8_downgrade
3083
3084Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3085This may not be possible if the PV contains non-byte encoding characters;
3086if this is the case, either returns false or, if C<fail_ok> is not
3087true, croaks.
3088
3089NOTE: this function is experimental and may change or be
3090removed without notice.
3091
3092 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
3093
3094=for hackers
3095Found in file sv.c
3096
3097=item sv_utf8_encode
3098
3099Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
3100flag so that it looks like bytes again. Nothing calls this.
3101
3102NOTE: this function is experimental and may change or be
3103removed without notice.
3104
3105 void sv_utf8_encode(SV *sv)
3106
3107=for hackers
3108Found in file sv.c
3109
3110=item sv_utf8_upgrade
3111
3112Convert the PV of an SV to its UTF8-encoded form.
3113
3114 void sv_utf8_upgrade(SV *sv)
3115
3116=for hackers
3117Found in file sv.c
3118
954c1994
GS
3119=item sv_vcatpvfn
3120
3121Processes its arguments like C<vsprintf> and appends the formatted output
3122to an SV. Uses an array of SVs if the C style variable argument list is
3123missing (NULL). When running with taint checks enabled, indicates via
3124C<maybe_tainted> if results are untrustworthy (often due to the use of
3125locales).
3126
3127 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3128
1a5780eb
GS
3129=for hackers
3130Found in file sv.c
3131
954c1994
GS
3132=item sv_vsetpvfn
3133
3134Works like C<vcatpvfn> but copies the text into the SV instead of
3135appending it.
3136
3137 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3138
1a5780eb
GS
3139=for hackers
3140Found in file sv.c
3141
954c1994
GS
3142=item THIS
3143
3144Variable which is setup by C<xsubpp> to designate the object in a C++
3145XSUB. This is always the proper type for the C++ object. See C<CLASS> and
3146L<perlxs/"Using XS With C++">.
3147
3148 (whatever) THIS
3149
1a5780eb
GS
3150=for hackers
3151Found in file XSUB.h
3152
954c1994
GS
3153=item toLOWER
3154
3155Converts the specified character to lowercase.
3156
3157 char toLOWER(char ch)
3158
1a5780eb
GS
3159=for hackers
3160Found in file handy.h
3161
954c1994
GS
3162=item toUPPER
3163
3164Converts the specified character to uppercase.
3165
3166 char toUPPER(char ch)
3167
1a5780eb
GS
3168=for hackers
3169Found in file handy.h
3170
fe406c08
GS
3171=item U8 *s
3172
3173Returns true if first C<len> bytes of the given string form valid a UTF8
3174string, false otherwise.
3175
d6f4130b 3176 is_utf8_string U8 *s(STRLEN len)
fe406c08
GS
3177
3178=for hackers
3179Found in file utf8.c
3180
feb4a48f
JH
3181=item utf8_distance
3182
3183Returns the number of UTF8 characters between the UTF-8 pointers C<a>
3184and C<b>.
3185
3186WARNING: use only if you *know* that the pointers point inside the
3187same UTF-8 buffer.
3188
3189 IV utf8_distance(U8 *a, U8 *b)
3190
3191=for hackers
3192Found in file utf8.c
3193
3194=item utf8_hop
3195
3196Return the UTF-8 pointer C<s> displaced by C<off> characters, either
3197forward or backward.
3198
3199WARNING: do not use the following unless you *know* C<off> is within
3200the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
3201on the first byte of character or just after the last byte of a character.
3202
3203 U8* utf8_hop(U8 *s, I32 off)
3204
3205=for hackers
3206Found in file utf8.c
3207
3208=item utf8_length
3209
3210Return the length of the UTF-8 char encoded string C<s> in characters.
3211Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
3212up past C<e>, croaks.
3213
3214 STRLEN utf8_length(U8* s, U8 *e)
3215
3216=for hackers
3217Found in file utf8.c
3218
1a5780eb
GS
3219=item utf8_to_bytes
3220
79d2a3c4
GS
3221Converts a string C<s> of length C<len> from UTF8 into byte encoding.
3222Unlike C<bytes_to_utf8>, this over-writes the original string, and
3223updates len to contain the new length.
72d299db 3224Returns zero on failure, setting C<len> to -1.
1a5780eb 3225
79d2a3c4 3226 U8 * utf8_to_bytes(U8 *s, STRLEN *len)
1a5780eb
GS
3227
3228=for hackers
3229Found in file utf8.c
3230
72d299db
GS
3231=item utf8_to_uv
3232
3233Returns the character value of the first character in the string C<s>
a4bf32d5 3234which is assumed to be in UTF8 encoding and no longer than C<curlen>;
a8ae6a0b 3235C<retlen> will be set to the length, in bytes, of that character.
72d299db 3236
a4bf32d5 3237If C<s> does not point to a well-formed UTF8 character, the behaviour
109a0973
GS
3238is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
3239it is assumed that the caller will raise a warning, and this function
feb4a48f
JH
3240will silently just set C<retlen> to C<-1> and return zero. If the
3241C<flags> does not contain UTF8_CHECK_ONLY, warnings about
3242malformations will be given, C<retlen> will be set to the expected
3243length of the UTF-8 character in bytes, and zero will be returned.
3244
3245The C<flags> can also contain various flags to allow deviations from
3246the strict UTF-8 encoding (see F<utf8.h>).
72d299db 3247
da27fb41 3248 U8* s utf8_to_uv(STRLEN curlen, STRLEN *retlen, U32 flags)
72d299db
GS
3249
3250=for hackers
3251Found in file utf8.c
3252
a4bf32d5 3253=item utf8_to_uv_simple
72d299db
GS
3254
3255Returns the character value of the first character in the string C<s>
3256which is assumed to be in UTF8 encoding; C<retlen> will be set to the
a8ae6a0b 3257length, in bytes, of that character.
72d299db 3258
a4bf32d5
A
3259If C<s> does not point to a well-formed UTF8 character, zero is
3260returned and retlen is set, if possible, to -1.
72d299db 3261
a4bf32d5 3262 U8* s utf8_to_uv_simple(STRLEN *retlen)
72d299db
GS
3263
3264=for hackers
3265Found in file utf8.c
3266
954c1994
GS
3267=item warn
3268
3269This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3270function the same way you use the C C<printf> function. See
3271C<croak>.
3272
3273 void warn(const char* pat, ...)
3274
1a5780eb
GS
3275=for hackers
3276Found in file util.c
3277
954c1994
GS
3278=item XPUSHi
3279
3280Push an integer onto the stack, extending the stack if necessary. Handles
3281'set' magic. See C<PUSHi>.
3282
3283 void XPUSHi(IV iv)
3284
1a5780eb
GS
3285=for hackers
3286Found in file pp.h
3287
954c1994
GS
3288=item XPUSHn
3289
3290Push a double onto the stack, extending the stack if necessary. Handles
3291'set' magic. See C<PUSHn>.
3292
3293 void XPUSHn(NV nv)
3294
1a5780eb
GS
3295=for hackers
3296Found in file pp.h
3297
954c1994
GS
3298=item XPUSHp
3299
3300Push a string onto the stack, extending the stack if necessary. The C<len>
3301indicates the length of the string. Handles 'set' magic. See
3302C<PUSHp>.
3303
3304 void XPUSHp(char* str, STRLEN len)
3305
1a5780eb
GS
3306=for hackers
3307Found in file pp.h
3308
954c1994
GS
3309=item XPUSHs
3310
3311Push an SV onto the stack, extending the stack if necessary. Does not
3312handle 'set' magic. See C<PUSHs>.
3313
3314 void XPUSHs(SV* sv)
3315
1a5780eb
GS
3316=for hackers
3317Found in file pp.h
3318
954c1994
GS
3319=item XPUSHu
3320
109a0973 3321Push an unsigned integer onto the stack, extending the stack if necessary.
954c1994
GS
3322See C<PUSHu>.
3323
3324 void XPUSHu(UV uv)
3325
1a5780eb
GS
3326=for hackers
3327Found in file pp.h
3328
954c1994
GS
3329=item XS
3330
3331Macro to declare an XSUB and its C parameter list. This is handled by
3332C<xsubpp>.
3333
1a5780eb
GS
3334=for hackers
3335Found in file XSUB.h
3336
954c1994
GS
3337=item XSRETURN
3338
3339Return from XSUB, indicating number of items on the stack. This is usually
3340handled by C<xsubpp>.
3341
3342 void XSRETURN(int nitems)
3343
1a5780eb
GS
3344=for hackers
3345Found in file XSUB.h
3346
954c1994
GS
3347=item XSRETURN_EMPTY
3348
3349Return an empty list from an XSUB immediately.
3350
3351 XSRETURN_EMPTY;
3352
1a5780eb
GS
3353=for hackers
3354Found in file XSUB.h
3355
954c1994
GS
3356=item XSRETURN_IV
3357
3358Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3359
3360 void XSRETURN_IV(IV iv)
3361
1a5780eb
GS
3362=for hackers
3363Found in file XSUB.h
3364
954c1994
GS
3365=item XSRETURN_NO
3366
3367Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3368
3369 XSRETURN_NO;
3370
1a5780eb
GS
3371=for hackers
3372Found in file XSUB.h
3373
954c1994
GS
3374=item XSRETURN_NV
3375
3376Return an double from an XSUB immediately. Uses C<XST_mNV>.
3377
3378 void XSRETURN_NV(NV nv)
3379
1a5780eb
GS
3380=for hackers
3381Found in file XSUB.h
3382
954c1994
GS
3383=item XSRETURN_PV
3384
3385Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3386
3387 void XSRETURN_PV(char* str)
3388
1a5780eb
GS
3389=for hackers
3390Found in file XSUB.h
3391
954c1994
GS
3392=item XSRETURN_UNDEF
3393
3394Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3395
3396 XSRETURN_UNDEF;
3397
1a5780eb
GS
3398=for hackers
3399Found in file XSUB.h
3400
954c1994
GS
3401=item XSRETURN_YES
3402
3403Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3404
3405 XSRETURN_YES;
3406
1a5780eb
GS
3407=for hackers
3408Found in file XSUB.h
3409
954c1994
GS
3410=item XST_mIV
3411
3412Place an integer into the specified position C<pos> on the stack. The
3413value is stored in a new mortal SV.
3414
3415 void XST_mIV(int pos, IV iv)
3416
1a5780eb
GS
3417=for hackers
3418Found in file XSUB.h
3419
954c1994
GS
3420=item XST_mNO
3421
3422Place C<&PL_sv_no> into the specified position C<pos> on the
3423stack.
3424
3425 void XST_mNO(int pos)
3426
1a5780eb
GS
3427=for hackers
3428Found in file XSUB.h
3429
954c1994
GS
3430=item XST_mNV
3431
3432Place a double into the specified position C<pos> on the stack. The value
3433is stored in a new mortal SV.
3434
3435 void XST_mNV(int pos, NV nv)
3436
1a5780eb
GS
3437=for hackers
3438Found in file XSUB.h
3439
954c1994
GS
3440=item XST_mPV
3441
3442Place a copy of a string into the specified position C<pos> on the stack.
3443The value is stored in a new mortal SV.
3444
3445 void XST_mPV(int pos, char* str)
3446
1a5780eb
GS
3447=for hackers
3448Found in file XSUB.h
3449
954c1994
GS
3450=item XST_mUNDEF
3451
3452Place C<&PL_sv_undef> into the specified position C<pos> on the
3453stack.
3454
3455 void XST_mUNDEF(int pos)
3456
1a5780eb
GS
3457=for hackers
3458Found in file XSUB.h
3459
954c1994
GS
3460=item XST_mYES
3461
3462Place C<&PL_sv_yes> into the specified position C<pos> on the
3463stack.
3464
3465 void XST_mYES(int pos)
3466
1a5780eb
GS
3467=for hackers
3468Found in file XSUB.h
3469
954c1994
GS
3470=item XS_VERSION
3471
3472The version identifier for an XS module. This is usually
3473handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3474
1a5780eb
GS
3475=for hackers
3476Found in file XSUB.h
3477
954c1994
GS
3478=item XS_VERSION_BOOTCHECK
3479
3480Macro to verify that a PM module's $VERSION variable matches the XS
3481module's C<XS_VERSION> variable. This is usually handled automatically by
3482C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3483
3484 XS_VERSION_BOOTCHECK;
3485
1a5780eb
GS
3486=for hackers
3487Found in file XSUB.h
3488
954c1994
GS
3489=item Zero
3490
3491The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
3492destination, C<nitems> is the number of items, and C<type> is the type.
3493
3494 void Zero(void* dest, int nitems, type)
3495
1a5780eb
GS
3496=for hackers
3497Found in file handy.h
3498
954c1994
GS
3499=back
3500
3501=head1 AUTHORS
3502
3503Until May 1997, this document was maintained by Jeff Okamoto
3504<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3505
3506With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3507Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3508Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3509Stephen McCamant, and Gurusamy Sarathy.
3510
3511API Listing originally by Dean Roehrich <roehrich@cray.com>.
3512
3513Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3514
3515=head1 SEE ALSO
3516
3517perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3518