This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
SvRX() and SvRXOK() macros
[perl5.git] / pod / perlapi.pod
1 -*- buffer-read-only: t -*-
2
3 !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
4 This file is built by autodoc.pl extracting documentation from the C source
5 files.
6
7 =head1 NAME
8
9 perlapi - autogenerated documentation for the perl public API
10
11 =head1 DESCRIPTION
12 X<Perl API> X<API> X<api>
13
14 This file contains the documentation of the perl public API generated by
15 embed.pl, specifically a listing of functions, macros, flags, and variables
16 that may be used by extension writers.  The interfaces of any functions that
17 are not listed here are subject to change without notice.  For this reason,
18 blindly using functions listed in proto.h is to be avoided when writing
19 extensions.
20
21 Note that all Perl API global variables must be referenced with the C<PL_>
22 prefix.  Some macros are provided for compatibility with the older,
23 unadorned names, but this support may be disabled in a future release.
24
25 The listing is alphabetical, case insensitive.
26
27
28 =head1 "Gimme" Values
29
30 =over 8
31
32 =item GIMME
33 X<GIMME>
34
35 A backward-compatible version of C<GIMME_V> which can only return
36 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
37 Deprecated.  Use C<GIMME_V> instead.
38
39         U32     GIMME
40
41 =for hackers
42 Found in file op.h
43
44 =item GIMME_V
45 X<GIMME_V>
46
47 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
48 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
49 respectively.
50
51         U32     GIMME_V
52
53 =for hackers
54 Found in file op.h
55
56 =item G_ARRAY
57 X<G_ARRAY>
58
59 Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
60 L<perlcall>.
61
62 =for hackers
63 Found in file cop.h
64
65 =item G_DISCARD
66 X<G_DISCARD>
67
68 Indicates that arguments returned from a callback should be discarded.  See
69 L<perlcall>.
70
71 =for hackers
72 Found in file cop.h
73
74 =item G_EVAL
75 X<G_EVAL>
76
77 Used to force a Perl C<eval> wrapper around a callback.  See
78 L<perlcall>.
79
80 =for hackers
81 Found in file cop.h
82
83 =item G_NOARGS
84 X<G_NOARGS>
85
86 Indicates that no arguments are being sent to a callback.  See
87 L<perlcall>.
88
89 =for hackers
90 Found in file cop.h
91
92 =item G_SCALAR
93 X<G_SCALAR>
94
95 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
96 L<perlcall>.
97
98 =for hackers
99 Found in file cop.h
100
101 =item G_VOID
102 X<G_VOID>
103
104 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
105
106 =for hackers
107 Found in file cop.h
108
109
110 =back
111
112 =head1 Array Manipulation Functions
113
114 =over 8
115
116 =item AvFILL
117 X<AvFILL>
118
119 Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
120
121         int     AvFILL(AV* av)
122
123 =for hackers
124 Found in file av.h
125
126 =item av_clear
127 X<av_clear>
128
129 Clears an array, making it empty.  Does not free the memory used by the
130 array itself.
131
132         void    av_clear(AV* ar)
133
134 =for hackers
135 Found in file av.c
136
137 =item av_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 GV Functions
1227
1228 =over 8
1229
1230 =item GvSV
1231 X<GvSV>
1232
1233 Return the SV from the GV.
1234
1235         SV*     GvSV(GV* gv)
1236
1237 =for hackers
1238 Found in file gv.h
1239
1240 =item gv_const_sv
1241 X<gv_const_sv>
1242
1243 If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1244 inlining, or C<gv> is a placeholder reference that would be promoted to such
1245 a typeglob, then returns the value returned by the sub.  Otherwise, returns
1246 NULL.
1247
1248         SV*     gv_const_sv(GV* gv)
1249
1250 =for hackers
1251 Found in file gv.c
1252
1253 =item gv_fetchmeth
1254 X<gv_fetchmeth>
1255
1256 Returns the glob with the given C<name> and a defined subroutine or
1257 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
1258 accessible via @ISA and UNIVERSAL::.
1259
1260 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
1261 side-effect creates a glob with the given C<name> in the given C<stash>
1262 which in the case of success contains an alias for the subroutine, and sets
1263 up caching info for this glob.
1264
1265 This function grants C<"SUPER"> token as a postfix of the stash name. The
1266 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1267 visible to Perl code.  So when calling C<call_sv>, you should not use
1268 the GV directly; instead, you should use the method's CV, which can be
1269 obtained from the GV with the C<GvCV> macro.
1270
1271         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1272
1273 =for hackers
1274 Found in file gv.c
1275
1276 =item gv_fetchmethod_autoload
1277 X<gv_fetchmethod_autoload>
1278
1279 Returns the glob which contains the subroutine to call to invoke the method
1280 on the C<stash>.  In fact in the presence of autoloading this may be the
1281 glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
1282 already setup.
1283
1284 The third parameter of C<gv_fetchmethod_autoload> determines whether
1285 AUTOLOAD lookup is performed if the given method is not present: non-zero
1286 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1287 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1288 with a non-zero C<autoload> parameter.
1289
1290 These functions grant C<"SUPER"> token as a prefix of the method name. Note
1291 that if you want to keep the returned glob for a long time, you need to
1292 check for it being "AUTOLOAD", since at the later time the call may load a
1293 different subroutine due to $AUTOLOAD changing its value. Use the glob
1294 created via a side effect to do this.
1295
1296 These functions have the same side-effects and as C<gv_fetchmeth> with
1297 C<level==0>.  C<name> should be writable if contains C<':'> or C<'
1298 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1299 C<call_sv> apply equally to these functions.
1300
1301         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1302
1303 =for hackers
1304 Found in file gv.c
1305
1306 =item gv_fetchmeth_autoload
1307 X<gv_fetchmeth_autoload>
1308
1309 Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1310 Returns a glob for the subroutine.
1311
1312 For an autoloaded subroutine without a GV, will create a GV even
1313 if C<level < 0>.  For an autoloaded subroutine without a stub, GvCV()
1314 of the result may be zero.
1315
1316         GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1317
1318 =for hackers
1319 Found in file gv.c
1320
1321 =item gv_stashpv
1322 X<gv_stashpv>
1323
1324 Returns a pointer to the stash for a specified package.  Uses C<strlen> to
1325 determine the length of C<name>, then calls C<gv_stashpvn()>.
1326
1327         HV*     gv_stashpv(const char* name, I32 flags)
1328
1329 =for hackers
1330 Found in file gv.c
1331
1332 =item gv_stashpvn
1333 X<gv_stashpvn>
1334
1335 Returns a pointer to the stash for a specified package.  The C<namelen>
1336 parameter indicates the length of the C<name>, in bytes.  C<flags> is passed
1337 to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
1338 created if it does not already exist.  If the package does not exist and
1339 C<flags> is 0 (or any other setting that does not create packages) then NULL
1340 is returned.
1341
1342
1343         HV*     gv_stashpvn(const char* name, U32 namelen, I32 flags)
1344
1345 =for hackers
1346 Found in file gv.c
1347
1348 =item gv_stashpvs
1349 X<gv_stashpvs>
1350
1351 Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1352
1353         HV*     gv_stashpvs(const char* name, I32 create)
1354
1355 =for hackers
1356 Found in file handy.h
1357
1358 =item gv_stashsv
1359 X<gv_stashsv>
1360
1361 Returns a pointer to the stash for a specified package.  See C<gv_stashpvn>.
1362
1363         HV*     gv_stashsv(SV* sv, I32 flags)
1364
1365 =for hackers
1366 Found in file gv.c
1367
1368
1369 =back
1370
1371 =head1 Handy Values
1372
1373 =over 8
1374
1375 =item Nullav
1376 X<Nullav>
1377
1378 Null AV pointer.
1379
1380 =for hackers
1381 Found in file av.h
1382
1383 =item Nullch
1384 X<Nullch>
1385
1386 Null character pointer.
1387
1388 =for hackers
1389 Found in file handy.h
1390
1391 =item Nullcv
1392 X<Nullcv>
1393
1394 Null CV pointer.
1395
1396 =for hackers
1397 Found in file cv.h
1398
1399 =item Nullhv
1400 X<Nullhv>
1401
1402 Null HV pointer.
1403
1404 =for hackers
1405 Found in file hv.h
1406
1407 =item Nullsv
1408 X<Nullsv>
1409
1410 Null SV pointer.
1411
1412 =for hackers
1413 Found in file handy.h
1414
1415
1416 =back
1417
1418 =head1 Hash Manipulation Functions
1419
1420 =over 8
1421
1422 =item get_hv
1423 X<get_hv>
1424
1425 Returns the HV of the specified Perl hash.  If C<create> is set and the
1426 Perl variable does not exist then it will be created.  If C<create> is not
1427 set and the variable does not exist then NULL is returned.
1428
1429 NOTE: the perl_ form of this function is deprecated.
1430
1431         HV*     get_hv(const char* name, I32 create)
1432
1433 =for hackers
1434 Found in file perl.c
1435
1436 =item HEf_SVKEY
1437 X<HEf_SVKEY>
1438
1439 This flag, used in the length slot of hash entries and magic structures,
1440 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1441 is to be expected. (For information only--not to be used).
1442
1443 =for hackers
1444 Found in file hv.h
1445
1446 =item HeHASH
1447 X<HeHASH>
1448
1449 Returns the computed hash stored in the hash entry.
1450
1451         U32     HeHASH(HE* he)
1452
1453 =for hackers
1454 Found in file hv.h
1455
1456 =item HeKEY
1457 X<HeKEY>
1458
1459 Returns the actual pointer stored in the key slot of the hash entry. The
1460 pointer may be either C<char*> or C<SV*>, depending on the value of
1461 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
1462 usually preferable for finding the value of a key.
1463
1464         void*   HeKEY(HE* he)
1465
1466 =for hackers
1467 Found in file hv.h
1468
1469 =item HeKLEN
1470 X<HeKLEN>
1471
1472 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1473 holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
1474 be assigned to. The C<HePV()> macro is usually preferable for finding key
1475 lengths.
1476
1477         STRLEN  HeKLEN(HE* he)
1478
1479 =for hackers
1480 Found in file hv.h
1481
1482 =item HePV
1483 X<HePV>
1484
1485 Returns the key slot of the hash entry as a C<char*> value, doing any
1486 necessary dereferencing of possibly C<SV*> keys.  The length of the string
1487 is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
1488 not care about what the length of the key is, you may use the global
1489 variable C<PL_na>, though this is rather less efficient than using a local
1490 variable.  Remember though, that hash keys in perl are free to contain
1491 embedded nulls, so using C<strlen()> or similar is not a good way to find
1492 the length of hash keys. This is very similar to the C<SvPV()> macro
1493 described elsewhere in this document.
1494
1495         char*   HePV(HE* he, STRLEN len)
1496
1497 =for hackers
1498 Found in file hv.h
1499
1500 =item HeSVKEY
1501 X<HeSVKEY>
1502
1503 Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
1504 contain an C<SV*> key.
1505
1506         SV*     HeSVKEY(HE* he)
1507
1508 =for hackers
1509 Found in file hv.h
1510
1511 =item HeSVKEY_force
1512 X<HeSVKEY_force>
1513
1514 Returns the key as an C<SV*>.  Will create and return a temporary mortal
1515 C<SV*> if the hash entry contains only a C<char*> key.
1516
1517         SV*     HeSVKEY_force(HE* he)
1518
1519 =for hackers
1520 Found in file hv.h
1521
1522 =item HeSVKEY_set
1523 X<HeSVKEY_set>
1524
1525 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1526 indicate the presence of an C<SV*> key, and returns the same
1527 C<SV*>.
1528
1529         SV*     HeSVKEY_set(HE* he, SV* sv)
1530
1531 =for hackers
1532 Found in file hv.h
1533
1534 =item HeVAL
1535 X<HeVAL>
1536
1537 Returns the value slot (type C<SV*>) stored in the hash entry.
1538
1539         SV*     HeVAL(HE* he)
1540
1541 =for hackers
1542 Found in file hv.h
1543
1544 =item HvNAME
1545 X<HvNAME>
1546
1547 Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1548 See C<SvSTASH>, C<CvSTASH>.
1549
1550         char*   HvNAME(HV* stash)
1551
1552 =for hackers
1553 Found in file hv.h
1554
1555 =item hv_assert
1556 X<hv_assert>
1557
1558 Check that a hash is in an internally consistent state.
1559
1560         void    hv_assert(HV* tb)
1561
1562 =for hackers
1563 Found in file hv.c
1564
1565 =item hv_clear
1566 X<hv_clear>
1567
1568 Clears a hash, making it empty.
1569
1570         void    hv_clear(HV* tb)
1571
1572 =for hackers
1573 Found in file hv.c
1574
1575 =item hv_clear_placeholders
1576 X<hv_clear_placeholders>
1577
1578 Clears any placeholders from a hash.  If a restricted hash has any of its keys
1579 marked as readonly and the key is subsequently deleted, the key is not actually
1580 deleted but is marked by assigning it a value of &PL_sv_placeholder.  This tags
1581 it so it will be ignored by future operations such as iterating over the hash,
1582 but will still allow the hash to have a value reassigned to the key at some
1583 future point.  This function clears any such placeholder keys from the hash.
1584 See Hash::Util::lock_keys() for an example of its use.
1585
1586         void    hv_clear_placeholders(HV* hb)
1587
1588 =for hackers
1589 Found in file hv.c
1590
1591 =item hv_delete
1592 X<hv_delete>
1593
1594 Deletes a key/value pair in the hash.  The value SV is removed from the
1595 hash and returned to the caller.  The C<klen> is the length of the key.
1596 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1597 will be returned.
1598
1599         SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
1600
1601 =for hackers
1602 Found in file hv.c
1603
1604 =item hv_delete_ent
1605 X<hv_delete_ent>
1606
1607 Deletes a key/value pair in the hash.  The value SV is removed from the
1608 hash and returned to the caller.  The C<flags> value will normally be zero;
1609 if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
1610 precomputed hash value, or 0 to ask for it to be computed.
1611
1612         SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1613
1614 =for hackers
1615 Found in file hv.c
1616
1617 =item hv_exists
1618 X<hv_exists>
1619
1620 Returns a boolean indicating whether the specified hash key exists.  The
1621 C<klen> is the length of the key.
1622
1623         bool    hv_exists(HV* tb, const char* key, I32 klen)
1624
1625 =for hackers
1626 Found in file hv.c
1627
1628 =item hv_exists_ent
1629 X<hv_exists_ent>
1630
1631 Returns a boolean indicating whether the specified hash key exists. C<hash>
1632 can be a valid precomputed hash value, or 0 to ask for it to be
1633 computed.
1634
1635         bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
1636
1637 =for hackers
1638 Found in file hv.c
1639
1640 =item hv_fetch
1641 X<hv_fetch>
1642
1643 Returns the SV which corresponds to the specified key in the hash.  The
1644 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
1645 part of a store.  Check that the return value is non-null before
1646 dereferencing it to an C<SV*>.
1647
1648 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1649 information on how to use this function on tied hashes.
1650
1651         SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1652
1653 =for hackers
1654 Found in file hv.c
1655
1656 =item hv_fetchs
1657 X<hv_fetchs>
1658
1659 Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1660
1661         SV**    hv_fetchs(HV* tb, const char* key, I32 lval)
1662
1663 =for hackers
1664 Found in file handy.h
1665
1666 =item hv_fetch_ent
1667 X<hv_fetch_ent>
1668
1669 Returns the hash entry which corresponds to the specified key in the hash.
1670 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1671 if you want the function to compute it.  IF C<lval> is set then the fetch
1672 will be part of a store.  Make sure the return value is non-null before
1673 accessing it.  The return value when C<tb> is a tied hash is a pointer to a
1674 static location, so be sure to make a copy of the structure if you need to
1675 store it somewhere.
1676
1677 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1678 information on how to use this function on tied hashes.
1679
1680         HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1681
1682 =for hackers
1683 Found in file hv.c
1684
1685 =item hv_iterinit
1686 X<hv_iterinit>
1687
1688 Prepares a starting point to traverse a hash table.  Returns the number of
1689 keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
1690 currently only meaningful for hashes without tie magic.
1691
1692 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1693 hash buckets that happen to be in use.  If you still need that esoteric
1694 value, you can get it through the macro C<HvFILL(tb)>.
1695
1696
1697         I32     hv_iterinit(HV* tb)
1698
1699 =for hackers
1700 Found in file hv.c
1701
1702 =item hv_iterkey
1703 X<hv_iterkey>
1704
1705 Returns the key from the current position of the hash iterator.  See
1706 C<hv_iterinit>.
1707
1708         char*   hv_iterkey(HE* entry, I32* retlen)
1709
1710 =for hackers
1711 Found in file hv.c
1712
1713 =item hv_iterkeysv
1714 X<hv_iterkeysv>
1715
1716 Returns the key as an C<SV*> from the current position of the hash
1717 iterator.  The return value will always be a mortal copy of the key.  Also
1718 see C<hv_iterinit>.
1719
1720         SV*     hv_iterkeysv(HE* entry)
1721
1722 =for hackers
1723 Found in file hv.c
1724
1725 =item hv_iternext
1726 X<hv_iternext>
1727
1728 Returns entries from a hash iterator.  See C<hv_iterinit>.
1729
1730 You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1731 iterator currently points to, without losing your place or invalidating your
1732 iterator.  Note that in this case the current entry is deleted from the hash
1733 with your iterator holding the last reference to it.  Your iterator is flagged
1734 to free the entry on the next call to C<hv_iternext>, so you must not discard
1735 your iterator immediately else the entry will leak - call C<hv_iternext> to
1736 trigger the resource deallocation.
1737
1738         HE*     hv_iternext(HV* tb)
1739
1740 =for hackers
1741 Found in file hv.c
1742
1743 =item hv_iternextsv
1744 X<hv_iternextsv>
1745
1746 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1747 operation.
1748
1749         SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
1750
1751 =for hackers
1752 Found in file hv.c
1753
1754 =item hv_iternext_flags
1755 X<hv_iternext_flags>
1756
1757 Returns entries from a hash iterator.  See C<hv_iterinit> and C<hv_iternext>.
1758 The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1759 set the placeholders keys (for restricted hashes) will be returned in addition
1760 to normal keys. By default placeholders are automatically skipped over.
1761 Currently a placeholder is implemented with a value that is
1762 C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1763 restricted hashes may change, and the implementation currently is
1764 insufficiently abstracted for any change to be tidy.
1765
1766 NOTE: this function is experimental and may change or be
1767 removed without notice.
1768
1769         HE*     hv_iternext_flags(HV* tb, I32 flags)
1770
1771 =for hackers
1772 Found in file hv.c
1773
1774 =item hv_iterval
1775 X<hv_iterval>
1776
1777 Returns the value from the current position of the hash iterator.  See
1778 C<hv_iterkey>.
1779
1780         SV*     hv_iterval(HV* tb, HE* entry)
1781
1782 =for hackers
1783 Found in file hv.c
1784
1785 =item hv_magic
1786 X<hv_magic>
1787
1788 Adds magic to a hash.  See C<sv_magic>.
1789
1790         void    hv_magic(HV* hv, GV* gv, int how)
1791
1792 =for hackers
1793 Found in file hv.c
1794
1795 =item hv_scalar
1796 X<hv_scalar>
1797
1798 Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1799
1800         SV*     hv_scalar(HV* hv)
1801
1802 =for hackers
1803 Found in file hv.c
1804
1805 =item hv_store
1806 X<hv_store>
1807
1808 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
1809 the length of the key.  The C<hash> parameter is the precomputed hash
1810 value; if it is zero then Perl will compute it.  The return value will be
1811 NULL if the operation failed or if the value did not need to be actually
1812 stored within the hash (as in the case of tied hashes).  Otherwise it can
1813 be dereferenced to get the original C<SV*>.  Note that the caller is
1814 responsible for suitably incrementing the reference count of C<val> before
1815 the call, and decrementing it if the function returned NULL.  Effectively
1816 a successful hv_store takes ownership of one reference to C<val>.  This is
1817 usually what you want; a newly created SV has a reference count of one, so
1818 if all your code does is create SVs then store them in a hash, hv_store
1819 will own the only reference to the new SV, and your code doesn't need to do
1820 anything further to tidy up.  hv_store is not implemented as a call to
1821 hv_store_ent, and does not create a temporary SV for the key, so if your
1822 key data is not already in SV form then use hv_store in preference to
1823 hv_store_ent.
1824
1825 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1826 information on how to use this function on tied hashes.
1827
1828         SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1829
1830 =for hackers
1831 Found in file hv.c
1832
1833 =item hv_stores
1834 X<hv_stores>
1835
1836 Like C<hv_store>, but takes a literal string instead of a string/length pair
1837 and omits the hash parameter.
1838
1839         SV**    hv_stores(HV* tb, const char* key, NULLOK SV* val)
1840
1841 =for hackers
1842 Found in file handy.h
1843
1844 =item hv_store_ent
1845 X<hv_store_ent>
1846
1847 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
1848 parameter is the precomputed hash value; if it is zero then Perl will
1849 compute it.  The return value is the new hash entry so created.  It will be
1850 NULL if the operation failed or if the value did not need to be actually
1851 stored within the hash (as in the case of tied hashes).  Otherwise the
1852 contents of the return value can be accessed using the C<He?> macros
1853 described here.  Note that the caller is responsible for suitably
1854 incrementing the reference count of C<val> before the call, and
1855 decrementing it if the function returned NULL.  Effectively a successful
1856 hv_store_ent takes ownership of one reference to C<val>.  This is
1857 usually what you want; a newly created SV has a reference count of one, so
1858 if all your code does is create SVs then store them in a hash, hv_store
1859 will own the only reference to the new SV, and your code doesn't need to do
1860 anything further to tidy up.  Note that hv_store_ent only reads the C<key>;
1861 unlike C<val> it does not take ownership of it, so maintaining the correct
1862 reference count on C<key> is entirely the caller's responsibility.  hv_store
1863 is not implemented as a call to hv_store_ent, and does not create a temporary
1864 SV for the key, so if your key data is not already in SV form then use
1865 hv_store in preference to hv_store_ent.
1866
1867 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1868 information on how to use this function on tied hashes.
1869
1870         HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1871
1872 =for hackers
1873 Found in file hv.c
1874
1875 =item hv_undef
1876 X<hv_undef>
1877
1878 Undefines the hash.
1879
1880         void    hv_undef(HV* tb)
1881
1882 =for hackers
1883 Found in file hv.c
1884
1885 =item newHV
1886 X<newHV>
1887
1888 Creates a new HV.  The reference count is set to 1.
1889
1890         HV*     newHV()
1891
1892 =for hackers
1893 Found in file hv.c
1894
1895
1896 =back
1897
1898 =head1 Magical Functions
1899
1900 =over 8
1901
1902 =item mg_clear
1903 X<mg_clear>
1904
1905 Clear something magical that the SV represents.  See C<sv_magic>.
1906
1907         int     mg_clear(SV* sv)
1908
1909 =for hackers
1910 Found in file mg.c
1911
1912 =item mg_copy
1913 X<mg_copy>
1914
1915 Copies the magic from one SV to another.  See C<sv_magic>.
1916
1917         int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1918
1919 =for hackers
1920 Found in file mg.c
1921
1922 =item mg_find
1923 X<mg_find>
1924
1925 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
1926
1927         MAGIC*  mg_find(const SV* sv, int type)
1928
1929 =for hackers
1930 Found in file mg.c
1931
1932 =item mg_free
1933 X<mg_free>
1934
1935 Free any magic storage used by the SV.  See C<sv_magic>.
1936
1937         int     mg_free(SV* sv)
1938
1939 =for hackers
1940 Found in file mg.c
1941
1942 =item mg_get
1943 X<mg_get>
1944
1945 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
1946
1947         int     mg_get(SV* sv)
1948
1949 =for hackers
1950 Found in file mg.c
1951
1952 =item mg_length
1953 X<mg_length>
1954
1955 Report on the SV's length.  See C<sv_magic>.
1956
1957         U32     mg_length(SV* sv)
1958
1959 =for hackers
1960 Found in file mg.c
1961
1962 =item mg_magical
1963 X<mg_magical>
1964
1965 Turns on the magical status of an SV.  See C<sv_magic>.
1966
1967         void    mg_magical(SV* sv)
1968
1969 =for hackers
1970 Found in file mg.c
1971
1972 =item mg_set
1973 X<mg_set>
1974
1975 Do magic after a value is assigned to the SV.  See C<sv_magic>.
1976
1977         int     mg_set(SV* sv)
1978
1979 =for hackers
1980 Found in file mg.c
1981
1982 =item SvGETMAGIC
1983 X<SvGETMAGIC>
1984
1985 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
1986 argument more than once.
1987
1988         void    SvGETMAGIC(SV* sv)
1989
1990 =for hackers
1991 Found in file sv.h
1992
1993 =item SvLOCK
1994 X<SvLOCK>
1995
1996 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1997 has been loaded.
1998
1999         void    SvLOCK(SV* sv)
2000
2001 =for hackers
2002 Found in file sv.h
2003
2004 =item SvSETMAGIC
2005 X<SvSETMAGIC>
2006
2007 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
2008 argument more than once.
2009
2010         void    SvSETMAGIC(SV* sv)
2011
2012 =for hackers
2013 Found in file sv.h
2014
2015 =item SvSetMagicSV
2016 X<SvSetMagicSV>
2017
2018 Like C<SvSetSV>, but does any set magic required afterwards.
2019
2020         void    SvSetMagicSV(SV* dsb, SV* ssv)
2021
2022 =for hackers
2023 Found in file sv.h
2024
2025 =item SvSetMagicSV_nosteal
2026 X<SvSetMagicSV_nosteal>
2027
2028 Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
2029
2030         void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2031
2032 =for hackers
2033 Found in file sv.h
2034
2035 =item SvSetSV
2036 X<SvSetSV>
2037
2038 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
2039 more than once.
2040
2041         void    SvSetSV(SV* dsb, SV* ssv)
2042
2043 =for hackers
2044 Found in file sv.h
2045
2046 =item SvSetSV_nosteal
2047 X<SvSetSV_nosteal>
2048
2049 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2050 ssv. May evaluate arguments more than once.
2051
2052         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
2053
2054 =for hackers
2055 Found in file sv.h
2056
2057 =item SvSHARE
2058 X<SvSHARE>
2059
2060 Arranges for sv to be shared between threads if a suitable module
2061 has been loaded.
2062
2063         void    SvSHARE(SV* sv)
2064
2065 =for hackers
2066 Found in file sv.h
2067
2068 =item SvUNLOCK
2069 X<SvUNLOCK>
2070
2071 Releases a mutual exclusion lock on sv if a suitable module
2072 has been loaded.
2073
2074         void    SvUNLOCK(SV* sv)
2075
2076 =for hackers
2077 Found in file sv.h
2078
2079
2080 =back
2081
2082 =head1 Memory Management
2083
2084 =over 8
2085
2086 =item Copy
2087 X<Copy>
2088
2089 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
2090 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2091 the type.  May fail on overlapping copies.  See also C<Move>.
2092
2093         void    Copy(void* src, void* dest, int nitems, type)
2094
2095 =for hackers
2096 Found in file handy.h
2097
2098 =item CopyD
2099 X<CopyD>
2100
2101 Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2102 optimise.
2103
2104         void *  CopyD(void* src, void* dest, int nitems, type)
2105
2106 =for hackers
2107 Found in file handy.h
2108
2109 =item Move
2110 X<Move>
2111
2112 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
2113 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2114 the type.  Can do overlapping moves.  See also C<Copy>.
2115
2116         void    Move(void* src, void* dest, int nitems, type)
2117
2118 =for hackers
2119 Found in file handy.h
2120
2121 =item MoveD
2122 X<MoveD>
2123
2124 Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2125 optimise.
2126
2127         void *  MoveD(void* src, void* dest, int nitems, type)
2128
2129 =for hackers
2130 Found in file handy.h
2131
2132 =item Newx
2133 X<Newx>
2134
2135 The XSUB-writer's interface to the C C<malloc> function.
2136
2137 In 5.9.3, Newx() and friends replace the older New() API, and drops
2138 the first parameter, I<x>, a debug aid which allowed callers to identify
2139 themselves.  This aid has been superseded by a new build option,
2140 PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>).  The older API is still
2141 there for use in XS modules supporting older perls.
2142
2143         void    Newx(void* ptr, int nitems, type)
2144
2145 =for hackers
2146 Found in file handy.h
2147
2148 =item Newxc
2149 X<Newxc>
2150
2151 The XSUB-writer's interface to the C C<malloc> function, with
2152 cast.  See also C<Newx>.
2153
2154         void    Newxc(void* ptr, int nitems, type, cast)
2155
2156 =for hackers
2157 Found in file handy.h
2158
2159 =item Newxz
2160 X<Newxz>
2161
2162 The XSUB-writer's interface to the C C<malloc> function.  The allocated
2163 memory is zeroed with C<memzero>.  See also C<Newx>.
2164
2165         void    Newxz(void* ptr, int nitems, type)
2166
2167 =for hackers
2168 Found in file handy.h
2169
2170 =item Poison
2171 X<Poison>
2172
2173 PoisonWith(0xEF) for catching access to freed memory.
2174
2175         void    Poison(void* dest, int nitems, type)
2176
2177 =for hackers
2178 Found in file handy.h
2179
2180 =item PoisonFree
2181 X<PoisonFree>
2182
2183 PoisonWith(0xEF) for catching access to freed memory.
2184
2185         void    PoisonFree(void* dest, int nitems, type)
2186
2187 =for hackers
2188 Found in file handy.h
2189
2190 =item PoisonNew
2191 X<PoisonNew>
2192
2193 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2194
2195         void    PoisonNew(void* dest, int nitems, type)
2196
2197 =for hackers
2198 Found in file handy.h
2199
2200 =item PoisonWith
2201 X<PoisonWith>
2202
2203 Fill up memory with a byte pattern (a byte repeated over and over
2204 again) that hopefully catches attempts to access uninitialized memory.
2205
2206         void    PoisonWith(void* dest, int nitems, type, U8 byte)
2207
2208 =for hackers
2209 Found in file handy.h
2210
2211 =item Renew
2212 X<Renew>
2213
2214 The XSUB-writer's interface to the C C<realloc> function.
2215
2216         void    Renew(void* ptr, int nitems, type)
2217
2218 =for hackers
2219 Found in file handy.h
2220
2221 =item Renewc
2222 X<Renewc>
2223
2224 The XSUB-writer's interface to the C C<realloc> function, with
2225 cast.
2226
2227         void    Renewc(void* ptr, int nitems, type, cast)
2228
2229 =for hackers
2230 Found in file handy.h
2231
2232 =item Safefree
2233 X<Safefree>
2234
2235 The XSUB-writer's interface to the C C<free> function.
2236
2237         void    Safefree(void* ptr)
2238
2239 =for hackers
2240 Found in file handy.h
2241
2242 =item savepv
2243 X<savepv>
2244
2245 Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2246 string which is a duplicate of C<pv>. The size of the string is
2247 determined by C<strlen()>. The memory allocated for the new string can
2248 be freed with the C<Safefree()> function.
2249
2250         char*   savepv(const char* pv)
2251
2252 =for hackers
2253 Found in file util.c
2254
2255 =item savepvn
2256 X<savepvn>
2257
2258 Perl's version of what C<strndup()> would be if it existed. Returns a
2259 pointer to a newly allocated string which is a duplicate of the first
2260 C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2261 the new string can be freed with the C<Safefree()> function.
2262
2263         char*   savepvn(const char* pv, I32 len)
2264
2265 =for hackers
2266 Found in file util.c
2267
2268 =item savepvs
2269 X<savepvs>
2270
2271 Like C<savepvn>, but takes a literal string instead of a string/length pair.
2272
2273         char*   savepvs(const char* s)
2274
2275 =for hackers
2276 Found in file handy.h
2277
2278 =item savesharedpv
2279 X<savesharedpv>
2280
2281 A version of C<savepv()> which allocates the duplicate string in memory
2282 which is shared between threads.
2283
2284         char*   savesharedpv(const char* pv)
2285
2286 =for hackers
2287 Found in file util.c
2288
2289 =item savesharedpvn
2290 X<savesharedpvn>
2291
2292 A version of C<savepvn()> which allocates the duplicate string in memory
2293 which is shared between threads. (With the specific difference that a NULL
2294 pointer is not acceptable)
2295
2296         char*   savesharedpvn(const char *const pv, const STRLEN len)
2297
2298 =for hackers
2299 Found in file util.c
2300
2301 =item savesvpv
2302 X<savesvpv>
2303
2304 A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
2305 the passed in SV using C<SvPV()>
2306
2307         char*   savesvpv(SV* sv)
2308
2309 =for hackers
2310 Found in file util.c
2311
2312 =item StructCopy
2313 X<StructCopy>
2314
2315 This is an architecture-independent macro to copy one structure to another.
2316
2317         void    StructCopy(type src, type dest, type)
2318
2319 =for hackers
2320 Found in file handy.h
2321
2322 =item Zero
2323 X<Zero>
2324
2325 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2326 destination, C<nitems> is the number of items, and C<type> is the type.
2327
2328         void    Zero(void* dest, int nitems, type)
2329
2330 =for hackers
2331 Found in file handy.h
2332
2333 =item ZeroD
2334 X<ZeroD>
2335
2336 Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2337 optimise.
2338
2339         void *  ZeroD(void* dest, int nitems, type)
2340
2341 =for hackers
2342 Found in file handy.h
2343
2344
2345 =back
2346
2347 =head1 Miscellaneous Functions
2348
2349 =over 8
2350
2351 =item fbm_compile
2352 X<fbm_compile>
2353
2354 Analyses the string in order to make fast searches on it using fbm_instr()
2355 -- the Boyer-Moore algorithm.
2356
2357         void    fbm_compile(SV* sv, U32 flags)
2358
2359 =for hackers
2360 Found in file util.c
2361
2362 =item fbm_instr
2363 X<fbm_instr>
2364
2365 Returns the location of the SV in the string delimited by C<str> and
2366 C<strend>.  It returns C<NULL> if the string can't be found.  The C<sv>
2367 does not have to be fbm_compiled, but the search will not be as fast
2368 then.
2369
2370         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
2371
2372 =for hackers
2373 Found in file util.c
2374
2375 =item form
2376 X<form>
2377
2378 Takes a sprintf-style format pattern and conventional
2379 (non-SV) arguments and returns the formatted string.
2380
2381     (char *) Perl_form(pTHX_ const char* pat, ...)
2382
2383 can be used any place a string (char *) is required:
2384
2385     char * s = Perl_form("%d.%d",major,minor);
2386
2387 Uses a single private buffer so if you want to format several strings you
2388 must explicitly copy the earlier strings away (and free the copies when you
2389 are done).
2390
2391         char*   form(const char* pat, ...)
2392
2393 =for hackers
2394 Found in file util.c
2395
2396 =item getcwd_sv
2397 X<getcwd_sv>
2398
2399 Fill the sv with current working directory
2400
2401         int     getcwd_sv(SV* sv)
2402
2403 =for hackers
2404 Found in file util.c
2405
2406 =item my_snprintf
2407 X<my_snprintf>
2408
2409 The C library C<snprintf> functionality, if available and
2410 standards-compliant (uses C<vsnprintf>, actually).  However, if the
2411 C<vsnprintf> is not available, will unfortunately use the unsafe
2412 C<vsprintf> which can overrun the buffer (there is an overrun check,
2413 but that may be too late).  Consider using C<sv_vcatpvf> instead, or
2414 getting C<vsnprintf>.
2415
2416         int     my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2417
2418 =for hackers
2419 Found in file util.c
2420
2421 =item my_sprintf
2422 X<my_sprintf>
2423
2424 The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2425 the length of the string written to the buffer. Only rare pre-ANSI systems
2426 need the wrapper function - usually this is a direct call to C<sprintf>.
2427
2428         int     my_sprintf(char *buffer, const char *pat, ...)
2429
2430 =for hackers
2431 Found in file util.c
2432
2433 =item my_vsnprintf
2434 X<my_vsnprintf>
2435
2436 The C library C<vsnprintf> if available and standards-compliant.
2437 However, if if the C<vsnprintf> is not available, will unfortunately
2438 use the unsafe C<vsprintf> which can overrun the buffer (there is an
2439 overrun check, but that may be too late).  Consider using
2440 C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2441
2442         int     my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2443
2444 =for hackers
2445 Found in file util.c
2446
2447 =item new_version
2448 X<new_version>
2449
2450 Returns a new version object based on the passed in SV:
2451
2452     SV *sv = new_version(SV *ver);
2453
2454 Does not alter the passed in ver SV.  See "upg_version" if you
2455 want to upgrade the SV.
2456
2457         SV*     new_version(SV *ver)
2458
2459 =for hackers
2460 Found in file util.c
2461
2462 =item scan_version
2463 X<scan_version>
2464
2465 Returns a pointer to the next character after the parsed
2466 version string, as well as upgrading the passed in SV to
2467 an RV.
2468
2469 Function must be called with an already existing SV like
2470
2471     sv = newSV(0);
2472     s = scan_version(s, SV *sv, bool qv);
2473
2474 Performs some preprocessing to the string to ensure that
2475 it has the correct characteristics of a version.  Flags the
2476 object if it contains an underscore (which denotes this
2477 is an alpha version).  The boolean qv denotes that the version
2478 should be interpreted as if it had multiple decimals, even if
2479 it doesn't.
2480
2481         const char*     scan_version(const char *vstr, SV *sv, bool qv)
2482
2483 =for hackers
2484 Found in file util.c
2485
2486 =item strEQ
2487 X<strEQ>
2488
2489 Test two strings to see if they are equal.  Returns true or false.
2490
2491         bool    strEQ(char* s1, char* s2)
2492
2493 =for hackers
2494 Found in file handy.h
2495
2496 =item strGE
2497 X<strGE>
2498
2499 Test two strings to see if the first, C<s1>, is greater than or equal to
2500 the second, C<s2>.  Returns true or false.
2501
2502         bool    strGE(char* s1, char* s2)
2503
2504 =for hackers
2505 Found in file handy.h
2506
2507 =item strGT
2508 X<strGT>
2509
2510 Test two strings to see if the first, C<s1>, is greater than the second,
2511 C<s2>.  Returns true or false.
2512
2513         bool    strGT(char* s1, char* s2)
2514
2515 =for hackers
2516 Found in file handy.h
2517
2518 =item strLE
2519 X<strLE>
2520
2521 Test two strings to see if the first, C<s1>, is less than or equal to the
2522 second, C<s2>.  Returns true or false.
2523
2524         bool    strLE(char* s1, char* s2)
2525
2526 =for hackers
2527 Found in file handy.h
2528
2529 =item strLT
2530 X<strLT>
2531
2532 Test two strings to see if the first, C<s1>, is less than the second,
2533 C<s2>.  Returns true or false.
2534
2535         bool    strLT(char* s1, char* s2)
2536
2537 =for hackers
2538 Found in file handy.h
2539
2540 =item strNE
2541 X<strNE>
2542
2543 Test two strings to see if they are different.  Returns true or
2544 false.
2545
2546         bool    strNE(char* s1, char* s2)
2547
2548 =for hackers
2549 Found in file handy.h
2550
2551 =item strnEQ
2552 X<strnEQ>
2553
2554 Test two strings to see if they are equal.  The C<len> parameter indicates
2555 the number of bytes to compare.  Returns true or false. (A wrapper for
2556 C<strncmp>).
2557
2558         bool    strnEQ(char* s1, char* s2, STRLEN len)
2559
2560 =for hackers
2561 Found in file handy.h
2562
2563 =item strnNE
2564 X<strnNE>
2565
2566 Test two strings to see if they are different.  The C<len> parameter
2567 indicates the number of bytes to compare.  Returns true or false. (A
2568 wrapper for C<strncmp>).
2569
2570         bool    strnNE(char* s1, char* s2, STRLEN len)
2571
2572 =for hackers
2573 Found in file handy.h
2574
2575 =item sv_nosharing
2576 X<sv_nosharing>
2577
2578 Dummy routine which "shares" an SV when there is no sharing module present.
2579 Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2580 Exists to avoid test for a NULL function pointer and because it could
2581 potentially warn under some level of strict-ness.
2582
2583         void    sv_nosharing(SV *sv)
2584
2585 =for hackers
2586 Found in file util.c
2587
2588 =item upg_version
2589 X<upg_version>
2590
2591 In-place upgrade of the supplied SV to a version object.
2592
2593     SV *sv = upg_version(SV *sv, bool qv);
2594
2595 Returns a pointer to the upgraded SV.  Set the boolean qv if you want
2596 to force this SV to be interpreted as an "extended" version.
2597
2598         SV*     upg_version(SV *ver, bool qv)
2599
2600 =for hackers
2601 Found in file util.c
2602
2603 =item vcmp
2604 X<vcmp>
2605
2606 Version object aware cmp.  Both operands must already have been 
2607 converted into version objects.
2608
2609         int     vcmp(SV *lvs, SV *rvs)
2610
2611 =for hackers
2612 Found in file util.c
2613
2614 =item vnormal
2615 X<vnormal>
2616
2617 Accepts a version object and returns the normalized string
2618 representation.  Call like:
2619
2620     sv = vnormal(rv);
2621
2622 NOTE: you can pass either the object directly or the SV
2623 contained within the RV.
2624
2625         SV*     vnormal(SV *vs)
2626
2627 =for hackers
2628 Found in file util.c
2629
2630 =item vnumify
2631 X<vnumify>
2632
2633 Accepts a version object and returns the normalized floating
2634 point representation.  Call like:
2635
2636     sv = vnumify(rv);
2637
2638 NOTE: you can pass either the object directly or the SV
2639 contained within the RV.
2640
2641         SV*     vnumify(SV *vs)
2642
2643 =for hackers
2644 Found in file util.c
2645
2646 =item vstringify
2647 X<vstringify>
2648
2649 In order to maintain maximum compatibility with earlier versions
2650 of Perl, this function will return either the floating point
2651 notation or the multiple dotted notation, depending on whether
2652 the original version contained 1 or more dots, respectively
2653
2654         SV*     vstringify(SV *vs)
2655
2656 =for hackers
2657 Found in file util.c
2658
2659 =item vverify
2660 X<vverify>
2661
2662 Validates that the SV contains a valid version object.
2663
2664     bool vverify(SV *vobj);
2665
2666 Note that it only confirms the bare minimum structure (so as not to get
2667 confused by derived classes which may contain additional hash entries):
2668
2669         bool    vverify(SV *vs)
2670
2671 =for hackers
2672 Found in file util.c
2673
2674
2675 =back
2676
2677 =head1 MRO Functions
2678
2679 =over 8
2680
2681 =item mro_get_linear_isa
2682 X<mro_get_linear_isa>
2683
2684 Returns either C<mro_get_linear_isa_c3> or
2685 C<mro_get_linear_isa_dfs> for the given stash,
2686 dependant upon which MRO is in effect
2687 for that stash.  The return value is a
2688 read-only AV*.
2689
2690 You are responsible for C<SvREFCNT_inc()> on the
2691 return value if you plan to store it anywhere
2692 semi-permanently (otherwise it might be deleted
2693 out from under you the next time the cache is
2694 invalidated).
2695
2696         AV*     mro_get_linear_isa(HV* stash)
2697
2698 =for hackers
2699 Found in file mro.c
2700
2701 =item mro_get_linear_isa_c3
2702 X<mro_get_linear_isa_c3>
2703
2704 Returns the C3 linearization of @ISA
2705 the given stash.  The return value is a read-only AV*.
2706 C<level> should be 0 (it is used internally in this
2707 function's recursion).
2708
2709 You are responsible for C<SvREFCNT_inc()> on the
2710 return value if you plan to store it anywhere
2711 semi-permanently (otherwise it might be deleted
2712 out from under you the next time the cache is
2713 invalidated).
2714
2715         AV*     mro_get_linear_isa_c3(HV* stash, I32 level)
2716
2717 =for hackers
2718 Found in file mro.c
2719
2720 =item mro_get_linear_isa_dfs
2721 X<mro_get_linear_isa_dfs>
2722
2723 Returns the Depth-First Search linearization of @ISA
2724 the given stash.  The return value is a read-only AV*.
2725 C<level> should be 0 (it is used internally in this
2726 function's recursion).
2727
2728 You are responsible for C<SvREFCNT_inc()> on the
2729 return value if you plan to store it anywhere
2730 semi-permanently (otherwise it might be deleted
2731 out from under you the next time the cache is
2732 invalidated).
2733
2734         AV*     mro_get_linear_isa_dfs(HV* stash, I32 level)
2735
2736 =for hackers
2737 Found in file mro.c
2738
2739 =item mro_method_changed_in
2740 X<mro_method_changed_in>
2741
2742 Invalidates method caching on any child classes
2743 of the given stash, so that they might notice
2744 the changes in this one.
2745
2746 Ideally, all instances of C<PL_sub_generation++> in
2747 perl source outside of C<mro.c> should be
2748 replaced by calls to this.
2749
2750 Perl automatically handles most of the common
2751 ways a method might be redefined.  However, there
2752 are a few ways you could change a method in a stash
2753 without the cache code noticing, in which case you
2754 need to call this method afterwards:
2755
2756 1) Directly manipulating the stash HV entries from
2757 XS code.
2758
2759 2) Assigning a reference to a readonly scalar
2760 constant into a stash entry in order to create
2761 a constant subroutine (like constant.pm
2762 does).
2763
2764 This same method is available from pure perl
2765 via, C<mro::method_changed_in(classname)>.
2766
2767         void    mro_method_changed_in(HV* stash)
2768
2769 =for hackers
2770 Found in file mro.c
2771
2772
2773 =back
2774
2775 =head1 Multicall Functions
2776
2777 =over 8
2778
2779 =item dMULTICALL
2780 X<dMULTICALL>
2781
2782 Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2783
2784                 dMULTICALL;
2785
2786 =for hackers
2787 Found in file cop.h
2788
2789 =item MULTICALL
2790 X<MULTICALL>
2791
2792 Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2793
2794                 MULTICALL;
2795
2796 =for hackers
2797 Found in file cop.h
2798
2799 =item POP_MULTICALL
2800 X<POP_MULTICALL>
2801
2802 Closing bracket for a lightweight callback.
2803 See L<perlcall/Lightweight Callbacks>.
2804
2805                 POP_MULTICALL;
2806
2807 =for hackers
2808 Found in file cop.h
2809
2810 =item PUSH_MULTICALL
2811 X<PUSH_MULTICALL>
2812
2813 Opening bracket for a lightweight callback.
2814 See L<perlcall/Lightweight Callbacks>.
2815
2816                 PUSH_MULTICALL;
2817
2818 =for hackers
2819 Found in file cop.h
2820
2821
2822 =back
2823
2824 =head1 Numeric functions
2825
2826 =over 8
2827
2828 =item grok_bin
2829 X<grok_bin>
2830
2831 converts a string representing a binary number to numeric form.
2832
2833 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2834 conversion flags, and I<result> should be NULL or a pointer to an NV.
2835 The scan stops at the end of the string, or the first invalid character.
2836 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2837 invalid character will also trigger a warning.
2838 On return I<*len> is set to the length of the scanned string,
2839 and I<*flags> gives output flags.
2840
2841 If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2842 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2843 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2844 and writes the value to I<*result> (or the value is discarded if I<result>
2845 is NULL).
2846
2847 The binary number may optionally be prefixed with "0b" or "b" unless
2848 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2849 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2850 number may use '_' characters to separate digits.
2851
2852         UV      grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2853
2854 =for hackers
2855 Found in file numeric.c
2856
2857 =item grok_hex
2858 X<grok_hex>
2859
2860 converts a string representing a hex number to numeric form.
2861
2862 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2863 conversion flags, and I<result> should be NULL or a pointer to an NV.
2864 The scan stops at the end of the string, or the first invalid character.
2865 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2866 invalid character will also trigger a warning.
2867 On return I<*len> is set to the length of the scanned string,
2868 and I<*flags> gives output flags.
2869
2870 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2871 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2872 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2873 and writes the value to I<*result> (or the value is discarded if I<result>
2874 is NULL).
2875
2876 The hex number may optionally be prefixed with "0x" or "x" unless
2877 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2878 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2879 number may use '_' characters to separate digits.
2880
2881         UV      grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2882
2883 =for hackers
2884 Found in file numeric.c
2885
2886 =item grok_number
2887 X<grok_number>
2888
2889 Recognise (or not) a number.  The type of the number is returned
2890 (0 if unrecognised), otherwise it is a bit-ORed combination of
2891 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2892 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2893
2894 If the value of the number can fit an in UV, it is returned in the *valuep
2895 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2896 will never be set unless *valuep is valid, but *valuep may have been assigned
2897 to during processing even though IS_NUMBER_IN_UV is not set on return.
2898 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2899 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2900
2901 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2902 seen (in which case *valuep gives the true value truncated to an integer), and
2903 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2904 absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
2905 number is larger than a UV.
2906
2907         int     grok_number(const char *pv, STRLEN len, UV *valuep)
2908
2909 =for hackers
2910 Found in file numeric.c
2911
2912 =item grok_numeric_radix
2913 X<grok_numeric_radix>
2914
2915 Scan and skip for a numeric decimal separator (radix).
2916
2917         bool    grok_numeric_radix(const char **sp, const char *send)
2918
2919 =for hackers
2920 Found in file numeric.c
2921
2922 =item grok_oct
2923 X<grok_oct>
2924
2925 converts a string representing an octal number to numeric form.
2926
2927 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2928 conversion flags, and I<result> should be NULL or a pointer to an NV.
2929 The scan stops at the end of the string, or the first invalid character.
2930 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2931 invalid character will also trigger a warning.
2932 On return I<*len> is set to the length of the scanned string,
2933 and I<*flags> gives output flags.
2934
2935 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2936 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2937 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2938 and writes the value to I<*result> (or the value is discarded if I<result>
2939 is NULL).
2940
2941 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2942 number may use '_' characters to separate digits.
2943
2944         UV      grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
2945
2946 =for hackers
2947 Found in file numeric.c
2948
2949 =item Perl_signbit
2950 X<Perl_signbit>
2951
2952 Return a non-zero integer if the sign bit on an NV is set, and 0 if
2953 it is not.  
2954
2955 If Configure detects this system has a signbit() that will work with
2956 our NVs, then we just use it via the #define in perl.h.  Otherwise,
2957 fall back on this implementation.  As a first pass, this gets everything
2958 right except -0.0.  Alas, catching -0.0 is the main use for this function,
2959 so this is not too helpful yet.  Still, at least we have the scaffolding
2960 in place to support other systems, should that prove useful.
2961
2962
2963 Configure notes:  This function is called 'Perl_signbit' instead of a
2964 plain 'signbit' because it is easy to imagine a system having a signbit()
2965 function or macro that doesn't happen to work with our particular choice
2966 of NVs.  We shouldn't just re-#define signbit as Perl_signbit and expect
2967 the standard system headers to be happy.  Also, this is a no-context
2968 function (no pTHX_) because Perl_signbit() is usually re-#defined in
2969 perl.h as a simple macro call to the system's signbit().
2970 Users should just always call Perl_signbit().
2971
2972 NOTE: this function is experimental and may change or be
2973 removed without notice.
2974
2975         int     Perl_signbit(NV f)
2976
2977 =for hackers
2978 Found in file numeric.c
2979
2980 =item scan_bin
2981 X<scan_bin>
2982
2983 For backwards compatibility. Use C<grok_bin> instead.
2984
2985         NV      scan_bin(const char* start, STRLEN len, STRLEN* retlen)
2986
2987 =for hackers
2988 Found in file numeric.c
2989
2990 =item scan_hex
2991 X<scan_hex>
2992
2993 For backwards compatibility. Use C<grok_hex> instead.
2994
2995         NV      scan_hex(const char* start, STRLEN len, STRLEN* retlen)
2996
2997 =for hackers
2998 Found in file numeric.c
2999
3000 =item scan_oct
3001 X<scan_oct>
3002
3003 For backwards compatibility. Use C<grok_oct> instead.
3004
3005         NV      scan_oct(const char* start, STRLEN len, STRLEN* retlen)
3006
3007 =for hackers
3008 Found in file numeric.c
3009
3010
3011 =back
3012
3013 =head1 Optree Manipulation Functions
3014
3015 =over 8
3016
3017 =item cv_const_sv
3018 X<cv_const_sv>
3019
3020 If C<cv> is a constant sub eligible for inlining. returns the constant
3021 value returned by the sub.  Otherwise, returns NULL.
3022
3023 Constant subs can be created with C<newCONSTSUB> or as described in
3024 L<perlsub/"Constant Functions">.
3025
3026         SV*     cv_const_sv(CV* cv)
3027
3028 =for hackers
3029 Found in file op.c
3030
3031 =item newCONSTSUB
3032 X<newCONSTSUB>
3033
3034 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
3035 eligible for inlining at compile-time.
3036
3037         CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)
3038
3039 =for hackers
3040 Found in file op.c
3041
3042 =item newXS
3043 X<newXS>
3044
3045 Used by C<xsubpp> to hook up XSUBs as Perl subs.  I<filename> needs to be
3046 static storage, as it is used directly as CvFILE(), without a copy being made.
3047
3048 =for hackers
3049 Found in file op.c
3050
3051
3052 =back
3053
3054 =head1 Pad Data Structures
3055
3056 =over 8
3057
3058 =item pad_sv
3059 X<pad_sv>
3060
3061 Get the value at offset po in the current pad.
3062 Use macro PAD_SV instead of calling this function directly.
3063
3064         SV*     pad_sv(PADOFFSET po)
3065
3066 =for hackers
3067 Found in file pad.c
3068
3069
3070 =back
3071
3072 =head1 Per-Interpreter Variables
3073
3074 =over 8
3075
3076 =item PL_modglobal
3077 X<PL_modglobal>
3078
3079 C<PL_modglobal> is a general purpose, interpreter global HV for use by
3080 extensions that need to keep information on a per-interpreter basis.
3081 In a pinch, it can also be used as a symbol table for extensions
3082 to share data among each other.  It is a good idea to use keys
3083 prefixed by the package name of the extension that owns the data.
3084
3085         HV*     PL_modglobal
3086
3087 =for hackers
3088 Found in file intrpvar.h
3089
3090 =item PL_na
3091 X<PL_na>
3092
3093 A convenience variable which is typically used with C<SvPV> when one
3094 doesn't care about the length of the string.  It is usually more efficient
3095 to either declare a local variable and use that instead or to use the
3096 C<SvPV_nolen> macro.
3097
3098         STRLEN  PL_na
3099
3100 =for hackers
3101 Found in file intrpvar.h
3102
3103 =item PL_sv_no
3104 X<PL_sv_no>
3105
3106 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
3107 C<&PL_sv_no>.
3108
3109         SV      PL_sv_no
3110
3111 =for hackers
3112 Found in file intrpvar.h
3113
3114 =item PL_sv_undef
3115 X<PL_sv_undef>
3116
3117 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
3118
3119         SV      PL_sv_undef
3120
3121 =for hackers
3122 Found in file intrpvar.h
3123
3124 =item PL_sv_yes
3125 X<PL_sv_yes>
3126
3127 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
3128 C<&PL_sv_yes>.
3129
3130         SV      PL_sv_yes
3131
3132 =for hackers
3133 Found in file intrpvar.h
3134
3135
3136 =back
3137
3138 =head1 REGEXP Functions
3139
3140 =over 8
3141
3142 =item SvRX
3143 X<SvRX>
3144
3145 Convenience macro to get the REGEXP from a SV. This is approximately
3146 equivalent to the following snippet:
3147
3148     if (SvMAGICAL(sv))
3149         mg_get(sv);
3150     if (SvROK(sv) &&
3151         (tmpsv = (SV*)SvRV(sv)) &&
3152         SvTYPE(tmpsv) == SVt_PVMG &&
3153         (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
3154     {
3155         return (REGEXP *)tmpmg->mg_obj;
3156     }
3157
3158 NULL will be returned if a REGEXP* is not found.
3159
3160         REGEXP *        SvRX(SV *sv)
3161
3162 =for hackers
3163 Found in file regexp.h
3164
3165 =item SvRXOK
3166 X<SvRXOK>
3167
3168 Returns a boolean indicating whether the SV contains qr magic
3169 (PERL_MAGIC_qr).
3170
3171 If you want to do something with the REGEXP* later use SvRX instead
3172 and check for NULL.
3173
3174         bool    SvRXOK(SV* sv)
3175
3176 =for hackers
3177 Found in file regexp.h
3178
3179
3180 =back
3181
3182 =head1 Simple Exception Handling Macros
3183
3184 =over 8
3185
3186 =item dXCPT
3187 X<dXCPT>
3188
3189 Set up necessary local variables for exception handling.
3190 See L<perlguts/"Exception Handling">.
3191
3192                 dXCPT;
3193
3194 =for hackers
3195 Found in file XSUB.h
3196
3197 =item XCPT_CATCH
3198 X<XCPT_CATCH>
3199
3200 Introduces a catch block.  See L<perlguts/"Exception Handling">.
3201
3202 =for hackers
3203 Found in file XSUB.h
3204
3205 =item XCPT_RETHROW
3206 X<XCPT_RETHROW>
3207
3208 Rethrows a previously caught exception.  See L<perlguts/"Exception Handling">.
3209
3210                 XCPT_RETHROW;
3211
3212 =for hackers
3213 Found in file XSUB.h
3214
3215 =item XCPT_TRY_END
3216 X<XCPT_TRY_END>
3217
3218 Ends a try block.  See L<perlguts/"Exception Handling">.
3219
3220 =for hackers
3221 Found in file XSUB.h
3222
3223 =item XCPT_TRY_START
3224 X<XCPT_TRY_START>
3225
3226 Starts a try block.  See L<perlguts/"Exception Handling">.
3227
3228 =for hackers
3229 Found in file XSUB.h
3230
3231
3232 =back
3233
3234 =head1 Stack Manipulation Macros
3235
3236 =over 8
3237
3238 =item dMARK
3239 X<dMARK>
3240
3241 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
3242 C<dORIGMARK>.
3243
3244                 dMARK;
3245
3246 =for hackers
3247 Found in file pp.h
3248
3249 =item dORIGMARK
3250 X<dORIGMARK>
3251
3252 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
3253
3254                 dORIGMARK;
3255
3256 =for hackers
3257 Found in file pp.h
3258
3259 =item dSP
3260 X<dSP>
3261
3262 Declares a local copy of perl's stack pointer for the XSUB, available via
3263 the C<SP> macro.  See C<SP>.
3264
3265                 dSP;
3266
3267 =for hackers
3268 Found in file pp.h
3269
3270 =item EXTEND
3271 X<EXTEND>
3272
3273 Used to extend the argument stack for an XSUB's return values. Once
3274 used, guarantees that there is room for at least C<nitems> to be pushed
3275 onto the stack.
3276
3277         void    EXTEND(SP, int nitems)
3278
3279 =for hackers
3280 Found in file pp.h
3281
3282 =item MARK
3283 X<MARK>
3284
3285 Stack marker variable for the XSUB.  See C<dMARK>.
3286
3287 =for hackers
3288 Found in file pp.h
3289
3290 =item mPUSHi
3291 X<mPUSHi>
3292
3293 Push an integer onto the stack.  The stack must have room for this element.
3294 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi>
3295 and C<XPUSHi>.
3296
3297         void    mPUSHi(IV iv)
3298
3299 =for hackers
3300 Found in file pp.h
3301
3302 =item mPUSHn
3303 X<mPUSHn>
3304
3305 Push a double onto the stack.  The stack must have room for this element.
3306 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn>
3307 and C<XPUSHn>.
3308
3309         void    mPUSHn(NV nv)
3310
3311 =for hackers
3312 Found in file pp.h
3313
3314 =item mPUSHp
3315 X<mPUSHp>
3316
3317 Push a string onto the stack.  The stack must have room for this element.
3318 The C<len> indicates the length of the string.  Handles 'set' magic.  Does
3319 not use C<TARG>.  See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3320
3321         void    mPUSHp(char* str, STRLEN len)
3322
3323 =for hackers
3324 Found in file pp.h
3325
3326 =item mPUSHu
3327 X<mPUSHu>
3328
3329 Push an unsigned integer onto the stack.  The stack must have room for this
3330 element.  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHu>,
3331 C<mXPUSHu> and C<XPUSHu>.
3332
3333         void    mPUSHu(UV uv)
3334
3335 =for hackers
3336 Found in file pp.h
3337
3338 =item mXPUSHi
3339 X<mXPUSHi>
3340
3341 Push an integer onto the stack, extending the stack if necessary.  Handles
3342 'set' magic.  Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and
3343 C<PUSHi>.
3344
3345         void    mXPUSHi(IV iv)
3346
3347 =for hackers
3348 Found in file pp.h
3349
3350 =item mXPUSHn
3351 X<mXPUSHn>
3352
3353 Push a double onto the stack, extending the stack if necessary.  Handles
3354 'set' magic.  Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and
3355 C<PUSHn>.
3356
3357         void    mXPUSHn(NV nv)
3358
3359 =for hackers
3360 Found in file pp.h
3361
3362 =item mXPUSHp
3363 X<mXPUSHp>
3364
3365 Push a string onto the stack, extending the stack if necessary.  The C<len>
3366 indicates the length of the string.  Handles 'set' magic.  Does not use
3367 C<TARG>.  See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
3368
3369         void    mXPUSHp(char* str, STRLEN len)
3370
3371 =for hackers
3372 Found in file pp.h
3373
3374 =item mXPUSHu
3375 X<mXPUSHu>
3376
3377 Push an unsigned integer onto the stack, extending the stack if necessary.
3378 Handles 'set' magic.  Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu>
3379 and C<PUSHu>.
3380
3381         void    mXPUSHu(UV uv)
3382
3383 =for hackers
3384 Found in file pp.h
3385
3386 =item ORIGMARK
3387 X<ORIGMARK>
3388
3389 The original stack mark for the XSUB.  See C<dORIGMARK>.
3390
3391 =for hackers
3392 Found in file pp.h
3393
3394 =item POPi
3395 X<POPi>
3396
3397 Pops an integer off the stack.
3398
3399         IV      POPi
3400
3401 =for hackers
3402 Found in file pp.h
3403
3404 =item POPl
3405 X<POPl>
3406
3407 Pops a long off the stack.
3408
3409         long    POPl
3410
3411 =for hackers
3412 Found in file pp.h
3413
3414 =item POPn
3415 X<POPn>
3416
3417 Pops a double off the stack.
3418
3419         NV      POPn
3420
3421 =for hackers
3422 Found in file pp.h
3423
3424 =item POPp
3425 X<POPp>
3426
3427 Pops a string off the stack. Deprecated. New code should use POPpx.
3428
3429         char*   POPp
3430
3431 =for hackers
3432 Found in file pp.h
3433
3434 =item POPpbytex
3435 X<POPpbytex>
3436
3437 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3438
3439         char*   POPpbytex
3440
3441 =for hackers
3442 Found in file pp.h
3443
3444 =item POPpx
3445 X<POPpx>
3446
3447 Pops a string off the stack.
3448
3449         char*   POPpx
3450
3451 =for hackers
3452 Found in file pp.h
3453
3454 =item POPs
3455 X<POPs>
3456
3457 Pops an SV off the stack.
3458
3459         SV*     POPs
3460
3461 =for hackers
3462 Found in file pp.h
3463
3464 =item PUSHi
3465 X<PUSHi>
3466
3467 Push an integer onto the stack.  The stack must have room for this element.
3468 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3469 called to declare it.  Do not call multiple C<TARG>-oriented macros to 
3470 return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
3471 C<mXPUSHi>.
3472
3473         void    PUSHi(IV iv)
3474
3475 =for hackers
3476 Found in file pp.h
3477
3478 =item PUSHMARK
3479 X<PUSHMARK>
3480
3481 Opening bracket for arguments on a callback.  See C<PUTBACK> and
3482 L<perlcall>.
3483
3484         void    PUSHMARK(SP)
3485
3486 =for hackers
3487 Found in file pp.h
3488
3489 =item PUSHmortal
3490 X<PUSHmortal>
3491
3492 Push a new mortal SV onto the stack.  The stack must have room for this
3493 element.  Does not handle 'set' magic.  Does not use C<TARG>.  See also
3494 C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3495
3496         void    PUSHmortal()
3497
3498 =for hackers
3499 Found in file pp.h
3500
3501 =item PUSHn
3502 X<PUSHn>
3503
3504 Push a double onto the stack.  The stack must have room for this element.
3505 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3506 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3507 return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
3508 C<mXPUSHn>.
3509
3510         void    PUSHn(NV nv)
3511
3512 =for hackers
3513 Found in file pp.h
3514
3515 =item PUSHp
3516 X<PUSHp>
3517
3518 Push a string onto the stack.  The stack must have room for this element.
3519 The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
3520 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
3521 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3522 C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
3523
3524         void    PUSHp(char* str, STRLEN len)
3525
3526 =for hackers
3527 Found in file pp.h
3528
3529 =item PUSHs
3530 X<PUSHs>
3531
3532 Push an SV onto the stack.  The stack must have room for this element.
3533 Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
3534 C<XPUSHs> and C<XPUSHmortal>.
3535
3536         void    PUSHs(SV* sv)
3537
3538 =for hackers
3539 Found in file pp.h
3540
3541 =item PUSHu
3542 X<PUSHu>
3543
3544 Push an unsigned integer onto the stack.  The stack must have room for this
3545 element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3546 should be called to declare it.  Do not call multiple C<TARG>-oriented
3547 macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
3548 C<XPUSHu> and C<mXPUSHu>.
3549
3550         void    PUSHu(UV uv)
3551
3552 =for hackers
3553 Found in file pp.h
3554
3555 =item PUTBACK
3556 X<PUTBACK>
3557
3558 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
3559 See C<PUSHMARK> and L<perlcall> for other uses.
3560
3561                 PUTBACK;
3562
3563 =for hackers
3564 Found in file pp.h
3565
3566 =item SP
3567 X<SP>
3568
3569 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
3570 C<SPAGAIN>.
3571
3572 =for hackers
3573 Found in file pp.h
3574
3575 =item SPAGAIN
3576 X<SPAGAIN>
3577
3578 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
3579
3580                 SPAGAIN;
3581
3582 =for hackers
3583 Found in file pp.h
3584
3585 =item XPUSHi
3586 X<XPUSHi>
3587
3588 Push an integer onto the stack, extending the stack if necessary.  Handles
3589 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3590 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3591 from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
3592
3593         void    XPUSHi(IV iv)
3594
3595 =for hackers
3596 Found in file pp.h
3597
3598 =item XPUSHmortal
3599 X<XPUSHmortal>
3600
3601 Push a new mortal SV onto the stack, extending the stack if necessary.  Does
3602 not handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHs>,
3603 C<PUSHmortal> and C<PUSHs>.
3604
3605         void    XPUSHmortal()
3606
3607 =for hackers
3608 Found in file pp.h
3609
3610 =item XPUSHn
3611 X<XPUSHn>
3612
3613 Push a double onto the stack, extending the stack if necessary.  Handles
3614 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3615 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3616 from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
3617
3618         void    XPUSHn(NV nv)
3619
3620 =for hackers
3621 Found in file pp.h
3622
3623 =item XPUSHp
3624 X<XPUSHp>
3625
3626 Push a string onto the stack, extending the stack if necessary.  The C<len>
3627 indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
3628 C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
3629 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3630 C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
3631
3632         void    XPUSHp(char* str, STRLEN len)
3633
3634 =for hackers
3635 Found in file pp.h
3636
3637 =item XPUSHs
3638 X<XPUSHs>
3639
3640 Push an SV onto the stack, extending the stack if necessary.  Does not
3641 handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
3642 C<PUSHs> and C<PUSHmortal>.
3643
3644         void    XPUSHs(SV* sv)
3645
3646 =for hackers
3647 Found in file pp.h
3648
3649 =item XPUSHu
3650 X<XPUSHu>
3651
3652 Push an unsigned integer onto the stack, extending the stack if necessary.
3653 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3654 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3655 return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
3656 C<mPUSHu>.
3657
3658         void    XPUSHu(UV uv)
3659
3660 =for hackers
3661 Found in file pp.h
3662
3663 =item XSRETURN
3664 X<XSRETURN>
3665
3666 Return from XSUB, indicating number of items on the stack.  This is usually
3667 handled by C<xsubpp>.
3668
3669         void    XSRETURN(int nitems)
3670
3671 =for hackers
3672 Found in file XSUB.h
3673
3674 =item XSRETURN_EMPTY
3675 X<XSRETURN_EMPTY>
3676
3677 Return an empty list from an XSUB immediately.
3678
3679                 XSRETURN_EMPTY;
3680
3681 =for hackers
3682 Found in file XSUB.h
3683
3684 =item XSRETURN_IV
3685 X<XSRETURN_IV>
3686
3687 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3688
3689         void    XSRETURN_IV(IV iv)
3690
3691 =for hackers
3692 Found in file XSUB.h
3693
3694 =item XSRETURN_NO
3695 X<XSRETURN_NO>
3696
3697 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3698
3699                 XSRETURN_NO;
3700
3701 =for hackers
3702 Found in file XSUB.h
3703
3704 =item XSRETURN_NV
3705 X<XSRETURN_NV>
3706
3707 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
3708
3709         void    XSRETURN_NV(NV nv)
3710
3711 =for hackers
3712 Found in file XSUB.h
3713
3714 =item XSRETURN_PV
3715 X<XSRETURN_PV>
3716
3717 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3718
3719         void    XSRETURN_PV(char* str)
3720
3721 =for hackers
3722 Found in file XSUB.h
3723
3724 =item XSRETURN_UNDEF
3725 X<XSRETURN_UNDEF>
3726
3727 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3728
3729                 XSRETURN_UNDEF;
3730
3731 =for hackers
3732 Found in file XSUB.h
3733
3734 =item XSRETURN_UV
3735 X<XSRETURN_UV>
3736
3737 Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
3738
3739         void    XSRETURN_UV(IV uv)
3740
3741 =for hackers
3742 Found in file XSUB.h
3743
3744 =item XSRETURN_YES
3745 X<XSRETURN_YES>
3746
3747 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3748
3749                 XSRETURN_YES;
3750
3751 =for hackers
3752 Found in file XSUB.h
3753
3754 =item XST_mIV
3755 X<XST_mIV>
3756
3757 Place an integer into the specified position C<pos> on the stack.  The
3758 value is stored in a new mortal SV.
3759
3760         void    XST_mIV(int pos, IV iv)
3761
3762 =for hackers
3763 Found in file XSUB.h
3764
3765 =item XST_mNO
3766 X<XST_mNO>
3767
3768 Place C<&PL_sv_no> into the specified position C<pos> on the
3769 stack.
3770
3771         void    XST_mNO(int pos)
3772
3773 =for hackers
3774 Found in file XSUB.h
3775
3776 =item XST_mNV
3777 X<XST_mNV>
3778
3779 Place a double into the specified position C<pos> on the stack.  The value
3780 is stored in a new mortal SV.
3781
3782         void    XST_mNV(int pos, NV nv)
3783
3784 =for hackers
3785 Found in file XSUB.h
3786
3787 =item XST_mPV
3788 X<XST_mPV>
3789
3790 Place a copy of a string into the specified position C<pos> on the stack. 
3791 The value is stored in a new mortal SV.
3792
3793         void    XST_mPV(int pos, char* str)
3794
3795 =for hackers
3796 Found in file XSUB.h
3797
3798 =item XST_mUNDEF
3799 X<XST_mUNDEF>
3800
3801 Place C<&PL_sv_undef> into the specified position C<pos> on the
3802 stack.
3803
3804         void    XST_mUNDEF(int pos)
3805
3806 =for hackers
3807 Found in file XSUB.h
3808
3809 =item XST_mYES
3810 X<XST_mYES>
3811
3812 Place C<&PL_sv_yes> into the specified position C<pos> on the
3813 stack.
3814
3815         void    XST_mYES(int pos)
3816
3817 =for hackers
3818 Found in file XSUB.h
3819
3820
3821 =back
3822
3823 =head1 SV Flags
3824
3825 =over 8
3826
3827 =item svtype
3828 X<svtype>
3829
3830 An enum of flags for Perl types.  These are found in the file B<sv.h>
3831 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3832
3833 =for hackers
3834 Found in file sv.h
3835
3836 =item SVt_IV
3837 X<SVt_IV>
3838
3839 Integer type flag for scalars.  See C<svtype>.
3840
3841 =for hackers
3842 Found in file sv.h
3843
3844 =item SVt_NV
3845 X<SVt_NV>
3846
3847 Double type flag for scalars.  See C<svtype>.
3848
3849 =for hackers
3850 Found in file sv.h
3851
3852 =item SVt_PV
3853 X<SVt_PV>
3854
3855 Pointer type flag for scalars.  See C<svtype>.
3856
3857 =for hackers
3858 Found in file sv.h
3859
3860 =item SVt_PVAV
3861 X<SVt_PVAV>
3862
3863 Type flag for arrays.  See C<svtype>.
3864
3865 =for hackers
3866 Found in file sv.h
3867
3868 =item SVt_PVCV
3869 X<SVt_PVCV>
3870
3871 Type flag for code refs.  See C<svtype>.
3872
3873 =for hackers
3874 Found in file sv.h
3875
3876 =item SVt_PVHV
3877 X<SVt_PVHV>
3878
3879 Type flag for hashes.  See C<svtype>.
3880
3881 =for hackers
3882 Found in file sv.h
3883
3884 =item SVt_PVMG
3885 X<SVt_PVMG>
3886
3887 Type flag for blessed scalars.  See C<svtype>.
3888
3889 =for hackers
3890 Found in file sv.h
3891
3892
3893 =back
3894
3895 =head1 SV Manipulation Functions
3896
3897 =over 8
3898
3899 =item get_sv
3900 X<get_sv>
3901
3902 Returns the SV of the specified Perl scalar.  If C<create> is set and the
3903 Perl variable does not exist then it will be created.  If C<create> is not
3904 set and the variable does not exist then NULL is returned.
3905
3906 NOTE: the perl_ form of this function is deprecated.
3907
3908         SV*     get_sv(const char* name, I32 create)
3909
3910 =for hackers
3911 Found in file perl.c
3912
3913 =item newRV_inc
3914 X<newRV_inc>
3915
3916 Creates an RV wrapper for an SV.  The reference count for the original SV is
3917 incremented.
3918
3919         SV*     newRV_inc(SV* sv)
3920
3921 =for hackers
3922 Found in file sv.h
3923
3924 =item SvCUR
3925 X<SvCUR>
3926
3927 Returns the length of the string which is in the SV.  See C<SvLEN>.
3928
3929         STRLEN  SvCUR(SV* sv)
3930
3931 =for hackers
3932 Found in file sv.h
3933
3934 =item SvCUR_set
3935 X<SvCUR_set>
3936
3937 Set the current length of the string which is in the SV.  See C<SvCUR>
3938 and C<SvIV_set>.
3939
3940         void    SvCUR_set(SV* sv, STRLEN len)
3941
3942 =for hackers
3943 Found in file sv.h
3944
3945 =item SvEND
3946 X<SvEND>
3947
3948 Returns a pointer to the last character in the string which is in the SV.
3949 See C<SvCUR>.  Access the character as *(SvEND(sv)).
3950
3951         char*   SvEND(SV* sv)
3952
3953 =for hackers
3954 Found in file sv.h
3955
3956 =item SvGAMAGIC
3957 X<SvGAMAGIC>
3958
3959 Returns true if the SV has get magic or overloading. If either is true then
3960 the scalar is active data, and has the potential to return a new value every
3961 time it is accessed. Hence you must be careful to only read it once per user
3962 logical operation and work with that returned value. If neither is true then
3963 the scalar's value cannot change unless written to.
3964
3965         char*   SvGAMAGIC(SV* sv)
3966
3967 =for hackers
3968 Found in file sv.h
3969
3970 =item SvGROW
3971 X<SvGROW>
3972
3973 Expands the character buffer in the SV so that it has room for the
3974 indicated number of bytes (remember to reserve space for an extra trailing
3975 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
3976 Returns a pointer to the character buffer.
3977
3978         char *  SvGROW(SV* sv, STRLEN len)
3979
3980 =for hackers
3981 Found in file sv.h
3982
3983 =item SvIOK
3984 X<SvIOK>
3985
3986 Returns a U32 value indicating whether the SV contains an integer.
3987
3988         U32     SvIOK(SV* sv)
3989
3990 =for hackers
3991 Found in file sv.h
3992
3993 =item SvIOKp
3994 X<SvIOKp>
3995
3996 Returns a U32 value indicating whether the SV contains an integer.  Checks
3997 the B<private> setting.  Use C<SvIOK>.
3998
3999         U32     SvIOKp(SV* sv)
4000
4001 =for hackers
4002 Found in file sv.h
4003
4004 =item SvIOK_notUV
4005 X<SvIOK_notUV>
4006
4007 Returns a boolean indicating whether the SV contains a signed integer.
4008
4009         bool    SvIOK_notUV(SV* sv)
4010
4011 =for hackers
4012 Found in file sv.h
4013
4014 =item SvIOK_off
4015 X<SvIOK_off>
4016
4017 Unsets the IV status of an SV.
4018
4019         void    SvIOK_off(SV* sv)
4020
4021 =for hackers
4022 Found in file sv.h
4023
4024 =item SvIOK_on
4025 X<SvIOK_on>
4026
4027 Tells an SV that it is an integer.
4028
4029         void    SvIOK_on(SV* sv)
4030
4031 =for hackers
4032 Found in file sv.h
4033
4034 =item SvIOK_only
4035 X<SvIOK_only>
4036
4037 Tells an SV that it is an integer and disables all other OK bits.
4038
4039         void    SvIOK_only(SV* sv)
4040
4041 =for hackers
4042 Found in file sv.h
4043
4044 =item SvIOK_only_UV
4045 X<SvIOK_only_UV>
4046
4047 Tells and SV that it is an unsigned integer and disables all other OK bits.
4048
4049         void    SvIOK_only_UV(SV* sv)
4050
4051 =for hackers
4052 Found in file sv.h
4053
4054 =item SvIOK_UV
4055 X<SvIOK_UV>
4056
4057 Returns a boolean indicating whether the SV contains an unsigned integer.
4058
4059         bool    SvIOK_UV(SV* sv)
4060
4061 =for hackers
4062 Found in file sv.h
4063
4064 =item SvIsCOW
4065 X<SvIsCOW>
4066
4067 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
4068 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
4069 COW)
4070
4071         bool    SvIsCOW(SV* sv)
4072
4073 =for hackers
4074 Found in file sv.h
4075
4076 =item SvIsCOW_shared_hash
4077 X<SvIsCOW_shared_hash>
4078
4079 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
4080 scalar.
4081
4082         bool    SvIsCOW_shared_hash(SV* sv)
4083
4084 =for hackers
4085 Found in file sv.h
4086
4087 =item SvIV
4088 X<SvIV>
4089
4090 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
4091 version which guarantees to evaluate sv only once.
4092
4093         IV      SvIV(SV* sv)
4094
4095 =for hackers
4096 Found in file sv.h
4097
4098 =item SvIVX
4099 X<SvIVX>
4100
4101 Returns the raw value in the SV's IV slot, without checks or conversions.
4102 Only use when you are sure SvIOK is true. See also C<SvIV()>.
4103
4104         IV      SvIVX(SV* sv)
4105
4106 =for hackers
4107 Found in file sv.h
4108
4109 =item SvIVx
4110 X<SvIVx>
4111
4112 Coerces the given SV to an integer and returns it. Guarantees to evaluate
4113 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4114 otherwise use the more efficient C<SvIV>.
4115
4116         IV      SvIVx(SV* sv)
4117
4118 =for hackers
4119 Found in file sv.h
4120
4121 =item SvIV_nomg
4122 X<SvIV_nomg>
4123
4124 Like C<SvIV> but doesn't process magic.
4125
4126         IV      SvIV_nomg(SV* sv)
4127
4128 =for hackers
4129 Found in file sv.h
4130
4131 =item SvIV_set
4132 X<SvIV_set>
4133
4134 Set the value of the IV pointer in sv to val.  It is possible to perform
4135 the same function of this macro with an lvalue assignment to C<SvIVX>.
4136 With future Perls, however, it will be more efficient to use 
4137 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
4138
4139         void    SvIV_set(SV* sv, IV val)
4140
4141 =for hackers
4142 Found in file sv.h
4143
4144 =item SvLEN
4145 X<SvLEN>
4146
4147 Returns the size of the string buffer in the SV, not including any part
4148 attributable to C<SvOOK>.  See C<SvCUR>.
4149
4150         STRLEN  SvLEN(SV* sv)
4151
4152 =for hackers
4153 Found in file sv.h
4154
4155 =item SvLEN_set
4156 X<SvLEN_set>
4157
4158 Set the actual length of the string which is in the SV.  See C<SvIV_set>.
4159
4160         void    SvLEN_set(SV* sv, STRLEN len)
4161
4162 =for hackers
4163 Found in file sv.h
4164
4165 =item SvMAGIC_set
4166 X<SvMAGIC_set>
4167
4168 Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
4169
4170         void    SvMAGIC_set(SV* sv, MAGIC* val)
4171
4172 =for hackers
4173 Found in file sv.h
4174
4175 =item SvNIOK
4176 X<SvNIOK>
4177
4178 Returns a U32 value indicating whether the SV contains a number, integer or
4179 double.
4180
4181         U32     SvNIOK(SV* sv)
4182
4183 =for hackers
4184 Found in file sv.h
4185
4186 =item SvNIOKp
4187 X<SvNIOKp>
4188
4189 Returns a U32 value indicating whether the SV contains a number, integer or
4190 double.  Checks the B<private> setting.  Use C<SvNIOK>.
4191
4192         U32     SvNIOKp(SV* sv)
4193
4194 =for hackers
4195 Found in file sv.h
4196
4197 =item SvNIOK_off
4198 X<SvNIOK_off>
4199
4200 Unsets the NV/IV status of an SV.
4201
4202         void    SvNIOK_off(SV* sv)
4203
4204 =for hackers
4205 Found in file sv.h
4206
4207 =item SvNOK
4208 X<SvNOK>
4209
4210 Returns a U32 value indicating whether the SV contains a double.
4211
4212         U32     SvNOK(SV* sv)
4213
4214 =for hackers
4215 Found in file sv.h
4216
4217 =item SvNOKp
4218 X<SvNOKp>
4219
4220 Returns a U32 value indicating whether the SV contains a double.  Checks the
4221 B<private> setting.  Use C<SvNOK>.
4222
4223         U32     SvNOKp(SV* sv)
4224
4225 =for hackers
4226 Found in file sv.h
4227
4228 =item SvNOK_off
4229 X<SvNOK_off>
4230
4231 Unsets the NV status of an SV.
4232
4233         void    SvNOK_off(SV* sv)
4234
4235 =for hackers
4236 Found in file sv.h
4237
4238 =item SvNOK_on
4239 X<SvNOK_on>
4240
4241 Tells an SV that it is a double.
4242
4243         void    SvNOK_on(SV* sv)
4244
4245 =for hackers
4246 Found in file sv.h
4247
4248 =item SvNOK_only
4249 X<SvNOK_only>
4250
4251 Tells an SV that it is a double and disables all other OK bits.
4252
4253         void    SvNOK_only(SV* sv)
4254
4255 =for hackers
4256 Found in file sv.h
4257
4258 =item SvNV
4259 X<SvNV>
4260
4261 Coerce the given SV to a double and return it. See C<SvNVx> for a version
4262 which guarantees to evaluate sv only once.
4263
4264         NV      SvNV(SV* sv)
4265
4266 =for hackers
4267 Found in file sv.h
4268
4269 =item SvNVX
4270 X<SvNVX>
4271
4272 Returns the raw value in the SV's NV slot, without checks or conversions.
4273 Only use when you are sure SvNOK is true. See also C<SvNV()>.
4274
4275         NV      SvNVX(SV* sv)
4276
4277 =for hackers
4278 Found in file sv.h
4279
4280 =item SvNVx
4281 X<SvNVx>
4282
4283 Coerces the given SV to a double and returns it. Guarantees to evaluate
4284 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4285 otherwise use the more efficient C<SvNV>.
4286
4287         NV      SvNVx(SV* sv)
4288
4289 =for hackers
4290 Found in file sv.h
4291
4292 =item SvNV_set
4293 X<SvNV_set>
4294
4295 Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
4296
4297         void    SvNV_set(SV* sv, NV val)
4298
4299 =for hackers
4300 Found in file sv.h
4301
4302 =item SvOK
4303 X<SvOK>
4304
4305 Returns a U32 value indicating whether the value is an SV. It also tells
4306 whether the value is defined or not.
4307
4308         U32     SvOK(SV* sv)
4309
4310 =for hackers
4311 Found in file sv.h
4312
4313 =item SvOOK
4314 X<SvOOK>
4315
4316 Returns a U32 indicating whether the SvIVX is a valid offset value for
4317 the SvPVX.  This hack is used internally to speed up removal of characters
4318 from the beginning of a SvPV.  When SvOOK is true, then the start of the
4319 allocated string buffer is really (SvPVX - SvIVX).
4320
4321         U32     SvOOK(SV* sv)
4322
4323 =for hackers
4324 Found in file sv.h
4325
4326 =item SvPOK
4327 X<SvPOK>
4328
4329 Returns a U32 value indicating whether the SV contains a character
4330 string.
4331
4332         U32     SvPOK(SV* sv)
4333
4334 =for hackers
4335 Found in file sv.h
4336
4337 =item SvPOKp
4338 X<SvPOKp>
4339
4340 Returns a U32 value indicating whether the SV contains a character string.
4341 Checks the B<private> setting.  Use C<SvPOK>.
4342
4343         U32     SvPOKp(SV* sv)
4344
4345 =for hackers
4346 Found in file sv.h
4347
4348 =item SvPOK_off
4349 X<SvPOK_off>
4350
4351 Unsets the PV status of an SV.
4352
4353         void    SvPOK_off(SV* sv)
4354
4355 =for hackers
4356 Found in file sv.h
4357
4358 =item SvPOK_on
4359 X<SvPOK_on>
4360
4361 Tells an SV that it is a string.
4362
4363         void    SvPOK_on(SV* sv)
4364
4365 =for hackers
4366 Found in file sv.h
4367
4368 =item SvPOK_only
4369 X<SvPOK_only>
4370
4371 Tells an SV that it is a string and disables all other OK bits.
4372 Will also turn off the UTF-8 status.
4373
4374         void    SvPOK_only(SV* sv)
4375
4376 =for hackers
4377 Found in file sv.h
4378
4379 =item SvPOK_only_UTF8
4380 X<SvPOK_only_UTF8>
4381
4382 Tells an SV that it is a string and disables all other OK bits,
4383 and leaves the UTF-8 status as it was.
4384
4385         void    SvPOK_only_UTF8(SV* sv)
4386
4387 =for hackers
4388 Found in file sv.h
4389
4390 =item SvPV
4391 X<SvPV>
4392
4393 Returns a pointer to the string in the SV, or a stringified form of
4394 the SV if the SV does not contain a string.  The SV may cache the
4395 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
4396 C<SvPVx> for a version which guarantees to evaluate sv only once.
4397
4398         char*   SvPV(SV* sv, STRLEN len)
4399
4400 =for hackers
4401 Found in file sv.h
4402
4403 =item SvPVbyte
4404 X<SvPVbyte>
4405
4406 Like C<SvPV>, but converts sv to byte representation first if necessary.
4407
4408         char*   SvPVbyte(SV* sv, STRLEN len)
4409
4410 =for hackers
4411 Found in file sv.h
4412
4413 =item SvPVbytex
4414 X<SvPVbytex>
4415
4416 Like C<SvPV>, but converts sv to byte representation first if necessary.
4417 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4418 otherwise.
4419
4420         char*   SvPVbytex(SV* sv, STRLEN len)
4421
4422 =for hackers
4423 Found in file sv.h
4424
4425 =item SvPVbytex_force
4426 X<SvPVbytex_force>
4427
4428 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4429 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4430 otherwise.
4431
4432         char*   SvPVbytex_force(SV* sv, STRLEN len)
4433
4434 =for hackers
4435 Found in file sv.h
4436
4437 =item SvPVbyte_force
4438 X<SvPVbyte_force>
4439
4440 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4441
4442         char*   SvPVbyte_force(SV* sv, STRLEN len)
4443
4444 =for hackers
4445 Found in file sv.h
4446
4447 =item SvPVbyte_nolen
4448 X<SvPVbyte_nolen>
4449
4450 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4451
4452         char*   SvPVbyte_nolen(SV* sv)
4453
4454 =for hackers
4455 Found in file sv.h
4456
4457 =item SvPVutf8
4458 X<SvPVutf8>
4459
4460 Like C<SvPV>, but converts sv to utf8 first if necessary.
4461
4462         char*   SvPVutf8(SV* sv, STRLEN len)
4463
4464 =for hackers
4465 Found in file sv.h
4466
4467 =item SvPVutf8x
4468 X<SvPVutf8x>
4469
4470 Like C<SvPV>, but converts sv to utf8 first if necessary.
4471 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4472 otherwise.
4473
4474         char*   SvPVutf8x(SV* sv, STRLEN len)
4475
4476 =for hackers
4477 Found in file sv.h
4478
4479 =item SvPVutf8x_force
4480 X<SvPVutf8x_force>
4481
4482 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4483 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4484 otherwise.
4485
4486         char*   SvPVutf8x_force(SV* sv, STRLEN len)
4487
4488 =for hackers
4489 Found in file sv.h
4490
4491 =item SvPVutf8_force
4492 X<SvPVutf8_force>
4493
4494 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4495
4496         char*   SvPVutf8_force(SV* sv, STRLEN len)
4497
4498 =for hackers
4499 Found in file sv.h
4500
4501 =item SvPVutf8_nolen
4502 X<SvPVutf8_nolen>
4503
4504 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4505
4506         char*   SvPVutf8_nolen(SV* sv)
4507
4508 =for hackers
4509 Found in file sv.h
4510
4511 =item SvPVX
4512 X<SvPVX>
4513
4514 Returns a pointer to the physical string in the SV.  The SV must contain a
4515 string.
4516
4517         char*   SvPVX(SV* sv)
4518
4519 =for hackers
4520 Found in file sv.h
4521
4522 =item SvPVx
4523 X<SvPVx>
4524
4525 A version of C<SvPV> which guarantees to evaluate C<sv> only once.
4526 Only use this if C<sv> is an expression with side effects, otherwise use the
4527 more efficient C<SvPVX>.
4528
4529         char*   SvPVx(SV* sv, STRLEN len)
4530
4531 =for hackers
4532 Found in file sv.h
4533
4534 =item SvPV_force
4535 X<SvPV_force>
4536
4537 Like C<SvPV> but will force the SV into containing just a string
4538 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4539 directly.
4540
4541         char*   SvPV_force(SV* sv, STRLEN len)
4542
4543 =for hackers
4544 Found in file sv.h
4545
4546 =item SvPV_force_nomg
4547 X<SvPV_force_nomg>
4548
4549 Like C<SvPV> but will force the SV into containing just a string
4550 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4551 directly. Doesn't process magic.
4552
4553         char*   SvPV_force_nomg(SV* sv, STRLEN len)
4554
4555 =for hackers
4556 Found in file sv.h
4557
4558 =item SvPV_nolen
4559 X<SvPV_nolen>
4560
4561 Returns a pointer to the string in the SV, or a stringified form of
4562 the SV if the SV does not contain a string.  The SV may cache the
4563 stringified form becoming C<SvPOK>.  Handles 'get' magic.
4564
4565         char*   SvPV_nolen(SV* sv)
4566
4567 =for hackers
4568 Found in file sv.h
4569
4570 =item SvPV_nomg
4571 X<SvPV_nomg>
4572
4573 Like C<SvPV> but doesn't process magic.
4574
4575         char*   SvPV_nomg(SV* sv, STRLEN len)
4576
4577 =for hackers
4578 Found in file sv.h
4579
4580 =item SvPV_set
4581 X<SvPV_set>
4582
4583 Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
4584
4585         void    SvPV_set(SV* sv, char* val)
4586
4587 =for hackers
4588 Found in file sv.h
4589
4590 =item SvREFCNT
4591 X<SvREFCNT>
4592
4593 Returns the value of the object's reference count.
4594
4595         U32     SvREFCNT(SV* sv)
4596
4597 =for hackers
4598 Found in file sv.h
4599
4600 =item SvREFCNT_dec
4601 X<SvREFCNT_dec>
4602
4603 Decrements the reference count of the given SV.
4604
4605         void    SvREFCNT_dec(SV* sv)
4606
4607 =for hackers
4608 Found in file sv.h
4609
4610 =item SvREFCNT_inc
4611 X<SvREFCNT_inc>
4612
4613 Increments the reference count of the given SV.
4614
4615 All of the following SvREFCNT_inc* macros are optimized versions of
4616 SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4617
4618         SV*     SvREFCNT_inc(SV* sv)
4619
4620 =for hackers
4621 Found in file sv.h
4622
4623 =item SvREFCNT_inc_NN
4624 X<SvREFCNT_inc_NN>
4625
4626 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4627 is not NULL.  Since we don't have to check the NULLness, it's faster
4628 and smaller.
4629
4630         SV*     SvREFCNT_inc_NN(SV* sv)
4631
4632 =for hackers
4633 Found in file sv.h
4634
4635 =item SvREFCNT_inc_simple
4636 X<SvREFCNT_inc_simple>
4637
4638 Same as SvREFCNT_inc, but can only be used with expressions without side
4639 effects.  Since we don't have to store a temporary value, it's faster.
4640
4641         SV*     SvREFCNT_inc_simple(SV* sv)
4642
4643 =for hackers
4644 Found in file sv.h
4645
4646 =item SvREFCNT_inc_simple_NN
4647 X<SvREFCNT_inc_simple_NN>
4648
4649 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4650 is not NULL.  Since we don't have to check the NULLness, it's faster
4651 and smaller.
4652
4653         SV*     SvREFCNT_inc_simple_NN(SV* sv)
4654
4655 =for hackers
4656 Found in file sv.h
4657
4658 =item SvREFCNT_inc_simple_void
4659 X<SvREFCNT_inc_simple_void>
4660
4661 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4662 return value.  The macro doesn't need to return a meaningful value.
4663
4664         void    SvREFCNT_inc_simple_void(SV* sv)
4665
4666 =for hackers
4667 Found in file sv.h
4668
4669 =item SvREFCNT_inc_simple_void_NN
4670 X<SvREFCNT_inc_simple_void_NN>
4671
4672 Same as SvREFCNT_inc, but can only be used if you don't need the return
4673 value, and you know that I<sv> is not NULL.  The macro doesn't need
4674 to return a meaningful value, or check for NULLness, so it's smaller
4675 and faster.
4676
4677         void    SvREFCNT_inc_simple_void_NN(SV* sv)
4678
4679 =for hackers
4680 Found in file sv.h
4681
4682 =item SvREFCNT_inc_void
4683 X<SvREFCNT_inc_void>
4684
4685 Same as SvREFCNT_inc, but can only be used if you don't need the
4686 return value.  The macro doesn't need to return a meaningful value.
4687
4688         void    SvREFCNT_inc_void(SV* sv)
4689
4690 =for hackers
4691 Found in file sv.h
4692
4693 =item SvREFCNT_inc_void_NN
4694 X<SvREFCNT_inc_void_NN>
4695
4696 Same as SvREFCNT_inc, but can only be used if you don't need the return
4697 value, and you know that I<sv> is not NULL.  The macro doesn't need
4698 to return a meaningful value, or check for NULLness, so it's smaller
4699 and faster.
4700
4701         void    SvREFCNT_inc_void_NN(SV* sv)
4702
4703 =for hackers
4704 Found in file sv.h
4705
4706 =item SvROK
4707 X<SvROK>
4708
4709 Tests if the SV is an RV.
4710
4711         U32     SvROK(SV* sv)
4712
4713 =for hackers
4714 Found in file sv.h
4715
4716 =item SvROK_off
4717 X<SvROK_off>
4718
4719 Unsets the RV status of an SV.
4720
4721         void    SvROK_off(SV* sv)
4722
4723 =for hackers
4724 Found in file sv.h
4725
4726 =item SvROK_on
4727 X<SvROK_on>
4728
4729 Tells an SV that it is an RV.
4730
4731         void    SvROK_on(SV* sv)
4732
4733 =for hackers
4734 Found in file sv.h
4735
4736 =item SvRV
4737 X<SvRV>
4738
4739 Dereferences an RV to return the SV.
4740
4741         SV*     SvRV(SV* sv)
4742
4743 =for hackers
4744 Found in file sv.h
4745
4746 =item SvRV_set
4747 X<SvRV_set>
4748
4749 Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
4750
4751         void    SvRV_set(SV* sv, SV* val)
4752
4753 =for hackers
4754 Found in file sv.h
4755
4756 =item SvSTASH
4757 X<SvSTASH>
4758
4759 Returns the stash of the SV.
4760
4761         HV*     SvSTASH(SV* sv)
4762
4763 =for hackers
4764 Found in file sv.h
4765
4766 =item SvSTASH_set
4767 X<SvSTASH_set>
4768
4769 Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
4770
4771         void    SvSTASH_set(SV* sv, HV* val)
4772
4773 =for hackers
4774 Found in file sv.h
4775
4776 =item SvTAINT
4777 X<SvTAINT>
4778
4779 Taints an SV if tainting is enabled.
4780
4781         void    SvTAINT(SV* sv)
4782
4783 =for hackers
4784 Found in file sv.h
4785
4786 =item SvTAINTED
4787 X<SvTAINTED>
4788
4789 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4790 not.
4791
4792         bool    SvTAINTED(SV* sv)
4793
4794 =for hackers
4795 Found in file sv.h
4796
4797 =item SvTAINTED_off
4798 X<SvTAINTED_off>
4799
4800 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4801 some of Perl's fundamental security features. XS module authors should not
4802 use this function unless they fully understand all the implications of
4803 unconditionally untainting the value. Untainting should be done in the
4804 standard perl fashion, via a carefully crafted regexp, rather than directly
4805 untainting variables.
4806
4807         void    SvTAINTED_off(SV* sv)
4808
4809 =for hackers
4810 Found in file sv.h
4811
4812 =item SvTAINTED_on
4813 X<SvTAINTED_on>
4814
4815 Marks an SV as tainted if tainting is enabled.
4816
4817         void    SvTAINTED_on(SV* sv)
4818
4819 =for hackers
4820 Found in file sv.h
4821
4822 =item SvTRUE
4823 X<SvTRUE>
4824
4825 Returns a boolean indicating whether Perl would evaluate the SV as true or
4826 false, defined or undefined.  Does not handle 'get' magic.
4827
4828         bool    SvTRUE(SV* sv)
4829
4830 =for hackers
4831 Found in file sv.h
4832
4833 =item SvTYPE
4834 X<SvTYPE>
4835
4836 Returns the type of the SV.  See C<svtype>.
4837
4838         svtype  SvTYPE(SV* sv)
4839
4840 =for hackers
4841 Found in file sv.h
4842
4843 =item SvUOK
4844 X<SvUOK>
4845
4846 Returns a boolean indicating whether the SV contains an unsigned integer.
4847
4848         bool    SvUOK(SV* sv)
4849
4850 =for hackers
4851 Found in file sv.h
4852
4853 =item SvUPGRADE
4854 X<SvUPGRADE>
4855
4856 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
4857 perform the upgrade if necessary.  See C<svtype>.
4858
4859         void    SvUPGRADE(SV* sv, svtype type)
4860
4861 =for hackers
4862 Found in file sv.h
4863
4864 =item SvUTF8
4865 X<SvUTF8>
4866
4867 Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
4868 Call this after SvPV() in case any call to string overloading updates the
4869 internal flag.
4870
4871         U32     SvUTF8(SV* sv)
4872
4873 =for hackers
4874 Found in file sv.h
4875
4876 =item SvUTF8_off
4877 X<SvUTF8_off>
4878
4879 Unsets the UTF-8 status of an SV.
4880
4881         void    SvUTF8_off(SV *sv)
4882
4883 =for hackers
4884 Found in file sv.h
4885
4886 =item SvUTF8_on
4887 X<SvUTF8_on>
4888
4889 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4890 Do not use frivolously.
4891
4892         void    SvUTF8_on(SV *sv)
4893
4894 =for hackers
4895 Found in file sv.h
4896
4897 =item SvUV
4898 X<SvUV>
4899
4900 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
4901 for a version which guarantees to evaluate sv only once.
4902
4903         UV      SvUV(SV* sv)
4904
4905 =for hackers
4906 Found in file sv.h
4907
4908 =item SvUVX
4909 X<SvUVX>
4910
4911 Returns the raw value in the SV's UV slot, without checks or conversions.
4912 Only use when you are sure SvIOK is true. See also C<SvUV()>.
4913
4914         UV      SvUVX(SV* sv)
4915
4916 =for hackers
4917 Found in file sv.h
4918
4919 =item SvUVx
4920 X<SvUVx>
4921
4922 Coerces the given SV to an unsigned integer and returns it. Guarantees to
4923 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4924 otherwise use the more efficient C<SvUV>.
4925
4926         UV      SvUVx(SV* sv)
4927
4928 =for hackers
4929 Found in file sv.h
4930
4931 =item SvUV_nomg
4932 X<SvUV_nomg>
4933
4934 Like C<SvUV> but doesn't process magic.
4935
4936         UV      SvUV_nomg(SV* sv)
4937
4938 =for hackers
4939 Found in file sv.h
4940
4941 =item SvUV_set
4942 X<SvUV_set>
4943
4944 Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
4945
4946         void    SvUV_set(SV* sv, UV val)
4947
4948 =for hackers
4949 Found in file sv.h
4950
4951 =item SvVOK
4952 X<SvVOK>
4953
4954 Returns a boolean indicating whether the SV contains a v-string.
4955
4956         bool    SvVOK(SV* sv)
4957
4958 =for hackers
4959 Found in file sv.h
4960
4961 =item sv_catpvn_nomg
4962 X<sv_catpvn_nomg>
4963
4964 Like C<sv_catpvn> but doesn't process magic.
4965
4966         void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
4967
4968 =for hackers
4969 Found in file sv.h
4970
4971 =item sv_catsv_nomg
4972 X<sv_catsv_nomg>
4973
4974 Like C<sv_catsv> but doesn't process magic.
4975
4976         void    sv_catsv_nomg(SV* dsv, SV* ssv)
4977
4978 =for hackers
4979 Found in file sv.h
4980
4981 =item sv_derived_from
4982 X<sv_derived_from>
4983
4984 Returns a boolean indicating whether the SV is derived from the specified class
4985 I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
4986 normal Perl method.
4987
4988         bool    sv_derived_from(SV* sv, const char* name)
4989
4990 =for hackers
4991 Found in file universal.c
4992
4993 =item sv_does
4994 X<sv_does>
4995
4996 Returns a boolean indicating whether the SV performs a specific, named role.
4997 The SV can be a Perl object or the name of a Perl class.
4998
4999         bool    sv_does(SV* sv, const char* name)
5000
5001 =for hackers
5002 Found in file universal.c
5003
5004 =item sv_report_used
5005 X<sv_report_used>
5006
5007 Dump the contents of all SVs not yet freed. (Debugging aid).
5008
5009         void    sv_report_used()
5010
5011 =for hackers
5012 Found in file sv.c
5013
5014 =item sv_setsv_nomg
5015 X<sv_setsv_nomg>
5016
5017 Like C<sv_setsv> but doesn't process magic.
5018
5019         void    sv_setsv_nomg(SV* dsv, SV* ssv)
5020
5021 =for hackers
5022 Found in file sv.h
5023
5024
5025 =back
5026
5027 =head1 SV-Body Allocation
5028
5029 =over 8
5030
5031 =item looks_like_number
5032 X<looks_like_number>
5033
5034 Test if the content of an SV looks like a number (or is a number).
5035 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
5036 non-numeric warning), even if your atof() doesn't grok them.
5037
5038         I32     looks_like_number(SV* sv)
5039
5040 =for hackers
5041 Found in file sv.c
5042
5043 =item newRV_noinc
5044 X<newRV_noinc>
5045
5046 Creates an RV wrapper for an SV.  The reference count for the original
5047 SV is B<not> incremented.
5048
5049         SV*     newRV_noinc(SV* sv)
5050
5051 =for hackers
5052 Found in file sv.c
5053
5054 =item newSV
5055 X<newSV>
5056
5057 Creates a new SV.  A non-zero C<len> parameter indicates the number of
5058 bytes of preallocated string space the SV should have.  An extra byte for a
5059 trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
5060 space is allocated.)  The reference count for the new SV is set to 1.
5061
5062 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5063 parameter, I<x>, a debug aid which allowed callers to identify themselves.
5064 This aid has been superseded by a new build option, PERL_MEM_LOG (see
5065 L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
5066 modules supporting older perls.
5067
5068         SV*     newSV(STRLEN len)
5069
5070 =for hackers
5071 Found in file sv.c
5072
5073 =item newSVhek
5074 X<newSVhek>
5075
5076 Creates a new SV from the hash key structure.  It will generate scalars that
5077 point to the shared string table where possible. Returns a new (undefined)
5078 SV if the hek is NULL.
5079
5080         SV*     newSVhek(const HEK *hek)
5081
5082 =for hackers
5083 Found in file sv.c
5084
5085 =item newSViv
5086 X<newSViv>
5087
5088 Creates a new SV and copies an integer into it.  The reference count for the
5089 SV is set to 1.
5090
5091         SV*     newSViv(IV i)
5092
5093 =for hackers
5094 Found in file sv.c
5095
5096 =item newSVnv
5097 X<newSVnv>
5098
5099 Creates a new SV and copies a floating point value into it.
5100 The reference count for the SV is set to 1.
5101
5102         SV*     newSVnv(NV n)
5103
5104 =for hackers
5105 Found in file sv.c
5106
5107 =item newSVpv
5108 X<newSVpv>
5109
5110 Creates a new SV and copies a string into it.  The reference count for the
5111 SV is set to 1.  If C<len> is zero, Perl will compute the length using
5112 strlen().  For efficiency, consider using C<newSVpvn> instead.
5113
5114         SV*     newSVpv(const char* s, STRLEN len)
5115
5116 =for hackers
5117 Found in file sv.c
5118
5119 =item newSVpvf
5120 X<newSVpvf>
5121
5122 Creates a new SV and initializes it with the string formatted like
5123 C<sprintf>.
5124
5125         SV*     newSVpvf(const char* pat, ...)
5126
5127 =for hackers
5128 Found in file sv.c
5129
5130 =item newSVpvn
5131 X<newSVpvn>
5132
5133 Creates a new SV and copies a string into it.  The reference count for the
5134 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5135 string.  You are responsible for ensuring that the source string is at least
5136 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5137
5138         SV*     newSVpvn(const char* s, STRLEN len)
5139
5140 =for hackers
5141 Found in file sv.c
5142
5143 =item newSVpvn_share
5144 X<newSVpvn_share>
5145
5146 Creates a new SV with its SvPVX_const pointing to a shared string in the string
5147 table. If the string does not already exist in the table, it is created
5148 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
5149 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
5150 otherwise the hash is computed.  The idea here is that as the string table
5151 is used for shared hash keys these strings will have SvPVX_const == HeKEY and
5152 hash lookup will avoid string compare.
5153
5154         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
5155
5156 =for hackers
5157 Found in file sv.c
5158
5159 =item newSVpvs
5160 X<newSVpvs>
5161
5162 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5163
5164         SV*     newSVpvs(const char* s)
5165
5166 =for hackers
5167 Found in file handy.h
5168
5169 =item newSVpvs_share
5170 X<newSVpvs_share>
5171
5172 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5173 pair and omits the hash parameter.
5174
5175         SV*     newSVpvs_share(const char* s)
5176
5177 =for hackers
5178 Found in file handy.h
5179
5180 =item newSVrv
5181 X<newSVrv>
5182
5183 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
5184 it will be upgraded to one.  If C<classname> is non-null then the new SV will
5185 be blessed in the specified package.  The new SV is returned and its
5186 reference count is 1.
5187
5188         SV*     newSVrv(SV* rv, const char* classname)
5189
5190 =for hackers
5191 Found in file sv.c
5192
5193 =item newSVsv
5194 X<newSVsv>
5195
5196 Creates a new SV which is an exact duplicate of the original SV.
5197 (Uses C<sv_setsv>).
5198
5199         SV*     newSVsv(SV* old)
5200
5201 =for hackers
5202 Found in file sv.c
5203
5204 =item newSVuv
5205 X<newSVuv>
5206
5207 Creates a new SV and copies an unsigned integer into it.
5208 The reference count for the SV is set to 1.
5209
5210         SV*     newSVuv(UV u)
5211
5212 =for hackers
5213 Found in file sv.c
5214
5215 =item newSV_type
5216 X<newSV_type>
5217
5218 Creates a new SV, of the type specificied.  The reference count for the new SV
5219 is set to 1.
5220
5221         SV*     newSV_type(svtype type)
5222
5223 =for hackers
5224 Found in file sv.c
5225
5226 =item sv_2bool
5227 X<sv_2bool>
5228
5229 This function is only called on magical items, and is only used by
5230 sv_true() or its macro equivalent.
5231
5232         bool    sv_2bool(SV* sv)
5233
5234 =for hackers
5235 Found in file sv.c
5236
5237 =item sv_2cv
5238 X<sv_2cv>
5239
5240 Using various gambits, try to get a CV from an SV; in addition, try if
5241 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5242 The flags in C<lref> are passed to sv_fetchsv.
5243
5244         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
5245
5246 =for hackers
5247 Found in file sv.c
5248
5249 =item sv_2io
5250 X<sv_2io>
5251
5252 Using various gambits, try to get an IO from an SV: the IO slot if its a
5253 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5254 named after the PV if we're a string.
5255
5256         IO*     sv_2io(SV* sv)
5257
5258 =for hackers
5259 Found in file sv.c
5260
5261 =item sv_2iv_flags
5262 X<sv_2iv_flags>
5263
5264 Return the integer value of an SV, doing any necessary string
5265 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5266 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5267
5268         IV      sv_2iv_flags(SV* sv, I32 flags)
5269
5270 =for hackers
5271 Found in file sv.c
5272
5273 =item sv_2mortal
5274 X<sv_2mortal>
5275
5276 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
5277 by an explicit call to FREETMPS, or by an implicit call at places such as
5278 statement boundaries.  SvTEMP() is turned on which means that the SV's
5279 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5280 and C<sv_mortalcopy>.
5281
5282         SV*     sv_2mortal(SV* sv)
5283
5284 =for hackers
5285 Found in file sv.c
5286
5287 =item sv_2nv
5288 X<sv_2nv>
5289
5290 Return the num value of an SV, doing any necessary string or integer
5291 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5292 macros.
5293
5294         NV      sv_2nv(SV* sv)
5295
5296 =for hackers
5297 Found in file sv.c
5298
5299 =item sv_2pvbyte
5300 X<sv_2pvbyte>
5301
5302 Return a pointer to the byte-encoded representation of the SV, and set *lp
5303 to its length.  May cause the SV to be downgraded from UTF-8 as a
5304 side-effect.
5305
5306 Usually accessed via the C<SvPVbyte> macro.
5307
5308         char*   sv_2pvbyte(SV* sv, STRLEN* lp)
5309
5310 =for hackers
5311 Found in file sv.c
5312
5313 =item sv_2pvutf8
5314 X<sv_2pvutf8>
5315
5316 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5317 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
5318
5319 Usually accessed via the C<SvPVutf8> macro.
5320
5321         char*   sv_2pvutf8(SV* sv, STRLEN* lp)
5322
5323 =for hackers
5324 Found in file sv.c
5325
5326 =item sv_2pv_flags
5327 X<sv_2pv_flags>
5328
5329 Returns a pointer to the string value of an SV, and sets *lp to its length.
5330 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5331 if necessary.
5332 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5333 usually end up here too.
5334
5335         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
5336
5337 =for hackers
5338 Found in file sv.c
5339
5340 =item sv_2uv_flags
5341 X<sv_2uv_flags>
5342
5343 Return the unsigned integer value of an SV, doing any necessary string
5344 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5345 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5346
5347         UV      sv_2uv_flags(SV* sv, I32 flags)
5348
5349 =for hackers
5350 Found in file sv.c
5351
5352 =item sv_backoff
5353 X<sv_backoff>
5354
5355 Remove any string offset. You should normally use the C<SvOOK_off> macro
5356 wrapper instead.
5357
5358         int     sv_backoff(SV* sv)
5359
5360 =for hackers
5361 Found in file sv.c
5362
5363 =item sv_bless
5364 X<sv_bless>
5365
5366 Blesses an SV into a specified package.  The SV must be an RV.  The package
5367 must be designated by its stash (see C<gv_stashpv()>).  The reference count
5368 of the SV is unaffected.
5369
5370         SV*     sv_bless(SV* sv, HV* stash)
5371
5372 =for hackers
5373 Found in file sv.c
5374
5375 =item sv_catpv
5376 X<sv_catpv>
5377
5378 Concatenates the string onto the end of the string which is in the SV.
5379 If the SV has the UTF-8 status set, then the bytes appended should be
5380 valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
5381
5382         void    sv_catpv(SV* sv, const char* ptr)
5383
5384 =for hackers
5385 Found in file sv.c
5386
5387 =item sv_catpvf
5388 X<sv_catpvf>
5389
5390 Processes its arguments like C<sprintf> and appends the formatted
5391 output to an SV.  If the appended data contains "wide" characters
5392 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5393 and characters >255 formatted with %c), the original SV might get
5394 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
5395 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5396 valid UTF-8; if the original SV was bytes, the pattern should be too.
5397
5398         void    sv_catpvf(SV* sv, const char* pat, ...)
5399
5400 =for hackers
5401 Found in file sv.c
5402
5403 =item sv_catpvf_mg
5404 X<sv_catpvf_mg>
5405
5406 Like C<sv_catpvf>, but also handles 'set' magic.
5407
5408         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
5409
5410 =for hackers
5411 Found in file sv.c
5412
5413 =item sv_catpvn
5414 X<sv_catpvn>
5415
5416 Concatenates the string onto the end of the string which is in the SV.  The
5417 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5418 status set, then the bytes appended should be valid UTF-8.
5419 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
5420
5421         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
5422
5423 =for hackers
5424 Found in file sv.c
5425
5426 =item sv_catpvn_flags
5427 X<sv_catpvn_flags>
5428
5429 Concatenates the string onto the end of the string which is in the SV.  The
5430 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5431 status set, then the bytes appended should be valid UTF-8.
5432 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5433 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5434 in terms of this function.
5435
5436         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
5437
5438 =for hackers
5439 Found in file sv.c
5440
5441 =item sv_catpvs
5442 X<sv_catpvs>
5443
5444 Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5445
5446         void    sv_catpvs(SV* sv, const char* s)
5447
5448 =for hackers
5449 Found in file handy.h
5450
5451 =item sv_catpv_mg
5452 X<sv_catpv_mg>
5453
5454 Like C<sv_catpv>, but also handles 'set' magic.
5455
5456         void    sv_catpv_mg(SV *sv, const char *ptr)
5457
5458 =for hackers
5459 Found in file sv.c
5460
5461 =item sv_catsv
5462 X<sv_catsv>
5463
5464 Concatenates the string from SV C<ssv> onto the end of the string in
5465 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
5466 not 'set' magic.  See C<sv_catsv_mg>.
5467
5468         void    sv_catsv(SV* dsv, SV* ssv)
5469
5470 =for hackers
5471 Found in file sv.c
5472
5473 =item sv_catsv_flags
5474 X<sv_catsv_flags>
5475
5476 Concatenates the string from SV C<ssv> onto the end of the string in
5477 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
5478 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5479 and C<sv_catsv_nomg> are implemented in terms of this function.
5480
5481         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
5482
5483 =for hackers
5484 Found in file sv.c
5485
5486 =item sv_chop
5487 X<sv_chop>
5488
5489 Efficient removal of characters from the beginning of the string buffer.
5490 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5491 the string buffer.  The C<ptr> becomes the first character of the adjusted
5492 string. Uses the "OOK hack".
5493 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5494 refer to the same chunk of data.
5495
5496         void    sv_chop(SV* sv, const char* ptr)
5497
5498 =for hackers
5499 Found in file sv.c
5500
5501 =item sv_clear
5502 X<sv_clear>
5503
5504 Clear an SV: call any destructors, free up any memory used by the body,
5505 and free the body itself. The SV's head is I<not> freed, although
5506 its type is set to all 1'