This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Subject: PATCH 5.10 documentation
[perl5.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 - 256 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>.
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>.
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>.
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>.
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
5138 =back
5139
5140 =head1 SV-Body Allocation
5141
5142 =over 8
5143
5144 =item looks_like_number
5145 X<looks_like_number>
5146
5147 Test if the content of an SV looks like a number (or is a number).
5148 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
5149 non-numeric warning), even if your atof() doesn't grok them.
5150
5151         I32     looks_like_number(SV *const sv)
5152
5153 =for hackers
5154 Found in file sv.c
5155
5156 =item newRV_noinc
5157 X<newRV_noinc>
5158
5159 Creates an RV wrapper for an SV.  The reference count for the original
5160 SV is B<not> incremented.
5161
5162         SV*     newRV_noinc(SV *const sv)
5163
5164 =for hackers
5165 Found in file sv.c
5166
5167 =item newSV
5168 X<newSV>
5169
5170 Creates a new SV.  A non-zero C<len> parameter indicates the number of
5171 bytes of preallocated string space the SV should have.  An extra byte for a
5172 trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
5173 space is allocated.)  The reference count for the new SV is set to 1.
5174
5175 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5176 parameter, I<x>, a debug aid which allowed callers to identify themselves.
5177 This aid has been superseded by a new build option, PERL_MEM_LOG (see
5178 L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
5179 modules supporting older perls.
5180
5181         SV*     newSV(const STRLEN len)
5182
5183 =for hackers
5184 Found in file sv.c
5185
5186 =item newSVhek
5187 X<newSVhek>
5188
5189 Creates a new SV from the hash key structure.  It will generate scalars that
5190 point to the shared string table where possible. Returns a new (undefined)
5191 SV if the hek is NULL.
5192
5193         SV*     newSVhek(const HEK *const hek)
5194
5195 =for hackers
5196 Found in file sv.c
5197
5198 =item newSViv
5199 X<newSViv>
5200
5201 Creates a new SV and copies an integer into it.  The reference count for the
5202 SV is set to 1.
5203
5204         SV*     newSViv(const IV i)
5205
5206 =for hackers
5207 Found in file sv.c
5208
5209 =item newSVnv
5210 X<newSVnv>
5211
5212 Creates a new SV and copies a floating point value into it.
5213 The reference count for the SV is set to 1.
5214
5215         SV*     newSVnv(const NV n)
5216
5217 =for hackers
5218 Found in file sv.c
5219
5220 =item newSVpv
5221 X<newSVpv>
5222
5223 Creates a new SV and copies a string into it.  The reference count for the
5224 SV is set to 1.  If C<len> is zero, Perl will compute the length using
5225 strlen().  For efficiency, consider using C<newSVpvn> instead.
5226
5227         SV*     newSVpv(const char *const s, const STRLEN len)
5228
5229 =for hackers
5230 Found in file sv.c
5231
5232 =item newSVpvf
5233 X<newSVpvf>
5234
5235 Creates a new SV and initializes it with the string formatted like
5236 C<sprintf>.
5237
5238         SV*     newSVpvf(const char *const pat, ...)
5239
5240 =for hackers
5241 Found in file sv.c
5242
5243 =item newSVpvn
5244 X<newSVpvn>
5245
5246 Creates a new SV and copies a string into it.  The reference count for the
5247 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5248 string.  You are responsible for ensuring that the source string is at least
5249 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5250
5251         SV*     newSVpvn(const char *const s, const STRLEN len)
5252
5253 =for hackers
5254 Found in file sv.c
5255
5256 =item newSVpvn_flags
5257 X<newSVpvn_flags>
5258
5259 Creates a new SV and copies a string into it.  The reference count for the
5260 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5261 string.  You are responsible for ensuring that the source string is at least
5262 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5263 Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
5264 If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
5265 returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
5266 C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
5267
5268     #define newSVpvn_utf8(s, len, u)                    \
5269         newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
5270
5271         SV*     newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
5272
5273 =for hackers
5274 Found in file sv.c
5275
5276 =item newSVpvn_share
5277 X<newSVpvn_share>
5278
5279 Creates a new SV with its SvPVX_const pointing to a shared string in the string
5280 table. If the string does not already exist in the table, it is created
5281 first.  Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
5282 value is used; otherwise the hash is computed. The string's hash can be later
5283 be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
5284 that as the string table is used for shared hash keys these strings will have
5285 SvPVX_const == HeKEY and hash lookup will avoid string compare.
5286
5287         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
5288
5289 =for hackers
5290 Found in file sv.c
5291
5292 =item newSVpvs
5293 X<newSVpvs>
5294
5295 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5296
5297         SV*     newSVpvs(const char* s)
5298
5299 =for hackers
5300 Found in file handy.h
5301
5302 =item newSVpvs_flags
5303 X<newSVpvs_flags>
5304
5305 Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
5306 pair.
5307
5308         SV*     newSVpvs_flags(const char* s, U32 flags)
5309
5310 =for hackers
5311 Found in file handy.h
5312
5313 =item newSVpvs_share
5314 X<newSVpvs_share>
5315
5316 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5317 pair and omits the hash parameter.
5318
5319         SV*     newSVpvs_share(const char* s)
5320
5321 =for hackers
5322 Found in file handy.h
5323
5324 =item newSVrv
5325 X<newSVrv>
5326
5327 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
5328 it will be upgraded to one.  If C<classname> is non-null then the new SV will
5329 be blessed in the specified package.  The new SV is returned and its
5330 reference count is 1.
5331
5332         SV*     newSVrv(SV *const rv, const char *const classname)
5333
5334 =for hackers
5335 Found in file sv.c
5336
5337 =item newSVsv
5338 X<newSVsv>
5339
5340 Creates a new SV which is an exact duplicate of the original SV.
5341 (Uses C<sv_setsv>).
5342
5343         SV*     newSVsv(SV *const old)
5344
5345 =for hackers
5346 Found in file sv.c
5347
5348 =item newSVuv
5349 X<newSVuv>
5350
5351 Creates a new SV and copies an unsigned integer into it.
5352 The reference count for the SV is set to 1.
5353
5354         SV*     newSVuv(const UV u)
5355
5356 =for hackers
5357 Found in file sv.c
5358
5359 =item newSV_type
5360 X<newSV_type>
5361
5362 Creates a new SV, of the type specified.  The reference count for the new SV
5363 is set to 1.
5364
5365         SV*     newSV_type(const svtype type)
5366
5367 =for hackers
5368 Found in file sv.c
5369
5370 =item sv_2bool
5371 X<sv_2bool>
5372
5373 This function is only called on magical items, and is only used by
5374 sv_true() or its macro equivalent.
5375
5376         bool    sv_2bool(SV *const sv)
5377
5378 =for hackers
5379 Found in file sv.c
5380
5381 =item sv_2cv
5382 X<sv_2cv>
5383
5384 Using various gambits, try to get a CV from an SV; in addition, try if
5385 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5386 The flags in C<lref> are passed to sv_fetchsv.
5387
5388         CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
5389
5390 =for hackers
5391 Found in file sv.c
5392
5393 =item sv_2io
5394 X<sv_2io>
5395
5396 Using various gambits, try to get an IO from an SV: the IO slot if its a
5397 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5398 named after the PV if we're a string.
5399
5400         IO*     sv_2io(SV *const sv)
5401
5402 =for hackers
5403 Found in file sv.c
5404
5405 =item sv_2iv_flags
5406 X<sv_2iv_flags>
5407
5408 Return the integer value of an SV, doing any necessary string
5409 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5410 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5411
5412         IV      sv_2iv_flags(SV *const sv, const I32 flags)
5413
5414 =for hackers
5415 Found in file sv.c
5416
5417 =item sv_2mortal
5418 X<sv_2mortal>
5419
5420 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
5421 by an explicit call to FREETMPS, or by an implicit call at places such as
5422 statement boundaries.  SvTEMP() is turned on which means that the SV's
5423 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5424 and C<sv_mortalcopy>.
5425
5426         SV*     sv_2mortal(SV *const sv)
5427
5428 =for hackers
5429 Found in file sv.c
5430
5431 =item sv_2nv
5432 X<sv_2nv>
5433
5434 Return the num value of an SV, doing any necessary string or integer
5435 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5436 macros.
5437
5438         NV      sv_2nv(SV *const sv)
5439
5440 =for hackers
5441 Found in file sv.c
5442
5443 =item sv_2pvbyte
5444 X<sv_2pvbyte>
5445
5446 Return a pointer to the byte-encoded representation of the SV, and set *lp
5447 to its length.  May cause the SV to be downgraded from UTF-8 as a
5448 side-effect.
5449
5450 Usually accessed via the C<SvPVbyte> macro.
5451
5452         char*   sv_2pvbyte(SV *const sv, STRLEN *const lp)
5453
5454 =for hackers
5455 Found in file sv.c
5456
5457 =item sv_2pvutf8
5458 X<sv_2pvutf8>
5459
5460 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5461 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
5462
5463 Usually accessed via the C<SvPVutf8> macro.
5464
5465         char*   sv_2pvutf8(SV *const sv, STRLEN *const lp)
5466
5467 =for hackers
5468 Found in file sv.c
5469
5470 =item sv_2pv_flags
5471 X<sv_2pv_flags>
5472
5473 Returns a pointer to the string value of an SV, and sets *lp to its length.
5474 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5475 if necessary.
5476 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5477 usually end up here too.
5478
5479         char*   sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)
5480
5481 =for hackers
5482 Found in file sv.c
5483
5484 =item sv_2uv_flags
5485 X<sv_2uv_flags>
5486
5487 Return the unsigned integer value of an SV, doing any necessary string
5488 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5489 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5490
5491         UV      sv_2uv_flags(SV *const sv, const I32 flags)
5492
5493 =for hackers
5494 Found in file sv.c
5495
5496 =item sv_backoff