Revert "show -E in error message when called with -E"
[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod
1 -*- buffer-read-only: t -*-
2
3 !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
4 This file is built by autodoc.pl extracting documentation from the C source
5 files.
6
7 =head1 NAME
8
9 perlapi - autogenerated documentation for the perl public API
10
11 =head1 DESCRIPTION
12 X<Perl API> X<API> X<api>
13
14 This file contains the documentation of the perl public API generated by
15 embed.pl, specifically a listing of functions, macros, flags, and variables
16 that may be used by extension writers.  The interfaces of any functions that
17 are not listed here are subject to change without notice.  For this reason,
18 blindly using functions listed in proto.h is to be avoided when writing
19 extensions.
20
21 Note that all Perl API global variables must be referenced with the C<PL_>
22 prefix.  Some macros are provided for compatibility with the older,
23 unadorned names, but this support may be disabled in a future release.
24
25 Perl was originally written to handle US-ASCII only (that is characters
26 whose ordinal numbers are in the range 0 - 127).
27 And documentation and comments may still use the term ASCII, when
28 sometimes in fact the entire range from 0 - 255 is meant.
29
30 Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
31 or ASCII.  Most of the documentation (and even comments in the code)
32 ignore the EBCDIC possibility.  
33 For almost all purposes the differences are transparent.
34 As an example, under EBCDIC,
35 instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
36 whenever this documentation refers to C<utf8>
37 (and variants of that name, including in function names),
38 it also (essentially transparently) means C<UTF-EBCDIC>.
39 But the ordinals of characters differ between ASCII, EBCDIC, and
40 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
41 than in UTF-8.
42
43 Also, on some EBCDIC machines, functions that are documented as operating on
44 US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
45 256 characters in the EBCDIC range, not just the subset corresponding to
46 US-ASCII.
47
48 The listing below is alphabetical, case insensitive.
49
50
51 =head1 "Gimme" Values
52
53 =over 8
54
55 =item GIMME
56 X<GIMME>
57
58 A backward-compatible version of C<GIMME_V> which can only return
59 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
60 Deprecated.  Use C<GIMME_V> instead.
61
62         U32     GIMME
63
64 =for hackers
65 Found in file op.h
66
67 =item GIMME_V
68 X<GIMME_V>
69
70 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
71 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
72 respectively.
73
74         U32     GIMME_V
75
76 =for hackers
77 Found in file op.h
78
79 =item G_ARRAY
80 X<G_ARRAY>
81
82 Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
83 L<perlcall>.
84
85 =for hackers
86 Found in file cop.h
87
88 =item G_DISCARD
89 X<G_DISCARD>
90
91 Indicates that arguments returned from a callback should be discarded.  See
92 L<perlcall>.
93
94 =for hackers
95 Found in file cop.h
96
97 =item G_EVAL
98 X<G_EVAL>
99
100 Used to force a Perl C<eval> wrapper around a callback.  See
101 L<perlcall>.
102
103 =for hackers
104 Found in file cop.h
105
106 =item G_NOARGS
107 X<G_NOARGS>
108
109 Indicates that no arguments are being sent to a callback.  See
110 L<perlcall>.
111
112 =for hackers
113 Found in file cop.h
114
115 =item G_SCALAR
116 X<G_SCALAR>
117
118 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
119 L<perlcall>.
120
121 =for hackers
122 Found in file cop.h
123
124 =item G_VOID
125 X<G_VOID>
126
127 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
128
129 =for hackers
130 Found in file cop.h
131
132
133 =back
134
135 =head1 Array Manipulation Functions
136
137 =over 8
138
139 =item AvFILL
140 X<AvFILL>
141
142 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
143
144         int     AvFILL(AV* av)
145
146 =for hackers
147 Found in file av.h
148
149 =item av_clear
150 X<av_clear>
151
152 Clears an array, making it empty.  Does not free the memory used by the
153 array itself.
154
155         void    av_clear(AV *av)
156
157 =for hackers
158 Found in file av.c
159
160 =item av_create_and_push
161 X<av_create_and_push>
162
163 Push an SV onto the end of the array, creating the array if necessary.
164 A small internal helper function to remove a commonly duplicated idiom.
165
166 NOTE: this function is experimental and may change or be
167 removed without notice.
168
169         void    av_create_and_push(AV **const avp, SV *const val)
170
171 =for hackers
172 Found in file av.c
173
174 =item av_create_and_unshift_one
175 X<av_create_and_unshift_one>
176
177 Unshifts an SV onto the beginning of the array, creating the array if
178 necessary.
179 A small internal helper function to remove a commonly duplicated idiom.
180
181 NOTE: this function is experimental and may change or be
182 removed without notice.
183
184         SV**    av_create_and_unshift_one(AV **const avp, SV *const val)
185
186 =for hackers
187 Found in file av.c
188
189 =item av_delete
190 X<av_delete>
191
192 Deletes the element indexed by C<key> from the array.  Returns the
193 deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
194 and null is returned.
195
196         SV*     av_delete(AV *av, I32 key, I32 flags)
197
198 =for hackers
199 Found in file av.c
200
201 =item av_exists
202 X<av_exists>
203
204 Returns true if the element indexed by C<key> has been initialized.
205
206 This relies on the fact that uninitialized array elements are set to
207 C<&PL_sv_undef>.
208
209         bool    av_exists(AV *av, I32 key)
210
211 =for hackers
212 Found in file av.c
213
214 =item av_extend
215 X<av_extend>
216
217 Pre-extend an array.  The C<key> is the index to which the array should be
218 extended.
219
220         void    av_extend(AV *av, I32 key)
221
222 =for hackers
223 Found in file av.c
224
225 =item av_fetch
226 X<av_fetch>
227
228 Returns the SV at the specified index in the array.  The C<key> is the
229 index.  If C<lval> is set then the fetch will be part of a store.  Check
230 that the return value is non-null before dereferencing it to a C<SV*>.
231
232 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
233 more information on how to use this function on tied arrays. 
234
235         SV**    av_fetch(AV *av, I32 key, I32 lval)
236
237 =for hackers
238 Found in file av.c
239
240 =item av_fill
241 X<av_fill>
242
243 Set the highest index in the array to the given number, equivalent to
244 Perl's C<$#array = $fill;>.
245
246 The number of elements in the an array will be C<fill + 1> after
247 av_fill() returns.  If the array was previously shorter then the
248 additional elements appended are set to C<PL_sv_undef>.  If the array
249 was longer, then the excess elements are freed.  C<av_fill(av, -1)> is
250 the same as C<av_clear(av)>.
251
252         void    av_fill(AV *av, I32 fill)
253
254 =for hackers
255 Found in file av.c
256
257 =item av_len
258 X<av_len>
259
260 Returns the highest index in the array.  The number of elements in the
261 array is C<av_len(av) + 1>.  Returns -1 if the array is empty.
262
263         I32     av_len(AV *av)
264
265 =for hackers
266 Found in file av.c
267
268 =item av_make
269 X<av_make>
270
271 Creates a new AV and populates it with a list of SVs.  The SVs are copied
272 into the array, so they may be freed after the call to av_make.  The new AV
273 will have a reference count of 1.
274
275         AV*     av_make(I32 size, SV **strp)
276
277 =for hackers
278 Found in file av.c
279
280 =item av_pop
281 X<av_pop>
282
283 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
284 is empty.
285
286         SV*     av_pop(AV *av)
287
288 =for hackers
289 Found in file av.c
290
291 =item av_push
292 X<av_push>
293
294 Pushes an SV onto the end of the array.  The array will grow automatically
295 to accommodate the addition.
296
297         void    av_push(AV *av, SV *val)
298
299 =for hackers
300 Found in file av.c
301
302 =item av_shift
303 X<av_shift>
304
305 Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the 
306 array is empty.
307
308         SV*     av_shift(AV *av)
309
310 =for hackers
311 Found in file av.c
312
313 =item av_store
314 X<av_store>
315
316 Stores an SV in an array.  The array index is specified as C<key>.  The
317 return value will be NULL if the operation failed or if the value did not
318 need to be actually stored within the array (as in the case of tied
319 arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
320 that the caller is responsible for suitably incrementing the reference
321 count of C<val> before the call, and decrementing it if the function
322 returned NULL.
323
324 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
325 more information on how to use this function on tied arrays.
326
327         SV**    av_store(AV *av, I32 key, SV *val)
328
329 =for hackers
330 Found in file av.c
331
332 =item av_undef
333 X<av_undef>
334
335 Undefines the array.  Frees the memory used by the array itself.
336
337         void    av_undef(AV *av)
338
339 =for hackers
340 Found in file av.c
341
342 =item av_unshift
343 X<av_unshift>
344
345 Unshift the given number of C<undef> values onto the beginning of the
346 array.  The array will grow automatically to accommodate the addition.  You
347 must then use C<av_store> to assign values to these new elements.
348
349         void    av_unshift(AV *av, I32 num)
350
351 =for hackers
352 Found in file av.c
353
354 =item get_av
355 X<get_av>
356
357 Returns the AV of the specified Perl array.  If C<create> is set and the
358 Perl variable does not exist then it will be created.  If C<create> is not
359 set and the variable does not exist then NULL is returned.
360
361 NOTE: the perl_ form of this function is deprecated.
362
363         AV*     get_av(const char* name, I32 create)
364
365 =for hackers
366 Found in file perl.c
367
368 =item newAV
369 X<newAV>
370
371 Creates a new AV.  The reference count is set to 1.
372
373         AV*     newAV()
374
375 =for hackers
376 Found in file av.h
377
378 =item sortsv
379 X<sortsv>
380
381 Sort an array. Here is an example:
382
383     sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
384
385 Currently this always uses mergesort. See sortsv_flags for a more
386 flexible routine.
387
388         void    sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
389
390 =for hackers
391 Found in file pp_sort.c
392
393 =item sortsv_flags
394 X<sortsv_flags>
395
396 Sort an array, with various options.
397
398         void    sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
399
400 =for hackers
401 Found in file pp_sort.c
402
403
404 =back
405
406 =head1 Callback Functions
407
408 =over 8
409
410 =item call_argv
411 X<call_argv>
412
413 Performs a callback to the specified Perl sub.  See L<perlcall>.
414
415 NOTE: the perl_ form of this function is deprecated.
416
417         I32     call_argv(const char* sub_name, I32 flags, char** argv)
418
419 =for hackers
420 Found in file perl.c
421
422 =item call_method
423 X<call_method>
424
425 Performs a callback to the specified Perl method.  The blessed object must
426 be on the stack.  See L<perlcall>.
427
428 NOTE: the perl_ form of this function is deprecated.
429
430         I32     call_method(const char* methname, I32 flags)
431
432 =for hackers
433 Found in file perl.c
434
435 =item call_pv
436 X<call_pv>
437
438 Performs a callback to the specified Perl sub.  See L<perlcall>.
439
440 NOTE: the perl_ form of this function is deprecated.
441
442         I32     call_pv(const char* sub_name, I32 flags)
443
444 =for hackers
445 Found in file perl.c
446
447 =item call_sv
448 X<call_sv>
449
450 Performs a callback to the Perl sub whose name is in the SV.  See
451 L<perlcall>.
452
453 NOTE: the perl_ form of this function is deprecated.
454
455         I32     call_sv(SV* sv, VOL I32 flags)
456
457 =for hackers
458 Found in file perl.c
459
460 =item ENTER
461 X<ENTER>
462
463 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
464
465                 ENTER;
466
467 =for hackers
468 Found in file scope.h
469
470 =item eval_pv
471 X<eval_pv>
472
473 Tells Perl to C<eval> the given string and return an SV* result.
474
475 NOTE: the perl_ form of this function is deprecated.
476
477         SV*     eval_pv(const char* p, I32 croak_on_error)
478
479 =for hackers
480 Found in file perl.c
481
482 =item eval_sv
483 X<eval_sv>
484
485 Tells Perl to C<eval> the string in the SV.
486
487 NOTE: the perl_ form of this function is deprecated.
488
489         I32     eval_sv(SV* sv, I32 flags)
490
491 =for hackers
492 Found in file perl.c
493
494 =item FREETMPS
495 X<FREETMPS>
496
497 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
498 L<perlcall>.
499
500                 FREETMPS;
501
502 =for hackers
503 Found in file scope.h
504
505 =item LEAVE
506 X<LEAVE>
507
508 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
509
510                 LEAVE;
511
512 =for hackers
513 Found in file scope.h
514
515 =item SAVETMPS
516 X<SAVETMPS>
517
518 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
519 L<perlcall>.
520
521                 SAVETMPS;
522
523 =for hackers
524 Found in file scope.h
525
526
527 =back
528
529 =head1 Character classes
530
531 =over 8
532
533 =item isALNUM
534 X<isALNUM>
535
536 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
537 alphanumeric character (including underscore) or digit.
538
539         bool    isALNUM(char ch)
540
541 =for hackers
542 Found in file handy.h
543
544 =item isALPHA
545 X<isALPHA>
546
547 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) 
548 alphabetic character.
549
550         bool    isALPHA(char ch)
551
552 =for hackers
553 Found in file handy.h
554
555 =item isDIGIT
556 X<isDIGIT>
557
558 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
559 digit.
560
561         bool    isDIGIT(char ch)
562
563 =for hackers
564 Found in file handy.h
565
566 =item isLOWER
567 X<isLOWER>
568
569 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
570 lowercase character.
571
572         bool    isLOWER(char ch)
573
574 =for hackers
575 Found in file handy.h
576
577 =item isSPACE
578 X<isSPACE>
579
580 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
581 whitespace.
582
583         bool    isSPACE(char ch)
584
585 =for hackers
586 Found in file handy.h
587
588 =item isUPPER
589 X<isUPPER>
590
591 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
592 uppercase character.
593
594         bool    isUPPER(char ch)
595
596 =for hackers
597 Found in file handy.h
598
599 =item toLOWER
600 X<toLOWER>
601
602 Converts the specified character to lowercase.  Characters outside the
603 US-ASCII (Basic Latin) range are viewed as not having any case.
604
605         char    toLOWER(char ch)
606
607 =for hackers
608 Found in file handy.h
609
610 =item toUPPER
611 X<toUPPER>
612
613 Converts the specified character to uppercase.  Characters outside the
614 US-ASCII (Basic Latin) range are viewed as not having any case.
615
616         char    toUPPER(char ch)
617
618 =for hackers
619 Found in file handy.h
620
621
622 =back
623
624 =head1 Cloning an interpreter
625
626 =over 8
627
628 =item perl_clone
629 X<perl_clone>
630
631 Create and return a new interpreter by cloning the current one.
632
633 perl_clone takes these flags as parameters:
634
635 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
636 without it we only clone the data and zero the stacks,
637 with it we copy the stacks and the new perl interpreter is
638 ready to run at the exact same point as the previous one.
639 The pseudo-fork code uses COPY_STACKS while the
640 threads->create doesn't.
641
642 CLONEf_KEEP_PTR_TABLE
643 perl_clone keeps a ptr_table with the pointer of the old
644 variable as a key and the new variable as a value,
645 this allows it to check if something has been cloned and not
646 clone it again but rather just use the value and increase the
647 refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
648 the ptr_table using the function
649 C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
650 reason to keep it around is if you want to dup some of your own
651 variable who are outside the graph perl scans, example of this
652 code is in threads.xs create
653
654 CLONEf_CLONE_HOST
655 This is a win32 thing, it is ignored on unix, it tells perls
656 win32host code (which is c++) to clone itself, this is needed on
657 win32 if you want to run two threads at the same time,
658 if you just want to do some stuff in a separate perl interpreter
659 and then throw it away and return to the original one,
660 you don't need to do anything.
661
662         PerlInterpreter*        perl_clone(PerlInterpreter *proto_perl, UV flags)
663
664 =for hackers
665 Found in file sv.c
666
667
668 =back
669
670 =head1 CV Manipulation Functions
671
672 =over 8
673
674 =item CvSTASH
675 X<CvSTASH>
676
677 Returns the stash of the CV.
678
679         HV*     CvSTASH(CV* cv)
680
681 =for hackers
682 Found in file cv.h
683
684 =item get_cv
685 X<get_cv>
686
687 Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
688
689 NOTE: the perl_ form of this function is deprecated.
690
691         CV*     get_cv(const char* name, I32 flags)
692
693 =for hackers
694 Found in file perl.c
695
696 =item get_cvn_flags
697 X<get_cvn_flags>
698
699 Returns the CV of the specified Perl subroutine.  C<flags> are passed to
700 C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
701 exist then it will be declared (which has the same effect as saying
702 C<sub name;>).  If C<GV_ADD> is not set and the subroutine does not exist
703 then NULL is returned.
704
705 NOTE: the perl_ form of this function is deprecated.
706
707         CV*     get_cvn_flags(const char* name, STRLEN len, I32 flags)
708
709 =for hackers
710 Found in file perl.c
711
712
713 =back
714
715 =head1 Embedding Functions
716
717 =over 8
718
719 =item cv_undef
720 X<cv_undef>
721
722 Clear out all the active components of a CV. This can happen either
723 by an explicit C<undef &foo>, or by the reference count going to zero.
724 In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
725 children can still follow the full lexical scope chain.
726
727         void    cv_undef(CV* cv)
728
729 =for hackers
730 Found in file op.c
731
732 =item load_module
733 X<load_module>
734
735 Loads the module whose name is pointed to by the string part of name.
736 Note that the actual module name, not its filename, should be given.
737 Eg, "Foo::Bar" instead of "Foo/Bar.pm".  flags can be any of
738 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
739 (or 0 for no flags). ver, if specified, provides version semantics
740 similar to C<use Foo::Bar VERSION>.  The optional trailing SV*
741 arguments can be used to specify arguments to the module's import()
742 method, similar to C<use Foo::Bar VERSION LIST>.
743
744         void    load_module(U32 flags, SV* name, SV* ver, ...)
745
746 =for hackers
747 Found in file op.c
748
749 =item nothreadhook
750 X<nothreadhook>
751
752 Stub that provides thread hook for perl_destruct when there are
753 no threads.
754
755         int     nothreadhook()
756
757 =for hackers
758 Found in file perl.c
759
760 =item perl_alloc
761 X<perl_alloc>
762
763 Allocates a new Perl interpreter.  See L<perlembed>.
764
765         PerlInterpreter*        perl_alloc()
766
767 =for hackers
768 Found in file perl.c
769
770 =item perl_construct
771 X<perl_construct>
772
773 Initializes a new Perl interpreter.  See L<perlembed>.
774
775         void    perl_construct(PerlInterpreter *my_perl)
776
777 =for hackers
778 Found in file perl.c
779
780 =item perl_destruct
781 X<perl_destruct>
782
783 Shuts down a Perl interpreter.  See L<perlembed>.
784
785         int     perl_destruct(PerlInterpreter *my_perl)
786
787 =for hackers
788 Found in file perl.c
789
790 =item perl_free
791 X<perl_free>
792
793 Releases a Perl interpreter.  See L<perlembed>.
794
795         void    perl_free(PerlInterpreter *my_perl)
796
797 =for hackers
798 Found in file perl.c
799
800 =item perl_parse
801 X<perl_parse>
802
803 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
804
805         int     perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)
806
807 =for hackers
808 Found in file perl.c
809
810 =item perl_run
811 X<perl_run>
812
813 Tells a Perl interpreter to run.  See L<perlembed>.
814
815         int     perl_run(PerlInterpreter *my_perl)
816
817 =for hackers
818 Found in file perl.c
819
820 =item require_pv
821 X<require_pv>
822
823 Tells Perl to C<require> the file named by the string argument.  It is
824 analogous to the Perl code C<eval "require '$file'">.  It's even
825 implemented that way; consider using load_module instead.
826
827 NOTE: the perl_ form of this function is deprecated.
828
829         void    require_pv(const char* pv)
830
831 =for hackers
832 Found in file perl.c
833
834
835 =back
836
837 =head1 Functions in file dump.c
838
839
840 =over 8
841
842 =item pv_display
843 X<pv_display>
844
845 Similar to
846
847   pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
848
849 except that an additional "\0" will be appended to the string when
850 len > cur and pv[cur] is "\0".
851
852 Note that the final string may be up to 7 chars longer than pvlim.
853
854         char*   pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
855
856 =for hackers
857 Found in file dump.c
858
859 =item pv_escape
860 X<pv_escape>
861
862 Escapes at most the first "count" chars of pv and puts the results into
863 dsv such that the size of the escaped string will not exceed "max" chars
864 and will not contain any incomplete escape sequences.
865
866 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
867 will also be escaped.
868
869 Normally the SV will be cleared before the escaped string is prepared,
870 but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
871
872 If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
873 if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
874 using C<is_utf8_string()> to determine if it is Unicode.
875
876 If PERL_PV_ESCAPE_ALL is set then all input chars will be output
877 using C<\x01F1> style escapes, otherwise only chars above 255 will be
878 escaped using this style, other non printable chars will use octal or
879 common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
880 then all chars below 255 will be treated as printable and 
881 will be output as literals.
882
883 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
884 string will be escaped, regardles of max. If the string is utf8 and 
885 the chars value is >255 then it will be returned as a plain hex 
886 sequence. Thus the output will either be a single char, 
887 an octal escape sequence, a special escape like C<\n> or a 3 or 
888 more digit hex value. 
889
890 If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
891 not a '\\'. This is because regexes very often contain backslashed
892 sequences, whereas '%' is not a particularly common character in patterns.
893
894 Returns a pointer to the escaped text as held by dsv.
895
896         char*   pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
897
898 =for hackers
899 Found in file dump.c
900
901 =item pv_pretty
902 X<pv_pretty>
903
904 Converts a string into something presentable, handling escaping via
905 pv_escape() and supporting quoting and ellipses.
906
907 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be 
908 double quoted with any double quotes in the string escaped. Otherwise
909 if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
910 angle brackets. 
911            
912 If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
913 string were output then an ellipsis C<...> will be appended to the
914 string. Note that this happens AFTER it has been quoted.
915            
916 If start_color is non-null then it will be inserted after the opening
917 quote (if there is one) but before the escaped text. If end_color
918 is non-null then it will be inserted after the escaped text but before
919 any quotes or ellipses.
920
921 Returns a pointer to the prettified text as held by dsv.
922            
923         char*   pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
924
925 =for hackers
926 Found in file dump.c
927
928
929 =back
930
931 =head1 Functions in file mathoms.c
932
933
934 =over 8
935
936 =item gv_fetchmethod
937 X<gv_fetchmethod>
938
939 See L<gv_fetchmethod_autoload>.
940
941         GV*     gv_fetchmethod(HV* stash, const char* name)
942
943 =for hackers
944 Found in file mathoms.c
945
946 =item pack_cat
947 X<pack_cat>
948
949 The engine implementing pack() Perl function. Note: parameters next_in_list and
950 flags are not used. This call should not be used; use packlist instead.
951
952         void    pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
953
954 =for hackers
955 Found in file mathoms.c
956
957 =item sv_2pvbyte_nolen
958 X<sv_2pvbyte_nolen>
959
960 Return a pointer to the byte-encoded representation of the SV.
961 May cause the SV to be downgraded from UTF-8 as a side-effect.
962
963 Usually accessed via the C<SvPVbyte_nolen> macro.
964
965         char*   sv_2pvbyte_nolen(SV* sv)
966
967 =for hackers
968 Found in file mathoms.c
969
970 =item sv_2pvutf8_nolen
971 X<sv_2pvutf8_nolen>
972
973 Return a pointer to the UTF-8-encoded representation of the SV.
974 May cause the SV to be upgraded to UTF-8 as a side-effect.
975
976 Usually accessed via the C<SvPVutf8_nolen> macro.
977
978         char*   sv_2pvutf8_nolen(SV* sv)
979
980 =for hackers
981 Found in file mathoms.c
982
983 =item sv_2pv_nolen
984 X<sv_2pv_nolen>
985
986 Like C<sv_2pv()>, but doesn't return the length too. You should usually
987 use the macro wrapper C<SvPV_nolen(sv)> instead.
988         char*   sv_2pv_nolen(SV* sv)
989
990 =for hackers
991 Found in file mathoms.c
992
993 =item sv_catpvn_mg
994 X<sv_catpvn_mg>
995
996 Like C<sv_catpvn>, but also handles 'set' magic.
997
998         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
999
1000 =for hackers
1001 Found in file mathoms.c
1002
1003 =item sv_catsv_mg
1004 X<sv_catsv_mg>
1005
1006 Like C<sv_catsv>, but also handles 'set' magic.
1007
1008         void    sv_catsv_mg(SV *dsv, SV *ssv)
1009
1010 =for hackers
1011 Found in file mathoms.c
1012
1013 =item sv_force_normal
1014 X<sv_force_normal>
1015
1016 Undo various types of fakery on an SV: if the PV is a shared string, make
1017 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
1018 an xpvmg. See also C<sv_force_normal_flags>.
1019
1020         void    sv_force_normal(SV *sv)
1021
1022 =for hackers
1023 Found in file mathoms.c
1024
1025 =item sv_iv
1026 X<sv_iv>
1027
1028 A private implementation of the C<SvIVx> macro for compilers which can't
1029 cope with complex macro expressions. Always use the macro instead.
1030
1031         IV      sv_iv(SV* sv)
1032
1033 =for hackers
1034 Found in file mathoms.c
1035
1036 =item sv_nolocking
1037 X<sv_nolocking>
1038
1039 Dummy routine which "locks" an SV when there is no locking module present.
1040 Exists to avoid test for a NULL function pointer and because it could
1041 potentially warn under some level of strict-ness.
1042
1043 "Superseded" by sv_nosharing().
1044
1045         void    sv_nolocking(SV *sv)
1046
1047 =for hackers
1048 Found in file mathoms.c
1049
1050 =item sv_nounlocking
1051 X<sv_nounlocking>
1052
1053 Dummy routine which "unlocks" an SV when there is no locking module present.
1054 Exists to avoid test for a NULL function pointer and because it could
1055 potentially warn under some level of strict-ness.
1056
1057 "Superseded" by sv_nosharing().
1058
1059         void    sv_nounlocking(SV *sv)
1060
1061 =for hackers
1062 Found in file mathoms.c
1063
1064 =item sv_nv
1065 X<sv_nv>
1066
1067 A private implementation of the C<SvNVx> macro for compilers which can't
1068 cope with complex macro expressions. Always use the macro instead.
1069
1070         NV      sv_nv(SV* sv)
1071
1072 =for hackers
1073 Found in file mathoms.c
1074
1075 =item sv_pv
1076 X<sv_pv>
1077
1078 Use the C<SvPV_nolen> macro instead
1079
1080         char*   sv_pv(SV *sv)
1081
1082 =for hackers
1083 Found in file mathoms.c
1084
1085 =item sv_pvbyte
1086 X<sv_pvbyte>
1087
1088 Use C<SvPVbyte_nolen> instead.
1089
1090         char*   sv_pvbyte(SV *sv)
1091
1092 =for hackers
1093 Found in file mathoms.c
1094
1095 =item sv_pvbyten
1096 X<sv_pvbyten>
1097
1098 A private implementation of the C<SvPVbyte> macro for compilers
1099 which can't cope with complex macro expressions. Always use the macro
1100 instead.
1101
1102         char*   sv_pvbyten(SV *sv, STRLEN *lp)
1103
1104 =for hackers
1105 Found in file mathoms.c
1106
1107 =item sv_pvn
1108 X<sv_pvn>
1109
1110 A private implementation of the C<SvPV> macro for compilers which can't
1111 cope with complex macro expressions. Always use the macro instead.
1112
1113         char*   sv_pvn(SV *sv, STRLEN *lp)
1114
1115 =for hackers
1116 Found in file mathoms.c
1117
1118 =item sv_pvutf8
1119 X<sv_pvutf8>
1120
1121 Use the C<SvPVutf8_nolen> macro instead
1122
1123         char*   sv_pvutf8(SV *sv)
1124
1125 =for hackers
1126 Found in file mathoms.c
1127
1128 =item sv_pvutf8n
1129 X<sv_pvutf8n>
1130
1131 A private implementation of the C<SvPVutf8> macro for compilers
1132 which can't cope with complex macro expressions. Always use the macro
1133 instead.
1134
1135         char*   sv_pvutf8n(SV *sv, STRLEN *lp)
1136
1137 =for hackers
1138 Found in file mathoms.c
1139
1140 =item sv_taint
1141 X<sv_taint>
1142
1143 Taint an SV. Use C<SvTAINTED_on> instead.
1144         void    sv_taint(SV* sv)
1145
1146 =for hackers
1147 Found in file mathoms.c
1148
1149 =item sv_unref
1150 X<sv_unref>
1151
1152 Unsets the RV status of the SV, and decrements the reference count of
1153 whatever was being referenced by the RV.  This can almost be thought of
1154 as a reversal of C<newSVrv>.  This is C<sv_unref_flags> with the C<flag>
1155 being zero.  See C<SvROK_off>.
1156
1157         void    sv_unref(SV* sv)
1158
1159 =for hackers
1160 Found in file mathoms.c
1161
1162 =item sv_usepvn
1163 X<sv_usepvn>
1164
1165 Tells an SV to use C<ptr> to find its string value. Implemented by
1166 calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
1167 magic. See C<sv_usepvn_flags>.
1168
1169         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
1170
1171 =for hackers
1172 Found in file mathoms.c
1173
1174 =item sv_usepvn_mg
1175 X<sv_usepvn_mg>
1176
1177 Like C<sv_usepvn>, but also handles 'set' magic.
1178
1179         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1180
1181 =for hackers
1182 Found in file mathoms.c
1183
1184 =item sv_uv
1185 X<sv_uv>
1186
1187 A private implementation of the C<SvUVx> macro for compilers which can't
1188 cope with complex macro expressions. Always use the macro instead.
1189
1190         UV      sv_uv(SV* sv)
1191
1192 =for hackers
1193 Found in file mathoms.c
1194
1195 =item unpack_str
1196 X<unpack_str>
1197
1198 The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
1199 and ocnt are not used. This call should not be used, use unpackstring instead.
1200
1201         I32     unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
1202
1203 =for hackers
1204 Found in file mathoms.c
1205
1206
1207 =back
1208
1209 =head1 Functions in file pp_ctl.c
1210
1211
1212 =over 8
1213
1214 =item find_runcv
1215 X<find_runcv>
1216
1217 Locate the CV corresponding to the currently executing sub or eval.
1218 If db_seqp is non_null, skip CVs that are in the DB package and populate
1219 *db_seqp with the cop sequence number at the point that the DB:: code was
1220 entered. (allows debuggers to eval in the scope of the breakpoint rather
1221 than in the scope of the debugger itself).
1222
1223         CV*     find_runcv(U32 *db_seqp)
1224
1225 =for hackers
1226 Found in file pp_ctl.c
1227
1228
1229 =back
1230
1231 =head1 Functions in file pp_pack.c
1232
1233
1234 =over 8
1235
1236 =item packlist
1237 X<packlist>
1238
1239 The engine implementing pack() Perl function.
1240
1241         void    packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
1242
1243 =for hackers
1244 Found in file pp_pack.c
1245
1246 =item unpackstring
1247 X<unpackstring>
1248
1249 The engine implementing unpack() Perl function. C<unpackstring> puts the
1250 extracted list items on the stack and returns the number of elements.
1251 Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
1252
1253         I32     unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
1254
1255 =for hackers
1256 Found in file pp_pack.c
1257
1258
1259 =back
1260
1261 =head1 Functions in file pp_sys.c
1262
1263
1264 =over 8
1265
1266 =item setdefout
1267 X<setdefout>
1268
1269 Sets PL_defoutgv, the default file handle for output, to the passed in
1270 typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference
1271 count of the passed in typeglob is increased by one, and the reference count
1272 of the typeglob that PL_defoutgv points to is decreased by one.
1273
1274         void    setdefout(GV* gv)
1275
1276 =for hackers
1277 Found in file pp_sys.c
1278
1279
1280 =back
1281
1282 =head1 GV Functions
1283
1284 =over 8
1285
1286 =item GvSV
1287 X<GvSV>
1288
1289 Return the SV from the GV.
1290
1291         SV*     GvSV(GV* gv)
1292
1293 =for hackers
1294 Found in file gv.h
1295
1296 =item gv_const_sv
1297 X<gv_const_sv>
1298
1299 If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1300 inlining, or C<gv> is a placeholder reference that would be promoted to such
1301 a typeglob, then returns the value returned by the sub.  Otherwise, returns
1302 NULL.
1303
1304         SV*     gv_const_sv(GV* gv)
1305
1306 =for hackers
1307 Found in file gv.c
1308
1309 =item gv_fetchmeth
1310 X<gv_fetchmeth>
1311
1312 Returns the glob with the given C<name> and a defined subroutine or
1313 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
1314 accessible via @ISA and UNIVERSAL::.
1315
1316 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
1317 side-effect creates a glob with the given C<name> in the given C<stash>
1318 which in the case of success contains an alias for the subroutine, and sets
1319 up caching info for this glob.
1320
1321 This function grants C<"SUPER"> token as a postfix of the stash name. The
1322 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1323 visible to Perl code.  So when calling C<call_sv>, you should not use
1324 the GV directly; instead, you should use the method's CV, which can be
1325 obtained from the GV with the C<GvCV> macro.
1326
1327         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1328
1329 =for hackers
1330 Found in file gv.c
1331
1332 =item gv_fetchmethod_autoload
1333 X<gv_fetchmethod_autoload>
1334
1335 Returns the glob which contains the subroutine to call to invoke the method
1336 on the C<stash>.  In fact in the presence of autoloading this may be the
1337 glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
1338 already setup.
1339
1340 The third parameter of C<gv_fetchmethod_autoload> determines whether
1341 AUTOLOAD lookup is performed if the given method is not present: non-zero
1342 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1343 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1344 with a non-zero C<autoload> parameter.
1345
1346 These functions grant C<"SUPER"> token as a prefix of the method name. Note
1347 that if you want to keep the returned glob for a long time, you need to
1348 check for it being "AUTOLOAD", since at the later time the call may load a
1349 different subroutine due to $AUTOLOAD changing its value. Use the glob
1350 created via a side effect to do this.
1351
1352 These functions have the same side-effects and as C<gv_fetchmeth> with
1353 C<level==0>.  C<name> should be writable if contains C<':'> or C<'
1354 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1355 C<call_sv> apply equally to these functions.
1356
1357         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1358
1359 =for hackers
1360 Found in file gv.c
1361
1362 =item gv_fetchmeth_autoload
1363 X<gv_fetchmeth_autoload>
1364
1365 Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1366 Returns a glob for the subroutine.
1367
1368 For an autoloaded subroutine without a GV, will create a GV even
1369 if C<level < 0>.  For an autoloaded subroutine without a stub, GvCV()
1370 of the result may be zero.
1371
1372         GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1373
1374 =for hackers
1375 Found in file gv.c
1376
1377 =item gv_stashpv
1378 X<gv_stashpv>
1379
1380 Returns a pointer to the stash for a specified package.  Uses C<strlen> to
1381 determine the length of C<name>, then calls C<gv_stashpvn()>.
1382
1383         HV*     gv_stashpv(const char* name, I32 flags)
1384
1385 =for hackers
1386 Found in file gv.c
1387
1388 =item gv_stashpvn
1389 X<gv_stashpvn>
1390
1391 Returns a pointer to the stash for a specified package.  The C<namelen>
1392 parameter indicates the length of the C<name>, in bytes.  C<flags> is passed
1393 to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
1394 created if it does not already exist.  If the package does not exist and
1395 C<flags> is 0 (or any other setting that does not create packages) then NULL
1396 is returned.
1397
1398
1399         HV*     gv_stashpvn(const char* name, U32 namelen, I32 flags)
1400
1401 =for hackers
1402 Found in file gv.c
1403
1404 =item gv_stashpvs
1405 X<gv_stashpvs>
1406
1407 Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1408
1409         HV*     gv_stashpvs(const char* name, I32 create)
1410
1411 =for hackers
1412 Found in file handy.h
1413
1414 =item gv_stashsv
1415 X<gv_stashsv>
1416
1417 Returns a pointer to the stash for a specified package.  See C<gv_stashpvn>.
1418
1419         HV*     gv_stashsv(SV* sv, I32 flags)
1420
1421 =for hackers
1422 Found in file gv.c
1423
1424
1425 =back
1426
1427 =head1 Handy Values
1428
1429 =over 8
1430
1431 =item Nullav
1432 X<Nullav>
1433
1434 Null AV pointer.
1435
1436 (deprecated - use C<(AV *)NULL> instead)
1437
1438 =for hackers
1439 Found in file av.h
1440
1441 =item Nullch
1442 X<Nullch>
1443
1444 Null character pointer. (No longer available when C<PERL_CORE> is defined.)
1445
1446 =for hackers
1447 Found in file handy.h
1448
1449 =item Nullcv
1450 X<Nullcv>
1451
1452 Null CV pointer.
1453
1454 (deprecated - use C<(CV *)NULL> instead)
1455
1456 =for hackers
1457 Found in file cv.h
1458
1459 =item Nullhv
1460 X<Nullhv>
1461
1462 Null HV pointer.
1463
1464 (deprecated - use C<(HV *)NULL> instead)
1465
1466 =for hackers
1467 Found in file hv.h
1468
1469 =item Nullsv
1470 X<Nullsv>
1471
1472 Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
1473
1474 =for hackers
1475 Found in file handy.h
1476
1477
1478 =back
1479
1480 =head1 Hash Manipulation Functions
1481
1482 =over 8
1483
1484 =item get_hv
1485 X<get_hv>
1486
1487 Returns the HV of the specified Perl hash.  If C<create> is set and the
1488 Perl variable does not exist then it will be created.  If C<create> is not
1489 set and the variable does not exist then NULL is returned.
1490
1491 NOTE: the perl_ form of this function is deprecated.
1492
1493         HV*     get_hv(const char* name, I32 create)
1494
1495 =for hackers
1496 Found in file perl.c
1497
1498 =item HEf_SVKEY
1499 X<HEf_SVKEY>
1500
1501 This flag, used in the length slot of hash entries and magic structures,
1502 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1503 is to be expected. (For information only--not to be used).
1504
1505 =for hackers
1506 Found in file hv.h
1507
1508 =item HeHASH
1509 X<HeHASH>
1510
1511 Returns the computed hash stored in the hash entry.
1512
1513         U32     HeHASH(HE* he)
1514
1515 =for hackers
1516 Found in file hv.h
1517
1518 =item HeKEY
1519 X<HeKEY>
1520
1521 Returns the actual pointer stored in the key slot of the hash entry. The
1522 pointer may be either C<char*> or C<SV*>, depending on the value of
1523 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
1524 usually preferable for finding the value of a key.
1525
1526         void*   HeKEY(HE* he)
1527
1528 =for hackers
1529 Found in file hv.h
1530
1531 =item HeKLEN
1532 X<HeKLEN>
1533
1534 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1535 holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
1536 be assigned to. The C<HePV()> macro is usually preferable for finding key
1537 lengths.
1538
1539         STRLEN  HeKLEN(HE* he)
1540
1541 =for hackers
1542 Found in file hv.h
1543
1544 =item HePV
1545 X<HePV>
1546
1547 Returns the key slot of the hash entry as a C<char*> value, doing any
1548 necessary dereferencing of possibly C<SV*> keys.  The length of the string
1549 is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
1550 not care about what the length of the key is, you may use the global
1551 variable C<PL_na>, though this is rather less efficient than using a local
1552 variable.  Remember though, that hash keys in perl are free to contain
1553 embedded nulls, so using C<strlen()> or similar is not a good way to find
1554 the length of hash keys. This is very similar to the C<SvPV()> macro
1555 described elsewhere in this document. See also C<HeUTF8>.
1556
1557 If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
1558 new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
1559 efficient.
1560
1561         char*   HePV(HE* he, STRLEN len)
1562
1563 =for hackers
1564 Found in file hv.h
1565
1566 =item HeSVKEY
1567 X<HeSVKEY>
1568
1569 Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
1570 contain an C<SV*> key.
1571
1572         SV*     HeSVKEY(HE* he)
1573
1574 =for hackers
1575 Found in file hv.h
1576
1577 =item HeSVKEY_force
1578 X<HeSVKEY_force>
1579
1580 Returns the key as an C<SV*>.  Will create and return a temporary mortal
1581 C<SV*> if the hash entry contains only a C<char*> key.
1582
1583         SV*     HeSVKEY_force(HE* he)
1584
1585 =for hackers
1586 Found in file hv.h
1587
1588 =item HeSVKEY_set
1589 X<HeSVKEY_set>
1590
1591 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1592 indicate the presence of an C<SV*> key, and returns the same
1593 C<SV*>.
1594
1595         SV*     HeSVKEY_set(HE* he, SV* sv)
1596
1597 =for hackers
1598 Found in file hv.h
1599
1600 =item HeUTF8
1601 X<HeUTF8>
1602
1603 Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
1604 doing any necessary dereferencing of possibly C<SV*> keys.  The value returned
1605 will be 0 or non-0, not necessarily 1 (or even a value with any low bits set),
1606 so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
1607 typedef for C<char>.
1608
1609         char*   HeUTF8(HE* he, STRLEN len)
1610
1611 =for hackers
1612 Found in file hv.h
1613
1614 =item HeVAL
1615 X<HeVAL>
1616
1617 Returns the value slot (type C<SV*>) stored in the hash entry.
1618
1619         SV*     HeVAL(HE* he)
1620
1621 =for hackers
1622 Found in file hv.h
1623
1624 =item HvNAME
1625 X<HvNAME>
1626
1627 Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1628 See C<SvSTASH>, C<CvSTASH>.
1629
1630         char*   HvNAME(HV* stash)
1631
1632 =for hackers
1633 Found in file hv.h
1634
1635 =item hv_assert
1636 X<hv_assert>
1637
1638 Check that a hash is in an internally consistent state.
1639
1640         void    hv_assert(HV *hv)
1641
1642 =for hackers
1643 Found in file hv.c
1644
1645 =item hv_clear
1646 X<hv_clear>
1647
1648 Clears a hash, making it empty.
1649
1650         void    hv_clear(HV *hv)
1651
1652 =for hackers
1653 Found in file hv.c
1654
1655 =item hv_clear_placeholders
1656 X<hv_clear_placeholders>
1657
1658 Clears any placeholders from a hash.  If a restricted hash has any of its keys
1659 marked as readonly and the key is subsequently deleted, the key is not actually
1660 deleted but is marked by assigning it a value of &PL_sv_placeholder.  This tags
1661 it so it will be ignored by future operations such as iterating over the hash,
1662 but will still allow the hash to have a value reassigned to the key at some
1663 future point.  This function clears any such placeholder keys from the hash.
1664 See Hash::Util::lock_keys() for an example of its use.
1665
1666         void    hv_clear_placeholders(HV *hv)
1667
1668 =for hackers
1669 Found in file hv.c
1670
1671 =item hv_delete
1672 X<hv_delete>
1673
1674 Deletes a key/value pair in the hash.  The value SV is removed from the
1675 hash and returned to the caller.  The C<klen> is the length of the key.
1676 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1677 will be returned.
1678
1679         SV*     hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
1680
1681 =for hackers
1682 Found in file hv.c
1683
1684 =item hv_delete_ent
1685 X<hv_delete_ent>
1686
1687 Deletes a key/value pair in the hash.  The value SV is removed from the
1688 hash and returned to the caller.  The C<flags> value will normally be zero;
1689 if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
1690 precomputed hash value, or 0 to ask for it to be computed.
1691
1692         SV*     hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
1693
1694 =for hackers
1695 Found in file hv.c
1696
1697 =item hv_exists
1698 X<hv_exists>
1699
1700 Returns a boolean indicating whether the specified hash key exists.  The
1701 C<klen> is the length of the key.
1702
1703         bool    hv_exists(HV *hv, const char *key, I32 klen)
1704
1705 =for hackers
1706 Found in file hv.c
1707
1708 =item hv_exists_ent
1709 X<hv_exists_ent>
1710
1711 Returns a boolean indicating whether the specified hash key exists. C<hash>
1712 can be a valid precomputed hash value, or 0 to ask for it to be
1713 computed.
1714
1715         bool    hv_exists_ent(HV *hv, SV *keysv, U32 hash)
1716
1717 =for hackers
1718 Found in file hv.c
1719
1720 =item hv_fetch
1721 X<hv_fetch>
1722
1723 Returns the SV which corresponds to the specified key in the hash.  The
1724 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
1725 part of a store.  Check that the return value is non-null before
1726 dereferencing it to an C<SV*>.
1727
1728 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1729 information on how to use this function on tied hashes.
1730
1731         SV**    hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
1732
1733 =for hackers
1734 Found in file hv.c
1735
1736 =item hv_fetchs
1737 X<hv_fetchs>
1738
1739 Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1740
1741         SV**    hv_fetchs(HV* tb, const char* key, I32 lval)
1742
1743 =for hackers
1744 Found in file handy.h
1745
1746 =item hv_fetch_ent
1747 X<hv_fetch_ent>
1748
1749 Returns the hash entry which corresponds to the specified key in the hash.
1750 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1751 if you want the function to compute it.  IF C<lval> is set then the fetch
1752 will be part of a store.  Make sure the return value is non-null before
1753 accessing it.  The return value when C<tb> is a tied hash is a pointer to a
1754 static location, so be sure to make a copy of the structure if you need to
1755 store it somewhere.
1756
1757 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1758 information on how to use this function on tied hashes.
1759
1760         HE*     hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
1761
1762 =for hackers
1763 Found in file hv.c
1764
1765 =item hv_iterinit
1766 X<hv_iterinit>
1767
1768 Prepares a starting point to traverse a hash table.  Returns the number of
1769 keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
1770 currently only meaningful for hashes without tie magic.
1771
1772 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1773 hash buckets that happen to be in use.  If you still need that esoteric
1774 value, you can get it through the macro C<HvFILL(tb)>.
1775
1776
1777         I32     hv_iterinit(HV *hv)
1778
1779 =for hackers
1780 Found in file hv.c
1781
1782 =item hv_iterkey
1783 X<hv_iterkey>
1784
1785 Returns the key from the current position of the hash iterator.  See
1786 C<hv_iterinit>.
1787
1788         char*   hv_iterkey(HE* entry, I32* retlen)
1789
1790 =for hackers
1791 Found in file hv.c
1792
1793 =item hv_iterkeysv
1794 X<hv_iterkeysv>
1795
1796 Returns the key as an C<SV*> from the current position of the hash
1797 iterator.  The return value will always be a mortal copy of the key.  Also
1798 see C<hv_iterinit>.
1799
1800         SV*     hv_iterkeysv(HE* entry)
1801
1802 =for hackers
1803 Found in file hv.c
1804
1805 =item hv_iternext
1806 X<hv_iternext>
1807
1808 Returns entries from a hash iterator.  See C<hv_iterinit>.
1809
1810 You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1811 iterator currently points to, without losing your place or invalidating your
1812 iterator.  Note that in this case the current entry is deleted from the hash
1813 with your iterator holding the last reference to it.  Your iterator is flagged
1814 to free the entry on the next call to C<hv_iternext>, so you must not discard
1815 your iterator immediately else the entry will leak - call C<hv_iternext> to
1816 trigger the resource deallocation.
1817
1818         HE*     hv_iternext(HV *hv)
1819
1820 =for hackers
1821 Found in file hv.c
1822
1823 =item hv_iternextsv
1824 X<hv_iternextsv>
1825
1826 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1827 operation.
1828
1829         SV*     hv_iternextsv(HV *hv, char **key, I32 *retlen)
1830
1831 =for hackers
1832 Found in file hv.c
1833
1834 =item hv_iternext_flags
1835 X<hv_iternext_flags>
1836
1837 Returns entries from a hash iterator.  See C<hv_iterinit> and C<hv_iternext>.
1838 The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1839 set the placeholders keys (for restricted hashes) will be returned in addition
1840 to normal keys. By default placeholders are automatically skipped over.
1841 Currently a placeholder is implemented with a value that is
1842 C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1843 restricted hashes may change, and the implementation currently is
1844 insufficiently abstracted for any change to be tidy.
1845
1846 NOTE: this function is experimental and may change or be
1847 removed without notice.
1848
1849         HE*     hv_iternext_flags(HV *hv, I32 flags)
1850
1851 =for hackers
1852 Found in file hv.c
1853
1854 =item hv_iterval
1855 X<hv_iterval>
1856
1857 Returns the value from the current position of the hash iterator.  See
1858 C<hv_iterkey>.
1859
1860         SV*     hv_iterval(HV *hv, HE *entry)
1861
1862 =for hackers
1863 Found in file hv.c
1864
1865 =item hv_magic
1866 X<hv_magic>
1867
1868 Adds magic to a hash.  See C<sv_magic>.
1869
1870         void    hv_magic(HV *hv, GV *gv, int how)
1871
1872 =for hackers
1873 Found in file hv.c
1874
1875 =item hv_scalar
1876 X<hv_scalar>
1877
1878 Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1879
1880         SV*     hv_scalar(HV *hv)
1881
1882 =for hackers
1883 Found in file hv.c
1884
1885 =item hv_store
1886 X<hv_store>
1887
1888 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
1889 the length of the key.  The C<hash> parameter is the precomputed hash
1890 value; if it is zero then Perl will compute it.  The return value will be
1891 NULL if the operation failed or if the value did not need to be actually
1892 stored within the hash (as in the case of tied hashes).  Otherwise it can
1893 be dereferenced to get the original C<SV*>.  Note that the caller is
1894 responsible for suitably incrementing the reference count of C<val> before
1895 the call, and decrementing it if the function returned NULL.  Effectively
1896 a successful hv_store takes ownership of one reference to C<val>.  This is
1897 usually what you want; a newly created SV has a reference count of one, so
1898 if all your code does is create SVs then store them in a hash, hv_store
1899 will own the only reference to the new SV, and your code doesn't need to do
1900 anything further to tidy up.  hv_store is not implemented as a call to
1901 hv_store_ent, and does not create a temporary SV for the key, so if your
1902 key data is not already in SV form then use hv_store in preference to
1903 hv_store_ent.
1904
1905 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1906 information on how to use this function on tied hashes.
1907
1908         SV**    hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash)
1909
1910 =for hackers
1911 Found in file hv.c
1912
1913 =item hv_stores
1914 X<hv_stores>
1915
1916 Like C<hv_store>, but takes a literal string instead of a string/length pair
1917 and omits the hash parameter.
1918
1919         SV**    hv_stores(HV* tb, const char* key, NULLOK SV* val)
1920
1921 =for hackers
1922 Found in file handy.h
1923
1924 =item hv_store_ent
1925 X<hv_store_ent>
1926
1927 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
1928 parameter is the precomputed hash value; if it is zero then Perl will
1929 compute it.  The return value is the new hash entry so created.  It will be
1930 NULL if the operation failed or if the value did not need to be actually
1931 stored within the hash (as in the case of tied hashes).  Otherwise the
1932 contents of the return value can be accessed using the C<He?> macros
1933 described here.  Note that the caller is responsible for suitably
1934 incrementing the reference count of C<val> before the call, and
1935 decrementing it if the function returned NULL.  Effectively a successful
1936 hv_store_ent takes ownership of one reference to C<val>.  This is
1937 usually what you want; a newly created SV has a reference count of one, so
1938 if all your code does is create SVs then store them in a hash, hv_store
1939 will own the only reference to the new SV, and your code doesn't need to do
1940 anything further to tidy up.  Note that hv_store_ent only reads the C<key>;
1941 unlike C<val> it does not take ownership of it, so maintaining the correct
1942 reference count on C<key> is entirely the caller's responsibility.  hv_store
1943 is not implemented as a call to hv_store_ent, and does not create a temporary
1944 SV for the key, so if your key data is not already in SV form then use
1945 hv_store in preference to hv_store_ent.
1946
1947 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1948 information on how to use this function on tied hashes.
1949
1950         HE*     hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
1951
1952 =for hackers
1953 Found in file hv.c
1954
1955 =item hv_undef
1956 X<hv_undef>
1957
1958 Undefines the hash.
1959
1960         void    hv_undef(HV *hv)
1961
1962 =for hackers
1963 Found in file hv.c
1964
1965 =item newHV
1966 X<newHV>
1967
1968 Creates a new HV.  The reference count is set to 1.
1969
1970         HV*     newHV()
1971
1972 =for hackers
1973 Found in file hv.h
1974
1975
1976 =back
1977
1978 =head1 Magical Functions
1979
1980 =over 8
1981
1982 =item mg_clear
1983 X<mg_clear>
1984
1985 Clear something magical that the SV represents.  See C<sv_magic>.
1986
1987         int     mg_clear(SV* sv)
1988
1989 =for hackers
1990 Found in file mg.c
1991
1992 =item mg_copy
1993 X<mg_copy>
1994
1995 Copies the magic from one SV to another.  See C<sv_magic>.
1996
1997         int     mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
1998
1999 =for hackers
2000 Found in file mg.c
2001
2002 =item mg_find
2003 X<mg_find>
2004
2005 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
2006
2007         MAGIC*  mg_find(const SV* sv, int type)
2008
2009 =for hackers
2010 Found in file mg.c
2011
2012 =item mg_free
2013 X<mg_free>
2014
2015 Free any magic storage used by the SV.  See C<sv_magic>.
2016
2017         int     mg_free(SV* sv)
2018
2019 =for hackers
2020 Found in file mg.c
2021
2022 =item mg_get
2023 X<mg_get>
2024
2025 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
2026
2027         int     mg_get(SV* sv)
2028
2029 =for hackers
2030 Found in file mg.c
2031
2032 =item mg_length
2033 X<mg_length>
2034
2035 Report on the SV's length.  See C<sv_magic>.
2036
2037         U32     mg_length(SV* sv)
2038
2039 =for hackers
2040 Found in file mg.c
2041
2042 =item mg_magical
2043 X<mg_magical>
2044
2045 Turns on the magical status of an SV.  See C<sv_magic>.
2046
2047         void    mg_magical(SV* sv)
2048
2049 =for hackers
2050 Found in file mg.c
2051
2052 =item mg_set
2053 X<mg_set>
2054
2055 Do magic after a value is assigned to the SV.  See C<sv_magic>.
2056
2057         int     mg_set(SV* sv)
2058
2059 =for hackers
2060 Found in file mg.c
2061
2062 =item SvGETMAGIC
2063 X<SvGETMAGIC>
2064
2065 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
2066 argument more than once.
2067
2068         void    SvGETMAGIC(SV* sv)
2069
2070 =for hackers
2071 Found in file sv.h
2072
2073 =item SvLOCK
2074 X<SvLOCK>
2075
2076 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
2077 has been loaded.
2078
2079         void    SvLOCK(SV* sv)
2080
2081 =for hackers
2082 Found in file sv.h
2083
2084 =item SvSETMAGIC
2085 X<SvSETMAGIC>
2086
2087 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
2088 argument more than once.
2089
2090         void    SvSETMAGIC(SV* sv)
2091
2092 =for hackers
2093 Found in file sv.h
2094
2095 =item SvSetMagicSV
2096 X<SvSetMagicSV>
2097
2098 Like C<SvSetSV>, but does any set magic required afterwards.
2099
2100         void    SvSetMagicSV(SV* dsb, SV* ssv)
2101
2102 =for hackers
2103 Found in file sv.h
2104
2105 =item SvSetMagicSV_nosteal
2106 X<SvSetMagicSV_nosteal>
2107
2108 Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
2109
2110         void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2111
2112 =for hackers
2113 Found in file sv.h
2114
2115 =item SvSetSV
2116 X<SvSetSV>
2117
2118 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
2119 more than once.
2120
2121         void    SvSetSV(SV* dsb, SV* ssv)
2122
2123 =for hackers
2124 Found in file sv.h
2125
2126 =item SvSetSV_nosteal
2127 X<SvSetSV_nosteal>
2128
2129 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2130 ssv. May evaluate arguments more than once.
2131
2132         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
2133
2134 =for hackers
2135 Found in file sv.h
2136
2137 =item SvSHARE
2138 X<SvSHARE>
2139
2140 Arranges for sv to be shared between threads if a suitable module
2141 has been loaded.
2142
2143         void    SvSHARE(SV* sv)
2144
2145 =for hackers
2146 Found in file sv.h
2147
2148 =item SvUNLOCK
2149 X<SvUNLOCK>
2150
2151 Releases a mutual exclusion lock on sv if a suitable module
2152 has been loaded.
2153
2154         void    SvUNLOCK(SV* sv)
2155
2156 =for hackers
2157 Found in file sv.h
2158
2159
2160 =back
2161
2162 =head1 Memory Management
2163
2164 =over 8
2165
2166 =item Copy
2167 X<Copy>
2168
2169 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
2170 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2171 the type.  May fail on overlapping copies.  See also C<Move>.
2172
2173         void    Copy(void* src, void* dest, int nitems, type)
2174
2175 =for hackers
2176 Found in file handy.h
2177
2178 =item CopyD
2179 X<CopyD>
2180
2181 Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2182 optimise.
2183
2184         void *  CopyD(void* src, void* dest, int nitems, type)
2185
2186 =for hackers
2187 Found in file handy.h
2188
2189 =item Move
2190 X<Move>
2191
2192 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
2193 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2194 the type.  Can do overlapping moves.  See also C<Copy>.
2195
2196         void    Move(void* src, void* dest, int nitems, type)
2197
2198 =for hackers
2199 Found in file handy.h
2200
2201 =item MoveD
2202 X<MoveD>
2203
2204 Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2205 optimise.
2206
2207         void *  MoveD(void* src, void* dest, int nitems, type)
2208
2209 =for hackers
2210 Found in file handy.h
2211
2212 =item Newx
2213 X<Newx>
2214
2215 The XSUB-writer's interface to the C C<malloc> function.
2216
2217 In 5.9.3, Newx() and friends replace the older New() API, and drops
2218 the first parameter, I<x>, a debug aid which allowed callers to identify
2219 themselves.  This aid has been superseded by a new build option,
2220 PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>).  The older API is still
2221 there for use in XS modules supporting older perls.
2222
2223         void    Newx(void* ptr, int nitems, type)
2224
2225 =for hackers
2226 Found in file handy.h
2227
2228 =item Newxc
2229 X<Newxc>
2230
2231 The XSUB-writer's interface to the C C<malloc> function, with
2232 cast.  See also C<Newx>.
2233
2234         void    Newxc(void* ptr, int nitems, type, cast)
2235
2236 =for hackers
2237 Found in file handy.h
2238
2239 =item Newxz
2240 X<Newxz>
2241
2242 The XSUB-writer's interface to the C C<malloc> function.  The allocated
2243 memory is zeroed with C<memzero>.  See also C<Newx>.
2244
2245         void    Newxz(void* ptr, int nitems, type)
2246
2247 =for hackers
2248 Found in file handy.h
2249
2250 =item Poison
2251 X<Poison>
2252
2253 PoisonWith(0xEF) for catching access to freed memory.
2254
2255         void    Poison(void* dest, int nitems, type)
2256
2257 =for hackers
2258 Found in file handy.h
2259
2260 =item PoisonFree
2261 X<PoisonFree>
2262
2263 PoisonWith(0xEF) for catching access to freed memory.
2264
2265         void    PoisonFree(void* dest, int nitems, type)
2266
2267 =for hackers
2268 Found in file handy.h
2269
2270 =item PoisonNew
2271 X<PoisonNew>
2272
2273 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2274
2275         void    PoisonNew(void* dest, int nitems, type)
2276
2277 =for hackers
2278 Found in file handy.h
2279
2280 =item PoisonWith
2281 X<PoisonWith>
2282
2283 Fill up memory with a byte pattern (a byte repeated over and over
2284 again) that hopefully catches attempts to access uninitialized memory.
2285
2286         void    PoisonWith(void* dest, int nitems, type, U8 byte)
2287
2288 =for hackers
2289 Found in file handy.h
2290
2291 =item Renew
2292 X<Renew>
2293
2294 The XSUB-writer's interface to the C C<realloc> function.
2295
2296         void    Renew(void* ptr, int nitems, type)
2297
2298 =for hackers
2299 Found in file handy.h
2300
2301 =item Renewc
2302 X<Renewc>
2303
2304 The XSUB-writer's interface to the C C<realloc> function, with
2305 cast.
2306
2307         void    Renewc(void* ptr, int nitems, type, cast)
2308
2309 =for hackers
2310 Found in file handy.h
2311
2312 =item Safefree
2313 X<Safefree>
2314
2315 The XSUB-writer's interface to the C C<free> function.
2316
2317         void    Safefree(void* ptr)
2318
2319 =for hackers
2320 Found in file handy.h
2321
2322 =item savepv
2323 X<savepv>
2324
2325 Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2326 string which is a duplicate of C<pv>. The size of the string is
2327 determined by C<strlen()>. The memory allocated for the new string can
2328 be freed with the C<Safefree()> function.
2329
2330         char*   savepv(const char* pv)
2331
2332 =for hackers
2333 Found in file util.c
2334
2335 =item savepvn
2336 X<savepvn>
2337
2338 Perl's version of what C<strndup()> would be if it existed. Returns a
2339 pointer to a newly allocated string which is a duplicate of the first
2340 C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2341 the new string can be freed with the C<Safefree()> function.
2342
2343         char*   savepvn(const char* pv, I32 len)
2344
2345 =for hackers
2346 Found in file util.c
2347
2348 =item savepvs
2349 X<savepvs>
2350
2351 Like C<savepvn>, but takes a literal string instead of a string/length pair.
2352
2353         char*   savepvs(const char* s)
2354
2355 =for hackers
2356 Found in file handy.h
2357
2358 =item savesharedpv
2359 X<savesharedpv>
2360
2361 A version of C<savepv()> which allocates the duplicate string in memory
2362 which is shared between threads.
2363
2364         char*   savesharedpv(const char* pv)
2365
2366 =for hackers
2367 Found in file util.c
2368
2369 =item savesharedpvn
2370 X<savesharedpvn>
2371
2372 A version of C<savepvn()> which allocates the duplicate string in memory
2373 which is shared between threads. (With the specific difference that a NULL
2374 pointer is not acceptable)
2375
2376         char*   savesharedpvn(const char *const pv, const STRLEN len)
2377
2378 =for hackers
2379 Found in file util.c
2380
2381 =item savesvpv
2382 X<savesvpv>
2383
2384 A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
2385 the passed in SV using C<SvPV()>
2386
2387         char*   savesvpv(SV* sv)
2388
2389 =for hackers
2390 Found in file util.c
2391
2392 =item StructCopy
2393 X<StructCopy>
2394
2395 This is an architecture-independent macro to copy one structure to another.
2396
2397         void    StructCopy(type src, type dest, type)
2398
2399 =for hackers
2400 Found in file handy.h
2401
2402 =item Zero
2403 X<Zero>
2404
2405 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2406 destination, C<nitems> is the number of items, and C<type> is the type.
2407
2408         void    Zero(void* dest, int nitems, type)
2409
2410 =for hackers
2411 Found in file handy.h
2412
2413 =item ZeroD
2414 X<ZeroD>
2415
2416 Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2417 optimise.
2418
2419         void *  ZeroD(void* dest, int nitems, type)
2420
2421 =for hackers
2422 Found in file handy.h
2423
2424
2425 =back
2426
2427 =head1 Miscellaneous Functions
2428
2429 =over 8
2430
2431 =item fbm_compile
2432 X<fbm_compile>
2433
2434 Analyses the string in order to make fast searches on it using fbm_instr()
2435 -- the Boyer-Moore algorithm.
2436
2437         void    fbm_compile(SV* sv, U32 flags)
2438
2439 =for hackers
2440 Found in file util.c
2441
2442 =item fbm_instr
2443 X<fbm_instr>
2444
2445 Returns the location of the SV in the string delimited by C<str> and
2446 C<strend>.  It returns C<NULL> if the string can't be found.  The C<sv>
2447 does not have to be fbm_compiled, but the search will not be as fast
2448 then.
2449
2450         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)
2451
2452 =for hackers
2453 Found in file util.c
2454
2455 =item form
2456 X<form>
2457
2458 Takes a sprintf-style format pattern and conventional
2459 (non-SV) arguments and returns the formatted string.
2460
2461     (char *) Perl_form(pTHX_ const char* pat, ...)
2462
2463 can be used any place a string (char *) is required:
2464
2465     char * s = Perl_form("%d.%d",major,minor);
2466
2467 Uses a single private buffer so if you want to format several strings you
2468 must explicitly copy the earlier strings away (and free the copies when you
2469 are done).
2470
2471         char*   form(const char* pat, ...)
2472
2473 =for hackers
2474 Found in file util.c
2475
2476 =item getcwd_sv
2477 X<getcwd_sv>
2478
2479 Fill the sv with current working directory
2480
2481         int     getcwd_sv(SV* sv)
2482
2483 =for hackers
2484 Found in file util.c
2485
2486 =item my_snprintf
2487 X<my_snprintf>
2488
2489 The C library C<snprintf> functionality, if available and
2490 standards-compliant (uses C<vsnprintf>, actually).  However, if the
2491 C<vsnprintf> is not available, will unfortunately use the unsafe
2492 C<vsprintf> which can overrun the buffer (there is an overrun check,
2493 but that may be too late).  Consider using C<sv_vcatpvf> instead, or
2494 getting C<vsnprintf>.
2495
2496         int     my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2497
2498 =for hackers
2499 Found in file util.c
2500
2501 =item my_sprintf
2502 X<my_sprintf>
2503
2504 The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2505 the length of the string written to the buffer. Only rare pre-ANSI systems
2506 need the wrapper function - usually this is a direct call to C<sprintf>.
2507
2508         int     my_sprintf(char *buffer, const char *pat, ...)
2509
2510 =for hackers
2511 Found in file util.c
2512
2513 =item my_vsnprintf
2514 X<my_vsnprintf>
2515
2516 The C library C<vsnprintf> if available and standards-compliant.
2517 However, if if the C<vsnprintf> is not available, will unfortunately
2518 use the unsafe C<vsprintf> which can overrun the buffer (there is an
2519 overrun check, but that may be too late).  Consider using
2520 C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2521
2522         int     my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2523
2524 =for hackers
2525 Found in file util.c
2526
2527 =item new_version
2528 X<new_version>
2529
2530 Returns a new version object based on the passed in SV:
2531
2532     SV *sv = new_version(SV *ver);
2533
2534 Does not alter the passed in ver SV.  See "upg_version" if you
2535 want to upgrade the SV.
2536
2537         SV*     new_version(SV *ver)
2538
2539 =for hackers
2540 Found in file util.c
2541
2542 =item scan_version
2543 X<scan_version>
2544
2545 Returns a pointer to the next character after the parsed
2546 version string, as well as upgrading the passed in SV to
2547 an RV.
2548
2549 Function must be called with an already existing SV like
2550
2551     sv = newSV(0);
2552     s = scan_version(s, SV *sv, bool qv);
2553
2554 Performs some preprocessing to the string to ensure that
2555 it has the correct characteristics of a version.  Flags the
2556 object if it contains an underscore (which denotes this
2557 is an alpha version).  The boolean qv denotes that the version
2558 should be interpreted as if it had multiple decimals, even if
2559 it doesn't.
2560
2561         const char*     scan_version(const char *s, SV *rv, bool qv)
2562
2563 =for hackers
2564 Found in file util.c
2565
2566 =item strEQ
2567 X<strEQ>
2568
2569 Test two strings to see if they are equal.  Returns true or false.
2570
2571         bool    strEQ(char* s1, char* s2)
2572
2573 =for hackers
2574 Found in file handy.h
2575
2576 =item strGE
2577 X<strGE>
2578
2579 Test two strings to see if the first, C<s1>, is greater than or equal to
2580 the second, C<s2>.  Returns true or false.
2581
2582         bool    strGE(char* s1, char* s2)
2583
2584 =for hackers
2585 Found in file handy.h
2586
2587 =item strGT
2588 X<strGT>
2589
2590 Test two strings to see if the first, C<s1>, is greater than the second,
2591 C<s2>.  Returns true or false.
2592
2593         bool    strGT(char* s1, char* s2)
2594
2595 =for hackers
2596 Found in file handy.h
2597
2598 =item strLE
2599 X<strLE>
2600
2601 Test two strings to see if the first, C<s1>, is less than or equal to the
2602 second, C<s2>.  Returns true or false.
2603
2604         bool    strLE(char* s1, char* s2)
2605
2606 =for hackers
2607 Found in file handy.h
2608
2609 =item strLT
2610 X<strLT>
2611
2612 Test two strings to see if the first, C<s1>, is less than the second,
2613 C<s2>.  Returns true or false.
2614
2615         bool    strLT(char* s1, char* s2)
2616
2617 =for hackers
2618 Found in file handy.h
2619
2620 =item strNE
2621 X<strNE>
2622
2623 Test two strings to see if they are different.  Returns true or
2624 false.
2625
2626         bool    strNE(char* s1, char* s2)
2627
2628 =for hackers
2629 Found in file handy.h
2630
2631 =item strnEQ
2632 X<strnEQ>
2633
2634 Test two strings to see if they are equal.  The C<len> parameter indicates
2635 the number of bytes to compare.  Returns true or false. (A wrapper for
2636 C<strncmp>).
2637
2638         bool    strnEQ(char* s1, char* s2, STRLEN len)
2639
2640 =for hackers
2641 Found in file handy.h
2642
2643 =item strnNE
2644 X<strnNE>
2645
2646 Test two strings to see if they are different.  The C<len> parameter
2647 indicates the number of bytes to compare.  Returns true or false. (A
2648 wrapper for C<strncmp>).
2649
2650         bool    strnNE(char* s1, char* s2, STRLEN len)
2651
2652 =for hackers
2653 Found in file handy.h
2654
2655 =item sv_destroyable
2656 X<sv_destroyable>
2657
2658 Dummy routine which reports that object can be destroyed when there is no
2659 sharing module present.  It ignores its single SV argument, and returns
2660 'true'.  Exists to avoid test for a NULL function pointer and because it
2661 could potentially warn under some level of strict-ness.
2662
2663         bool    sv_destroyable(SV *sv)
2664
2665 =for hackers
2666 Found in file util.c
2667
2668 =item sv_nosharing
2669 X<sv_nosharing>
2670
2671 Dummy routine which "shares" an SV when there is no sharing module present.
2672 Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2673 Exists to avoid test for a NULL function pointer and because it could
2674 potentially warn under some level of strict-ness.
2675
2676         void    sv_nosharing(SV *sv)
2677
2678 =for hackers
2679 Found in file util.c
2680
2681 =item upg_version
2682 X<upg_version>
2683
2684 In-place upgrade of the supplied SV to a version object.
2685
2686     SV *sv = upg_version(SV *sv, bool qv);
2687
2688 Returns a pointer to the upgraded SV.  Set the boolean qv if you want
2689 to force this SV to be interpreted as an "extended" version.
2690
2691         SV*     upg_version(SV *ver, bool qv)
2692
2693 =for hackers
2694 Found in file util.c
2695
2696 =item vcmp
2697 X<vcmp>
2698
2699 Version object aware cmp.  Both operands must already have been 
2700 converted into version objects.
2701
2702         int     vcmp(SV *lhv, SV *rhv)
2703
2704 =for hackers
2705 Found in file util.c
2706
2707 =item vnormal
2708 X<vnormal>
2709
2710 Accepts a version object and returns the normalized string
2711 representation.  Call like:
2712
2713     sv = vnormal(rv);
2714
2715 NOTE: you can pass either the object directly or the SV
2716 contained within the RV.
2717
2718         SV*     vnormal(SV *vs)
2719
2720 =for hackers
2721 Found in file util.c
2722
2723 =item vnumify
2724 X<vnumify>
2725
2726 Accepts a version object and returns the normalized floating
2727 point representation.  Call like:
2728
2729     sv = vnumify(rv);
2730
2731 NOTE: you can pass either the object directly or the SV
2732 contained within the RV.
2733
2734         SV*     vnumify(SV *vs)
2735
2736 =for hackers
2737 Found in file util.c
2738
2739 =item vstringify
2740 X<vstringify>
2741
2742 In order to maintain maximum compatibility with earlier versions
2743 of Perl, this function will return either the floating point
2744 notation or the multiple dotted notation, depending on whether
2745 the original version contained 1 or more dots, respectively
2746
2747         SV*     vstringify(SV *vs)
2748
2749 =for hackers
2750 Found in file util.c
2751
2752 =item vverify
2753 X<vverify>
2754
2755 Validates that the SV contains a valid version object.
2756
2757     bool vverify(SV *vobj);
2758
2759 Note that it only confirms the bare minimum structure (so as not to get
2760 confused by derived classes which may contain additional hash entries):
2761
2762         bool    vverify(SV *vs)
2763
2764 =for hackers
2765 Found in file util.c
2766
2767
2768 =back
2769
2770 =head1 MRO Functions
2771
2772 =over 8
2773
2774 =item mro_get_linear_isa
2775 X<mro_get_linear_isa>
2776
2777 Returns either C<mro_get_linear_isa_c3> or
2778 C<mro_get_linear_isa_dfs> for the given stash,
2779 dependant upon which MRO is in effect
2780 for that stash.  The return value is a
2781 read-only AV*.
2782
2783 You are responsible for C<SvREFCNT_inc()> on the
2784 return value if you plan to store it anywhere
2785 semi-permanently (otherwise it might be deleted
2786 out from under you the next time the cache is
2787 invalidated).
2788
2789         AV*     mro_get_linear_isa(HV* stash)
2790
2791 =for hackers
2792 Found in file mro.c
2793
2794 =item mro_method_changed_in
2795 X<mro_method_changed_in>
2796
2797 Invalidates method caching on any child classes
2798 of the given stash, so that they might notice
2799 the changes in this one.
2800
2801 Ideally, all instances of C<PL_sub_generation++> in
2802 perl source outside of C<mro.c> should be
2803 replaced by calls to this.
2804
2805 Perl automatically handles most of the common
2806 ways a method might be redefined.  However, there
2807 are a few ways you could change a method in a stash
2808 without the cache code noticing, in which case you
2809 need to call this method afterwards:
2810
2811 1) Directly manipulating the stash HV entries from
2812 XS code.
2813
2814 2) Assigning a reference to a readonly scalar
2815 constant into a stash entry in order to create
2816 a constant subroutine (like constant.pm
2817 does).
2818
2819 This same method is available from pure perl
2820 via, C<mro::method_changed_in(classname)>.
2821
2822         void    mro_method_changed_in(HV* stash)
2823
2824 =for hackers
2825 Found in file mro.c
2826
2827
2828 =back
2829
2830 =head1 Multicall Functions
2831
2832 =over 8
2833
2834 =item dMULTICALL
2835 X<dMULTICALL>
2836
2837 Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2838
2839                 dMULTICALL;
2840
2841 =for hackers
2842 Found in file cop.h
2843
2844 =item MULTICALL
2845 X<MULTICALL>
2846
2847 Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2848
2849                 MULTICALL;
2850
2851 =for hackers
2852 Found in file cop.h
2853
2854 =item POP_MULTICALL
2855 X<POP_MULTICALL>
2856
2857 Closing bracket for a lightweight callback.
2858 See L<perlcall/Lightweight Callbacks>.
2859
2860                 POP_MULTICALL;
2861
2862 =for hackers
2863 Found in file cop.h
2864
2865 =item PUSH_MULTICALL
2866 X<PUSH_MULTICALL>
2867
2868 Opening bracket for a lightweight callback.
2869 See L<perlcall/Lightweight Callbacks>.
2870
2871                 PUSH_MULTICALL;
2872
2873 =for hackers
2874 Found in file cop.h
2875
2876
2877 =back
2878
2879 =head1 Numeric functions
2880
2881 =over 8
2882
2883 =item grok_bin
2884 X<grok_bin>
2885
2886 converts a string representing a binary number to numeric form.
2887
2888 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2889 conversion flags, and I<result> should be NULL or a pointer to an NV.
2890 The scan stops at the end of the string, or the first invalid character.
2891 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2892 invalid character will also trigger a warning.
2893 On return I<*len> is set to the length of the scanned string,
2894 and I<*flags> gives output flags.
2895
2896 If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2897 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2898 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2899 and writes the value to I<*result> (or the value is discarded if I<result>
2900 is NULL).
2901
2902 The binary number may optionally be prefixed with "0b" or "b" unless
2903 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2904 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2905 number may use '_' characters to separate digits.
2906
2907         UV      grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2908
2909 =for hackers
2910 Found in file numeric.c
2911
2912 =item grok_hex
2913 X<grok_hex>
2914
2915 converts a string representing a hex number to numeric form.
2916
2917 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2918 conversion flags, and I<result> should be NULL or a pointer to an NV.
2919 The scan stops at the end of the string, or the first invalid character.
2920 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2921 invalid character will also trigger a warning.
2922 On return I<*len> is set to the length of the scanned string,
2923 and I<*flags> gives output flags.
2924
2925 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2926 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2927 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2928 and writes the value to I<*result> (or the value is discarded if I<result>
2929 is NULL).
2930
2931 The hex number may optionally be prefixed with "0x" or "x" unless
2932 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2933 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2934 number may use '_' characters to separate digits.
2935
2936         UV      grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2937
2938 =for hackers
2939 Found in file numeric.c
2940
2941 =item grok_number
2942 X<grok_number>
2943
2944 Recognise (or not) a number.  The type of the number is returned
2945 (0 if unrecognised), otherwise it is a bit-ORed combination of
2946 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2947 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2948
2949 If the value of the number can fit an in UV, it is returned in the *valuep
2950 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2951 will never be set unless *valuep is valid, but *valuep may have been assigned
2952 to during processing even though IS_NUMBER_IN_UV is not set on return.
2953 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2954 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2955
2956 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2957 seen (in which case *valuep gives the true value truncated to an integer), and
2958 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2959 absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
2960 number is larger than a UV.
2961
2962         int     grok_number(const char *pv, STRLEN len, UV *valuep)
2963
2964 =for hackers
2965 Found in file numeric.c
2966
2967 =item grok_numeric_radix
2968 X<grok_numeric_radix>
2969
2970 Scan and skip for a numeric decimal separator (radix).
2971
2972         bool    grok_numeric_radix(const char **sp, const char *send)
2973
2974 =for hackers
2975 Found in file numeric.c
2976
2977 =item grok_oct
2978 X<grok_oct>
2979
2980 converts a string representing an octal number to numeric form.
2981
2982 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2983 conversion flags, and I<result> should be NULL or a pointer to an NV.
2984 The scan stops at the end of the string, or the first invalid character.
2985 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2986 invalid character will also trigger a warning.
2987 On return I<*len> is set to the length of the scanned string,
2988 and I<*flags> gives output flags.
2989
2990 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2991 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2992 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2993 and writes the value to I<*result> (or the value is discarded if I<result>
2994 is NULL).
2995
2996 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2997 number may use '_' characters to separate digits.
2998
2999         UV      grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
3000
3001 =for hackers
3002 Found in file numeric.c
3003
3004 =item Perl_signbit
3005 X<Perl_signbit>
3006
3007 Return a non-zero integer if the sign bit on an NV is set, and 0 if
3008 it is not.  
3009
3010 If Configure detects this system has a signbit() that will work with
3011 our NVs, then we just use it via the #define in perl.h.  Otherwise,
3012 fall back on this implementation.  As a first pass, this gets everything
3013 right except -0.0.  Alas, catching -0.0 is the main use for this function,
3014 so this is not too helpful yet.  Still, at least we have the scaffolding
3015 in place to support other systems, should that prove useful.
3016
3017
3018 Configure notes:  This function is called 'Perl_signbit' instead of a
3019 plain 'signbit' because it is easy to imagine a system having a signbit()
3020 function or macro that doesn't happen to work with our particular choice
3021 of NVs.  We shouldn't just re-#define signbit as Perl_signbit and expect
3022 the standard system headers to be happy.  Also, this is a no-context
3023 function (no pTHX_) because Perl_signbit() is usually re-#defined in
3024 perl.h as a simple macro call to the system's signbit().
3025 Users should just always call Perl_signbit().
3026
3027 NOTE: this function is experimental and may change or be
3028 removed without notice.
3029
3030         int     Perl_signbit(NV f)
3031
3032 =for hackers
3033 Found in file numeric.c
3034
3035 =item scan_bin
3036 X<scan_bin>
3037
3038 For backwards compatibility. Use C<grok_bin> instead.
3039
3040         NV      scan_bin(const char* start, STRLEN len, STRLEN* retlen)
3041
3042 =for hackers
3043 Found in file numeric.c
3044
3045 =item scan_hex
3046 X<scan_hex>
3047
3048 For backwards compatibility. Use C<grok_hex> instead.
3049
3050         NV      scan_hex(const char* start, STRLEN len, STRLEN* retlen)
3051
3052 =for hackers
3053 Found in file numeric.c
3054
3055 =item scan_oct
3056 X<scan_oct>
3057
3058 For backwards compatibility. Use C<grok_oct> instead.
3059
3060         NV      scan_oct(const char* start, STRLEN len, STRLEN* retlen)
3061
3062 =for hackers
3063 Found in file numeric.c
3064
3065
3066 =back
3067
3068 =head1 Optree Manipulation Functions
3069
3070 =over 8
3071
3072 =item cv_const_sv
3073 X<cv_const_sv>
3074
3075 If C<cv> is a constant sub eligible for inlining. returns the constant
3076 value returned by the sub.  Otherwise, returns NULL.
3077
3078 Constant subs can be created with C<newCONSTSUB> or as described in
3079 L<perlsub/"Constant Functions">.
3080
3081         SV*     cv_const_sv(const CV *const cv)
3082
3083 =for hackers
3084 Found in file op.c
3085
3086 =item newCONSTSUB
3087 X<newCONSTSUB>
3088
3089 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
3090 eligible for inlining at compile-time.
3091
3092         CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)
3093
3094 =for hackers
3095 Found in file op.c
3096
3097 =item newXS
3098 X<newXS>
3099
3100 Used by C<xsubpp> to hook up XSUBs as Perl subs.  I<filename> needs to be
3101 static storage, as it is used directly as CvFILE(), without a copy being made.
3102
3103 =for hackers
3104 Found in file op.c
3105
3106
3107 =back
3108
3109 =head1 Pad Data Structures
3110
3111 =over 8
3112
3113 =item pad_sv
3114 X<pad_sv>
3115
3116 Get the value at offset po in the current pad.
3117 Use macro PAD_SV instead of calling this function directly.
3118
3119         SV*     pad_sv(PADOFFSET po)
3120
3121 =for hackers
3122 Found in file pad.c
3123
3124
3125 =back
3126
3127 =head1 Per-Interpreter Variables
3128
3129 =over 8
3130
3131 =item PL_modglobal
3132 X<PL_modglobal>
3133
3134 C<PL_modglobal> is a general purpose, interpreter global HV for use by
3135 extensions that need to keep information on a per-interpreter basis.
3136 In a pinch, it can also be used as a symbol table for extensions
3137 to share data among each other.  It is a good idea to use keys
3138 prefixed by the package name of the extension that owns the data.
3139
3140         HV*     PL_modglobal
3141
3142 =for hackers
3143 Found in file intrpvar.h
3144
3145 =item PL_na
3146 X<PL_na>
3147
3148 A convenience variable which is typically used with C<SvPV> when one
3149 doesn't care about the length of the string.  It is usually more efficient
3150 to either declare a local variable and use that instead or to use the
3151 C<SvPV_nolen> macro.
3152
3153         STRLEN  PL_na
3154
3155 =for hackers
3156 Found in file intrpvar.h
3157
3158 =item PL_sv_no
3159 X<PL_sv_no>
3160
3161 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
3162 C<&PL_sv_no>.
3163
3164         SV      PL_sv_no
3165
3166 =for hackers
3167 Found in file intrpvar.h
3168
3169 =item PL_sv_undef
3170 X<PL_sv_undef>
3171
3172 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
3173
3174         SV      PL_sv_undef
3175
3176 =for hackers
3177 Found in file intrpvar.h
3178
3179 =item PL_sv_yes
3180 X<PL_sv_yes>
3181
3182 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
3183 C<&PL_sv_yes>.
3184
3185         SV      PL_sv_yes
3186
3187 =for hackers
3188 Found in file intrpvar.h
3189
3190
3191 =back
3192
3193 =head1 REGEXP Functions
3194
3195 =over 8
3196
3197 =item SvRX
3198 X<SvRX>
3199
3200 Convenience macro to get the REGEXP from a SV. This is approximately
3201 equivalent to the following snippet:
3202
3203     if (SvMAGICAL(sv))
3204         mg_get(sv);
3205     if (SvROK(sv) &&
3206         (tmpsv = (SV*)SvRV(sv)) &&
3207         SvTYPE(tmpsv) == SVt_PVMG &&
3208         (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
3209     {
3210         return (REGEXP *)tmpmg->mg_obj;
3211     }
3212
3213 NULL will be returned if a REGEXP* is not found.
3214
3215         REGEXP *        SvRX(SV *sv)
3216
3217 =for hackers
3218 Found in file regexp.h
3219
3220 =item SvRXOK
3221 X<SvRXOK>
3222
3223 Returns a boolean indicating whether the SV contains qr magic
3224 (PERL_MAGIC_qr).
3225
3226 If you want to do something with the REGEXP* later use SvRX instead
3227 and check for NULL.
3228
3229         bool    SvRXOK(SV* sv)
3230
3231 =for hackers
3232 Found in file regexp.h
3233
3234
3235 =back
3236
3237 =head1 Simple Exception Handling Macros
3238
3239 =over 8
3240
3241 =item dXCPT
3242 X<dXCPT>
3243
3244 Set up necessary local variables for exception handling.
3245 See L<perlguts/"Exception Handling">.
3246
3247                 dXCPT;
3248
3249 =for hackers
3250 Found in file XSUB.h
3251
3252 =item XCPT_CATCH
3253 X<XCPT_CATCH>
3254
3255 Introduces a catch block.  See L<perlguts/"Exception Handling">.
3256
3257 =for hackers
3258 Found in file XSUB.h
3259
3260 =item XCPT_RETHROW
3261 X<XCPT_RETHROW>
3262
3263 Rethrows a previously caught exception.  See L<perlguts/"Exception Handling">.
3264
3265                 XCPT_RETHROW;
3266
3267 =for hackers
3268 Found in file XSUB.h
3269
3270 =item XCPT_TRY_END
3271 X<XCPT_TRY_END>
3272
3273 Ends a try block.  See L<perlguts/"Exception Handling">.
3274
3275 =for hackers
3276 Found in file XSUB.h
3277
3278 =item XCPT_TRY_START
3279 X<XCPT_TRY_START>
3280
3281 Starts a try block.  See L<perlguts/"Exception Handling">.
3282
3283 =for hackers
3284 Found in file XSUB.h
3285
3286
3287 =back
3288
3289 =head1 Stack Manipulation Macros
3290
3291 =over 8
3292
3293 =item dMARK
3294 X<dMARK>
3295
3296 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
3297 C<dORIGMARK>.
3298
3299                 dMARK;
3300
3301 =for hackers
3302 Found in file pp.h
3303
3304 =item dORIGMARK
3305 X<dORIGMARK>
3306
3307 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
3308
3309                 dORIGMARK;
3310
3311 =for hackers
3312 Found in file pp.h
3313
3314 =item dSP
3315 X<dSP>
3316
3317 Declares a local copy of perl's stack pointer for the XSUB, available via
3318 the C<SP> macro.  See C<SP>.
3319
3320                 dSP;
3321
3322 =for hackers
3323 Found in file pp.h
3324
3325 =item EXTEND
3326 X<EXTEND>
3327
3328 Used to extend the argument stack for an XSUB's return values. Once
3329 used, guarantees that there is room for at least C<nitems> to be pushed
3330 onto the stack.
3331
3332         void    EXTEND(SP, int nitems)
3333
3334 =for hackers
3335 Found in file pp.h
3336
3337 =item MARK
3338 X<MARK>
3339
3340 Stack marker variable for the XSUB.  See C<dMARK>.
3341
3342 =for hackers
3343 Found in file pp.h
3344
3345 =item mPUSHi
3346 X<mPUSHi>
3347
3348 Push an integer onto the stack.  The stack must have room for this element.
3349 Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>.
3350
3351         void    mPUSHi(IV iv)
3352
3353 =for hackers
3354 Found in file pp.h
3355
3356 =item mPUSHn
3357 X<mPUSHn>
3358
3359 Push a double onto the stack.  The stack must have room for this element.
3360 Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>.
3361
3362         void    mPUSHn(NV nv)
3363
3364 =for hackers
3365 Found in file pp.h
3366
3367 =item mPUSHp
3368 X<mPUSHp>
3369
3370 Push a string onto the stack.  The stack must have room for this element.
3371 The C<len> indicates the length of the string.  Does not use C<TARG>.
3372 See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3373
3374         void    mPUSHp(char* str, STRLEN len)
3375
3376 =for hackers
3377 Found in file pp.h
3378
3379 =item mPUSHs
3380 X<mPUSHs>
3381
3382 Push an SV onto the stack and mortalizes the SV.  The stack must have room
3383 for this element.  Does not use C<TARG>.  See also C<PUSHs> and C<mXPUSHs>.
3384
3385         void    mPUSHs(SV* sv)
3386
3387 =for hackers
3388 Found in file pp.h
3389
3390 =item mPUSHu
3391 X<mPUSHu>
3392
3393 Push an unsigned integer onto the stack.  The stack must have room for this
3394 element.  Does not use C<TARG>.  See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>.
3395
3396         void    mPUSHu(UV uv)
3397
3398 =for hackers
3399 Found in file pp.h
3400
3401 =item mXPUSHi
3402 X<mXPUSHi>
3403
3404 Push an integer onto the stack, extending the stack if necessary.
3405 Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>.
3406
3407         void    mXPUSHi(IV iv)
3408
3409 =for hackers
3410 Found in file pp.h
3411
3412 =item mXPUSHn
3413 X<mXPUSHn>
3414
3415 Push a double onto the stack, extending the stack if necessary.
3416 Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>.
3417
3418         void    mXPUSHn(NV nv)
3419
3420 =for hackers
3421 Found in file pp.h
3422
3423 =item mXPUSHp
3424 X<mXPUSHp>
3425
3426 Push a string onto the stack, extending the stack if necessary.  The C<len>
3427 indicates the length of the string.  Does not use C<TARG>.  See also C<XPUSHp>,
3428 C<mPUSHp> and C<PUSHp>.
3429
3430         void    mXPUSHp(char* str, STRLEN len)
3431
3432 =for hackers
3433 Found in file pp.h
3434
3435 =item mXPUSHs
3436 X<mXPUSHs>
3437
3438 Push an SV onto the stack, extending the stack if necessary and mortalizes
3439 the SV.  Does not use C<TARG>.  See also C<XPUSHs> and C<mPUSHs>.
3440
3441         void    mXPUSHs(SV* sv)
3442
3443 =for hackers
3444 Found in file pp.h
3445
3446 =item mXPUSHu
3447 X<mXPUSHu>
3448
3449 Push an unsigned integer onto the stack, extending the stack if necessary.
3450 Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>.
3451
3452         void    mXPUSHu(UV uv)
3453
3454 =for hackers
3455 Found in file pp.h
3456
3457 =item ORIGMARK
3458 X<ORIGMARK>
3459
3460 The original stack mark for the XSUB.  See C<dORIGMARK>.
3461
3462 =for hackers
3463 Found in file pp.h
3464
3465 =item POPi
3466 X<POPi>
3467
3468 Pops an integer off the stack.
3469
3470         IV      POPi
3471
3472 =for hackers
3473 Found in file pp.h
3474
3475 =item POPl
3476 X<POPl>
3477
3478 Pops a long off the stack.
3479
3480         long    POPl
3481
3482 =for hackers
3483 Found in file pp.h
3484
3485 =item POPn
3486 X<POPn>
3487
3488 Pops a double off the stack.
3489
3490         NV      POPn
3491
3492 =for hackers
3493 Found in file pp.h
3494
3495 =item POPp
3496 X<POPp>
3497
3498 Pops a string off the stack. Deprecated. New code should use POPpx.
3499
3500         char*   POPp
3501
3502 =for hackers
3503 Found in file pp.h
3504
3505 =item POPpbytex
3506 X<POPpbytex>
3507
3508 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3509
3510         char*   POPpbytex
3511
3512 =for hackers
3513 Found in file pp.h
3514
3515 =item POPpx
3516 X<POPpx>
3517
3518 Pops a string off the stack.
3519
3520         char*   POPpx
3521
3522 =for hackers
3523 Found in file pp.h
3524
3525 =item POPs
3526 X<POPs>
3527
3528 Pops an SV off the stack.
3529
3530         SV*     POPs
3531
3532 =for hackers
3533 Found in file pp.h
3534
3535 =item PUSHi
3536 X<PUSHi>
3537
3538 Push an integer onto the stack.  The stack must have room for this element.
3539 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3540 called to declare it.  Do not call multiple C<TARG>-oriented macros to 
3541 return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
3542 C<mXPUSHi>.
3543
3544         void    PUSHi(IV iv)
3545
3546 =for hackers
3547 Found in file pp.h
3548
3549 =item PUSHMARK
3550 X<PUSHMARK>
3551
3552 Opening bracket for arguments on a callback.  See C<PUTBACK> and
3553 L<perlcall>.
3554
3555         void    PUSHMARK(SP)
3556
3557 =for hackers
3558 Found in file pp.h
3559
3560 =item PUSHmortal
3561 X<PUSHmortal>
3562
3563 Push a new mortal SV onto the stack.  The stack must have room for this
3564 element.  Does not use C<TARG>.  See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3565
3566         void    PUSHmortal()
3567
3568 =for hackers
3569 Found in file pp.h
3570
3571 =item PUSHn
3572 X<PUSHn>
3573
3574 Push a double onto the stack.  The stack must have room for this element.
3575 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3576 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3577 return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
3578 C<mXPUSHn>.
3579
3580         void    PUSHn(NV nv)
3581
3582 =for hackers
3583 Found in file pp.h
3584
3585 =item PUSHp
3586 X<PUSHp>
3587
3588 Push a string onto the stack.  The stack must have room for this element.
3589 The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
3590 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
3591 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3592 C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
3593
3594         void    PUSHp(char* str, STRLEN len)
3595
3596 =for hackers
3597 Found in file pp.h
3598
3599 =item PUSHs
3600 X<PUSHs>
3601
3602 Push an SV onto the stack.  The stack must have room for this element.
3603 Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
3604 C<XPUSHs> and C<XPUSHmortal>.
3605
3606         void    PUSHs(SV* sv)
3607
3608 =for hackers
3609 Found in file pp.h
3610
3611 =item PUSHu
3612 X<PUSHu>
3613
3614 Push an unsigned integer onto the stack.  The stack must have room for this
3615 element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3616 should be called to declare it.  Do not call multiple C<TARG>-oriented
3617 macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
3618 C<XPUSHu> and C<mXPUSHu>.
3619
3620         void    PUSHu(UV uv)
3621
3622 =for hackers
3623 Found in file pp.h
3624
3625 =item PUTBACK
3626 X<PUTBACK>
3627
3628 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
3629 See C<PUSHMARK> and L<perlcall> for other uses.
3630
3631                 PUTBACK;
3632
3633 =for hackers
3634 Found in file pp.h
3635
3636 =item SP
3637 X<SP>
3638
3639 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
3640 C<SPAGAIN>.
3641
3642 =for hackers
3643 Found in file pp.h
3644
3645 =item SPAGAIN
3646 X<SPAGAIN>
3647
3648 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
3649
3650                 SPAGAIN;
3651
3652 =for hackers
3653 Found in file pp.h
3654
3655 =item XPUSHi
3656 X<XPUSHi>
3657
3658 Push an integer onto the stack, extending the stack if necessary.  Handles
3659 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3660 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3661 from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
3662
3663         void    XPUSHi(IV iv)
3664
3665 =for hackers
3666 Found in file pp.h
3667
3668 =item XPUSHmortal
3669 X<XPUSHmortal>
3670
3671 Push a new mortal SV onto the stack, extending the stack if necessary.
3672 Does not use C<TARG>.  See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>.
3673
3674         void    XPUSHmortal()
3675
3676 =for hackers
3677 Found in file pp.h
3678
3679 =item XPUSHn
3680 X<XPUSHn>
3681
3682 Push a double onto the stack, extending the stack if necessary.  Handles
3683 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3684 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3685 from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
3686
3687         void    XPUSHn(NV nv)
3688
3689 =for hackers
3690 Found in file pp.h
3691
3692 =item XPUSHp
3693 X<XPUSHp>
3694
3695 Push a string onto the stack, extending the stack if necessary.  The C<len>
3696 indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
3697 C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
3698 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3699 C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
3700
3701         void    XPUSHp(char* str, STRLEN len)
3702
3703 =for hackers
3704 Found in file pp.h
3705
3706 =item XPUSHs
3707 X<XPUSHs>
3708
3709 Push an SV onto the stack, extending the stack if necessary.  Does not
3710 handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
3711 C<PUSHs> and C<PUSHmortal>.
3712
3713         void    XPUSHs(SV* sv)
3714
3715 =for hackers
3716 Found in file pp.h
3717
3718 =item XPUSHu
3719 X<XPUSHu>
3720
3721 Push an unsigned integer onto the stack, extending the stack if necessary.
3722 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3723 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3724 return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
3725 C<mPUSHu>.
3726
3727         void    XPUSHu(UV uv)
3728
3729 =for hackers
3730 Found in file pp.h
3731
3732 =item XSRETURN
3733 X<XSRETURN>
3734
3735 Return from XSUB, indicating number of items on the stack.  This is usually
3736 handled by C<xsubpp>.
3737
3738         void    XSRETURN(int nitems)
3739
3740 =for hackers
3741 Found in file XSUB.h
3742
3743 =item XSRETURN_EMPTY
3744 X<XSRETURN_EMPTY>
3745
3746 Return an empty list from an XSUB immediately.
3747
3748                 XSRETURN_EMPTY;
3749
3750 =for hackers
3751 Found in file XSUB.h
3752
3753 =item XSRETURN_IV
3754 X<XSRETURN_IV>
3755
3756 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3757
3758         void    XSRETURN_IV(IV iv)
3759
3760 =for hackers
3761 Found in file XSUB.h
3762
3763 =item XSRETURN_NO
3764 X<XSRETURN_NO>
3765
3766 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3767
3768                 XSRETURN_NO;
3769
3770 =for hackers
3771 Found in file XSUB.h
3772
3773 =item XSRETURN_NV
3774 X<XSRETURN_NV>
3775
3776 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
3777
3778         void    XSRETURN_NV(NV nv)
3779
3780 =for hackers
3781 Found in file XSUB.h
3782
3783 =item XSRETURN_PV
3784 X<XSRETURN_PV>
3785
3786 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3787
3788         void    XSRETURN_PV(char* str)
3789
3790 =for hackers
3791 Found in file XSUB.h
3792
3793 =item XSRETURN_UNDEF
3794 X<XSRETURN_UNDEF>
3795
3796 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3797
3798                 XSRETURN_UNDEF;
3799
3800 =for hackers
3801 Found in file XSUB.h
3802
3803 =item XSRETURN_UV
3804 X<XSRETURN_UV>
3805
3806 Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
3807
3808         void    XSRETURN_UV(IV uv)
3809
3810 =for hackers
3811 Found in file XSUB.h
3812
3813 =item XSRETURN_YES
3814 X<XSRETURN_YES>
3815
3816 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3817
3818                 XSRETURN_YES;
3819
3820 =for hackers
3821 Found in file XSUB.h
3822
3823 =item XST_mIV
3824 X<XST_mIV>
3825
3826 Place an integer into the specified position C<pos> on the stack.  The
3827 value is stored in a new mortal SV.
3828
3829         void    XST_mIV(int pos, IV iv)
3830
3831 =for hackers
3832 Found in file XSUB.h
3833
3834 =item XST_mNO
3835 X<XST_mNO>
3836
3837 Place C<&PL_sv_no> into the specified position C<pos> on the
3838 stack.
3839
3840         void    XST_mNO(int pos)
3841
3842 =for hackers
3843 Found in file XSUB.h
3844
3845 =item XST_mNV
3846 X<XST_mNV>
3847
3848 Place a double into the specified position C<pos> on the stack.  The value
3849 is stored in a new mortal SV.
3850
3851         void    XST_mNV(int pos, NV nv)
3852
3853 =for hackers
3854 Found in file XSUB.h
3855
3856 =item XST_mPV
3857 X<XST_mPV>
3858
3859 Place a copy of a string into the specified position C<pos> on the stack. 
3860 The value is stored in a new mortal SV.
3861
3862         void    XST_mPV(int pos, char* str)
3863
3864 =for hackers
3865 Found in file XSUB.h
3866
3867 =item XST_mUNDEF
3868 X<XST_mUNDEF>
3869
3870 Place C<&PL_sv_undef> into the specified position C<pos> on the
3871 stack.
3872
3873         void    XST_mUNDEF(int pos)
3874
3875 =for hackers
3876 Found in file XSUB.h
3877
3878 =item XST_mYES
3879 X<XST_mYES>
3880
3881 Place C<&PL_sv_yes> into the specified position C<pos> on the
3882 stack.
3883
3884         void    XST_mYES(int pos)
3885
3886 =for hackers
3887 Found in file XSUB.h
3888
3889
3890 =back
3891
3892 =head1 SV Flags
3893
3894 =over 8
3895
3896 =item svtype
3897 X<svtype>
3898
3899 An enum of flags for Perl types.  These are found in the file B<sv.h>
3900 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3901
3902 =for hackers
3903 Found in file sv.h
3904
3905 =item SVt_IV
3906 X<SVt_IV>
3907
3908 Integer type flag for scalars.  See C<svtype>.
3909
3910 =for hackers
3911 Found in file sv.h
3912
3913 =item SVt_NV
3914 X<SVt_NV>
3915
3916 Double type flag for scalars.  See C<svtype>.
3917
3918 =for hackers
3919 Found in file sv.h
3920
3921 =item SVt_PV
3922 X<SVt_PV>
3923
3924 Pointer type flag for scalars.  See C<svtype>.
3925
3926 =for hackers
3927 Found in file sv.h
3928
3929 =item SVt_PVAV
3930 X<SVt_PVAV>
3931
3932 Type flag for arrays.  See C<svtype>.
3933
3934 =for hackers
3935 Found in file sv.h
3936
3937 =item SVt_PVCV
3938 X<SVt_PVCV>
3939
3940 Type flag for code refs.  See C<svtype>.
3941
3942 =for hackers
3943 Found in file sv.h
3944
3945 =item SVt_PVHV
3946 X<SVt_PVHV>
3947
3948 Type flag for hashes.  See C<svtype>.
3949
3950 =for hackers
3951 Found in file sv.h
3952
3953 =item SVt_PVMG
3954 X<SVt_PVMG>
3955
3956 Type flag for blessed scalars.  See C<svtype>.
3957
3958 =for hackers
3959 Found in file sv.h
3960
3961
3962 =back
3963
3964 =head1 SV Manipulation Functions
3965
3966 =over 8
3967
3968 =item croak_xs_usage
3969 X<croak_xs_usage>
3970
3971 A specialised variant of C<croak()> for emitting the usage message for xsubs
3972
3973     croak_xs_usage(cv, "eee_yow");
3974
3975 works out the package name and subroutine name from C<cv>, and then calls
3976 C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
3977
3978     Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
3979
3980         void    croak_xs_usage(const CV *const cv, const char *const params)
3981
3982 =for hackers
3983 Found in file universal.c
3984
3985 =item get_sv
3986 X<get_sv>
3987
3988 Returns the SV of the specified Perl scalar.  If C<create> is set and the
3989 Perl variable does not exist then it will be created.  If C<create> is not
3990 set and the variable does not exist then NULL is returned.
3991
3992 NOTE: the perl_ form of this function is deprecated.
3993
3994         SV*     get_sv(const char* name, I32 create)
3995
3996 =for hackers
3997 Found in file perl.c
3998
3999 =item newRV_inc
4000 X<newRV_inc>
4001
4002 Creates an RV wrapper for an SV.  The reference count for the original SV is
4003 incremented.
4004
4005         SV*     newRV_inc(SV* sv)
4006
4007 =for hackers
4008 Found in file sv.h
4009
4010 =item newSVpvn_utf8
4011 X<newSVpvn_utf8>
4012
4013 Creates a new SV and copies a string into it.  If utf8 is true, calls
4014 C<SvUTF8_on> on the new SV.  Implemented as a wrapper around C<newSVpvn_flags>.
4015
4016         SV*     newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
4017
4018 =for hackers
4019 Found in file sv.h
4020
4021 =item SvCUR
4022 X<SvCUR>
4023
4024 Returns the length of the string which is in the SV.  See C<SvLEN>.
4025
4026         STRLEN  SvCUR(SV* sv)
4027
4028 =for hackers
4029 Found in file sv.h
4030
4031 =item SvCUR_set
4032 X<SvCUR_set>
4033
4034 Set the current length of the string which is in the SV.  See C<SvCUR>
4035 and C<SvIV_set>.
4036
4037         void    SvCUR_set(SV* sv, STRLEN len)
4038
4039 =for hackers
4040 Found in file sv.h
4041
4042 =item SvEND
4043 X<SvEND>
4044
4045 Returns a pointer to the last character in the string which is in the SV.
4046 See C<SvCUR>.  Access the character as *(SvEND(sv)).
4047
4048         char*   SvEND(SV* sv)
4049
4050 =for hackers
4051 Found in file sv.h
4052
4053 =item SvGAMAGIC
4054 X<SvGAMAGIC>
4055
4056 Returns true if the SV has get magic or overloading. If either is true then
4057 the scalar is active data, and has the potential to return a new value every
4058 time it is accessed. Hence you must be careful to only read it once per user
4059 logical operation and work with that returned value. If neither is true then
4060 the scalar's value cannot change unless written to.
4061
4062         char*   SvGAMAGIC(SV* sv)
4063
4064 =for hackers
4065 Found in file sv.h
4066
4067 =item SvGROW
4068 X<SvGROW>
4069
4070 Expands the character buffer in the SV so that it has room for the
4071 indicated number of bytes (remember to reserve space for an extra trailing
4072 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
4073 Returns a pointer to the character buffer.
4074
4075         char *  SvGROW(SV* sv, STRLEN len)
4076
4077 =for hackers
4078 Found in file sv.h
4079
4080 =item SvIOK
4081 X<SvIOK>
4082
4083 Returns a U32 value indicating whether the SV contains an integer.
4084
4085         U32     SvIOK(SV* sv)
4086
4087 =for hackers
4088 Found in file sv.h
4089
4090 =item SvIOKp
4091 X<SvIOKp>
4092
4093 Returns a U32 value indicating whether the SV contains an integer.  Checks
4094 the B<private> setting.  Use C<SvIOK> instead.
4095
4096         U32     SvIOKp(SV* sv)
4097
4098 =for hackers
4099 Found in file sv.h
4100
4101 =item SvIOK_notUV
4102 X<SvIOK_notUV>
4103
4104 Returns a boolean indicating whether the SV contains a signed integer.
4105
4106         bool    SvIOK_notUV(SV* sv)
4107
4108 =for hackers
4109 Found in file sv.h
4110
4111 =item SvIOK_off
4112 X<SvIOK_off>
4113
4114 Unsets the IV status of an SV.
4115
4116         void    SvIOK_off(SV* sv)
4117
4118 =for hackers
4119 Found in file sv.h
4120
4121 =item SvIOK_on
4122 X<SvIOK_on>
4123
4124 Tells an SV that it is an integer.
4125
4126         void    SvIOK_on(SV* sv)
4127
4128 =for hackers
4129 Found in file sv.h
4130
4131 =item SvIOK_only
4132 X<SvIOK_only>
4133
4134 Tells an SV that it is an integer and disables all other OK bits.
4135
4136         void    SvIOK_only(SV* sv)
4137
4138 =for hackers
4139 Found in file sv.h
4140
4141 =item SvIOK_only_UV
4142 X<SvIOK_only_UV>
4143
4144 Tells and SV that it is an unsigned integer and disables all other OK bits.
4145
4146         void    SvIOK_only_UV(SV* sv)
4147
4148 =for hackers
4149 Found in file sv.h
4150
4151 =item SvIOK_UV
4152 X<SvIOK_UV>
4153
4154 Returns a boolean indicating whether the SV contains an unsigned integer.
4155
4156         bool    SvIOK_UV(SV* sv)
4157
4158 =for hackers
4159 Found in file sv.h
4160
4161 =item SvIsCOW
4162 X<SvIsCOW>
4163
4164 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
4165 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
4166 COW)
4167
4168         bool    SvIsCOW(SV* sv)
4169
4170 =for hackers
4171 Found in file sv.h
4172
4173 =item SvIsCOW_shared_hash
4174 X<SvIsCOW_shared_hash>
4175
4176 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
4177 scalar.
4178
4179         bool    SvIsCOW_shared_hash(SV* sv)
4180
4181 =for hackers
4182 Found in file sv.h
4183
4184 =item SvIV
4185 X<SvIV>
4186
4187 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
4188 version which guarantees to evaluate sv only once.
4189
4190         IV      SvIV(SV* sv)
4191
4192 =for hackers
4193 Found in file sv.h
4194
4195 =item SvIVX
4196 X<SvIVX>
4197
4198 Returns the raw value in the SV's IV slot, without checks or conversions.
4199 Only use when you are sure SvIOK is true. See also C<SvIV()>.
4200
4201         IV      SvIVX(SV* sv)
4202
4203 =for hackers
4204 Found in file sv.h
4205
4206 =item SvIVx
4207 X<SvIVx>
4208
4209 Coerces the given SV to an integer and returns it. Guarantees to evaluate
4210 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4211 otherwise use the more efficient C<SvIV>.
4212
4213         IV      SvIVx(SV* sv)
4214
4215 =for hackers
4216 Found in file sv.h
4217
4218 =item SvIV_nomg
4219 X<SvIV_nomg>
4220
4221 Like C<SvIV> but doesn't process magic.
4222
4223         IV      SvIV_nomg(SV* sv)
4224
4225 =for hackers
4226 Found in file sv.h
4227
4228 =item SvIV_set
4229 X<SvIV_set>
4230
4231 Set the value of the IV pointer in sv to val.  It is possible to perform
4232 the same function of this macro with an lvalue assignment to C<SvIVX>.
4233 With future Perls, however, it will be more efficient to use 
4234 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
4235
4236         void    SvIV_set(SV* sv, IV val)
4237
4238 =for hackers
4239 Found in file sv.h
4240
4241 =item SvLEN
4242 X<SvLEN>
4243
4244 Returns the size of the string buffer in the SV, not including any part
4245 attributable to C<SvOOK>.  See C<SvCUR>.
4246
4247         STRLEN  SvLEN(SV* sv)
4248
4249 =for hackers
4250 Found in file sv.h
4251
4252 =item SvLEN_set
4253 X<SvLEN_set>
4254
4255 Set the actual length of the string which is in the SV.  See C<SvIV_set>.
4256
4257         void    SvLEN_set(SV* sv, STRLEN len)
4258
4259 =for hackers
4260 Found in file sv.h
4261
4262 =item SvMAGIC_set
4263 X<SvMAGIC_set>
4264
4265 Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
4266
4267         void    SvMAGIC_set(SV* sv, MAGIC* val)
4268
4269 =for hackers
4270 Found in file sv.h
4271
4272 =item SvNIOK
4273 X<SvNIOK>
4274
4275 Returns a U32 value indicating whether the SV contains a number, integer or
4276 double.
4277
4278         U32     SvNIOK(SV* sv)
4279
4280 =for hackers
4281 Found in file sv.h
4282
4283 =item SvNIOKp
4284 X<SvNIOKp>
4285
4286 Returns a U32 value indicating whether the SV contains a number, integer or
4287 double.  Checks the B<private> setting.  Use C<SvNIOK> instead.
4288
4289         U32     SvNIOKp(SV* sv)
4290
4291 =for hackers
4292 Found in file sv.h
4293
4294 =item SvNIOK_off
4295 X<SvNIOK_off>
4296
4297 Unsets the NV/IV status of an SV.
4298
4299         void    SvNIOK_off(SV* sv)
4300
4301 =for hackers
4302 Found in file sv.h
4303
4304 =item SvNOK
4305 X<SvNOK>
4306
4307 Returns a U32 value indicating whether the SV contains a double.
4308
4309         U32     SvNOK(SV* sv)
4310
4311 =for hackers
4312 Found in file sv.h
4313
4314 =item SvNOKp
4315 X<SvNOKp>
4316
4317 Returns a U32 value indicating whether the SV contains a double.  Checks the
4318 B<private> setting.  Use C<SvNOK> instead.
4319
4320         U32     SvNOKp(SV* sv)
4321
4322 =for hackers
4323 Found in file sv.h
4324
4325 =item SvNOK_off
4326 X<SvNOK_off>
4327
4328 Unsets the NV status of an SV.
4329
4330         void    SvNOK_off(SV* sv)
4331
4332 =for hackers
4333 Found in file sv.h
4334
4335 =item SvNOK_on
4336 X<SvNOK_on>
4337
4338 Tells an SV that it is a double.
4339
4340         void    SvNOK_on(SV* sv)
4341
4342 =for hackers
4343 Found in file sv.h
4344
4345 =item SvNOK_only
4346 X<SvNOK_only>
4347
4348 Tells an SV that it is a double and disables all other OK bits.
4349
4350         void    SvNOK_only(SV* sv)
4351
4352 =for hackers
4353 Found in file sv.h
4354
4355 =item SvNV
4356 X<SvNV>
4357
4358 Coerce the given SV to a double and return it. See C<SvNVx> for a version
4359 which guarantees to evaluate sv only once.
4360
4361         NV      SvNV(SV* sv)
4362
4363 =for hackers
4364 Found in file sv.h
4365
4366 =item SvNVX
4367 X<SvNVX>
4368
4369 Returns the raw value in the SV's NV slot, without checks or conversions.
4370 Only use when you are sure SvNOK is true. See also C<SvNV()>.
4371
4372         NV      SvNVX(SV* sv)
4373
4374 =for hackers
4375 Found in file sv.h
4376
4377 =item SvNVx
4378 X<SvNVx>
4379
4380 Coerces the given SV to a double and returns it. Guarantees to evaluate
4381 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4382 otherwise use the more efficient C<SvNV>.
4383
4384         NV      SvNVx(SV* sv)
4385
4386 =for hackers
4387 Found in file sv.h
4388
4389 =item SvNV_set
4390 X<SvNV_set>
4391
4392 Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
4393
4394         void    SvNV_set(SV* sv, NV val)
4395
4396 =for hackers
4397 Found in file sv.h
4398
4399 =item SvOK
4400 X<SvOK>
4401
4402 Returns a U32 value indicating whether the value is an SV. It also tells
4403 whether the value is defined or not.
4404
4405         U32     SvOK(SV* sv)
4406
4407 =for hackers
4408 Found in file sv.h
4409
4410 =item SvOOK
4411 X<SvOOK>
4412
4413 Returns a U32 indicating whether the pointer to the string buffer is offset.
4414 This hack is used internally to speed up removal of characters from the
4415 beginning of a SvPV.  When SvOOK is true, then the start of the
4416 allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
4417 This offset used to be stored in SvIVX, but is now stored within the spare
4418 part of the buffer.
4419
4420         U32     SvOOK(SV* sv)
4421
4422 =for hackers
4423 Found in file sv.h
4424
4425 =item SvOOK_offset
4426 X<SvOOK_offset>
4427
4428 Reads into I<len> the offset from SvPVX back to the true start of the
4429 allocated buffer, which will be non-zero if C<sv_chop> has been used to
4430 efficiently remove characters from start of the buffer. Implemented as a
4431 macro, which takes the address of I<len>, which must be of type C<STRLEN>.
4432 Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
4433
4434         void    SvOOK_offset(NN SV*sv, STRLEN len)
4435
4436 =for hackers
4437 Found in file sv.h
4438
4439 =item SvPOK
4440 X<SvPOK>
4441
4442 Returns a U32 value indicating whether the SV contains a character
4443 string.
4444
4445         U32     SvPOK(SV* sv)
4446
4447 =for hackers
4448 Found in file sv.h
4449
4450 =item SvPOKp
4451 X<SvPOKp>
4452
4453 Returns a U32 value indicating whether the SV contains a character string.
4454 Checks the B<private> setting.  Use C<SvPOK> instead.
4455
4456         U32     SvPOKp(SV* sv)
4457
4458 =for hackers
4459 Found in file sv.h
4460
4461 =item SvPOK_off
4462 X<SvPOK_off>
4463
4464 Unsets the PV status of an SV.
4465
4466         void    SvPOK_off(SV* sv)
4467
4468 =for hackers
4469 Found in file sv.h
4470
4471 =item SvPOK_on
4472 X<SvPOK_on>
4473
4474 Tells an SV that it is a string.
4475
4476         void    SvPOK_on(SV* sv)
4477
4478 =for hackers
4479 Found in file sv.h
4480
4481 =item SvPOK_only
4482 X<SvPOK_only>
4483
4484 Tells an SV that it is a string and disables all other OK bits.
4485 Will also turn off the UTF-8 status.
4486
4487         void    SvPOK_only(SV* sv)
4488
4489 =for hackers
4490 Found in file sv.h
4491
4492 =item SvPOK_only_UTF8
4493 X<SvPOK_only_UTF8>
4494
4495 Tells an SV that it is a string and disables all other OK bits,
4496 and leaves the UTF-8 status as it was.
4497
4498         void    SvPOK_only_UTF8(SV* sv)
4499
4500 =for hackers
4501 Found in file sv.h
4502
4503 =item SvPV
4504 X<SvPV>
4505
4506 Returns a pointer to the string in the SV, or a stringified form of
4507 the SV if the SV does not contain a string.  The SV may cache the
4508 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
4509 C<SvPVx> for a version which guarantees to evaluate sv only once.
4510
4511         char*   SvPV(SV* sv, STRLEN len)
4512
4513 =for hackers
4514 Found in file sv.h
4515
4516 =item SvPVbyte
4517 X<SvPVbyte>
4518
4519 Like C<SvPV>, but converts sv to byte representation first if necessary.
4520
4521         char*   SvPVbyte(SV* sv, STRLEN len)
4522
4523 =for hackers
4524 Found in file sv.h
4525
4526 =item SvPVbytex
4527 X<SvPVbytex>
4528
4529 Like C<SvPV>, but converts sv to byte representation first if necessary.
4530 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4531 otherwise.
4532
4533         char*   SvPVbytex(SV* sv, STRLEN len)
4534
4535 =for hackers
4536 Found in file sv.h
4537
4538 =item SvPVbytex_force
4539 X<SvPVbytex_force>
4540
4541 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4542 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4543 otherwise.
4544
4545         char*   SvPVbytex_force(SV* sv, STRLEN len)
4546
4547 =for hackers
4548 Found in file sv.h
4549
4550 =item SvPVbyte_force
4551 X<SvPVbyte_force>
4552
4553 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4554
4555         char*   SvPVbyte_force(SV* sv, STRLEN len)
4556
4557 =for hackers
4558 Found in file sv.h
4559
4560 =item SvPVbyte_nolen
4561 X<SvPVbyte_nolen>
4562
4563 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4564
4565         char*   SvPVbyte_nolen(SV* sv)
4566
4567 =for hackers
4568 Found in file sv.h
4569
4570 =item SvPVutf8
4571 X<SvPVutf8>
4572
4573 Like C<SvPV>, but converts sv to utf8 first if necessary.
4574
4575         char*   SvPVutf8(SV* sv, STRLEN len)
4576
4577 =for hackers
4578 Found in file sv.h
4579
4580 =item SvPVutf8x
4581 X<SvPVutf8x>
4582
4583 Like C<SvPV>, but converts sv to utf8 first if necessary.
4584 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4585 otherwise.
4586
4587         char*   SvPVutf8x(SV* sv, STRLEN len)
4588
4589 =for hackers
4590 Found in file sv.h
4591
4592 =item SvPVutf8x_force
4593 X<SvPVutf8x_force>
4594
4595 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4596 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4597 otherwise.
4598
4599         char*   SvPVutf8x_force(SV* sv, STRLEN len)
4600
4601 =for hackers
4602 Found in file sv.h
4603
4604 =item SvPVutf8_force
4605 X<SvPVutf8_force>
4606
4607 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4608
4609         char*   SvPVutf8_force(SV* sv, STRLEN len)
4610
4611 =for hackers
4612 Found in file sv.h
4613
4614 =item SvPVutf8_nolen
4615 X<SvPVutf8_nolen>
4616
4617 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4618
4619         char*   SvPVutf8_nolen(SV* sv)
4620
4621 =for hackers
4622 Found in file sv.h
4623
4624 =item SvPVX
4625 X<SvPVX>
4626
4627 Returns a pointer to the physical string in the SV.  The SV must contain a
4628 string.
4629
4630         char*   SvPVX(SV* sv)
4631
4632 =for hackers
4633 Found in file sv.h
4634
4635 =item SvPVx
4636 X<SvPVx>
4637
4638 A version of C<SvPV> which guarantees to evaluate C<sv> only once.
4639 Only use this if C<sv> is an expression with side effects, otherwise use the
4640 more efficient C<SvPVX>.
4641
4642         char*   SvPVx(SV* sv, STRLEN len)
4643
4644 =for hackers
4645 Found in file sv.h
4646
4647 =item SvPV_force
4648 X<SvPV_force>
4649
4650 Like C<SvPV> but will force the SV into containing just a string
4651 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4652 directly.
4653
4654         char*   SvPV_force(SV* sv, STRLEN len)
4655
4656 =for hackers
4657 Found in file sv.h
4658
4659 =item SvPV_force_nomg
4660 X<SvPV_force_nomg>
4661
4662 Like C<SvPV> but will force the SV into containing just a string
4663 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4664 directly. Doesn't process magic.
4665
4666         char*   SvPV_force_nomg(SV* sv, STRLEN len)
4667
4668 =for hackers
4669 Found in file sv.h
4670
4671 =item SvPV_nolen
4672 X<SvPV_nolen>
4673
4674 Returns a pointer to the string in the SV, or a stringified form of
4675 the SV if the SV does not contain a string.  The SV may cache the
4676 stringified form becoming C<SvPOK>.  Handles 'get' magic.
4677
4678         char*   SvPV_nolen(SV* sv)
4679
4680 =for hackers
4681 Found in file sv.h
4682
4683 =item SvPV_nomg
4684 X<SvPV_nomg>
4685
4686 Like C<SvPV> but doesn't process magic.
4687
4688         char*   SvPV_nomg(SV* sv, STRLEN len)
4689
4690 =for hackers
4691 Found in file sv.h
4692
4693 =item SvPV_set
4694 X<SvPV_set>
4695
4696 Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
4697
4698         void    SvPV_set(SV* sv, char* val)
4699
4700 =for hackers
4701 Found in file sv.h
4702
4703 =item SvREFCNT
4704 X<SvREFCNT>
4705
4706 Returns the value of the object's reference count.
4707
4708         U32     SvREFCNT(SV* sv)
4709
4710 =for hackers
4711 Found in file sv.h
4712
4713 =item SvREFCNT_dec
4714 X<SvREFCNT_dec>
4715
4716 Decrements the reference count of the given SV.
4717
4718         void    SvREFCNT_dec(SV* sv)
4719
4720 =for hackers
4721 Found in file sv.h
4722
4723 =item SvREFCNT_inc
4724 X<SvREFCNT_inc>
4725
4726 Increments the reference count of the given SV.
4727
4728 All of the following SvREFCNT_inc* macros are optimized versions of
4729 SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4730
4731         SV*     SvREFCNT_inc(SV* sv)
4732
4733 =for hackers
4734 Found in file sv.h
4735
4736 =item SvREFCNT_inc_NN
4737 X<SvREFCNT_inc_NN>
4738
4739 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4740 is not NULL.  Since we don't have to check the NULLness, it's faster
4741 and smaller.
4742
4743         SV*     SvREFCNT_inc_NN(SV* sv)
4744
4745 =for hackers
4746 Found in file sv.h
4747
4748 =item SvREFCNT_inc_simple
4749 X<SvREFCNT_inc_simple>
4750
4751 Same as SvREFCNT_inc, but can only be used with expressions without side
4752 effects.  Since we don't have to store a temporary value, it's faster.
4753
4754         SV*     SvREFCNT_inc_simple(SV* sv)
4755
4756 =for hackers
4757 Found in file sv.h
4758
4759 =item SvREFCNT_inc_simple_NN
4760 X<SvREFCNT_inc_simple_NN>
4761
4762 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4763 is not NULL.  Since we don't have to check the NULLness, it's faster
4764 and smaller.
4765
4766         SV*     SvREFCNT_inc_simple_NN(SV* sv)
4767
4768 =for hackers
4769 Found in file sv.h
4770
4771 =item SvREFCNT_inc_simple_void
4772 X<SvREFCNT_inc_simple_void>
4773
4774 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4775 return value.  The macro doesn't need to return a meaningful value.
4776
4777         void    SvREFCNT_inc_simple_void(SV* sv)
4778
4779 =for hackers
4780 Found in file sv.h
4781
4782 =item SvREFCNT_inc_simple_void_NN
4783 X<SvREFCNT_inc_simple_void_NN>
4784
4785 Same as SvREFCNT_inc, but can only be used if you don't need the return
4786 value, and you know that I<sv> is not NULL.  The macro doesn't need
4787 to return a meaningful value, or check for NULLness, so it's smaller
4788 and faster.
4789
4790         void    SvREFCNT_inc_simple_void_NN(SV* sv)
4791
4792 =for hackers
4793 Found in file sv.h
4794
4795 =item SvREFCNT_inc_void
4796 X<SvREFCNT_inc_void>
4797
4798 Same as SvREFCNT_inc, but can only be used if you don't need the
4799 return value.  The macro doesn't need to return a meaningful value.
4800
4801         void    SvREFCNT_inc_void(SV* sv)
4802
4803 =for hackers
4804 Found in file sv.h
4805
4806 =item SvREFCNT_inc_void_NN
4807 X<SvREFCNT_inc_void_NN>
4808
4809 Same as SvREFCNT_inc, but can only be used if you don't need the return
4810 value, and you know that I<sv> is not NULL.  The macro doesn't need
4811 to return a meaningful value, or check for NULLness, so it's smaller
4812 and faster.
4813
4814         void    SvREFCNT_inc_void_NN(SV* sv)
4815
4816 =for hackers
4817 Found in file sv.h
4818
4819 =item SvROK
4820 X<SvROK>
4821
4822 Tests if the SV is an RV.
4823
4824         U32     SvROK(SV* sv)
4825
4826 =for hackers
4827 Found in file sv.h
4828
4829 =item SvROK_off
4830 X<SvROK_off>
4831
4832 Unsets the RV status of an SV.
4833
4834         void    SvROK_off(SV* sv)
4835
4836 =for hackers
4837 Found in file sv.h
4838
4839 =item SvROK_on
4840 X<SvROK_on>
4841
4842 Tells an SV that it is an RV.
4843
4844         void    SvROK_on(SV* sv)
4845
4846 =for hackers
4847 Found in file sv.h
4848
4849 =item SvRV
4850 X<SvRV>
4851
4852 Dereferences an RV to return the SV.
4853
4854         SV*     SvRV(SV* sv)
4855
4856 =for hackers
4857 Found in file sv.h
4858
4859 =item SvRV_set
4860 X<SvRV_set>
4861
4862 Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
4863
4864         void    SvRV_set(SV* sv, SV* val)
4865
4866 =for hackers
4867 Found in file sv.h
4868
4869 =item SvSTASH
4870 X<SvSTASH>
4871
4872 Returns the stash of the SV.
4873
4874         HV*     SvSTASH(SV* sv)
4875
4876 =for hackers
4877 Found in file sv.h
4878
4879 =item SvSTASH_set
4880 X<SvSTASH_set>
4881
4882 Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
4883
4884         void    SvSTASH_set(SV* sv, HV* val)
4885
4886 =for hackers
4887 Found in file sv.h
4888
4889 =item SvTAINT
4890 X<SvTAINT>
4891
4892 Taints an SV if tainting is enabled.
4893
4894         void    SvTAINT(SV* sv)
4895
4896 =for hackers
4897 Found in file sv.h
4898
4899 =item SvTAINTED
4900 X<SvTAINTED>
4901
4902 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4903 not.
4904
4905         bool    SvTAINTED(SV* sv)
4906
4907 =for hackers
4908 Found in file sv.h
4909
4910 =item SvTAINTED_off
4911 X<SvTAINTED_off>
4912
4913 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4914 some of Perl's fundamental security features. XS module authors should not
4915 use this function unless they fully understand all the implications of
4916 unconditionally untainting the value. Untainting should be done in the
4917 standard perl fashion, via a carefully crafted regexp, rather than directly
4918 untainting variables.
4919
4920         void    SvTAINTED_off(SV* sv)
4921
4922 =for hackers
4923 Found in file sv.h
4924
4925 =item SvTAINTED_on
4926 X<SvTAINTED_on>
4927
4928 Marks an SV as tainted if tainting is enabled.
4929
4930         void    SvTAINTED_on(SV* sv)
4931
4932 =for hackers
4933 Found in file sv.h
4934
4935 =item SvTRUE
4936 X<SvTRUE>
4937
4938 Returns a boolean indicating whether Perl would evaluate the SV as true or
4939 false, defined or undefined.  Does not handle 'get' magic.
4940
4941         bool    SvTRUE(SV* sv)
4942
4943 =for hackers
4944 Found in file sv.h
4945
4946 =item SvTYPE
4947 X<SvTYPE>
4948
4949 Returns the type of the SV.  See C<svtype>.
4950
4951         svtype  SvTYPE(SV* sv)
4952
4953 =for hackers
4954 Found in file sv.h
4955
4956 =item SvUOK
4957 X<SvUOK>
4958
4959 Returns a boolean indicating whether the SV contains an unsigned integer.
4960
4961         bool    SvUOK(SV* sv)
4962
4963 =for hackers
4964 Found in file sv.h
4965
4966 =item SvUPGRADE
4967 X<SvUPGRADE>
4968
4969 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
4970 perform the upgrade if necessary.  See C<svtype>.
4971
4972         void    SvUPGRADE(SV* sv, svtype type)
4973
4974 =for hackers
4975 Found in file sv.h
4976
4977 =item SvUTF8
4978 X<SvUTF8>
4979
4980 Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
4981 Call this after SvPV() in case any call to string overloading updates the
4982 internal flag.
4983
4984         U32     SvUTF8(SV* sv)
4985
4986 =for hackers
4987 Found in file sv.h
4988
4989 =item SvUTF8_off
4990 X<SvUTF8_off>
4991
4992 Unsets the UTF-8 status of an SV.
4993
4994         void    SvUTF8_off(SV *sv)
4995
4996 =for hackers
4997 Found in file sv.h
4998
4999 =item SvUTF8_on
5000 X<SvUTF8_on>
5001
5002 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
5003 Do not use frivolously.
5004
5005         void    SvUTF8_on(SV *sv)
5006
5007 =for hackers
5008 Found in file sv.h
5009
5010 =item SvUV
5011 X<SvUV>
5012
5013 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
5014 for a version which guarantees to evaluate sv only once.
5015
5016         UV      SvUV(SV* sv)
5017
5018 =for hackers
5019 Found in file sv.h
5020
5021 =item SvUVX
5022 X<SvUVX>
5023
5024 Returns the raw value in the SV's UV slot, without checks or conversions.
5025 Only use when you are sure SvIOK is true. See also C<SvUV()>.
5026
5027         UV      SvUVX(SV* sv)
5028
5029 =for hackers
5030 Found in file sv.h
5031
5032 =item SvUVx
5033 X<SvUVx>
5034
5035 Coerces the given SV to an unsigned integer and returns it. Guarantees to
5036 C<sv> only once. Only use this if C<sv> is an expression with side effects,
5037 otherwise use the more efficient C<SvUV>.
5038
5039         UV      SvUVx(SV* sv)
5040
5041 =for hackers
5042 Found in file sv.h
5043
5044 =item SvUV_nomg
5045 X<SvUV_nomg>
5046
5047 Like C<SvUV> but doesn't process magic.
5048
5049         UV      SvUV_nomg(SV* sv)
5050
5051 =for hackers
5052 Found in file sv.h
5053
5054 =item SvUV_set
5055 X<SvUV_set>
5056
5057 Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
5058
5059         void    SvUV_set(SV* sv, UV val)
5060
5061 =for hackers
5062 Found in file sv.h
5063
5064 =item SvVOK
5065 X<SvVOK>
5066
5067 Returns a boolean indicating whether the SV contains a v-string.
5068
5069         bool    SvVOK(SV* sv)
5070
5071 =for hackers
5072 Found in file sv.h
5073
5074 =item sv_catpvn_nomg
5075 X<sv_catpvn_nomg>
5076
5077 Like C<sv_catpvn> but doesn't process magic.
5078
5079         void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
5080
5081 =for hackers
5082 Found in file sv.h
5083
5084 =item sv_catsv_nomg
5085 X<sv_catsv_nomg>
5086
5087 Like C<sv_catsv> but doesn't process magic.
5088
5089         void    sv_catsv_nomg(SV* dsv, SV* ssv)
5090
5091 =for hackers
5092 Found in file sv.h
5093
5094 =item sv_derived_from
5095 X<sv_derived_from>
5096
5097 Returns a boolean indicating whether the SV is derived from the specified class
5098 I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
5099 normal Perl method.
5100
5101         bool    sv_derived_from(SV* sv, const char *const name)
5102
5103 =for hackers
5104 Found in file universal.c
5105
5106 =item sv_does
5107 X<sv_does>
5108
5109 Returns a boolean indicating whether the SV performs a specific, named role.
5110 The SV can be a Perl object or the name of a Perl class.
5111
5112         bool    sv_does(SV* sv, const char *const name)
5113
5114 =for hackers
5115 Found in file universal.c
5116
5117 =item sv_report_used
5118 X<sv_report_used>
5119
5120 Dump the contents of all SVs not yet freed. (Debugging aid).
5121
5122         void    sv_report_used()
5123
5124 =for hackers
5125 Found in file sv.c
5126
5127 =item sv_setsv_nomg
5128 X<sv_setsv_nomg>
5129
5130 Like C<sv_setsv> but doesn't process magic.
5131
5132         void    sv_setsv_nomg(SV* dsv, SV* ssv)
5133
5134 =for hackers
5135 Found in file sv.h
5136
5137 =item sv_utf8_upgrade_nomg
5138 X<sv_utf8_upgrade_nomg>
5139
5140 Like sv_utf8_upgrade, but doesn't do magic on C<sv>
5141
5142         STRLEN  sv_utf8_upgrade_nomg(NN SV *sv)
5143
5144 =for hackers
5145 Found in file sv.h
5146
5147
5148 =back
5149
5150 =head1 SV-Body Allocation
5151
5152 =over 8
5153
5154 =item looks_like_number
5155 X<looks_like_number>
5156
5157 Test if the content of an SV looks like a number (or is a number).
5158 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
5159 non-numeric warning), even if your atof() doesn't grok them.
5160
5161         I32     looks_like_number(SV *const sv)
5162
5163 =for hackers
5164 Found in file sv.c
5165
5166 =item newRV_noinc
5167 X<newRV_noinc>
5168
5169 Creates an RV wrapper for an SV.  The reference count for the original
5170 SV is B<not> incremented.
5171
5172         SV*     newRV_noinc(SV *const sv)
5173
5174 =for hackers
5175 Found in file sv.c
5176
5177 =item newSV
5178 X<newSV>
5179
5180 Creates a new SV.  A non-zero C<len> parameter indicates the number of
5181 bytes of preallocated string space the SV should have.  An extra byte for a
5182 trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
5183 space is allocated.)  The reference count for the new SV is set to 1.
5184
5185 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5186 parameter, I<x>, a debug aid which allowed callers to identify themselves.
5187 This aid has been superseded by a new build option, PERL_MEM_LOG (see
5188 L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
5189 modules supporting older perls.
5190
5191         SV*     newSV(const STRLEN len)
5192
5193 =for hackers
5194 Found in file sv.c
5195
5196 =item newSVhek
5197 X<newSVhek>
5198
5199 Creates a new SV from the hash key structure.  It will generate scalars that
5200 point to the shared string table where possible. Returns a new (undefined)
5201 SV if the hek is NULL.
5202
5203         SV*     newSVhek(const HEK *const hek)
5204
5205 =for hackers
5206 Found in file sv.c
5207
5208 =item newSViv
5209 X<newSViv>
5210
5211 Creates a new SV and copies an integer into it.  The reference count for the
5212 SV is set to 1.
5213
5214         SV*     newSViv(const IV i)
5215
5216 =for hackers
5217 Found in file sv.c
5218
5219 =item newSVnv
5220 X<newSVnv>
5221
5222 Creates a new SV and copies a floating point value into it.
5223 The reference count for the SV is set to 1.
5224
5225         SV*     newSVnv(const NV n)
5226
5227 =for hackers
5228 Found in file sv.c
5229
5230 =item newSVpv
5231 X<newSVpv>
5232
5233 Creates a new SV and copies a string into it.  The reference count for the
5234 SV is set to 1.  If C<len> is zero, Perl will compute the length using
5235 strlen().  For efficiency, consider using C<newSVpvn> instead.
5236
5237         SV*     newSVpv(const char *const s, const STRLEN len)
5238
5239 =for hackers
5240 Found in file sv.c
5241
5242 =item newSVpvf
5243 X<newSVpvf>
5244
5245 Creates a new SV and initializes it with the string formatted like
5246 C<sprintf>.
5247
5248         SV*     newSVpvf(const char *const pat, ...)
5249
5250 =for hackers
5251 Found in file sv.c
5252
5253 =item newSVpvn
5254 X<newSVpvn>
5255
5256 Creates a new SV and copies a string into it.  The reference count for the
5257 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5258 string.  You are responsible for ensuring that the source string is at least
5259 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5260
5261         SV*     newSVpvn(const char *const s, const STRLEN len)
5262
5263 =for hackers
5264 Found in file sv.c
5265
5266 =item newSVpvn_flags
5267 X<newSVpvn_flags>
5268
5269 Creates a new SV and copies a string into it.  The reference count for the
5270 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5271 string.  You are responsible for ensuring that the source string is at least
5272 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5273 Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
5274 If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
5275 returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
5276 C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
5277
5278     #define newSVpvn_utf8(s, len, u)                    \
5279         newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
5280
5281         SV*     newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
5282
5283 =for hackers
5284 Found in file sv.c
5285
5286 =item newSVpvn_share
5287 X<newSVpvn_share>
5288
5289 Creates a new SV with its SvPVX_const pointing to a shared string in the string
5290 table. If the string does not already exist in the table, it is created
5291 first.  Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
5292 value is used; otherwise the hash is computed. The string's hash can be later
5293 be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
5294 that as the string table is used for shared hash keys these strings will have
5295 SvPVX_const == HeKEY and hash lookup will avoid string compare.
5296
5297         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
5298
5299 =for hackers
5300 Found in file sv.c
5301
5302 =item newSVpvs
5303 X<newSVpvs>
5304
5305 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5306
5307         SV*     newSVpvs(const char* s)
5308
5309 =for hackers
5310 Found in file handy.h
5311
5312 =item newSVpvs_flags
5313 X<newSVpvs_flags>
5314
5315 Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
5316 pair.
5317
5318         SV*     newSVpvs_flags(const char* s, U32 flags)
5319
5320 =for hackers
5321 Found in file handy.h
5322
5323 =item newSVpvs_share
5324 X<newSVpvs_share>
5325
5326 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5327 pair and omits the hash parameter.
5328
5329         SV*     newSVpvs_share(const char* s)
5330
5331 =for hackers
5332 Found in file handy.h
5333
5334 =item newSVrv
5335 X<newSVrv>
5336
5337 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
5338 it will be upgraded to one.  If C<classname> is non-null then the new SV will
5339 be blessed in the specified package.  The new SV is returned and its
5340 reference count is 1.
5341
5342         SV*     newSVrv(SV *const rv, const char *const classname)
5343
5344 =for hackers
5345 Found in file sv.c
5346
5347 =item newSVsv
5348 X<newSVsv>
5349
5350 Creates a new SV which is an exact duplicate of the original SV.
5351 (Uses C<sv_setsv>).
5352
5353         SV*     newSVsv(SV *const old)
5354
5355 =for hackers
5356 Found in file sv.c
5357
5358 =item newSVuv
5359 X<newSVuv>
5360
5361 Creates a new SV and copies an unsigned integer into it.
5362 The reference count for the SV is set to 1.
5363
5364         SV*     newSVuv(const UV u)
5365
5366 =for hackers
5367 Found in file sv.c
5368
5369 =item newSV_type
5370 X<newSV_type>
5371
5372 Creates a new SV, of the type specified.  The reference count for the new SV
5373 is set to 1.
5374
5375         SV*     newSV_type(const svtype type)
5376
5377 =for hackers
5378 Found in file sv.c
5379
5380 =item sv_2bool
5381 X<sv_2bool>
5382
5383 This function is only called on magical items, and is only used by
5384 sv_true() or its macro equivalent.
5385
5386         bool    sv_2bool(SV *const sv)
5387
5388 =for hackers
5389 Found in file sv.c
5390
5391 =item sv_2cv
5392 X<sv_2cv>
5393
5394 Using various gambits, try to get a CV from an SV; in addition, try if
5395 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5396 The flags in C<lref> are passed to sv_fetchsv.
5397
5398         CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
5399
5400 =for hackers
5401 Found in file sv.c
5402
5403 =item sv_2io
5404 X<sv_2io>
5405
5406 Using various gambits, try to get an IO from an SV: the IO slot if its a
5407 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5408 named after the PV if we're a string.
5409
5410         IO*     sv_2io(SV *const sv)
5411
5412 =for hackers
5413 Found in file sv.c
5414
5415 =item sv_2iv_flags
5416 X<sv_2iv_flags>
5417
5418 Return the integer value of an SV, doing any necessary string
5419 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5420 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5421
5422         IV      sv_2iv_flags(SV *const sv, const I32 flags)
5423
5424 =for hackers
5425 Found in file sv.c
5426
5427 =item sv_2mortal
5428 X<sv_2mortal>
5429
5430 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
5431 by an explicit call to FREETMPS, or by an implicit call at places such as
5432 statement boundaries.  SvTEMP() is turned on which means that the SV's
5433 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5434 and C<sv_mortalcopy>.
5435
5436         SV*     sv_2mortal(SV *const sv)
5437
5438 =for hackers
5439 Found in file sv.c
5440
5441 =item sv_2nv
5442 X<sv_2nv>
5443
5444 Return the num value of an SV, doing any necessary string or integer
5445 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5446 macros.
5447
5448         NV      sv_2nv(SV *const sv)
5449
5450 =for hackers
5451 Found in file sv.c
5452
5453 =item sv_2pvbyte
5454 X<sv_2pvbyte>
5455
5456 Return a pointer to the byte-encoded representation of the SV, and set *lp
5457 to its length.  May cause the SV to be downgraded from UTF-8 as a
5458 side-effect.
5459
5460 Usually accessed via the C<SvPVbyte> macro.
5461
5462         char*   sv_2pvbyte(SV *const sv, STRLEN *const lp)
5463
5464 =for hackers
5465 Found in file sv.c
5466
5467 =item sv_2pvutf8
5468 X<sv_2pvutf8>
5469
5470 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5471 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
5472
5473 Usually accessed via the C<SvPVutf8> macro.
5474
5475         char*   sv_2pvutf8(SV *const sv, STRLEN *const lp)
5476
5477 =for hackers
5478 Found in file sv.c
5479
5480 =item sv_2pv_flags
5481 X<sv_2pv_flags>
5482
5483 Returns a pointer to the string value of an SV, and sets *lp to its length.
5484 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5485 if necessary.
5486 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5487 usually end up here too.
5488
5489         char*   sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)
5490
5491 =for hackers
5492 Found in file sv.c
5493
5494 =item sv_2uv_flags
5495 X<sv_2uv_flags>
5496
5497 Return the unsigned integer value of an SV, doing any necessary string
5498 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5499 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5500
5501         UV      sv_2uv_flags(SV *const sv, const I32 flags)
5502
5503 =for hackers
5504 Found in file sv.c
5505
5506 =item sv_backoff
5507 X<sv_backoff>
5508
5509 Remove any string offset. You should normally use the C<SvOOK_off> macro
5510 wrapper instead.
5511
5512         int     sv_backoff(SV *const sv)
5513
5514 =for hackers
5515 Found in file sv.c
5516
5517 =item sv_bless
5518 X<sv_bless>
5519
5520 Blesses an SV into a specified package.  The SV must be an RV.  The package
5521 must be designated by its stash (see C<gv_stashpv()>).  The reference count
5522 of the SV is unaffected.
5523
5524         SV*     sv_bless(SV *const sv, HV *const stash)
5525
5526 =for hackers
5527 Found in file sv.c
5528
5529 =item sv_catpv
5530 X<sv_catpv>
5531
5532 Concatenates the string onto the end of the string which is in the SV.
5533 If the SV has the UTF-8 status set, then the bytes appended should be
5534 valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
5535
5536         void    sv_catpv(SV *const sv, const char* ptr)
5537
5538 =for hackers
5539 Found in file sv.c
5540
5541 =item sv_catpvf
5542 X<sv_catpvf>
5543
5544 Processes its arguments like C<sprintf> and appends the formatted
5545 output to an SV.  If the appended data contains "wide" characters
5546 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5547 and characters >255 formatted with %c), the original SV might get
5548 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
5549 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5550 valid UTF-8; if the original SV was bytes, the pattern should be too.
5551
5552         void    sv_catpvf(SV *const sv, const char *const pat, ...)
5553
5554 =for hackers
5555 Found in file sv.c
5556
5557 =item sv_catpvf_mg
5558 X<sv_catpvf_mg>
5559
5560 Like C<sv_catpvf>, but also handles 'set' magic.
5561
5562         void    sv_catpvf_mg(SV *const sv, const char *const pat, ...)
5563
5564 =for hackers
5565 Found in file sv.c
5566
5567 =item sv_catpvn
5568 X<sv_catpvn>
5569
5570 Concatenates the string onto the end of the string which is in the SV.  The
5571 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5572 status set, then the bytes appended should be valid UTF-8.
5573 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
5574
5575         void    sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
5576
5577 =for hackers
5578 Found in file sv.c
5579
5580 =item sv_catpvn_flags
5581 X<sv_catpvn_flags>
5582
5583 Concatenates the string onto the end of the string which is in the SV.  The
5584 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5585 status set, then the bytes appended should be valid UTF-8.
5586 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5587 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5588 in terms of this function.
5589
5590         void    sv_catpvn_flags(SV *const dstr, const char *sstr, const STRLEN len, const I32 flags)
5591
5592 =for hackers
5593 Found in file sv.c
5594
5595 =item sv_catpvs
5596 X<sv_catpvs>
5597
5598 Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5599
5600         void    sv_catpvs(SV* sv, const char* s)
5601
5602 =for hackers
5603 Found in file handy.h
5604
5605 =item sv_catpv_mg
5606 X<sv_catpv_mg>
5607
5608 Like C<sv_catpv>, but also handles 'set' magic.
5609
5610         void    sv_catpv_mg(SV *const sv, const char *const ptr)
5611
5612 =for hackers
5613 Found in file sv.c
5614
5615 =item sv_catsv
5616 X<sv_catsv>
5617
5618 Concatenates the string from SV C<ssv> onto the end of the string in
5619 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
5620 not 'set' magic.  See C<sv_catsv_mg>.
5621
5622         void    sv_catsv(SV *dstr, SV *sstr)
5623
5624 =for hackers
5625 Found in file sv.c
5626
5627 =item sv_catsv_flags
5628 X<sv_catsv_flags>
5629
5630 Concatenates the string from SV C<ssv> onto the end of the string in
5631 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
5632 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5633 and C<sv_catsv_nomg> are implemented in terms of this function.
5634
5635         void    sv_catsv_flags(SV *const dsv, SV *const ssv, const I32 flags)
5636
5637 =for hackers
5638 Found in file sv.c
5639
5640 =item sv_chop
5641 X<sv_chop>
5642
5643 Efficient removal of characters from the beginning of the string buffer.
5644 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5645 the string buffer.  The C<ptr> becomes the first character of the adjusted
5646 string. Uses the "OOK hack".
5647 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5648 refer to the same chunk of data.
5649
5650         void    sv_chop(SV *const sv, const char *const ptr)
5651
5652 =for hackers
5653 Found in file sv.c
5654
5655 =item sv_clear
5656 X<sv_clear>
5657
5658 Clear an SV: call any destructors, free up any memory used by the body,
5659 and free the body itself. The SV's head is I<not> freed, although
5660 its type is set to all 1's so that it won't inadvertently be assumed
5661 to be live during global destruction etc.
5662 This function should only be called when REFCNT is zero. Most of the time
5663 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5664 instead.
5665
5666         void    sv_clear(SV *const sv)
5667
5668 =for hackers
5669 Found in file sv.c
5670
5671 =item sv_cmp
5672 X<sv_cmp>
5673
5674 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
5675 string in C<sv1> is less than, equal to, or greater than the string in
5676 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5677 coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
5678
5679         I32     sv_cmp(SV *const sv1, SV *const sv2)
5680
5681 =for hackers
5682 Found in file sv.c
5683
5684 =item sv_cmp_locale
5685 X<sv_cmp_locale>
5686
5687 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5688 'use bytes' aware, handles get magic, and will coerce its args to strings
5689 if necessary.  See also C<sv_cmp>.
5690
5691         I32     sv_cmp_locale(SV *const sv1, SV *const sv2)
5692
5693 =for hackers
5694 Found in file sv.c
5695
5696 =item sv_collxfrm
5697 X<sv_collxfrm>
5698
5699 Add Collate Transform magic to an SV if it doesn't already have it.
5700
5701 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
5702 scalar data of the variable, but transformed to such a format that a normal
5703 memory comparison can be used to compare the data according to the locale
5704 settings.
5705
5706         char*   sv_collxfrm(SV *const sv, STRLEN *const nxp)
5707
5708 =for hackers
5709 Found in file sv.c
5710
5711 =item sv_copypv
5712 X<sv_copypv>
5713
5714 Copies a stringified representation of the source SV into the
5715 destination SV.  Automatically performs any necessary mg_get and
5716 coercion of numeric values into strings.  Guaranteed to preserve
5717 UTF8 flag even from overloaded objects.  Similar in nature to
5718 sv_2pv[_flags] but operates directly on an SV instead of just the
5719 string.  Mostly uses sv_2pv_flags to do its work, except when that
5720 would lose the UTF-8'ness of the PV.
5721
5722         void    sv_copypv(SV *const dsv, SV *const ssv)
5723
5724 =for hackers
5725 Found in file sv.c
5726
5727 =item sv_dec
5728 X<sv_dec>
5729
5730 Auto-decrement of the value in the SV, doing string to numeric conversion
5731 if necessary. Handles 'get' magic.
5732
5733         void    sv_dec(SV *const sv)
5734
5735 =for hackers
5736 Found in file sv.c
5737
5738 =item sv_eq
5739 X<sv_eq>
5740
5741 Returns a boolean indicating whether the strings in the two SVs are
5742 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5743 coerce its args to strings if necessary.
5744
5745         I32     sv_eq(SV* sv1, SV* sv2)
5746
5747 =for hackers
5748 Found in file sv.c
5749
5750 =item sv_force_normal_flags
5751 X<sv_force_normal_flags>
5752
5753 Undo various types of fakery on an SV: if the PV is a shared string, make
5754 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
5755 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
5756 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
5757 then a copy-on-write scalar drops its PV buffer (if any) and becomes
5758 SvPOK_off rather than making a copy. (Used where this scalar is about to be
5759 set to some other value.) In addition, the C<flags> parameter gets passed to
5760 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
5761 with flags set to 0.
5762
5763         void    sv_force_normal_flags(SV *const sv, const U32 flags)
5764
5765 =for hackers
5766 Found in file sv.c
5767
5768 =item sv_free
5769 X<sv_free>
5770
5771 Decrement an SV's reference count, and if it drops to zero, call
5772 C<sv_clear> to invoke destructors and free up any memory used by
5773 the body; finally, deallocate the SV's head itself.
5774 Normally called via a wrapper macro C<SvREFCNT_dec>.
5775
5776         void    sv_free(SV *const sv)
5777
5778 =for hackers
5779 Found in file sv.c
5780
5781 =item sv_gets
5782 X<sv_gets>
5783
5784 Get a line from the filehandle and store it into the SV, optionally
5785 appending to the currently-stored string.
5786
5787         char*   sv_gets(SV *const sv, PerlIO *const fp, I32 append)
5788
5789 =for hackers
5790 Found in file sv.c
5791
5792 =item sv_grow
5793 X<sv_grow>
5794
5795 Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
5796 upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
5797 Use the C<SvGROW> wrapper instead.
5798
5799         char*   sv_grow(SV *const sv, STRLEN newlen)
5800
5801 =for hackers
5802 Found in file sv.c
5803
5804 =item sv_inc
5805 X<sv_inc>
5806
5807 Auto-increment of the value in the SV, doing string to numeric conversion
5808 if necessary. Handles 'get' magic.
5809
5810         void    sv_inc(SV *const sv)
5811
5812 =for hackers
5813 Found in file sv.c
5814
5815 =item sv_insert
5816 X<sv_insert>
5817
5818 Inserts a string at the specified offset/length within the SV. Similar to
5819 the Perl substr() function. Handles get magic.
5820
5821         void    sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)
5822
5823 =for hackers
5824 Found in file sv.c
5825
5826 =item sv_insert_flags
5827 X<sv_insert_flags>
5828
5829 Same as C<sv_insert>, but the extra C<flags> are passed the C<SvPV_force_flags> that applies to C<bigstr>.
5830
5831         void    sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
5832
5833 =for hackers
5834 Found in file sv.c
5835
5836 =item sv_isa
5837 X<sv_isa>
5838
5839 Returns a boolean indicating whether the SV is blessed into the specified
5840 class.  This does not check for subtypes; use C<sv_derived_from> to verify
5841 an inheritance relationship.
5842
5843         int     sv_isa(SV* sv, const char *const name)
5844
5845 =for hackers
5846 Found in file sv.c
5847
5848 =item sv_isobject
5849 X<sv_isobject>
5850
5851 Returns a boolean indicating whether the SV is an RV pointing to a blessed
5852 object.  If the SV is not an RV, or if the object is not blessed, then this
5853 will return false.
5854
5855         int     sv_isobject(SV* sv)
5856
5857 =for hackers
5858 Found in file sv.c
5859
5860 =item sv_len
5861 X<sv_len>
5862
5863 Returns the length of the string in the SV. Handles magic and type
5864 coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
5865
5866         STRLEN  sv_len(SV *const sv)
5867
5868 =for hackers
5869 Found in file sv.c
5870
5871 =item sv_len_utf8
5872 X<sv_len_utf8>
5873
5874 Returns the number of characters in the string in an SV, counting wide
5875 UTF-8 bytes as a single character. Handles magic and type coercion.
5876
5877         STRLEN  sv_len_utf8(SV *const sv)
5878
5879 =for hackers
5880 Found in file sv.c
5881
5882 =item sv_magic
5883 X<sv_magic>
5884
5885 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
5886 then adds a new magic item of type C<how> to the head of the magic list.
5887
5888 See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
5889 handling of the C<name> and C<namlen> arguments.
5890
5891 You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
5892 to add more than one instance of the same 'how'.
5893
5894         void    sv_magic(SV *const sv, SV *const obj, const int how, const char *const name, const I32 namlen)
5895
5896 =for hackers
5897 Found in file sv.c
5898
5899 =item sv_magicext
5900 X<sv_magicext>
5901
5902 Adds magic to an SV, upgrading it if necessary. Applies the
5903 supplied vtable and returns a pointer to the magic added.
5904
5905 Note that C<sv_magicext> will allow things that C<sv_magic> will not.
5906 In particular, you can add magic to SvREADONLY SVs, and add more than
5907 one instance of the same 'how'.
5908
5909 If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
5910 stored, if C<namlen> is zero then C<name> is stored as-is and - as another
5911 special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
5912 to contain an C<SV*> and is stored as-is with its REFCNT incremented.
5913
5914 (This is now used as a subroutine by C<sv_magic>.)
5915
5916         MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how, const MGVTBL *const vtbl, const char *const name, const I32 namlen)
5917
5918 =for hackers
5919 Found in file sv.c
5920
5921 =item sv_mortalcopy
5922 X<sv_mortalcopy>
5923
5924 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
5925 The new SV is marked as mortal. It will be destroyed "soon", either by an
5926 explicit call to FREETMPS, or by an implicit call at places such as
5927 statement boundaries.  See also C<sv_newmortal> and C<sv_2mortal>.
5928
5929         SV*     sv_mortalcopy(SV *const oldsv)
5930
5931 =for hackers
5932 Found in file sv.c
5933
5934 =item sv_newmortal
5935 X<sv_newmortal>
5936
5937 Creates a new null SV which is mortal.  The reference count of the SV is
5938 set to 1. It will be destroyed "soon", either by an explicit call to
5939 FREETMPS, or by an implicit call at places such as statement boundaries.
5940 See also C<sv_mortalcopy> and C<sv_2mortal>.
5941
5942         SV*     sv_newmortal()
5943
5944 =for hackers
5945 Found in file sv.c
5946
5947 =item sv_newref
5948 X<sv_newref>
5949
5950 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
5951 instead.
5952
5953         SV*     sv_newref(SV *const sv)
5954
5955 =for hackers
5956 Found in file sv.c
5957
5958 =item sv_pos_b2u
5959 X<sv_pos_b2u>
5960
5961 Converts the value pointed to by offsetp from a count of bytes from the
5962 start of the string, to a count of the equivalent number of UTF-8 chars.
5963 Handles magic and type coercion.
5964
5965         void    sv_pos_b2u(SV *const sv, I32 *const offsetp)
5966
5967 =for hackers
5968 Found in file sv.c
5969
5970 =item sv_pos_u2b
5971 X<sv_pos_u2b>
5972
5973 Converts the value pointed to by offsetp from a count of UTF-8 chars from
5974 the start of the string, to a count of the equivalent number of bytes; if
5975 lenp is non-zero, it does the same to lenp, but this time starting from
5976 the offset, rather than from the start of the string. Handles magic and
5977 type coercion.
5978
5979         void    sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp)
5980
5981 =for hackers
5982 Found in file sv.c
5983
5984 =item sv_pvbyten_force
5985 X<sv_pvbyten_force>
5986
5987 The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
5988
5989         char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)
5990
5991 =for hackers
5992 Found in file sv.c
5993
5994 =item sv_pvn_force
5995 X<sv_pvn_force>
5996
5997 Get a sensible string out of the SV somehow.
5998 A private implementation of the C<SvPV_force> macro for compilers which
5999 can't cope with complex macro expressions. Always use the macro instead.
6000
6001         char*   sv_pvn_force(SV* sv, STRLEN* lp)
6002
6003 =for hackers
6004 Found in file sv.c
6005
6006 =item sv_pvn_force_flags
6007 X<sv_pvn_force_flags>
6008
6009 Get a sensible string out of the SV somehow.
6010 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
6011 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
6012 implemented in terms of this function.
6013 You normally want to use the various wrapper macros instead: see
6014 C<SvPV_force> and C<SvPV_force_nomg>
6015
6016         char*   sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)
6017
6018 =for hackers
6019 Found in file sv.c
6020
6021 =item sv_pvutf8n_force
6022 X<sv_pvutf8n_force>
6023
6024 The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
6025
6026         char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
6027
6028 =for hackers
6029 Found in file sv.c
6030
6031 =item sv_reftype
6032 X<sv_reftype>
6033
6034 Returns a string describing what the SV is a reference to.
6035
6036         const char*     sv_reftype(const SV *const sv, const int ob)
6037
6038 =for hackers
6039 Found in file sv.c
6040
6041 =item sv_replace
6042 X<sv_replace>
6043
6044 Make the first argument a copy of the second, then delete the original.
6045 The target SV physically takes over ownership of the body of the source SV
6046 and inherits its flags; however, the target keeps any magic it owns,
6047 and any magic in the source is discarded.
6048 Note that this is a rather specialist SV copying operation; most of the
6049 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
6050
6051         void    sv_replace(SV *const sv, SV *const nsv)
6052
6053 =for hackers
6054 Found in file sv.c
6055
6056 =item sv_reset
6057 X<sv_reset>
6058
6059 Underlying implementation for the C<reset> Perl function.
6060 Note that the perl-level function is vaguely deprecated.
6061
6062         void    sv_reset(const char* s, HV *const stash)
6063
6064 =for hackers
6065 Found in file sv.c
6066
6067 =item sv_rvweaken
6068 X<sv_rvweaken>
6069
6070 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
6071 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
6072 push a back-reference to this RV onto the array of backreferences
6073 associated with that magic. If the RV is magical, set magic will be
6074 called after the RV is cleared.
6075
6076         SV*     sv_rvweaken(SV *const sv)
6077
6078 =for hackers
6079 Found in file sv.c
6080
6081 =item sv_setiv
6082 X<sv_setiv>
6083
6084 Copies an integer into the given SV, upgrading first if necessary.
6085 Does not handle 'set' magic.  See also C<sv_setiv_mg>.
6086
6087         void    sv_setiv(SV *const sv, const IV num)
6088
6089 =for hackers
6090 Found in file sv.c
6091
6092 =item sv_setiv_mg
6093 X<sv_setiv_mg>
6094
6095 Like C<sv_setiv>, but also handles 'set' magic.
6096
6097         void    sv_setiv_mg(SV *const sv, const IV i)
6098
6099 =for hackers
6100 Found in file sv.c
6101
6102 =item sv_setnv
6103 X<sv_setnv>
6104
6105 Copies a double into the given SV, upgrading first if necessary.
6106 Does not handle 'set' magic.  See also C<sv_setnv_mg>.
6107
6108         void    sv_setnv(SV *const sv, const NV num)
6109
6110 =for hackers
6111 Found in file sv.c
6112
6113 =item sv_setnv_mg
6114 X<sv_setnv_mg>
6115
6116 Like C<sv_setnv>, but also handles 'set' magic.
6117
6118         void    sv_setnv_mg(SV *const sv, const NV num)
6119
6120 =for hackers
6121 Found in file sv.c
6122
6123 =item sv_setpv
6124 X<sv_setpv>
6125
6126 Copies a string into an SV.  The string must be null-terminated.  Does not
6127 handle 'set' magic.  See C<sv_setpv_mg>.
6128
6129         void    sv_setpv(SV *const sv, const char *const ptr)
6130
6131 =for hackers
6132 Found in file sv.c
6133
6134 =item sv_setpvf
6135 X<sv_setpvf>
6136
6137 Works like C<sv_catpvf> but copies the text into the SV instead of
6138 appending it.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
6139
6140         void    sv_setpvf(SV *const sv, const char *const pat, ...)
6141
6142 =for hackers
6143 Found in file sv.c
6144
6145 =item sv_setpvf_mg
6146 X<sv_setpvf_mg>
6147
6148 Like C<sv_setpvf>, but also handles 'set' magic.
6149
6150         void    sv_setpvf_mg(SV *const sv, const char *const pat, ...)
6151
6152 =for hackers
6153 Found in file sv.c
6154
6155 =item sv_setpviv
6156 X<sv_setpviv>
6157
6158 Copies an integer into the given SV, also updating its string value.
6159 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
6160
6161         void    sv_setpviv(SV *const sv, const IV num)
6162
6163 =for hackers
6164 Found in file sv.c
6165
6166 =item sv_setpviv_mg
6167 X<sv_setpviv_mg>
6168
6169 Like C<sv_setpviv>, but also handles 'set' magic.
6170
6171         void    sv_setpviv_mg(SV *const sv, const IV iv)
6172
6173 =for hackers
6174 Found in file sv.c
6175
6176 =item sv_setpvn
6177 X<sv_setpvn>
6178
6179 Copies a string into an SV.  The C<len> parameter indicates the number of
6180 bytes to be copied.  If the C<ptr> argument is NULL the SV will become
6181 undefined.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
6182
6183         void    sv_setpvn(SV *const sv, const char *const ptr, const STRLEN len)
6184
6185 =for hackers
6186 Found in file sv.c
6187
6188 =item sv_setpvn_mg
6189 X<sv_setpvn_mg>
6190
6191 Like C<sv_setpvn>, but also handles 'set' magic.
6192
6193         void    sv_setpvn_mg(SV *const sv, const char *const ptr, const STRLEN len)
6194
6195 =for hackers
6196 Found in file sv.c
6197
6198 =item sv_setpvs
6199 X<sv_setpvs>
6200
6201 Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
6202
6203         void    sv_setpvs(SV* sv, const char* s)
6204
6205 =for hackers
6206 Found in file handy.h
6207
6208 =item sv_setpv_mg
6209 X<sv_setpv_mg>
6210
6211 Like C<sv_setpv>, but also handles 'set' magic.
6212
6213         void    sv_setpv_mg(SV *const sv, const char *const ptr)
6214
6215 =for hackers
6216 Found in file sv.c
6217
6218 =item sv_setref_iv
6219 X<sv_setref_iv>
6220
6221 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
6222 argument will be upgraded to an RV.  That RV will be modified to point to
6223 the new SV.  The C<classname> argument indicates the package for the
6224 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6225 will have a reference count of 1, and the RV will be returned.
6226
6227         SV*     sv_setref_iv(SV *const rv, const char *const classname, const IV iv)
6228
6229 =for hackers
6230 Found in file sv.c
6231
6232 =item sv_setref_nv
6233 X<sv_setref_nv>
6234
6235 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
6236 argument will be upgraded to an RV.  That RV will be modified to point to
6237 the new SV.  The C<classname> argument indicates the package for the
6238 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6239 will have a reference count of 1, and the RV will be returned.
6240
6241         SV*     sv_setref_nv(SV *const rv, const char *const classname, const NV nv)
6242
6243 =for hackers
6244 Found in file sv.c
6245
6246 =item sv_setref_pv
6247 X<sv_setref_pv>
6248
6249 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
6250 argument will be upgraded to an RV.  That RV will be modified to point to
6251 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
6252 into the SV.  The C<classname> argument indicates the package for the
6253 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6254 will have a reference count of 1, and the RV will be returned.
6255
6256 Do not use with other Perl types such as HV, AV, SV, CV, because those
6257 objects will become corrupted by the pointer copy process.
6258
6259 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
6260
6261         SV*     sv_setref_pv(SV *const rv, const char *const classname, void *const pv)
6262
6263 =for hackers
6264 Found in file sv.c
6265
6266 =item sv_setref_pvn
6267 X<sv_setref_pvn>
6268
6269 Copies a string into a new SV, optionally blessing the SV.  The length of the
6270 string must be specified with C<n>.  The C<rv> argument will be upgraded to
6271 an RV.  That RV will be modified to point to the new SV.  The C<classname>
6272 argument indicates the package for the blessing.  Set C<classname> to
6273 C<NULL> to avoid the blessing.  The new SV will have a reference count
6274 of 1, and the RV will be returned.
6275
6276 Note that C<sv_setref_pv> copies the pointer while this copies the string.
6277
6278         SV*     sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)
6279
6280 =for hackers
6281 Found in file sv.c
6282
6283 =item sv_setref_uv
6284 X<sv_setref_uv>
6285
6286 Copies an unsigned integer into a new SV, optionally blessing the SV.  The C<rv>
6287 argument will be upgraded to an RV.  That RV will be modified to point to
6288 the new SV.  The C<classname> argument indicates the package for the
6289 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
6290 will have a reference count of 1, and the RV will be returned.
6291
6292         SV*     sv_setref_uv(SV *const rv, const char *const classname, const UV uv)
6293
6294 =for hackers
6295 Found in file sv.c
6296
6297 =item sv_setsv
6298 X<sv_setsv>
6299
6300 Copies the contents of the source SV C<ssv> into the destination SV
6301 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
6302 function if the source SV needs to be reused. Does not handle 'set' magic.
6303 Loosely speaking, it performs a copy-by-value, obliterating any previous
6304 content of the destination.
6305
6306 You probably want to use one of the assortment of wrappers, such as
6307 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6308 C<SvSetMagicSV_nosteal>.
6309
6310         void    sv_setsv(SV *dstr, SV *sstr)
6311
6312 =for hackers
6313 Found in file sv.c
6314
6315 =item sv_setsv_flags
6316 X<sv_setsv_flags>
6317
6318 Copies the contents of the source SV C<ssv> into the destination SV
6319 C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
6320 function if the source SV needs to be reused. Does not handle 'set' magic.
6321 Loosely speaking, it performs a copy-by-value, obliterating any previous
6322 content of the destination.
6323 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
6324 C<ssv> if appropriate, else not. If the C<flags> parameter has the
6325 C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
6326 and C<sv_setsv_nomg> are implemented in terms of this function.
6327
6328 You probably want to use one of the assortment of wrappers, such as
6329 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6330 C<SvSetMagicSV_nosteal>.
6331
6332 This is the primary function for copying scalars, and most other
6333 copy-ish functions and macros use this underneath.
6334
6335         void    sv_setsv_flags(SV *dstr, SV *sstr, const I32 flags)
6336
6337 =for hackers
6338 Found in file sv.c
6339
6340 =item sv_setsv_mg
6341 X<sv_setsv_mg>
6342
6343 Like C<sv_setsv>, but also handles 'set' magic.
6344
6345         void    sv_setsv_mg(SV *const dstr, SV *const sstr)
6346
6347 =for hackers
6348 Found in file sv.c
6349
6350 =item sv_setuv
6351 X<sv_setuv>
6352
6353 Copies an unsigned integer into the given SV, upgrading first if necessary.
6354 Does not handle 'set' magic.  See also C<sv_setuv_mg>.
6355
6356         void    sv_setuv(SV *const sv, const UV num)
6357
6358 =for hackers
6359 Found in file sv.c
6360
6361 =item sv_setuv_mg
6362 X<sv_setuv_mg>
6363
6364 Like C<sv_setuv>, but also handles 'set' magic.
6365
6366         void    sv_setuv_mg(SV *const sv, const UV u)
6367
6368 =for hackers
6369 Found in file sv.c
6370
6371 =item sv_tainted
6372 X<sv_tainted>
6373
6374 Test an SV for taintedness. Use C<SvTAINTED> instead.
6375         bool    sv_tainted(SV *const sv)
6376
6377 =for hackers
6378 Found in file sv.c
6379
6380 =item sv_true
6381 X<sv_true>
6382
6383 Returns true if the SV has a true value by Perl's rules.
6384 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
6385 instead use an in-line version.
6386
6387         I32     sv_true(SV *const sv)
6388
6389 =for hackers
6390 Found in file sv.c
6391
6392 =item sv_unmagic
6393 X<sv_unmagic>
6394
6395 Removes all magic of type C<type> from an SV.
6396
6397         int     sv_unmagic(SV *const sv, const int type)
6398
6399 =for hackers
6400 Found in file sv.c
6401
6402 =item sv_unref_flags
6403 X<sv_unref_flags>
6404
6405 Unsets the RV status of the SV, and decrements the reference count of
6406 whatever was being referenced by the RV.  This can almost be thought of
6407 as a reversal of C<newSVrv>.  The C<cflags> argument can contain
6408 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
6409 (otherwise the decrementing is conditional on the reference count being
6410 different from one or the reference being a readonly SV).
6411 See C<SvROK_off>.
6412
6413         void    sv_unref_flags(SV *const ref, const U32 flags)
6414
6415 =for hackers
6416 Found in file sv.c
6417
6418 =item sv_untaint
6419 X<sv_untaint>
6420
6421 Untaint an SV. Use C<SvTAINTED_off> instead.
6422         void    sv_untaint(SV *const sv)
6423
6424 =for hackers
6425 Found in file sv.c
6426
6427 =item sv_upgrade
6428 X<sv_upgrade>
6429
6430 Upgrade an SV to a more complex form.  Generally adds a new body type to the
6431 SV, then copies across as much information as possible from the old body.
6432 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
6433
6434         void    sv_upgrade(SV *const sv, svtype new_type)
6435
6436 =for hackers
6437 Found in file sv.c
6438
6439 =item sv_usepvn_flags
6440 X<sv_usepvn_flags>
6441
6442 Tells an SV to use C<ptr> to find its string value.  Normally the
6443 string is stored inside the SV but sv_usepvn allows the SV to use an
6444 outside string.  The C<ptr> should point to memory that was allocated
6445 by C<malloc>.  The string length, C<len>, must be supplied.  By default
6446 this function will realloc (i.e. move) the memory pointed to by C<ptr>,
6447 so that pointer should not be freed or used by the programmer after
6448 giving it to sv_usepvn, and neither should any pointers from "behind"
6449 that pointer (e.g. ptr + 1) be used.
6450
6451 If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
6452 SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
6453 will be skipped. (i.e. the buffer is actually at least 1 byte longer than
6454 C<len>, and already meets the requirements for storing in C<SvPVX>)
6455
6456         void    sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags)
6457
6458 =for hackers
6459 Found in file sv.c
6460
6461 =item sv_utf8_decode
6462 X<sv_utf8_decode>
6463
6464 If the PV of the SV is an octet sequence in UTF-8
6465 and contains a multiple-byte character, the C<SvUTF8> flag is turned on
6466 so that it looks like a character. If the PV contains only single-byte
6467 characters, the C<SvUTF8> flag stays being off.
6468 Scans PV for validity and returns false if the PV is invalid UTF-8.
6469
6470 NOTE: this function is experimental and may change or be
6471 removed without notice.
6472
6473         bool    sv_utf8_decode(SV *const sv)
6474
6475 =for hackers
6476 Found in file sv.c
6477
6478 =item sv_utf8_downgrade
6479 X<sv_utf8_downgrade>
6480
6481 Attempts to convert the PV of an SV from characters to bytes.
6482 If the PV contains a character that cannot fit
6483 in a byte, this conversion will fail;
6484 in this case, either returns false or, if C<fail_ok> is not
6485 true, croaks.
6486
6487 This is not as a general purpose Unicode to byte encoding interface:
6488 use the Encode extension for that.
6489
6490 NOTE: this function is experimental and may change or be
6491 removed without notice.
6492
6493         bool    sv_utf8_downgrade(SV *const sv, const bool fail_ok)
6494
6495 =for hackers
6496 Found in file sv.c
6497
6498 =item sv_utf8_encode
6499 X<sv_utf8_encode>
6500
6501 Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
6502 flag off so that it looks like octets again.
6503
6504         void    sv_utf8_encode(SV *const sv)
6505
6506 =for hackers
6507 Found in file sv.c
6508
6509 =item sv_utf8_upgrade
6510 X<sv_utf8_upgrade>
6511
6512 Converts the PV of an SV to its UTF-8-encoded form.
6513 Forces the SV to string form if it is not already.
6514 Will C<mg_get> on C<sv> if appropriate.
6515 Always sets the SvUTF8 flag to avoid future validity checks even
6516 if the whole string is the same in UTF-8 as not.
6517 Returns the number of bytes in the converted string
6518
6519 This is not as a general purpose byte encoding to Unicode interface:
6520 use the Encode extension for that.
6521
6522         STRLEN  sv_utf8_upgrade(SV *sv)
6523
6524 =for hackers
6525 Found in file sv.c
6526
6527 =item sv_utf8_upgrade_flags
6528 X<sv_utf8_upgrade_flags>
6529
6530 Converts the PV of an SV to its UTF-8-encoded form.
6531 Forces the SV to string form if it is not already.
6532 Always sets the SvUTF8 flag to avoid future validity checks even
6533 if all the bytes are invariant in UTF-8. If C<flags> has C<SV_GMAGIC> bit set,
6534 will C<mg_get> on C<sv> if appropriate, else not.
6535 Returns the number of bytes in the converted string
6536 C<sv_utf8_upgrade> and
6537 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
6538
6539 This is not as a general purpose byte encoding to Unicode interface:
6540 use the Encode extension for that.
6541
6542         STRLEN  sv_utf8_upgrade_flags(SV *const sv, const I32 flags)
6543
6544 =for hackers
6545 Found in file sv.c
6546
6547 =item sv_utf8_upgrade_nomg
6548 X<sv_utf8_upgrade_nomg>
6549
6550 Like sv_utf8_upgrade, but doesn't do magic on C<sv>
6551
6552         STRLEN  sv_utf8_upgrade_nomg(SV *sv)
6553
6554 =for hackers
6555 Found in file sv.c
6556
6557 =item sv_vcatpvf
6558 X<sv_vcatpvf>
6559
6560 Processes its arguments like C<vsprintf> and appends the formatted output
6561 to an SV.  Does not handle 'set' magic.  See C<sv_vcatpvf_mg>.
6562
6563 Usually used via its frontend C<sv_catpvf>.
6564
6565         void    sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)
6566
6567 =for hackers
6568 Found in file sv.c
6569
6570 =item sv_vcatpvfn
6571 X<sv_vcatpvfn>
6572
6573 Processes its arguments like C<vsprintf> and appends the formatted output
6574 to an SV.  Uses an array of SVs if the C style variable argument list is
6575 missing (NULL).  When running with taint checks enabled, indicates via
6576 C<maybe_tainted> if results are untrustworthy (often due to the use of
6577 locales).
6578
6579 Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
6580
6581         void    sv_vcatpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
6582
6583 =for hackers
6584 Found in file sv.c
6585
6586 =item sv_vcatpvf_mg
6587 X<sv_vcatpvf_mg>
6588
6589 Like C<sv_vcatpvf>, but also handles 'set' magic.
6590
6591 Usually used via its frontend C<sv_catpvf_mg>.
6592
6593         void    sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)
6594
6595 =for hackers
6596 Found in file sv.c
6597
6598 =item sv_vsetpvf
6599 X<sv_vsetpvf>
6600
6601 Works like C<sv_vcatpvf> but copies the text into the SV instead of
6602 appending it.  Does not handle 'set' magic.  See C<sv_vsetpvf_mg>.
6603
6604 Usually used via its frontend C<sv_setpvf>.
6605
6606         void    sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)
6607
6608 =for hackers
6609 Found in file sv.c
6610
6611 =item sv_vsetpvfn
6612 X<sv_vsetpvfn>
6613
6614 Works like C<sv_vcatpvfn> but copies the text into the SV instead of
6615 appending it.
6616
6617 Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
6618
6619         void    sv_vsetpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
6620
6621 =for hackers
6622 Found in file sv.c
6623
6624 =item sv_vsetpvf_mg
6625 X<sv_vsetpvf_mg>
6626
6627 Like C<sv_vsetpvf>, but also handles 'set' magic.
6628
6629 Usually used via its frontend C<sv_setpvf_mg>.
6630
6631         void    sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)
6632
6633 =for hackers
6634 Found in file sv.c
6635
6636
6637 =back
6638
6639 =head1 Unicode Support
6640
6641 =over 8
6642
6643 =item bytes_from_utf8
6644 X<bytes_from_utf8>
6645
6646 Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
6647 Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
6648 the newly-created string, and updates C<len> to contain the new
6649 length.  Returns the original string if no conversion occurs, C<len>
6650 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
6651 0 if C<s> is converted or consisted entirely of characters that are invariant
6652 in utf8 (i.e., US-ASCII on non-EBCDIC machines).
6653
6654 NOTE: this function is experimental and may change or be
6655 removed without notice.
6656
6657         U8*     bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
6658
6659 =for hackers
6660 Found in file utf8.c
6661
6662 =item bytes_to_utf8
6663 X<bytes_to_utf8>
6664
6665 Converts a string C<s> of length C<len> from the native encoding into UTF-8.
6666 Returns a pointer to the newly-created string, and sets C<len> to
6667 reflect the new length.
6668
6669 A NUL character will be written after the end of the string.
6670
6671 If you want to convert to UTF-8 from encodings other than
6672 the native (Latin1 or EBCDIC),
6673 see sv_recode_to_utf8().
6674
6675 NOTE: this function is experimental and may change or be
6676 removed without notice.
6677
6678         U8*     bytes_to_utf8(const U8 *s, STRLEN *len)
6679
6680 =for hackers
6681 Found in file utf8.c
6682
6683 =item ibcmp_utf8
6684 X<ibcmp_utf8>
6685
6686 Return true if the strings s1 and s2 differ case-insensitively, false
6687 if not (if they are equal case-insensitively).  If u1 is true, the
6688 string s1 is assumed to be in UTF-8-encoded Unicode.  If u2 is true,
6689 the string s2 is assumed to be in UTF-8-encoded Unicode.  If u1 or u2
6690 are false, the respective string is assumed to be in native 8-bit
6691 encoding.
6692
6693 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
6694 in there (they will point at the beginning of the I<next> character).
6695 If the pointers behind pe1 or pe2 are non-NULL, they are the end
6696 pointers beyond which scanning will not continue under any
6697 circumstances.  If the byte lengths l1 and l2 are non-zero, s1+l1 and
6698 s2+l2 will be used as goal end pointers that will also stop the scan,
6699 and which qualify towards defining a successful match: all the scans
6700 that define an explicit length must reach their goal pointers for
6701 a match to succeed).
6702
6703 For case-insensitiveness, the "casefolding" of Unicode is used
6704 instead of upper/lowercasing both the characters, see
6705 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
6706
6707         I32     ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)
6708
6709 =for hackers
6710 Found in file utf8.c
6711
6712 =item is_utf8_char
6713 X<is_utf8_char>
6714
6715 Tests if some arbitrary number of bytes begins in a valid UTF-8
6716 character.  Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
6717 character is a valid UTF-8 character.  The actual number of bytes in the UTF-8
6718 character will be returned if it is valid, otherwise 0.
6719
6720         STRLEN  is_utf8_char(const U8 *s)
6721
6722 =for hackers
6723 Found in file utf8.c
6724
6725 =item is_utf8_string
6726 X<is_utf8_string>
6727
6728 Returns true if first C<len> bytes of the given string form a valid
6729 UTF-8 string, false otherwise.  Note that 'a valid UTF-8 string' does
6730 not mean 'a string that contains code points above 0x7F encoded in UTF-8'
6731 because a valid ASCII string is a valid UTF-8 string.
6732
6733 See also is_utf8_string_loclen() and is_utf8_string_loc().
6734
6735         bool    is_utf8_string(const U8 *s, STRLEN len)
6736
6737 =for hackers
6738 Found in file utf8.c
6739
6740 =item is_utf8_string_loc
6741 X<is_utf8_string_loc>
6742
6743 Like is_utf8_string() but stores the location of the failure (in the
6744 case of "utf8ness failure") or the location s+len (in the case of
6745 "utf8ness success") in the C<ep>.
6746
6747 See also is_utf8_string_loclen() and is_utf8_string().
6748
6749         bool    is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
6750
6751 =for hackers
6752 Found in file utf8.c
6753
6754 =item is_utf8_string_loclen
6755 X<is_utf8_string_loclen>
6756
6757 Like is_utf8_string() but stores the location of the failure (in the
6758 case of "utf8ness failure") or the location s+len (in the case of
6759 "utf8ness success") in the C<ep>, and the number of UTF-8
6760 encoded characters in the C<el>.
6761
6762 See also is_utf8_string_loc() and is_utf8_string().
6763
6764         bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
6765
6766 =for hackers
6767 Found in file utf8.c
6768
6769 =item pv_uni_display
6770 X<pv_uni_display>
6771
6772 Build to the scalar dsv a displayable version of the string spv,
6773 length len, the displayable version being at most pvlim bytes long
6774 (if longer, the rest is truncated and "..." will be appended).
6775
6776 The flags argument can have UNI_DISPLAY_ISPRINT set to display
6777 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
6778 to display the \\[nrfta\\] as the backslashed versions (like '\n')
6779 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
6780 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
6781 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
6782
6783 The pointer to the PV of the dsv is returned.
6784
6785         char*   pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
6786
6787 =for hackers
6788 Found in file utf8.c
6789
6790 =item sv_cat_decode
6791 X<sv_cat_decode>
6792
6793 The encoding is assumed to be an Encode object, the PV of the ssv is
6794 assumed to be octets in that encoding and decoding the input starts
6795 from the position which (PV + *offset) pointed to.  The dsv will be
6796 concatenated the decoded UTF-8 string from ssv.  Decoding will terminate
6797 when the string tstr appears in decoding output or the input ends on
6798 the PV of the ssv. The value which the offset points will be modified
6799 to the last input position on the ssv.
6800
6801 Returns TRUE if the terminator was found, else returns FALSE.
6802
6803         bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
6804
6805 =for hackers
6806 Found in file sv.c
6807
6808 =item sv_recode_to_utf8
6809 X<sv_recode_to_utf8>
6810
6811 The encoding is assumed to be an Encode object, on entry the PV
6812 of the sv is assumed to be octets in that encoding, and the sv
6813 will be converted into Unicode (and UTF-8).
6814
6815 If the sv already is UTF-8 (or if it is not POK), or if the encoding
6816 is not a reference, nothing is done to the sv.  If the encoding is not
6817 an C<Encode::XS> Encoding object, bad things will happen.
6818 (See F<lib/encoding.pm> and L<Encode>).
6819
6820 The PV of the sv is returned.
6821
6822         char*   sv_recode_to_utf8(SV* sv, SV *encoding)
6823
6824 =for hackers
6825 Found in file sv.c
6826
6827 =item sv_uni_display
6828 X<sv_uni_display>
6829
6830 Build to the scalar dsv a displayable version of the scalar sv,
6831 the displayable version being at most pvlim bytes long
6832 (if longer, the rest is truncated and "..." will be appended).
6833
6834 The flags argument is as in pv_uni_display().
6835
6836 The pointer to the PV of the dsv is returned.
6837
6838         char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
6839
6840 =for hackers
6841 Found in file utf8.c
6842
6843 =item to_utf8_case
6844 X<to_utf8_case>
6845
6846 The "p" contains the pointer to the UTF-8 string encoding
6847 the character that is being converted.
6848
6849 The "ustrp" is a pointer to the character buffer to put the
6850 conversion result to.  The "lenp" is a pointer to the length
6851 of the result.
6852
6853 The "swashp" is a pointer to the swash to use.
6854
6855 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
6856 and loaded by SWASHNEW, using lib/utf8_heavy.pl.  The special (usually,
6857 but not always, a multicharacter mapping), is tried first.
6858
6859 The "special" is a string like "utf8::ToSpecLower", which means the
6860 hash %utf8::ToSpecLower.  The access to the hash is through
6861 Perl_to_utf8_case().
6862
6863 The "normal" is a string like "ToLower" which means the swash
6864 %utf8::ToLower.
6865
6866         UV      to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
6867
6868 =for hackers
6869 Found in file utf8.c
6870
6871 =item to_utf8_fold
6872 X<to_utf8_fold>
6873
6874 Convert the UTF-8 encoded character at p to its foldcase version and
6875 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6876 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6877 foldcase version may be longer than the original character (up to
6878 three characters).
6879
6880 The first character of the foldcased version is returned
6881 (but note, as explained above, that there may be more.)
6882
6883         UV      to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
6884
6885 =for hackers
6886 Found in file utf8.c
6887
6888 =item to_utf8_lower
6889 X<to_utf8_lower>
6890
6891 Convert the UTF-8 encoded character at p to its lowercase version and
6892 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6893 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6894 lowercase version may be longer than the original character.
6895
6896 The first character of the lowercased version is returned
6897 (but note, as explained above, that there may be more.)
6898
6899         UV      to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
6900
6901 =for hackers
6902 Found in file utf8.c
6903
6904 =item to_utf8_title
6905 X<to_utf8_title>
6906
6907 Convert the UTF-8 encoded character at p to its titlecase version and
6908 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6909 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6910 titlecase version may be longer than the original character.
6911
6912 The first character of the titlecased version is returned
6913 (but note, as explained above, that there may be more.)
6914
6915         UV      to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
6916
6917 =for hackers
6918 Found in file utf8.c
6919
6920 =item to_utf8_upper
6921 X<to_utf8_upper>
6922
6923 Convert the UTF-8 encoded character at p to its uppercase version and
6924 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6925 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
6926 the uppercase version may be longer than the original character.
6927
6928 The first character of the uppercased version is returned
6929 (but note, as explained above, that there may be more.)
6930
6931         UV      to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
6932
6933 =for hackers
6934 Found in file utf8.c
6935
6936 =item utf8n_to_uvchr
6937 X<utf8n_to_uvchr>
6938
6939 flags
6940
6941 Returns the native character value of the first character in the string 
6942 C<s>
6943 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6944 length, in bytes, of that character.
6945
6946 Allows length and flags to be passed to low level routine.
6947
6948         UV      utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6949
6950 =for hackers
6951 Found in file utf8.c
6952
6953 =item utf8n_to_uvuni
6954 X<utf8n_to_uvuni>
6955
6956 Bottom level UTF-8 decode routine.
6957 Returns the Unicode code point value of the first character in the string C<s>
6958 which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
6959 C<retlen> will be set to the length, in bytes, of that character.
6960
6961 If C<s> does not point to a well-formed UTF-8 character, the behaviour
6962 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
6963 it is assumed that the caller will raise a warning, and this function
6964 will silently just set C<retlen> to C<-1> and return zero.  If the
6965 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
6966 malformations will be given, C<retlen> will be set to the expected
6967 length of the UTF-8 character in bytes, and zero will be returned.
6968
6969 The C<flags> can also contain various flags to allow deviations from
6970 the strict UTF-8 encoding (see F<utf8.h>).
6971
6972 Most code should use utf8_to_uvchr() rather than call this directly.
6973
6974         UV      utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6975
6976 =for hackers
6977 Found in file utf8.c
6978
6979 =item utf8_distance
6980 X<utf8_distance>
6981
6982 Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
6983 and C<b>.
6984
6985 WARNING: use only if you *know* that the pointers point inside the
6986 same UTF-8 buffer.
6987
6988         IV      utf8_distance(const U8 *a, const U8 *b)
6989
6990 =for hackers
6991 Found in file utf8.c
6992
6993 =item utf8_hop
6994 X<utf8_hop>
6995
6996 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
6997 forward or backward.
6998
6999 WARNING: do not use the following unless you *know* C<off> is within
7000 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
7001 on the first byte of character or just after the last byte of a character.
7002
7003         U8*     utf8_hop(const U8 *s, I32 off)
7004
7005 =for hackers
7006 Found in file utf8.c
7007
7008 =item utf8_length
7009 X<utf8_length>
7010
7011 Return the length of the UTF-8 char encoded string C<s> in characters.
7012 Stops at C<e> (inclusive).  If C<e E<lt> s> or if the scan would end
7013 up past C<e>, croaks.
7014
7015         STRLEN  utf8_length(const U8* s, const U8 *e)
7016
7017 =for hackers
7018 Found in file utf8.c
7019
7020 =item utf8_to_bytes
7021 X<utf8_to_bytes>
7022
7023 Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
7024 Unlike C<bytes_to_utf8>, this over-writes the original string, and
7025 updates len to contain the new length.
7026 Returns zero on failure, setting C<len> to -1.
7027
7028 If you need a copy of the string, see C<bytes_from_utf8>.
7029
7030 NOTE: this function is experimental and may change or be
7031 removed without notice.
7032
7033         U8*     utf8_to_bytes(U8 *s, STRLEN *len)
7034
7035 =for hackers
7036 Found in file utf8.c
7037
7038 =item utf8_to_uvchr
7039 X<utf8_to_uvchr>
7040
7041 Returns the native character value of the first character in the string C<s>
7042 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
7043 length, in bytes, of that character.
7044
7045 If C<s> does not point to a well-formed UTF-8 character, zero is
7046 returned and retlen is set, if possible, to -1.
7047
7048         UV      utf8_to_uvchr(const U8 *s, STRLEN *retlen)
7049
7050 =for hackers
7051 Found in file utf8.c
7052
7053 =item utf8_to_uvuni
7054 X<utf8_to_uvuni>
7055
7056 Returns the Unicode code point of the first character in the string C<s>
7057 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
7058 length, in bytes, of that character.
7059
7060 This function should only be used when the returned UV is considered
7061 an index into the Unicode semantic tables (e.g. swashes).
7062
7063 If C<s> does not point to a well-formed UTF-8 character, zero is
7064 returned and retlen is set, if possible, to -1.
7065
7066         UV      utf8_to_uvuni(const U8 *s, STRLEN *retlen)
7067
7068 =for hackers
7069 Found in file utf8.c
7070
7071 =item uvchr_to_utf8
7072 X<uvchr_to_utf8>
7073
7074 Adds the UTF-8 representation of the Native codepoint C<uv> to the end
7075 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
7076 bytes available. The return value is the pointer to the byte after the
7077 end of the new character. In other words,
7078
7079     d = uvchr_to_utf8(d, uv);
7080
7081 is the recommended wide native character-aware way of saying
7082
7083     *(d++) = uv;
7084
7085         U8*     uvchr_to_utf8(U8 *d, UV uv)
7086
7087 =for hackers
7088 Found in file utf8.c
7089
7090 =item uvuni_to_utf8_flags
7091 X<uvuni_to_utf8_flags>
7092
7093 Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
7094 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
7095 bytes available. The return value is the pointer to the byte after the
7096 end of the new character. In other words,
7097
7098     d = uvuni_to_utf8_flags(d, uv, flags);
7099
7100 or, in most cases,
7101
7102     d = uvuni_to_utf8(d, uv);
7103
7104 (which is equivalent to)
7105
7106     d = uvuni_to_utf8_flags(d, uv, 0);
7107
7108 is the recommended Unicode-aware way of saying
7109
7110     *(d++) = uv;
7111
7112         U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
7113
7114 =for hackers
7115 Found in file utf8.c
7116
7117
7118 =back
7119
7120 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
7121
7122 =over 8
7123
7124 =item ax
7125 X<ax>
7126
7127 Variable which is setup by C<xsubpp> to indicate the stack base offset,
7128 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
7129 must be called prior to setup the C<MARK> variable.
7130
7131         I32     ax
7132
7133 =for hackers
7134 Found in file XSUB.h
7135
7136 =item CLASS
7137 X<CLASS>
7138
7139 Variable which is setup by C<xsubpp> to indicate the 
7140 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
7141
7142         char*   CLASS
7143
7144 =for hackers
7145 Found in file XSUB.h
7146
7147 =item dAX
7148 X<dAX>
7149
7150 Sets up the C<ax> variable.
7151 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7152
7153                 dAX;
7154
7155 =for hackers
7156 Found in file XSUB.h
7157
7158 =item dAXMARK
7159 X<dAXMARK>
7160
7161 Sets up the C<ax> variable and stack marker variable C<mark>.
7162 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7163
7164                 dAXMARK;
7165
7166 =for hackers
7167 Found in file XSUB.h
7168
7169 =item dITEMS
7170 X<dITEMS>
7171
7172 Sets up the C<items> variable.
7173 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7174
7175                 dITEMS;
7176
7177 =for hackers
7178 Found in file XSUB.h
7179
7180 =item dUNDERBAR
7181 X<dUNDERBAR>
7182
7183 Sets up the C<padoff_du> variable for an XSUB that wishes to use
7184 C<UNDERBAR>.
7185
7186                 dUNDERBAR;
7187
7188 =for hackers
7189 Found in file XSUB.h
7190
7191 =item dXSARGS
7192 X<dXSARGS>
7193
7194 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
7195 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
7196 This is usually handled automatically by C<xsubpp>.
7197
7198                 dXSARGS;
7199
7200 =for hackers
7201 Found in file XSUB.h
7202
7203 =item dXSI32
7204 X<dXSI32>
7205
7206 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
7207 handled automatically by C<xsubpp>.
7208
7209                 dXSI32;
7210
7211 =for hackers
7212 Found in file XSUB.h
7213
7214 =item items
7215 X<items>
7216
7217 Variable which is setup by C<xsubpp> to indicate the number of 
7218 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
7219
7220         I32     items
7221
7222 =for hackers
7223 Found in file XSUB.h
7224
7225 =item ix
7226 X<ix>
7227
7228 Variable which is setup by C<xsubpp> to indicate which of an 
7229 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
7230
7231         I32     ix
7232
7233 =for hackers
7234 Found in file XSUB.h
7235
7236 =item newXSproto
7237 X<newXSproto>
7238
7239 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
7240 the subs.
7241
7242 =for hackers
7243 Found in file XSUB.h
7244
7245 =item RETVAL
7246 X<RETVAL>
7247
7248 Variable which is setup by C<xsubpp> to hold the return value for an 
7249 XSUB. This is always the proper type for the XSUB. See 
7250 L<perlxs/"The RETVAL Variable">.
7251
7252         (whatever)      RETVAL
7253
7254 =for hackers
7255 Found in file XSUB.h
7256
7257 =item ST
7258 X<ST>
7259
7260 Used to access elements on the XSUB's stack.
7261
7262         SV*     ST(int ix)
7263
7264 =for hackers
7265 Found in file XSUB.h
7266
7267 =item THIS
7268 X<THIS>
7269
7270 Variable which is setup by C<xsubpp> to designate the object in a C++ 
7271 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
7272 L<perlxs/"Using XS With C++">.
7273
7274         (whatever)      THIS
7275
7276 =for hackers
7277 Found in file XSUB.h
7278
7279 =item UNDERBAR
7280 X<UNDERBAR>
7281
7282 The SV* corresponding to the $_ variable. Works even if there
7283 is a lexical $_ in scope.
7284
7285 =for hackers
7286 Found in file XSUB.h
7287
7288 =item XS
7289 X<XS>
7290
7291 Macro to declare an XSUB and its C parameter list.  This is handled by
7292 C<xsubpp>.
7293
7294 =for hackers
7295 Found in file XSUB.h
7296
7297 =item XS_VERSION
7298 X<XS_VERSION>
7299
7300 The version identifier for an XS module.  This is usually
7301 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
7302
7303 =for hackers
7304 Found in file XSUB.h
7305
7306 =item XS_VERSION_BOOTCHECK
7307 X<XS_VERSION_BOOTCHECK>
7308
7309 Macro to verify that a PM module's $VERSION variable matches the XS
7310 module's C<XS_VERSION> variable.  This is usually handled automatically by
7311 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
7312
7313                 XS_VERSION_BOOTCHECK;
7314
7315 =for hackers
7316 Found in file XSUB.h
7317
7318
7319 =back
7320
7321 =head1 Warning and Dieing
7322
7323 =over 8
7324
7325 =item croak
7326 X<croak>
7327
7328 This is the XSUB-writer's interface to Perl's C<die> function.
7329 Normally call this function the same way you call the C C<printf>
7330 function.  Calling C<croak> returns control directly to Perl,
7331 sidestepping the normal C order of execution. See C<warn>.
7332
7333 If you want to throw an exception object, assign the object to
7334 C<$@> and then pass C<NULL> to croak():
7335
7336    errsv = get_sv("@", TRUE);
7337    sv_setsv(errsv, exception_object);
7338    croak(NULL);
7339
7340         void    croak(const char* pat, ...)
7341
7342 =for hackers
7343 Found in file util.c
7344
7345 =item warn
7346 X<warn>
7347
7348 This is the XSUB-writer's interface to Perl's C<warn> function.  Call this
7349 function the same way you call the C C<printf> function.  See C<croak>.
7350
7351         void    warn(const char* pat, ...)
7352
7353 =for hackers
7354 Found in file util.c
7355
7356
7357 =back
7358
7359 =head1 AUTHORS
7360
7361 Until May 1997, this document was maintained by Jeff Okamoto
7362 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
7363
7364 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
7365 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
7366 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
7367 Stephen McCamant, and Gurusamy Sarathy.
7368
7369 API Listing originally by Dean Roehrich <roehrich@cray.com>.
7370
7371 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
7372
7373 =head1 SEE ALSO
7374
7375 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
7376
7377 =cut
7378
7379  ex: set ro: