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