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