This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
f4af853af7dbf7b9f940527586b7b1c1ab16ea00
[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).  However, if the
2253 C<vsnprintf> is not available, will unfortunately use the unsafe
2254 C<vsprintf> which can overrun the buffer (there is an overrun check,
2255 but that may be too late).  Consider using C<sv_vcatpvf> instead, or
2256 getting C<vsnprintf>.
2257
2258         int     my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2259
2260 =for hackers
2261 Found in file util.c
2262
2263 =item my_sprintf
2264 X<my_sprintf>
2265
2266 The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2267 the length of the string written to the buffer. Only rare pre-ANSI systems
2268 need the wrapper function - usually this is a direct call to C<sprintf>.
2269
2270         int     my_sprintf(char *buffer, const char *pat, ...)
2271
2272 =for hackers
2273 Found in file util.c
2274
2275 =item my_vsnprintf
2276 X<my_vsnprintf>
2277
2278 The C library C<vsnprintf> if available and standards-compliant.
2279 However, if if the C<vsnprintf> is not available, will unfortunately
2280 use the unsafe C<vsprintf> which can overrun the buffer (there is an
2281 overrun check, but that may be too late).  Consider using
2282 C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2283
2284         int     my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2285
2286 =for hackers
2287 Found in file util.c
2288
2289 =item new_version
2290 X<new_version>
2291
2292 Returns a new version object based on the passed in SV:
2293
2294     SV *sv = new_version(SV *ver);
2295
2296 Does not alter the passed in ver SV.  See "upg_version" if you
2297 want to upgrade the SV.
2298
2299         SV*     new_version(SV *ver)
2300
2301 =for hackers
2302 Found in file util.c
2303
2304 =item scan_version
2305 X<scan_version>
2306
2307 Returns a pointer to the next character after the parsed
2308 version string, as well as upgrading the passed in SV to
2309 an RV.
2310
2311 Function must be called with an already existing SV like
2312
2313     sv = newSV(0);
2314     s = scan_version(s,SV *sv, bool qv);
2315
2316 Performs some preprocessing to the string to ensure that
2317 it has the correct characteristics of a version.  Flags the
2318 object if it contains an underscore (which denotes this
2319 is a alpha version).  The boolean qv denotes that the version
2320 should be interpreted as if it had multiple decimals, even if
2321 it doesn't.
2322
2323         const char*     scan_version(const char *vstr, SV *sv, bool qv)
2324
2325 =for hackers
2326 Found in file util.c
2327
2328 =item strEQ
2329 X<strEQ>
2330
2331 Test two strings to see if they are equal.  Returns true or false.
2332
2333         bool    strEQ(char* s1, char* s2)
2334
2335 =for hackers
2336 Found in file handy.h
2337
2338 =item strGE
2339 X<strGE>
2340
2341 Test two strings to see if the first, C<s1>, is greater than or equal to
2342 the second, C<s2>.  Returns true or false.
2343
2344         bool    strGE(char* s1, char* s2)
2345
2346 =for hackers
2347 Found in file handy.h
2348
2349 =item strGT
2350 X<strGT>
2351
2352 Test two strings to see if the first, C<s1>, is greater than the second,
2353 C<s2>.  Returns true or false.
2354
2355         bool    strGT(char* s1, char* s2)
2356
2357 =for hackers
2358 Found in file handy.h
2359
2360 =item strLE
2361 X<strLE>
2362
2363 Test two strings to see if the first, C<s1>, is less than or equal to the
2364 second, C<s2>.  Returns true or false.
2365
2366         bool    strLE(char* s1, char* s2)
2367
2368 =for hackers
2369 Found in file handy.h
2370
2371 =item strLT
2372 X<strLT>
2373
2374 Test two strings to see if the first, C<s1>, is less than the second,
2375 C<s2>.  Returns true or false.
2376
2377         bool    strLT(char* s1, char* s2)
2378
2379 =for hackers
2380 Found in file handy.h
2381
2382 =item strNE
2383 X<strNE>
2384
2385 Test two strings to see if they are different.  Returns true or
2386 false.
2387
2388         bool    strNE(char* s1, char* s2)
2389
2390 =for hackers
2391 Found in file handy.h
2392
2393 =item strnEQ
2394 X<strnEQ>
2395
2396 Test two strings to see if they are equal.  The C<len> parameter indicates
2397 the number of bytes to compare.  Returns true or false. (A wrapper for
2398 C<strncmp>).
2399
2400         bool    strnEQ(char* s1, char* s2, STRLEN len)
2401
2402 =for hackers
2403 Found in file handy.h
2404
2405 =item strnNE
2406 X<strnNE>
2407
2408 Test two strings to see if they are different.  The C<len> parameter
2409 indicates the number of bytes to compare.  Returns true or false. (A
2410 wrapper for C<strncmp>).
2411
2412         bool    strnNE(char* s1, char* s2, STRLEN len)
2413
2414 =for hackers
2415 Found in file handy.h
2416
2417 =item sv_nosharing
2418 X<sv_nosharing>
2419
2420 Dummy routine which "shares" an SV when there is no sharing module present.
2421 Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2422 Exists to avoid test for a NULL function pointer and because it could
2423 potentially warn under some level of strict-ness.
2424
2425         void    sv_nosharing(SV *sv)
2426
2427 =for hackers
2428 Found in file util.c
2429
2430 =item upg_version
2431 X<upg_version>
2432
2433 In-place upgrade of the supplied SV to a version object.
2434
2435     SV *sv = upg_version(SV *sv);
2436
2437 Returns a pointer to the upgraded SV.
2438
2439         SV*     upg_version(SV *ver)
2440
2441 =for hackers
2442 Found in file util.c
2443
2444 =item vcmp
2445 X<vcmp>
2446
2447 Version object aware cmp.  Both operands must already have been 
2448 converted into version objects.
2449
2450         int     vcmp(SV *lvs, SV *rvs)
2451
2452 =for hackers
2453 Found in file util.c
2454
2455 =item vnormal
2456 X<vnormal>
2457
2458 Accepts a version object and returns the normalized string
2459 representation.  Call like:
2460
2461     sv = vnormal(rv);
2462
2463 NOTE: you can pass either the object directly or the SV
2464 contained within the RV.
2465
2466         SV*     vnormal(SV *vs)
2467
2468 =for hackers
2469 Found in file util.c
2470
2471 =item vnumify
2472 X<vnumify>
2473
2474 Accepts a version object and returns the normalized floating
2475 point representation.  Call like:
2476
2477     sv = vnumify(rv);
2478
2479 NOTE: you can pass either the object directly or the SV
2480 contained within the RV.
2481
2482         SV*     vnumify(SV *vs)
2483
2484 =for hackers
2485 Found in file util.c
2486
2487 =item vstringify
2488 X<vstringify>
2489
2490 In order to maintain maximum compatibility with earlier versions
2491 of Perl, this function will return either the floating point
2492 notation or the multiple dotted notation, depending on whether
2493 the original version contained 1 or more dots, respectively
2494
2495         SV*     vstringify(SV *vs)
2496
2497 =for hackers
2498 Found in file util.c
2499
2500 =item vverify
2501 X<vverify>
2502
2503 Validates that the SV contains a valid version object.
2504
2505     bool vverify(SV *vobj);
2506
2507 Note that it only confirms the bare minimum structure (so as not to get
2508 confused by derived classes which may contain additional hash entries):
2509
2510         bool    vverify(SV *vs)
2511
2512 =for hackers
2513 Found in file util.c
2514
2515
2516 =back
2517
2518 =head1 Multicall Functions
2519
2520 =over 8
2521
2522 =item dMULTICALL
2523 X<dMULTICALL>
2524
2525 Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2526
2527                 dMULTICALL;
2528
2529 =for hackers
2530 Found in file cop.h
2531
2532 =item MULTICALL
2533 X<MULTICALL>
2534
2535 Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2536
2537                 MULTICALL;
2538
2539 =for hackers
2540 Found in file cop.h
2541
2542 =item POP_MULTICALL
2543 X<POP_MULTICALL>
2544
2545 Closing bracket for a lightweight callback.
2546 See L<perlcall/Lightweight Callbacks>.
2547
2548                 POP_MULTICALL;
2549
2550 =for hackers
2551 Found in file cop.h
2552
2553 =item PUSH_MULTICALL
2554 X<PUSH_MULTICALL>
2555
2556 Opening bracket for a lightweight callback.
2557 See L<perlcall/Lightweight Callbacks>.
2558
2559                 PUSH_MULTICALL;
2560
2561 =for hackers
2562 Found in file cop.h
2563
2564
2565 =back
2566
2567 =head1 Numeric functions
2568
2569 =over 8
2570
2571 =item grok_bin
2572 X<grok_bin>
2573
2574 converts a string representing a binary number to numeric form.
2575
2576 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2577 conversion flags, and I<result> should be NULL or a pointer to an NV.
2578 The scan stops at the end of the string, or the first invalid character.
2579 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2580 invalid character will also trigger a warning.
2581 On return I<*len> is set to the length of the scanned string,
2582 and I<*flags> gives output flags.
2583
2584 If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2585 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2586 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2587 and writes the value to I<*result> (or the value is discarded if I<result>
2588 is NULL).
2589
2590 The binary number may optionally be prefixed with "0b" or "b" unless
2591 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2592 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2593 number may use '_' characters to separate digits.
2594
2595         UV      grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2596
2597 =for hackers
2598 Found in file numeric.c
2599
2600 =item grok_hex
2601 X<grok_hex>
2602
2603 converts a string representing a hex number to numeric form.
2604
2605 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2606 conversion flags, and I<result> should be NULL or a pointer to an NV.
2607 The scan stops at the end of the string, or the first invalid character.
2608 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2609 invalid character will also trigger a warning.
2610 On return I<*len> is set to the length of the scanned string,
2611 and I<*flags> gives output flags.
2612
2613 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2614 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2615 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2616 and writes the value to I<*result> (or the value is discarded if I<result>
2617 is NULL).
2618
2619 The hex number may optionally be prefixed with "0x" or "x" unless
2620 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2621 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2622 number may use '_' characters to separate digits.
2623
2624         UV      grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2625
2626 =for hackers
2627 Found in file numeric.c
2628
2629 =item grok_number
2630 X<grok_number>
2631
2632 Recognise (or not) a number.  The type of the number is returned
2633 (0 if unrecognised), otherwise it is a bit-ORed combination of
2634 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2635 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2636
2637 If the value of the number can fit an in UV, it is returned in the *valuep
2638 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2639 will never be set unless *valuep is valid, but *valuep may have been assigned
2640 to during processing even though IS_NUMBER_IN_UV is not set on return.
2641 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2642 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2643
2644 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2645 seen (in which case *valuep gives the true value truncated to an integer), and
2646 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2647 absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
2648 number is larger than a UV.
2649
2650         int     grok_number(const char *pv, STRLEN len, UV *valuep)
2651
2652 =for hackers
2653 Found in file numeric.c
2654
2655 =item grok_numeric_radix
2656 X<grok_numeric_radix>
2657
2658 Scan and skip for a numeric decimal separator (radix).
2659
2660         bool    grok_numeric_radix(const char **sp, const char *send)
2661
2662 =for hackers
2663 Found in file numeric.c
2664
2665 =item grok_oct
2666 X<grok_oct>
2667
2668 converts a string representing an octal number to numeric form.
2669
2670 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2671 conversion flags, and I<result> should be NULL or a pointer to an NV.
2672 The scan stops at the end of the string, or the first invalid character.
2673 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2674 invalid character will also trigger a warning.
2675 On return I<*len> is set to the length of the scanned string,
2676 and I<*flags> gives output flags.
2677
2678 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2679 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2680 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2681 and writes the value to I<*result> (or the value is discarded if I<result>
2682 is NULL).
2683
2684 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2685 number may use '_' characters to separate digits.
2686
2687         UV      grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
2688
2689 =for hackers
2690 Found in file numeric.c
2691
2692 =item scan_bin
2693 X<scan_bin>
2694
2695 For backwards compatibility. Use C<grok_bin> instead.
2696
2697         NV      scan_bin(const char* start, STRLEN len, STRLEN* retlen)
2698
2699 =for hackers
2700 Found in file numeric.c
2701
2702 =item scan_hex
2703 X<scan_hex>
2704
2705 For backwards compatibility. Use C<grok_hex> instead.
2706
2707         NV      scan_hex(const char* start, STRLEN len, STRLEN* retlen)
2708
2709 =for hackers
2710 Found in file numeric.c
2711
2712 =item scan_oct
2713 X<scan_oct>
2714
2715 For backwards compatibility. Use C<grok_oct> instead.
2716
2717         NV      scan_oct(const char* start, STRLEN len, STRLEN* retlen)
2718
2719 =for hackers
2720 Found in file numeric.c
2721
2722
2723 =back
2724
2725 =head1 Optree Manipulation Functions
2726
2727 =over 8
2728
2729 =item cv_const_sv
2730 X<cv_const_sv>
2731
2732 If C<cv> is a constant sub eligible for inlining. returns the constant
2733 value returned by the sub.  Otherwise, returns NULL.
2734
2735 Constant subs can be created with C<newCONSTSUB> or as described in
2736 L<perlsub/"Constant Functions">.
2737
2738         SV*     cv_const_sv(CV* cv)
2739
2740 =for hackers
2741 Found in file op.c
2742
2743 =item newCONSTSUB
2744 X<newCONSTSUB>
2745
2746 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
2747 eligible for inlining at compile-time.
2748
2749         CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)
2750
2751 =for hackers
2752 Found in file op.c
2753
2754 =item newXS
2755 X<newXS>
2756
2757 Used by C<xsubpp> to hook up XSUBs as Perl subs.  I<filename> needs to be
2758 static storage, as it is used directly as CvFILE(), without a copy being made.
2759
2760 =for hackers
2761 Found in file op.c
2762
2763
2764 =back
2765
2766 =head1 Pad Data Structures
2767
2768 =over 8
2769
2770 =item pad_sv
2771 X<pad_sv>
2772
2773 Get the value at offset po in the current pad.
2774 Use macro PAD_SV instead of calling this function directly.
2775
2776         SV*     pad_sv(PADOFFSET po)
2777
2778 =for hackers
2779 Found in file pad.c
2780
2781
2782 =back
2783
2784 =head1 Simple Exception Handling Macros
2785
2786 =over 8
2787
2788 =item dXCPT
2789 X<dXCPT>
2790
2791 Set up necessary local variables for exception handling.
2792 See L<perlguts/"Exception Handling">.
2793
2794                 dXCPT;
2795
2796 =for hackers
2797 Found in file XSUB.h
2798
2799 =item XCPT_CATCH
2800 X<XCPT_CATCH>
2801
2802 Introduces a catch block.  See L<perlguts/"Exception Handling">.
2803
2804 =for hackers
2805 Found in file XSUB.h
2806
2807 =item XCPT_RETHROW
2808 X<XCPT_RETHROW>
2809
2810 Rethrows a previously caught exception.  See L<perlguts/"Exception Handling">.
2811
2812                 XCPT_RETHROW;
2813
2814 =for hackers
2815 Found in file XSUB.h
2816
2817 =item XCPT_TRY_END
2818 X<XCPT_TRY_END>
2819
2820 Ends a try block.  See L<perlguts/"Exception Handling">.
2821
2822 =for hackers
2823 Found in file XSUB.h
2824
2825 =item XCPT_TRY_START
2826 X<XCPT_TRY_START>
2827
2828 Starts a try block.  See L<perlguts/"Exception Handling">.
2829
2830 =for hackers
2831 Found in file XSUB.h
2832
2833
2834 =back
2835
2836 =head1 Stack Manipulation Macros
2837
2838 =over 8
2839
2840 =item dMARK
2841 X<dMARK>
2842
2843 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
2844 C<dORIGMARK>.
2845
2846                 dMARK;
2847
2848 =for hackers
2849 Found in file pp.h
2850
2851 =item dORIGMARK
2852 X<dORIGMARK>
2853
2854 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
2855
2856                 dORIGMARK;
2857
2858 =for hackers
2859 Found in file pp.h
2860
2861 =item dSP
2862 X<dSP>
2863
2864 Declares a local copy of perl's stack pointer for the XSUB, available via
2865 the C<SP> macro.  See C<SP>.
2866
2867                 dSP;
2868
2869 =for hackers
2870 Found in file pp.h
2871
2872 =item EXTEND
2873 X<EXTEND>
2874
2875 Used to extend the argument stack for an XSUB's return values. Once
2876 used, guarantees that there is room for at least C<nitems> to be pushed
2877 onto the stack.
2878
2879         void    EXTEND(SP, int nitems)
2880
2881 =for hackers
2882 Found in file pp.h
2883
2884 =item MARK
2885 X<MARK>
2886
2887 Stack marker variable for the XSUB.  See C<dMARK>.
2888
2889 =for hackers
2890 Found in file pp.h
2891
2892 =item mPUSHi
2893 X<mPUSHi>
2894
2895 Push an integer onto the stack.  The stack must have room for this element.
2896 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi>
2897 and C<XPUSHi>.
2898
2899         void    mPUSHi(IV iv)
2900
2901 =for hackers
2902 Found in file pp.h
2903
2904 =item mPUSHn
2905 X<mPUSHn>
2906
2907 Push a double onto the stack.  The stack must have room for this element.
2908 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn>
2909 and C<XPUSHn>.
2910
2911         void    mPUSHn(NV nv)
2912
2913 =for hackers
2914 Found in file pp.h
2915
2916 =item mPUSHp
2917 X<mPUSHp>
2918
2919 Push a string onto the stack.  The stack must have room for this element.
2920 The C<len> indicates the length of the string.  Handles 'set' magic.  Does
2921 not use C<TARG>.  See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
2922
2923         void    mPUSHp(char* str, STRLEN len)
2924
2925 =for hackers
2926 Found in file pp.h
2927
2928 =item mPUSHu
2929 X<mPUSHu>
2930
2931 Push an unsigned integer onto the stack.  The stack must have room for this
2932 element.  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHu>,
2933 C<mXPUSHu> and C<XPUSHu>.
2934
2935         void    mPUSHu(UV uv)
2936
2937 =for hackers
2938 Found in file pp.h
2939
2940 =item mXPUSHi
2941 X<mXPUSHi>
2942
2943 Push an integer onto the stack, extending the stack if necessary.  Handles
2944 'set' magic.  Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and
2945 C<PUSHi>.
2946
2947         void    mXPUSHi(IV iv)
2948
2949 =for hackers
2950 Found in file pp.h
2951
2952 =item mXPUSHn
2953 X<mXPUSHn>
2954
2955 Push a double onto the stack, extending the stack if necessary.  Handles
2956 'set' magic.  Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and
2957 C<PUSHn>.
2958
2959         void    mXPUSHn(NV nv)
2960
2961 =for hackers
2962 Found in file pp.h
2963
2964 =item mXPUSHp
2965 X<mXPUSHp>
2966
2967 Push a string onto the stack, extending the stack if necessary.  The C<len>
2968 indicates the length of the string.  Handles 'set' magic.  Does not use
2969 C<TARG>.  See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
2970
2971         void    mXPUSHp(char* str, STRLEN len)
2972
2973 =for hackers
2974 Found in file pp.h
2975
2976 =item mXPUSHu
2977 X<mXPUSHu>
2978
2979 Push an unsigned integer onto the stack, extending the stack if necessary.
2980 Handles 'set' magic.  Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu>
2981 and C<PUSHu>.
2982
2983         void    mXPUSHu(UV uv)
2984
2985 =for hackers
2986 Found in file pp.h
2987
2988 =item ORIGMARK
2989 X<ORIGMARK>
2990
2991 The original stack mark for the XSUB.  See C<dORIGMARK>.
2992
2993 =for hackers
2994 Found in file pp.h
2995
2996 =item POPi
2997 X<POPi>
2998
2999 Pops an integer off the stack.
3000
3001         IV      POPi
3002
3003 =for hackers
3004 Found in file pp.h
3005
3006 =item POPl
3007 X<POPl>
3008
3009 Pops a long off the stack.
3010
3011         long    POPl
3012
3013 =for hackers
3014 Found in file pp.h
3015
3016 =item POPn
3017 X<POPn>
3018
3019 Pops a double off the stack.
3020
3021         NV      POPn
3022
3023 =for hackers
3024 Found in file pp.h
3025
3026 =item POPp
3027 X<POPp>
3028
3029 Pops a string off the stack. Deprecated. New code should use POPpx.
3030
3031         char*   POPp
3032
3033 =for hackers
3034 Found in file pp.h
3035
3036 =item POPpbytex
3037 X<POPpbytex>
3038
3039 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3040
3041         char*   POPpbytex
3042
3043 =for hackers
3044 Found in file pp.h
3045
3046 =item POPpx
3047 X<POPpx>
3048
3049 Pops a string off the stack.
3050
3051         char*   POPpx
3052
3053 =for hackers
3054 Found in file pp.h
3055
3056 =item POPs
3057 X<POPs>
3058
3059 Pops an SV off the stack.
3060
3061         SV*     POPs
3062
3063 =for hackers
3064 Found in file pp.h
3065
3066 =item PUSHi
3067 X<PUSHi>
3068
3069 Push an integer onto the stack.  The stack must have room for this element.
3070 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3071 called to declare it.  Do not call multiple C<TARG>-oriented macros to 
3072 return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
3073 C<mXPUSHi>.
3074
3075         void    PUSHi(IV iv)
3076
3077 =for hackers
3078 Found in file pp.h
3079
3080 =item PUSHMARK
3081 X<PUSHMARK>
3082
3083 Opening bracket for arguments on a callback.  See C<PUTBACK> and
3084 L<perlcall>.
3085
3086         void    PUSHMARK(SP)
3087
3088 =for hackers
3089 Found in file pp.h
3090
3091 =item PUSHmortal
3092 X<PUSHmortal>
3093
3094 Push a new mortal SV onto the stack.  The stack must have room for this
3095 element.  Does not handle 'set' magic.  Does not use C<TARG>.  See also
3096 C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3097
3098         void    PUSHmortal()
3099
3100 =for hackers
3101 Found in file pp.h
3102
3103 =item PUSHn
3104 X<PUSHn>
3105
3106 Push a double onto the stack.  The stack must have room for this element.
3107 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3108 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3109 return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
3110 C<mXPUSHn>.
3111
3112         void    PUSHn(NV nv)
3113
3114 =for hackers
3115 Found in file pp.h
3116
3117 =item PUSHp
3118 X<PUSHp>
3119
3120 Push a string onto the stack.  The stack must have room for this element.
3121 The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
3122 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
3123 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3124 C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
3125
3126         void    PUSHp(char* str, STRLEN len)
3127
3128 =for hackers
3129 Found in file pp.h
3130
3131 =item PUSHs
3132 X<PUSHs>
3133
3134 Push an SV onto the stack.  The stack must have room for this element.
3135 Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
3136 C<XPUSHs> and C<XPUSHmortal>.
3137
3138         void    PUSHs(SV* sv)
3139
3140 =for hackers
3141 Found in file pp.h
3142
3143 =item PUSHu
3144 X<PUSHu>
3145
3146 Push an unsigned integer onto the stack.  The stack must have room for this
3147 element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3148 should be called to declare it.  Do not call multiple C<TARG>-oriented
3149 macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
3150 C<XPUSHu> and C<mXPUSHu>.
3151
3152         void    PUSHu(UV uv)
3153
3154 =for hackers
3155 Found in file pp.h
3156
3157 =item PUTBACK
3158 X<PUTBACK>
3159
3160 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
3161 See C<PUSHMARK> and L<perlcall> for other uses.
3162
3163                 PUTBACK;
3164
3165 =for hackers
3166 Found in file pp.h
3167
3168 =item SP
3169 X<SP>
3170
3171 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
3172 C<SPAGAIN>.
3173
3174 =for hackers
3175 Found in file pp.h
3176
3177 =item SPAGAIN
3178 X<SPAGAIN>
3179
3180 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
3181
3182                 SPAGAIN;
3183
3184 =for hackers
3185 Found in file pp.h
3186
3187 =item XPUSHi
3188 X<XPUSHi>
3189
3190 Push an integer onto the stack, extending the stack if necessary.  Handles
3191 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3192 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3193 from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
3194
3195         void    XPUSHi(IV iv)
3196
3197 =for hackers
3198 Found in file pp.h
3199
3200 =item XPUSHmortal
3201 X<XPUSHmortal>
3202
3203 Push a new mortal SV onto the stack, extending the stack if necessary.  Does
3204 not handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHs>,
3205 C<PUSHmortal> and C<PUSHs>.
3206
3207         void    XPUSHmortal()
3208
3209 =for hackers
3210 Found in file pp.h
3211
3212 =item XPUSHn
3213 X<XPUSHn>
3214
3215 Push a double onto the stack, extending the stack if necessary.  Handles
3216 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3217 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3218 from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
3219
3220         void    XPUSHn(NV nv)
3221
3222 =for hackers
3223 Found in file pp.h
3224
3225 =item XPUSHp
3226 X<XPUSHp>
3227
3228 Push a string onto the stack, extending the stack if necessary.  The C<len>
3229 indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
3230 C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
3231 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3232 C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
3233
3234         void    XPUSHp(char* str, STRLEN len)
3235
3236 =for hackers
3237 Found in file pp.h
3238
3239 =item XPUSHs
3240 X<XPUSHs>
3241
3242 Push an SV onto the stack, extending the stack if necessary.  Does not
3243 handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
3244 C<PUSHs> and C<PUSHmortal>.
3245
3246         void    XPUSHs(SV* sv)
3247
3248 =for hackers
3249 Found in file pp.h
3250
3251 =item XPUSHu
3252 X<XPUSHu>
3253
3254 Push an unsigned integer onto the stack, extending the stack if necessary.
3255 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3256 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3257 return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
3258 C<mPUSHu>.
3259
3260         void    XPUSHu(UV uv)
3261
3262 =for hackers
3263 Found in file pp.h
3264
3265 =item XSRETURN
3266 X<XSRETURN>
3267
3268 Return from XSUB, indicating number of items on the stack.  This is usually
3269 handled by C<xsubpp>.
3270
3271         void    XSRETURN(int nitems)
3272
3273 =for hackers
3274 Found in file XSUB.h
3275
3276 =item XSRETURN_EMPTY
3277 X<XSRETURN_EMPTY>
3278
3279 Return an empty list from an XSUB immediately.
3280
3281                 XSRETURN_EMPTY;
3282
3283 =for hackers
3284 Found in file XSUB.h
3285
3286 =item XSRETURN_IV
3287 X<XSRETURN_IV>
3288
3289 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3290
3291         void    XSRETURN_IV(IV iv)
3292
3293 =for hackers
3294 Found in file XSUB.h
3295
3296 =item XSRETURN_NO
3297 X<XSRETURN_NO>
3298
3299 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3300
3301                 XSRETURN_NO;
3302
3303 =for hackers
3304 Found in file XSUB.h
3305
3306 =item XSRETURN_NV
3307 X<XSRETURN_NV>
3308
3309 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
3310
3311         void    XSRETURN_NV(NV nv)
3312
3313 =for hackers
3314 Found in file XSUB.h
3315
3316 =item XSRETURN_PV
3317 X<XSRETURN_PV>
3318
3319 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3320
3321         void    XSRETURN_PV(char* str)
3322
3323 =for hackers
3324 Found in file XSUB.h
3325
3326 =item XSRETURN_UNDEF
3327 X<XSRETURN_UNDEF>
3328
3329 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3330
3331                 XSRETURN_UNDEF;
3332
3333 =for hackers
3334 Found in file XSUB.h
3335
3336 =item XSRETURN_UV
3337 X<XSRETURN_UV>
3338
3339 Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
3340
3341         void    XSRETURN_UV(IV uv)
3342
3343 =for hackers
3344 Found in file XSUB.h
3345
3346 =item XSRETURN_YES
3347 X<XSRETURN_YES>
3348
3349 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3350
3351                 XSRETURN_YES;
3352
3353 =for hackers
3354 Found in file XSUB.h
3355
3356 =item XST_mIV
3357 X<XST_mIV>
3358
3359 Place an integer into the specified position C<pos> on the stack.  The
3360 value is stored in a new mortal SV.
3361
3362         void    XST_mIV(int pos, IV iv)
3363
3364 =for hackers
3365 Found in file XSUB.h
3366
3367 =item XST_mNO
3368 X<XST_mNO>
3369
3370 Place C<&PL_sv_no> into the specified position C<pos> on the
3371 stack.
3372
3373         void    XST_mNO(int pos)
3374
3375 =for hackers
3376 Found in file XSUB.h
3377
3378 =item XST_mNV
3379 X<XST_mNV>
3380
3381 Place a double into the specified position C<pos> on the stack.  The value
3382 is stored in a new mortal SV.
3383
3384         void    XST_mNV(int pos, NV nv)
3385
3386 =for hackers
3387 Found in file XSUB.h
3388
3389 =item XST_mPV
3390 X<XST_mPV>
3391
3392 Place a copy of a string into the specified position C<pos> on the stack. 
3393 The value is stored in a new mortal SV.
3394
3395         void    XST_mPV(int pos, char* str)
3396
3397 =for hackers
3398 Found in file XSUB.h
3399
3400 =item XST_mUNDEF
3401 X<XST_mUNDEF>
3402
3403 Place C<&PL_sv_undef> into the specified position C<pos> on the
3404 stack.
3405
3406         void    XST_mUNDEF(int pos)
3407
3408 =for hackers
3409 Found in file XSUB.h
3410
3411 =item XST_mYES
3412 X<XST_mYES>
3413
3414 Place C<&PL_sv_yes> into the specified position C<pos> on the
3415 stack.
3416
3417         void    XST_mYES(int pos)
3418
3419 =for hackers
3420 Found in file XSUB.h
3421
3422
3423 =back
3424
3425 =head1 SV Flags
3426
3427 =over 8
3428
3429 =item svtype
3430 X<svtype>
3431
3432 An enum of flags for Perl types.  These are found in the file B<sv.h>
3433 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3434
3435 =for hackers
3436 Found in file sv.h
3437
3438 =item SVt_IV
3439 X<SVt_IV>
3440
3441 Integer type flag for scalars.  See C<svtype>.
3442
3443 =for hackers
3444 Found in file sv.h
3445
3446 =item SVt_NV
3447 X<SVt_NV>
3448
3449 Double type flag for scalars.  See C<svtype>.
3450
3451 =for hackers
3452 Found in file sv.h
3453
3454 =item SVt_PV
3455 X<SVt_PV>
3456
3457 Pointer type flag for scalars.  See C<svtype>.
3458
3459 =for hackers
3460 Found in file sv.h
3461
3462 =item SVt_PVAV
3463 X<SVt_PVAV>
3464
3465 Type flag for arrays.  See C<svtype>.
3466
3467 =for hackers
3468 Found in file sv.h
3469
3470 =item SVt_PVCV
3471 X<SVt_PVCV>
3472
3473 Type flag for code refs.  See C<svtype>.
3474
3475 =for hackers
3476 Found in file sv.h
3477
3478 =item SVt_PVHV
3479 X<SVt_PVHV>
3480
3481 Type flag for hashes.  See C<svtype>.
3482
3483 =for hackers
3484 Found in file sv.h
3485
3486 =item SVt_PVMG
3487 X<SVt_PVMG>
3488
3489 Type flag for blessed scalars.  See C<svtype>.
3490
3491 =for hackers
3492 Found in file sv.h
3493
3494
3495 =back
3496
3497 =head1 SV Manipulation Functions
3498
3499 =over 8
3500
3501 =item get_sv
3502 X<get_sv>
3503
3504 Returns the SV of the specified Perl scalar.  If C<create> is set and the
3505 Perl variable does not exist then it will be created.  If C<create> is not
3506 set and the variable does not exist then NULL is returned.
3507
3508 NOTE: the perl_ form of this function is deprecated.
3509
3510         SV*     get_sv(const char* name, I32 create)
3511
3512 =for hackers
3513 Found in file perl.c
3514
3515 =item newRV_inc
3516 X<newRV_inc>
3517
3518 Creates an RV wrapper for an SV.  The reference count for the original SV is
3519 incremented.
3520
3521         SV*     newRV_inc(SV* sv)
3522
3523 =for hackers
3524 Found in file sv.h
3525
3526 =item SvCUR
3527 X<SvCUR>
3528
3529 Returns the length of the string which is in the SV.  See C<SvLEN>.
3530
3531         STRLEN  SvCUR(SV* sv)
3532
3533 =for hackers
3534 Found in file sv.h
3535
3536 =item SvCUR_set
3537 X<SvCUR_set>
3538
3539 Set the current length of the string which is in the SV.  See C<SvCUR>
3540 and C<SvIV_set>.
3541
3542         void    SvCUR_set(SV* sv, STRLEN len)
3543
3544 =for hackers
3545 Found in file sv.h
3546
3547 =item SvEND
3548 X<SvEND>
3549
3550 Returns a pointer to the last character in the string which is in the SV.
3551 See C<SvCUR>.  Access the character as *(SvEND(sv)).
3552
3553         char*   SvEND(SV* sv)
3554
3555 =for hackers
3556 Found in file sv.h
3557
3558 =item SvGAMAGIC
3559 X<SvGAMAGIC>
3560
3561 Returns true if the SV has get magic or overloading. If either is true then
3562 the scalar is active data, and has the potential to return a new value every
3563 time it is accessed. Hence you must be careful to only read it once per user
3564 logical operation and work with that returned value. If neither is true then
3565 the scalar's value cannot change unless written to.
3566
3567         char*   SvGAMAGIC(SV* sv)
3568
3569 =for hackers
3570 Found in file sv.h
3571
3572 =item SvGROW
3573 X<SvGROW>
3574
3575 Expands the character buffer in the SV so that it has room for the
3576 indicated number of bytes (remember to reserve space for an extra trailing
3577 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
3578 Returns a pointer to the character buffer.
3579
3580         char *  SvGROW(SV* sv, STRLEN len)
3581
3582 =for hackers
3583 Found in file sv.h
3584
3585 =item SvIOK
3586 X<SvIOK>
3587
3588 Returns a boolean indicating whether the SV contains an integer.
3589
3590         bool    SvIOK(SV* sv)
3591
3592 =for hackers
3593 Found in file sv.h
3594
3595 =item SvIOKp
3596 X<SvIOKp>
3597
3598 Returns a boolean indicating whether the SV contains an integer.  Checks
3599 the B<private> setting.  Use C<SvIOK>.
3600
3601         bool    SvIOKp(SV* sv)
3602
3603 =for hackers
3604 Found in file sv.h
3605
3606 =item SvIOK_notUV
3607 X<SvIOK_notUV>
3608
3609 Returns a boolean indicating whether the SV contains a signed integer.
3610
3611         bool    SvIOK_notUV(SV* sv)
3612
3613 =for hackers
3614 Found in file sv.h
3615
3616 =item SvIOK_off
3617 X<SvIOK_off>
3618
3619 Unsets the IV status of an SV.
3620
3621         void    SvIOK_off(SV* sv)
3622
3623 =for hackers
3624 Found in file sv.h
3625
3626 =item SvIOK_on
3627 X<SvIOK_on>
3628
3629 Tells an SV that it is an integer.
3630
3631         void    SvIOK_on(SV* sv)
3632
3633 =for hackers
3634 Found in file sv.h
3635
3636 =item SvIOK_only
3637 X<SvIOK_only>
3638
3639 Tells an SV that it is an integer and disables all other OK bits.
3640
3641         void    SvIOK_only(SV* sv)
3642
3643 =for hackers
3644 Found in file sv.h
3645
3646 =item SvIOK_only_UV
3647 X<SvIOK_only_UV>
3648
3649 Tells and SV that it is an unsigned integer and disables all other OK bits.
3650
3651         void    SvIOK_only_UV(SV* sv)
3652
3653 =for hackers
3654 Found in file sv.h
3655
3656 =item SvIOK_UV
3657 X<SvIOK_UV>
3658
3659 Returns a boolean indicating whether the SV contains an unsigned integer.
3660
3661         bool    SvIOK_UV(SV* sv)
3662
3663 =for hackers
3664 Found in file sv.h
3665
3666 =item SvIsCOW
3667 X<SvIsCOW>
3668
3669 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
3670 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
3671 COW)
3672
3673         bool    SvIsCOW(SV* sv)
3674
3675 =for hackers
3676 Found in file sv.h
3677
3678 =item SvIsCOW_shared_hash
3679 X<SvIsCOW_shared_hash>
3680
3681 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
3682 scalar.
3683
3684         bool    SvIsCOW_shared_hash(SV* sv)
3685
3686 =for hackers
3687 Found in file sv.h
3688
3689 =item SvIV
3690 X<SvIV>
3691
3692 Coerces the given SV to an integer and returns it. See  C<SvIVx> for a
3693 version which guarantees to evaluate sv only once.
3694
3695         IV      SvIV(SV* sv)
3696
3697 =for hackers
3698 Found in file sv.h
3699
3700 =item SvIVX
3701 X<SvIVX>
3702
3703 Returns the raw value in the SV's IV slot, without checks or conversions.
3704 Only use when you are sure SvIOK is true. See also C<SvIV()>.
3705
3706         IV      SvIVX(SV* sv)
3707
3708 =for hackers
3709 Found in file sv.h
3710
3711 =item SvIVx
3712 X<SvIVx>
3713
3714 Coerces the given SV to an integer and returns it. Guarantees to evaluate
3715 sv only once. Use the more efficient C<SvIV> otherwise.
3716
3717         IV      SvIVx(SV* sv)
3718
3719 =for hackers
3720 Found in file sv.h
3721
3722 =item SvIV_nomg
3723 X<SvIV_nomg>
3724
3725 Like C<SvIV> but doesn't process magic.
3726
3727         IV      SvIV_nomg(SV* sv)
3728
3729 =for hackers
3730 Found in file sv.h
3731
3732 =item SvIV_set
3733 X<SvIV_set>
3734
3735 Set the value of the IV pointer in sv to val.  It is possible to perform
3736 the same function of this macro with an lvalue assignment to C<SvIVX>.
3737 With future Perls, however, it will be more efficient to use 
3738 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
3739
3740         void    SvIV_set(SV* sv, IV val)
3741
3742 =for hackers
3743 Found in file sv.h
3744
3745 =item SvLEN
3746 X<SvLEN>
3747
3748 Returns the size of the string buffer in the SV, not including any part
3749 attributable to C<SvOOK>.  See C<SvCUR>.
3750
3751         STRLEN  SvLEN(SV* sv)
3752
3753 =for hackers
3754 Found in file sv.h
3755
3756 =item SvLEN_set
3757 X<SvLEN_set>
3758
3759 Set the actual length of the string which is in the SV.  See C<SvIV_set>.
3760
3761         void    SvLEN_set(SV* sv, STRLEN len)
3762
3763 =for hackers
3764 Found in file sv.h
3765
3766 =item SvMAGIC_set
3767 X<SvMAGIC_set>
3768
3769 Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
3770
3771         void    SvMAGIC_set(SV* sv, MAGIC* val)
3772
3773 =for hackers
3774 Found in file sv.h
3775
3776 =item SvNIOK
3777 X<SvNIOK>
3778
3779 Returns a boolean indicating whether the SV contains a number, integer or
3780 double.
3781
3782         bool    SvNIOK(SV* sv)
3783
3784 =for hackers
3785 Found in file sv.h
3786
3787 =item SvNIOKp
3788 X<SvNIOKp>
3789
3790 Returns a boolean indicating whether the SV contains a number, integer or
3791 double.  Checks the B<private> setting.  Use C<SvNIOK>.
3792
3793         bool    SvNIOKp(SV* sv)
3794
3795 =for hackers
3796 Found in file sv.h
3797
3798 =item SvNIOK_off
3799 X<SvNIOK_off>
3800
3801 Unsets the NV/IV status of an SV.
3802
3803         void    SvNIOK_off(SV* sv)
3804
3805 =for hackers
3806 Found in file sv.h
3807
3808 =item SvNOK
3809 X<SvNOK>
3810
3811 Returns a boolean indicating whether the SV contains a double.
3812
3813         bool    SvNOK(SV* sv)
3814
3815 =for hackers
3816 Found in file sv.h
3817
3818 =item SvNOKp
3819 X<SvNOKp>
3820
3821 Returns a boolean indicating whether the SV contains a double.  Checks the
3822 B<private> setting.  Use C<SvNOK>.
3823
3824         bool    SvNOKp(SV* sv)
3825
3826 =for hackers
3827 Found in file sv.h
3828
3829 =item SvNOK_off
3830 X<SvNOK_off>
3831
3832 Unsets the NV status of an SV.
3833
3834         void    SvNOK_off(SV* sv)
3835
3836 =for hackers
3837 Found in file sv.h
3838
3839 =item SvNOK_on
3840 X<SvNOK_on>
3841
3842 Tells an SV that it is a double.
3843
3844         void    SvNOK_on(SV* sv)
3845
3846 =for hackers
3847 Found in file sv.h
3848
3849 =item SvNOK_only
3850 X<SvNOK_only>
3851
3852 Tells an SV that it is a double and disables all other OK bits.
3853
3854         void    SvNOK_only(SV* sv)
3855
3856 =for hackers
3857 Found in file sv.h
3858
3859 =item SvNV
3860 X<SvNV>
3861
3862 Coerce the given SV to a double and return it. See  C<SvNVx> for a version
3863 which guarantees to evaluate sv only once.
3864
3865         NV      SvNV(SV* sv)
3866
3867 =for hackers
3868 Found in file sv.h
3869
3870 =item SvNVX
3871 X<SvNVX>
3872
3873 Returns the raw value in the SV's NV slot, without checks or conversions.
3874 Only use when you are sure SvNOK is true. See also C<SvNV()>.
3875
3876         NV      SvNVX(SV* sv)
3877
3878 =for hackers
3879 Found in file sv.h
3880
3881 =item SvNVx
3882 X<SvNVx>
3883
3884 Coerces the given SV to a double and returns it. Guarantees to evaluate
3885 sv only once. Use the more efficient C<SvNV> otherwise.
3886
3887         NV      SvNVx(SV* sv)
3888
3889 =for hackers
3890 Found in file sv.h
3891
3892 =item SvNV_set
3893 X<SvNV_set>
3894
3895 Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
3896
3897         void    SvNV_set(SV* sv, NV val)
3898
3899 =for hackers
3900 Found in file sv.h
3901
3902 =item SvOK
3903 X<SvOK>
3904
3905 Returns a boolean indicating whether the value is an SV. It also tells
3906 whether the value is defined or not.
3907
3908         bool    SvOK(SV* sv)
3909
3910 =for hackers
3911 Found in file sv.h
3912
3913 =item SvOOK
3914 X<SvOOK>
3915
3916 Returns a boolean indicating whether the SvIVX is a valid offset value for
3917 the SvPVX.  This hack is used internally to speed up removal of characters
3918 from the beginning of a SvPV.  When SvOOK is true, then the start of the
3919 allocated string buffer is really (SvPVX - SvIVX).
3920
3921         bool    SvOOK(SV* sv)
3922
3923 =for hackers
3924 Found in file sv.h
3925
3926 =item SvPOK
3927 X<SvPOK>
3928
3929 Returns a boolean indicating whether the SV contains a character
3930 string.
3931
3932         bool    SvPOK(SV* sv)
3933
3934 =for hackers
3935 Found in file sv.h
3936
3937 =item SvPOKp
3938 X<SvPOKp>
3939
3940 Returns a boolean indicating whether the SV contains a character string.
3941 Checks the B<private> setting.  Use C<SvPOK>.
3942
3943         bool    SvPOKp(SV* sv)
3944
3945 =for hackers
3946 Found in file sv.h
3947
3948 =item SvPOK_off
3949 X<SvPOK_off>
3950
3951 Unsets the PV status of an SV.
3952
3953         void    SvPOK_off(SV* sv)
3954
3955 =for hackers
3956 Found in file sv.h
3957
3958 =item SvPOK_on
3959 X<SvPOK_on>
3960
3961 Tells an SV that it is a string.
3962
3963         void    SvPOK_on(SV* sv)
3964
3965 =for hackers
3966 Found in file sv.h
3967
3968 =item SvPOK_only
3969 X<SvPOK_only>
3970
3971 Tells an SV that it is a string and disables all other OK bits.
3972 Will also turn off the UTF-8 status.
3973
3974         void    SvPOK_only(SV* sv)
3975
3976 =for hackers
3977 Found in file sv.h
3978
3979 =item SvPOK_only_UTF8
3980 X<SvPOK_only_UTF8>
3981
3982 Tells an SV that it is a string and disables all other OK bits,
3983 and leaves the UTF-8 status as it was.
3984
3985         void    SvPOK_only_UTF8(SV* sv)
3986
3987 =for hackers
3988 Found in file sv.h
3989
3990 =item SvPV
3991 X<SvPV>
3992
3993 Returns a pointer to the string in the SV, or a stringified form of
3994 the SV if the SV does not contain a string.  The SV may cache the
3995 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
3996 C<SvPVx> for a version which guarantees to evaluate sv only once.
3997
3998         char*   SvPV(SV* sv, STRLEN len)
3999
4000 =for hackers
4001 Found in file sv.h
4002
4003 =item SvPVbyte
4004 X<SvPVbyte>
4005
4006 Like C<SvPV>, but converts sv to byte representation first if necessary.
4007
4008         char*   SvPVbyte(SV* sv, STRLEN len)
4009
4010 =for hackers
4011 Found in file sv.h
4012
4013 =item SvPVbytex
4014 X<SvPVbytex>
4015
4016 Like C<SvPV>, but converts sv to byte representation first if necessary.
4017 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4018 otherwise.
4019
4020         char*   SvPVbytex(SV* sv, STRLEN len)
4021
4022 =for hackers
4023 Found in file sv.h
4024
4025 =item SvPVbytex_force
4026 X<SvPVbytex_force>
4027
4028 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4029 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4030 otherwise.
4031
4032         char*   SvPVbytex_force(SV* sv, STRLEN len)
4033
4034 =for hackers
4035 Found in file sv.h
4036
4037 =item SvPVbyte_force
4038 X<SvPVbyte_force>
4039
4040 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4041
4042         char*   SvPVbyte_force(SV* sv, STRLEN len)
4043
4044 =for hackers
4045 Found in file sv.h
4046
4047 =item SvPVbyte_nolen
4048 X<SvPVbyte_nolen>
4049
4050 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4051
4052         char*   SvPVbyte_nolen(SV* sv)
4053
4054 =for hackers
4055 Found in file sv.h
4056
4057 =item SvPVutf8
4058 X<SvPVutf8>
4059
4060 Like C<SvPV>, but converts sv to utf8 first if necessary.
4061
4062         char*   SvPVutf8(SV* sv, STRLEN len)
4063
4064 =for hackers
4065 Found in file sv.h
4066
4067 =item SvPVutf8x
4068 X<SvPVutf8x>
4069
4070 Like C<SvPV>, but converts sv to utf8 first if necessary.
4071 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4072 otherwise.
4073
4074         char*   SvPVutf8x(SV* sv, STRLEN len)
4075
4076 =for hackers
4077 Found in file sv.h
4078
4079 =item SvPVutf8x_force
4080 X<SvPVutf8x_force>
4081
4082 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4083 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4084 otherwise.
4085
4086         char*   SvPVutf8x_force(SV* sv, STRLEN len)
4087
4088 =for hackers
4089 Found in file sv.h
4090
4091 =item SvPVutf8_force
4092 X<SvPVutf8_force>
4093
4094 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4095
4096         char*   SvPVutf8_force(SV* sv, STRLEN len)
4097
4098 =for hackers
4099 Found in file sv.h
4100
4101 =item SvPVutf8_nolen
4102 X<SvPVutf8_nolen>
4103
4104 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4105
4106         char*   SvPVutf8_nolen(SV* sv)
4107
4108 =for hackers
4109 Found in file sv.h
4110
4111 =item SvPVX
4112 X<SvPVX>
4113
4114 Returns a pointer to the physical string in the SV.  The SV must contain a
4115 string.
4116
4117         char*   SvPVX(SV* sv)
4118
4119 =for hackers
4120 Found in file sv.h
4121
4122 =item SvPVx
4123 X<SvPVx>
4124
4125 A version of C<SvPV> which guarantees to evaluate sv only once.
4126
4127         char*   SvPVx(SV* sv, STRLEN len)
4128
4129 =for hackers
4130 Found in file sv.h
4131
4132 =item SvPV_force
4133 X<SvPV_force>
4134
4135 Like C<SvPV> but will force the SV into containing just a string
4136 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4137 directly.
4138
4139         char*   SvPV_force(SV* sv, STRLEN len)
4140
4141 =for hackers
4142 Found in file sv.h
4143
4144 =item SvPV_force_nomg
4145 X<SvPV_force_nomg>
4146
4147 Like C<SvPV> but will force the SV into containing just a string
4148 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4149 directly. Doesn't process magic.
4150
4151         char*   SvPV_force_nomg(SV* sv, STRLEN len)
4152
4153 =for hackers
4154 Found in file sv.h
4155
4156 =item SvPV_nolen
4157 X<SvPV_nolen>
4158
4159 Returns a pointer to the string in the SV, or a stringified form of
4160 the SV if the SV does not contain a string.  The SV may cache the
4161 stringified form becoming C<SvPOK>.  Handles 'get' magic.
4162
4163         char*   SvPV_nolen(SV* sv)
4164
4165 =for hackers
4166 Found in file sv.h
4167
4168 =item SvPV_nomg
4169 X<SvPV_nomg>
4170
4171 Like C<SvPV> but doesn't process magic.
4172
4173         char*   SvPV_nomg(SV* sv, STRLEN len)
4174
4175 =for hackers
4176 Found in file sv.h
4177
4178 =item SvPV_set
4179 X<SvPV_set>
4180
4181 Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
4182
4183         void    SvPV_set(SV* sv, char* val)
4184
4185 =for hackers
4186 Found in file sv.h
4187
4188 =item SvREFCNT
4189 X<SvREFCNT>
4190
4191 Returns the value of the object's reference count.
4192
4193         U32     SvREFCNT(SV* sv)
4194
4195 =for hackers
4196 Found in file sv.h
4197
4198 =item SvREFCNT_dec
4199 X<SvREFCNT_dec>
4200
4201 Decrements the reference count of the given SV.
4202
4203         void    SvREFCNT_dec(SV* sv)
4204
4205 =for hackers
4206 Found in file sv.h
4207
4208 =item SvREFCNT_inc
4209 X<SvREFCNT_inc>
4210
4211 Increments the reference count of the given SV.
4212
4213         SV*     SvREFCNT_inc(SV* sv)
4214
4215 =for hackers
4216 Found in file sv.h
4217
4218 =item SvREFCNT_inc_NN
4219 X<SvREFCNT_inc_NN>
4220
4221 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4222 is not NULL.  Since we don't have to check the NULLness, it's faster
4223 and smaller.
4224
4225         SV*     SvREFCNT_inc_NN(SV* sv)
4226
4227 =for hackers
4228 Found in file sv.h
4229
4230 =item SvREFCNT_inc_simple
4231 X<SvREFCNT_inc_simple>
4232
4233 Same as SvREFCNT_inc, but can only be used with simple variables, not
4234 expressions or pointer dereferences.  Since we don't have to store a
4235 temporary value, it's faster.
4236
4237         SV*     SvREFCNT_inc_simple(SV* sv)
4238
4239 =for hackers
4240 Found in file sv.h
4241
4242 =item SvREFCNT_inc_simple_NN
4243 X<SvREFCNT_inc_simple_NN>
4244
4245 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4246 is not NULL.  Since we don't have to check the NULLness, it's faster
4247 and smaller.
4248
4249         SV*     SvREFCNT_inc_simple_NN(SV* sv)
4250
4251 =for hackers
4252 Found in file sv.h
4253
4254 =item SvREFCNT_inc_simple_void
4255 X<SvREFCNT_inc_simple_void>
4256
4257 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4258 return value.  The macro doesn't need to return a meaningful value.
4259
4260         SV*     SvREFCNT_inc_simple_void(SV* sv)
4261
4262 =for hackers
4263 Found in file sv.h
4264
4265 =item SvREFCNT_inc_void
4266 X<SvREFCNT_inc_void>
4267
4268 Same as SvREFCNT_inc, but can only be used if you don't need the
4269 return value.  The macro doesn't need to return a meaningful value.
4270
4271         SV*     SvREFCNT_inc_void(SV* sv)
4272
4273 =for hackers
4274 Found in file sv.h
4275
4276 =item SvREFCNT_inc_void_NN
4277 X<SvREFCNT_inc_void_NN>
4278
4279 Same as SvREFCNT_inc, but can only be used if you don't need the return
4280 value, and you know that I<sv> is not NULL.  The macro doesn't need
4281 to return a meaningful value, or check for NULLness, so it's smaller
4282 and faster.
4283
4284         SV*     SvREFCNT_inc_void_NN(SV* sv)
4285
4286 =for hackers
4287 Found in file sv.h
4288
4289 =item SvROK
4290 X<SvROK>
4291
4292 Tests if the SV is an RV.
4293
4294         bool    SvROK(SV* sv)
4295
4296 =for hackers
4297 Found in file sv.h
4298
4299 =item SvROK_off
4300 X<SvROK_off>
4301
4302 Unsets the RV status of an SV.
4303
4304         void    SvROK_off(SV* sv)
4305
4306 =for hackers
4307 Found in file sv.h
4308
4309 =item SvROK_on
4310 X<SvROK_on>
4311
4312 Tells an SV that it is an RV.
4313
4314         void    SvROK_on(SV* sv)
4315
4316 =for hackers
4317 Found in file sv.h
4318
4319 =item SvRV
4320 X<SvRV>
4321
4322 Dereferences an RV to return the SV.
4323
4324         SV*     SvRV(SV* sv)
4325
4326 =for hackers
4327 Found in file sv.h
4328
4329 =item SvRV_set
4330 X<SvRV_set>
4331
4332 Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
4333
4334         void    SvRV_set(SV* sv, SV* val)
4335
4336 =for hackers
4337 Found in file sv.h
4338
4339 =item SvSTASH
4340 X<SvSTASH>
4341
4342 Returns the stash of the SV.
4343
4344         HV*     SvSTASH(SV* sv)
4345
4346 =for hackers
4347 Found in file sv.h
4348
4349 =item SvSTASH_set
4350 X<SvSTASH_set>
4351
4352 Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
4353
4354         void    SvSTASH_set(SV* sv, HV* val)
4355
4356 =for hackers
4357 Found in file sv.h
4358
4359 =item SvTAINT
4360 X<SvTAINT>
4361
4362 Taints an SV if tainting is enabled.
4363
4364         void    SvTAINT(SV* sv)
4365
4366 =for hackers
4367 Found in file sv.h
4368
4369 =item SvTAINTED
4370 X<SvTAINTED>
4371
4372 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4373 not.
4374
4375         bool    SvTAINTED(SV* sv)
4376
4377 =for hackers
4378 Found in file sv.h
4379
4380 =item SvTAINTED_off
4381 X<SvTAINTED_off>
4382
4383 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4384 some of Perl's fundamental security features. XS module authors should not
4385 use this function unless they fully understand all the implications of
4386 unconditionally untainting the value. Untainting should be done in the
4387 standard perl fashion, via a carefully crafted regexp, rather than directly
4388 untainting variables.
4389
4390         void    SvTAINTED_off(SV* sv)
4391
4392 =for hackers
4393 Found in file sv.h
4394
4395 =item SvTAINTED_on
4396 X<SvTAINTED_on>
4397
4398 Marks an SV as tainted if tainting is enabled.
4399
4400         void    SvTAINTED_on(SV* sv)
4401
4402 =for hackers
4403 Found in file sv.h
4404
4405 =item SvTRUE
4406 X<SvTRUE>
4407
4408 Returns a boolean indicating whether Perl would evaluate the SV as true or
4409 false, defined or undefined.  Does not handle 'get' magic.
4410
4411         bool    SvTRUE(SV* sv)
4412
4413 =for hackers
4414 Found in file sv.h
4415
4416 =item SvTYPE
4417 X<SvTYPE>
4418
4419 Returns the type of the SV.  See C<svtype>.
4420
4421         svtype  SvTYPE(SV* sv)
4422
4423 =for hackers
4424 Found in file sv.h
4425
4426 =item SvUOK
4427 X<SvUOK>
4428
4429 Returns a boolean indicating whether the SV contains an unsigned integer.
4430
4431         void    SvUOK(SV* sv)
4432
4433 =for hackers
4434 Found in file sv.h
4435
4436 =item SvUPGRADE
4437 X<SvUPGRADE>
4438
4439 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
4440 perform the upgrade if necessary.  See C<svtype>.
4441
4442         void    SvUPGRADE(SV* sv, svtype type)
4443
4444 =for hackers
4445 Found in file sv.h
4446
4447 =item SvUTF8
4448 X<SvUTF8>
4449
4450 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
4451
4452         bool    SvUTF8(SV* sv)
4453
4454 =for hackers
4455 Found in file sv.h
4456
4457 =item SvUTF8_off
4458 X<SvUTF8_off>
4459
4460 Unsets the UTF-8 status of an SV.
4461
4462         void    SvUTF8_off(SV *sv)
4463
4464 =for hackers
4465 Found in file sv.h
4466
4467 =item SvUTF8_on
4468 X<SvUTF8_on>
4469
4470 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4471 Do not use frivolously.
4472
4473         void    SvUTF8_on(SV *sv)
4474
4475 =for hackers
4476 Found in file sv.h
4477
4478 =item SvUV
4479 X<SvUV>
4480
4481 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
4482 for a version which guarantees to evaluate sv only once.
4483
4484         UV      SvUV(SV* sv)
4485
4486 =for hackers
4487 Found in file sv.h
4488
4489 =item SvUVX
4490 X<SvUVX>
4491
4492 Returns the raw value in the SV's UV slot, without checks or conversions.
4493 Only use when you are sure SvIOK is true. See also C<SvUV()>.
4494
4495         UV      SvUVX(SV* sv)
4496
4497 =for hackers
4498 Found in file sv.h
4499
4500 =item SvUVx
4501 X<SvUVx>
4502
4503 Coerces the given SV to an unsigned integer and returns it. Guarantees to
4504 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
4505
4506         UV      SvUVx(SV* sv)
4507
4508 =for hackers
4509 Found in file sv.h
4510
4511 =item SvUV_nomg
4512 X<SvUV_nomg>
4513
4514 Like C<SvUV> but doesn't process magic.
4515
4516         UV      SvUV_nomg(SV* sv)
4517
4518 =for hackers
4519 Found in file sv.h
4520
4521 =item SvUV_set
4522 X<SvUV_set>
4523
4524 Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
4525
4526         void    SvUV_set(SV* sv, UV val)
4527
4528 =for hackers
4529 Found in file sv.h
4530
4531 =item SvVOK
4532 X<SvVOK>
4533
4534 Returns a boolean indicating whether the SV contains a v-string.
4535
4536         bool    SvVOK(SV* sv)
4537
4538 =for hackers
4539 Found in file sv.h
4540
4541 =item sv_catpvn_nomg
4542 X<sv_catpvn_nomg>
4543
4544 Like C<sv_catpvn> but doesn't process magic.
4545
4546         void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
4547
4548 =for hackers
4549 Found in file sv.h
4550
4551 =item sv_catsv_nomg
4552 X<sv_catsv_nomg>
4553
4554 Like C<sv_catsv> but doesn't process magic.
4555
4556         void    sv_catsv_nomg(SV* dsv, SV* ssv)
4557
4558 =for hackers
4559 Found in file sv.h
4560
4561 =item sv_derived_from
4562 X<sv_derived_from>
4563
4564 Returns a boolean indicating whether the SV is derived from the specified class
4565 I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
4566 normal Perl method.
4567
4568         bool    sv_derived_from(SV* sv, const char* name)
4569
4570 =for hackers
4571 Found in file universal.c
4572
4573 =item sv_report_used
4574 X<sv_report_used>
4575
4576 Dump the contents of all SVs not yet freed. (Debugging aid).
4577
4578         void    sv_report_used()
4579
4580 =for hackers
4581 Found in file sv.c
4582
4583 =item sv_setsv_nomg
4584 X<sv_setsv_nomg>
4585
4586 Like C<sv_setsv> but doesn't process magic.
4587
4588         void    sv_setsv_nomg(SV* dsv, SV* ssv)
4589
4590 =for hackers
4591 Found in file sv.h
4592
4593
4594 =back
4595
4596 =head1 SV-Body Allocation
4597
4598 =over 8
4599
4600 =item looks_like_number
4601 X<looks_like_number>
4602
4603 Test if the content of an SV looks like a number (or is a number).
4604 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
4605 non-numeric warning), even if your atof() doesn't grok them.
4606
4607         I32     looks_like_number(SV* sv)
4608
4609 =for hackers
4610 Found in file sv.c
4611
4612 =item newRV_noinc
4613 X<newRV_noinc>
4614
4615 Creates an RV wrapper for an SV.  The reference count for the original
4616 SV is B<not> incremented.
4617
4618         SV*     newRV_noinc(SV* sv)
4619
4620 =for hackers
4621 Found in file sv.c
4622
4623 =item newSV
4624 X<newSV>
4625
4626 Creates a new SV.  A non-zero C<len> parameter indicates the number of
4627 bytes of preallocated string space the SV should have.  An extra byte for a
4628 trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
4629 space is allocated.)  The reference count for the new SV is set to 1.
4630
4631 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
4632 parameter, I<x>, a debug aid which allowed callers to identify themselves.
4633 This aid has been superseded by a new build option, PERL_MEM_LOG (see
4634 L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
4635 modules supporting older perls.
4636
4637         SV*     newSV(STRLEN len)
4638
4639 =for hackers
4640 Found in file sv.c
4641
4642 =item newSVhek
4643 X<newSVhek>
4644
4645 Creates a new SV from the hash key structure.  It will generate scalars that
4646 point to the shared string table where possible. Returns a new (undefined)
4647 SV if the hek is NULL.
4648
4649         SV*     newSVhek(const HEK *hek)
4650
4651 =for hackers
4652 Found in file sv.c
4653
4654 =item newSViv
4655 X<newSViv>
4656
4657 Creates a new SV and copies an integer into it.  The reference count for the
4658 SV is set to 1.
4659
4660         SV*     newSViv(IV i)
4661
4662 =for hackers
4663 Found in file sv.c
4664
4665 =item newSVnv
4666 X<newSVnv>
4667
4668 Creates a new SV and copies a floating point value into it.
4669 The reference count for the SV is set to 1.
4670
4671         SV*     newSVnv(NV n)
4672
4673 =for hackers
4674 Found in file sv.c
4675
4676 =item newSVpv
4677 X<newSVpv>
4678
4679 Creates a new SV and copies a string into it.  The reference count for the
4680 SV is set to 1.  If C<len> is zero, Perl will compute the length using
4681 strlen().  For efficiency, consider using C<newSVpvn> instead.
4682
4683         SV*     newSVpv(const char* s, STRLEN len)
4684
4685 =for hackers
4686 Found in file sv.c
4687
4688 =item newSVpvf
4689 X<newSVpvf>
4690
4691 Creates a new SV and initializes it with the string formatted like
4692 C<sprintf>.
4693
4694         SV*     newSVpvf(const char* pat, ...)
4695
4696 =for hackers
4697 Found in file sv.c
4698
4699 =item newSVpvn
4700 X<newSVpvn>
4701
4702 Creates a new SV and copies a string into it.  The reference count for the
4703 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
4704 string.  You are responsible for ensuring that the source string is at least
4705 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
4706
4707         SV*     newSVpvn(const char* s, STRLEN len)
4708
4709 =for hackers
4710 Found in file sv.c
4711
4712 =item newSVpvn_share
4713 X<newSVpvn_share>
4714
4715 Creates a new SV with its SvPVX_const pointing to a shared string in the string
4716 table. If the string does not already exist in the table, it is created
4717 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
4718 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
4719 otherwise the hash is computed.  The idea here is that as the string table
4720 is used for shared hash keys these strings will have SvPVX_const == HeKEY and
4721 hash lookup will avoid string compare.
4722
4723         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
4724
4725 =for hackers
4726 Found in file sv.c
4727
4728 =item newSVrv
4729 X<newSVrv>
4730
4731 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
4732 it will be upgraded to one.  If C<classname> is non-null then the new SV will
4733 be blessed in the specified package.  The new SV is returned and its
4734 reference count is 1.
4735
4736         SV*     newSVrv(SV* rv, const char* classname)
4737
4738 =for hackers
4739 Found in file sv.c
4740
4741 =item newSVsv
4742 X<newSVsv>
4743
4744 Creates a new SV which is an exact duplicate of the original SV.
4745 (Uses C<sv_setsv>).
4746
4747         SV*     newSVsv(SV* old)
4748
4749 =for hackers
4750 Found in file sv.c
4751
4752 =item newSVuv
4753 X<newSVuv>
4754
4755 Creates a new SV and copies an unsigned integer into it.
4756 The reference count for the SV is set to 1.
4757
4758         SV*     newSVuv(UV u)
4759
4760 =for hackers
4761 Found in file sv.c
4762
4763 =item sv_2bool
4764 X<sv_2bool>
4765
4766 This function is only called on magical items, and is only used by
4767 sv_true() or its macro equivalent.
4768
4769         bool    sv_2bool(SV* sv)
4770
4771 =for hackers
4772 Found in file sv.c
4773
4774 =item sv_2cv
4775 X<sv_2cv>
4776
4777 Using various gambits, try to get a CV from an SV; in addition, try if
4778 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
4779 The flags in C<lref> are passed to sv_fetchsv.
4780
4781         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
4782
4783 =for hackers
4784 Found in file sv.c
4785
4786 =item sv_2io
4787 X<sv_2io>
4788
4789 Using various gambits, try to get an IO from an SV: the IO slot if its a
4790 GV; or the recursive result if we're an RV; or the IO slot of the symbol
4791 named after the PV if we're a string.
4792
4793         IO*     sv_2io(SV* sv)
4794
4795 =for hackers
4796 Found in file sv.c
4797
4798 =item sv_2iv_flags
4799 X<sv_2iv_flags>
4800
4801 Return the integer value of an SV, doing any necessary string
4802 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
4803 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
4804
4805         IV      sv_2iv_flags(SV* sv, I32 flags)
4806
4807 =for hackers
4808 Found in file sv.c
4809
4810 =item sv_2mortal
4811 X<sv_2mortal>
4812
4813 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
4814 by an explicit call to FREETMPS, or by an implicit call at places such as
4815 statement boundaries.  SvTEMP() is turned on which means that the SV's
4816 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
4817 and C<sv_mortalcopy>.
4818
4819         SV*     sv_2mortal(SV* sv)
4820
4821 =for hackers
4822 Found in file sv.c
4823
4824 =item sv_2nv
4825 X<sv_2nv>
4826
4827 Return the num value of an SV, doing any necessary string or integer
4828 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
4829 macros.
4830
4831         NV      sv_2nv(SV* sv)
4832
4833 =for hackers
4834 Found in file sv.c
4835
4836 =item sv_2pvbyte
4837 X<sv_2pvbyte>
4838
4839 Return a pointer to the byte-encoded representation of the SV, and set *lp
4840 to its length.  May cause the SV to be downgraded from UTF-8 as a
4841 side-effect.
4842
4843 Usually accessed via the C<SvPVbyte> macro.
4844
4845         char*   sv_2pvbyte(SV* sv, STRLEN* lp)
4846
4847 =for hackers
4848 Found in file sv.c
4849
4850 =item sv_2pvutf8
4851 X<sv_2pvutf8>
4852
4853 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
4854 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
4855
4856 Usually accessed via the C<SvPVutf8> macro.
4857
4858         char*   sv_2pvutf8(SV* sv, STRLEN* lp)
4859
4860 =for hackers
4861 Found in file sv.c
4862
4863 =item sv_2pv_flags
4864 X<sv_2pv_flags>
4865
4866 Returns a pointer to the string value of an SV, and sets *lp to its length.
4867 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
4868 if necessary.
4869 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
4870 usually end up here too.
4871
4872         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
4873
4874 =for hackers
4875 Found in file sv.c
4876
4877 =item sv_2uv_flags
4878 X<sv_2uv_flags>
4879
4880 Return the unsigned integer value of an SV, doing any necessary string
4881 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
4882 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
4883
4884         UV      sv_2uv_flags(SV* sv, I32 flags)
4885
4886 =for hackers
4887 Found in file sv.c
4888
4889 =item sv_backoff
4890 X<sv_backoff>
4891
4892 Remove any string offset. You should normally use the C<SvOOK_off> macro
4893 wrapper instead.
4894
4895         int     sv_backoff(SV* sv)
4896
4897 =for hackers
4898 Found in file sv.c
4899
4900 =item sv_bless
4901 X<sv_bless>
4902
4903 Blesses an SV into a specified package.  The SV must be an RV.  The package
4904 must be designated by its stash (see C<gv_stashpv()>).  The reference count
4905 of the SV is unaffected.
4906
4907         SV*     sv_bless(SV* sv, HV* stash)
4908
4909 =for hackers
4910 Found in file sv.c
4911
4912 =item sv_catpv
4913 X<sv_catpv>
4914
4915 Concatenates the string onto the end of the string which is in the SV.
4916 If the SV has the UTF-8 status set, then the bytes appended should be
4917 valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
4918
4919         void    sv_catpv(SV* sv, const char* ptr)
4920
4921 =for hackers
4922 Found in file sv.c
4923
4924 =item sv_catpvf
4925 X<sv_catpvf>
4926
4927 Processes its arguments like C<sprintf> and appends the formatted
4928 output to an SV.  If the appended data contains "wide" characters
4929 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
4930 and characters >255 formatted with %c), the original SV might get
4931 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
4932 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
4933 valid UTF-8; if the original SV was bytes, the pattern should be too.
4934
4935         void    sv_catpvf(SV* sv, const char* pat, ...)
4936
4937 =for hackers
4938 Found in file sv.c
4939
4940 =item sv_catpvf_mg
4941 X<sv_catpvf_mg>
4942
4943 Like C<sv_catpvf>, but also handles 'set' magic.
4944
4945         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
4946
4947 =for hackers
4948 Found in file sv.c
4949
4950 =item sv_catpvn
4951 X<sv_catpvn>
4952
4953 Concatenates the string onto the end of the string which is in the SV.  The
4954 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
4955 status set, then the bytes appended should be valid UTF-8.
4956 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
4957
4958         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
4959
4960 =for hackers
4961 Found in file sv.c
4962
4963 =item sv_catpvn_flags
4964 X<sv_catpvn_flags>
4965
4966 Concatenates the string onto the end of the string which is in the SV.  The
4967 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
4968 status set, then the bytes appended should be valid UTF-8.
4969 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
4970 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
4971 in terms of this function.
4972
4973         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
4974
4975 =for hackers
4976 Found in file sv.c
4977
4978 =item sv_catpv_mg
4979 X<sv_catpv_mg>
4980
4981 Like C<sv_catpv>, but also handles 'set' magic.
4982
4983         void    sv_catpv_mg(SV *sv, const char *ptr)
4984
4985 =for hackers
4986 Found in file sv.c
4987
4988 =item sv_catsv
4989 X<sv_catsv>
4990
4991 Concatenates the string from SV C<ssv> onto the end of the string in
4992 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
4993 not 'set' magic.  See C<sv_catsv_mg>.
4994
4995         void    sv_catsv(SV* dsv, SV* ssv)
4996
4997 =for hackers
4998 Found in file sv.c
4999
5000 =item sv_catsv_flags
5001 X<sv_catsv_flags>
5002
5003 Concatenates the string from SV C<ssv> onto the end of the string in
5004 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
5005 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5006 and C<sv_catsv_nomg> are implemented in terms of this function.
5007
5008         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
5009
5010 =for hackers
5011 Found in file sv.c
5012
5013 =item sv_chop
5014 X<sv_chop>
5015
5016 Efficient removal of characters from the beginning of the string buffer.
5017 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5018 the string buffer.  The C<ptr> becomes the first character of the adjusted
5019 string. Uses the "OOK hack".
5020 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5021 refer to the same chunk of data.
5022
5023         void    sv_chop(SV* sv, const char* ptr)
5024
5025 =for hackers
5026 Found in file sv.c
5027
5028 =item sv_clear
5029 X<sv_clear>
5030
5031 Clear an SV: call any destructors, free up any memory used by the body,
5032 and free the body itself. The SV's head is I<not> freed, although
5033 its type is set to all 1's so that it won't inadvertently be assumed
5034 to be live during global destruction etc.
5035 This function should only be called when REFCNT is zero. Most of the time
5036 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5037 instead.
5038
5039         void    sv_clear(SV* sv)
5040
5041 =for hackers
5042 Found in file sv.c
5043
5044 =item sv_cmp
5045 X<sv_cmp>
5046
5047 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
5048 string in C<sv1> is less than, equal to, or greater than the string in
5049 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5050 coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
5051
5052         I32     sv_cmp(SV* sv1, SV* sv2)
5053
5054 =for hackers
5055 Found in file sv.c
5056
5057 =item sv_cmp_locale
5058 X<sv_cmp_locale>
5059
5060 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5061 'use bytes' aware, handles get magic, and will coerce its args to strings
5062 if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
5063
5064         I32     sv_cmp_locale(SV* sv1, SV* sv2)
5065
5066 =for hackers
5067 Found in file sv.c
5068
5069 =item sv_collxfrm
5070 X<sv_collxfrm>
5071
5072 Add Collate Transform magic to an SV if it doesn't already have it.
5073
5074 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
5075 scalar data of the variable, but transformed to such a format that a normal
5076 memory comparison can be used to compare the data according to the locale
5077 settings.
5078
5079         char*   sv_collxfrm(SV* sv, STRLEN* nxp)
5080
5081 =for hackers
5082 Found in file sv.c
5083
5084 =item sv_copypv
5085 X<sv_copypv>
5086
5087 Copies a stringified representation of the source SV into the
5088 destination SV.  Automatically performs any necessary mg_get and
5089 coercion of numeric values into strings.  Guaranteed to preserve
5090 UTF-8 flag even from overloaded objects.  Similar in nature to
5091 sv_2pv[_flags] but operates directly on an SV instead of just the
5092 string.  Mostly uses sv_2pv_flags to do its work, except when that
5093 would lose the UTF-8'ness of the PV.
5094
5095         void    sv_copypv(SV* dsv, SV* ssv)
5096
5097 =for hackers
5098 Found in file sv.c
5099
5100 =item sv_dec
5101 X<sv_dec>
5102
5103 Auto-decrement of the value in the SV, doing string to numeric conversion
5104 if necessary. Handles 'get' magic.
5105
5106         void    sv_dec(SV* sv)
5107
5108 =for hackers
5109 Found in file sv.c
5110
5111 =item sv_eq
5112 X<sv_eq>
5113
5114 Returns a boolean indicating whether the strings in the two SVs are
5115 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5116 coerce its args to strings if necessary.
5117
5118         I32     sv_eq(SV* sv1, SV* sv2)
5119
5120 =for hackers
5121 Found in file sv.c
5122
5123 =item sv_force_normal_flags
5124 X<sv_force_normal_flags>
5125
5126 Undo various types of fakery on an SV: if the PV is a shared string, make
5127 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
5128 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
5129 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
5130 then a copy-on-write scalar drops its PV buffer (if any) and becomes
5131 SvPOK_off rather than making a copy. (Used where this scalar is about to be
5132 set to some other value.) In addition, the C<flags> parameter gets passed to
5133 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
5134 with flags set to 0.
5135
5136         void    sv_force_normal_flags(SV *sv, U32 flags)
5137
5138 =for hackers
5139 Found in file sv.c
5140
5141 =item sv_free
5142 X<sv_free>
5143
5144 Decrement an SV's reference count, and if it drops to zero, call
5145 C<sv_clear> to invoke destructors and free up any memory used by
5146 the body; finally, deallocate the SV's head itself.
5147 Normally called via a wrapper macro C<SvREFCNT_dec>.
5148
5149         void    sv_free(SV* sv)
5150
5151 =for hackers
5152 Found in file sv.c
5153
5154 =item sv_gets
5155 X<sv_gets>
5156
5157 Get a line from the filehandle and store it into the SV, optionally
5158 appending to the currently-stored string.
5159
5160         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
5161
5162 =for hackers
5163 Found in file sv.c
5164
5165 =item sv_grow
5166 X<sv_grow>
5167
5168 Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
5169 upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
5170 Use the C<SvGROW> wrapper instead.
5171
5172         char*   sv_grow(SV* sv, STRLEN newlen)
5173
5174 =for hackers
5175 Found in file sv.c
5176
5177 =item sv_inc
5178 X<sv_inc>
5179
5180 Auto-increment of the value in the SV, doing string to numeric conversion
5181 if necessary. Handles 'get' magic.
5182
5183         void    sv_inc(SV* sv)
5184
5185 =for hackers
5186 Found in file sv.c
5187
5188 =item sv_insert
5189 X<sv_insert>
5190
5191 Inserts a string at the specified offset/length within the SV. Similar to
5192 the Perl substr() function.
5193
5194         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
5195
5196 =for hackers
5197 Found in file sv.c
5198
5199 =item sv_isa
5200 X<sv_isa>
5201
5202 Returns a boolean indicating whether the SV is blessed into the specified
5203 class.  This does not check for subtypes; use C<sv_derived_from> to verify
5204 an inheritance relationship.
5205
5206         int     sv_isa(SV* sv, const char* name)
5207
5208 =for hackers
5209 Found in file sv.c
5210
5211 =item sv_isobject
5212 X<sv_isobject>
5213
5214 Returns a boolean indicating whether the SV is an RV pointing to a blessed
5215 object.  If the SV is not an RV, or if the object is not blessed, then this
5216 will return false.
5217
5218         int     sv_isobject(SV* sv)
5219
5220 =for hackers
5221 Found in file sv.c
5222
5223 =item sv_len
5224 X<sv_len>
5225
5226 Returns the length of the string in the SV. Handles magic and type
5227 coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
5228
5229         STRLEN  sv_len(SV* sv)
5230
5231 =for hackers
5232 Found in file sv.c
5233
5234 =item sv_len_utf8
5235 X<sv_len_utf8>
5236
5237 Returns the number of characters in the string in an SV, counting wide
5238 UTF-8 bytes as a single character. Handles magic and type coercion.
5239
5240         STRLEN  sv_len_utf8(SV* sv)
5241
5242 =for hackers
5243 Found in file sv.c
5244
5245 =item sv_magic
5246 X<sv_magic>
5247
5248 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
5249 then adds a new magic item of type C<how> to the head of the magic list.
5250
5251 See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
5252 handling of the C<name> and C<namlen> arguments.
5253
5254 You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
5255 to add more than one instance of the same 'how'.
5256
5257         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
5258
5259 =for hackers
5260 Found in file sv.c
5261
5262 =item sv_magicext
5263 X<sv_magicext>
5264
5265 Adds magic to an SV, upgrading it if necessary. Applies the
5266 supplied vtable and returns a pointer to the magic added.
5267
5268 Note that C<sv_magicext> will allow things that C<sv_magic> will not.
5269 In particular, you can add magic to SvREADONLY SVs, and add more than
5270 one instance of the same 'how'.
5271
5272 If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
5273 stored, if C<namlen> is zero then C<name> is stored as-is and - as another
5274 special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
5275 to contain an C<SV*> and is stored as-is with its REFCNT incremented.
5276
5277 (This is now used as a subroutine by C<sv_magic>.)
5278
5279         MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen)
5280
5281 =for hackers
5282 Found in file sv.c
5283
5284 =item sv_mortalcopy
5285 X<sv_mortalcopy>
5286
5287 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
5288 The new SV is marked as mortal. It will be destroyed "soon", either by an
5289 explicit call to FREETMPS, or by an implicit call at places such as
5290 statement boundaries.  See also C<sv_newmortal> and C<sv_2mortal>.
5291
5292         SV*     sv_mortalcopy(SV* oldsv)
5293
5294 =for hackers
5295 Found in file sv.c
5296
5297 =item sv_newmortal
5298 X<sv_newmortal>
5299
5300 Creates a new null SV which is mortal.  The reference count of the SV is
5301 set to 1. It will be destroyed "soon", either by an explicit call to
5302 FREETMPS, or by an implicit call at places such as statement boundaries.
5303 See also C<sv_mortalcopy> and C<sv_2mortal>.
5304
5305         SV*     sv_newmortal()
5306
5307 =for hackers
5308 Found in file sv.c
5309
5310 =item sv_newref
5311 X<sv_newref>
5312
5313 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
5314 instead.
5315
5316         SV*     sv_newref(SV* sv)
5317
5318 =for hackers
5319 Found in file sv.c
5320
5321 =item sv_pos_b2u
5322 X<sv_pos_b2u>
5323
5324 Converts the value pointed to by offsetp from a count of bytes from the
5325 start of the string, to a count of the equivalent number of UTF-8 chars.
5326 Handles magic and type coercion.
5327
5328         void    sv_pos_b2u(SV* sv, I32* offsetp)
5329
5330 =for hackers
5331 Found in file sv.c
5332
5333 =item sv_pos_u2b
5334 X<sv_pos_u2b>
5335
5336 Converts the value pointed to by offsetp from a count of UTF-8 chars from
5337 the start of the string, to a count of the equivalent number of bytes; if
5338 lenp is non-zero, it does the same to lenp, but this time starting from
5339 the offset, rather than from the start of the string. Handles magic and
5340 type coercion.
5341
5342         void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
5343
5344 =for hackers
5345 Found in file sv.c
5346
5347 =item sv_pvbyten_force
5348 X<sv_pvbyten_force>
5349
5350 The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
5351
5352         char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
5353
5354 =for hackers
5355 Found in file sv.c
5356
5357 =item sv_pvn_force
5358 X<sv_pvn_force>
5359
5360 Get a sensible string out of the SV somehow.
5361 A private implementation of the C<SvPV_force> macro for compilers which
5362 can't cope with complex macro expressions. Always use the macro instead.
5363
5364         char*   sv_pvn_force(SV* sv, STRLEN* lp)
5365
5366 =for hackers
5367 Found in file sv.c
5368
5369 =item sv_pvn_force_flags
5370 X<sv_pvn_force_flags>
5371
5372 Get a sensible string out of the SV somehow.
5373 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
5374 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
5375 implemented in terms of this function.
5376 You normally want to use the various wrapper macros instead: see
5377 C<SvPV_force> and C<SvPV_force_nomg>
5378
5379         char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
5380
5381 =for hackers
5382 Found in file sv.c
5383
5384 =item sv_pvutf8n_force
5385 X<sv_pvutf8n_force>
5386
5387 The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
5388
5389         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
5390
5391 =for hackers
5392 Found in file sv.c
5393
5394 =item sv_reftype
5395 X<sv_reftype>
5396
5397 Returns a string describing what the SV is a reference to.
5398
5399         char*   sv_reftype(const SV* sv, int ob)
5400
5401 =for hackers
5402 Found in file sv.c
5403
5404 =item sv_replace
5405 X<sv_replace>
5406
5407 Make the first argument a copy of the second, then delete the original.
5408 The target SV physically takes over ownership of the body of the source SV
5409 and inherits its flags; however, the target keeps any magic it owns,
5410 and any magic in the source is discarded.
5411 Note that this is a rather specialist SV copying operation; most of the
5412 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
5413
5414         void    sv_replace(SV* sv, SV* nsv)
5415
5416 =for hackers
5417 Found in file sv.c
5418
5419 =item sv_reset
5420 X<sv_reset>
5421
5422 Underlying implementation for the C<reset> Perl function.
5423 Note that the perl-level function is vaguely deprecated.
5424
5425         void    sv_reset(const char* s, HV* stash)
5426
5427 =for hackers
5428 Found in file sv.c
5429
5430 =item sv_rvweaken
5431 X<sv_rvweaken>
5432
5433 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
5434 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
5435 push a back-reference to this RV onto the array of backreferences
5436 associated with that magic.
5437
5438         SV*     sv_rvweaken(SV *sv)
5439
5440 =for hackers
5441 Found in file sv.c
5442
5443 =item sv_setiv
5444 X<sv_setiv>
5445
5446 Copies an integer into the given SV, upgrading first if necessary.
5447 Does not handle 'set' magic.  See also C<sv_setiv_mg>.
5448
5449         void    sv_setiv(SV* sv, IV num)
5450
5451 =for hackers
5452 Found in file sv.c
5453
5454 =item sv_setiv_mg
5455 X<sv_setiv_mg>
5456
5457 Like C<sv_setiv>, but also handles 'set' magic.
5458
5459         void    sv_setiv_mg(SV *sv, IV i)
5460
5461 =for hackers
5462 Found in file sv.c
5463
5464 =item sv_setnv
5465 X<sv_setnv>
5466
5467 Copies a double into the given SV, upgrading first if necessary.
5468 Does not handle 'set' magic.  See also C<sv_setnv_mg>.
5469
5470         void    sv_setnv(SV* sv, NV num)
5471
5472 =for hackers
5473 Found in file sv.c
5474
5475 =item sv_setnv_mg
5476 X<sv_setnv_mg>
5477
5478 Like C<sv_setnv>, but also handles 'set' magic.
5479
5480         void    sv_setnv_mg(SV *sv, NV num)
5481
5482 =for hackers
5483 Found in file sv.c
5484
5485 =item sv_setpv
5486 X<sv_setpv>
5487
5488 Copies a string into an SV.  The string must be null-terminated.  Does not
5489 handle 'set' magic.  See C<sv_setpv_mg>.
5490