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