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