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