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