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