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