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