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