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