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