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