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