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