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