This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
464a30dbeebb8fb3018610b5a06ecae6d007b1e1
[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_vstring
2502
2503 Returns a pointer to the next character after the parsed
2504 vstring, as well as updating the passed in sv.
2505
2506 Function must be called like
2507
2508         sv = NEWSV(92,5);
2509         s = new_vstring(s,sv);
2510
2511 The sv must already be large enough to store the vstring
2512 passed in.
2513
2514         char*   new_vstring(char *vstr, SV *sv)
2515
2516 =for hackers
2517 Found in file util.c
2518
2519 =item SvCUR
2520
2521 Returns the length of the string which is in the SV.  See C<SvLEN>.
2522
2523         STRLEN  SvCUR(SV* sv)
2524
2525 =for hackers
2526 Found in file sv.h
2527
2528 =item SvCUR_set
2529
2530 Set the length of the string which is in the SV.  See C<SvCUR>.
2531
2532         void    SvCUR_set(SV* sv, STRLEN len)
2533
2534 =for hackers
2535 Found in file sv.h
2536
2537 =item SvEND
2538
2539 Returns a pointer to the last character in the string which is in the SV.
2540 See C<SvCUR>.  Access the character as *(SvEND(sv)).
2541
2542         char*   SvEND(SV* sv)
2543
2544 =for hackers
2545 Found in file sv.h
2546
2547 =item SvGROW
2548
2549 Expands the character buffer in the SV so that it has room for the
2550 indicated number of bytes (remember to reserve space for an extra trailing
2551 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
2552 Returns a pointer to the character buffer.
2553
2554         char *  SvGROW(SV* sv, STRLEN len)
2555
2556 =for hackers
2557 Found in file sv.h
2558
2559 =item SvIOK
2560
2561 Returns a boolean indicating whether the SV contains an integer.
2562
2563         bool    SvIOK(SV* sv)
2564
2565 =for hackers
2566 Found in file sv.h
2567
2568 =item SvIOKp
2569
2570 Returns a boolean indicating whether the SV contains an integer.  Checks
2571 the B<private> setting.  Use C<SvIOK>.
2572
2573         bool    SvIOKp(SV* sv)
2574
2575 =for hackers
2576 Found in file sv.h
2577
2578 =item SvIOK_notUV
2579
2580 Returns a boolean indicating whether the SV contains a signed integer.
2581
2582         void    SvIOK_notUV(SV* sv)
2583
2584 =for hackers
2585 Found in file sv.h
2586
2587 =item SvIOK_off
2588
2589 Unsets the IV status of an SV.
2590
2591         void    SvIOK_off(SV* sv)
2592
2593 =for hackers
2594 Found in file sv.h
2595
2596 =item SvIOK_on
2597
2598 Tells an SV that it is an integer.
2599
2600         void    SvIOK_on(SV* sv)
2601
2602 =for hackers
2603 Found in file sv.h
2604
2605 =item SvIOK_only
2606
2607 Tells an SV that it is an integer and disables all other OK bits.
2608
2609         void    SvIOK_only(SV* sv)
2610
2611 =for hackers
2612 Found in file sv.h
2613
2614 =item SvIOK_only_UV
2615
2616 Tells and SV that it is an unsigned integer and disables all other OK bits.
2617
2618         void    SvIOK_only_UV(SV* sv)
2619
2620 =for hackers
2621 Found in file sv.h
2622
2623 =item SvIOK_UV
2624
2625 Returns a boolean indicating whether the SV contains an unsigned integer.
2626
2627         void    SvIOK_UV(SV* sv)
2628
2629 =for hackers
2630 Found in file sv.h
2631
2632 =item SvIV
2633
2634 Coerces the given SV to an integer and returns it. See  C<SvIVx> for a
2635 version which guarantees to evaluate sv only once.
2636
2637         IV      SvIV(SV* sv)
2638
2639 =for hackers
2640 Found in file sv.h
2641
2642 =item SvIVx
2643
2644 Coerces the given SV to an integer and returns it. Guarantees to evaluate
2645 sv only once. Use the more efficient C<SvIV> otherwise.
2646
2647         IV      SvIVx(SV* sv)
2648
2649 =for hackers
2650 Found in file sv.h
2651
2652 =item SvIVX
2653
2654 Returns the raw value in the SV's IV slot, without checks or conversions.
2655 Only use when you are sure SvIOK is true. See also C<SvIV()>.
2656
2657         IV      SvIVX(SV* sv)
2658
2659 =for hackers
2660 Found in file sv.h
2661
2662 =item SvLEN
2663
2664 Returns the size of the string buffer in the SV, not including any part
2665 attributable to C<SvOOK>.  See C<SvCUR>.
2666
2667         STRLEN  SvLEN(SV* sv)
2668
2669 =for hackers
2670 Found in file sv.h
2671
2672 =item SvNIOK
2673
2674 Returns a boolean indicating whether the SV contains a number, integer or
2675 double.
2676
2677         bool    SvNIOK(SV* sv)
2678
2679 =for hackers
2680 Found in file sv.h
2681
2682 =item SvNIOKp
2683
2684 Returns a boolean indicating whether the SV contains a number, integer or
2685 double.  Checks the B<private> setting.  Use C<SvNIOK>.
2686
2687         bool    SvNIOKp(SV* sv)
2688
2689 =for hackers
2690 Found in file sv.h
2691
2692 =item SvNIOK_off
2693
2694 Unsets the NV/IV status of an SV.
2695
2696         void    SvNIOK_off(SV* sv)
2697
2698 =for hackers
2699 Found in file sv.h
2700
2701 =item SvNOK
2702
2703 Returns a boolean indicating whether the SV contains a double.
2704
2705         bool    SvNOK(SV* sv)
2706
2707 =for hackers
2708 Found in file sv.h
2709
2710 =item SvNOKp
2711
2712 Returns a boolean indicating whether the SV contains a double.  Checks the
2713 B<private> setting.  Use C<SvNOK>.
2714
2715         bool    SvNOKp(SV* sv)
2716
2717 =for hackers
2718 Found in file sv.h
2719
2720 =item SvNOK_off
2721
2722 Unsets the NV status of an SV.
2723
2724         void    SvNOK_off(SV* sv)
2725
2726 =for hackers
2727 Found in file sv.h
2728
2729 =item SvNOK_on
2730
2731 Tells an SV that it is a double.
2732
2733         void    SvNOK_on(SV* sv)
2734
2735 =for hackers
2736 Found in file sv.h
2737
2738 =item SvNOK_only
2739
2740 Tells an SV that it is a double and disables all other OK bits.
2741
2742         void    SvNOK_only(SV* sv)
2743
2744 =for hackers
2745 Found in file sv.h
2746
2747 =item SvNV
2748
2749 Coerce the given SV to a double and return it. See  C<SvNVx> for a version
2750 which guarantees to evaluate sv only once.
2751
2752         NV      SvNV(SV* sv)
2753
2754 =for hackers
2755 Found in file sv.h
2756
2757 =item SvNVX
2758
2759 Returns the raw value in the SV's NV slot, without checks or conversions.
2760 Only use when you are sure SvNOK is true. See also C<SvNV()>.
2761
2762         NV      SvNVX(SV* sv)
2763
2764 =for hackers
2765 Found in file sv.h
2766
2767 =item SvNVx
2768
2769 Coerces the given SV to a double and returns it. Guarantees to evaluate
2770 sv only once. Use the more efficient C<SvNV> otherwise.
2771
2772         NV      SvNVx(SV* sv)
2773
2774 =for hackers
2775 Found in file sv.h
2776
2777 =item SvOK
2778
2779 Returns a boolean indicating whether the value is an SV.
2780
2781         bool    SvOK(SV* sv)
2782
2783 =for hackers
2784 Found in file sv.h
2785
2786 =item SvOOK
2787
2788 Returns a boolean indicating whether the SvIVX is a valid offset value for
2789 the SvPVX.  This hack is used internally to speed up removal of characters
2790 from the beginning of a SvPV.  When SvOOK is true, then the start of the
2791 allocated string buffer is really (SvPVX - SvIVX).
2792
2793         bool    SvOOK(SV* sv)
2794
2795 =for hackers
2796 Found in file sv.h
2797
2798 =item SvPOK
2799
2800 Returns a boolean indicating whether the SV contains a character
2801 string.
2802
2803         bool    SvPOK(SV* sv)
2804
2805 =for hackers
2806 Found in file sv.h
2807
2808 =item SvPOKp
2809
2810 Returns a boolean indicating whether the SV contains a character string.
2811 Checks the B<private> setting.  Use C<SvPOK>.
2812
2813         bool    SvPOKp(SV* sv)
2814
2815 =for hackers
2816 Found in file sv.h
2817
2818 =item SvPOK_off
2819
2820 Unsets the PV status of an SV.
2821
2822         void    SvPOK_off(SV* sv)
2823
2824 =for hackers
2825 Found in file sv.h
2826
2827 =item SvPOK_on
2828
2829 Tells an SV that it is a string.
2830
2831         void    SvPOK_on(SV* sv)
2832
2833 =for hackers
2834 Found in file sv.h
2835
2836 =item SvPOK_only
2837
2838 Tells an SV that it is a string and disables all other OK bits.
2839 Will also turn off the UTF8 status.
2840
2841         void    SvPOK_only(SV* sv)
2842
2843 =for hackers
2844 Found in file sv.h
2845
2846 =item SvPOK_only_UTF8
2847
2848 Tells an SV that it is a string and disables all other OK bits,
2849 and leaves the UTF8 status as it was.
2850
2851         void    SvPOK_only_UTF8(SV* sv)
2852
2853 =for hackers
2854 Found in file sv.h
2855
2856 =item SvPV
2857
2858 Returns a pointer to the string in the SV, or a stringified form of
2859 the SV if the SV does not contain a string.  The SV may cache the
2860 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
2861 C<SvPVx> for a version which guarantees to evaluate sv only once.
2862
2863         char*   SvPV(SV* sv, STRLEN len)
2864
2865 =for hackers
2866 Found in file sv.h
2867
2868 =item SvPVbyte
2869
2870 Like C<SvPV>, but converts sv to byte representation first if necessary.
2871
2872         char*   SvPVbyte(SV* sv, STRLEN len)
2873
2874 =for hackers
2875 Found in file sv.h
2876
2877 =item SvPVbytex
2878
2879 Like C<SvPV>, but converts sv to byte representation first if necessary.
2880 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
2881 otherwise.
2882
2883
2884         char*   SvPVbytex(SV* sv, STRLEN len)
2885
2886 =for hackers
2887 Found in file sv.h
2888
2889 =item SvPVbytex_force
2890
2891 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2892 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
2893 otherwise.
2894
2895         char*   SvPVbytex_force(SV* sv, STRLEN len)
2896
2897 =for hackers
2898 Found in file sv.h
2899
2900 =item SvPVbyte_force
2901
2902 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2903
2904         char*   SvPVbyte_force(SV* sv, STRLEN len)
2905
2906 =for hackers
2907 Found in file sv.h
2908
2909 =item SvPVbyte_nolen
2910
2911 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2912
2913         char*   SvPVbyte_nolen(SV* sv)
2914
2915 =for hackers
2916 Found in file sv.h
2917
2918 =item SvPVutf8
2919
2920 Like C<SvPV>, but converts sv to utf8 first if necessary.
2921
2922         char*   SvPVutf8(SV* sv, STRLEN len)
2923
2924 =for hackers
2925 Found in file sv.h
2926
2927 =item SvPVutf8x
2928
2929 Like C<SvPV>, but converts sv to utf8 first if necessary.
2930 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
2931 otherwise.
2932
2933         char*   SvPVutf8x(SV* sv, STRLEN len)
2934
2935 =for hackers
2936 Found in file sv.h
2937
2938 =item SvPVutf8x_force
2939
2940 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2941 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
2942 otherwise.
2943
2944         char*   SvPVutf8x_force(SV* sv, STRLEN len)
2945
2946 =for hackers
2947 Found in file sv.h
2948
2949 =item SvPVutf8_force
2950
2951 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2952
2953         char*   SvPVutf8_force(SV* sv, STRLEN len)
2954
2955 =for hackers
2956 Found in file sv.h
2957
2958 =item SvPVutf8_nolen
2959
2960 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
2961
2962         char*   SvPVutf8_nolen(SV* sv)
2963
2964 =for hackers
2965 Found in file sv.h
2966
2967 =item SvPVX
2968
2969 Returns a pointer to the physical string in the SV.  The SV must contain a
2970 string.
2971
2972         char*   SvPVX(SV* sv)
2973
2974 =for hackers
2975 Found in file sv.h
2976
2977 =item SvPVx
2978
2979 A version of C<SvPV> which guarantees to evaluate sv only once.
2980
2981         char*   SvPVx(SV* sv, STRLEN len)
2982
2983 =for hackers
2984 Found in file sv.h
2985
2986 =item SvPV_force
2987
2988 Like C<SvPV> but will force the SV into containing just a string
2989 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
2990 directly.
2991
2992         char*   SvPV_force(SV* sv, STRLEN len)
2993
2994 =for hackers
2995 Found in file sv.h
2996
2997 =item SvPV_force_nomg
2998
2999 Like C<SvPV> but will force the SV into containing just a string
3000 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
3001 directly. Doesn't process magic.
3002
3003         char*   SvPV_force_nomg(SV* sv, STRLEN len)
3004
3005 =for hackers
3006 Found in file sv.h
3007
3008 =item SvPV_nolen
3009
3010 Returns a pointer to the string in the SV, or a stringified form of
3011 the SV if the SV does not contain a string.  The SV may cache the
3012 stringified form becoming C<SvPOK>.  Handles 'get' magic.
3013
3014         char*   SvPV_nolen(SV* sv)
3015
3016 =for hackers
3017 Found in file sv.h
3018
3019 =item SvREFCNT
3020
3021 Returns the value of the object's reference count.
3022
3023         U32     SvREFCNT(SV* sv)
3024
3025 =for hackers
3026 Found in file sv.h
3027
3028 =item SvREFCNT_dec
3029
3030 Decrements the reference count of the given SV.
3031
3032         void    SvREFCNT_dec(SV* sv)
3033
3034 =for hackers
3035 Found in file sv.h
3036
3037 =item SvREFCNT_inc
3038
3039 Increments the reference count of the given SV.
3040
3041         SV*     SvREFCNT_inc(SV* sv)
3042
3043 =for hackers
3044 Found in file sv.h
3045
3046 =item SvROK
3047
3048 Tests if the SV is an RV.
3049
3050         bool    SvROK(SV* sv)
3051
3052 =for hackers
3053 Found in file sv.h
3054
3055 =item SvROK_off
3056
3057 Unsets the RV status of an SV.
3058
3059         void    SvROK_off(SV* sv)
3060
3061 =for hackers
3062 Found in file sv.h
3063
3064 =item SvROK_on
3065
3066 Tells an SV that it is an RV.
3067
3068         void    SvROK_on(SV* sv)
3069
3070 =for hackers
3071 Found in file sv.h
3072
3073 =item SvRV
3074
3075 Dereferences an RV to return the SV.
3076
3077         SV*     SvRV(SV* sv)
3078
3079 =for hackers
3080 Found in file sv.h
3081
3082 =item SvSTASH
3083
3084 Returns the stash of the SV.
3085
3086         HV*     SvSTASH(SV* sv)
3087
3088 =for hackers
3089 Found in file sv.h
3090
3091 =item SvTAINT
3092
3093 Taints an SV if tainting is enabled
3094
3095         void    SvTAINT(SV* sv)
3096
3097 =for hackers
3098 Found in file sv.h
3099
3100 =item SvTAINTED
3101
3102 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3103 not.
3104
3105         bool    SvTAINTED(SV* sv)
3106
3107 =for hackers
3108 Found in file sv.h
3109
3110 =item SvTAINTED_off
3111
3112 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3113 some of Perl's fundamental security features. XS module authors should not
3114 use this function unless they fully understand all the implications of
3115 unconditionally untainting the value. Untainting should be done in the
3116 standard perl fashion, via a carefully crafted regexp, rather than directly
3117 untainting variables.
3118
3119         void    SvTAINTED_off(SV* sv)
3120
3121 =for hackers
3122 Found in file sv.h
3123
3124 =item SvTAINTED_on
3125
3126 Marks an SV as tainted.
3127
3128         void    SvTAINTED_on(SV* sv)
3129
3130 =for hackers
3131 Found in file sv.h
3132
3133 =item SvTRUE
3134
3135 Returns a boolean indicating whether Perl would evaluate the SV as true or
3136 false, defined or undefined.  Does not handle 'get' magic.
3137
3138         bool    SvTRUE(SV* sv)
3139
3140 =for hackers
3141 Found in file sv.h
3142
3143 =item SvTYPE
3144
3145 Returns the type of the SV.  See C<svtype>.
3146
3147         svtype  SvTYPE(SV* sv)
3148
3149 =for hackers
3150 Found in file sv.h
3151
3152 =item SvUNLOCK
3153
3154 Releases a mutual exclusion lock on sv if a suitable module
3155 has been loaded.
3156
3157
3158         void    SvUNLOCK(SV* sv)
3159
3160 =for hackers
3161 Found in file sv.h
3162
3163 =item SvUOK
3164
3165 Returns a boolean indicating whether the SV contains an unsigned integer.
3166
3167         void    SvUOK(SV* sv)
3168
3169 =for hackers
3170 Found in file sv.h
3171
3172 =item SvUPGRADE
3173
3174 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
3175 perform the upgrade if necessary.  See C<svtype>.
3176
3177         void    SvUPGRADE(SV* sv, svtype type)
3178
3179 =for hackers
3180 Found in file sv.h
3181
3182 =item SvUTF8
3183
3184 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3185
3186         void    SvUTF8(SV* sv)
3187
3188 =for hackers
3189 Found in file sv.h
3190
3191 =item SvUTF8_off
3192
3193 Unsets the UTF8 status of an SV.
3194
3195         void    SvUTF8_off(SV *sv)
3196
3197 =for hackers
3198 Found in file sv.h
3199
3200 =item SvUTF8_on
3201
3202 Turn on the UTF8 status of an SV (the data is not changed, just the flag).
3203 Do not use frivolously.
3204
3205         void    SvUTF8_on(SV *sv)
3206
3207 =for hackers
3208 Found in file sv.h
3209
3210 =item SvUV
3211
3212 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
3213 for a version which guarantees to evaluate sv only once.
3214
3215         UV      SvUV(SV* sv)
3216
3217 =for hackers
3218 Found in file sv.h
3219
3220 =item SvUVx
3221
3222 Coerces the given SV to an unsigned integer and returns it. Guarantees to
3223 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
3224
3225         UV      SvUVx(SV* sv)
3226
3227 =for hackers
3228 Found in file sv.h
3229
3230 =item SvUVX
3231
3232 Returns the raw value in the SV's UV slot, without checks or conversions.
3233 Only use when you are sure SvIOK is true. See also C<SvUV()>.
3234
3235         UV      SvUVX(SV* sv)
3236
3237 =for hackers
3238 Found in file sv.h
3239
3240 =item sv_2bool
3241
3242 This function is only called on magical items, and is only used by
3243 sv_true() or its macro equivalent.
3244
3245         bool    sv_2bool(SV* sv)
3246
3247 =for hackers
3248 Found in file sv.c
3249
3250 =item sv_2cv
3251
3252 Using various gambits, try to get a CV from an SV; in addition, try if
3253 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3254
3255         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3256
3257 =for hackers
3258 Found in file sv.c
3259
3260 =item sv_2io
3261
3262 Using various gambits, try to get an IO from an SV: the IO slot if its a
3263 GV; or the recursive result if we're an RV; or the IO slot of the symbol
3264 named after the PV if we're a string.
3265
3266         IO*     sv_2io(SV* sv)
3267
3268 =for hackers
3269 Found in file sv.c
3270
3271 =item sv_2iv
3272
3273 Return the integer value of an SV, doing any necessary string conversion,
3274 magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3275
3276         IV      sv_2iv(SV* sv)
3277
3278 =for hackers
3279 Found in file sv.c
3280
3281 =item sv_2mortal
3282
3283 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
3284 by an explicit call to FREETMPS, or by an implicit call at places such as
3285 statement boundaries.  See also C<sv_newmortal> and C<sv_mortalcopy>.
3286
3287         SV*     sv_2mortal(SV* sv)
3288
3289 =for hackers
3290 Found in file sv.c
3291
3292 =item sv_2nv
3293
3294 Return the num value of an SV, doing any necessary string or integer
3295 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3296 macros.
3297
3298         NV      sv_2nv(SV* sv)
3299
3300 =for hackers
3301 Found in file sv.c
3302
3303 =item sv_2pvbyte
3304
3305 Return a pointer to the byte-encoded representation of the SV, and set *lp
3306 to its length.  May cause the SV to be downgraded from UTF8 as a
3307 side-effect.
3308
3309 Usually accessed via the C<SvPVbyte> macro.
3310
3311         char*   sv_2pvbyte(SV* sv, STRLEN* lp)
3312
3313 =for hackers
3314 Found in file sv.c
3315
3316 =item sv_2pvbyte_nolen
3317
3318 Return a pointer to the byte-encoded representation of the SV.
3319 May cause the SV to be downgraded from UTF8 as a side-effect.
3320
3321 Usually accessed via the C<SvPVbyte_nolen> macro.
3322
3323         char*   sv_2pvbyte_nolen(SV* sv)
3324
3325 =for hackers
3326 Found in file sv.c
3327
3328 =item sv_2pvutf8
3329
3330 Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3331 to its length.  May cause the SV to be upgraded to UTF8 as a side-effect.
3332
3333 Usually accessed via the C<SvPVutf8> macro.
3334
3335         char*   sv_2pvutf8(SV* sv, STRLEN* lp)
3336
3337 =for hackers
3338 Found in file sv.c
3339
3340 =item sv_2pvutf8_nolen
3341
3342 Return a pointer to the UTF8-encoded representation of the SV.
3343 May cause the SV to be upgraded to UTF8 as a side-effect.
3344
3345 Usually accessed via the C<SvPVutf8_nolen> macro.
3346
3347         char*   sv_2pvutf8_nolen(SV* sv)
3348
3349 =for hackers
3350 Found in file sv.c
3351
3352 =item sv_2pv_flags
3353
3354 Returns a pointer to the string value of an SV, and sets *lp to its length.
3355 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3356 if necessary.
3357 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3358 usually end up here too.
3359
3360         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3361
3362 =for hackers
3363 Found in file sv.c
3364
3365 =item sv_2pv_nolen
3366
3367 Like C<sv_2pv()>, but doesn't return the length too. You should usually
3368 use the macro wrapper C<SvPV_nolen(sv)> instead.
3369         char*   sv_2pv_nolen(SV* sv)
3370
3371 =for hackers
3372 Found in file sv.c
3373
3374 =item sv_2uv
3375
3376 Return the unsigned integer value of an SV, doing any necessary string
3377 conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3378 macros.
3379
3380         UV      sv_2uv(SV* sv)
3381
3382 =for hackers
3383 Found in file sv.c
3384
3385 =item sv_backoff
3386
3387 Remove any string offset. You should normally use the C<SvOOK_off> macro
3388 wrapper instead.
3389
3390         int     sv_backoff(SV* sv)
3391
3392 =for hackers
3393 Found in file sv.c
3394
3395 =item sv_bless
3396
3397 Blesses an SV into a specified package.  The SV must be an RV.  The package
3398 must be designated by its stash (see C<gv_stashpv()>).  The reference count
3399 of the SV is unaffected.
3400
3401         SV*     sv_bless(SV* sv, HV* stash)
3402
3403 =for hackers
3404 Found in file sv.c
3405
3406 =item sv_catpv
3407
3408 Concatenates the string onto the end of the string which is in the SV.
3409 If the SV has the UTF8 status set, then the bytes appended should be
3410 valid UTF8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
3411
3412         void    sv_catpv(SV* sv, const char* ptr)
3413
3414 =for hackers
3415 Found in file sv.c
3416
3417 =item sv_catpvf
3418
3419 Processes its arguments like C<sprintf> and appends the formatted
3420 output to an SV.  If the appended data contains "wide" characters
3421 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3422 and characters >255 formatted with %c), the original SV might get
3423 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.
3424 C<SvSETMAGIC()> must typically be called after calling this function
3425 to handle 'set' magic.
3426
3427         void    sv_catpvf(SV* sv, const char* pat, ...)
3428
3429 =for hackers
3430 Found in file sv.c
3431
3432 =item sv_catpvf_mg
3433
3434 Like C<sv_catpvf>, but also handles 'set' magic.
3435
3436         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
3437
3438 =for hackers
3439 Found in file sv.c
3440
3441 =item sv_catpvn
3442
3443 Concatenates the string onto the end of the string which is in the SV.  The
3444 C<len> indicates number of bytes to copy.  If the SV has the UTF8
3445 status set, then the bytes appended should be valid UTF8.
3446 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
3447
3448         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3449
3450 =for hackers
3451 Found in file sv.c
3452
3453 =item sv_catpvn_flags
3454
3455 Concatenates the string onto the end of the string which is in the SV.  The
3456 C<len> indicates number of bytes to copy.  If the SV has the UTF8
3457 status set, then the bytes appended should be valid UTF8.
3458 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3459 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3460 in terms of this function.
3461
3462         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3463
3464 =for hackers
3465 Found in file sv.c
3466
3467 =item sv_catpvn_mg
3468
3469 Like C<sv_catpvn>, but also handles 'set' magic.
3470
3471         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3472
3473 =for hackers
3474 Found in file sv.c
3475
3476 =item sv_catpv_mg
3477
3478 Like C<sv_catpv>, but also handles 'set' magic.
3479
3480         void    sv_catpv_mg(SV *sv, const char *ptr)
3481
3482 =for hackers
3483 Found in file sv.c
3484
3485 =item sv_catsv
3486
3487 Concatenates the string from SV C<ssv> onto the end of the string in
3488 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
3489 not 'set' magic.  See C<sv_catsv_mg>.
3490
3491         void    sv_catsv(SV* dsv, SV* ssv)
3492
3493 =for hackers
3494 Found in file sv.c
3495
3496 =item sv_catsv_flags
3497
3498 Concatenates the string from SV C<ssv> onto the end of the string in
3499 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
3500 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3501 and C<sv_catsv_nomg> are implemented in terms of this function.
3502
3503         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3504
3505 =for hackers
3506 Found in file sv.c
3507
3508 =item sv_catsv_mg
3509
3510 Like C<sv_catsv>, but also handles 'set' magic.
3511
3512         void    sv_catsv_mg(SV *dstr, SV *sstr)
3513
3514 =for hackers
3515 Found in file sv.c
3516
3517 =item sv_chop
3518
3519 Efficient removal of characters from the beginning of the string buffer.
3520 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3521 the string buffer.  The C<ptr> becomes the first character of the adjusted
3522 string. Uses the "OOK hack".
3523
3524         void    sv_chop(SV* sv, char* ptr)
3525
3526 =for hackers
3527 Found in file sv.c
3528
3529 =item sv_clear
3530
3531 Clear an SV: call any destructors, free up any memory used by the body,
3532 and free the body itself. The SV's head is I<not> freed, although
3533 its type is set to all 1's so that it won't inadvertently be assumed
3534 to be live during global destruction etc.
3535 This function should only be called when REFCNT is zero. Most of the time
3536 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3537 instead.
3538
3539         void    sv_clear(SV* sv)
3540
3541 =for hackers
3542 Found in file sv.c
3543
3544 =item sv_cmp
3545
3546 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
3547 string in C<sv1> is less than, equal to, or greater than the string in
3548 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3549 coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
3550
3551         I32     sv_cmp(SV* sv1, SV* sv2)
3552
3553 =for hackers
3554 Found in file sv.c
3555
3556 =item sv_cmp_locale
3557
3558 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3559 'use bytes' aware, handles get magic, and will coerce its args to strings
3560 if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
3561
3562         I32     sv_cmp_locale(SV* sv1, SV* sv2)
3563
3564 =for hackers
3565 Found in file sv.c
3566
3567 =item sv_collxfrm
3568
3569 Add Collate Transform magic to an SV if it doesn't already have it.
3570
3571 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3572 scalar data of the variable, but transformed to such a format that a normal
3573 memory comparison can be used to compare the data according to the locale
3574 settings.
3575
3576         char*   sv_collxfrm(SV* sv, STRLEN* nxp)
3577
3578 =for hackers
3579 Found in file sv.c
3580
3581 =item sv_copypv
3582
3583 Copies a stringified representation of the source SV into the
3584 destination SV.  Automatically performs any necessary mg_get and
3585 coercion of numeric values into strings.  Guaranteed to preserve
3586 UTF-8 flag even from overloaded objects.  Similar in nature to
3587 sv_2pv[_flags] but operates directly on an SV instead of just the
3588 string.  Mostly uses sv_2pv_flags to do its work, except when that
3589 would lose the UTF-8'ness of the PV.
3590
3591         void    sv_copypv(SV* dsv, SV* ssv)
3592
3593 =for hackers
3594 Found in file sv.c
3595
3596 =item sv_dec
3597
3598 Auto-decrement of the value in the SV, doing string to numeric conversion
3599 if necessary. Handles 'get' magic.
3600
3601         void    sv_dec(SV* sv)
3602
3603 =for hackers
3604 Found in file sv.c
3605
3606 =item sv_derived_from
3607
3608 Returns a boolean indicating whether the SV is derived from the specified
3609 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
3610 for class names as well as for objects.
3611
3612         bool    sv_derived_from(SV* sv, const char* name)
3613
3614 =for hackers
3615 Found in file universal.c
3616
3617 =item sv_eq
3618
3619 Returns a boolean indicating whether the strings in the two SVs are
3620 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3621 coerce its args to strings if necessary.
3622
3623         I32     sv_eq(SV* sv1, SV* sv2)
3624
3625 =for hackers
3626 Found in file sv.c
3627
3628 =item sv_force_normal
3629
3630 Undo various types of fakery on an SV: if the PV is a shared string, make
3631 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3632 an xpvmg. See also C<sv_force_normal_flags>.
3633
3634         void    sv_force_normal(SV *sv)
3635
3636 =for hackers
3637 Found in file sv.c
3638
3639 =item sv_force_normal_flags
3640
3641 Undo various types of fakery on an SV: if the PV is a shared string, make
3642 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3643 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
3644 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
3645 then a copy-on-write scalar drops its PV buffer (if any) and becomes
3646 SvPOK_off rather than making a copy. (Used where this scalar is about to be
3647 set to some other value. In addtion, the C<flags> parameter gets passed to
3648 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
3649 with flags set to 0.
3650
3651         void    sv_force_normal_flags(SV *sv, U32 flags)
3652
3653 =for hackers
3654 Found in file sv.c
3655
3656 =item sv_free
3657
3658 Decrement an SV's reference count, and if it drops to zero, call
3659 C<sv_clear> to invoke destructors and free up any memory used by
3660 the body; finally, deallocate the SV's head itself.
3661 Normally called via a wrapper macro C<SvREFCNT_dec>.
3662
3663         void    sv_free(SV* sv)
3664
3665 =for hackers
3666 Found in file sv.c
3667
3668 =item sv_gets
3669
3670 Get a line from the filehandle and store it into the SV, optionally
3671 appending to the currently-stored string.
3672
3673         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
3674
3675 =for hackers
3676 Found in file sv.c
3677
3678 =item sv_grow
3679
3680 Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
3681 upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
3682 Use the C<SvGROW> wrapper instead.
3683
3684         char*   sv_grow(SV* sv, STRLEN newlen)
3685
3686 =for hackers
3687 Found in file sv.c
3688
3689 =item sv_inc
3690
3691 Auto-increment of the value in the SV, doing string to numeric conversion
3692 if necessary. Handles 'get' magic.
3693
3694         void    sv_inc(SV* sv)
3695
3696 =for hackers
3697 Found in file sv.c
3698
3699 =item sv_insert
3700
3701 Inserts a string at the specified offset/length within the SV. Similar to
3702 the Perl substr() function.
3703
3704         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3705
3706 =for hackers
3707 Found in file sv.c
3708
3709 =item sv_isa
3710
3711 Returns a boolean indicating whether the SV is blessed into the specified
3712 class.  This does not check for subtypes; use C<sv_derived_from> to verify
3713 an inheritance relationship.
3714
3715         int     sv_isa(SV* sv, const char* name)
3716
3717 =for hackers
3718 Found in file sv.c
3719
3720 =item sv_isobject
3721
3722 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3723 object.  If the SV is not an RV, or if the object is not blessed, then this
3724 will return false.
3725
3726         int     sv_isobject(SV* sv)
3727
3728 =for hackers
3729 Found in file sv.c
3730
3731 =item sv_iv
3732
3733 A private implementation of the C<SvIVx> macro for compilers which can't
3734 cope with complex macro expressions. Always use the macro instead.
3735
3736         IV      sv_iv(SV* sv)
3737
3738 =for hackers
3739 Found in file sv.c
3740
3741 =item sv_len
3742
3743 Returns the length of the string in the SV. Handles magic and type
3744 coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
3745
3746         STRLEN  sv_len(SV* sv)
3747
3748 =for hackers
3749 Found in file sv.c
3750
3751 =item sv_len_utf8
3752
3753 Returns the number of characters in the string in an SV, counting wide
3754 UTF8 bytes as a single character. Handles magic and type coercion.
3755
3756         STRLEN  sv_len_utf8(SV* sv)
3757
3758 =for hackers
3759 Found in file sv.c
3760
3761 =item sv_magic
3762
3763 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3764 then adds a new magic item of type C<how> to the head of the magic list.
3765
3766         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3767
3768 =for hackers
3769 Found in file sv.c
3770
3771 =item sv_magicext
3772
3773 Adds magic to an SV, upgrading it if necessary. Applies the
3774 supplied vtable and returns pointer to the magic added.
3775
3776 Note that sv_magicext will allow things that sv_magic will not.
3777 In particular you can add magic to SvREADONLY SVs and and more than
3778 one instance of the same 'how'
3779
3780 I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
3781 if C<namelen> is zero then C<name> is stored as-is and - as another special
3782 case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
3783 an C<SV*> and has its REFCNT incremented
3784
3785 (This is now used as a subroutine by sv_magic.)
3786
3787         MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen        )
3788
3789 =for hackers
3790 Found in file sv.c
3791
3792 =item sv_mortalcopy
3793
3794 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
3795 The new SV is marked as mortal. It will be destroyed "soon", either by an
3796 explicit call to FREETMPS, or by an implicit call at places such as
3797 statement boundaries.  See also C<sv_newmortal> and C<sv_2mortal>.
3798
3799         SV*     sv_mortalcopy(SV* oldsv)
3800
3801 =for hackers
3802 Found in file sv.c
3803
3804 =item sv_newmortal
3805
3806 Creates a new null SV which is mortal.  The reference count of the SV is
3807 set to 1. It will be destroyed "soon", either by an explicit call to
3808 FREETMPS, or by an implicit call at places such as statement boundaries.
3809 See also C<sv_mortalcopy> and C<sv_2mortal>.
3810
3811         SV*     sv_newmortal()
3812
3813 =for hackers
3814 Found in file sv.c
3815
3816 =item sv_newref
3817
3818 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3819 instead.
3820
3821         SV*     sv_newref(SV* sv)
3822
3823 =for hackers
3824 Found in file sv.c
3825
3826 =item sv_nolocking
3827
3828 Dummy routine which "locks" an SV when there is no locking module present.
3829 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3830 some level of strict-ness.
3831
3832         void    sv_nolocking(SV *)
3833
3834 =for hackers
3835 Found in file util.c
3836
3837 =item sv_nosharing
3838
3839 Dummy routine which "shares" an SV when there is no sharing module present.
3840 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3841 some level of strict-ness.
3842
3843         void    sv_nosharing(SV *)
3844
3845 =for hackers
3846 Found in file util.c
3847
3848 =item sv_nounlocking
3849
3850 Dummy routine which "unlocks" an SV when there is no locking module present.
3851 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3852 some level of strict-ness.
3853
3854         void    sv_nounlocking(SV *)
3855
3856 =for hackers
3857 Found in file util.c
3858
3859 =item sv_nv
3860
3861 A private implementation of the C<SvNVx> macro for compilers which can't
3862 cope with complex macro expressions. Always use the macro instead.
3863
3864         NV      sv_nv(SV* sv)
3865
3866 =for hackers
3867 Found in file sv.c
3868
3869 =item sv_pos_b2u
3870
3871 Converts the value pointed to by offsetp from a count of bytes from the
3872 start of the string, to a count of the equivalent number of UTF8 chars.
3873 Handles magic and type coercion.
3874
3875         void    sv_pos_b2u(SV* sv, I32* offsetp)
3876
3877 =for hackers
3878 Found in file sv.c
3879
3880 =item sv_pos_u2b
3881
3882 Converts the value pointed to by offsetp from a count of UTF8 chars from
3883 the start of the string, to a count of the equivalent number of bytes; if
3884 lenp is non-zero, it does the same to lenp, but this time starting from
3885 the offset, rather than from the start of the string. Handles magic and
3886 type coercion.
3887
3888         void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3889
3890 =for hackers
3891 Found in file sv.c
3892
3893 =item sv_pv
3894
3895 Use the C<SvPV_nolen> macro instead
3896
3897         char*   sv_pv(SV *sv)
3898
3899 =for hackers
3900 Found in file sv.c
3901
3902 =item sv_pvbyte
3903
3904 Use C<SvPVbyte_nolen> instead.
3905
3906         char*   sv_pvbyte(SV *sv)
3907
3908 =for hackers
3909 Found in file sv.c
3910
3911 =item sv_pvbyten
3912
3913 A private implementation of the C<SvPVbyte> macro for compilers
3914 which can't cope with complex macro expressions. Always use the macro
3915 instead.
3916
3917         char*   sv_pvbyten(SV *sv, STRLEN *len)
3918
3919 =for hackers
3920 Found in file sv.c
3921
3922 =item sv_pvbyten_force
3923
3924 A private implementation of the C<SvPVbytex_force> macro for compilers
3925 which can't cope with complex macro expressions. Always use the macro
3926 instead.
3927
3928         char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
3929
3930 =for hackers
3931 Found in file sv.c
3932
3933 =item sv_pvn
3934
3935 A private implementation of the C<SvPV> macro for compilers which can't
3936 cope with complex macro expressions. Always use the macro instead.
3937
3938         char*   sv_pvn(SV *sv, STRLEN *len)
3939
3940 =for hackers
3941 Found in file sv.c
3942
3943 =item sv_pvn_force
3944
3945 Get a sensible string out of the SV somehow.
3946 A private implementation of the C<SvPV_force> macro for compilers which
3947 can't cope with complex macro expressions. Always use the macro instead.
3948
3949         char*   sv_pvn_force(SV* sv, STRLEN* lp)
3950
3951 =for hackers
3952 Found in file sv.c
3953
3954 =item sv_pvn_force_flags
3955
3956 Get a sensible string out of the SV somehow.
3957 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
3958 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
3959 implemented in terms of this function.
3960 You normally want to use the various wrapper macros instead: see
3961 C<SvPV_force> and C<SvPV_force_nomg>
3962
3963         char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3964
3965 =for hackers
3966 Found in file sv.c
3967
3968 =item sv_pvutf8
3969
3970 Use the C<SvPVutf8_nolen> macro instead
3971
3972         char*   sv_pvutf8(SV *sv)
3973
3974 =for hackers
3975 Found in file sv.c
3976
3977 =item sv_pvutf8n
3978
3979 A private implementation of the C<SvPVutf8> macro for compilers
3980 which can't cope with complex macro expressions. Always use the macro
3981 instead.
3982
3983         char*   sv_pvutf8n(SV *sv, STRLEN *len)
3984
3985 =for hackers
3986 Found in file sv.c
3987
3988 =item sv_pvutf8n_force
3989
3990 A private implementation of the C<SvPVutf8_force> macro for compilers
3991 which can't cope with complex macro expressions. Always use the macro
3992 instead.
3993
3994         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
3995
3996 =for hackers
3997 Found in file sv.c
3998
3999 =item sv_reftype
4000
4001 Returns a string describing what the SV is a reference to.
4002
4003         char*   sv_reftype(SV* sv, int ob)
4004
4005 =for hackers
4006 Found in file sv.c
4007
4008 =item sv_replace
4009
4010 Make the first argument a copy of the second, then delete the original.
4011 The target SV physically takes over ownership of the body of the source SV
4012 and inherits its flags; however, the target keeps any magic it owns,
4013 and any magic in the source is discarded.
4014 Note that this is a rather specialist SV copying operation; most of the
4015 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
4016
4017         void    sv_replace(SV* sv, SV* nsv)
4018
4019 =for hackers
4020 Found in file sv.c
4021
4022 =item sv_report_used
4023
4024 Dump the contents of all SVs not yet freed. (Debugging aid).
4025
4026         void    sv_report_used()
4027
4028 =for hackers
4029 Found in file sv.c
4030
4031 =item sv_reset
4032
4033 Underlying implementation for the C<reset> Perl function.
4034 Note that the perl-level function is vaguely deprecated.
4035
4036         void    sv_reset(char* s, HV* stash)
4037
4038 =for hackers
4039 Found in file sv.c
4040
4041 =item sv_rvweaken
4042
4043 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
4044 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
4045 push a back-reference to this RV onto the array of backreferences
4046 associated with that magic.
4047
4048         SV*     sv_rvweaken(SV *sv)
4049
4050 =for hackers
4051 Found in file sv.c
4052
4053 =item sv_setiv
4054
4055 Copies an integer into the given SV, upgrading first if necessary.
4056 Does not handle 'set' magic.  See also C<sv_setiv_mg>.
4057
4058         void    sv_setiv(SV* sv, IV num)
4059
4060 =for hackers
4061 Found in file sv.c
4062
4063 =item sv_setiv_mg
4064
4065 Like C<sv_setiv>, but also handles 'set' magic.
4066
4067         void    sv_setiv_mg(SV *sv, IV i)
4068
4069 =for hackers
4070 Found in file sv.c
4071
4072 =item sv_setnv
4073
4074 Copies a double into the given SV, upgrading first if necessary.
4075 Does not handle 'set' magic.  See also C<sv_setnv_mg>.
4076
4077         void    sv_setnv(SV* sv, NV num)
4078
4079 =for hackers
4080 Found in file sv.c
4081
4082 =item sv_setnv_mg
4083
4084 Like C<sv_setnv>, but also handles 'set' magic.
4085
4086         void    sv_setnv_mg(SV *sv, NV num)
4087
4088 =for hackers
4089 Found in file sv.c
4090
4091 =item sv_setpv
4092
4093 Copies a string into an SV.  The string must be null-terminated.  Does not
4094 handle 'set' magic.  See C<sv_setpv_mg>.
4095
4096         void    sv_setpv(SV* sv, const char* ptr)
4097
4098 =for hackers
4099 Found in file sv.c
4100
4101 =item sv_setpvf
4102
4103 Processes its arguments like C<sprintf> and sets an SV to the formatted
4104 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
4105
4106         void    sv_setpvf(SV* sv, const char* pat, ...)
4107
4108 =for hackers
4109 Found in file sv.c
4110
4111 =item sv_setpvf_mg
4112
4113 Like C<sv_setpvf>, but also handles 'set' magic.
4114
4115         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
4116
4117 =for hackers
4118 Found in file sv.c
4119
4120 =item sv_setpvn
4121
4122 Copies a string into an SV.  The C<len> parameter indicates the number of
4123 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
4124
4125         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
4126
4127 =for hackers
4128 Found in file sv.c
4129
4130 =item sv_setpvn_mg
4131
4132 Like C<sv_setpvn>, but also handles 'set' magic.
4133
4134         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
4135
4136 =for hackers
4137 Found in file sv.c
4138
4139 =item sv_setpv_mg
4140
4141 Like C<sv_setpv>, but also handles 'set' magic.
4142
4143         void    sv_setpv_mg(SV *sv, const char *ptr)
4144
4145 =for hackers
4146 Found in file sv.c
4147
4148 =item sv_setref_iv
4149
4150 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
4151 argument will be upgraded to an RV.  That RV will be modified to point to
4152 the new SV.  The C<classname> argument indicates the package for the
4153 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4154 will be returned and will have a reference count of 1.
4155
4156         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
4157
4158 =for hackers
4159 Found in file sv.c
4160
4161 =item sv_setref_nv
4162
4163 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
4164 argument will be upgraded to an RV.  That RV will be modified to point to
4165 the new SV.  The C<classname> argument indicates the package for the
4166 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4167 will be returned and will have a reference count of 1.
4168
4169         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
4170
4171 =for hackers
4172 Found in file sv.c
4173
4174 =item sv_setref_pv
4175
4176 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
4177 argument will be upgraded to an RV.  That RV will be modified to point to
4178 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
4179 into the SV.  The C<classname> argument indicates the package for the
4180 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4181 will be returned and will have a reference count of 1.
4182
4183 Do not use with other Perl types such as HV, AV, SV, CV, because those
4184 objects will become corrupted by the pointer copy process.
4185
4186 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
4187
4188         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
4189
4190 =for hackers
4191 Found in file sv.c
4192
4193 =item sv_setref_pvn
4194
4195 Copies a string into a new SV, optionally blessing the SV.  The length of the
4196 string must be specified with C<n>.  The C<rv> argument will be upgraded to
4197 an RV.  That RV will be modified to point to the new SV.  The C<classname>
4198 argument indicates the package for the blessing.  Set C<classname> to
4199 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
4200 a reference count of 1.
4201
4202 Note that C<sv_setref_pv> copies the pointer while this copies the string.
4203
4204         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
4205
4206 =for hackers
4207 Found in file sv.c
4208
4209 =item sv_setref_uv
4210
4211 Copies an unsigned integer into a new SV, optionally blessing the SV.  The C<rv>
4212 argument will be upgraded to an RV.  That RV will be modified to point to
4213 the new SV.  The C<classname> argument indicates the package for the
4214 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
4215 will be returned and will have a reference count of 1.
4216
4217         SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)
4218
4219 =for hackers
4220 Found in file sv.c
4221
4222 =item sv_setsv
4223
4224 Copies the contents of the source SV C<ssv> into the destination SV
4225 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
4226 function if the source SV needs to be reused. Does not handle 'set' magic.
4227 Loosely speaking, it performs a copy-by-value, obliterating any previous
4228 content of the destination.
4229
4230 You probably want to use one of the assortment of wrappers, such as
4231 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4232 C<SvSetMagicSV_nosteal>.
4233
4234         void    sv_setsv(SV* dsv, SV* ssv)
4235
4236 =for hackers
4237 Found in file sv.c
4238
4239 =item sv_setsv_flags
4240
4241 Copies the contents of the source SV C<ssv> into the destination SV
4242 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
4243 function if the source SV needs to be reused. Does not handle 'set' magic.
4244 Loosely speaking, it performs a copy-by-value, obliterating any previous
4245 content of the destination.
4246 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
4247 C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
4248 implemented in terms of this function.
4249
4250 You probably want to use one of the assortment of wrappers, such as
4251 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4252 C<SvSetMagicSV_nosteal>.
4253
4254 This is the primary function for copying scalars, and most other
4255 copy-ish functions and macros use this underneath.
4256
4257         void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
4258
4259 =for hackers
4260 Found in file sv.c
4261
4262 =item sv_setsv_mg
4263
4264 Like C<sv_setsv>, but also handles 'set' magic.
4265
4266         void    sv_setsv_mg(SV *dstr, SV *sstr)
4267
4268 =for hackers
4269 Found in file sv.c
4270
4271 =item sv_setuv
4272
4273 Copies an unsigned integer into the given SV, upgrading first if necessary.
4274 Does not handle 'set' magic.  See also C<sv_setuv_mg>.
4275
4276         void    sv_setuv(SV* sv, UV num)
4277
4278 =for hackers
4279 Found in file sv.c
4280
4281 =item sv_setuv_mg
4282
4283 Like C<sv_setuv>, but also handles 'set' magic.
4284
4285         void    sv_setuv_mg(SV *sv, UV u)
4286
4287 =for hackers
4288 Found in file sv.c
4289
4290 =item sv_taint
4291
4292 Taint an SV. Use C<SvTAINTED_on> instead.
4293         void    sv_taint(SV* sv)
4294
4295 =for hackers
4296 Found in file sv.c
4297
4298 =item sv_tainted
4299
4300 Test an SV for taintedness. Use C<SvTAINTED> instead.
4301         bool    sv_tainted(SV* sv)
4302
4303 =for hackers
4304 Found in file sv.c
4305
4306 =item sv_true
4307
4308 Returns true if the SV has a true value by Perl's rules.
4309 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
4310 instead use an in-line version.
4311
4312         I32     sv_true(SV *sv)
4313
4314 =for hackers
4315 Found in file sv.c
4316
4317 =item sv_unmagic
4318
4319 Removes all magic of type C<type> from an SV.
4320
4321         int     sv_unmagic(SV* sv, int type)
4322
4323 =for hackers
4324 Found in file sv.c
4325
4326 =item sv_unref
4327
4328 Unsets the RV status of the SV, and decrements the reference count of
4329 whatever was being referenced by the RV.  This can almost be thought of
4330 as a reversal of C<newSVrv>.  This is C<sv_unref_flags> with the C<flag>
4331 being zero.  See C<SvROK_off>.
4332
4333         void    sv_unref(SV* sv)
4334
4335 =for hackers
4336 Found in file sv.c
4337
4338 =item sv_unref_flags
4339
4340 Unsets the RV status of the SV, and decrements the reference count of
4341 whatever was being referenced by the RV.  This can almost be thought of
4342 as a reversal of C<newSVrv>.  The C<cflags> argument can contain
4343 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
4344 (otherwise the decrementing is conditional on the reference count being
4345 different from one or the reference being a readonly SV).
4346 See C<SvROK_off>.
4347
4348         void    sv_unref_flags(SV* sv, U32 flags)
4349
4350 =for hackers
4351 Found in file sv.c
4352
4353 =item sv_untaint
4354
4355 Untaint an SV. Use C<SvTAINTED_off> instead.
4356         void    sv_untaint(SV* sv)
4357
4358 =for hackers
4359 Found in file sv.c
4360
4361 =item sv_upgrade
4362
4363 Upgrade an SV to a more complex form.  Generally adds a new body type to the
4364 SV, then copies across as much information as possible from the old body.
4365 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
4366
4367         bool    sv_upgrade(SV* sv, U32 mt)
4368
4369 =for hackers
4370 Found in file sv.c
4371
4372 =item sv_usepvn
4373
4374 Tells an SV to use C<ptr> to find its string value.  Normally the string is
4375 stored inside the SV but sv_usepvn allows the SV to use an outside string.
4376 The C<ptr> should point to memory that was allocated by C<malloc>.  The
4377 string length, C<len>, must be supplied.  This function will realloc the
4378 memory pointed to by C<ptr>, so that pointer should not be freed or used by
4379 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
4380 See C<sv_usepvn_mg>.
4381
4382         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
4383
4384 =for hackers
4385 Found in file sv.c
4386
4387 =item sv_usepvn_mg
4388
4389 Like C<sv_usepvn>, but also handles 'set' magic.
4390
4391         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
4392
4393 =for hackers
4394 Found in file sv.c
4395
4396 =item sv_utf8_decode
4397
4398 Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
4399 turn off SvUTF8 if needed so that we see characters. Used as a building block
4400 for decode_utf8 in Encode.xs
4401
4402 NOTE: this function is experimental and may change or be
4403 removed without notice.
4404
4405         bool    sv_utf8_decode(SV *sv)
4406
4407 =for hackers
4408 Found in file sv.c
4409
4410 =item sv_utf8_downgrade
4411
4412 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
4413 This may not be possible if the PV contains non-byte encoding characters;
4414 if this is the case, either returns false or, if C<fail_ok> is not
4415 true, croaks.
4416
4417 This is not as a general purpose Unicode to byte encoding interface:
4418 use the Encode extension for that.
4419
4420 NOTE: this function is experimental and may change or be
4421 removed without notice.
4422
4423         bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
4424
4425 =for hackers
4426 Found in file sv.c
4427
4428 =item sv_utf8_encode
4429
4430 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
4431 flag so that it looks like octets again. Used as a building block
4432 for encode_utf8 in Encode.xs
4433
4434         void    sv_utf8_encode(SV *sv)
4435
4436 =for hackers
4437 Found in file sv.c
4438
4439 =item sv_utf8_upgrade
4440
4441 Convert the PV of an SV to its UTF8-encoded form.
4442 Forces the SV to string form if it is not already.
4443 Always sets the SvUTF8 flag to avoid future validity checks even
4444 if all the bytes have hibit clear.
4445
4446 This is not as a general purpose byte encoding to Unicode interface:
4447 use the Encode extension for that.
4448
4449         STRLEN  sv_utf8_upgrade(SV *sv)
4450
4451 =for hackers
4452 Found in file sv.c
4453
4454 =item sv_utf8_upgrade_flags
4455
4456 Convert the PV of an SV to its UTF8-encoded form.
4457 Forces the SV to string form if it is not already.
4458 Always sets the SvUTF8 flag to avoid future validity checks even
4459 if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
4460 will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
4461 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
4462
4463 This is not as a general purpose byte encoding to Unicode interface:
4464 use the Encode extension for that.
4465
4466         STRLEN  sv_utf8_upgrade_flags(SV *sv, I32 flags)
4467
4468 =for hackers
4469 Found in file sv.c
4470
4471 =item sv_uv
4472
4473 A private implementation of the C<SvUVx> macro for compilers which can't
4474 cope with complex macro expressions. Always use the macro instead.
4475
4476         UV      sv_uv(SV* sv)
4477
4478 =for hackers
4479 Found in file sv.c
4480
4481 =item sv_vcatpvfn
4482
4483 Processes its arguments like C<vsprintf> and appends the formatted output
4484 to an SV.  Uses an array of SVs if the C style variable argument list is
4485 missing (NULL).  When running with taint checks enabled, indicates via
4486 C<maybe_tainted> if results are untrustworthy (often due to the use of
4487 locales).
4488
4489 Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
4490
4491         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4492
4493 =for hackers
4494 Found in file sv.c
4495
4496 =item sv_vsetpvfn
4497
4498 Works like C<vcatpvfn> but copies the text into the SV instead of
4499 appending it.
4500
4501 Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
4502
4503         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4504
4505 =for hackers
4506 Found in file sv.c
4507
4508
4509 =back
4510
4511 =head1 Unicode Support
4512
4513 =over 8
4514
4515 =item bytes_from_utf8
4516
4517 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4518 Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
4519 the newly-created string, and updates C<len> to contain the new
4520 length.  Returns the original string if no conversion occurs, C<len>
4521 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
4522 0 if C<s> is converted or contains all 7bit characters.
4523
4524 NOTE: this function is experimental and may change or be
4525 removed without notice.
4526
4527         U8*     bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
4528
4529 =for hackers
4530 Found in file utf8.c
4531
4532 =item bytes_to_utf8
4533
4534 Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
4535 Returns a pointer to the newly-created string, and sets C<len> to
4536 reflect the new length.
4537
4538 NOTE: this function is experimental and may change or be
4539 removed without notice.
4540
4541         U8*     bytes_to_utf8(U8 *s, STRLEN *len)
4542
4543 =for hackers
4544 Found in file utf8.c
4545
4546 =item ibcmp_utf8
4547
4548 Return true if the strings s1 and s2 differ case-insensitively, false
4549 if not (if they are equal case-insensitively).  If u1 is true, the
4550 string s1 is assumed to be in UTF-8-encoded Unicode.  If u2 is true,
4551 the string s2 is assumed to be in UTF-8-encoded Unicode.  If u1 or u2
4552 are false, the respective string is assumed to be in native 8-bit
4553 encoding.
4554
4555 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
4556 in there (they will point at the beginning of the I<next> character).
4557 If the pointers behind pe1 or pe2 are non-NULL, they are the end
4558 pointers beyond which scanning will not continue under any
4559 circustances.  If the byte lengths l1 and l2 are non-zero, s1+l1 and
4560 s2+l2 will be used as goal end pointers that will also stop the scan,
4561 and which qualify towards defining a successful match: all the scans
4562 that define an explicit length must reach their goal pointers for
4563 a match to succeed).
4564
4565 For case-insensitiveness, the "casefolding" of Unicode is used
4566 instead of upper/lowercasing both the characters, see
4567 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
4568
4569         I32     ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
4570
4571 =for hackers
4572 Found in file utf8.c
4573
4574 =item is_utf8_char
4575
4576 Tests if some arbitrary number of bytes begins in a valid UTF-8
4577 character.  Note that an INVARIANT (i.e. ASCII) character is a valid
4578 UTF-8 character.  The actual number of bytes in the UTF-8 character
4579 will be returned if it is valid, otherwise 0.
4580
4581         STRLEN  is_utf8_char(U8 *p)
4582
4583 =for hackers
4584 Found in file utf8.c
4585
4586 =item is_utf8_string
4587
4588 Returns true if first C<len> bytes of the given string form a valid UTF8
4589 string, false otherwise.  Note that 'a valid UTF8 string' does not mean
4590 'a string that contains UTF8' because a valid ASCII string is a valid
4591 UTF8 string.
4592
4593         bool    is_utf8_string(U8 *s, STRLEN len)
4594
4595 =for hackers
4596 Found in file utf8.c
4597
4598 =item pv_uni_display
4599
4600 Build to the scalar dsv a displayable version of the string spv,
4601 length len, the displayable version being at most pvlim bytes long
4602 (if longer, the rest is truncated and "..." will be appended).
4603
4604 The flags argument can have UNI_DISPLAY_ISPRINT set to display
4605 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
4606 to display the \\[nrfta\\] as the backslashed versions (like '\n')
4607 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
4608 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
4609 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
4610
4611 The pointer to the PV of the dsv is returned.
4612
4613         char*   pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
4614
4615 =for hackers
4616 Found in file utf8.c
4617
4618 =item sv_recode_to_utf8
4619
4620 The encoding is assumed to be an Encode object, on entry the PV
4621 of the sv is assumed to be octets in that encoding, and the sv
4622 will be converted into Unicode (and UTF-8).
4623
4624 If the sv already is UTF-8 (or if it is not POK), or if the encoding
4625 is not a reference, nothing is done to the sv.  If the encoding is not
4626 an C<Encode::XS> Encoding object, bad things will happen.
4627 (See F<lib/encoding.pm> and L<Encode>).
4628
4629 The PV of the sv is returned.
4630
4631         char*   sv_recode_to_utf8(SV* sv, SV *encoding)
4632
4633 =for hackers
4634 Found in file sv.c
4635
4636 =item sv_uni_display
4637
4638 Build to the scalar dsv a displayable version of the scalar sv,
4639 the displayable version being at most pvlim bytes long
4640 (if longer, the rest is truncated and "..." will be appended).
4641
4642 The flags argument is as in pv_uni_display().
4643
4644 The pointer to the PV of the dsv is returned.
4645
4646         char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4647
4648 =for hackers
4649 Found in file utf8.c
4650
4651 =item to_utf8_case
4652
4653 The "p" contains the pointer to the UTF-8 string encoding
4654 the character that is being converted.
4655
4656 The "ustrp" is a pointer to the character buffer to put the
4657 conversion result to.  The "lenp" is a pointer to the length
4658 of the result.
4659
4660 The "swashp" is a pointer to the swash to use.
4661
4662 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
4663 and loaded by SWASHGET, using lib/utf8_heavy.pl.  The special (usually,
4664 but not always, a multicharacter mapping), is tried first.
4665
4666 The "special" is a string like "utf8::ToSpecLower", which means the
4667 hash %utf8::ToSpecLower.  The access to the hash is through
4668 Perl_to_utf8_case().
4669
4670 The "normal" is a string like "ToLower" which means the swash
4671 %utf8::ToLower.
4672
4673         UV      to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
4674
4675 =for hackers
4676 Found in file utf8.c
4677
4678 =item to_utf8_fold
4679
4680 Convert the UTF-8 encoded character at p to its foldcase version and
4681 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4682 that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
4683 foldcase version may be longer than the original character (up to
4684 three characters).
4685
4686 The first character of the foldcased version is returned
4687 (but note, as explained above, that there may be more.)
4688
4689         UV      to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
4690
4691 =for hackers
4692 Found in file utf8.c
4693
4694 =item to_utf8_lower
4695
4696 Convert the UTF-8 encoded character at p to its lowercase version and
4697 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4698 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4699 lowercase version may be longer than the original character (up to two
4700 characters).
4701
4702 The first character of the lowercased version is returned
4703 (but note, as explained above, that there may be more.)
4704
4705         UV      to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
4706
4707 =for hackers
4708 Found in file utf8.c
4709
4710 =item to_utf8_title
4711
4712 Convert the UTF-8 encoded character at p to its titlecase version and
4713 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4714 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4715 titlecase version may be longer than the original character (up to two
4716 characters).
4717
4718 The first character of the titlecased version is returned
4719 (but note, as explained above, that there may be more.)
4720
4721         UV      to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
4722
4723 =for hackers
4724 Found in file utf8.c
4725
4726 =item to_utf8_upper
4727
4728 Convert the UTF-8 encoded character at p to its uppercase version and
4729 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
4730 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4731 uppercase version may be longer than the original character (up to two
4732 characters).
4733
4734 The first character of the uppercased version is returned
4735 (but note, as explained above, that there may be more.)
4736
4737         UV      to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
4738
4739 =for hackers
4740 Found in file utf8.c
4741
4742 =item utf8n_to_uvchr
4743
4744 Returns the native character value of the first character in the string C<s>
4745 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4746 length, in bytes, of that character.
4747
4748 Allows length and flags to be passed to low level routine.
4749
4750         UV      utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4751
4752 =for hackers
4753 Found in file utf8.c
4754
4755 =item utf8n_to_uvuni
4756
4757 Bottom level UTF-8 decode routine.
4758 Returns the unicode code point value of the first character in the string C<s>
4759 which is assumed to be in UTF8 encoding and no longer than C<curlen>;
4760 C<retlen> will be set to the length, in bytes, of that character.
4761
4762 If C<s> does not point to a well-formed UTF8 character, the behaviour
4763 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
4764 it is assumed that the caller will raise a warning, and this function
4765 will silently just set C<retlen> to C<-1> and return zero.  If the
4766 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
4767 malformations will be given, C<retlen> will be set to the expected
4768 length of the UTF-8 character in bytes, and zero will be returned.
4769
4770 The C<flags> can also contain various flags to allow deviations from
4771 the strict UTF-8 encoding (see F<utf8.h>).
4772
4773 Most code should use utf8_to_uvchr() rather than call this directly.
4774
4775         UV      utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4776
4777 =for hackers
4778 Found in file utf8.c
4779
4780 =item utf8_distance
4781
4782 Returns the number of UTF8 characters between the UTF-8 pointers C<a>
4783 and C<b>.
4784
4785 WARNING: use only if you *know* that the pointers point inside the
4786 same UTF-8 buffer.
4787
4788         IV      utf8_distance(U8 *a, U8 *b)
4789
4790 =for hackers
4791 Found in file utf8.c
4792
4793 =item utf8_hop
4794
4795 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
4796 forward or backward.
4797
4798 WARNING: do not use the following unless you *know* C<off> is within
4799 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
4800 on the first byte of character or just after the last byte of a character.
4801
4802         U8*     utf8_hop(U8 *s, I32 off)
4803
4804 =for hackers
4805 Found in file utf8.c
4806
4807 =item utf8_length
4808
4809 Return the length of the UTF-8 char encoded string C<s> in characters.
4810 Stops at C<e> (inclusive).  If C<e E<lt> s> or if the scan would end
4811 up past C<e>, croaks.
4812
4813         STRLEN  utf8_length(U8* s, U8 *e)
4814
4815 =for hackers
4816 Found in file utf8.c
4817
4818 =item utf8_to_bytes
4819
4820 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4821 Unlike C<bytes_to_utf8>, this over-writes the original string, and
4822 updates len to contain the new length.
4823 Returns zero on failure, setting C<len> to -1.
4824
4825 NOTE: this function is experimental and may change or be
4826 removed without notice.
4827
4828         U8*     utf8_to_bytes(U8 *s, STRLEN *len)
4829
4830 =for hackers
4831 Found in file utf8.c
4832
4833 =item utf8_to_uvchr
4834
4835 Returns the native character value of the first character in the string C<s>
4836 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4837 length, in bytes, of that character.
4838
4839 If C<s> does not point to a well-formed UTF8 character, zero is
4840 returned and retlen is set, if possible, to -1.
4841
4842         UV      utf8_to_uvchr(U8 *s, STRLEN* retlen)
4843
4844 =for hackers
4845 Found in file utf8.c
4846
4847 =item utf8_to_uvuni
4848
4849 Returns the Unicode code point of the first character in the string C<s>
4850 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4851 length, in bytes, of that character.
4852
4853 This function should only be used when returned UV is considered
4854 an index into the Unicode semantic tables (e.g. swashes).
4855
4856 If C<s> does not point to a well-formed UTF8 character, zero is
4857 returned and retlen is set, if possible, to -1.
4858
4859         UV      utf8_to_uvuni(U8 *s, STRLEN* retlen)
4860
4861 =for hackers
4862 Found in file utf8.c
4863
4864 =item uvchr_to_utf8
4865
4866 Adds the UTF8 representation of the Native codepoint C<uv> to the end
4867 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4868 bytes available. The return value is the pointer to the byte after the
4869 end of the new character. In other words,
4870
4871     d = uvchr_to_utf8(d, uv);
4872
4873 is the recommended wide native character-aware way of saying
4874
4875     *(d++) = uv;
4876
4877         U8*     uvchr_to_utf8(U8 *d, UV uv)
4878
4879 =for hackers
4880 Found in file utf8.c
4881
4882 =item uvuni_to_utf8_flags
4883
4884 Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
4885 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4886 bytes available. The return value is the pointer to the byte after the
4887 end of the new character. In other words,
4888
4889     d = uvuni_to_utf8_flags(d, uv, flags);
4890
4891 or, in most cases,
4892
4893     d = uvuni_to_utf8(d, uv);
4894
4895 (which is equivalent to)
4896
4897     d = uvuni_to_utf8_flags(d, uv, 0);
4898
4899 is the recommended Unicode-aware way of saying
4900
4901     *(d++) = uv;
4902
4903         U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4904
4905 =for hackers
4906 Found in file utf8.c
4907
4908
4909 =back
4910
4911 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
4912
4913 =over 8
4914
4915 =item ax
4916
4917 Variable which is setup by C<xsubpp> to indicate the stack base offset,
4918 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
4919 must be called prior to setup the C<MARK> variable.
4920
4921         I32     ax
4922
4923 =for hackers
4924 Found in file XSUB.h
4925
4926 =item CLASS
4927
4928 Variable which is setup by C<xsubpp> to indicate the 
4929 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
4930
4931         char*   CLASS
4932
4933 =for hackers
4934 Found in file XSUB.h
4935
4936 =item dAX
4937
4938 Sets up the C<ax> variable.
4939 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
4940
4941                 dAX;
4942
4943 =for hackers
4944 Found in file XSUB.h
4945
4946 =item dITEMS
4947
4948 Sets up the C<items> variable.
4949 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
4950
4951                 dITEMS;
4952
4953 =for hackers
4954 Found in file XSUB.h
4955
4956 =item dXSARGS
4957
4958 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
4959 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
4960 This is usually handled automatically by C<xsubpp>.
4961
4962                 dXSARGS;
4963
4964 =for hackers
4965 Found in file XSUB.h
4966
4967 =item dXSI32
4968
4969 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
4970 handled automatically by C<xsubpp>.
4971
4972                 dXSI32;
4973
4974 =for hackers
4975 Found in file XSUB.h
4976
4977 =item items
4978
4979 Variable which is setup by C<xsubpp> to indicate the number of 
4980 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
4981
4982         I32     items
4983
4984 =for hackers
4985 Found in file XSUB.h
4986
4987 =item ix
4988
4989 Variable which is setup by C<xsubpp> to indicate which of an 
4990 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
4991
4992         I32     ix
4993
4994 =for hackers
4995 Found in file XSUB.h
4996
4997 =item newXSproto
4998
4999 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
5000 the subs.
5001
5002 =for hackers
5003 Found in file XSUB.h
5004
5005 =item RETVAL
5006
5007 Variable which is setup by C<xsubpp> to hold the return value for an 
5008 XSUB. This is always the proper type for the XSUB. See 
5009 L<perlxs/"The RETVAL Variable">.
5010
5011         (whatever)      RETVAL
5012
5013 =for hackers
5014 Found in file XSUB.h
5015
5016 =item ST
5017
5018 Used to access elements on the XSUB's stack.
5019
5020         SV*     ST(int ix)
5021
5022 =for hackers
5023 Found in file XSUB.h
5024
5025 =item THIS
5026
5027 Variable which is setup by C<xsubpp> to designate the object in a C++ 
5028 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
5029 L<perlxs/"Using XS With C++">.
5030
5031         (whatever)      THIS
5032
5033 =for hackers
5034 Found in file XSUB.h
5035
5036 =item XS
5037
5038 Macro to declare an XSUB and its C parameter list.  This is handled by
5039 C<xsubpp>.
5040
5041 =for hackers
5042 Found in file XSUB.h
5043
5044 =item XSRETURN_EMPTY
5045
5046 Return an empty list from an XSUB immediately.
5047
5048
5049                 XSRETURN_EMPTY;
5050
5051 =for hackers
5052 Found in file XSUB.h
5053
5054 =item XS_VERSION
5055
5056 The version identifier for an XS module.  This is usually
5057 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
5058
5059 =for hackers
5060 Found in file XSUB.h
5061
5062 =item XS_VERSION_BOOTCHECK
5063
5064 Macro to verify that a PM module's $VERSION variable matches the XS
5065 module's C<XS_VERSION> variable.  This is usually handled automatically by
5066 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
5067
5068                 XS_VERSION_BOOTCHECK;
5069
5070 =for hackers
5071 Found in file XSUB.h
5072
5073
5074 =back
5075
5076 =head1 Warning and Dieing
5077
5078 =over 8
5079
5080 =item croak
5081
5082 This is the XSUB-writer's interface to Perl's C<die> function.
5083 Normally use this function the same way you use the C C<printf>
5084 function.  See C<warn>.
5085
5086 If you want to throw an exception object, assign the object to
5087 C<$@> and then pass C<Nullch> to croak():
5088
5089    errsv = get_sv("@", TRUE);
5090    sv_setsv(errsv, exception_object);
5091    croak(Nullch);
5092
5093         void    croak(const char* pat, ...)
5094
5095 =for hackers
5096 Found in file util.c
5097
5098 =item warn
5099
5100 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
5101 function the same way you use the C C<printf> function.  See
5102 C<croak>.
5103
5104         void    warn(const char* pat, ...)
5105
5106 =for hackers
5107 Found in file util.c
5108
5109
5110 =back
5111
5112 =head1 AUTHORS
5113
5114 Until May 1997, this document was maintained by Jeff Okamoto
5115 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
5116
5117 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
5118 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
5119 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
5120 Stephen McCamant, and Gurusamy Sarathy.
5121
5122 API Listing originally by Dean Roehrich <roehrich@cray.com>.
5123
5124 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
5125
5126 =head1 SEE ALSO
5127
5128 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
5129