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