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