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