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