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