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