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