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