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