This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
delete thrdvar.h and move its contents to intrpvar.h
[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 Simple Exception Handling Macros
3139
3140 =over 8
3141
3142 =item dXCPT
3143 X<dXCPT>
3144
3145 Set up necessary local variables for exception handling.
3146 See L<perlguts/"Exception Handling">.
3147
3148                 dXCPT;
3149
3150 =for hackers
3151 Found in file XSUB.h
3152
3153 =item XCPT_CATCH
3154 X<XCPT_CATCH>
3155
3156 Introduces a catch block.  See L<perlguts/"Exception Handling">.
3157
3158 =for hackers
3159 Found in file XSUB.h
3160
3161 =item XCPT_RETHROW
3162 X<XCPT_RETHROW>
3163
3164 Rethrows a previously caught exception.  See L<perlguts/"Exception Handling">.
3165
3166                 XCPT_RETHROW;
3167
3168 =for hackers
3169 Found in file XSUB.h
3170
3171 =item XCPT_TRY_END
3172 X<XCPT_TRY_END>
3173
3174 Ends a try block.  See L<perlguts/"Exception Handling">.
3175
3176 =for hackers
3177 Found in file XSUB.h
3178
3179 =item XCPT_TRY_START
3180 X<XCPT_TRY_START>
3181
3182 Starts a try block.  See L<perlguts/"Exception Handling">.
3183
3184 =for hackers
3185 Found in file XSUB.h
3186
3187
3188 =back
3189
3190 =head1 Stack Manipulation Macros
3191
3192 =over 8
3193
3194 =item dMARK
3195 X<dMARK>
3196
3197 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
3198 C<dORIGMARK>.
3199
3200                 dMARK;
3201
3202 =for hackers
3203 Found in file pp.h
3204
3205 =item dORIGMARK
3206 X<dORIGMARK>
3207
3208 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
3209
3210                 dORIGMARK;
3211
3212 =for hackers
3213 Found in file pp.h
3214
3215 =item dSP
3216 X<dSP>
3217
3218 Declares a local copy of perl's stack pointer for the XSUB, available via
3219 the C<SP> macro.  See C<SP>.
3220
3221                 dSP;
3222
3223 =for hackers
3224 Found in file pp.h
3225
3226 =item EXTEND
3227 X<EXTEND>
3228
3229 Used to extend the argument stack for an XSUB's return values. Once
3230 used, guarantees that there is room for at least C<nitems> to be pushed
3231 onto the stack.
3232
3233         void    EXTEND(SP, int nitems)
3234
3235 =for hackers
3236 Found in file pp.h
3237
3238 =item MARK
3239 X<MARK>
3240
3241 Stack marker variable for the XSUB.  See C<dMARK>.
3242
3243 =for hackers
3244 Found in file pp.h
3245
3246 =item mPUSHi
3247 X<mPUSHi>
3248
3249 Push an integer onto the stack.  The stack must have room for this element.
3250 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi>
3251 and C<XPUSHi>.
3252
3253         void    mPUSHi(IV iv)
3254
3255 =for hackers
3256 Found in file pp.h
3257
3258 =item mPUSHn
3259 X<mPUSHn>
3260
3261 Push a double onto the stack.  The stack must have room for this element.
3262 Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn>
3263 and C<XPUSHn>.
3264
3265         void    mPUSHn(NV nv)
3266
3267 =for hackers
3268 Found in file pp.h
3269
3270 =item mPUSHp
3271 X<mPUSHp>
3272
3273 Push a string onto the stack.  The stack must have room for this element.
3274 The C<len> indicates the length of the string.  Handles 'set' magic.  Does
3275 not use C<TARG>.  See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3276
3277         void    mPUSHp(char* str, STRLEN len)
3278
3279 =for hackers
3280 Found in file pp.h
3281
3282 =item mPUSHu
3283 X<mPUSHu>
3284
3285 Push an unsigned integer onto the stack.  The stack must have room for this
3286 element.  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHu>,
3287 C<mXPUSHu> and C<XPUSHu>.
3288
3289         void    mPUSHu(UV uv)
3290
3291 =for hackers
3292 Found in file pp.h
3293
3294 =item mXPUSHi
3295 X<mXPUSHi>
3296
3297 Push an integer onto the stack, extending the stack if necessary.  Handles
3298 'set' magic.  Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and
3299 C<PUSHi>.
3300
3301         void    mXPUSHi(IV iv)
3302
3303 =for hackers
3304 Found in file pp.h
3305
3306 =item mXPUSHn
3307 X<mXPUSHn>
3308
3309 Push a double onto the stack, extending the stack if necessary.  Handles
3310 'set' magic.  Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and
3311 C<PUSHn>.
3312
3313         void    mXPUSHn(NV nv)
3314
3315 =for hackers
3316 Found in file pp.h
3317
3318 =item mXPUSHp
3319 X<mXPUSHp>
3320
3321 Push a string onto the stack, extending the stack if necessary.  The C<len>
3322 indicates the length of the string.  Handles 'set' magic.  Does not use
3323 C<TARG>.  See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
3324
3325         void    mXPUSHp(char* str, STRLEN len)
3326
3327 =for hackers
3328 Found in file pp.h
3329
3330 =item mXPUSHu
3331 X<mXPUSHu>
3332
3333 Push an unsigned integer onto the stack, extending the stack if necessary.
3334 Handles 'set' magic.  Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu>
3335 and C<PUSHu>.
3336
3337         void    mXPUSHu(UV uv)
3338
3339 =for hackers
3340 Found in file pp.h
3341
3342 =item ORIGMARK
3343 X<ORIGMARK>
3344
3345 The original stack mark for the XSUB.  See C<dORIGMARK>.
3346
3347 =for hackers
3348 Found in file pp.h
3349
3350 =item POPi
3351 X<POPi>
3352
3353 Pops an integer off the stack.
3354
3355         IV      POPi
3356
3357 =for hackers
3358 Found in file pp.h
3359
3360 =item POPl
3361 X<POPl>
3362
3363 Pops a long off the stack.
3364
3365         long    POPl
3366
3367 =for hackers
3368 Found in file pp.h
3369
3370 =item POPn
3371 X<POPn>
3372
3373 Pops a double off the stack.
3374
3375         NV      POPn
3376
3377 =for hackers
3378 Found in file pp.h
3379
3380 =item POPp
3381 X<POPp>
3382
3383 Pops a string off the stack. Deprecated. New code should use POPpx.
3384
3385         char*   POPp
3386
3387 =for hackers
3388 Found in file pp.h
3389
3390 =item POPpbytex
3391 X<POPpbytex>
3392
3393 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3394
3395         char*   POPpbytex
3396
3397 =for hackers
3398 Found in file pp.h
3399
3400 =item POPpx
3401 X<POPpx>
3402
3403 Pops a string off the stack.
3404
3405         char*   POPpx
3406
3407 =for hackers
3408 Found in file pp.h
3409
3410 =item POPs
3411 X<POPs>
3412
3413 Pops an SV off the stack.
3414
3415         SV*     POPs
3416
3417 =for hackers
3418 Found in file pp.h
3419
3420 =item PUSHi
3421 X<PUSHi>
3422
3423 Push an integer onto the stack.  The stack must have room for this element.
3424 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3425 called to declare it.  Do not call multiple C<TARG>-oriented macros to 
3426 return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
3427 C<mXPUSHi>.
3428
3429         void    PUSHi(IV iv)
3430
3431 =for hackers
3432 Found in file pp.h
3433
3434 =item PUSHMARK
3435 X<PUSHMARK>
3436
3437 Opening bracket for arguments on a callback.  See C<PUTBACK> and
3438 L<perlcall>.
3439
3440         void    PUSHMARK(SP)
3441
3442 =for hackers
3443 Found in file pp.h
3444
3445 =item PUSHmortal
3446 X<PUSHmortal>
3447
3448 Push a new mortal SV onto the stack.  The stack must have room for this
3449 element.  Does not handle 'set' magic.  Does not use C<TARG>.  See also
3450 C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3451
3452         void    PUSHmortal()
3453
3454 =for hackers
3455 Found in file pp.h
3456
3457 =item PUSHn
3458 X<PUSHn>
3459
3460 Push a double onto the stack.  The stack must have room for this element.
3461 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3462 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3463 return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
3464 C<mXPUSHn>.
3465
3466         void    PUSHn(NV nv)
3467
3468 =for hackers
3469 Found in file pp.h
3470
3471 =item PUSHp
3472 X<PUSHp>
3473
3474 Push a string onto the stack.  The stack must have room for this element.
3475 The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
3476 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
3477 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3478 C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
3479
3480         void    PUSHp(char* str, STRLEN len)
3481
3482 =for hackers
3483 Found in file pp.h
3484
3485 =item PUSHs
3486 X<PUSHs>
3487
3488 Push an SV onto the stack.  The stack must have room for this element.
3489 Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
3490 C<XPUSHs> and C<XPUSHmortal>.
3491
3492         void    PUSHs(SV* sv)
3493
3494 =for hackers
3495 Found in file pp.h
3496
3497 =item PUSHu
3498 X<PUSHu>
3499
3500 Push an unsigned integer onto the stack.  The stack must have room for this
3501 element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3502 should be called to declare it.  Do not call multiple C<TARG>-oriented
3503 macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
3504 C<XPUSHu> and C<mXPUSHu>.
3505
3506         void    PUSHu(UV uv)
3507
3508 =for hackers
3509 Found in file pp.h
3510
3511 =item PUTBACK
3512 X<PUTBACK>
3513
3514 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
3515 See C<PUSHMARK> and L<perlcall> for other uses.
3516
3517                 PUTBACK;
3518
3519 =for hackers
3520 Found in file pp.h
3521
3522 =item SP
3523 X<SP>
3524
3525 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
3526 C<SPAGAIN>.
3527
3528 =for hackers
3529 Found in file pp.h
3530
3531 =item SPAGAIN
3532 X<SPAGAIN>
3533
3534 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
3535
3536                 SPAGAIN;
3537
3538 =for hackers
3539 Found in file pp.h
3540
3541 =item XPUSHi
3542 X<XPUSHi>
3543
3544 Push an integer onto the stack, extending the stack if necessary.  Handles
3545 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3546 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3547 from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
3548
3549         void    XPUSHi(IV iv)
3550
3551 =for hackers
3552 Found in file pp.h
3553
3554 =item XPUSHmortal
3555 X<XPUSHmortal>
3556
3557 Push a new mortal SV onto the stack, extending the stack if necessary.  Does
3558 not handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHs>,
3559 C<PUSHmortal> and C<PUSHs>.
3560
3561         void    XPUSHmortal()
3562
3563 =for hackers
3564 Found in file pp.h
3565
3566 =item XPUSHn
3567 X<XPUSHn>
3568
3569 Push a double onto the stack, extending the stack if necessary.  Handles
3570 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3571 declare it.  Do not call multiple C<TARG>-oriented macros to return lists
3572 from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
3573
3574         void    XPUSHn(NV nv)
3575
3576 =for hackers
3577 Found in file pp.h
3578
3579 =item XPUSHp
3580 X<XPUSHp>
3581
3582 Push a string onto the stack, extending the stack if necessary.  The C<len>
3583 indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
3584 C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
3585 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3586 C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
3587
3588         void    XPUSHp(char* str, STRLEN len)
3589
3590 =for hackers
3591 Found in file pp.h
3592
3593 =item XPUSHs
3594 X<XPUSHs>
3595
3596 Push an SV onto the stack, extending the stack if necessary.  Does not
3597 handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
3598 C<PUSHs> and C<PUSHmortal>.
3599
3600         void    XPUSHs(SV* sv)
3601
3602 =for hackers
3603 Found in file pp.h
3604
3605 =item XPUSHu
3606 X<XPUSHu>
3607
3608 Push an unsigned integer onto the stack, extending the stack if necessary.
3609 Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3610 called to declare it.  Do not call multiple C<TARG>-oriented macros to
3611 return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
3612 C<mPUSHu>.
3613
3614         void    XPUSHu(UV uv)
3615
3616 =for hackers
3617 Found in file pp.h
3618
3619 =item XSRETURN
3620 X<XSRETURN>
3621
3622 Return from XSUB, indicating number of items on the stack.  This is usually
3623 handled by C<xsubpp>.
3624
3625         void    XSRETURN(int nitems)
3626
3627 =for hackers
3628 Found in file XSUB.h
3629
3630 =item XSRETURN_EMPTY
3631 X<XSRETURN_EMPTY>
3632
3633 Return an empty list from an XSUB immediately.
3634
3635                 XSRETURN_EMPTY;
3636
3637 =for hackers
3638 Found in file XSUB.h
3639
3640 =item XSRETURN_IV
3641 X<XSRETURN_IV>
3642
3643 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3644
3645         void    XSRETURN_IV(IV iv)
3646
3647 =for hackers
3648 Found in file XSUB.h
3649
3650 =item XSRETURN_NO
3651 X<XSRETURN_NO>
3652
3653 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3654
3655                 XSRETURN_NO;
3656
3657 =for hackers
3658 Found in file XSUB.h
3659
3660 =item XSRETURN_NV
3661 X<XSRETURN_NV>
3662
3663 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
3664
3665         void    XSRETURN_NV(NV nv)
3666
3667 =for hackers
3668 Found in file XSUB.h
3669
3670 =item XSRETURN_PV
3671 X<XSRETURN_PV>
3672
3673 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3674
3675         void    XSRETURN_PV(char* str)
3676
3677 =for hackers
3678 Found in file XSUB.h
3679
3680 =item XSRETURN_UNDEF
3681 X<XSRETURN_UNDEF>
3682
3683 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3684
3685                 XSRETURN_UNDEF;
3686
3687 =for hackers
3688 Found in file XSUB.h
3689
3690 =item XSRETURN_UV
3691 X<XSRETURN_UV>
3692
3693 Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
3694
3695         void    XSRETURN_UV(IV uv)
3696
3697 =for hackers
3698 Found in file XSUB.h
3699
3700 =item XSRETURN_YES
3701 X<XSRETURN_YES>
3702
3703 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3704
3705                 XSRETURN_YES;
3706
3707 =for hackers
3708 Found in file XSUB.h
3709
3710 =item XST_mIV
3711 X<XST_mIV>
3712
3713 Place an integer into the specified position C<pos> on the stack.  The
3714 value is stored in a new mortal SV.
3715
3716         void    XST_mIV(int pos, IV iv)
3717
3718 =for hackers
3719 Found in file XSUB.h
3720
3721 =item XST_mNO
3722 X<XST_mNO>
3723
3724 Place C<&PL_sv_no> into the specified position C<pos> on the
3725 stack.
3726
3727         void    XST_mNO(int pos)
3728
3729 =for hackers
3730 Found in file XSUB.h
3731
3732 =item XST_mNV
3733 X<XST_mNV>
3734
3735 Place a double into the specified position C<pos> on the stack.  The value
3736 is stored in a new mortal SV.
3737
3738         void    XST_mNV(int pos, NV nv)
3739
3740 =for hackers
3741 Found in file XSUB.h
3742
3743 =item XST_mPV
3744 X<XST_mPV>
3745
3746 Place a copy of a string into the specified position C<pos> on the stack. 
3747 The value is stored in a new mortal SV.
3748
3749         void    XST_mPV(int pos, char* str)
3750
3751 =for hackers
3752 Found in file XSUB.h
3753
3754 =item XST_mUNDEF
3755 X<XST_mUNDEF>
3756
3757 Place C<&PL_sv_undef> into the specified position C<pos> on the
3758 stack.
3759
3760         void    XST_mUNDEF(int pos)
3761
3762 =for hackers
3763 Found in file XSUB.h
3764
3765 =item XST_mYES
3766 X<XST_mYES>
3767
3768 Place C<&PL_sv_yes> into the specified position C<pos> on the
3769 stack.
3770
3771         void    XST_mYES(int pos)
3772
3773 =for hackers
3774 Found in file XSUB.h
3775
3776
3777 =back
3778
3779 =head1 SV Flags
3780
3781 =over 8
3782
3783 =item svtype
3784 X<svtype>
3785
3786 An enum of flags for Perl types.  These are found in the file B<sv.h>
3787 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
3788
3789 =for hackers
3790 Found in file sv.h
3791
3792 =item SVt_IV
3793 X<SVt_IV>
3794
3795 Integer type flag for scalars.  See C<svtype>.
3796
3797 =for hackers
3798 Found in file sv.h
3799
3800 =item SVt_NV
3801 X<SVt_NV>
3802
3803 Double type flag for scalars.  See C<svtype>.
3804
3805 =for hackers
3806 Found in file sv.h
3807
3808 =item SVt_PV
3809 X<SVt_PV>
3810
3811 Pointer type flag for scalars.  See C<svtype>.
3812
3813 =for hackers
3814 Found in file sv.h
3815
3816 =item SVt_PVAV
3817 X<SVt_PVAV>
3818
3819 Type flag for arrays.  See C<svtype>.
3820
3821 =for hackers
3822 Found in file sv.h
3823
3824 =item SVt_PVCV
3825 X<SVt_PVCV>
3826
3827 Type flag for code refs.  See C<svtype>.
3828
3829 =for hackers
3830 Found in file sv.h
3831
3832 =item SVt_PVHV
3833 X<SVt_PVHV>
3834
3835 Type flag for hashes.  See C<svtype>.
3836
3837 =for hackers
3838 Found in file sv.h
3839
3840 =item SVt_PVMG
3841 X<SVt_PVMG>
3842
3843 Type flag for blessed scalars.  See C<svtype>.
3844
3845 =for hackers
3846 Found in file sv.h
3847
3848
3849 =back
3850
3851 =head1 SV Manipulation Functions
3852
3853 =over 8
3854
3855 =item get_sv
3856 X<get_sv>
3857
3858 Returns the SV of the specified Perl scalar.  If C<create> is set and the
3859 Perl variable does not exist then it will be created.  If C<create> is not
3860 set and the variable does not exist then NULL is returned.
3861
3862 NOTE: the perl_ form of this function is deprecated.
3863
3864         SV*     get_sv(const char* name, I32 create)
3865
3866 =for hackers
3867 Found in file perl.c
3868
3869 =item newRV_inc
3870 X<newRV_inc>
3871
3872 Creates an RV wrapper for an SV.  The reference count for the original SV is
3873 incremented.
3874
3875         SV*     newRV_inc(SV* sv)
3876
3877 =for hackers
3878 Found in file sv.h
3879
3880 =item SvCUR
3881 X<SvCUR>
3882
3883 Returns the length of the string which is in the SV.  See C<SvLEN>.
3884
3885         STRLEN  SvCUR(SV* sv)
3886
3887 =for hackers
3888 Found in file sv.h
3889
3890 =item SvCUR_set
3891 X<SvCUR_set>
3892
3893 Set the current length of the string which is in the SV.  See C<SvCUR>
3894 and C<SvIV_set>.
3895
3896         void    SvCUR_set(SV* sv, STRLEN len)
3897
3898 =for hackers
3899 Found in file sv.h
3900
3901 =item SvEND
3902 X<SvEND>
3903
3904 Returns a pointer to the last character in the string which is in the SV.
3905 See C<SvCUR>.  Access the character as *(SvEND(sv)).
3906
3907         char*   SvEND(SV* sv)
3908
3909 =for hackers
3910 Found in file sv.h
3911
3912 =item SvGAMAGIC
3913 X<SvGAMAGIC>
3914
3915 Returns true if the SV has get magic or overloading. If either is true then
3916 the scalar is active data, and has the potential to return a new value every
3917 time it is accessed. Hence you must be careful to only read it once per user
3918 logical operation and work with that returned value. If neither is true then
3919 the scalar's value cannot change unless written to.
3920
3921         char*   SvGAMAGIC(SV* sv)
3922
3923 =for hackers
3924 Found in file sv.h
3925
3926 =item SvGROW
3927 X<SvGROW>
3928
3929 Expands the character buffer in the SV so that it has room for the
3930 indicated number of bytes (remember to reserve space for an extra trailing
3931 NUL character).  Calls C<sv_grow> to perform the expansion if necessary.
3932 Returns a pointer to the character buffer.
3933
3934         char *  SvGROW(SV* sv, STRLEN len)
3935
3936 =for hackers
3937 Found in file sv.h
3938
3939 =item SvIOK
3940 X<SvIOK>
3941
3942 Returns a U32 value indicating whether the SV contains an integer.
3943
3944         U32     SvIOK(SV* sv)
3945
3946 =for hackers
3947 Found in file sv.h
3948
3949 =item SvIOKp
3950 X<SvIOKp>
3951
3952 Returns a U32 value indicating whether the SV contains an integer.  Checks
3953 the B<private> setting.  Use C<SvIOK>.
3954
3955         U32     SvIOKp(SV* sv)
3956
3957 =for hackers
3958 Found in file sv.h
3959
3960 =item SvIOK_notUV
3961 X<SvIOK_notUV>
3962
3963 Returns a boolean indicating whether the SV contains a signed integer.
3964
3965         bool    SvIOK_notUV(SV* sv)
3966
3967 =for hackers
3968 Found in file sv.h
3969
3970 =item SvIOK_off
3971 X<SvIOK_off>
3972
3973 Unsets the IV status of an SV.
3974
3975         void    SvIOK_off(SV* sv)
3976
3977 =for hackers
3978 Found in file sv.h
3979
3980 =item SvIOK_on
3981 X<SvIOK_on>
3982
3983 Tells an SV that it is an integer.
3984
3985         void    SvIOK_on(SV* sv)
3986
3987 =for hackers
3988 Found in file sv.h
3989
3990 =item SvIOK_only
3991 X<SvIOK_only>
3992
3993 Tells an SV that it is an integer and disables all other OK bits.
3994
3995         void    SvIOK_only(SV* sv)
3996
3997 =for hackers
3998 Found in file sv.h
3999
4000 =item SvIOK_only_UV
4001 X<SvIOK_only_UV>
4002
4003 Tells and SV that it is an unsigned integer and disables all other OK bits.
4004
4005         void    SvIOK_only_UV(SV* sv)
4006
4007 =for hackers
4008 Found in file sv.h
4009
4010 =item SvIOK_UV
4011 X<SvIOK_UV>
4012
4013 Returns a boolean indicating whether the SV contains an unsigned integer.
4014
4015         bool    SvIOK_UV(SV* sv)
4016
4017 =for hackers
4018 Found in file sv.h
4019
4020 =item SvIsCOW
4021 X<SvIsCOW>
4022
4023 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
4024 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
4025 COW)
4026
4027         bool    SvIsCOW(SV* sv)
4028
4029 =for hackers
4030 Found in file sv.h
4031
4032 =item SvIsCOW_shared_hash
4033 X<SvIsCOW_shared_hash>
4034
4035 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
4036 scalar.
4037
4038         bool    SvIsCOW_shared_hash(SV* sv)
4039
4040 =for hackers
4041 Found in file sv.h
4042
4043 =item SvIV
4044 X<SvIV>
4045
4046 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
4047 version which guarantees to evaluate sv only once.
4048
4049         IV      SvIV(SV* sv)
4050
4051 =for hackers
4052 Found in file sv.h
4053
4054 =item SvIVX
4055 X<SvIVX>
4056
4057 Returns the raw value in the SV's IV slot, without checks or conversions.
4058 Only use when you are sure SvIOK is true. See also C<SvIV()>.
4059
4060         IV      SvIVX(SV* sv)
4061
4062 =for hackers
4063 Found in file sv.h
4064
4065 =item SvIVx
4066 X<SvIVx>
4067
4068 Coerces the given SV to an integer and returns it. Guarantees to evaluate
4069 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4070 otherwise use the more efficient C<SvIV>.
4071
4072         IV      SvIVx(SV* sv)
4073
4074 =for hackers
4075 Found in file sv.h
4076
4077 =item SvIV_nomg
4078 X<SvIV_nomg>
4079
4080 Like C<SvIV> but doesn't process magic.
4081
4082         IV      SvIV_nomg(SV* sv)
4083
4084 =for hackers
4085 Found in file sv.h
4086
4087 =item SvIV_set
4088 X<SvIV_set>
4089
4090 Set the value of the IV pointer in sv to val.  It is possible to perform
4091 the same function of this macro with an lvalue assignment to C<SvIVX>.
4092 With future Perls, however, it will be more efficient to use 
4093 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
4094
4095         void    SvIV_set(SV* sv, IV val)
4096
4097 =for hackers
4098 Found in file sv.h
4099
4100 =item SvLEN
4101 X<SvLEN>
4102
4103 Returns the size of the string buffer in the SV, not including any part
4104 attributable to C<SvOOK>.  See C<SvCUR>.
4105
4106         STRLEN  SvLEN(SV* sv)
4107
4108 =for hackers
4109 Found in file sv.h
4110
4111 =item SvLEN_set
4112 X<SvLEN_set>
4113
4114 Set the actual length of the string which is in the SV.  See C<SvIV_set>.
4115
4116         void    SvLEN_set(SV* sv, STRLEN len)
4117
4118 =for hackers
4119 Found in file sv.h
4120
4121 =item SvMAGIC_set
4122 X<SvMAGIC_set>
4123
4124 Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
4125
4126         void    SvMAGIC_set(SV* sv, MAGIC* val)
4127
4128 =for hackers
4129 Found in file sv.h
4130
4131 =item SvNIOK
4132 X<SvNIOK>
4133
4134 Returns a U32 value indicating whether the SV contains a number, integer or
4135 double.
4136
4137         U32     SvNIOK(SV* sv)
4138
4139 =for hackers
4140 Found in file sv.h
4141
4142 =item SvNIOKp
4143 X<SvNIOKp>
4144
4145 Returns a U32 value indicating whether the SV contains a number, integer or
4146 double.  Checks the B<private> setting.  Use C<SvNIOK>.
4147
4148         U32     SvNIOKp(SV* sv)
4149
4150 =for hackers
4151 Found in file sv.h
4152
4153 =item SvNIOK_off
4154 X<SvNIOK_off>
4155
4156 Unsets the NV/IV status of an SV.
4157
4158         void    SvNIOK_off(SV* sv)
4159
4160 =for hackers
4161 Found in file sv.h
4162
4163 =item SvNOK
4164 X<SvNOK>
4165
4166 Returns a U32 value indicating whether the SV contains a double.
4167
4168         U32     SvNOK(SV* sv)
4169
4170 =for hackers
4171 Found in file sv.h
4172
4173 =item SvNOKp
4174 X<SvNOKp>
4175
4176 Returns a U32 value indicating whether the SV contains a double.  Checks the
4177 B<private> setting.  Use C<SvNOK>.
4178
4179         U32     SvNOKp(SV* sv)
4180
4181 =for hackers
4182 Found in file sv.h
4183
4184 =item SvNOK_off
4185 X<SvNOK_off>
4186
4187 Unsets the NV status of an SV.
4188
4189         void    SvNOK_off(SV* sv)
4190
4191 =for hackers
4192 Found in file sv.h
4193
4194 =item SvNOK_on
4195 X<SvNOK_on>
4196
4197 Tells an SV that it is a double.
4198
4199         void    SvNOK_on(SV* sv)
4200
4201 =for hackers
4202 Found in file sv.h
4203
4204 =item SvNOK_only
4205 X<SvNOK_only>
4206
4207 Tells an SV that it is a double and disables all other OK bits.
4208
4209         void    SvNOK_only(SV* sv)
4210
4211 =for hackers
4212 Found in file sv.h
4213
4214 =item SvNV
4215 X<SvNV>
4216
4217 Coerce the given SV to a double and return it. See C<SvNVx> for a version
4218 which guarantees to evaluate sv only once.
4219
4220         NV      SvNV(SV* sv)
4221
4222 =for hackers
4223 Found in file sv.h
4224
4225 =item SvNVX
4226 X<SvNVX>
4227
4228 Returns the raw value in the SV's NV slot, without checks or conversions.
4229 Only use when you are sure SvNOK is true. See also C<SvNV()>.
4230
4231         NV      SvNVX(SV* sv)
4232
4233 =for hackers
4234 Found in file sv.h
4235
4236 =item SvNVx
4237 X<SvNVx>
4238
4239 Coerces the given SV to a double and returns it. Guarantees to evaluate
4240 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4241 otherwise use the more efficient C<SvNV>.
4242
4243         NV      SvNVx(SV* sv)
4244
4245 =for hackers
4246 Found in file sv.h
4247
4248 =item SvNV_set
4249 X<SvNV_set>
4250
4251 Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
4252
4253         void    SvNV_set(SV* sv, NV val)
4254
4255 =for hackers
4256 Found in file sv.h
4257
4258 =item SvOK
4259 X<SvOK>
4260
4261 Returns a U32 value indicating whether the value is an SV. It also tells
4262 whether the value is defined or not.
4263
4264         U32     SvOK(SV* sv)
4265
4266 =for hackers
4267 Found in file sv.h
4268
4269 =item SvOOK
4270 X<SvOOK>
4271
4272 Returns a U32 indicating whether the SvIVX is a valid offset value for
4273 the SvPVX.  This hack is used internally to speed up removal of characters
4274 from the beginning of a SvPV.  When SvOOK is true, then the start of the
4275 allocated string buffer is really (SvPVX - SvIVX).
4276
4277         U32     SvOOK(SV* sv)
4278
4279 =for hackers
4280 Found in file sv.h
4281
4282 =item SvPOK
4283 X<SvPOK>
4284
4285 Returns a U32 value indicating whether the SV contains a character
4286 string.
4287
4288         U32     SvPOK(SV* sv)
4289
4290 =for hackers
4291 Found in file sv.h
4292
4293 =item SvPOKp
4294 X<SvPOKp>
4295
4296 Returns a U32 value indicating whether the SV contains a character string.
4297 Checks the B<private> setting.  Use C<SvPOK>.
4298
4299         U32     SvPOKp(SV* sv)
4300
4301 =for hackers
4302 Found in file sv.h
4303
4304 =item SvPOK_off
4305 X<SvPOK_off>
4306
4307 Unsets the PV status of an SV.
4308
4309         void    SvPOK_off(SV* sv)
4310
4311 =for hackers
4312 Found in file sv.h
4313
4314 =item SvPOK_on
4315 X<SvPOK_on>
4316
4317 Tells an SV that it is a string.
4318
4319         void    SvPOK_on(SV* sv)
4320
4321 =for hackers
4322 Found in file sv.h
4323
4324 =item SvPOK_only
4325 X<SvPOK_only>
4326
4327 Tells an SV that it is a string and disables all other OK bits.
4328 Will also turn off the UTF-8 status.
4329
4330         void    SvPOK_only(SV* sv)
4331
4332 =for hackers
4333 Found in file sv.h
4334
4335 =item SvPOK_only_UTF8
4336 X<SvPOK_only_UTF8>
4337
4338 Tells an SV that it is a string and disables all other OK bits,
4339 and leaves the UTF-8 status as it was.
4340
4341         void    SvPOK_only_UTF8(SV* sv)
4342
4343 =for hackers
4344 Found in file sv.h
4345
4346 =item SvPV
4347 X<SvPV>
4348
4349 Returns a pointer to the string in the SV, or a stringified form of
4350 the SV if the SV does not contain a string.  The SV may cache the
4351 stringified version becoming C<SvPOK>.  Handles 'get' magic. See also
4352 C<SvPVx> for a version which guarantees to evaluate sv only once.
4353
4354         char*   SvPV(SV* sv, STRLEN len)
4355
4356 =for hackers
4357 Found in file sv.h
4358
4359 =item SvPVbyte
4360 X<SvPVbyte>
4361
4362 Like C<SvPV>, but converts sv to byte representation first if necessary.
4363
4364         char*   SvPVbyte(SV* sv, STRLEN len)
4365
4366 =for hackers
4367 Found in file sv.h
4368
4369 =item SvPVbytex
4370 X<SvPVbytex>
4371
4372 Like C<SvPV>, but converts sv to byte representation first if necessary.
4373 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4374 otherwise.
4375
4376         char*   SvPVbytex(SV* sv, STRLEN len)
4377
4378 =for hackers
4379 Found in file sv.h
4380
4381 =item SvPVbytex_force
4382 X<SvPVbytex_force>
4383
4384 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4385 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4386 otherwise.
4387
4388         char*   SvPVbytex_force(SV* sv, STRLEN len)
4389
4390 =for hackers
4391 Found in file sv.h
4392
4393 =item SvPVbyte_force
4394 X<SvPVbyte_force>
4395
4396 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4397
4398         char*   SvPVbyte_force(SV* sv, STRLEN len)
4399
4400 =for hackers
4401 Found in file sv.h
4402
4403 =item SvPVbyte_nolen
4404 X<SvPVbyte_nolen>
4405
4406 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4407
4408         char*   SvPVbyte_nolen(SV* sv)
4409
4410 =for hackers
4411 Found in file sv.h
4412
4413 =item SvPVutf8
4414 X<SvPVutf8>
4415
4416 Like C<SvPV>, but converts sv to utf8 first if necessary.
4417
4418         char*   SvPVutf8(SV* sv, STRLEN len)
4419
4420 =for hackers
4421 Found in file sv.h
4422
4423 =item SvPVutf8x
4424 X<SvPVutf8x>
4425
4426 Like C<SvPV>, but converts sv to utf8 first if necessary.
4427 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4428 otherwise.
4429
4430         char*   SvPVutf8x(SV* sv, STRLEN len)
4431
4432 =for hackers
4433 Found in file sv.h
4434
4435 =item SvPVutf8x_force
4436 X<SvPVutf8x_force>
4437
4438 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4439 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4440 otherwise.
4441
4442         char*   SvPVutf8x_force(SV* sv, STRLEN len)
4443
4444 =for hackers
4445 Found in file sv.h
4446
4447 =item SvPVutf8_force
4448 X<SvPVutf8_force>
4449
4450 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4451
4452         char*   SvPVutf8_force(SV* sv, STRLEN len)
4453
4454 =for hackers
4455 Found in file sv.h
4456
4457 =item SvPVutf8_nolen
4458 X<SvPVutf8_nolen>
4459
4460 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4461
4462         char*   SvPVutf8_nolen(SV* sv)
4463
4464 =for hackers
4465 Found in file sv.h
4466
4467 =item SvPVX
4468 X<SvPVX>
4469
4470 Returns a pointer to the physical string in the SV.  The SV must contain a
4471 string.
4472
4473         char*   SvPVX(SV* sv)
4474
4475 =for hackers
4476 Found in file sv.h
4477
4478 =item SvPVx
4479 X<SvPVx>
4480
4481 A version of C<SvPV> which guarantees to evaluate C<sv> only once.
4482 Only use this if C<sv> is an expression with side effects, otherwise use the
4483 more efficient C<SvPVX>.
4484
4485         char*   SvPVx(SV* sv, STRLEN len)
4486
4487 =for hackers
4488 Found in file sv.h
4489
4490 =item SvPV_force
4491 X<SvPV_force>
4492
4493 Like C<SvPV> but will force the SV into containing just a string
4494 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4495 directly.
4496
4497         char*   SvPV_force(SV* sv, STRLEN len)
4498
4499 =for hackers
4500 Found in file sv.h
4501
4502 =item SvPV_force_nomg
4503 X<SvPV_force_nomg>
4504
4505 Like C<SvPV> but will force the SV into containing just a string
4506 (C<SvPOK_only>).  You want force if you are going to update the C<SvPVX>
4507 directly. Doesn't process magic.
4508
4509         char*   SvPV_force_nomg(SV* sv, STRLEN len)
4510
4511 =for hackers
4512 Found in file sv.h
4513
4514 =item SvPV_nolen
4515 X<SvPV_nolen>
4516
4517 Returns a pointer to the string in the SV, or a stringified form of
4518 the SV if the SV does not contain a string.  The SV may cache the
4519 stringified form becoming C<SvPOK>.  Handles 'get' magic.
4520
4521         char*   SvPV_nolen(SV* sv)
4522
4523 =for hackers
4524 Found in file sv.h
4525
4526 =item SvPV_nomg
4527 X<SvPV_nomg>
4528
4529 Like C<SvPV> but doesn't process magic.
4530
4531         char*   SvPV_nomg(SV* sv, STRLEN len)
4532
4533 =for hackers
4534 Found in file sv.h
4535
4536 =item SvPV_set
4537 X<SvPV_set>
4538
4539 Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
4540
4541         void    SvPV_set(SV* sv, char* val)
4542
4543 =for hackers
4544 Found in file sv.h
4545
4546 =item SvREFCNT
4547 X<SvREFCNT>
4548
4549 Returns the value of the object's reference count.
4550
4551         U32     SvREFCNT(SV* sv)
4552
4553 =for hackers
4554 Found in file sv.h
4555
4556 =item SvREFCNT_dec
4557 X<SvREFCNT_dec>
4558
4559 Decrements the reference count of the given SV.
4560
4561         void    SvREFCNT_dec(SV* sv)
4562
4563 =for hackers
4564 Found in file sv.h
4565
4566 =item SvREFCNT_inc
4567 X<SvREFCNT_inc>
4568
4569 Increments the reference count of the given SV.
4570
4571 All of the following SvREFCNT_inc* macros are optimized versions of
4572 SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4573
4574         SV*     SvREFCNT_inc(SV* sv)
4575
4576 =for hackers
4577 Found in file sv.h
4578
4579 =item SvREFCNT_inc_NN
4580 X<SvREFCNT_inc_NN>
4581
4582 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4583 is not NULL.  Since we don't have to check the NULLness, it's faster
4584 and smaller.
4585
4586         SV*     SvREFCNT_inc_NN(SV* sv)
4587
4588 =for hackers
4589 Found in file sv.h
4590
4591 =item SvREFCNT_inc_simple
4592 X<SvREFCNT_inc_simple>
4593
4594 Same as SvREFCNT_inc, but can only be used with expressions without side
4595 effects.  Since we don't have to store a temporary value, it's faster.
4596
4597         SV*     SvREFCNT_inc_simple(SV* sv)
4598
4599 =for hackers
4600 Found in file sv.h
4601
4602 =item SvREFCNT_inc_simple_NN
4603 X<SvREFCNT_inc_simple_NN>
4604
4605 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4606 is not NULL.  Since we don't have to check the NULLness, it's faster
4607 and smaller.
4608
4609         SV*     SvREFCNT_inc_simple_NN(SV* sv)
4610
4611 =for hackers
4612 Found in file sv.h
4613
4614 =item SvREFCNT_inc_simple_void
4615 X<SvREFCNT_inc_simple_void>
4616
4617 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4618 return value.  The macro doesn't need to return a meaningful value.
4619
4620         void    SvREFCNT_inc_simple_void(SV* sv)
4621
4622 =for hackers
4623 Found in file sv.h
4624
4625 =item SvREFCNT_inc_simple_void_NN
4626 X<SvREFCNT_inc_simple_void_NN>
4627
4628 Same as SvREFCNT_inc, but can only be used if you don't need the return
4629 value, and you know that I<sv> is not NULL.  The macro doesn't need
4630 to return a meaningful value, or check for NULLness, so it's smaller
4631 and faster.
4632
4633         void    SvREFCNT_inc_simple_void_NN(SV* sv)
4634
4635 =for hackers
4636 Found in file sv.h
4637
4638 =item SvREFCNT_inc_void
4639 X<SvREFCNT_inc_void>
4640
4641 Same as SvREFCNT_inc, but can only be used if you don't need the
4642 return value.  The macro doesn't need to return a meaningful value.
4643
4644         void    SvREFCNT_inc_void(SV* sv)
4645
4646 =for hackers
4647 Found in file sv.h
4648
4649 =item SvREFCNT_inc_void_NN
4650 X<SvREFCNT_inc_void_NN>
4651
4652 Same as SvREFCNT_inc, but can only be used if you don't need the return
4653 value, and you know that I<sv> is not NULL.  The macro doesn't need
4654 to return a meaningful value, or check for NULLness, so it's smaller
4655 and faster.
4656
4657         void    SvREFCNT_inc_void_NN(SV* sv)
4658
4659 =for hackers
4660 Found in file sv.h
4661
4662 =item SvROK
4663 X<SvROK>
4664
4665 Tests if the SV is an RV.
4666
4667         U32     SvROK(SV* sv)
4668
4669 =for hackers
4670 Found in file sv.h
4671
4672 =item SvROK_off
4673 X<SvROK_off>
4674
4675 Unsets the RV status of an SV.
4676
4677         void    SvROK_off(SV* sv)
4678
4679 =for hackers
4680 Found in file sv.h
4681
4682 =item SvROK_on
4683 X<SvROK_on>
4684
4685 Tells an SV that it is an RV.
4686
4687         void    SvROK_on(SV* sv)
4688
4689 =for hackers
4690 Found in file sv.h
4691
4692 =item SvRV
4693 X<SvRV>
4694
4695 Dereferences an RV to return the SV.
4696
4697         SV*     SvRV(SV* sv)
4698
4699 =for hackers
4700 Found in file sv.h
4701
4702 =item SvRV_set
4703 X<SvRV_set>
4704
4705 Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
4706
4707         void    SvRV_set(SV* sv, SV* val)
4708
4709 =for hackers
4710 Found in file sv.h
4711
4712 =item SvSTASH
4713 X<SvSTASH>
4714
4715 Returns the stash of the SV.
4716
4717         HV*     SvSTASH(SV* sv)
4718
4719 =for hackers
4720 Found in file sv.h
4721
4722 =item SvSTASH_set
4723 X<SvSTASH_set>
4724
4725 Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
4726
4727         void    SvSTASH_set(SV* sv, HV* val)
4728
4729 =for hackers
4730 Found in file sv.h
4731
4732 =item SvTAINT
4733 X<SvTAINT>
4734
4735 Taints an SV if tainting is enabled.
4736
4737         void    SvTAINT(SV* sv)
4738
4739 =for hackers
4740 Found in file sv.h
4741
4742 =item SvTAINTED
4743 X<SvTAINTED>
4744
4745 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4746 not.
4747
4748         bool    SvTAINTED(SV* sv)
4749
4750 =for hackers
4751 Found in file sv.h
4752
4753 =item SvTAINTED_off
4754 X<SvTAINTED_off>
4755
4756 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4757 some of Perl's fundamental security features. XS module authors should not
4758 use this function unless they fully understand all the implications of
4759 unconditionally untainting the value. Untainting should be done in the
4760 standard perl fashion, via a carefully crafted regexp, rather than directly
4761 untainting variables.
4762
4763         void    SvTAINTED_off(SV* sv)
4764
4765 =for hackers
4766 Found in file sv.h
4767
4768 =item SvTAINTED_on
4769 X<SvTAINTED_on>
4770
4771 Marks an SV as tainted if tainting is enabled.
4772
4773         void    SvTAINTED_on(SV* sv)
4774
4775 =for hackers
4776 Found in file sv.h
4777
4778 =item SvTRUE
4779 X<SvTRUE>
4780
4781 Returns a boolean indicating whether Perl would evaluate the SV as true or
4782 false, defined or undefined.  Does not handle 'get' magic.
4783
4784         bool    SvTRUE(SV* sv)
4785
4786 =for hackers
4787 Found in file sv.h
4788
4789 =item SvTYPE
4790 X<SvTYPE>
4791
4792 Returns the type of the SV.  See C<svtype>.
4793
4794         svtype  SvTYPE(SV* sv)
4795
4796 =for hackers
4797 Found in file sv.h
4798
4799 =item SvUOK
4800 X<SvUOK>
4801
4802 Returns a boolean indicating whether the SV contains an unsigned integer.
4803
4804         bool    SvUOK(SV* sv)
4805
4806 =for hackers
4807 Found in file sv.h
4808
4809 =item SvUPGRADE
4810 X<SvUPGRADE>
4811
4812 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
4813 perform the upgrade if necessary.  See C<svtype>.
4814
4815         void    SvUPGRADE(SV* sv, svtype type)
4816
4817 =for hackers
4818 Found in file sv.h
4819
4820 =item SvUTF8
4821 X<SvUTF8>
4822
4823 Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
4824 Call this after SvPV() in case any call to string overloading updates the
4825 internal flag.
4826
4827         U32     SvUTF8(SV* sv)
4828
4829 =for hackers
4830 Found in file sv.h
4831
4832 =item SvUTF8_off
4833 X<SvUTF8_off>
4834
4835 Unsets the UTF-8 status of an SV.
4836
4837         void    SvUTF8_off(SV *sv)
4838
4839 =for hackers
4840 Found in file sv.h
4841
4842 =item SvUTF8_on
4843 X<SvUTF8_on>
4844
4845 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4846 Do not use frivolously.
4847
4848         void    SvUTF8_on(SV *sv)
4849
4850 =for hackers
4851 Found in file sv.h
4852
4853 =item SvUV
4854 X<SvUV>
4855
4856 Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
4857 for a version which guarantees to evaluate sv only once.
4858
4859         UV      SvUV(SV* sv)
4860
4861 =for hackers
4862 Found in file sv.h
4863
4864 =item SvUVX
4865 X<SvUVX>
4866
4867 Returns the raw value in the SV's UV slot, without checks or conversions.
4868 Only use when you are sure SvIOK is true. See also C<SvUV()>.
4869
4870         UV      SvUVX(SV* sv)
4871
4872 =for hackers
4873 Found in file sv.h
4874
4875 =item SvUVx
4876 X<SvUVx>
4877
4878 Coerces the given SV to an unsigned integer and returns it. Guarantees to
4879 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4880 otherwise use the more efficient C<SvUV>.
4881
4882         UV      SvUVx(SV* sv)
4883
4884 =for hackers
4885 Found in file sv.h
4886
4887 =item SvUV_nomg
4888 X<SvUV_nomg>
4889
4890 Like C<SvUV> but doesn't process magic.
4891
4892         UV      SvUV_nomg(SV* sv)
4893
4894 =for hackers
4895 Found in file sv.h
4896
4897 =item SvUV_set
4898 X<SvUV_set>
4899
4900 Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
4901
4902         void    SvUV_set(SV* sv, UV val)
4903
4904 =for hackers
4905 Found in file sv.h
4906
4907 =item SvVOK
4908 X<SvVOK>
4909
4910 Returns a boolean indicating whether the SV contains a v-string.
4911
4912         bool    SvVOK(SV* sv)
4913
4914 =for hackers
4915 Found in file sv.h
4916
4917 =item sv_catpvn_nomg
4918 X<sv_catpvn_nomg>
4919
4920 Like C<sv_catpvn> but doesn't process magic.
4921
4922         void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
4923
4924 =for hackers
4925 Found in file sv.h
4926
4927 =item sv_catsv_nomg
4928 X<sv_catsv_nomg>
4929
4930 Like C<sv_catsv> but doesn't process magic.
4931
4932         void    sv_catsv_nomg(SV* dsv, SV* ssv)
4933
4934 =for hackers
4935 Found in file sv.h
4936
4937 =item sv_derived_from
4938 X<sv_derived_from>
4939
4940 Returns a boolean indicating whether the SV is derived from the specified class
4941 I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
4942 normal Perl method.
4943
4944         bool    sv_derived_from(SV* sv, const char* name)
4945
4946 =for hackers
4947 Found in file universal.c
4948
4949 =item sv_does
4950 X<sv_does>
4951
4952 Returns a boolean indicating whether the SV performs a specific, named role.
4953 The SV can be a Perl object or the name of a Perl class.
4954
4955         bool    sv_does(SV* sv, const char* name)
4956
4957 =for hackers
4958 Found in file universal.c
4959
4960 =item sv_report_used
4961 X<sv_report_used>
4962
4963 Dump the contents of all SVs not yet freed. (Debugging aid).
4964
4965         void    sv_report_used()
4966
4967 =for hackers
4968 Found in file sv.c
4969
4970 =item sv_setsv_nomg
4971 X<sv_setsv_nomg>
4972
4973 Like C<sv_setsv> but doesn't process magic.
4974
4975         void    sv_setsv_nomg(SV* dsv, SV* ssv)
4976
4977 =for hackers
4978 Found in file sv.h
4979
4980
4981 =back
4982
4983 =head1 SV-Body Allocation
4984
4985 =over 8
4986
4987 =item looks_like_number
4988 X<looks_like_number>
4989
4990 Test if the content of an SV looks like a number (or is a number).
4991 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
4992 non-numeric warning), even if your atof() doesn't grok them.
4993
4994         I32     looks_like_number(SV* sv)
4995
4996 =for hackers
4997 Found in file sv.c
4998
4999 =item newRV_noinc
5000 X<newRV_noinc>
5001
5002 Creates an RV wrapper for an SV.  The reference count for the original
5003 SV is B<not> incremented.
5004
5005         SV*     newRV_noinc(SV* sv)
5006
5007 =for hackers
5008 Found in file sv.c
5009
5010 =item newSV
5011 X<newSV>
5012
5013 Creates a new SV.  A non-zero C<len> parameter indicates the number of
5014 bytes of preallocated string space the SV should have.  An extra byte for a
5015 trailing NUL is also reserved.  (SvPOK is not set for the SV even if string
5016 space is allocated.)  The reference count for the new SV is set to 1.
5017
5018 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5019 parameter, I<x>, a debug aid which allowed callers to identify themselves.
5020 This aid has been superseded by a new build option, PERL_MEM_LOG (see
5021 L<perlhack/PERL_MEM_LOG>).  The older API is still there for use in XS
5022 modules supporting older perls.
5023
5024         SV*     newSV(STRLEN len)
5025
5026 =for hackers
5027 Found in file sv.c
5028
5029 =item newSVhek
5030 X<newSVhek>
5031
5032 Creates a new SV from the hash key structure.  It will generate scalars that
5033 point to the shared string table where possible. Returns a new (undefined)
5034 SV if the hek is NULL.
5035
5036         SV*     newSVhek(const HEK *hek)
5037
5038 =for hackers
5039 Found in file sv.c
5040
5041 =item newSViv
5042 X<newSViv>
5043
5044 Creates a new SV and copies an integer into it.  The reference count for the
5045 SV is set to 1.
5046
5047         SV*     newSViv(IV i)
5048
5049 =for hackers
5050 Found in file sv.c
5051
5052 =item newSVnv
5053 X<newSVnv>
5054
5055 Creates a new SV and copies a floating point value into it.
5056 The reference count for the SV is set to 1.
5057
5058         SV*     newSVnv(NV n)
5059
5060 =for hackers
5061 Found in file sv.c
5062
5063 =item newSVpv
5064 X<newSVpv>
5065
5066 Creates a new SV and copies a string into it.  The reference count for the
5067 SV is set to 1.  If C<len> is zero, Perl will compute the length using
5068 strlen().  For efficiency, consider using C<newSVpvn> instead.
5069
5070         SV*     newSVpv(const char* s, STRLEN len)
5071
5072 =for hackers
5073 Found in file sv.c
5074
5075 =item newSVpvf
5076 X<newSVpvf>
5077
5078 Creates a new SV and initializes it with the string formatted like
5079 C<sprintf>.
5080
5081         SV*     newSVpvf(const char* pat, ...)
5082
5083 =for hackers
5084 Found in file sv.c
5085
5086 =item newSVpvn
5087 X<newSVpvn>
5088
5089 Creates a new SV and copies a string into it.  The reference count for the
5090 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
5091 string.  You are responsible for ensuring that the source string is at least
5092 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
5093
5094         SV*     newSVpvn(const char* s, STRLEN len)
5095
5096 =for hackers
5097 Found in file sv.c
5098
5099 =item newSVpvn_share
5100 X<newSVpvn_share>
5101
5102 Creates a new SV with its SvPVX_const pointing to a shared string in the string
5103 table. If the string does not already exist in the table, it is created
5104 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
5105 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
5106 otherwise the hash is computed.  The idea here is that as the string table
5107 is used for shared hash keys these strings will have SvPVX_const == HeKEY and
5108 hash lookup will avoid string compare.
5109
5110         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
5111
5112 =for hackers
5113 Found in file sv.c
5114
5115 =item newSVpvs
5116 X<newSVpvs>
5117
5118 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5119
5120         SV*     newSVpvs(const char* s)
5121
5122 =for hackers
5123 Found in file handy.h
5124
5125 =item newSVpvs_share
5126 X<newSVpvs_share>
5127
5128 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5129 pair and omits the hash parameter.
5130
5131         SV*     newSVpvs_share(const char* s)
5132
5133 =for hackers
5134 Found in file handy.h
5135
5136 =item newSVrv
5137 X<newSVrv>
5138
5139 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
5140 it will be upgraded to one.  If C<classname> is non-null then the new SV will
5141 be blessed in the specified package.  The new SV is returned and its
5142 reference count is 1.
5143
5144         SV*     newSVrv(SV* rv, const char* classname)
5145
5146 =for hackers
5147 Found in file sv.c
5148
5149 =item newSVsv
5150 X<newSVsv>
5151
5152 Creates a new SV which is an exact duplicate of the original SV.
5153 (Uses C<sv_setsv>).
5154
5155         SV*     newSVsv(SV* old)
5156
5157 =for hackers
5158 Found in file sv.c
5159
5160 =item newSVuv
5161 X<newSVuv>
5162
5163 Creates a new SV and copies an unsigned integer into it.
5164 The reference count for the SV is set to 1.
5165
5166         SV*     newSVuv(UV u)
5167
5168 =for hackers
5169 Found in file sv.c
5170
5171 =item newSV_type
5172 X<newSV_type>
5173
5174 Creates a new SV, of the type specificied.  The reference count for the new SV
5175 is set to 1.
5176
5177         SV*     newSV_type(svtype type)
5178
5179 =for hackers
5180 Found in file sv.c
5181
5182 =item sv_2bool
5183 X<sv_2bool>
5184
5185 This function is only called on magical items, and is only used by
5186 sv_true() or its macro equivalent.
5187
5188         bool    sv_2bool(SV* sv)
5189
5190 =for hackers
5191 Found in file sv.c
5192
5193 =item sv_2cv
5194 X<sv_2cv>
5195
5196 Using various gambits, try to get a CV from an SV; in addition, try if
5197 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5198 The flags in C<lref> are passed to sv_fetchsv.
5199
5200         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
5201
5202 =for hackers
5203 Found in file sv.c
5204
5205 =item sv_2io
5206 X<sv_2io>
5207
5208 Using various gambits, try to get an IO from an SV: the IO slot if its a
5209 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5210 named after the PV if we're a string.
5211
5212         IO*     sv_2io(SV* sv)
5213
5214 =for hackers
5215 Found in file sv.c
5216
5217 =item sv_2iv_flags
5218 X<sv_2iv_flags>
5219
5220 Return the integer value of an SV, doing any necessary string
5221 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5222 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5223
5224         IV      sv_2iv_flags(SV* sv, I32 flags)
5225
5226 =for hackers
5227 Found in file sv.c
5228
5229 =item sv_2mortal
5230 X<sv_2mortal>
5231
5232 Marks an existing SV as mortal.  The SV will be destroyed "soon", either
5233 by an explicit call to FREETMPS, or by an implicit call at places such as
5234 statement boundaries.  SvTEMP() is turned on which means that the SV's
5235 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5236 and C<sv_mortalcopy>.
5237
5238         SV*     sv_2mortal(SV* sv)
5239
5240 =for hackers
5241 Found in file sv.c
5242
5243 =item sv_2nv
5244 X<sv_2nv>
5245
5246 Return the num value of an SV, doing any necessary string or integer
5247 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5248 macros.
5249
5250         NV      sv_2nv(SV* sv)
5251
5252 =for hackers
5253 Found in file sv.c
5254
5255 =item sv_2pvbyte
5256 X<sv_2pvbyte>
5257
5258 Return a pointer to the byte-encoded representation of the SV, and set *lp
5259 to its length.  May cause the SV to be downgraded from UTF-8 as a
5260 side-effect.
5261
5262 Usually accessed via the C<SvPVbyte> macro.
5263
5264         char*   sv_2pvbyte(SV* sv, STRLEN* lp)
5265
5266 =for hackers
5267 Found in file sv.c
5268
5269 =item sv_2pvutf8
5270 X<sv_2pvutf8>
5271
5272 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5273 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.
5274
5275 Usually accessed via the C<SvPVutf8> macro.
5276
5277         char*   sv_2pvutf8(SV* sv, STRLEN* lp)
5278
5279 =for hackers
5280 Found in file sv.c
5281
5282 =item sv_2pv_flags
5283 X<sv_2pv_flags>
5284
5285 Returns a pointer to the string value of an SV, and sets *lp to its length.
5286 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5287 if necessary.
5288 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5289 usually end up here too.
5290
5291         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
5292
5293 =for hackers
5294 Found in file sv.c
5295
5296 =item sv_2uv_flags
5297 X<sv_2uv_flags>
5298
5299 Return the unsigned integer value of an SV, doing any necessary string
5300 conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
5301 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5302
5303         UV      sv_2uv_flags(SV* sv, I32 flags)
5304
5305 =for hackers
5306 Found in file sv.c
5307
5308 =item sv_backoff
5309 X<sv_backoff>
5310
5311 Remove any string offset. You should normally use the C<SvOOK_off> macro
5312 wrapper instead.
5313
5314         int     sv_backoff(SV* sv)
5315
5316 =for hackers
5317 Found in file sv.c
5318
5319 =item sv_bless
5320 X<sv_bless>
5321
5322 Blesses an SV into a specified package.  The SV must be an RV.  The package
5323 must be designated by its stash (see C<gv_stashpv()>).  The reference count
5324 of the SV is unaffected.
5325
5326         SV*     sv_bless(SV* sv, HV* stash)
5327
5328 =for hackers
5329 Found in file sv.c
5330
5331 =item sv_catpv
5332 X<sv_catpv>
5333
5334 Concatenates the string onto the end of the string which is in the SV.
5335 If the SV has the UTF-8 status set, then the bytes appended should be
5336 valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
5337
5338         void    sv_catpv(SV* sv, const char* ptr)
5339
5340 =for hackers
5341 Found in file sv.c
5342
5343 =item sv_catpvf
5344 X<sv_catpvf>
5345
5346 Processes its arguments like C<sprintf> and appends the formatted
5347 output to an SV.  If the appended data contains "wide" characters
5348 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5349 and characters >255 formatted with %c), the original SV might get
5350 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
5351 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5352 valid UTF-8; if the original SV was bytes, the pattern should be too.
5353
5354         void    sv_catpvf(SV* sv, const char* pat, ...)
5355
5356 =for hackers
5357 Found in file sv.c
5358
5359 =item sv_catpvf_mg
5360 X<sv_catpvf_mg>
5361
5362 Like C<sv_catpvf>, but also handles 'set' magic.
5363
5364         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
5365
5366 =for hackers
5367 Found in file sv.c
5368
5369 =item sv_catpvn
5370 X<sv_catpvn>
5371
5372 Concatenates the string onto the end of the string which is in the SV.  The
5373 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5374 status set, then the bytes appended should be valid UTF-8.
5375 Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
5376
5377         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
5378
5379 =for hackers
5380 Found in file sv.c
5381
5382 =item sv_catpvn_flags
5383 X<sv_catpvn_flags>
5384
5385 Concatenates the string onto the end of the string which is in the SV.  The
5386 C<len> indicates number of bytes to copy.  If the SV has the UTF-8
5387 status set, then the bytes appended should be valid UTF-8.
5388 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5389 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5390 in terms of this function.
5391
5392         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
5393
5394 =for hackers
5395 Found in file sv.c
5396
5397 =item sv_catpvs
5398 X<sv_catpvs>
5399
5400 Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5401
5402         void    sv_catpvs(SV* sv, const char* s)
5403
5404 =for hackers
5405 Found in file handy.h
5406
5407 =item sv_catpv_mg
5408 X<sv_catpv_mg>
5409
5410 Like C<sv_catpv>, but also handles 'set' magic.
5411
5412         void    sv_catpv_mg(SV *sv, const char *ptr)
5413
5414 =for hackers
5415 Found in file sv.c
5416
5417 =item sv_catsv
5418 X<sv_catsv>
5419
5420 Concatenates the string from SV C<ssv> onto the end of the string in
5421 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  Handles 'get' magic, but
5422 not 'set' magic.  See C<sv_catsv_mg>.
5423
5424         void    sv_catsv(SV* dsv, SV* ssv)
5425
5426 =for hackers
5427 Found in file sv.c
5428
5429 =item sv_catsv_flags
5430 X<sv_catsv_flags>
5431
5432 Concatenates the string from SV C<ssv> onto the end of the string in
5433 SV C<dsv>.  Modifies C<dsv> but not C<ssv>.  If C<flags> has C<SV_GMAGIC>
5434 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5435 and C<sv_catsv_nomg> are implemented in terms of this function.
5436
5437         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
5438
5439 =for hackers
5440 Found in file sv.c
5441
5442 =item sv_chop
5443 X<sv_chop>
5444
5445 Efficient removal of characters from the beginning of the string buffer.
5446 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5447 the string buffer.  The C<ptr> becomes the first character of the adjusted
5448 string. Uses the "OOK hack".
5449 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5450 refer to the same chunk of data.
5451
5452         void    sv_chop(SV* sv, const char* ptr)
5453
5454 =for hackers
5455 Found in file sv.c
5456
5457 =item sv_clear
5458 X<sv_clear>
5459
5460 Clear an SV: call any destructors, free up any memory used by the body,
5461 and free the body itself. The SV's head is I<not> freed, although
5462 its type is set to all 1's so that it won't inadvertently be assumed
5463 to be live during global destruction etc.
5464 This function should only be called when REFCNT is zero. Most of the time
5465 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5466 instead.
5467
5468         void    sv_clear(SV* sv)
5469
5470 =for hackers
5471 Found in file sv.c
5472
5473 =item sv_cmp
5474 X<sv_cmp>
5475
5476 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
5477 string in C<sv1> is less than, equal to, or greater than the string in
5478 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5479 coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
5480
5481         I32     sv_cmp(SV* sv1, SV* sv2)
5482
5483 =for hackers
5484 Found in file sv.c
5485
5486 =item sv_cmp_locale
5487 X<sv_cmp_locale>
5488
5489 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5490 'use bytes' aware, handles get magic, and will coerce its args to strings
5491 if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
5492
5493         I32     sv_cmp_locale(SV* sv1, SV* sv2)
5494
5495 =for hackers
5496 Found in file sv.c
5497
5498 =item sv_collxfrm
5499 X<sv_collxfrm>
5500
5501 Add Collate Transform magic to an SV if it doesn't already have it.
5502