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