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