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