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