This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Version object patch #1
[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
21 =head1 "Gimme" Values
22
23 =over 8
24
25 =item GIMME
26
27 A backward-compatible version of C<GIMME_V> which can only return
28 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
29 Deprecated.  Use C<GIMME_V> instead.
30
31         U32     GIMME
32
33 =for hackers
34 Found in file op.h
35
36 =item GIMME_V
37
38 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
39 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
40 respectively.
41
42         U32     GIMME_V
43
44 =for hackers
45 Found in file op.h
46
47 =item G_ARRAY
48
49 Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
50 L<perlcall>.
51
52 =for hackers
53 Found in file cop.h
54
55 =item G_DISCARD
56
57 Indicates that arguments returned from a callback should be discarded.  See
58 L<perlcall>.
59
60 =for hackers
61 Found in file cop.h
62
63 =item G_EVAL
64
65 Used to force a Perl C<eval> wrapper around a callback.  See
66 L<perlcall>.
67
68 =for hackers
69 Found in file cop.h
70
71 =item G_NOARGS
72
73 Indicates that no arguments are being sent to a callback.  See
74 L<perlcall>.
75
76 =for hackers
77 Found in file cop.h
78
79 =item G_SCALAR
80
81 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
82 L<perlcall>.
83
84 =for hackers
85 Found in file cop.h
86
87 =item G_VOID
88
89 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
90
91 =for hackers
92 Found in file cop.h
93
94
95 =back
96
97 =head1 Array Manipulation Functions
98
99 =over 8
100
101 =item AvFILL
102
103 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
104
105         int     AvFILL(AV* av)
106
107 =for hackers
108 Found in file av.h
109
110 =item av_clear
111
112 Clears an array, making it empty.  Does not free the memory used by the
113 array itself.
114
115         void    av_clear(AV* ar)
116
117 =for hackers
118 Found in file av.c
119
120 =item av_delete
121
122 Deletes the element indexed by C<key> from the array.  Returns the
123 deleted element. C<flags> is currently ignored.
124
125         SV*     av_delete(AV* ar, I32 key, I32 flags)
126
127 =for hackers
128 Found in file av.c
129
130 =item av_exists
131
132 Returns true if the element indexed by C<key> has been initialized.
133
134 This relies on the fact that uninitialized array elements are set to
135 C<&PL_sv_undef>.
136
137         bool    av_exists(AV* ar, I32 key)
138
139 =for hackers
140 Found in file av.c
141
142 =item av_extend
143
144 Pre-extend an array.  The C<key> is the index to which the array should be
145 extended.
146
147         void    av_extend(AV* ar, I32 key)
148
149 =for hackers
150 Found in file av.c
151
152 =item av_fetch
153
154 Returns the SV at the specified index in the array.  The C<key> is the
155 index.  If C<lval> is set then the fetch will be part of a store.  Check
156 that the return value is non-null before dereferencing it to a C<SV*>.
157
158 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
159 more information on how to use this function on tied arrays. 
160
161         SV**    av_fetch(AV* ar, I32 key, I32 lval)
162
163 =for hackers
164 Found in file av.c
165
166 =item av_fill
167
168 Ensure than an array has a given number of elements, equivalent to
169 Perl's C<$#array = $fill;>.
170
171         void    av_fill(AV* ar, I32 fill)
172
173 =for hackers
174 Found in file av.c
175
176 =item av_len
177
178 Returns the highest index in the array.  Returns -1 if the array is
179 empty.
180
181         I32     av_len(AV* ar)
182
183 =for hackers
184 Found in file av.c
185
186 =item av_make
187
188 Creates a new AV and populates it with a list of SVs.  The SVs are copied
189 into the array, so they may be freed after the call to av_make.  The new AV
190 will have a reference count of 1.
191
192         AV*     av_make(I32 size, SV** svp)
193
194 =for hackers
195 Found in file av.c
196
197 =item av_pop
198
199 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
200 is empty.
201
202         SV*     av_pop(AV* ar)
203
204 =for hackers
205 Found in file av.c
206
207 =item av_push
208
209 Pushes an SV onto the end of the array.  The array will grow automatically
210 to accommodate the addition.
211
212         void    av_push(AV* ar, SV* val)
213
214 =for hackers
215 Found in file av.c
216
217 =item av_shift
218
219 Shifts an SV off the beginning of the array.
220
221         SV*     av_shift(AV* ar)
222
223 =for hackers
224 Found in file av.c
225
226 =item av_store
227
228 Stores an SV in an array.  The array index is specified as C<key>.  The
229 return value will be NULL if the operation failed or if the value did not
230 need to be actually stored within the array (as in the case of tied
231 arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
232 that the caller is responsible for suitably incrementing the reference
233 count of C<val> before the call, and decrementing it if the function
234 returned NULL.
235
236 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
237 more information on how to use this function on tied arrays.
238
239         SV**    av_store(AV* ar, I32 key, SV* val)
240
241 =for hackers
242 Found in file av.c
243
244 =item av_undef
245
246 Undefines the array.  Frees the memory used by the array itself.
247
248         void    av_undef(AV* ar)
249
250 =for hackers
251 Found in file av.c
252
253 =item av_unshift
254
255 Unshift the given number of C<undef> values onto the beginning of the
256 array.  The array will grow automatically to accommodate the addition.  You
257 must then use C<av_store> to assign values to these new elements.
258
259         void    av_unshift(AV* ar, I32 num)
260
261 =for hackers
262 Found in file av.c
263
264 =item get_av
265
266 Returns the AV of the specified Perl array.  If C<create> is set and the
267 Perl variable does not exist then it will be created.  If C<create> is not
268 set and the variable does not exist then NULL is returned.
269
270 NOTE: the perl_ form of this function is deprecated.
271
272         AV*     get_av(const char* name, I32 create)
273
274 =for hackers
275 Found in file perl.c
276
277 =item newAV
278
279 Creates a new AV.  The reference count is set to 1.
280
281         AV*     newAV()
282
283 =for hackers
284 Found in file av.c
285
286 =item Nullav
287
288 Null AV pointer.
289
290
291 =for hackers
292 Found in file av.h
293
294 =item sortsv
295
296 Sort an array. Here is an example:
297
298     sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
299
300 See lib/sort.pm for details about controlling the sorting algorithm.
301
302         void    sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
303
304 =for hackers
305 Found in file pp_sort.c
306
307
308 =back
309
310 =head1 Callback Functions
311
312 =over 8
313
314 =item call_argv
315
316 Performs a callback to the specified Perl sub.  See L<perlcall>.
317
318 NOTE: the perl_ form of this function is deprecated.
319
320         I32     call_argv(const char* sub_name, I32 flags, char** argv)
321
322 =for hackers
323 Found in file perl.c
324
325 =item call_method
326
327 Performs a callback to the specified Perl method.  The blessed object must
328 be on the stack.  See L<perlcall>.
329
330 NOTE: the perl_ form of this function is deprecated.
331
332         I32     call_method(const char* methname, I32 flags)
333
334 =for hackers
335 Found in file perl.c
336
337 =item call_pv
338
339 Performs a callback to the specified Perl sub.  See L<perlcall>.
340
341 NOTE: the perl_ form of this function is deprecated.
342
343         I32     call_pv(const char* sub_name, I32 flags)
344
345 =for hackers
346 Found in file perl.c
347
348 =item call_sv
349
350 Performs a callback to the Perl sub whose name is in the SV.  See
351 L<perlcall>.
352
353 NOTE: the perl_ form of this function is deprecated.
354
355         I32     call_sv(SV* sv, I32 flags)
356
357 =for hackers
358 Found in file perl.c
359
360 =item ENTER
361
362 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
363
364                 ENTER;
365
366 =for hackers
367 Found in file scope.h
368
369 =item eval_pv
370
371 Tells Perl to C<eval> the given string and return an SV* result.
372
373 NOTE: the perl_ form of this function is deprecated.
374
375         SV*     eval_pv(const char* p, I32 croak_on_error)
376
377 =for hackers
378 Found in file perl.c
379
380 =item eval_sv
381
382 Tells Perl to C<eval> the string in the SV.
383
384 NOTE: the perl_ form of this function is deprecated.
385
386         I32     eval_sv(SV* sv, I32 flags)
387
388 =for hackers
389 Found in file perl.c
390
391 =item FREETMPS
392
393 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
394 L<perlcall>.
395
396                 FREETMPS;
397
398 =for hackers
399 Found in file scope.h
400
401 =item LEAVE
402
403 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
404
405                 LEAVE;
406
407 =for hackers
408 Found in file scope.h
409
410 =item SAVETMPS
411
412 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
413 L<perlcall>.
414
415                 SAVETMPS;
416
417 =for hackers
418 Found in file scope.h
419
420
421 =back
422
423 =head1 Character classes
424
425 =over 8
426
427 =item isALNUM
428
429 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
430 character (including underscore) or digit.
431
432         bool    isALNUM(char ch)
433
434 =for hackers
435 Found in file handy.h
436
437 =item isALPHA
438
439 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
440 character.
441
442         bool    isALPHA(char ch)
443
444 =for hackers
445 Found in file handy.h
446
447 =item isDIGIT
448
449 Returns a boolean indicating whether the C C<char> is an ASCII
450 digit.
451
452         bool    isDIGIT(char ch)
453
454 =for hackers
455 Found in file handy.h
456
457 =item isLOWER
458
459 Returns a boolean indicating whether the C C<char> is a lowercase
460 character.
461
462         bool    isLOWER(char ch)
463
464 =for hackers
465 Found in file handy.h
466
467 =item isSPACE
468
469 Returns a boolean indicating whether the C C<char> is whitespace.
470
471         bool    isSPACE(char ch)
472
473 =for hackers
474 Found in file handy.h
475
476 =item isUPPER
477
478 Returns a boolean indicating whether the C C<char> is an uppercase
479 character.
480
481         bool    isUPPER(char ch)
482
483 =for hackers
484 Found in file handy.h
485
486 =item toLOWER
487
488 Converts the specified character to lowercase.
489
490         char    toLOWER(char ch)
491
492 =for hackers
493 Found in file handy.h
494
495 =item toUPPER
496
497 Converts the specified character to uppercase.
498
499         char    toUPPER(char ch)
500
501 =for hackers
502 Found in file handy.h
503
504
505 =back
506
507 =head1 Cloning an interpreter
508
509 =over 8
510
511 =item perl_clone
512
513 Create and return a new interpreter by cloning the current one.
514
515         PerlInterpreter*        perl_clone(PerlInterpreter* interp, UV flags)
516
517 =for hackers
518 Found in file sv.c
519
520
521 =back
522
523 =head1 CV Manipulation Functions
524
525 =over 8
526
527 =item CvSTASH
528
529 Returns the stash of the CV.
530
531         HV*     CvSTASH(CV* cv)
532
533 =for hackers
534 Found in file cv.h
535
536 =item get_cv
537
538 Returns the CV of the specified Perl subroutine.  If C<create> is set and
539 the Perl subroutine does not exist then it will be declared (which has the
540 same effect as saying C<sub name;>).  If C<create> is not set and the
541 subroutine does not exist then NULL is returned.
542
543 NOTE: the perl_ form of this function is deprecated.
544
545         CV*     get_cv(const char* name, I32 create)
546
547 =for hackers
548 Found in file perl.c
549
550 =item Nullcv
551
552 Null CV pointer.
553
554
555 =for hackers
556 Found in file cv.h
557
558
559 =back
560
561 =head1 Embedding Functions
562
563 =over 8
564
565 =item load_module
566
567 Loads the module whose name is pointed to by the string part of name.
568 Note that the actual module name, not its filename, should be given.
569 Eg, "Foo::Bar" instead of "Foo/Bar.pm".  flags can be any of
570 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
571 (or 0 for no flags). ver, if specified, provides version semantics
572 similar to C<use Foo::Bar VERSION>.  The optional trailing SV*
573 arguments can be used to specify arguments to the module's import()
574 method, similar to C<use Foo::Bar VERSION LIST>.
575
576         void    load_module(U32 flags, SV* name, SV* ver, ...)
577
578 =for hackers
579 Found in file op.c
580
581 =item nothreadhook
582
583 Stub that provides thread hook for perl_destruct when there are
584 no threads.
585
586         int     nothreadhook()
587
588 =for hackers
589 Found in file perl.c
590
591 =item perl_alloc
592
593 Allocates a new Perl interpreter.  See L<perlembed>.
594
595         PerlInterpreter*        perl_alloc()
596
597 =for hackers
598 Found in file perl.c
599
600 =item perl_construct
601
602 Initializes a new Perl interpreter.  See L<perlembed>.
603
604         void    perl_construct(PerlInterpreter* interp)
605
606 =for hackers
607 Found in file perl.c
608
609 =item perl_destruct
610
611 Shuts down a Perl interpreter.  See L<perlembed>.
612
613         int     perl_destruct(PerlInterpreter* interp)
614
615 =for hackers
616 Found in file perl.c
617
618 =item perl_free
619
620 Releases a Perl interpreter.  See L<perlembed>.
621
622         void    perl_free(PerlInterpreter* interp)
623
624 =for hackers
625 Found in file perl.c
626
627 =item perl_parse
628
629 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
630
631         int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
632
633 =for hackers
634 Found in file perl.c
635
636 =item perl_run
637
638 Tells a Perl interpreter to run.  See L<perlembed>.
639
640         int     perl_run(PerlInterpreter* interp)
641
642 =for hackers
643 Found in file perl.c
644
645 =item require_pv
646
647 Tells Perl to C<require> the file named by the string argument.  It is
648 analogous to the Perl code C<eval "require '$file'">.  It's even
649 implemented that way; consider using Perl_load_module instead.
650
651 NOTE: the perl_ form of this function is deprecated.
652
653         void    require_pv(const char* pv)
654
655 =for hackers
656 Found in file perl.c
657
658
659 =back
660
661 =head1 Functions in file pp_pack.c
662
663
664 =over 8
665
666 =item pack_cat
667
668 The engine implementing pack() Perl function.
669
670         void    pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
671
672 =for hackers
673 Found in file pp_pack.c
674
675 =item unpack_str
676
677 The engine implementing unpack() Perl function.
678
679         I32     unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
680
681 =for hackers
682 Found in file pp_pack.c
683
684
685 =back
686
687 =head1 Global Variables
688
689 =over 8
690
691 =item PL_modglobal
692
693 C<PL_modglobal> is a general purpose, interpreter global HV for use by
694 extensions that need to keep information on a per-interpreter basis.
695 In a pinch, it can also be used as a symbol table for extensions
696 to share data among each other.  It is a good idea to use keys
697 prefixed by the package name of the extension that owns the data.
698
699         HV*     PL_modglobal
700
701 =for hackers
702 Found in file intrpvar.h
703
704 =item PL_na
705
706 A convenience variable which is typically used with C<SvPV> when one
707 doesn't care about the length of the string.  It is usually more efficient
708 to either declare a local variable and use that instead or to use the
709 C<SvPV_nolen> macro.
710
711         STRLEN  PL_na
712
713 =for hackers
714 Found in file thrdvar.h
715
716 =item PL_sv_no
717
718 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
719 C<&PL_sv_no>.
720
721         SV      PL_sv_no
722
723 =for hackers
724 Found in file intrpvar.h
725
726 =item PL_sv_undef
727
728 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
729
730         SV      PL_sv_undef
731
732 =for hackers
733 Found in file intrpvar.h
734
735 =item PL_sv_yes
736
737 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
738 C<&PL_sv_yes>.
739
740         SV      PL_sv_yes
741
742 =for hackers
743 Found in file intrpvar.h
744
745
746 =back
747
748 =head1 GV Functions
749
750 =over 8
751
752 =item GvSV
753
754 Return the SV from the GV.
755
756         SV*     GvSV(GV* gv)
757
758 =for hackers
759 Found in file gv.h
760
761 =item gv_fetchmeth
762
763 Returns the glob with the given C<name> and a defined subroutine or
764 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
765 accessible via @ISA and UNIVERSAL::.
766
767 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
768 side-effect creates a glob with the given C<name> in the given C<stash>
769 which in the case of success contains an alias for the subroutine, and sets
770 up caching info for this glob.  Similarly for all the searched stashes.
771
772 This function grants C<"SUPER"> token as a postfix of the stash name. The
773 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
774 visible to Perl code.  So when calling C<call_sv>, you should not use
775 the GV directly; instead, you should use the method's CV, which can be
776 obtained from the GV with the C<GvCV> macro.
777
778         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
779
780 =for hackers
781 Found in file gv.c
782
783 =item gv_fetchmethod
784
785 See L<gv_fetchmethod_autoload>.
786
787         GV*     gv_fetchmethod(HV* stash, const char* name)
788
789 =for hackers
790 Found in file gv.c
791
792 =item gv_fetchmethod_autoload
793
794 Returns the glob which contains the subroutine to call to invoke the method
795 on the C<stash>.  In fact in the presence of autoloading this may be the
796 glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
797 already setup.
798
799 The third parameter of C<gv_fetchmethod_autoload> determines whether
800 AUTOLOAD lookup is performed if the given method is not present: non-zero
801 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
802 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
803 with a non-zero C<autoload> parameter.
804
805 These functions grant C<"SUPER"> token as a prefix of the method name. Note
806 that if you want to keep the returned glob for a long time, you need to
807 check for it being "AUTOLOAD", since at the later time the call may load a
808 different subroutine due to $AUTOLOAD changing its value. Use the glob
809 created via a side effect to do this.
810
811 These functions have the same side-effects and as C<gv_fetchmeth> with
812 C<level==0>.  C<name> should be writable if contains C<':'> or C<'
813 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
814 C<call_sv> apply equally to these functions.
815
816         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
817
818 =for hackers
819 Found in file gv.c
820
821 =item gv_fetchmeth_autoload
822
823 Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
824 Returns a glob for the subroutine.
825
826 For an autoloaded subroutine without a GV, will create a GV even
827 if C<level < 0>.  For an autoloaded subroutine without a stub, GvCV()
828 of the result may be zero.
829
830         GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
831
832 =for hackers
833 Found in file gv.c
834
835 =item gv_stashpv
836
837 Returns a pointer to the stash for a specified package.  C<name> should
838 be a valid UTF-8 string.  If C<create> is set then the package will be
839 created if it does not already exist.  If C<create> is not set and the
840 package does not exist then NULL is returned.
841
842         HV*     gv_stashpv(const char* name, I32 create)
843
844 =for hackers
845 Found in file gv.c
846
847 =item gv_stashsv
848
849 Returns a pointer to the stash for a specified package, which must be a
850 valid UTF-8 string.  See C<gv_stashpv>.
851
852         HV*     gv_stashsv(SV* sv, I32 create)
853
854 =for hackers
855 Found in file gv.c
856
857
858 =back
859
860 =head1 Handy Values
861
862 =over 8
863
864 =item HEf_SVKEY
865
866 This flag, used in the length slot of hash entries and magic structures,
867 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
868 is to be expected. (For information only--not to be used).
869
870
871 =for hackers
872 Found in file hv.h
873
874 =item Nullch 
875
876 Null character pointer.
877 =for hackers
878 Found in file handy.h
879
880 =item Nullsv
881
882 Null SV pointer.
883
884 =for hackers
885 Found in file handy.h
886
887
888 =back
889
890 =head1 Hash Manipulation Functions
891
892 =over 8
893
894 =item get_hv
895
896 Returns the HV of the specified Perl hash.  If C<create> is set and the
897 Perl variable does not exist then it will be created.  If C<create> is not
898 set and the variable does not exist then NULL is returned.
899
900 NOTE: the perl_ form of this function is deprecated.
901
902         HV*     get_hv(const char* name, I32 create)
903
904 =for hackers
905 Found in file perl.c
906
907 =item HeHASH
908
909 Returns the computed hash stored in the hash entry.
910
911         U32     HeHASH(HE* he)
912
913 =for hackers
914 Found in file hv.h
915
916 =item HeKEY
917
918 Returns the actual pointer stored in the key slot of the hash entry. The
919 pointer may be either C<char*> or C<SV*>, depending on the value of
920 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
921 usually preferable for finding the value of a key.
922
923         void*   HeKEY(HE* he)
924
925 =for hackers
926 Found in file hv.h
927
928 =item HeKLEN
929
930 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
931 holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
932 be assigned to. The C<HePV()> macro is usually preferable for finding key
933 lengths.
934
935         STRLEN  HeKLEN(HE* he)
936
937 =for hackers
938 Found in file hv.h
939
940 =item HePV
941
942 Returns the key slot of the hash entry as a C<char*> value, doing any
943 necessary dereferencing of possibly C<SV*> keys.  The length of the string
944 is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
945 not care about what the length of the key is, you may use the global
946 variable C<PL_na>, though this is rather less efficient than using a local
947 variable.  Remember though, that hash keys in perl are free to contain
948 embedded nulls, so using C<strlen()> or similar is not a good way to find
949 the length of hash keys. This is very similar to the C<SvPV()> macro
950 described elsewhere in this document.
951
952         char*   HePV(HE* he, STRLEN len)
953
954 =for hackers
955 Found in file hv.h
956
957 =item HeSVKEY
958
959 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
960 contain an C<SV*> key.
961
962         SV*     HeSVKEY(HE* he)
963
964 =for hackers
965 Found in file hv.h
966
967 =item HeSVKEY_force
968
969 Returns the key as an C<SV*>.  Will create and return a temporary mortal
970 C<SV*> if the hash entry contains only a C<char*> key.
971
972         SV*     HeSVKEY_force(HE* he)
973
974 =for hackers
975 Found in file hv.h
976
977 =item HeSVKEY_set
978
979 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
980 indicate the presence of an C<SV*> key, and returns the same
981 C<SV*>.
982
983         SV*     HeSVKEY_set(HE* he, SV* sv)
984
985 =for hackers
986 Found in file hv.h
987
988 =item HeVAL
989
990 Returns the value slot (type C<SV*>) stored in the hash entry.
991
992         SV*     HeVAL(HE* he)
993
994 =for hackers
995 Found in file hv.h
996
997 =item HvNAME
998
999 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
1000
1001         char*   HvNAME(HV* stash)
1002
1003 =for hackers
1004 Found in file hv.h
1005
1006 =item hv_clear
1007
1008 Clears a hash, making it empty.
1009
1010         void    hv_clear(HV* tb)
1011
1012 =for hackers
1013 Found in file hv.c
1014
1015 =item hv_delete
1016
1017 Deletes a key/value pair in the hash.  The value SV is removed from the
1018 hash and returned to the caller.  The C<klen> is the length of the key.
1019 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1020 will be returned.
1021
1022         SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
1023
1024 =for hackers
1025 Found in file hv.c
1026
1027 =item hv_delete_ent
1028
1029 Deletes a key/value pair in the hash.  The value SV is removed from the
1030 hash and returned to the caller.  The C<flags> value will normally be zero;
1031 if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
1032 precomputed hash value, or 0 to ask for it to be computed.
1033
1034         SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1035
1036 =for hackers
1037 Found in file hv.c
1038
1039 =item hv_exists
1040
1041 Returns a boolean indicating whether the specified hash key exists.  The
1042 C<klen> is the length of the key.
1043
1044         bool    hv_exists(HV* tb, const char* key, I32 klen)
1045
1046 =for hackers
1047 Found in file hv.c
1048
1049 =item hv_exists_ent
1050
1051 Returns a boolean indicating whether the specified hash key exists. C<hash>
1052 can be a valid precomputed hash value, or 0 to ask for it to be
1053 computed.
1054
1055         bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
1056
1057 =for hackers
1058 Found in file hv.c
1059
1060 =item hv_fetch
1061
1062 Returns the SV which corresponds to the specified key in the hash.  The
1063 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
1064 part of a store.  Check that the return value is non-null before
1065 dereferencing it to an C<SV*>.
1066
1067 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1068 information on how to use this function on tied hashes.
1069
1070         SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1071
1072 =for hackers
1073 Found in file hv.c
1074
1075 =item hv_fetch_ent
1076
1077 Returns the hash entry which corresponds to the specified key in the hash.
1078 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1079 if you want the function to compute it.  IF C<lval> is set then the fetch
1080 will be part of a store.  Make sure the return value is non-null before
1081 accessing it.  The return value when C<tb> is a tied hash is a pointer to a
1082 static location, so be sure to make a copy of the structure if you need to
1083 store it somewhere.
1084
1085 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1086 information on how to use this function on tied hashes.
1087
1088         HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1089
1090 =for hackers
1091 Found in file hv.c
1092
1093 =item hv_iterinit
1094
1095 Prepares a starting point to traverse a hash table.  Returns the number of
1096 keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
1097 currently only meaningful for hashes without tie magic.
1098
1099 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1100 hash buckets that happen to be in use.  If you still need that esoteric
1101 value, you can get it through the macro C<HvFILL(tb)>.
1102
1103
1104         I32     hv_iterinit(HV* tb)
1105
1106 =for hackers
1107 Found in file hv.c
1108
1109 =item hv_iterkey
1110
1111 Returns the key from the current position of the hash iterator.  See
1112 C<hv_iterinit>.
1113
1114         char*   hv_iterkey(HE* entry, I32* retlen)
1115
1116 =for hackers
1117 Found in file hv.c
1118
1119 =item hv_iterkeysv
1120
1121 Returns the key as an C<SV*> from the current position of the hash
1122 iterator.  The return value will always be a mortal copy of the key.  Also
1123 see C<hv_iterinit>.
1124
1125         SV*     hv_iterkeysv(HE* entry)
1126
1127 =for hackers
1128 Found in file hv.c
1129
1130 =item hv_iternext
1131
1132 Returns entries from a hash iterator.  See C<hv_iterinit>.
1133
1134 You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1135 iterator currently points to, without losing your place or invalidating your
1136 iterator.  Note that in this case the current entry is deleted from the hash
1137 with your iterator holding the last reference to it.  Your iterator is flagged
1138 to free the entry on the next call to C<hv_iternext>, so you must not discard
1139 your iterator immediately else the entry will leak - call C<hv_iternext> to
1140 trigger the resource deallocation.
1141
1142         HE*     hv_iternext(HV* tb)
1143
1144 =for hackers
1145 Found in file hv.c
1146
1147 =item hv_iternextsv
1148
1149 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1150 operation.
1151
1152         SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
1153
1154 =for hackers
1155 Found in file hv.c
1156
1157 =item hv_iternext_flags
1158
1159 Returns entries from a hash iterator.  See C<hv_iterinit> and C<hv_iternext>.
1160 The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1161 set the placeholders keys (for restricted hashes) will be returned in addition
1162 to normal keys. By default placeholders are automatically skipped over.
1163 Currently a placeholder is implemented with a value that is literally
1164 <&Perl_sv_undef> (a regular C<undef> value is a normal read-write SV for which
1165 C<!SvOK> is false). Note that the implementation of placeholders and
1166 restricted hashes may change, and the implementation currently is
1167 insufficiently abstracted for any change to be tidy.
1168
1169 NOTE: this function is experimental and may change or be
1170 removed without notice.
1171
1172         HE*     hv_iternext_flags(HV* tb, I32 flags)
1173
1174 =for hackers
1175 Found in file hv.c
1176
1177 =item hv_iterval
1178
1179 Returns the value from the current position of the hash iterator.  See
1180 C<hv_iterkey>.
1181
1182         SV*     hv_iterval(HV* tb, HE* entry)
1183
1184 =for hackers
1185 Found in file hv.c
1186
1187 =item hv_magic
1188
1189 Adds magic to a hash.  See C<sv_magic>.
1190
1191         void    hv_magic(HV* hv, GV* gv, int how)
1192
1193 =for hackers
1194 Found in file hv.c
1195
1196 =item hv_store
1197
1198 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
1199 the length of the key.  The C<hash> parameter is the precomputed hash
1200 value; if it is zero then Perl will compute it.  The return value will be
1201 NULL if the operation failed or if the value did not need to be actually
1202 stored within the hash (as in the case of tied hashes).  Otherwise it can
1203 be dereferenced to get the original C<SV*>.  Note that the caller is
1204 responsible for suitably incrementing the reference count of C<val> before
1205 the call, and decrementing it if the function returned NULL.
1206
1207 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1208 information on how to use this function on tied hashes.
1209
1210         SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1211
1212 =for hackers
1213 Found in file hv.c
1214
1215 =item hv_store_ent
1216
1217 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
1218 parameter is the precomputed hash value; if it is zero then Perl will
1219 compute it.  The return value is the new hash entry so created.  It will be
1220 NULL if the operation failed or if the value did not need to be actually
1221 stored within the hash (as in the case of tied hashes).  Otherwise the
1222 contents of the return value can be accessed using the C<He?> macros
1223 described here.  Note that the caller is responsible for suitably
1224 incrementing the reference count of C<val> before the call, and
1225 decrementing it if the function returned NULL.
1226
1227 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1228 information on how to use this function on tied hashes.
1229
1230         HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1231
1232 =for hackers
1233 Found in file hv.c
1234
1235 =item hv_undef
1236
1237 Undefines the hash.
1238
1239         void    hv_undef(HV* tb)
1240
1241 =for hackers
1242 Found in file hv.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 Nullhv
1254
1255 Null HV pointer.
1256
1257
1258 =for hackers
1259 Found in file hv.h
1260
1261
1262 =back
1263
1264 =head1 Magical Functions
1265
1266 =over 8
1267
1268 =item mg_clear
1269
1270 Clear something magical that the SV represents.  See C<sv_magic>.
1271
1272         int     mg_clear(SV* sv)
1273
1274 =for hackers
1275 Found in file mg.c
1276
1277 =item mg_copy
1278
1279 Copies the magic from one SV to another.  See C<sv_magic>.
1280
1281         int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1282
1283 =for hackers
1284 Found in file mg.c
1285
1286 =item mg_find
1287
1288 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
1289
1290         MAGIC*  mg_find(SV* sv, int type)
1291
1292 =for hackers
1293 Found in file mg.c
1294
1295 =item mg_free
1296
1297 Free any magic storage used by the SV.  See C<sv_magic>.
1298
1299         int     mg_free(SV* sv)
1300
1301 =for hackers
1302 Found in file mg.c
1303
1304 =item mg_get
1305
1306 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
1307
1308         int     mg_get(SV* sv)
1309
1310 =for hackers
1311 Found in file mg.c
1312
1313 =item mg_length
1314
1315 Report on the SV's length.  See C<sv_magic>.
1316
1317         U32     mg_length(SV* sv)
1318
1319 =for hackers
1320 Found in file mg.c
1321
1322 =item mg_magical
1323
1324 Turns on the magical status of an SV.  See C<sv_magic>.
1325
1326         void    mg_magical(SV* sv)
1327
1328 =for hackers
1329 Found in file mg.c
1330
1331 =item mg_set
1332
1333 Do magic after a value is assigned to the SV.  See C<sv_magic>.
1334
1335         int     mg_set(SV* sv)
1336
1337 =for hackers
1338 Found in file mg.c
1339
1340 =item SvGETMAGIC
1341
1342 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
1343 argument more than once.
1344
1345         void    SvGETMAGIC(SV* sv)
1346
1347 =for hackers
1348 Found in file sv.h
1349
1350 =item SvLOCK
1351
1352 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1353 has been loaded.
1354
1355         void    SvLOCK(SV* sv)
1356
1357 =for hackers
1358 Found in file sv.h
1359
1360 =item SvSETMAGIC
1361
1362 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
1363 argument more than once.
1364
1365         void    SvSETMAGIC(SV* sv)
1366
1367 =for hackers
1368 Found in file sv.h
1369
1370 =item SvSetMagicSV
1371
1372 Like C<SvSetSV>, but does any set magic required afterwards.
1373
1374         void    SvSetMagicSV(SV* dsb, SV* ssv)
1375
1376 =for hackers
1377 Found in file sv.h
1378
1379 =item SvSetMagicSV_nosteal
1380
1381 Like C<SvSetMagicSV>, but does any set magic required afterwards.
1382
1383         void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1384
1385 =for hackers
1386 Found in file sv.h
1387
1388 =item SvSetSV
1389
1390 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
1391 more than once.
1392
1393         void    SvSetSV(SV* dsb, SV* ssv)
1394
1395 =for hackers
1396 Found in file sv.h
1397
1398 =item SvSetSV_nosteal
1399
1400 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1401 ssv. May evaluate arguments more than once.
1402
1403         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
1404
1405 =for hackers
1406 Found in file sv.h
1407
1408 =item SvSHARE
1409
1410 Arranges for sv to be shared between threads if a suitable module
1411 has been loaded.
1412
1413         void    SvSHARE(SV* sv)
1414
1415 =for hackers
1416 Found in file sv.h
1417
1418
1419 =back
1420
1421 =head1 Memory Management
1422
1423 =over 8
1424
1425 =item Copy
1426
1427 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
1428 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1429 the type.  May fail on overlapping copies.  See also C<Move>.
1430
1431         void    Copy(void* src, void* dest, int nitems, type)
1432
1433 =for hackers
1434 Found in file handy.h
1435
1436 =item Move
1437
1438 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
1439 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1440 the type.  Can do overlapping moves.  See also C<Copy>.
1441
1442         void    Move(void* src, void* dest, int nitems, type)
1443
1444 =for hackers
1445 Found in file handy.h
1446
1447 =item New
1448
1449 The XSUB-writer's interface to the C C<malloc> function.
1450
1451         void    New(int id, void* ptr, int nitems, type)
1452
1453 =for hackers
1454 Found in file handy.h
1455
1456 =item Newc
1457
1458 The XSUB-writer's interface to the C C<malloc> function, with
1459 cast.
1460
1461         void    Newc(int id, void* ptr, int nitems, type, cast)
1462
1463 =for hackers
1464 Found in file handy.h
1465
1466 =item NEWSV
1467
1468 Creates a new SV.  A non-zero C<len> parameter indicates the number of
1469 bytes of preallocated string space the SV should have.  An extra byte for a
1470 tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
1471 space is allocated.)  The reference count for the new SV is set to 1.
1472 C<id> is an integer id between 0 and 1299 (used to identify leaks).
1473
1474
1475         SV*     NEWSV(int id, STRLEN len)
1476
1477 =for hackers
1478 Found in file handy.h
1479
1480 =item Newz
1481
1482 The XSUB-writer's interface to the C C<malloc> function.  The allocated
1483 memory is zeroed with C<memzero>.
1484
1485         void    Newz(int id, void* ptr, int nitems, type)
1486
1487 =for hackers
1488 Found in file handy.h
1489
1490 =item Poison
1491
1492 Fill up memory with a pattern (byte 0xAB over and over again) that
1493 hopefully catches attempts to access uninitialized memory.
1494
1495         void    Poison(void* dest, int nitems, type)
1496
1497 =for hackers
1498 Found in file handy.h
1499
1500 =item Renew
1501
1502 The XSUB-writer's interface to the C C<realloc> function.
1503
1504         void    Renew(void* ptr, int nitems, type)
1505
1506 =for hackers
1507 Found in file handy.h
1508
1509 =item Renewc
1510
1511 The XSUB-writer's interface to the C C<realloc> function, with
1512 cast.
1513
1514         void    Renewc(void* ptr, int nitems, type, cast)
1515
1516 =for hackers
1517 Found in file handy.h
1518
1519 =item Safefree
1520
1521 The XSUB-writer's interface to the C C<free> function.
1522
1523         void    Safefree(void* ptr)
1524
1525 =for hackers
1526 Found in file handy.h
1527
1528 =item savepv
1529
1530 Perl's version of C<strdup()>. Returns a pointer to a newly allocated
1531 string which is a duplicate of C<pv>. The size of the string is
1532 determined by C<strlen()>. The memory allocated for the new string can
1533 be freed with the C<Safefree()> function.
1534
1535         char*   savepv(const char* pv)
1536
1537 =for hackers
1538 Found in file util.c
1539
1540 =item savepvn
1541
1542 Perl's version of what C<strndup()> would be if it existed. Returns a
1543 pointer to a newly allocated string which is a duplicate of the first
1544 C<len> bytes from C<pv>. The memory allocated for the new string can be
1545 freed with the C<Safefree()> function.
1546
1547         char*   savepvn(const char* pv, I32 len)
1548
1549 =for hackers
1550 Found in file util.c
1551
1552 =item savesharedpv
1553
1554 A version of C<savepv()> which allocates the duplicate string in memory
1555 which is shared between threads.
1556
1557         char*   savesharedpv(const char* pv)
1558
1559 =for hackers
1560 Found in file util.c
1561
1562 =item StructCopy
1563
1564 This is an architecture-independent macro to copy one structure to another.
1565
1566         void    StructCopy(type src, type dest, type)
1567
1568 =for hackers
1569 Found in file handy.h
1570
1571 =item Zero
1572
1573 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
1574 destination, C<nitems> is the number of items, and C<type> is the type.
1575
1576         void    Zero(void* dest, int nitems, type)
1577
1578 =for hackers
1579 Found in file handy.h
1580
1581
1582 =back
1583
1584 =head1 Miscellaneous Functions
1585
1586 =over 8
1587
1588 =item fbm_compile
1589
1590 Analyses the string in order to make fast searches on it using fbm_instr()
1591 -- the Boyer-Moore algorithm.
1592
1593         void    fbm_compile(SV* sv, U32 flags)
1594
1595 =for hackers
1596 Found in file util.c
1597
1598 =item fbm_instr
1599
1600 Returns the location of the SV in the string delimited by C<str> and
1601 C<strend>.  It returns C<Nullch> if the string can't be found.  The C<sv>
1602 does not have to be fbm_compiled, but the search will not be as fast
1603 then.
1604
1605         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
1606
1607 =for hackers
1608 Found in file util.c
1609
1610 =item form
1611
1612 Takes a sprintf-style format pattern and conventional
1613 (non-SV) arguments and returns the formatted string.
1614
1615     (char *) Perl_form(pTHX_ const char* pat, ...)
1616
1617 can be used any place a string (char *) is required:
1618
1619     char * s = Perl_form("%d.%d",major,minor);
1620
1621 Uses a single private buffer so if you want to format several strings you
1622 must explicitly copy the earlier strings away (and free the copies when you
1623 are done).
1624
1625         char*   form(const char* pat, ...)
1626
1627 =for hackers
1628 Found in file util.c
1629
1630 =item getcwd_sv
1631
1632 Fill the sv with current working directory
1633
1634         int     getcwd_sv(SV* sv)
1635
1636 =for hackers
1637 Found in file util.c
1638
1639 =item strEQ
1640
1641 Test two strings to see if they are equal.  Returns true or false.
1642
1643         bool    strEQ(char* s1, char* s2)
1644
1645 =for hackers
1646 Found in file handy.h
1647
1648 =item strGE
1649
1650 Test two strings to see if the first, C<s1>, is greater than or equal to
1651 the second, C<s2>.  Returns true or false.
1652
1653         bool    strGE(char* s1, char* s2)
1654
1655 =for hackers
1656 Found in file handy.h
1657
1658 =item strGT
1659
1660 Test two strings to see if the first, C<s1>, is greater than the second,
1661 C<s2>.  Returns true or false.
1662
1663         bool    strGT(char* s1, char* s2)
1664
1665 =for hackers
1666 Found in file handy.h
1667
1668 =item strLE
1669
1670 Test two strings to see if the first, C<s1>, is less than or equal to the
1671 second, C<s2>.  Returns true or false.
1672
1673         bool    strLE(char* s1, char* s2)
1674
1675 =for hackers
1676 Found in file handy.h
1677
1678 =item strLT
1679
1680 Test two strings to see if the first, C<s1>, is less than the second,
1681 C<s2>.  Returns true or false.
1682
1683         bool    strLT(char* s1, char* s2)
1684
1685 =for hackers
1686 Found in file handy.h
1687
1688 =item strNE
1689
1690 Test two strings to see if they are different.  Returns true or
1691 false.
1692
1693         bool    strNE(char* s1, char* s2)
1694
1695 =for hackers
1696 Found in file handy.h
1697
1698 =item strnEQ
1699
1700 Test two strings to see if they are equal.  The C<len> parameter indicates
1701 the number of bytes to compare.  Returns true or false. (A wrapper for
1702 C<strncmp>).
1703
1704         bool    strnEQ(char* s1, char* s2, STRLEN len)
1705
1706 =for hackers
1707 Found in file handy.h
1708
1709 =item strnNE
1710
1711 Test two strings to see if they are different.  The C<len> parameter
1712 indicates the number of bytes to compare.  Returns true or false. (A
1713 wrapper for C<strncmp>).
1714
1715         bool    strnNE(char* s1, char* s2, STRLEN len)
1716
1717 =for hackers
1718 Found in file handy.h
1719
1720
1721 =back
1722
1723 =head1 Numeric functions
1724
1725 =over 8
1726
1727 =item grok_bin
1728
1729 converts a string representing a binary number to numeric form.
1730
1731 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1732 conversion flags, and I<result> should be NULL or a pointer to an NV.
1733 The scan stops at the end of the string, or the first invalid character.
1734 On return I<*len> is set to the length scanned string, and I<*flags> gives
1735 output flags.
1736
1737 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1738 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
1739 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1740 and writes the value to I<*result> (or the value is discarded if I<result>
1741 is NULL).
1742
1743 The hex number may optionally be prefixed with "0b" or "b" unless
1744 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1745 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
1746 number may use '_' characters to separate digits.
1747
1748         UV      grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
1749
1750 =for hackers
1751 Found in file numeric.c
1752
1753 =item grok_hex
1754
1755 converts a string representing a hex number to numeric form.
1756
1757 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1758 conversion flags, and I<result> should be NULL or a pointer to an NV.
1759 The scan stops at the end of the string, or the first non-hex-digit character.
1760 On return I<*len> is set to the length scanned string, and I<*flags> gives
1761 output flags.
1762
1763 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1764 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
1765 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1766 and writes the value to I<*result> (or the value is discarded if I<result>
1767 is NULL).
1768
1769 The hex number may optionally be prefixed with "0x" or "x" unless
1770 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1771 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
1772 number may use '_' characters to separate digits.
1773
1774         UV      grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
1775
1776 =for hackers
1777 Found in file numeric.c
1778
1779 =item grok_number
1780
1781 Recognise (or not) a number.  The type of the number is returned
1782 (0 if unrecognised), otherwise it is a bit-ORed combination of
1783 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
1784 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
1785
1786 If the value of the number can fit an in UV, it is returned in the *valuep
1787 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
1788 will never be set unless *valuep is valid, but *valuep may have been assigned
1789 to during processing even though IS_NUMBER_IN_UV is not set on return.
1790 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
1791 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
1792
1793 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
1794 seen (in which case *valuep gives the true value truncated to an integer), and
1795 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
1796 absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
1797 number is larger than a UV.
1798
1799         int     grok_number(const char *pv, STRLEN len, UV *valuep)
1800
1801 =for hackers
1802 Found in file numeric.c
1803
1804 =item grok_numeric_radix
1805
1806 Scan and skip for a numeric decimal separator (radix).
1807
1808         bool    grok_numeric_radix(const char **sp, const char *send)
1809
1810 =for hackers
1811 Found in file numeric.c
1812
1813 =item grok_oct
1814
1815
1816         UV      grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
1817
1818 =for hackers
1819 Found in file numeric.c
1820
1821 =item scan_bin
1822
1823 For backwards compatibility. Use C<grok_bin> instead.
1824
1825         NV      scan_bin(char* start, STRLEN len, STRLEN* retlen)
1826
1827 =for hackers
1828 Found in file numeric.c
1829
1830 =item scan_hex
1831
1832 For backwards compatibility. Use C<grok_hex> instead.
1833
1834         NV      scan_hex(char* start, STRLEN len, STRLEN* retlen)
1835
1836 =for hackers
1837 Found in file numeric.c
1838
1839 =item scan_oct
1840
1841 For backwards compatibility. Use C<grok_oct> instead.
1842
1843         NV      scan_oct(char* start, STRLEN len, STRLEN* retlen)
1844
1845 =for hackers
1846 Found in file numeric.c
1847
1848
1849 =back
1850
1851 =head1 Optree Manipulation Functions
1852
1853 =over 8
1854
1855 =item cv_const_sv
1856
1857 If C<cv> is a constant sub eligible for inlining. returns the constant
1858 value returned by the sub.  Otherwise, returns NULL.
1859
1860 Constant subs can be created with C<newCONSTSUB> or as described in
1861 L<perlsub/"Constant Functions">.
1862
1863         SV*     cv_const_sv(CV* cv)
1864
1865 =for hackers
1866 Found in file op.c
1867
1868 =item newCONSTSUB
1869
1870 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1871 eligible for inlining at compile-time.
1872
1873         CV*     newCONSTSUB(HV* stash, char* name, SV* sv)
1874
1875 =for hackers
1876 Found in file op.c
1877
1878 =item newXS
1879
1880 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1881
1882 =for hackers
1883 Found in file op.c
1884
1885
1886 =back
1887
1888 =head1 Stack Manipulation Macros
1889
1890 =over 8
1891
1892 =item dMARK
1893
1894 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
1895 C<dORIGMARK>.
1896
1897                 dMARK;
1898
1899 =for hackers
1900 Found in file pp.h
1901
1902 =item dORIGMARK
1903
1904 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
1905
1906                 dORIGMARK;
1907
1908 =for hackers
1909 Found in file pp.h
1910
1911 =item dSP
1912
1913 Declares a local copy of perl's stack pointer for the XSUB, available via
1914 the C<SP> macro.  See C<SP>.
1915
1916                 dSP;
1917
1918 =for hackers
1919 Found in file pp.h
1920
1921 =item EXTEND
1922
1923 Used to extend the argument stack for an XSUB's return values. Once
1924 used, guarantees that there is room for at least C<nitems> to be pushed
1925 onto the stack.
1926
1927         void    EXTEND(SP, int nitems)
1928
1929 =for hackers
1930 Found in file pp.h
1931
1932 =item MARK
1933
1934 Stack marker variable for the XSUB.  See C<dMARK>.
1935
1936 =for hackers
1937 Found in file pp.h
1938
1939 =item ORIGMARK
1940
1941 The original stack mark for the XSUB.  See C<dORIGMARK>.
1942
1943 =for hackers
1944 Found in file pp.h
1945
1946 =item POPi
1947
1948 Pops an integer off the stack.
1949
1950         IV      POPi
1951
1952 =for hackers
1953 Found in file pp.h
1954
1955 =item POPl
1956
1957 Pops a long off the stack.
1958
1959         long    POPl
1960
1961 =for hackers
1962 Found in file pp.h
1963
1964 =item POPn
1965
1966 Pops a double off the stack.
1967
1968         NV      POPn
1969
1970 =for hackers
1971 Found in file pp.h
1972
1973 =item POPp
1974
1975 Pops a string off the stack. Deprecated. New code should provide
1976 a STRLEN n_a and use POPpx.
1977
1978         char*   POPp
1979
1980 =for hackers
1981 Found in file pp.h
1982
1983 =item POPpbytex
1984
1985 Pops a string off the stack which must consist of bytes i.e. characters < 256.
1986 Requires a variable STRLEN n_a in scope.
1987
1988         char*   POPpbytex
1989
1990 =for hackers
1991 Found in file pp.h
1992
1993 =item POPpx
1994
1995 Pops a string off the stack.
1996 Requires a variable STRLEN n_a in scope.
1997
1998         char*   POPpx
1999
2000 =for hackers
2001 Found in file pp.h
2002
2003 =item POPs
2004
2005 Pops an SV off the stack.
2006
2007         SV*     POPs
2008
2009 =for hackers
2010 Found in file pp.h
2011
2012 =item PUSHi
2013
2014 Push an integer onto the stack.  The stack must have room for this element.
2015 Handles 'set' magic.  See C<XPUSHi>.
2016
2017         void    PUSHi(IV iv)
2018
2019 =for hackers
2020 Found in file pp.h
2021
2022 =item PUSHMARK
2023
2024 Opening bracket for arguments on a callback.  See C<PUTBACK> and
2025 L<perlcall>.
2026
2027                 PUSHMARK;
2028
2029 =for hackers
2030 Found in file pp.h
2031
2032 =item PUSHn
2033
2034 Push a double onto the stack.  The stack must have room for this element.
2035 Handles 'set' magic.  See C<XPUSHn>.
2036
2037         void    PUSHn(NV nv)
2038
2039 =for hackers
2040 Found in file pp.h
2041
2042 =item PUSHp
2043
2044 Push a string onto the stack.  The stack must have room for this element.
2045 The C<len> indicates the length of the string.  Handles 'set' magic.  See
2046 C<XPUSHp>.
2047
2048         void    PUSHp(char* str, STRLEN len)
2049
2050 =for hackers
2051 Found in file pp.h
2052
2053 =item PUSHs
2054
2055 Push an SV onto the stack.  The stack must have room for this element.
2056 Does not handle 'set' magic.  See C<XPUSHs>.
2057
2058         void    PUSHs(SV* sv)
2059
2060 =for hackers
2061 Found in file pp.h
2062
2063 =item PUSHu
2064
2065 Push an unsigned integer onto the stack.  The stack must have room for this
2066 element.  See C<XPUSHu>.
2067
2068         void    PUSHu(UV uv)
2069
2070 =for hackers
2071 Found in file pp.h
2072
2073 =item PUTBACK
2074
2075 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
2076 See C<PUSHMARK> and L<perlcall> for other uses.
2077
2078                 PUTBACK;
2079
2080 =for hackers
2081 Found in file pp.h
2082
2083 =item SP
2084
2085 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
2086 C<SPAGAIN>.
2087
2088 =for hackers
2089 Found in file pp.h
2090
2091 =item SPAGAIN
2092
2093 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
2094
2095                 SPAGAIN;
2096
2097 =for hackers
2098 Found in file pp.h
2099
2100 =item XPUSHi
2101
2102 Push an integer onto the stack, extending the stack if necessary.  Handles
2103 'set' magic. See C<PUSHi>.
2104
2105         void    XPUSHi(IV iv)
2106
2107 =for hackers
2108 Found in file pp.h
2109
2110 =item XPUSHn
2111
2112 Push a double onto the stack, extending the stack if necessary.  Handles
2113 'set' magic.  See C<PUSHn>.
2114
2115         void    XPUSHn(NV nv)
2116
2117 =for hackers
2118 Found in file pp.h
2119
2120 =item XPUSHp
2121
2122 Push a string onto the stack, extending the stack if necessary.  The C<len>
2123 indicates the length of the string.  Handles 'set' magic.  See
2124 C<PUSHp>.
2125
2126         void    XPUSHp(char* str, STRLEN len)
2127
2128 =for hackers
2129 Found in file pp.h
2130
2131 =item XPUSHs
2132
2133 Push an SV onto the stack, extending the stack if necessary.  Does not
2134 handle 'set' magic.  See C<PUSHs>.
2135
2136         void    XPUSHs(SV* sv)
2137
2138 =for hackers
2139 Found in file pp.h
2140
2141 =item XPUSHu
2142
2143 Push an unsigned integer onto the stack, extending the stack if necessary.
2144 See C<PUSHu>.
2145
2146         void    XPUSHu(UV uv)
2147
2148 =for hackers
2149 Found in file pp.h
2150
2151 =item XSRETURN
2152
2153 Return from XSUB, indicating number of items on the stack.  This is usually
2154 handled by C<xsubpp>.
2155
2156         void    XSRETURN(int nitems)
2157
2158 =for hackers
2159 Found in file XSUB.h
2160
2161 =item XSRETURN_IV
2162
2163 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
2164
2165         void    XSRETURN_IV(IV iv)
2166
2167 =for hackers
2168 Found in file XSUB.h
2169
2170 =item XSRETURN_NO
2171
2172 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
2173
2174                 XSRETURN_NO;
2175
2176 =for hackers
2177 Found in file XSUB.h
2178
2179 =item XSRETURN_NV
2180
2181 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
2182
2183         void    XSRETURN_NV(NV nv)
2184
2185 =for hackers
2186 Found in file XSUB.h
2187
2188 =item XSRETURN_PV
2189
2190 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
2191
2192         void    XSRETURN_PV(char* str)
2193
2194 =for hackers
2195 Found in file XSUB.h
2196
2197 =item XSRETURN_UNDEF
2198
2199 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
2200
2201                 XSRETURN_UNDEF;
2202
2203 =for hackers
2204 Found in file XSUB.h
2205
2206 =item XSRETURN_YES
2207
2208 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
2209
2210                 XSRETURN_YES;
2211
2212 =for hackers
2213 Found in file XSUB.h
2214
2215 =item XST_mIV
2216
2217 Place an integer into the specified position C<pos> on the stack.  The
2218 value is stored in a new mortal SV.
2219
2220         void    XST_mIV(int pos, IV iv)
2221
2222 =for hackers
2223 Found in file XSUB.h
2224
2225 =item XST_mNO
2226
2227 Place C<&PL_sv_no> into the specified position C<pos> on the
2228 stack.
2229
2230         void    XST_mNO(int pos)
2231
2232 =for hackers
2233 Found in file XSUB.h
2234
2235 =item XST_mNV
2236
2237 Place a double into the specified position C<pos> on the stack.  The value
2238 is stored in a new mortal SV.
2239
2240         void    XST_mNV(int pos, NV nv)
2241
2242 =for hackers
2243 Found in file XSUB.h
2244
2245 =item XST_mPV
2246
2247 Place a copy of a string into the specified position C<pos> on the stack. 
2248 The value is stored in a new mortal SV.
2249
2250         void    XST_mPV(int pos, char* str)
2251
2252 =for hackers
2253 Found in file XSUB.h
2254
2255 =item XST_mUNDEF
2256
2257 Place C<&PL_sv_undef> into the specified position C<pos> on the
2258 stack.
2259
2260         void    XST_mUNDEF(int pos)
2261
2262 =for hackers
2263 Found in file XSUB.h
2264
2265 =item XST_mYES
2266
2267 Place C<&PL_sv_yes> into the specified position C<pos> on the
2268 stack.
2269
2270         void    XST_mYES(int pos)
2271
2272 =for hackers
2273 Found in file XSUB.h
2274
2275
2276 =back
2277
2278 =head1 SV Flags
2279
2280 =over 8
2281
2282 =item svtype
2283
2284 An enum of flags for Perl types.  These are found in the file B<sv.h>
2285 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
2286
2287 =for hackers
2288 Found in file sv.h
2289
2290 =item SVt_IV
2291
2292 Integer type flag for scalars.  See C<svtype>.
2293
2294 =for hackers
2295 Found in file sv.h
2296
2297 =item SVt_NV
2298
2299 Double type flag for scalars.  See C<svtype>.
2300
2301 =for hackers
2302 Found in file sv.h
2303
2304 =item SVt_PV
2305
2306 Pointer type flag for scalars.  See C<svtype>.
2307
2308 =for hackers
2309 Found in file sv.h
2310
2311 =item SVt_PVAV
2312
2313 Type flag for arrays.  See C<svtype>.
2314
2315 =for hackers
2316 Found in file sv.h
2317
2318 =item SVt_PVCV
2319
2320 Type flag for code refs.  See C<svtype>.
2321
2322 =for hackers
2323 Found in file sv.h
2324
2325 =item SVt_PVHV
2326
2327 Type flag for hashes.  See C<svtype>.
2328
2329 =for hackers
2330 Found in file sv.h
2331
2332 =item SVt_PVMG
2333
2334 Type flag for blessed scalars.  See C<svtype>.
2335
2336 =for hackers
2337 Found in file sv.h
2338
2339
2340 =back
2341
2342 =head1 SV Manipulation Functions
2343
2344 =over 8
2345
2346 =item get_sv
2347
2348 Returns the SV of the specified Perl scalar.  If C<create> is set and the
2349 Perl variable does not exist then it will be created.  If C<create> is not
2350 set and the variable does not exist then NULL is returned.
2351
2352 NOTE: the perl_ form of this function is deprecated.
2353
2354         SV*     get_sv(const char* name, I32 create)
2355
2356 =for hackers
2357 Found in file perl.c
2358
2359 =item looks_like_number
2360
2361 Test if the content of an SV looks like a number (or is a number).
2362 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2363 non-numeric warning), even if your atof() doesn't grok them.
2364
2365         I32     looks_like_number(SV* sv)
2366
2367 =for hackers
2368 Found in file sv.c
2369
2370 =item newRV_inc
2371
2372 Creates an RV wrapper for an SV.  The reference count for the original SV is
2373 incremented.
2374
2375         SV*     newRV_inc(SV* sv)
2376
2377 =for hackers
2378 Found in file sv.h
2379
2380 =item newRV_noinc
2381
2382 Creates an RV wrapper for an SV.  The reference count for the original
2383 SV is B<not> incremented.
2384
2385         SV*     newRV_noinc(SV *sv)
2386
2387 =for hackers
2388 Found in file sv.c
2389
2390 =item newSV
2391
2392 Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2393 with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2394 macro.
2395
2396         SV*     newSV(STRLEN len)
2397
2398 =for hackers
2399 Found in file sv.c
2400
2401 =item newSViv
2402
2403 Creates a new SV and copies an integer into it.  The reference count for the
2404 SV is set to 1.
2405
2406         SV*     newSViv(IV i)
2407
2408 =for hackers
2409 Found in file sv.c
2410
2411 =item newSVnv
2412
2413 Creates a new SV and copies a floating point value into it.
2414 The reference count for the SV is set to 1.
2415
2416         SV*     newSVnv(NV n)
2417
2418 =for hackers
2419 Found in file sv.c
2420
2421 =item newSVpv
2422
2423 Creates a new SV and copies a string into it.  The reference count for the
2424 SV is set to 1.  If C<len> is zero, Perl will compute the length using
2425 strlen().  For efficiency, consider using C<newSVpvn> instead.
2426
2427         SV*     newSVpv(const char* s, STRLEN len)
2428
2429 =for hackers
2430 Found in file sv.c
2431
2432 =item newSVpvf
2433
2434 Creates a new SV and initializes it with the string formatted like
2435 C<sprintf>.
2436
2437         SV*     newSVpvf(const char* pat, ...)
2438
2439 =for hackers
2440 Found in file sv.c
2441
2442 =item newSVpvn
2443
2444 Creates a new SV and copies a string into it.  The reference count for the
2445 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
2446 string.  You are responsible for ensuring that the source string is at least
2447 C<len> bytes long.
2448
2449         SV*     newSVpvn(const char* s, STRLEN len)
2450
2451 =for hackers
2452 Found in file sv.c
2453
2454 =item newSVpvn_share
2455
2456 Creates a new SV with its SvPVX pointing to a shared string in the string
2457 table. If the string does not already exist in the table, it is created
2458 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
2459 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
2460 otherwise the hash is computed.  The idea here is that as the string table
2461 is used for shared hash keys these strings will have SvPVX == HeKEY and
2462 hash lookup will avoid string compare.
2463
2464         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
2465
2466 =for hackers
2467 Found in file sv.c
2468
2469 =item newSVrv
2470
2471 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
2472 it will be upgraded to one.  If C<classname> is non-null then the new SV will
2473 be blessed in the specified package.  The new SV is returned and its
2474 reference count is 1.
2475
2476         SV*     newSVrv(SV* rv, const char* classname)
2477
2478 =for hackers
2479 Found in file sv.c
2480
2481 =item newSVsv
2482
2483 Creates a new SV which is an exact duplicate of the original SV.
2484 (Uses C<sv_setsv>).
2485
2486         SV*     newSVsv(SV* old)
2487
2488 =for hackers
2489 Found in file sv.c
2490
2491 =item newSVuv
2492
2493 Creates a new SV and copies an unsigned integer into it.
2494 The reference count for the SV is set to 1.
2495
2496         SV*     newSVuv(UV u)
2497
2498 =for hackers
2499 Found in file sv.c
2500
2501 =item new_version
2502
2503 Returns a new version object based on the passed in SV:
2504
2505     SV *sv = new_version(SV *ver);
2506
2507 Does not alter the passed in ver SV.  See "upg_version" if you
2508 want to upgrade the SV.
2509
2510         SV*     new_version(SV *ver)
2511
2512 =for hackers
2513 Found in file util.c
2514
2515 =item scan_version
2516
2517 Returns a pointer to the next character after the parsed
2518 version string, as well as upgrading the passed in SV to
2519 an RV.
2520
2521 Function must be called with an already existing SV like
2522
2523     sv = NEWSV(92,0);
2524     s = scan_version(s,sv);
2525
2526 Performs some preprocessing to the string to ensure that
2527 it has the correct characteristics of a version.  Flags the
2528 object if it contains an underscore (which denotes this
2529 is a beta version).
2530
2531         char*   scan_version(char *vstr, SV *sv)
2532
2533 =for hackers
2534 Found in file util.c
2535
2536 =item scan_vstring
2537
2538 Returns a pointer to the next character after the parsed
2539 vstring, as well as updating the passed in sv.
2540
2541 Function must be called like
2542
2543         sv = NEWSV(92,5);
2544         s = scan_vstring(s,sv);
2545
2546 The sv should already be large enough to store the vstring
2547 passed in, for performance reasons.
2548
2549         char*   scan_vstring(char *vstr, SV *sv)
2550
2551 =for hackers
2552 Found in file util.c
2553
2554 =item SvCUR
2555
2556 Returns the length of the string which is in the SV.  See C<SvLEN>.
2557
2558         STRLEN  SvCUR(SV* sv)
2559
2560 =for hackers
2561 Found in file sv.h
2562
2563 =item SvCUR_set
2564
2565 Set the length of the string which is in the SV.  See C<SvCUR>.
2566
2567         void    SvCUR_set(SV* sv, STRLEN len)
2568
2569 =for hackers
2570 Found in file sv.h
2571
2572 =item SvEND
2573
2574 Returns a pointer to the last character in the string which is in the SV.
2575 See C<SvCUR>.  Access the character as *(SvEND(sv)).
2576
2577         char*   SvEND(SV* sv)
2578
2579 =for hackers
2580 Found in file sv.h
2581
2582 =item SvGROW
2583
2584 Expands the character buffer in the SV so that it has room for the
2585 indicated number of bytes (remember to reserve space for an extra trailing
2586 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
2587 Returns a pointer to the character buffer.
2588
2589         char *  SvGROW(SV* sv, STRLEN len)
2590
2591 =for hackers
2592 Found in file sv.h
2593
2594 =item SvIOK
2595
2596 Returns a boolean indicating whether the SV contains an integer.
2597
2598         bool    SvIOK(SV* sv)
2599
2600 =for hackers
2601 Found in file sv.h
2602
2603 =item SvIOKp
2604
2605 Returns a boolean indicating whether the SV contains an integer.  Checks
2606 the B<private> setting.  Use C<SvIOK>.
2607
2608         bool    SvIOKp(SV* sv)
2609
2610 =for hackers
2611 Found in file sv.h
2612
2613 =item SvIOK_notUV
2614
2615 Returns a boolean indicating whether the SV contains a signed integer.
2616
2617         void    SvIOK_notUV(SV* sv)
2618
2619 =for hackers
2620 Found in file sv.h
2621
2622 =item SvIOK_off
2623
2624 Unsets the IV status of an SV.
2625
2626         void    SvIOK_off(SV* sv)
2627
2628 =for hackers
2629 Found in file sv.h
2630
2631 =item SvIOK_on
2632
2633 Tells an SV that it is an integer.
2634
2635         void    SvIOK_on(SV* sv)
2636
2637 =for hackers
2638 Found in file sv.h
2639
2640 =item SvIOK_only
2641
2642 Tells an SV that it is an integer and disables all other OK bits.
2643
2644         void    SvIOK_only(SV* sv)
2645
2646 =for hackers
2647 Found in file sv.h
2648
2649 =item SvIOK_only_UV
2650
2651 Tells and SV that it is an unsigned integer and disables all other OK bits.
2652
2653         void    SvIOK_only_UV(SV* sv)
2654
2655 =for hackers
2656 Found in file sv.h
2657
2658 =item SvIOK_UV
2659
2660 Returns a boolean indicating whether the SV contains an unsigned integer.
2661
2662         void    SvIOK_UV(SV* sv)
2663
2664 =for hackers
2665 Found in file sv.h
2666
2667 =item SvIV
2668
2669 Coerces the given SV to an integer and returns it. See  C<SvIVx> for a
2670 version which guarantees to evaluate sv only once.
2671
2672         IV      SvIV(SV* sv)
2673
2674 =for hackers
2675 Found in file sv.h
2676
2677 =item SvIVx
2678
2679 Coerces the given SV to an integer and returns it. Guarantees to evaluate
2680 sv only once. Use the more efficient C<SvIV> otherwise.
2681
2682         IV      SvIVx(SV* sv)
2683
2684 =for hackers
2685 Found in file sv.h
2686
2687 =item SvIVX
2688
2689 Returns the raw value in the SV's IV slot, without checks or conversions.
2690 Only use when you are sure SvIOK is true. See also C<SvIV()>.
2691
2692         IV      SvIVX(SV* sv)
2693
2694 =for hackers
2695 Found in file sv.h
2696
2697 =item SvLEN
2698
2699 Returns the size of the string buffer in the SV, not including any part
2700 attributable to C<SvOOK>.  See C<SvCUR>.
2701
2702         STRLEN  SvLEN(SV* sv)
2703
2704 =for hackers
2705 Found in file sv.h
2706
2707 =item SvNIOK
2708
2709 Returns a boolean indicating whether the SV contains a number, integer or
2710 double.
2711
2712         bool    SvNIOK(SV* sv)
2713
2714 =for hackers
2715 Found in file sv.h
2716
2717 =item SvNIOKp
2718
2719 Returns a boolean indicating whether the SV contains a number, integer or
2720 double.  Checks the B<private> setting.  Use C<SvNIOK>.
2721
2722         bool    SvNIOKp(SV* sv)
2723
2724 =for hackers
2725 Found in file sv.h
2726
2727 =item SvNIOK_off
2728
2729 Unsets the NV/IV status of an SV.
2730
2731         void    SvNIOK_off(SV* sv)
2732
2733 =for hackers
2734 Found in file sv.h
2735
2736 =item SvNOK
2737
2738 Returns a boolean indicating whether the SV contains a double.
2739
2740         bool    SvNOK(SV* sv)
2741
2742 =for hackers
2743 Found in file sv.h
2744
2745 =item SvNOKp
2746
2747 Returns a boolean indicating whether the SV contains a double.  Checks the
2748 B<private> setting.  Use C<SvNOK>.
2749
2750         bool    SvNOKp(SV* sv)
2751
2752 =for hackers
2753 Found in file sv.h
2754
2755 =item SvNOK_off
2756
2757 Unsets the NV status of an SV.
2758
2759         void    SvNOK_off(SV* sv)
2760
2761 =for hackers
2762 Found in file sv.h
2763
2764 =item SvNOK_on
2765
2766 Tells an SV that it is a double.
2767
2768         void    SvNOK_on(SV* sv)
2769
2770 =for hackers
2771 Found in file sv.h
2772
2773 =item SvNOK_only
2774
2775 Tells an SV that it is a double and disables all other OK bits.
2776
2777         void    SvNOK_only(SV* sv)
2778
2779 =for hackers
2780 Found in file sv.h
2781
2782 =item SvNV
2783
2784 Coerce the given SV to a double and return it. See  C<SvNVx> for a version
2785 which guarantees to evaluate sv only once.
2786
2787         NV      SvNV(SV* sv)
2788
2789 =for hackers
2790 Found in file sv.h
2791
2792 =item SvNVX
2793
2794 Returns the raw value in the SV's NV slot, without checks or conversions.
2795 Only use when you are sure SvNOK is true. See also C<SvNV()>.
2796
2797         NV      SvNVX(SV* sv)
2798
2799 =for hackers
2800 Found in file sv.h
2801
2802 =item SvNVx
2803
2804 Coerces the given SV to a double and returns it. Guarantees to evaluate
2805 sv only once. Use the more efficient C<SvNV> otherwise.
2806
2807         NV      SvNVx(SV* sv)
2808
2809 =for hackers
2810 Found in file sv.h
2811
2812 =item SvOK
2813
2814 Returns a boolean indicating whether the value is an SV.
2815
2816         bool    SvOK(SV* sv)
2817
2818 =for hackers
2819 Found in file sv.h
2820
2821 =item SvOOK
2822
2823 Returns a boolean indicating whether the SvIVX is a valid offset value for
2824 the SvPVX.  This hack is used internally to speed up removal of characters
2825 from the beginning of a SvPV.  When SvOOK is true, then the start of the
2826 allocated string buffer is really (SvPVX - SvIVX).
2827
2828         bool    SvOOK(SV* sv)
2829
2830 =for hackers
2831 Found in file sv.h
2832
2833 =item SvPOK
2834
2835 Returns a boolean indicating whether the SV contains a character
2836 string.
2837
2838         bool    SvPOK(SV* sv)
2839
2840 =for hackers
2841 Found in file sv.h
2842
2843 =item SvPOKp
2844
2845 Returns a boolean indicating whether the SV contains a character string.
2846 Checks the B<private> setting.  Use C<SvPOK>.
2847
2848         bool    SvPOKp(SV* sv)
2849
2850 =for hackers
2851 Found in file sv.h
2852
2853 =item SvPOK_off
2854
2855 Unsets the PV status of an SV.
2856
2857         void    SvPOK_off(SV* sv)
2858
2859 =for hackers
2860 Found in file sv.h
2861
2862 =item SvPOK_on
2863
2864 Tells an SV that it is a string.
2865
2866         void    SvPOK_on(SV* sv)
2867
2868 =for hackers
2869 Found in file sv.h
2870
2871 =item SvPOK_only
2872
2873 Tells an SV that it is a string and disables all other OK bits.
2874 Will also turn off the UTF8 status.
2875
2876         void    SvPOK_only(SV* sv)
2877
2878 =for hackers
2879 Found in file sv.h
2880
2881 =item SvPOK_only_UTF8
2882
2883 Tells an SV that it is a string and disables all other OK bits,
2884 and leaves the UTF8 status as it was.
2885
2886         void    SvPOK_only_UTF8(SV* sv)
2887
2888 =for hackers
2889 Found in file sv.h
2890
2891 =item SvPV
2892
2893 Returns a pointer to the string in the SV, or a stringified form of
2894 the SV if the SV does not contain a string.  The SV may cache the
2895 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
2896 C<SvPVx> for a version which guarantees to evaluate sv only once.
2897
2898         char*   SvPV(SV* sv, STRLEN len)
2899
2900 =for hackers
2901 Found in file sv.h
2902
2903 =item SvPVbyte
2904
2905 Like C<SvPV>, but converts sv to byte representation first if necessary.
2906
2907         char*   SvPVbyte(SV* sv, STRLEN len)
2908
2909 =for hackers
2910 Found in file sv.h
2911
2912 =item SvPVbytex
2913
2914 Like C<SvPV>, but converts sv to byte representation first if necessary.
2915 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
2916 otherwise.
2917
2918
2919         char*   SvPVbytex(SV* sv, STRLEN len)
2920
2921 =for hackers
2922 Found in file sv.h
2923
2924 =item SvPVbytex_force
2925
2926 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2927 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
2928 otherwise.
2929
2930         char*   SvPVbytex_force(SV* sv, STRLEN len)
2931
2932 =for hackers
2933 Found in file sv.h
2934
2935 =item SvPVbyte_force
2936
2937 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2938
2939         char*   SvPVbyte_force(SV* sv, STRLEN len)
2940
2941 =for hackers
2942 Found in file sv.h
2943
2944 =item SvPVbyte_nolen
2945
2946 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2947
2948         char*   SvPVbyte_nolen(SV* sv)
2949
2950 =for hackers
2951 Found in file sv.h
2952
2953 =item SvPVutf8
2954
2955 Like C<SvPV>, but converts sv to utf8 first if necessary.
2956
2957         char*   SvPVutf8(SV* sv, STRLEN len)
2958
2959 =for hackers
2960 Found in file sv.h
2961
2962 =item SvPVutf8x
2963
2964 Like C<SvPV>, but converts sv to utf8 first if necessary.
2965 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
2966 otherwise.
2967
2968         char*   SvPVutf8x(SV* sv, STRLEN len)
2969
2970 =for hackers
2971 Found in file sv.h
2972
2973 =item SvPVutf8x_force
2974
2975 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2976 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
2977 otherwise.
2978
2979         char*   SvPVutf8x_force(SV* sv, STRLEN len)
2980
2981 =for hackers
2982 Found in file sv.h
2983
2984 =item SvPVutf8_force
2985
2986 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2987
2988         char*   SvPVutf8_force(SV* sv, STRLEN len)
2989
2990 =for hackers
2991 Found in file sv.h
2992
2993 =item SvPVutf8_nolen
2994
2995 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
2996
2997         char*   SvPVutf8_nolen(SV* sv)
2998
2999 =for hackers
3000 Found in file sv.h
3001
3002 =item SvPVx
3003
3004 A version of C<SvPV> which guarantees to evaluate sv only once.
3005
3006         char*   SvPVx(SV* sv, STRLEN len)
3007
3008 =for hackers
3009 Found in file sv.h
3010
3011 =item SvPVX
3012
3013 Returns a pointer to the physical string in the SV.  The SV must contain a
3014 string.
3015
3016         char*   SvPVX(SV* sv)
3017
3018 =for hackers
3019 Found in file sv.h
3020
3021 =item SvPV_force
3022
3023 Like C<SvPV> but will force the SV into containing just a string
3024 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
3025 directly.
3026
3027         char*   SvPV_force(SV* sv, STRLEN len)
3028
3029 =for hackers
3030 Found in file sv.h
3031
3032 =item SvPV_force_nomg
3033
3034 Like C<SvPV> but will force the SV into containing just a string
3035 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
3036 directly. Doesn't process magic.
3037
3038         char*   SvPV_force_nomg(SV* sv, STRLEN len)
3039
3040 =for hackers
3041 Found in file sv.h
3042
3043 =item SvPV_nolen
3044
3045 Returns a pointer to the string in the SV, or a stringified form of
3046 the SV if the SV does not contain a string.  The SV may cache the
3047 stringified form becoming C<SvPOK>.  Handles 'get' magic.
3048
3049         char*   SvPV_nolen(SV* sv)
3050
3051 =for hackers
3052 Found in file sv.h
3053
3054 =item SvREFCNT
3055
3056 Returns the value of the object's reference count.
3057
3058         U32     SvREFCNT(SV* sv)
3059
3060 =for hackers
3061 Found in file sv.h
3062
3063 =item SvREFCNT_dec
3064
3065 Decrements the reference count of the given SV.
3066
3067         void    SvREFCNT_dec(SV* sv)
3068
3069 =for hackers
3070 Found in file sv.h
3071
3072 =item SvREFCNT_inc
3073
3074 Increments the reference count of the given SV.
3075
3076         SV*     SvREFCNT_inc(SV* sv)
3077
3078 =for hackers
3079 Found in file sv.h
3080
3081 =item SvROK
3082
3083 Tests if the SV is an RV.
3084
3085         bool    SvROK(SV* sv)
3086
3087 =for hackers
3088 Found in file sv.h
3089
3090 =item SvROK_off
3091
3092 Unsets the RV status of an SV.
3093
3094         void    SvROK_off(SV* sv)
3095
3096 =for hackers
3097 Found in file sv.h
3098
3099 =item SvROK_on
3100
3101 Tells an SV that it is an RV.
3102
3103         void    SvROK_on(SV* sv)
3104
3105 =for hackers
3106 Found in file sv.h
3107
3108 =item SvRV
3109
3110 Dereferences an RV to return the SV.
3111
3112         SV*     SvRV(SV* sv)
3113
3114 =for hackers
3115 Found in file sv.h
3116
3117 =item SvSTASH
3118
3119 Returns the stash of the SV.
3120
3121         HV*     SvSTASH(SV* sv)
3122
3123 =for hackers
3124 Found in file sv.h
3125
3126 =item SvTAINT
3127
3128 Taints an SV if tainting is enabled
3129
3130         void    SvTAINT(SV* sv)
3131
3132 =for hackers
3133 Found in file sv.h
3134
3135 =item SvTAINTED
3136
3137 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3138 not.
3139
3140         bool    SvTAINTED(SV* sv)
3141
3142 =for hackers
3143 Found in file sv.h
3144
3145 =item SvTAINTED_off
3146
3147 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3148 some of Perl's fundamental security features. XS module authors should not
3149 use this function unless they fully understand all the implications of
3150 unconditionally untainting the value. Untainting should be done in the
3151 standard perl fashion, via a carefully crafted regexp, rather than directly
3152 untainting variables.
3153
3154         void    SvTAINTED_off(SV* sv)
3155
3156 =for hackers
3157 Found in file sv.h
3158
3159 =item SvTAINTED_on
3160
3161 Marks an SV as tainted.
3162
3163         void    SvTAINTED_on(SV* sv)
3164
3165 =for hackers
3166 Found in file sv.h
3167
3168 =item SvTRUE
3169
3170 Returns a boolean indicating whether Perl would evaluate the SV as true or
3171 false, defined or undefined.  Does not handle 'get' magic.
3172
3173         bool    SvTRUE(SV* sv)
3174
3175 =for hackers
3176 Found in file sv.h
3177
3178 =item SvTYPE
3179
3180 Returns the type of the SV.  See C<svtype>.
3181
3182         svtype  SvTYPE(SV* sv)
3183
3184 =for hackers
3185 Found in file sv.h
3186
3187 =item SvUNLOCK
3188
3189 Releases a mutual exclusion lock on sv if a suitable module
3190 has been loaded.
3191
3192
3193         void    SvUNLOCK(SV* sv)
3194
3195 =for hackers
3196 Found in file sv.h
3197
3198 =item SvUOK
3199
3200 Returns a boolean indicating whether the SV contains an unsigned integer.
3201
3202         void    SvUOK(SV* sv)
3203
3204 =for hackers
3205 Found in file sv.h
3206
3207 =item SvUPGRADE
3208
3209 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
3210 perform the upgrade if necessary.  See C<svtype>.
3211
3212         void    SvUPGRADE(SV* sv, svtype type)
3213
3214 =for hackers
3215 Found in file sv.h
3216
3217 =item SvUTF8
3218
3219 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3220
3221         void    SvUTF8(SV* sv)
3222
3223 =for hackers
3224 Found in file sv.h
3225
3226 =item SvUTF8_off
3227
3228 Unsets the UTF8 status of an SV.
3229
3230         void    SvUTF8_off(SV *sv)
3231
3232 =for hackers
3233 Found in file sv.h
3234
3235 =item SvUTF8_on
3236
3237 Turn on the UTF8 status of an SV (the data is not changed, just the flag).
3238 Do not use frivolously.
3239
3240         void    SvUTF8_on(SV *sv)
3241
3242 =for hackers
3243 Found in file sv.h
3244
3245 =item SvUV
3246
3247 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
3248 for a version which guarantees to evaluate sv only once.
3249
3250         UV      SvUV(SV* sv)
3251
3252 =for hackers
3253 Found in file sv.h
3254
3255 =item SvUVX
3256
3257 Returns the raw value in the SV's UV slot, without checks or conversions.
3258 Only use when you are sure SvIOK is true. See also C<SvUV()>.
3259
3260         UV      SvUVX(SV* sv)
3261
3262 =for hackers
3263 Found in file sv.h
3264
3265 =item SvUVx
3266
3267 Coerces the given SV to an unsigned integer and returns it. Guarantees to
3268 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
3269
3270         UV      SvUVx(SV* sv)
3271
3272 =for hackers
3273 Found in file sv.h
3274
3275 =item SvVOK
3276
3277 Returns a boolean indicating whether the SV contains a v-string.
3278
3279         bool    SvVOK(SV* sv)
3280
3281 =for hackers
3282 Found in file sv.h
3283
3284 =item sv_2bool
3285
3286 This function is only called on magical items, and is only used by
3287 sv_true() or its macro equivalent.
3288
3289         bool    sv_2bool(SV* sv)
3290
3291 =for hackers
3292 Found in file sv.c
3293
3294 =item sv_2cv
3295
3296 Using various gambits, try to get a CV from an SV; in addition, try if
3297 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3298
3299         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3300
3301 =for hackers
3302 Found in file sv.c
3303
3304 =item sv_2io
3305
3306 Using various gambits, try to get an IO from an SV: the IO slot if its a
3307 GV; or the recursive result if we're an RV; or the IO slot of the symbol
3308 named after the PV if we're a string.
3309
3310         IO*     sv_2io(SV* sv)
3311
3312 =for hackers
3313 Found in file sv.c
3314
3315 =item sv_2iv
3316
3317 Return the integer value of an SV, doing any necessary string conversion,
3318 magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3319
3320         IV      sv_2iv(SV* sv)
3321
3322 =for hackers
3323 Found in file sv.c
3324
3325 =item sv_2mortal
3326
3327 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
3328 by an explicit call to FREETMPS, or by an implicit call at places such as
3329 statement boundaries.  See also C<sv_newmortal> and C<sv_mortalcopy>.
3330
3331         SV*     sv_2mortal(SV* sv)
3332
3333 =for hackers
3334 Found in file sv.c
3335
3336 =item sv_2nv
3337
3338 Return the num value of an SV, doing any necessary string or integer
3339 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3340 macros.
3341
3342         NV      sv_2nv(SV* sv)
3343
3344 =for hackers
3345 Found in file sv.c
3346
3347 =item sv_2pvbyte
3348
3349 Return a pointer to the byte-encoded representation of the SV, and set *lp
3350 to its length.  May cause the SV to be downgraded from UTF8 as a
3351 side-effect.
3352
3353 Usually accessed via the C<SvPVbyte> macro.
3354
3355         char*   sv_2pvbyte(SV* sv, STRLEN* lp)
3356
3357 =for hackers
3358 Found in file sv.c
3359
3360 =item sv_2pvbyte_nolen
3361
3362 Return a pointer to the byte-encoded representation of the SV.
3363 May cause the SV to be downgraded from UTF8 as a side-effect.
3364
3365 Usually accessed via the C<SvPVbyte_nolen> macro.
3366
3367         char*   sv_2pvbyte_nolen(SV* sv)
3368
3369 =for hackers
3370 Found in file sv.c
3371
3372 =item sv_2pvutf8
3373
3374 Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3375 to its length.  May cause the SV to be upgraded to UTF8 as a side-effect.
3376
3377 Usually accessed via the C<SvPVutf8> macro.
3378
3379         char*   sv_2pvutf8(SV* sv, STRLEN* lp)
3380
3381 =for hackers
3382 Found in file sv.c
3383
3384 =item sv_2pvutf8_nolen
3385
3386 Return a pointer to the UTF8-encoded representation of the SV.
3387 May cause the SV to be upgraded to UTF8 as a side-effect.
3388
3389 Usually accessed via the C<SvPVutf8_nolen> macro.
3390
3391         char*   sv_2pvutf8_nolen(SV* sv)
3392
3393 =for hackers
3394 Found in file sv.c
3395
3396 =item sv_2pv_flags
3397
3398 Returns a pointer to the string value of an SV, and sets *lp to its length.
3399 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3400 if necessary.
3401 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3402 usually end up here too.
3403
3404         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3405
3406 =for hackers
3407 Found in file sv.c
3408
3409 =item sv_2pv_nolen
3410
3411 Like C<sv_2pv()>, but doesn't return the length too. You should usually
3412 use the macro wrapper C<SvPV_nolen(sv)> instead.
3413         char*   sv_2pv_nolen(SV* sv)
3414
3415 =for hackers
3416 Found in file sv.c
3417
3418 =item sv_2uv
3419
3420 Return the unsigned integer value of an SV, doing any necessary string
3421 conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3422 macros.
3423
3424         UV      sv_2uv(SV* sv)
3425
3426 =for hackers
3427 Found in file sv.c
3428
3429 =item sv_backoff
3430
3431 Remove any string offset. You should normally use the C<SvOOK_off> macro
3432 wrapper instead.
3433
3434         int     sv_backoff(SV* sv)
3435
3436 =for hackers
3437 Found in file sv.c
3438
3439 =item sv_bless
3440
3441 Blesses an SV into a specified package.  The SV must be an RV.  The package
3442 must be designated by its stash (see C<gv_stashpv()>).  The reference count
3443 of the SV is unaffected.
3444
3445         SV*     sv_bless(SV* sv, HV* stash)
3446
3447 =for hackers
3448 Found in file sv.c
3449
3450 =item sv_catpv
3451
3452 Concatenates the string onto the end of the string which is in the SV.
3453 If the SV has the UTF8 status set, then the bytes appended should be
3454 valid UTF8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
3455
3456         void    sv_catpv(SV* sv, const char* ptr)
3457
3458 =for hackers
3459 Found in file sv.c
3460
3461 =item sv_catpvf
3462
3463 Processes its arguments like C<sprintf> and appends the formatted
3464 output to an SV.  If the appended data contains "wide" characters
3465 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3466 and characters >255 formatted with %c), the original SV might get
3467 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.
3468 C<SvSETMAGIC()> must typically be called after calling this function
3469 to handle 'set' magic.
3470
3471         void    sv_catpvf(SV* sv, const char* pat, ...)
3472
3473 =for hackers
3474 Found in file sv.c
3475
3476 =item sv_catpvf_mg
3477
3478 Like C<sv_catpvf>, but also handles 'set' magic.
3479
3480         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
3481
3482 =for hackers
3483 Found in file sv.c
3484
3485 =item sv_catpvn
3486
3487 Concatenates the string onto the end of the string which is in the SV.  The
3488 C<len> indicates number of bytes to copy.  If the SV has the UTF8
3489 status set, then the bytes appended should be valid UTF8.
3490 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
3491
3492         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3493
3494 =for hackers
3495 Found in file sv.c
3496
3497 =item sv_catpvn_flags
3498
3499 Concatenates the string onto the end of the string which is in the SV.  The
3500 C<len> indicates number of bytes to copy.  If the SV has the UTF8
3501 status set, then the bytes appended should be valid UTF8.
3502 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3503 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3504 in terms of this function.
3505
3506         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3507
3508 =for hackers
3509 Found in file sv.c
3510
3511 =item sv_catpvn_mg
3512
3513 Like C<sv_catpvn>, but also handles 'set' magic.
3514
3515         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3516
3517 =for hackers
3518 Found in file sv.c
3519
3520 =item sv_catpv_mg
3521
3522 Like C<sv_catpv>, but also handles 'set' magic.
3523
3524         void    sv_catpv_mg(SV *sv, const char *ptr)
3525
3526 =for hackers
3527 Found in file sv.c
3528
3529 =item sv_catsv
3530
3531 Concatenates the string from SV C<ssv> onto the end of the string in
3532 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
3533 not 'set' magic.  See C<sv_catsv_mg>.
3534
3535         void    sv_catsv(SV* dsv, SV* ssv)
3536
3537 =for hackers
3538 Found in file sv.c
3539
3540 =item sv_catsv_flags
3541
3542 Concatenates the string from SV C<ssv> onto the end of the string in
3543 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
3544 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3545 and C<sv_catsv_nomg> are implemented in terms of this function.
3546
3547         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3548
3549 =for hackers
3550 Found in file sv.c
3551
3552 =item sv_catsv_mg
3553
3554 Like C<sv_catsv>, but also handles 'set' magic.
3555
3556         void    sv_catsv_mg(SV *dstr, SV *sstr)
3557
3558 =for hackers
3559 Found in file sv.c
3560
3561 =item sv_chop
3562
3563 Efficient removal of characters from the beginning of the string buffer.
3564 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3565 the string buffer.  The C<ptr> becomes the first character of the adjusted
3566 string. Uses the "OOK hack".
3567
3568         void    sv_chop(SV* sv, char* ptr)
3569
3570 =for hackers
3571 Found in file sv.c
3572
3573 =item sv_clear
3574
3575 Clear an SV: call any destructors, free up any memory used by the body,
3576 and free the body itself. The SV's head is I<not> freed, although
3577 its type is set to all 1's so that it won't inadvertently be assumed
3578 to be live during global destruction etc.
3579 This function should only be called when REFCNT is zero. Most of the time
3580 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3581 instead.
3582
3583         void    sv_clear(SV* sv)
3584
3585 =for hackers
3586 Found in file sv.c
3587
3588 =item sv_cmp
3589
3590 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
3591 string in C<sv1> is less than, equal to, or greater than the string in
3592 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3593 coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
3594
3595         I32     sv_cmp(SV* sv1, SV* sv2)
3596
3597 =for hackers
3598 Found in file sv.c
3599
3600 =item sv_cmp_locale
3601
3602 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3603 'use bytes' aware, handles get magic, and will coerce its args to strings
3604 if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
3605
3606         I32     sv_cmp_locale(SV* sv1, SV* sv2)
3607
3608 =for hackers
3609 Found in file sv.c
3610
3611 =item sv_collxfrm
3612
3613 Add Collate Transform magic to an SV if it doesn't already have it.
3614
3615 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3616 scalar data of the variable, but transformed to such a format that a normal
3617 memory comparison can be used to compare the data according to the locale
3618 settings.
3619
3620         char*   sv_collxfrm(SV* sv, STRLEN* nxp)
3621
3622 =for hackers
3623 Found in file sv.c
3624
3625 =item sv_copypv
3626
3627 Copies a stringified representation of the source SV into the
3628 destination SV.  Automatically performs any necessary mg_get and
3629 coercion of numeric values into strings.  Guaranteed to preserve
3630 UTF-8 flag even from overloaded objects.  Similar in nature to
3631 sv_2pv[_flags] but operates directly on an SV instead of just the
3632 string.  Mostly uses sv_2pv_flags to do its work, except when that
3633 would lose the UTF-8'ness of the PV.
3634
3635         void    sv_copypv(SV* dsv, SV* ssv)
3636
3637 =for hackers
3638 Found in file sv.c
3639
3640 =item sv_dec
3641
3642 Auto-decrement of the value in the SV, doing string to numeric conversion
3643 if necessary. Handles 'get' magic.
3644
3645         void    sv_dec(SV* sv)
3646
3647 =for hackers
3648 Found in file sv.c
3649
3650 =item sv_derived_from
3651
3652 Returns a boolean indicating whether the SV is derived from the specified
3653 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
3654 for class names as well as for objects.
3655
3656         bool    sv_derived_from(SV* sv, const char* name)
3657
3658 =for hackers
3659 Found in file universal.c
3660
3661 =item sv_eq
3662
3663 Returns a boolean indicating whether the strings in the two SVs are
3664 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3665 coerce its args to strings if necessary.
3666
3667         I32     sv_eq(SV* sv1, SV* sv2)
3668
3669 =for hackers
3670 Found in file sv.c
3671
3672 =item sv_force_normal
3673
3674 Undo various types of fakery on an SV: if the PV is a shared string, make
3675 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3676 an xpvmg. See also C<sv_force_normal_flags>.
3677
3678         void    sv_force_normal(SV *sv)
3679
3680 =for hackers
3681 Found in file sv.c
3682
3683 =item sv_force_normal_flags
3684
3685 Undo various types of fakery on an SV: if the PV is a shared string, make
3686 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3687 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
3688 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
3689 then a copy-on-write scalar drops its PV buffer (if any) and becomes
3690 SvPOK_off rather than making a copy. (Used where this scalar is about to be
3691 set to some other value. In addtion, the C<flags> parameter gets passed to
3692 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
3693 with flags set to 0.
3694
3695         void    sv_force_normal_flags(SV *sv, U32 flags)
3696
3697 =for hackers
3698 Found in file sv.c
3699
3700 =item sv_free
3701
3702 Decrement an SV's reference count, and if it drops to zero, call
3703 C<sv_clear> to invoke destructors and free up any memory used by
3704 the body; finally, deallocate the SV's head itself.
3705 Normally called via a wrapper macro C<SvREFCNT_dec>.
3706
3707         void    sv_free(SV* sv)
3708
3709 =for hackers
3710 Found in file sv.c
3711
3712 =item sv_gets
3713
3714 Get a line from the filehandle and store it into the SV, optionally
3715 appending to the currently-stored string.
3716
3717         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
3718
3719 =for hackers
3720 Found in file sv.c
3721
3722 =item sv_grow
3723
3724 Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
3725 upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
3726 Use the C<SvGROW> wrapper instead.
3727
3728         char*   sv_grow(SV* sv, STRLEN newlen)
3729
3730 =for hackers
3731 Found in file sv.c
3732
3733 =item sv_inc
3734
3735 Auto-increment of the value in the SV, doing string to numeric conversion
3736 if necessary. Handles 'get' magic.
3737
3738         void    sv_inc(SV* sv)
3739
3740 =for hackers
3741 Found in file sv.c
3742
3743 =item sv_insert
3744
3745 Inserts a string at the specified offset/length within the SV. Similar to
3746 the Perl substr() function.
3747
3748         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3749
3750 =for hackers
3751 Found in file sv.c
3752
3753 =item sv_isa
3754
3755 Returns a boolean indicating whether the SV is blessed into the specified
3756 class.  This does not check for subtypes; use C<sv_derived_from> to verify
3757 an inheritance relationship.
3758
3759         int     sv_isa(SV* sv, const char* name)
3760
3761 =for hackers
3762 Found in file sv.c
3763
3764 =item sv_isobject
3765
3766 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3767 object.  If the SV is not an RV, or if the object is not blessed, then this
3768 will return false.
3769
3770         int     sv_isobject(SV* sv)
3771
3772 =for hackers
3773 Found in file sv.c
3774
3775 =item sv_iv
3776
3777 A private implementation of the C<SvIVx> macro for compilers which can't
3778 cope with complex macro expressions. Always use the macro instead.
3779
3780         IV      sv_iv(SV* sv)
3781
3782 =for hackers
3783 Found in file sv.c
3784
3785 =item sv_len
3786
3787 Returns the length of the string in the SV. Handles magic and type
3788 coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
3789
3790         STRLEN  sv_len(SV* sv)
3791
3792 =for hackers
3793 Found in file sv.c
3794
3795 =item sv_len_utf8
3796
3797 Returns the number of characters in the string in an SV, counting wide
3798 UTF8 bytes as a single character. Handles magic and type coercion.
3799
3800         STRLEN  sv_len_utf8(SV* sv)
3801
3802 =for hackers
3803 Found in file sv.c
3804
3805 =item sv_magic
3806
3807 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3808 then adds a new magic item of type C<how> to the head of the magic list.
3809
3810         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3811
3812 =for hackers
3813 Found in file sv.c
3814
3815 =item sv_magicext
3816
3817 Adds magic to an SV, upgrading it if necessary. Applies the
3818 supplied vtable and returns pointer to the magic added.
3819
3820 Note that sv_magicext will allow things that sv_magic will not.
3821 In particular you can add magic to SvREADONLY SVs and and more than
3822 one instance of the same 'how'
3823
3824 I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
3825 if C<namelen> is zero then C<name> is stored as-is and - as another special
3826 case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
3827 an C<SV*> and has its REFCNT incremented
3828
3829 (This is now used as a subroutine by sv_magic.)
3830
3831         MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen        )
3832
3833 =for hackers
3834 Found in file sv.c
3835
3836 =item sv_mortalcopy
3837
3838 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
3839 The new SV is marked as mortal. It will be destroyed "soon", either by an
3840 explicit call to FREETMPS, or by an implicit call at places such as
3841 statement boundaries.  See also C<sv_newmortal> and C<sv_2mortal>.
3842
3843         SV*     sv_mortalcopy(SV* oldsv)
3844
3845 =for hackers
3846 Found in file sv.c
3847
3848 =item sv_newmortal
3849
3850 Creates a new null SV which is mortal.  The reference count of the SV is
3851 set to 1. It will be destroyed "soon", either by an explicit call to
3852 FREETMPS, or by an implicit call at places such as statement boundaries.
3853 See also C<sv_mortalcopy> and C<sv_2mortal>.
3854
3855         SV*     sv_newmortal()
3856
3857 =for hackers
3858 Found in file sv.c
3859
3860 =item sv_newref
3861
3862 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3863 instead.
3864
3865         SV*     sv_newref(SV* sv)
3866
3867 =for hackers
3868 Found in file sv.c
3869
3870 =item sv_nolocking
3871
3872 Dummy routine which "locks" an SV when there is no locking module present.
3873 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3874 some level of strict-ness.
3875
3876         void    sv_nolocking(SV *)
3877
3878 =for hackers
3879 Found in file util.c
3880
3881 =item sv_nosharing
3882
3883 Dummy routine which "shares" an SV when there is no sharing module present.
3884 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3885 some level of strict-ness.
3886
3887         void    sv_nosharing(SV *)
3888
3889 =for hackers
3890 Found in file util.c
3891
3892 =item sv_nounlocking
3893
3894 Dummy routine which "unlocks" an SV when there is no locking module present.
3895 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3896 some level of strict-ness.
3897
3898         void    sv_nounlocking(SV *)
3899
3900 =for hackers
3901 Found in file util.c
3902
3903 =item sv_nv
3904
3905 A private implementation of the C<SvNVx> macro for compilers which can't
3906 cope with complex macro expressions. Always use the macro instead.
3907
3908         NV      sv_nv(SV* sv)
3909
3910 =for hackers
3911 Found in file sv.c
3912
3913 =item sv_pos_b2u
3914
3915 Converts the value pointed to by offsetp from a count of bytes from the
3916 start of the string, to a count of the equivalent number of UTF8 chars.
3917 Handles magic and type coercion.
3918
3919         void    sv_pos_b2u(SV* sv, I32* offsetp)
3920
3921 =for hackers
3922 Found in file sv.c
3923
3924 =item sv_pos_u2b
3925
3926 Converts the value pointed to by offsetp from a count of UTF8 chars from
3927 the start of the string, to a count of the equivalent number of bytes; if
3928 lenp is non-zero, it does the same to lenp, but this time starting from
3929 the offset, rather than from the start of the string. Handles magic and
3930 type coercion.
3931
3932         void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3933
3934 =for hackers
3935 Found in file sv.c
3936
3937 =item sv_pv
3938
3939 Use the C<SvPV_nolen> macro instead
3940
3941         char*   sv_pv(SV *sv)
3942
3943 =for hackers
3944 Found in file sv.c
3945
3946 =item sv_pvbyte
3947
3948 Use C<SvPVbyte_nolen> instead.
3949
3950         char*   sv_pvbyte(SV *sv)
3951
3952 =for hackers
3953 Found in file sv.c
3954
3955 =item sv_pvbyten
3956
3957 A private implementation of the C<SvPVbyte> macro for compilers
3958 which can't cope with complex macro expressions. Always use the macro
3959 instead.
3960
3961         char*   sv_pvbyten(SV *sv, STRLEN *len)
3962
3963 =for hackers
3964 Found in file sv.c
3965
3966 =item sv_pvbyten_force
3967
3968 A private implementation of the C<SvPVbytex_force> macro for compilers
3969 which can't cope with complex macro expressions. Always use the macro
3970 instead.
3971
3972         char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
3973
3974 =for hackers
3975 Found in file sv.c
3976
3977 =item sv_pvn
3978
3979 A private implementation of the C<SvPV> macro for compilers which can't
3980 cope with complex macro expressions. Always use the macro instead.
3981
3982         char*   sv_pvn(SV *sv, STRLEN *len)
3983
3984 =for hackers
3985 Found in file sv.c
3986
3987 =item sv_pvn_force
3988
3989 Get a sensible string out of the SV somehow.
3990 A private implementation of the C<SvPV_force> macro for compilers which
3991 can't cope with complex macro expressions. Always use the macro instead.
3992
3993         char*   sv_pvn_force(SV* sv, STRLEN* lp)
3994
3995 =for hackers
3996 Found in file sv.c
3997
3998 =item sv_pvn_force_flags
3999
4000 Get a sensible string out of the SV somehow.
4001 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
4002 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
4003 implemented in terms of this function.
4004 You normally want to use the various wrapper macros instead: see
4005 C<SvPV_force> and C<SvPV_force_nomg>
4006
4007         char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
4008
4009 =for hackers
4010 Found in file sv.c
4011
4012 =item sv_pvutf8
4013
4014 Use the C<SvPVutf8_nolen> macro instead
4015
4016         char*   sv_pvutf8(SV *sv)
4017
4018 =for hackers
4019 Found in file sv.c
4020
4021 =item sv_pvutf8n
4022
4023 A private implementation of the C<SvPVutf8> macro for compilers
4024 which can't cope with complex macro expressions. Always use the macro
4025 instead.
4026
4027         char*   sv_pvutf8n(SV *sv, STRLEN *len)
4028
4029 =for hackers
4030 Found in file sv.c
4031
4032 =item sv_pvutf8n_force
4033
4034 A private implementation of the C<SvPVutf8_force> macro for compilers
4035 which can't cope with complex macro expressions. Always use the macro
4036 instead.
4037
4038         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
4039
4040 =for hackers
4041 Found in file sv.c
4042
4043 =item sv_reftype
4044
4045 Returns a string describing what the SV is a reference to.
4046
4047         char*   sv_reftype(SV* sv, int ob)
4048
4049 =for hackers
4050 Found in file sv.c
4051
4052 =item sv_replace
4053
4054 Make the first argument a copy of the second, then delete the original.
4055 The target SV physically takes over ownership of the body of the source SV
4056 and inherits its flags; however, the target keeps any magic it owns,
4057 and any magic in the source is discarded.
4058 Note that this is a rather specialist SV copying operation; most of the
4059 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
4060
4061         void    sv_replace(SV* sv, SV* nsv)
4062
4063 =for hackers
4064 Found in file sv.c
4065
4066 =item sv_report_used
4067
4068 Dump the contents of all SVs not yet freed. (Debugging aid).
4069
4070         void    sv_report_used()
4071
4072 =for hackers
4073 Found in file sv.c
4074
4075 =item sv_reset
4076
4077 Underlying implementation for the C<reset> Perl function.
4078 Note that the perl-level function is vaguely deprecated.
4079
4080         void    sv_reset(char* s, HV* stash)
4081
4082 =for hackers
4083 Found in file sv.c
4084
4085 =item sv_rvweaken
4086
4087 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
4088 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
4089 push a back-reference to this RV onto the array of backreferences
4090 associated with that magic.
4091
4092         SV*     sv_rvweaken(SV *sv)
4093
4094 =for hackers
4095 Found in file sv.c
4096
4097 =item sv_setiv
4098
4099 Copies an integer into the given SV, upgrading first if necessary.
4100 Does not handle 'set' magic.  See also C<sv_setiv_mg>.
4101
4102         void    sv_setiv(SV* sv, IV num)
4103
4104 =for hackers
4105 Found in file sv.c
4106
4107 =item sv_setiv_mg
4108
4109 Like C<sv_setiv>, but also handles 'set' magic.
4110
4111         void    sv_setiv_mg(SV *sv, IV i)
4112
4113 =for hackers
4114 Found in file sv.c
4115
4116 =item sv_setnv
4117
4118 Copies a double into the given SV, upgrading first if necessary.
4119 Does not handle 'set' magic.  See also C<sv_setnv_mg>.
4120
4121         void    sv_setnv(SV* sv, NV num)
4122
4123 =for hackers
4124 Found in file sv.c
4125
4126 =item sv_setnv_mg
4127
4128 Like C<sv_setnv>, but also handles 'set' magic.
4129
4130         void    sv_setnv_mg(SV *sv, NV num)
4131
4132 =for hackers
4133 Found in file sv.c
4134
4135 =item sv_setpv
4136
4137 Copies a string into an SV.  The string must be null-terminated.  Does not
4138 handle 'set' magic.  See C<sv_setpv_mg>.
4139
4140         void    sv_setpv(SV* sv, const char* ptr)
4141
4142 =for hackers
4143 Found in file sv.c
4144
4145 =item sv_setpvf
4146
4147 Processes its arguments like C<sprintf> and sets an SV to the formatted
4148 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
4149
4150         void    sv_setpvf(SV* sv, const char* pat, ...)
4151
4152 =for hackers
4153 Found in file sv.c
4154
4155 =item sv_setpvf_mg
4156
4157 Like C<sv_setpvf>, but also handles 'set' magic.
4158
4159         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
4160
4161 =for hackers
4162 Found in file sv.c
4163
4164 =item sv_setpvn
4165
4166 Copies a string into an SV.  The C<len> parameter indicates the number of
4167 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
4168
4169         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
4170
4171 =for hackers
4172 Found in file sv.c
4173
4174 =item sv_setpvn_mg
4175
4176 Like C<sv_setpvn>, but also handles 'set' magic.
4177
4178         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
4179
4180 =for hackers
4181 Found in file sv.c
4182
4183 =item sv_setpv_mg
4184
4185 Like C<sv_setpv>, but also handles 'set' magic.
4186
4187         void    sv_setpv_mg(SV *sv, const char *ptr)
4188
4189 =for hackers
4190 Found in file sv.c
4191
4192 =item sv_setref_iv
4193
4194 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
4195 argument will be upgraded to an RV.  That RV will be modified to point to
4196 the new SV.  The C<classname> argument indicates the package for the
4197 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4198 will be returned and will have a reference count of 1.
4199
4200         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
4201
4202 =for hackers
4203 Found in file sv.c
4204
4205 =item sv_setref_nv
4206
4207 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
4208 argument will be upgraded to an RV.  That RV will be modified to point to
4209 the new SV.  The C<classname> argument indicates the package for the
4210 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4211 will be returned and will have a reference count of 1.
4212
4213         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
4214
4215 =for hackers
4216 Found in file sv.c
4217
4218 =item sv_setref_pv
4219
4220 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
4221 argument will be upgraded to an RV.  That RV will be modified to point to
4222 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
4223 into the SV.  The C<classname> argument indicates the package for the
4224 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4225 will be returned and will have a reference count of 1.
4226
4227 Do not use with other Perl types such as HV, AV, SV, CV, because those
4228 objects will become corrupted by the pointer copy process.
4229
4230 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
4231
4232         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
4233
4234 =for hackers
4235 Found in file sv.c
4236
4237 =item sv_setref_pvn
4238
4239 Copies a string into a new SV, optionally blessing the SV.  The length of the
4240 string must be specified with C<n>.  The C<rv> argument will be upgraded to
4241 an RV.  That RV will be modified to point to the new SV.  The C<classname>
4242 argument indicates the package for the blessing.  Set C<classname> to
4243 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
4244 a reference count of 1.
4245
4246 Note that C<sv_setref_pv> copies the pointer while this copies the string.
4247
4248         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
4249
4250 =for hackers
4251 Found in file sv.c
4252
4253 =item sv_setref_uv
4254
4255 Copies an unsigned integer into a new SV, optionally blessing the SV.  The C<rv>
4256 argument will be upgraded to an RV.  That RV will be modified to point to
4257 the new SV.  The C<classname> argument indicates the package for the
4258 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4259 will be returned and will have a reference count of 1.
4260
4261         SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)
4262
4263 =for hackers
4264 Found in file sv.c
4265
4266 =item sv_setsv
4267
4268 Copies the contents of the source SV C<ssv> into the destination SV
4269 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
4270 function if the source SV needs to be reused. Does not handle 'set' magic.
4271 Loosely speaking, it performs a copy-by-value, obliterating any previous
4272 content of the destination.
4273
4274 You probably want to use one of the assortment of wrappers, such as
4275 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4276 C<SvSetMagicSV_nosteal>.
4277
4278         void    sv_setsv(SV* dsv, SV* ssv)
4279
4280 =for hackers
4281 Found in file sv.c
4282
4283 =item sv_setsv_flags
4284
4285 Copies the contents of the source SV C<ssv> into the destination SV
4286 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
4287 function if the source SV needs to be reused. Does not handle 'set' magic.
4288 Loosely speaking, it performs a copy-by-value, obliterating any previous
4289 content of the destination.
4290 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
4291 C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
4292 implemented in terms of this function.
4293
4294 You probably want to use one of the assortment of wrappers, such as
4295 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4296 C<SvSetMagicSV_nosteal>.
4297
4298 This is the primary function for copying scalars, and most other
4299 copy-ish functions and macros use this underneath.
4300
4301         void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
4302
4303 =for hackers
4304 Found in file sv.c
4305
4306 =item sv_setsv_mg
4307
4308 Like C<sv_setsv>, but also handles 'set' magic.
4309
4310         void    sv_setsv_mg(SV *dstr, SV *sstr)
4311
4312 =for hackers
4313 Found in file sv.c
4314
4315 =item sv_setuv
4316
4317 Copies an unsigned integer into the given SV, upgrading first if necessary.
4318 Does not handle 'set' magic.  See also C<sv_setuv_mg>.
4319
4320         void    sv_setuv(SV* sv, UV num)
4321
4322 =for hackers
4323 Found in file sv.c
4324
4325 =item sv_setuv_mg
4326
4327 Like C<sv_setuv>, but also handles 'set' magic.
4328
4329         void    sv_setuv_mg(SV *sv, UV u)
4330
4331 =for hackers
4332 Found in file sv.c
4333
4334 =item sv_taint
4335
4336 Taint an SV. Use C<SvTAINTED_on> instead.
4337         void    sv_taint(SV* sv)
4338
4339 =for hackers
4340 Found in file sv.c
4341
4342 =item sv_tainted
4343
4344 Test an SV for taintedness. Use C<SvTAINTED> instead.
4345         bool    sv_tainted(SV* sv)
4346
4347 =for hackers
4348 Found in file sv.c
4349
4350 =item sv_true
4351
4352 Returns true if the SV has a true value by Perl's rules.
4353 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
4354 instead use an in-line version.
4355
4356         I32     sv_true(SV *sv)
4357
4358 =for hackers
4359 Found in file sv.c
4360
4361 =item sv_unmagic
4362
4363 Removes all magic of type C<type> from an SV.
4364
4365         int     sv_unmagic(SV* sv, int type)
4366
4367 =for hackers
4368 Found in file sv.c
4369
4370 =item sv_unref
4371
4372 Unsets the RV status of the SV, and decrements the reference count of
4373 whatever was being referenced by the RV.  This can almost be thought of
4374 as a reversal of C<newSVrv>.  This is C<sv_unref_flags> with the C<flag>
4375 being zero.  See C<SvROK_off>.
4376
4377         void    sv_unref(SV* sv)
4378
4379 =for hackers
4380 Found in file sv.c
4381
4382 =item sv_unref_flags
4383
4384 Unsets the RV status of the SV, and decrements the reference count of
4385 whatever was being referenced by the RV.  This can almost be thought of
4386 as a reversal of C<newSVrv>.  The C<cflags> argument can contain
4387 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
4388 (otherwise the decrementing is conditional on the reference count being
4389 different from one or the reference being a readonly SV).
4390 See C<SvROK_off>.
4391
4392         void    sv_unref_flags(SV* sv, U32 flags)
4393
4394 =for hackers
4395 Found in file sv.c
4396
4397 =item sv_untaint
4398
4399 Untaint an SV. Use C<SvTAINTED_off> instead.
4400         void    sv_untaint(SV* sv)
4401
4402 =for hackers
4403 Found in file sv.c
4404
4405 =item sv_upgrade
4406
4407 Upgrade an SV to a more complex form.  Generally adds a new body type to the
4408 SV, then copies across as much information as possible from the old body.
4409 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
4410
4411         bool    sv_upgrade(SV* sv, U32 mt)
4412
4413 =for hackers
4414 Found in file sv.c
4415
4416 =item sv_usepvn
4417
4418 Tells an SV to use C<ptr> to find its string value.  Normally the string is
4419 stored inside the SV but sv_usepvn allows the SV to use an outside string.
4420 The C<ptr> should point to memory that was allocated by C<malloc>.  The
4421 string length, C<len>, must be supplied.  This function will realloc the
4422 memory pointed to by C<ptr>, so that pointer should not be freed or used by
4423 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
4424 See C<sv_usepvn_mg>.
4425
4426         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
4427
4428 =for hackers
4429 Found in file sv.c
4430
4431 =item sv_usepvn_mg
4432
4433 Like C<sv_usepvn>, but also handles 'set' magic.
4434
4435         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
4436
4437 =for hackers
4438 Found in file sv.c
4439
4440 =item sv_utf8_decode
4441
4442 Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
4443 turn off SvUTF8 if needed so that we see characters. Used as a building block
4444 for decode_utf8 in Encode.xs
4445
4446 NOTE: this function is experimental and may change or be
4447 removed without notice.
4448
4449         bool    sv_utf8_decode(SV *sv)
4450
4451 =for hackers
4452 Found in file sv.c
4453
4454 =item sv_utf8_downgrade
4455
4456 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
4457 This may not be possible if the PV contains non-byte encoding characters;
4458 if this is the case, either returns false or, if C<fail_ok> is not
4459 true, croaks.
4460
4461 This is not as a general purpose Unicode to byte encoding interface:
4462 use the Encode extension for that.
4463
4464 NOTE: this function is experimental and may change or be
4465 removed without notice.
4466
4467         bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
4468
4469 =for hackers
4470 Found in file sv.c
4471
4472 =item sv_utf8_encode
4473
4474 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
4475 flag so that it looks like octets again. Used as a building block
4476 for encode_utf8 in Encode.xs
4477
4478         void    sv_utf8_encode(SV *sv)
4479
4480 =for hackers
4481 Found in file sv.c
4482
4483 =item sv_utf8_upgrade
4484
4485 Convert the PV of an SV to its UTF8-encoded form.
4486 Forces the SV to string form if it is not already.
4487 Always sets the SvUTF8 flag to avoid future validity checks even
4488 if all the bytes have hibit clear.
4489
4490 This is not as a general purpose byte encoding to Unicode interface:
4491 use the Encode extension for that.
4492
4493         STRLEN  sv_utf8_upgrade(SV *sv)
4494
4495 =for hackers
4496 Found in file sv.c
4497
4498 =item sv_utf8_upgrade_flags
4499
4500 Convert the PV of an SV to its UTF8-encoded form.
4501 Forces the SV to string form if it is not already.
4502 Always sets the SvUTF8 flag to avoid future validity checks even
4503 if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
4504 will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
4505 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
4506
4507 This is not as a general purpose byte encoding to Unicode interface:
4508 use the Encode extension for that.
4509
4510         STRLEN  sv_utf8_upgrade_flags(SV *sv, I32 flags)
4511
4512 =for hackers
4513 Found in file sv.c
4514
4515 =item sv_uv
4516
4517 A private implementation of the C<SvUVx> macro for compilers which can't
4518 cope with complex macro expressions. Always use the macro instead.
4519
4520         UV      sv_uv(SV* sv)
4521
4522 =for hackers
4523 Found in file sv.c
4524
4525 =item sv_vcatpvfn
4526
4527 Processes its arguments like C<vsprintf> and appends the formatted output
4528 to an SV.  Uses an array of SVs if the C style variable argument list is
4529 missing (NULL).  When running with taint checks enabled, indicates via
4530 C<maybe_tainted> if results are untrustworthy (often due to the use of
4531 locales).
4532
4533 Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
4534
4535         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4536
4537 =for hackers
4538 Found in file sv.c
4539
4540 =item sv_vsetpvfn
4541
4542 Works like C<vcatpvfn> but copies the text into the SV instead of
4543 appending it.
4544
4545 Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
4546
4547         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4548
4549 =for hackers
4550 Found in file sv.c
4551
4552 =item upg_version
4553
4554 In-place upgrade of the supplied SV to a version object.
4555
4556     SV *sv = upg_version(SV *sv);
4557
4558 Returns a pointer to the upgraded SV.
4559
4560         SV*     upg_version(SV *ver)
4561
4562 =for hackers
4563 Found in file util.c
4564
4565 =item vnumify
4566
4567 Accepts a version (or vstring) object and returns the
4568 normalized floating point representation.  Call like:
4569
4570     sv = vnumify(sv,SvRV(rv));
4571
4572 NOTE: no checking is done to see if the object is of the
4573 correct type (for speed).
4574
4575         SV*     vnumify(SV *sv, SV *vs)
4576
4577 =for hackers
4578 Found in file util.c
4579
4580 =item vstringify
4581
4582 Accepts a version (or vstring) object and returns the
4583 normalized representation.  Call like:
4584
4585     sv = vstringify(sv,SvRV(rv));
4586
4587 NOTE: no checking is done to see if the object is of the
4588 correct type (for speed).
4589
4590         SV*     vstringify(SV *sv, SV *vs)
4591
4592 =for hackers
4593 Found in file util.c
4594
4595
4596 =back
4597
4598 =head1 Unicode Support
4599
4600 =over 8
4601
4602 =item bytes_from_utf8
4603
4604 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4605 Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
4606 the newly-created string, and updates C<len> to contain the new
4607 length.  Returns the original string if no conversion occurs, C<len>
4608 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
4609 0 if C<s> is converted or contains all 7bit characters.
4610
4611 NOTE: this function is experimental and may change or be
4612 removed without notice.
4613
4614         U8*     bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
4615
4616 =for hackers
4617 Found in file utf8.c
4618
4619 =item bytes_to_utf8
4620
4621 Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
4622 Returns a pointer to the newly-created string, and sets C<len> to
4623 reflect the new length.
4624
4625 NOTE: this function is experimental and may change or be
4626 removed without notice.
4627
4628         U8*     bytes_to_utf8(U8 *s, STRLEN *len)
4629
4630 =for hackers
4631 Found in file utf8.c
4632
4633 =item ibcmp_utf8
4634
4635 Return true if the strings s1 and s2 differ case-insensitively, false
4636 if not (if they are equal case-insensitively).  If u1 is true, the
4637 string s1 is assumed to be in UTF-8-encoded Unicode.  If u2 is true,
4638 the string s2 is assumed to be in UTF-8-encoded Unicode.  If u1 or u2
4639 are false, the respective string is assumed to be in native 8-bit
4640 encoding.
4641
4642 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
4643 in there (they will point at the beginning of the I<next> character).
4644 If the pointers behind pe1 or pe2 are non-NULL, they are the end
4645 pointers beyond which scanning will not continue under any
4646 circustances.  If the byte lengths l1 and l2 are non-zero, s1+l1 and
4647 s2+l2 will be used as goal end pointers that will also stop the scan,
4648 and which qualify towards defining a successful match: all the scans
4649 that define an explicit length must reach their goal pointers for
4650 a match to succeed).
4651
4652 For case-insensitiveness, the "casefolding" of Unicode is used
4653 instead of upper/lowercasing both the characters, see
4654 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
4655
4656         I32     ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
4657
4658 =for hackers
4659 Found in file utf8.c
4660
4661 =item is_utf8_char
4662
4663 Tests if some arbitrary number of bytes begins in a valid UTF-8
4664 character.  Note that an INVARIANT (i.e. ASCII) character is a valid
4665 UTF-8 character.  The actual number of bytes in the UTF-8 character
4666 will be returned if it is valid, otherwise 0.
4667
4668         STRLEN  is_utf8_char(U8 *p)
4669
4670 =for hackers
4671 Found in file utf8.c
4672
4673 =item is_utf8_string
4674
4675 Returns true if first C<len> bytes of the given string form a valid UTF8
4676 string, false otherwise.  Note that 'a valid UTF8 string' does not mean
4677 'a string that contains UTF8' because a valid ASCII string is a valid
4678 UTF8 string.
4679
4680         bool    is_utf8_string(U8 *s, STRLEN len)
4681
4682 =for hackers
4683 Found in file utf8.c
4684
4685 =item pv_uni_display
4686
4687 Build to the scalar dsv a displayable version of the string spv,
4688 length len, the displayable version being at most pvlim bytes long
4689 (if longer, the rest is truncated and "..." will be appended).
4690
4691 The flags argument can have UNI_DISPLAY_ISPRINT set to display
4692 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
4693 to display the \\[nrfta\\] as the backslashed versions (like '\n')
4694 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
4695 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
4696 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
4697
4698 The pointer to the PV of the dsv is returned.
4699
4700         char*   pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
4701
4702 =for hackers
4703 Found in file utf8.c
4704
4705 =item sv_recode_to_utf8
4706
4707 The encoding is assumed to be an Encode object, on entry the PV
4708 of the sv is assumed to be octets in that encoding, and the sv
4709 will be converted into Unicode (and UTF-8).
4710
4711 If the sv already is UTF-8 (or if it is not POK), or if the encoding
4712 is not a reference, nothing is done to the sv.  If the encoding is not
4713 an C<Encode::XS> Encoding object, bad things will happen.
4714 (See F<lib/encoding.pm> and L<Encode>).
4715
4716 The PV of the sv is returned.
4717
4718         char*   sv_recode_to_utf8(SV* sv, SV *encoding)
4719
4720 =for hackers
4721 Found in file sv.c
4722
4723 =item sv_uni_display
4724
4725 Build to the scalar dsv a displayable version of the scalar sv,
4726 the displayable version being at most pvlim bytes long
4727 (if longer, the rest is truncated and "..." will be appended).
4728
4729 The flags argument is as in pv_uni_display().
4730
4731 The pointer to the PV of the dsv is returned.
4732
4733         char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4734
4735 =for hackers
4736 Found in file utf8.c
4737
4738 =item to_utf8_case
4739
4740 The "p" contains the pointer to the UTF-8 string encoding
4741 the character that is being converted.
4742
4743 The "ustrp" is a pointer to the character buffer to put the
4744 conversion result to.  The "lenp" is a pointer to the length
4745 of the result.
4746
4747 The "swashp" is a pointer to the swash to use.
4748
4749 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
4750 and loaded by SWASHGET, using lib/utf8_heavy.pl.  The special (usually,
4751 but not always, a multicharacter mapping), is tried first.
4752
4753 The "special" is a string like "utf8::ToSpecLower", which means the
4754 hash %utf8::ToSpecLower.  The access to the hash is through
4755 Perl_to_utf8_case().
4756
4757 The "normal" is a string like "ToLower" which means the swash
4758 %utf8::ToLower.
4759
4760         UV      to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
4761
4762 =for hackers
4763 Found in file utf8.c
4764
4765 =item to_utf8_fold
4766
4767 Convert the UTF-8 encoded character at p to its foldcase version and
4768 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4769 that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
4770 foldcase version may be longer than the original character (up to
4771 three characters).
4772
4773 The first character of the foldcased version is returned
4774 (but note, as explained above, that there may be more.)
4775
4776         UV      to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
4777
4778 =for hackers
4779 Found in file utf8.c
4780
4781 =item to_utf8_lower
4782
4783 Convert the UTF-8 encoded character at p to its lowercase version and
4784 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4785 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4786 lowercase version may be longer than the original character (up to two
4787 characters).
4788
4789 The first character of the lowercased version is returned
4790 (but note, as explained above, that there may be more.)
4791
4792         UV      to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
4793
4794 =for hackers
4795 Found in file utf8.c
4796
4797 =item to_utf8_title
4798
4799 Convert the UTF-8 encoded character at p to its titlecase version and
4800 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4801 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4802 titlecase version may be longer than the original character (up to two
4803 characters).
4804
4805 The first character of the titlecased version is returned
4806 (but note, as explained above, that there may be more.)
4807
4808         UV      to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
4809
4810 =for hackers
4811 Found in file utf8.c
4812
4813 =item to_utf8_upper
4814
4815 Convert the UTF-8 encoded character at p to its uppercase version and
4816 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4817 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4818 uppercase version may be longer than the original character (up to two
4819 characters).
4820
4821 The first character of the uppercased version is returned
4822 (but note, as explained above, that there may be more.)
4823
4824         UV      to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
4825
4826 =for hackers
4827 Found in file utf8.c
4828
4829 =item utf8n_to_uvchr
4830
4831 Returns the native character value of the first character in the string C<s>
4832 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4833 length, in bytes, of that character.
4834
4835 Allows length and flags to be passed to low level routine.
4836
4837         UV      utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4838
4839 =for hackers
4840 Found in file utf8.c
4841
4842 =item utf8n_to_uvuni
4843
4844 Bottom level UTF-8 decode routine.
4845 Returns the unicode code point value of the first character in the string C<s>
4846 which is assumed to be in UTF8 encoding and no longer than C<curlen>;
4847 C<retlen> will be set to the length, in bytes, of that character.
4848
4849 If C<s> does not point to a well-formed UTF8 character, the behaviour
4850 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
4851 it is assumed that the caller will raise a warning, and this function
4852 will silently just set C<retlen> to C<-1> and return zero.  If the
4853 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
4854 malformations will be given, C<retlen> will be set to the expected
4855 length of the UTF-8 character in bytes, and zero will be returned.
4856
4857 The C<flags> can also contain various flags to allow deviations from
4858 the strict UTF-8 encoding (see F<utf8.h>).
4859
4860 Most code should use utf8_to_uvchr() rather than call this directly.
4861
4862         UV      utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4863
4864 =for hackers
4865 Found in file utf8.c
4866
4867 =item utf8_distance
4868
4869 Returns the number of UTF8 characters between the UTF-8 pointers C<a>
4870 and C<b>.
4871
4872 WARNING: use only if you *know* that the pointers point inside the
4873 same UTF-8 buffer.
4874
4875         IV      utf8_distance(U8 *a, U8 *b)
4876
4877 =for hackers
4878 Found in file utf8.c
4879
4880 =item utf8_hop
4881
4882 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
4883 forward or backward.
4884
4885 WARNING: do not use the following unless you *know* C<off> is within
4886 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
4887 on the first byte of character or just after the last byte of a character.
4888
4889         U8*     utf8_hop(U8 *s, I32 off)
4890
4891 =for hackers
4892 Found in file utf8.c
4893
4894 =item utf8_length
4895
4896 Return the length of the UTF-8 char encoded string C<s> in characters.
4897 Stops at C<e> (inclusive).  If C<e E<lt> s> or if the scan would end
4898 up past C<e>, croaks.
4899
4900         STRLEN  utf8_length(U8* s, U8 *e)
4901
4902 =for hackers
4903 Found in file utf8.c
4904
4905 =item utf8_to_bytes
4906
4907 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4908 Unlike C<bytes_to_utf8>, this over-writes the original string, and
4909 updates len to contain the new length.
4910 Returns zero on failure, setting C<len> to -1.
4911
4912 NOTE: this function is experimental and may change or be
4913 removed without notice.
4914
4915         U8*     utf8_to_bytes(U8 *s, STRLEN *len)
4916
4917 =for hackers
4918 Found in file utf8.c
4919
4920 =item utf8_to_uvchr
4921
4922 Returns the native character value of the first character in the string C<s>
4923 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4924 length, in bytes, of that character.
4925
4926 If C<s> does not point to a well-formed UTF8 character, zero is
4927 returned and retlen is set, if possible, to -1.
4928
4929         UV      utf8_to_uvchr(U8 *s, STRLEN* retlen)
4930
4931 =for hackers
4932 Found in file utf8.c
4933
4934 =item utf8_to_uvuni
4935
4936 Returns the Unicode code point of the first character in the string C<s>
4937 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4938 length, in bytes, of that character.
4939
4940 This function should only be used when returned UV is considered
4941 an index into the Unicode semantic tables (e.g. swashes).
4942
4943 If C<s> does not point to a well-formed UTF8 character, zero is
4944 returned and retlen is set, if possible, to -1.
4945
4946         UV      utf8_to_uvuni(U8 *s, STRLEN* retlen)
4947
4948 =for hackers
4949 Found in file utf8.c
4950
4951 =item uvchr_to_utf8
4952
4953 Adds the UTF8 representation of the Native codepoint C<uv> to the end
4954 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4955 bytes available. The return value is the pointer to the byte after the
4956 end of the new character. In other words,
4957
4958     d = uvchr_to_utf8(d, uv);
4959
4960 is the recommended wide native character-aware way of saying
4961
4962     *(d++) = uv;
4963
4964         U8*     uvchr_to_utf8(U8 *d, UV uv)
4965
4966 =for hackers
4967 Found in file utf8.c
4968
4969 =item uvuni_to_utf8_flags
4970
4971 Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
4972 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4973 bytes available. The return value is the pointer to the byte after the
4974 end of the new character. In other words,
4975
4976     d = uvuni_to_utf8_flags(d, uv, flags);
4977
4978 or, in most cases,
4979
4980     d = uvuni_to_utf8(d, uv);
4981
4982 (which is equivalent to)
4983
4984     d = uvuni_to_utf8_flags(d, uv, 0);
4985
4986 is the recommended Unicode-aware way of saying
4987
4988     *(d++) = uv;
4989
4990         U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4991
4992 =for hackers
4993 Found in file utf8.c
4994
4995
4996 =back
4997
4998 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
4999
5000 =over 8
5001
5002 =item ax
5003
5004 Variable which is setup by C<xsubpp> to indicate the stack base offset,
5005 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
5006 must be called prior to setup the C<MARK> variable.
5007
5008         I32     ax
5009
5010 =for hackers
5011 Found in file XSUB.h
5012
5013 =item CLASS
5014
5015 Variable which is setup by C<xsubpp> to indicate the 
5016 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
5017
5018         char*   CLASS
5019
5020 =for hackers
5021 Found in file XSUB.h
5022
5023 =item dAX
5024
5025 Sets up the C<ax> variable.
5026 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
5027
5028                 dAX;
5029
5030 =for hackers
5031 Found in file XSUB.h
5032
5033 =item dITEMS
5034
5035 Sets up the C<items> variable.
5036 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
5037
5038                 dITEMS;
5039
5040 =for hackers
5041 Found in file XSUB.h
5042
5043 =item dXSARGS
5044
5045 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
5046 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
5047 This is usually handled automatically by C<xsubpp>.
5048
5049                 dXSARGS;
5050
5051 =for hackers
5052 Found in file XSUB.h
5053
5054 =item dXSI32
5055
5056 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
5057 handled automatically by C<xsubpp>.
5058
5059                 dXSI32;
5060
5061 =for hackers
5062 Found in file XSUB.h
5063
5064 =item items
5065
5066 Variable which is setup by C<xsubpp> to indicate the number of 
5067 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
5068
5069         I32     items
5070
5071 =for hackers
5072 Found in file XSUB.h
5073
5074 =item ix
5075
5076 Variable which is setup by C<xsubpp> to indicate which of an 
5077 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
5078
5079         I32     ix
5080
5081 =for hackers
5082 Found in file XSUB.h
5083
5084 =item newXSproto
5085
5086 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
5087 the subs.
5088
5089 =for hackers
5090 Found in file XSUB.h
5091
5092 =item RETVAL
5093
5094 Variable which is setup by C<xsubpp> to hold the return value for an 
5095 XSUB. This is always the proper type for the XSUB. See 
5096 L<perlxs/"The RETVAL Variable">.
5097
5098         (whatever)      RETVAL
5099
5100 =for hackers
5101 Found in file XSUB.h
5102
5103 =item ST
5104
5105 Used to access elements on the XSUB's stack.
5106
5107         SV*     ST(int ix)
5108
5109 =for hackers
5110 Found in file XSUB.h
5111
5112 =item THIS
5113
5114 Variable which is setup by C<xsubpp> to designate the object in a C++ 
5115 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
5116 L<perlxs/"Using XS With C++">.
5117
5118         (whatever)      THIS
5119
5120 =for hackers
5121 Found in file XSUB.h
5122
5123 =item XS
5124
5125 Macro to declare an XSUB and its C parameter list.  This is handled by
5126 C<xsubpp>.
5127
5128 =for hackers
5129 Found in file XSUB.h
5130
5131 =item XSRETURN_EMPTY
5132
5133 Return an empty list from an XSUB immediately.
5134
5135
5136                 XSRETURN_EMPTY;
5137
5138 =for hackers
5139 Found in file XSUB.h
5140
5141 =item XS_VERSION
5142
5143 The version identifier for an XS module.  This is usually
5144 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
5145
5146 =for hackers
5147 Found in file XSUB.h
5148
5149 =item XS_VERSION_BOOTCHECK
5150
5151 Macro to verify that a PM module's $VERSION variable matches the XS
5152 module's C<XS_VERSION> variable.  This is usually handled automatically by
5153 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
5154
5155                 XS_VERSION_BOOTCHECK;
5156
5157 =for hackers
5158 Found in file XSUB.h
5159
5160
5161 =back
5162
5163 =head1 Warning and Dieing
5164
5165 =over 8
5166
5167 =item croak
5168
5169 This is the XSUB-writer's interface to Perl's C<die> function.
5170 Normally use this function the same way you use the C C<printf>
5171 function.  See C<warn>.
5172
5173 If you want to throw an exception object, assign the object to
5174 C<$@> and then pass C<Nullch> to croak():
5175
5176    errsv = get_sv("@", TRUE);
5177    sv_setsv(errsv, exception_object);
5178    croak(Nullch);
5179
5180         void    croak(const char* pat, ...)
5181
5182 =for hackers
5183 Found in file util.c
5184
5185 =item warn
5186
5187 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
5188 function the same way you use the C C<printf> function.  See
5189 C<croak>.
5190
5191         void    warn(const char* pat, ...)
5192
5193 =for hackers
5194 Found in file util.c
5195
5196
5197 =back
5198
5199 =head1 AUTHORS
5200
5201 Until May 1997, this document was maintained by Jeff Okamoto
5202 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
5203
5204 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
5205 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
5206 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
5207 Stephen McCamant, and Gurusamy Sarathy.
5208
5209 API Listing originally by Dean Roehrich <roehrich@cray.com>.
5210
5211 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
5212
5213 =head1 SEE ALSO
5214
5215 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
5216