This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate mainline.
[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 bytes_to_utf8
186
187 Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
188 Returns a pointer to the newly-created string, and sets C<len> to
189 reflect the new length.
190
191         U8 *    bytes_to_utf8(U8 *s, STRLEN *len)
192
193 =for hackers
194 Found in file utf8.c
195
196 =item call_argv
197
198 Performs a callback to the specified Perl sub.  See L<perlcall>.
199
200 NOTE: the perl_ form of this function is deprecated.
201
202         I32     call_argv(const char* sub_name, I32 flags, char** argv)
203
204 =for hackers
205 Found in file perl.c
206
207 =item call_method
208
209 Performs a callback to the specified Perl method.  The blessed object must
210 be on the stack.  See L<perlcall>.
211
212 NOTE: the perl_ form of this function is deprecated.
213
214         I32     call_method(const char* methname, I32 flags)
215
216 =for hackers
217 Found in file perl.c
218
219 =item call_pv
220
221 Performs a callback to the specified Perl sub.  See L<perlcall>.
222
223 NOTE: the perl_ form of this function is deprecated.
224
225         I32     call_pv(const char* sub_name, I32 flags)
226
227 =for hackers
228 Found in file perl.c
229
230 =item call_sv
231
232 Performs a callback to the Perl sub whose name is in the SV.  See
233 L<perlcall>.
234
235 NOTE: the perl_ form of this function is deprecated.
236
237         I32     call_sv(SV* sv, I32 flags)
238
239 =for hackers
240 Found in file perl.c
241
242 =item CLASS
243
244 Variable which is setup by C<xsubpp> to indicate the 
245 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
246
247         char*   CLASS
248
249 =for hackers
250 Found in file XSUB.h
251
252 =item Copy
253
254 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
255 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
256 the type.  May fail on overlapping copies.  See also C<Move>.
257
258         void    Copy(void* src, void* dest, int nitems, type)
259
260 =for hackers
261 Found in file handy.h
262
263 =item croak
264
265 This is the XSUB-writer's interface to Perl's C<die> function.
266 Normally use this function the same way you use the C C<printf>
267 function.  See C<warn>.
268
269 If you want to throw an exception object, assign the object to
270 C<$@> and then pass C<Nullch> to croak():
271
272    errsv = get_sv("@", TRUE);
273    sv_setsv(errsv, exception_object);
274    croak(Nullch);
275
276         void    croak(const char* pat, ...)
277
278 =for hackers
279 Found in file util.c
280
281 =item CvSTASH
282
283 Returns the stash of the CV.
284
285         HV*     CvSTASH(CV* cv)
286
287 =for hackers
288 Found in file cv.h
289
290 =item cv_const_sv
291
292 If C<cv> is a constant sub eligible for inlining. returns the constant
293 value returned by the sub.  Otherwise, returns NULL.
294
295 Constant subs can be created with C<newCONSTSUB> or as described in
296 L<perlsub/"Constant Functions">.
297
298         SV*     cv_const_sv(CV* cv)
299
300 =for hackers
301 Found in file op.c
302
303 =item dMARK
304
305 Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
306 C<dORIGMARK>.
307
308                 dMARK;
309
310 =for hackers
311 Found in file pp.h
312
313 =item dORIGMARK
314
315 Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
316
317                 dORIGMARK;
318
319 =for hackers
320 Found in file pp.h
321
322 =item dSP
323
324 Declares a local copy of perl's stack pointer for the XSUB, available via
325 the C<SP> macro.  See C<SP>.
326
327                 dSP;
328
329 =for hackers
330 Found in file pp.h
331
332 =item dXSARGS
333
334 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
335 is usually handled automatically by C<xsubpp>.  Declares the C<items>
336 variable to indicate the number of items on the stack.
337
338                 dXSARGS;
339
340 =for hackers
341 Found in file XSUB.h
342
343 =item dXSI32
344
345 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
346 handled automatically by C<xsubpp>.
347
348                 dXSI32;
349
350 =for hackers
351 Found in file XSUB.h
352
353 =item ENTER
354
355 Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
356
357                 ENTER;
358
359 =for hackers
360 Found in file scope.h
361
362 =item eval_pv
363
364 Tells Perl to C<eval> the given string and return an SV* result.
365
366 NOTE: the perl_ form of this function is deprecated.
367
368         SV*     eval_pv(const char* p, I32 croak_on_error)
369
370 =for hackers
371 Found in file perl.c
372
373 =item eval_sv
374
375 Tells Perl to C<eval> the string in the SV.
376
377 NOTE: the perl_ form of this function is deprecated.
378
379         I32     eval_sv(SV* sv, I32 flags)
380
381 =for hackers
382 Found in file perl.c
383
384 =item EXTEND
385
386 Used to extend the argument stack for an XSUB's return values. Once
387 used, guarantees that there is room for at least C<nitems> to be pushed
388 onto the stack.
389
390         void    EXTEND(SP, int nitems)
391
392 =for hackers
393 Found in file pp.h
394
395 =item fbm_compile
396
397 Analyses the string in order to make fast searches on it using fbm_instr()
398 -- the Boyer-Moore algorithm.
399
400         void    fbm_compile(SV* sv, U32 flags)
401
402 =for hackers
403 Found in file util.c
404
405 =item fbm_instr
406
407 Returns the location of the SV in the string delimited by C<str> and
408 C<strend>.  It returns C<Nullch> if the string can't be found.  The C<sv>
409 does not have to be fbm_compiled, but the search will not be as fast
410 then.
411
412         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
413
414 =for hackers
415 Found in file util.c
416
417 =item FREETMPS
418
419 Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
420 L<perlcall>.
421
422                 FREETMPS;
423
424 =for hackers
425 Found in file scope.h
426
427 =item get_av
428
429 Returns the AV of the specified Perl array.  If C<create> is set and the
430 Perl variable does not exist then it will be created.  If C<create> is not
431 set and the variable does not exist then NULL is returned.
432
433 NOTE: the perl_ form of this function is deprecated.
434
435         AV*     get_av(const char* name, I32 create)
436
437 =for hackers
438 Found in file perl.c
439
440 =item get_cv
441
442 Returns the CV of the specified Perl subroutine.  If C<create> is set and
443 the Perl subroutine does not exist then it will be declared (which has the
444 same effect as saying C<sub name;>).  If C<create> is not set and the
445 subroutine does not exist then NULL is returned.
446
447 NOTE: the perl_ form of this function is deprecated.
448
449         CV*     get_cv(const char* name, I32 create)
450
451 =for hackers
452 Found in file perl.c
453
454 =item get_hv
455
456 Returns the HV of the specified Perl hash.  If C<create> is set and the
457 Perl variable does not exist then it will be created.  If C<create> is not
458 set and the variable does not exist then NULL is returned.
459
460 NOTE: the perl_ form of this function is deprecated.
461
462         HV*     get_hv(const char* name, I32 create)
463
464 =for hackers
465 Found in file perl.c
466
467 =item get_sv
468
469 Returns the SV of the specified Perl scalar.  If C<create> is set and the
470 Perl variable does not exist then it will be created.  If C<create> is not
471 set and the variable does not exist then NULL is returned.
472
473 NOTE: the perl_ form of this function is deprecated.
474
475         SV*     get_sv(const char* name, I32 create)
476
477 =for hackers
478 Found in file perl.c
479
480 =item GIMME
481
482 A backward-compatible version of C<GIMME_V> which can only return
483 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
484 Deprecated.  Use C<GIMME_V> instead.
485
486         U32     GIMME
487
488 =for hackers
489 Found in file op.h
490
491 =item GIMME_V
492
493 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
494 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
495 respectively.
496
497         U32     GIMME_V
498
499 =for hackers
500 Found in file op.h
501
502 =item GvSV
503
504 Return the SV from the GV.
505
506         SV*     GvSV(GV* gv)
507
508 =for hackers
509 Found in file gv.h
510
511 =item gv_fetchmeth
512
513 Returns the glob with the given C<name> and a defined subroutine or
514 C<NULL>.  The glob lives in the given C<stash>, or in the stashes
515 accessible via @ISA and @UNIVERSAL.
516
517 The argument C<level> should be either 0 or -1.  If C<level==0>, as a
518 side-effect creates a glob with the given C<name> in the given C<stash>
519 which in the case of success contains an alias for the subroutine, and sets
520 up caching info for this glob.  Similarly for all the searched stashes.
521
522 This function grants C<"SUPER"> token as a postfix of the stash name. The
523 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
524 visible to Perl code.  So when calling C<call_sv>, you should not use
525 the GV directly; instead, you should use the method's CV, which can be
526 obtained from the GV with the C<GvCV> macro.
527
528         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
529
530 =for hackers
531 Found in file gv.c
532
533 =item gv_fetchmethod
534
535 See L<gv_fetchmethod_autoload>.
536
537         GV*     gv_fetchmethod(HV* stash, const char* name)
538
539 =for hackers
540 Found in file gv.c
541
542 =item gv_fetchmethod_autoload
543
544 Returns the glob which contains the subroutine to call to invoke the method
545 on the C<stash>.  In fact in the presence of autoloading this may be the
546 glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
547 already setup.
548
549 The third parameter of C<gv_fetchmethod_autoload> determines whether
550 AUTOLOAD lookup is performed if the given method is not present: non-zero
551 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
552 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
553 with a non-zero C<autoload> parameter.
554
555 These functions grant C<"SUPER"> token as a prefix of the method name. Note
556 that if you want to keep the returned glob for a long time, you need to
557 check for it being "AUTOLOAD", since at the later time the call may load a
558 different subroutine due to $AUTOLOAD changing its value. Use the glob
559 created via a side effect to do this.
560
561 These functions have the same side-effects and as C<gv_fetchmeth> with
562 C<level==0>.  C<name> should be writable if contains C<':'> or C<'
563 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
564 C<call_sv> apply equally to these functions.
565
566         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
567
568 =for hackers
569 Found in file gv.c
570
571 =item gv_stashpv
572
573 Returns a pointer to the stash for a specified package.  C<name> should
574 be a valid UTF-8 string.  If C<create> is set then the package will be
575 created if it does not already exist.  If C<create> is not set and the
576 package does not exist then NULL is returned.
577
578         HV*     gv_stashpv(const char* name, I32 create)
579
580 =for hackers
581 Found in file gv.c
582
583 =item gv_stashsv
584
585 Returns a pointer to the stash for a specified package, which must be a
586 valid UTF-8 string.  See C<gv_stashpv>.
587
588         HV*     gv_stashsv(SV* sv, I32 create)
589
590 =for hackers
591 Found in file gv.c
592
593 =item G_ARRAY
594
595 Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
596 L<perlcall>.
597
598 =for hackers
599 Found in file cop.h
600
601 =item G_DISCARD
602
603 Indicates that arguments returned from a callback should be discarded.  See
604 L<perlcall>.
605
606 =for hackers
607 Found in file cop.h
608
609 =item G_EVAL
610
611 Used to force a Perl C<eval> wrapper around a callback.  See
612 L<perlcall>.
613
614 =for hackers
615 Found in file cop.h
616
617 =item G_NOARGS
618
619 Indicates that no arguments are being sent to a callback.  See
620 L<perlcall>.
621
622 =for hackers
623 Found in file cop.h
624
625 =item G_SCALAR
626
627 Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
628 L<perlcall>.
629
630 =for hackers
631 Found in file cop.h
632
633 =item G_VOID
634
635 Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
636
637 =for hackers
638 Found in file cop.h
639
640 =item HEf_SVKEY
641
642 This flag, used in the length slot of hash entries and magic structures,
643 specifies the structure contains a C<SV*> pointer where a C<char*> pointer
644 is to be expected. (For information only--not to be used).
645
646 =for hackers
647 Found in file hv.h
648
649 =item HeHASH
650
651 Returns the computed hash stored in the hash entry.
652
653         U32     HeHASH(HE* he)
654
655 =for hackers
656 Found in file hv.h
657
658 =item HeKEY
659
660 Returns the actual pointer stored in the key slot of the hash entry. The
661 pointer may be either C<char*> or C<SV*>, depending on the value of
662 C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
663 usually preferable for finding the value of a key.
664
665         void*   HeKEY(HE* he)
666
667 =for hackers
668 Found in file hv.h
669
670 =item HeKLEN
671
672 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
673 holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
674 be assigned to. The C<HePV()> macro is usually preferable for finding key
675 lengths.
676
677         STRLEN  HeKLEN(HE* he)
678
679 =for hackers
680 Found in file hv.h
681
682 =item HePV
683
684 Returns the key slot of the hash entry as a C<char*> value, doing any
685 necessary dereferencing of possibly C<SV*> keys.  The length of the string
686 is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
687 not care about what the length of the key is, you may use the global
688 variable C<PL_na>, though this is rather less efficient than using a local
689 variable.  Remember though, that hash keys in perl are free to contain
690 embedded nulls, so using C<strlen()> or similar is not a good way to find
691 the length of hash keys. This is very similar to the C<SvPV()> macro
692 described elsewhere in this document.
693
694         char*   HePV(HE* he, STRLEN len)
695
696 =for hackers
697 Found in file hv.h
698
699 =item HeSVKEY
700
701 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
702 contain an C<SV*> key.
703
704         SV*     HeSVKEY(HE* he)
705
706 =for hackers
707 Found in file hv.h
708
709 =item HeSVKEY_force
710
711 Returns the key as an C<SV*>.  Will create and return a temporary mortal
712 C<SV*> if the hash entry contains only a C<char*> key.
713
714         SV*     HeSVKEY_force(HE* he)
715
716 =for hackers
717 Found in file hv.h
718
719 =item HeSVKEY_set
720
721 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
722 indicate the presence of an C<SV*> key, and returns the same
723 C<SV*>.
724
725         SV*     HeSVKEY_set(HE* he, SV* sv)
726
727 =for hackers
728 Found in file hv.h
729
730 =item HeVAL
731
732 Returns the value slot (type C<SV*>) stored in the hash entry.
733
734         SV*     HeVAL(HE* he)
735
736 =for hackers
737 Found in file hv.h
738
739 =item HvNAME
740
741 Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
742
743         char*   HvNAME(HV* stash)
744
745 =for hackers
746 Found in file hv.h
747
748 =item hv_clear
749
750 Clears a hash, making it empty.
751
752         void    hv_clear(HV* tb)
753
754 =for hackers
755 Found in file hv.c
756
757 =item hv_delete
758
759 Deletes a key/value pair in the hash.  The value SV is removed from the
760 hash and returned to the caller.  The C<klen> is the length of the key.
761 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
762 will be returned.
763
764         SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
765
766 =for hackers
767 Found in file hv.c
768
769 =item hv_delete_ent
770
771 Deletes a key/value pair in the hash.  The value SV is removed from the
772 hash and returned to the caller.  The C<flags> value will normally be zero;
773 if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
774 precomputed hash value, or 0 to ask for it to be computed.
775
776         SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
777
778 =for hackers
779 Found in file hv.c
780
781 =item hv_exists
782
783 Returns a boolean indicating whether the specified hash key exists.  The
784 C<klen> is the length of the key.
785
786         bool    hv_exists(HV* tb, const char* key, I32 klen)
787
788 =for hackers
789 Found in file hv.c
790
791 =item hv_exists_ent
792
793 Returns a boolean indicating whether the specified hash key exists. C<hash>
794 can be a valid precomputed hash value, or 0 to ask for it to be
795 computed.
796
797         bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
798
799 =for hackers
800 Found in file hv.c
801
802 =item hv_fetch
803
804 Returns the SV which corresponds to the specified key in the hash.  The
805 C<klen> is the length of the key.  If C<lval> is set then the fetch will be
806 part of a store.  Check that the return value is non-null before
807 dereferencing it to a C<SV*>.
808
809 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
810 information on how to use this function on tied hashes.
811
812         SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
813
814 =for hackers
815 Found in file hv.c
816
817 =item hv_fetch_ent
818
819 Returns the hash entry which corresponds to the specified key in the hash.
820 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
821 if you want the function to compute it.  IF C<lval> is set then the fetch
822 will be part of a store.  Make sure the return value is non-null before
823 accessing it.  The return value when C<tb> is a tied hash is a pointer to a
824 static location, so be sure to make a copy of the structure if you need to
825 store it somewhere.
826
827 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
828 information on how to use this function on tied hashes.
829
830         HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
831
832 =for hackers
833 Found in file hv.c
834
835 =item hv_iterinit
836
837 Prepares a starting point to traverse a hash table.  Returns the number of
838 keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
839 currently only meaningful for hashes without tie magic.
840
841 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
842 hash buckets that happen to be in use.  If you still need that esoteric
843 value, you can get it through the macro C<HvFILL(tb)>.
844
845         I32     hv_iterinit(HV* tb)
846
847 =for hackers
848 Found in file hv.c
849
850 =item hv_iterkey
851
852 Returns the key from the current position of the hash iterator.  See
853 C<hv_iterinit>.
854
855         char*   hv_iterkey(HE* entry, I32* retlen)
856
857 =for hackers
858 Found in file hv.c
859
860 =item hv_iterkeysv
861
862 Returns the key as an C<SV*> from the current position of the hash
863 iterator.  The return value will always be a mortal copy of the key.  Also
864 see C<hv_iterinit>.
865
866         SV*     hv_iterkeysv(HE* entry)
867
868 =for hackers
869 Found in file hv.c
870
871 =item hv_iternext
872
873 Returns entries from a hash iterator.  See C<hv_iterinit>.
874
875         HE*     hv_iternext(HV* tb)
876
877 =for hackers
878 Found in file hv.c
879
880 =item hv_iternextsv
881
882 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
883 operation.
884
885         SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
886
887 =for hackers
888 Found in file hv.c
889
890 =item hv_iterval
891
892 Returns the value from the current position of the hash iterator.  See
893 C<hv_iterkey>.
894
895         SV*     hv_iterval(HV* tb, HE* entry)
896
897 =for hackers
898 Found in file hv.c
899
900 =item hv_magic
901
902 Adds magic to a hash.  See C<sv_magic>.
903
904         void    hv_magic(HV* hv, GV* gv, int how)
905
906 =for hackers
907 Found in file hv.c
908
909 =item hv_store
910
911 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
912 the length of the key.  The C<hash> parameter is the precomputed hash
913 value; if it is zero then Perl will compute it.  The return value will be
914 NULL if the operation failed or if the value did not need to be actually
915 stored within the hash (as in the case of tied hashes).  Otherwise it can
916 be dereferenced to get the original C<SV*>.  Note that the caller is
917 responsible for suitably incrementing the reference count of C<val> before
918 the call, and decrementing it if the function returned NULL.
919
920 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
921 information on how to use this function on tied hashes.
922
923         SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
924
925 =for hackers
926 Found in file hv.c
927
928 =item hv_store_ent
929
930 Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
931 parameter is the precomputed hash value; if it is zero then Perl will
932 compute it.  The return value is the new hash entry so created.  It will be
933 NULL if the operation failed or if the value did not need to be actually
934 stored within the hash (as in the case of tied hashes).  Otherwise the
935 contents of the return value can be accessed using the C<He???> macros
936 described here.  Note that the caller is responsible for suitably
937 incrementing the reference count of C<val> before the call, and
938 decrementing it if the function returned NULL.
939
940 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
941 information on how to use this function on tied hashes.
942
943         HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
944
945 =for hackers
946 Found in file hv.c
947
948 =item hv_undef
949
950 Undefines the hash.
951
952         void    hv_undef(HV* tb)
953
954 =for hackers
955 Found in file hv.c
956
957 =item isALNUM
958
959 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
960 character (including underscore) or digit.
961
962         bool    isALNUM(char ch)
963
964 =for hackers
965 Found in file handy.h
966
967 =item isALPHA
968
969 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
970 character.
971
972         bool    isALPHA(char ch)
973
974 =for hackers
975 Found in file handy.h
976
977 =item isDIGIT
978
979 Returns a boolean indicating whether the C C<char> is an ASCII
980 digit.
981
982         bool    isDIGIT(char ch)
983
984 =for hackers
985 Found in file handy.h
986
987 =item isLOWER
988
989 Returns a boolean indicating whether the C C<char> is a lowercase
990 character.
991
992         bool    isLOWER(char ch)
993
994 =for hackers
995 Found in file handy.h
996
997 =item isSPACE
998
999 Returns a boolean indicating whether the C C<char> is whitespace.
1000
1001         bool    isSPACE(char ch)
1002
1003 =for hackers
1004 Found in file handy.h
1005
1006 =item isUPPER
1007
1008 Returns a boolean indicating whether the C C<char> is an uppercase
1009 character.
1010
1011         bool    isUPPER(char ch)
1012
1013 =for hackers
1014 Found in file handy.h
1015
1016 =item items
1017
1018 Variable which is setup by C<xsubpp> to indicate the number of 
1019 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
1020
1021         I32     items
1022
1023 =for hackers
1024 Found in file XSUB.h
1025
1026 =item ix
1027
1028 Variable which is setup by C<xsubpp> to indicate which of an 
1029 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
1030
1031         I32     ix
1032
1033 =for hackers
1034 Found in file XSUB.h
1035
1036 =item LEAVE
1037
1038 Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
1039
1040                 LEAVE;
1041
1042 =for hackers
1043 Found in file scope.h
1044
1045 =item looks_like_number
1046
1047 Test if an the content of an SV looks like a number (or is a
1048 number). C<Inf> and C<Infinity> are treated as numbers (so will not
1049 issue a non-numeric warning), even if your atof() doesn't grok them.
1050
1051         I32     looks_like_number(SV* sv)
1052
1053 =for hackers
1054 Found in file sv.c
1055
1056 =item MARK
1057
1058 Stack marker variable for the XSUB.  See C<dMARK>.
1059
1060 =for hackers
1061 Found in file pp.h
1062
1063 =item mg_clear
1064
1065 Clear something magical that the SV represents.  See C<sv_magic>.
1066
1067         int     mg_clear(SV* sv)
1068
1069 =for hackers
1070 Found in file mg.c
1071
1072 =item mg_copy
1073
1074 Copies the magic from one SV to another.  See C<sv_magic>.
1075
1076         int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1077
1078 =for hackers
1079 Found in file mg.c
1080
1081 =item mg_find
1082
1083 Finds the magic pointer for type matching the SV.  See C<sv_magic>.
1084
1085         MAGIC*  mg_find(SV* sv, int type)
1086
1087 =for hackers
1088 Found in file mg.c
1089
1090 =item mg_free
1091
1092 Free any magic storage used by the SV.  See C<sv_magic>.
1093
1094         int     mg_free(SV* sv)
1095
1096 =for hackers
1097 Found in file mg.c
1098
1099 =item mg_get
1100
1101 Do magic after a value is retrieved from the SV.  See C<sv_magic>.
1102
1103         int     mg_get(SV* sv)
1104
1105 =for hackers
1106 Found in file mg.c
1107
1108 =item mg_length
1109
1110 Report on the SV's length.  See C<sv_magic>.
1111
1112         U32     mg_length(SV* sv)
1113
1114 =for hackers
1115 Found in file mg.c
1116
1117 =item mg_magical
1118
1119 Turns on the magical status of an SV.  See C<sv_magic>.
1120
1121         void    mg_magical(SV* sv)
1122
1123 =for hackers
1124 Found in file mg.c
1125
1126 =item mg_set
1127
1128 Do magic after a value is assigned to the SV.  See C<sv_magic>.
1129
1130         int     mg_set(SV* sv)
1131
1132 =for hackers
1133 Found in file mg.c
1134
1135 =item Move
1136
1137 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
1138 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1139 the type.  Can do overlapping moves.  See also C<Copy>.
1140
1141         void    Move(void* src, void* dest, int nitems, type)
1142
1143 =for hackers
1144 Found in file handy.h
1145
1146 =item New
1147
1148 The XSUB-writer's interface to the C C<malloc> function.
1149
1150         void    New(int id, void* ptr, int nitems, type)
1151
1152 =for hackers
1153 Found in file handy.h
1154
1155 =item newAV
1156
1157 Creates a new AV.  The reference count is set to 1.
1158
1159         AV*     newAV()
1160
1161 =for hackers
1162 Found in file av.c
1163
1164 =item Newc
1165
1166 The XSUB-writer's interface to the C C<malloc> function, with
1167 cast.
1168
1169         void    Newc(int id, void* ptr, int nitems, type, cast)
1170
1171 =for hackers
1172 Found in file handy.h
1173
1174 =item newCONSTSUB
1175
1176 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1177 eligible for inlining at compile-time.
1178
1179         CV*     newCONSTSUB(HV* stash, char* name, SV* sv)
1180
1181 =for hackers
1182 Found in file op.c
1183
1184 =item newHV
1185
1186 Creates a new HV.  The reference count is set to 1.
1187
1188         HV*     newHV()
1189
1190 =for hackers
1191 Found in file hv.c
1192
1193 =item newRV_inc
1194
1195 Creates an RV wrapper for an SV.  The reference count for the original SV is
1196 incremented.
1197
1198         SV*     newRV_inc(SV* sv)
1199
1200 =for hackers
1201 Found in file sv.h
1202
1203 =item newRV_noinc
1204
1205 Creates an RV wrapper for an SV.  The reference count for the original
1206 SV is B<not> incremented.
1207
1208         SV*     newRV_noinc(SV *sv)
1209
1210 =for hackers
1211 Found in file sv.c
1212
1213 =item NEWSV
1214
1215 Creates a new SV.  A non-zero C<len> parameter indicates the number of
1216 bytes of preallocated string space the SV should have.  An extra byte for a
1217 tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
1218 space is allocated.)  The reference count for the new SV is set to 1.
1219 C<id> is an integer id between 0 and 1299 (used to identify leaks).
1220
1221         SV*     NEWSV(int id, STRLEN len)
1222
1223 =for hackers
1224 Found in file handy.h
1225
1226 =item newSViv
1227
1228 Creates a new SV and copies an integer into it.  The reference count for the
1229 SV is set to 1.
1230
1231         SV*     newSViv(IV i)
1232
1233 =for hackers
1234 Found in file sv.c
1235
1236 =item newSVnv
1237
1238 Creates a new SV and copies a floating point value into it.
1239 The reference count for the SV is set to 1.
1240
1241         SV*     newSVnv(NV n)
1242
1243 =for hackers
1244 Found in file sv.c
1245
1246 =item newSVpv
1247
1248 Creates a new SV and copies a string into it.  The reference count for the
1249 SV is set to 1.  If C<len> is zero, Perl will compute the length using
1250 strlen().  For efficiency, consider using C<newSVpvn> instead.
1251
1252         SV*     newSVpv(const char* s, STRLEN len)
1253
1254 =for hackers
1255 Found in file sv.c
1256
1257 =item newSVpvf
1258
1259 Creates a new SV an initialize it with the string formatted like
1260 C<sprintf>.
1261
1262         SV*     newSVpvf(const char* pat, ...)
1263
1264 =for hackers
1265 Found in file sv.c
1266
1267 =item newSVpvn
1268
1269 Creates a new SV and copies a string into it.  The reference count for the
1270 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
1271 string.  You are responsible for ensuring that the source string is at least
1272 C<len> bytes long.
1273
1274         SV*     newSVpvn(const char* s, STRLEN len)
1275
1276 =for hackers
1277 Found in file sv.c
1278
1279 =item newSVpvn_share
1280
1281 Creates a new SV and populates it with a string from
1282 the string table. Turns on READONLY and FAKE.
1283 The idea here is that as string table is used for shared hash
1284 keys these strings will have SvPVX == HeKEY and hash lookup
1285 will avoid string compare.
1286
1287         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
1288
1289 =for hackers
1290 Found in file sv.c
1291
1292 =item newSVrv
1293
1294 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
1295 it will be upgraded to one.  If C<classname> is non-null then the new SV will
1296 be blessed in the specified package.  The new SV is returned and its
1297 reference count is 1.
1298
1299         SV*     newSVrv(SV* rv, const char* classname)
1300
1301 =for hackers
1302 Found in file sv.c
1303
1304 =item newSVsv
1305
1306 Creates a new SV which is an exact duplicate of the original SV.
1307
1308         SV*     newSVsv(SV* old)
1309
1310 =for hackers
1311 Found in file sv.c
1312
1313 =item newSVuv
1314
1315 Creates a new SV and copies an unsigned integer into it.
1316 The reference count for the SV is set to 1.
1317
1318         SV*     newSVuv(UV u)
1319
1320 =for hackers
1321 Found in file sv.c
1322
1323 =item newXS
1324
1325 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1326
1327 =for hackers
1328 Found in file op.c
1329
1330 =item newXSproto
1331
1332 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
1333 the subs.
1334
1335 =for hackers
1336 Found in file XSUB.h
1337
1338 =item Newz
1339
1340 The XSUB-writer's interface to the C C<malloc> function.  The allocated
1341 memory is zeroed with C<memzero>.
1342
1343         void    Newz(int id, void* ptr, int nitems, type)
1344
1345 =for hackers
1346 Found in file handy.h
1347
1348 =item Nullav
1349
1350 Null AV pointer.
1351
1352 =for hackers
1353 Found in file av.h
1354
1355 =item Nullch
1356
1357 Null character pointer.
1358
1359 =for hackers
1360 Found in file handy.h
1361
1362 =item Nullcv
1363
1364 Null CV pointer.
1365
1366 =for hackers
1367 Found in file cv.h
1368
1369 =item Nullhv
1370
1371 Null HV pointer.
1372
1373 =for hackers
1374 Found in file hv.h
1375
1376 =item Nullsv
1377
1378 Null SV pointer.
1379
1380 =for hackers
1381 Found in file handy.h
1382
1383 =item ORIGMARK
1384
1385 The original stack mark for the XSUB.  See C<dORIGMARK>.
1386
1387 =for hackers
1388 Found in file pp.h
1389
1390 =item perl_alloc
1391
1392 Allocates a new Perl interpreter.  See L<perlembed>.
1393
1394         PerlInterpreter*        perl_alloc()
1395
1396 =for hackers
1397 Found in file perl.c
1398
1399 =item perl_construct
1400
1401 Initializes a new Perl interpreter.  See L<perlembed>.
1402
1403         void    perl_construct(PerlInterpreter* interp)
1404
1405 =for hackers
1406 Found in file perl.c
1407
1408 =item perl_destruct
1409
1410 Shuts down a Perl interpreter.  See L<perlembed>.
1411
1412         void    perl_destruct(PerlInterpreter* interp)
1413
1414 =for hackers
1415 Found in file perl.c
1416
1417 =item perl_free
1418
1419 Releases a Perl interpreter.  See L<perlembed>.
1420
1421         void    perl_free(PerlInterpreter* interp)
1422
1423 =for hackers
1424 Found in file perl.c
1425
1426 =item perl_parse
1427
1428 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
1429
1430         int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1431
1432 =for hackers
1433 Found in file perl.c
1434
1435 =item perl_run
1436
1437 Tells a Perl interpreter to run.  See L<perlembed>.
1438
1439         int     perl_run(PerlInterpreter* interp)
1440
1441 =for hackers
1442 Found in file perl.c
1443
1444 =item PL_DBsingle
1445
1446 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1447 boolean which indicates whether subs are being single-stepped.
1448 Single-stepping is automatically turned on after every step.  This is the C
1449 variable which corresponds to Perl's $DB::single variable.  See
1450 C<PL_DBsub>.
1451
1452         SV *    PL_DBsingle
1453
1454 =for hackers
1455 Found in file intrpvar.h
1456
1457 =item PL_DBsub
1458
1459 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1460 the SV which holds the name of the sub being debugged.  This is the C
1461 variable which corresponds to Perl's $DB::sub variable.  See
1462 C<PL_DBsingle>.
1463
1464         GV *    PL_DBsub
1465
1466 =for hackers
1467 Found in file intrpvar.h
1468
1469 =item PL_DBtrace
1470
1471 Trace variable used when Perl is run in debugging mode, with the B<-d>
1472 switch.  This is the C variable which corresponds to Perl's $DB::trace
1473 variable.  See C<PL_DBsingle>.
1474
1475         SV *    PL_DBtrace
1476
1477 =for hackers
1478 Found in file intrpvar.h
1479
1480 =item PL_dowarn
1481
1482 The C variable which corresponds to Perl's $^W warning variable.
1483
1484         bool    PL_dowarn
1485
1486 =for hackers
1487 Found in file intrpvar.h
1488
1489 =item PL_modglobal
1490
1491 C<PL_modglobal> is a general purpose, interpreter global HV for use by
1492 extensions that need to keep information on a per-interpreter basis.
1493 In a pinch, it can also be used as a symbol table for extensions
1494 to share data among each other.  It is a good idea to use keys
1495 prefixed by the package name of the extension that owns the data.
1496
1497         HV*     PL_modglobal
1498
1499 =for hackers
1500 Found in file intrpvar.h
1501
1502 =item PL_na
1503
1504 A convenience variable which is typically used with C<SvPV> when one
1505 doesn't care about the length of the string.  It is usually more efficient
1506 to either declare a local variable and use that instead or to use the
1507 C<SvPV_nolen> macro.
1508
1509         STRLEN  PL_na
1510
1511 =for hackers
1512 Found in file thrdvar.h
1513
1514 =item PL_sv_no
1515
1516 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
1517 C<&PL_sv_no>.
1518
1519         SV      PL_sv_no
1520
1521 =for hackers
1522 Found in file intrpvar.h
1523
1524 =item PL_sv_undef
1525
1526 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
1527
1528         SV      PL_sv_undef
1529
1530 =for hackers
1531 Found in file intrpvar.h
1532
1533 =item PL_sv_yes
1534
1535 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
1536 C<&PL_sv_yes>.
1537
1538         SV      PL_sv_yes
1539
1540 =for hackers
1541 Found in file intrpvar.h
1542
1543 =item POPi
1544
1545 Pops an integer off the stack.
1546
1547         IV      POPi
1548
1549 =for hackers
1550 Found in file pp.h
1551
1552 =item POPl
1553
1554 Pops a long off the stack.
1555
1556         long    POPl
1557
1558 =for hackers
1559 Found in file pp.h
1560
1561 =item POPn
1562
1563 Pops a double off the stack.
1564
1565         NV      POPn
1566
1567 =for hackers
1568 Found in file pp.h
1569
1570 =item POPp
1571
1572 Pops a string off the stack.
1573
1574         char*   POPp
1575
1576 =for hackers
1577 Found in file pp.h
1578
1579 =item POPs
1580
1581 Pops an SV off the stack.
1582
1583         SV*     POPs
1584
1585 =for hackers
1586 Found in file pp.h
1587
1588 =item PUSHi
1589
1590 Push an integer onto the stack.  The stack must have room for this element.
1591 Handles 'set' magic.  See C<XPUSHi>.
1592
1593         void    PUSHi(IV iv)
1594
1595 =for hackers
1596 Found in file pp.h
1597
1598 =item PUSHMARK
1599
1600 Opening bracket for arguments on a callback.  See C<PUTBACK> and
1601 L<perlcall>.
1602
1603                 PUSHMARK;
1604
1605 =for hackers
1606 Found in file pp.h
1607
1608 =item PUSHn
1609
1610 Push a double onto the stack.  The stack must have room for this element.
1611 Handles 'set' magic.  See C<XPUSHn>.
1612
1613         void    PUSHn(NV nv)
1614
1615 =for hackers
1616 Found in file pp.h
1617
1618 =item PUSHp
1619
1620 Push a string onto the stack.  The stack must have room for this element.
1621 The C<len> indicates the length of the string.  Handles 'set' magic.  See
1622 C<XPUSHp>.
1623
1624         void    PUSHp(char* str, STRLEN len)
1625
1626 =for hackers
1627 Found in file pp.h
1628
1629 =item PUSHs
1630
1631 Push an SV onto the stack.  The stack must have room for this element.
1632 Does not handle 'set' magic.  See C<XPUSHs>.
1633
1634         void    PUSHs(SV* sv)
1635
1636 =for hackers
1637 Found in file pp.h
1638
1639 =item PUSHu
1640
1641 Push an unsigned integer onto the stack.  The stack must have room for this
1642 element.  See C<XPUSHu>.
1643
1644         void    PUSHu(UV uv)
1645
1646 =for hackers
1647 Found in file pp.h
1648
1649 =item PUTBACK
1650
1651 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
1652 See C<PUSHMARK> and L<perlcall> for other uses.
1653
1654                 PUTBACK;
1655
1656 =for hackers
1657 Found in file pp.h
1658
1659 =item Renew
1660
1661 The XSUB-writer's interface to the C C<realloc> function.
1662
1663         void    Renew(void* ptr, int nitems, type)
1664
1665 =for hackers
1666 Found in file handy.h
1667
1668 =item Renewc
1669
1670 The XSUB-writer's interface to the C C<realloc> function, with
1671 cast.
1672
1673         void    Renewc(void* ptr, int nitems, type, cast)
1674
1675 =for hackers
1676 Found in file handy.h
1677
1678 =item require_pv
1679
1680 Tells Perl to C<require> a module.
1681
1682 NOTE: the perl_ form of this function is deprecated.
1683
1684         void    require_pv(const char* pv)
1685
1686 =for hackers
1687 Found in file perl.c
1688
1689 =item RETVAL
1690
1691 Variable which is setup by C<xsubpp> to hold the return value for an 
1692 XSUB. This is always the proper type for the XSUB. See 
1693 L<perlxs/"The RETVAL Variable">.
1694
1695         (whatever)      RETVAL
1696
1697 =for hackers
1698 Found in file XSUB.h
1699
1700 =item Safefree
1701
1702 The XSUB-writer's interface to the C C<free> function.
1703
1704         void    Safefree(void* ptr)
1705
1706 =for hackers
1707 Found in file handy.h
1708
1709 =item savepv
1710
1711 Copy a string to a safe spot.  This does not use an SV.
1712
1713         char*   savepv(const char* sv)
1714
1715 =for hackers
1716 Found in file util.c
1717
1718 =item savepvn
1719
1720 Copy a string to a safe spot.  The C<len> indicates number of bytes to
1721 copy.  This does not use an SV.
1722
1723         char*   savepvn(const char* sv, I32 len)
1724
1725 =for hackers
1726 Found in file util.c
1727
1728 =item SAVETMPS
1729
1730 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
1731 L<perlcall>.
1732
1733                 SAVETMPS;
1734
1735 =for hackers
1736 Found in file scope.h
1737
1738 =item SP
1739
1740 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
1741 C<SPAGAIN>.
1742
1743 =for hackers
1744 Found in file pp.h
1745
1746 =item SPAGAIN
1747
1748 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
1749
1750                 SPAGAIN;
1751
1752 =for hackers
1753 Found in file pp.h
1754
1755 =item ST
1756
1757 Used to access elements on the XSUB's stack.
1758
1759         SV*     ST(int ix)
1760
1761 =for hackers
1762 Found in file XSUB.h
1763
1764 =item strEQ
1765
1766 Test two strings to see if they are equal.  Returns true or false.
1767
1768         bool    strEQ(char* s1, char* s2)
1769
1770 =for hackers
1771 Found in file handy.h
1772
1773 =item strGE
1774
1775 Test two strings to see if the first, C<s1>, is greater than or equal to
1776 the second, C<s2>.  Returns true or false.
1777
1778         bool    strGE(char* s1, char* s2)
1779
1780 =for hackers
1781 Found in file handy.h
1782
1783 =item strGT
1784
1785 Test two strings to see if the first, C<s1>, is greater than the second,
1786 C<s2>.  Returns true or false.
1787
1788         bool    strGT(char* s1, char* s2)
1789
1790 =for hackers
1791 Found in file handy.h
1792
1793 =item strLE
1794
1795 Test two strings to see if the first, C<s1>, is less than or equal to the
1796 second, C<s2>.  Returns true or false.
1797
1798         bool    strLE(char* s1, char* s2)
1799
1800 =for hackers
1801 Found in file handy.h
1802
1803 =item strLT
1804
1805 Test two strings to see if the first, C<s1>, is less than the second,
1806 C<s2>.  Returns true or false.
1807
1808         bool    strLT(char* s1, char* s2)
1809
1810 =for hackers
1811 Found in file handy.h
1812
1813 =item strNE
1814
1815 Test two strings to see if they are different.  Returns true or
1816 false.
1817
1818         bool    strNE(char* s1, char* s2)
1819
1820 =for hackers
1821 Found in file handy.h
1822
1823 =item strnEQ
1824
1825 Test two strings to see if they are equal.  The C<len> parameter indicates
1826 the number of bytes to compare.  Returns true or false. (A wrapper for
1827 C<strncmp>).
1828
1829         bool    strnEQ(char* s1, char* s2, STRLEN len)
1830
1831 =for hackers
1832 Found in file handy.h
1833
1834 =item strnNE
1835
1836 Test two strings to see if they are different.  The C<len> parameter
1837 indicates the number of bytes to compare.  Returns true or false. (A
1838 wrapper for C<strncmp>).
1839
1840         bool    strnNE(char* s1, char* s2, STRLEN len)
1841
1842 =for hackers
1843 Found in file handy.h
1844
1845 =item StructCopy
1846
1847 This is an architecture-independent macro to copy one structure to another.
1848
1849         void    StructCopy(type src, type dest, type)
1850
1851 =for hackers
1852 Found in file handy.h
1853
1854 =item SvCUR
1855
1856 Returns the length of the string which is in the SV.  See C<SvLEN>.
1857
1858         STRLEN  SvCUR(SV* sv)
1859
1860 =for hackers
1861 Found in file sv.h
1862
1863 =item SvCUR_set
1864
1865 Set the length of the string which is in the SV.  See C<SvCUR>.
1866
1867         void    SvCUR_set(SV* sv, STRLEN len)
1868
1869 =for hackers
1870 Found in file sv.h
1871
1872 =item SvEND
1873
1874 Returns a pointer to the last character in the string which is in the SV.
1875 See C<SvCUR>.  Access the character as *(SvEND(sv)).
1876
1877         char*   SvEND(SV* sv)
1878
1879 =for hackers
1880 Found in file sv.h
1881
1882 =item SvGETMAGIC
1883
1884 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
1885 argument more than once.
1886
1887         void    SvGETMAGIC(SV* sv)
1888
1889 =for hackers
1890 Found in file sv.h
1891
1892 =item SvGROW
1893
1894 Expands the character buffer in the SV so that it has room for the
1895 indicated number of bytes (remember to reserve space for an extra trailing
1896 NUL character).  Calls C<sv_grow> to perform the expansion if necessary. 
1897 Returns a pointer to the character buffer.
1898
1899         void    SvGROW(SV* sv, STRLEN len)
1900
1901 =for hackers
1902 Found in file sv.h
1903
1904 =item SvIOK
1905
1906 Returns a boolean indicating whether the SV contains an integer.
1907
1908         bool    SvIOK(SV* sv)
1909
1910 =for hackers
1911 Found in file sv.h
1912
1913 =item SvIOKp
1914
1915 Returns a boolean indicating whether the SV contains an integer.  Checks
1916 the B<private> setting.  Use C<SvIOK>.
1917
1918         bool    SvIOKp(SV* sv)
1919
1920 =for hackers
1921 Found in file sv.h
1922
1923 =item SvIOK_notUV
1924
1925 Returns a boolean indicating whether the SV contains an signed integer.
1926
1927         void    SvIOK_notUV(SV* sv)
1928
1929 =for hackers
1930 Found in file sv.h
1931
1932 =item SvIOK_off
1933
1934 Unsets the IV status of an SV.
1935
1936         void    SvIOK_off(SV* sv)
1937
1938 =for hackers
1939 Found in file sv.h
1940
1941 =item SvIOK_on
1942
1943 Tells an SV that it is an integer.
1944
1945         void    SvIOK_on(SV* sv)
1946
1947 =for hackers
1948 Found in file sv.h
1949
1950 =item SvIOK_only
1951
1952 Tells an SV that it is an integer and disables all other OK bits.
1953
1954         void    SvIOK_only(SV* sv)
1955
1956 =for hackers
1957 Found in file sv.h
1958
1959 =item SvIOK_only_UV
1960
1961 Tells and SV that it is an unsigned integer and disables all other OK bits.
1962
1963         void    SvIOK_only_UV(SV* sv)
1964
1965 =for hackers
1966 Found in file sv.h
1967
1968 =item SvIOK_UV
1969
1970 Returns a boolean indicating whether the SV contains an unsigned integer.
1971
1972         void    SvIOK_UV(SV* sv)
1973
1974 =for hackers
1975 Found in file sv.h
1976
1977 =item SvIV
1978
1979 Coerces the given SV to an integer and returns it.
1980
1981         IV      SvIV(SV* sv)
1982
1983 =for hackers
1984 Found in file sv.h
1985
1986 =item SvIVX
1987
1988 Returns the integer which is stored in the SV, assuming SvIOK is
1989 true.
1990
1991         IV      SvIVX(SV* sv)
1992
1993 =for hackers
1994 Found in file sv.h
1995
1996 =item SvLEN
1997
1998 Returns the size of the string buffer in the SV, not including any part
1999 attributable to C<SvOOK>.  See C<SvCUR>.
2000
2001         STRLEN  SvLEN(SV* sv)
2002
2003 =for hackers
2004 Found in file sv.h
2005
2006 =item SvNIOK
2007
2008 Returns a boolean indicating whether the SV contains a number, integer or
2009 double.
2010
2011         bool    SvNIOK(SV* sv)
2012
2013 =for hackers
2014 Found in file sv.h
2015
2016 =item SvNIOKp
2017
2018 Returns a boolean indicating whether the SV contains a number, integer or
2019 double.  Checks the B<private> setting.  Use C<SvNIOK>.
2020
2021         bool    SvNIOKp(SV* sv)
2022
2023 =for hackers
2024 Found in file sv.h
2025
2026 =item SvNIOK_off
2027
2028 Unsets the NV/IV status of an SV.
2029
2030         void    SvNIOK_off(SV* sv)
2031
2032 =for hackers
2033 Found in file sv.h
2034
2035 =item SvNOK
2036
2037 Returns a boolean indicating whether the SV contains a double.
2038
2039         bool    SvNOK(SV* sv)
2040
2041 =for hackers
2042 Found in file sv.h
2043
2044 =item SvNOKp
2045
2046 Returns a boolean indicating whether the SV contains a double.  Checks the
2047 B<private> setting.  Use C<SvNOK>.
2048
2049         bool    SvNOKp(SV* sv)
2050
2051 =for hackers
2052 Found in file sv.h
2053
2054 =item SvNOK_off
2055
2056 Unsets the NV status of an SV.
2057
2058         void    SvNOK_off(SV* sv)
2059
2060 =for hackers
2061 Found in file sv.h
2062
2063 =item SvNOK_on
2064
2065 Tells an SV that it is a double.
2066
2067         void    SvNOK_on(SV* sv)
2068
2069 =for hackers
2070 Found in file sv.h
2071
2072 =item SvNOK_only
2073
2074 Tells an SV that it is a double and disables all other OK bits.
2075
2076         void    SvNOK_only(SV* sv)
2077
2078 =for hackers
2079 Found in file sv.h
2080
2081 =item SvNV
2082
2083 Coerce the given SV to a double and return it.
2084
2085         NV      SvNV(SV* sv)
2086
2087 =for hackers
2088 Found in file sv.h
2089
2090 =item SvNVX
2091
2092 Returns the double which is stored in the SV, assuming SvNOK is
2093 true.
2094
2095         NV      SvNVX(SV* sv)
2096
2097 =for hackers
2098 Found in file sv.h
2099
2100 =item SvOK
2101
2102 Returns a boolean indicating whether the value is an SV.
2103
2104         bool    SvOK(SV* sv)
2105
2106 =for hackers
2107 Found in file sv.h
2108
2109 =item SvOOK
2110
2111 Returns a boolean indicating whether the SvIVX is a valid offset value for
2112 the SvPVX.  This hack is used internally to speed up removal of characters
2113 from the beginning of a SvPV.  When SvOOK is true, then the start of the
2114 allocated string buffer is really (SvPVX - SvIVX).
2115
2116         bool    SvOOK(SV* sv)
2117
2118 =for hackers
2119 Found in file sv.h
2120
2121 =item SvPOK
2122
2123 Returns a boolean indicating whether the SV contains a character
2124 string.
2125
2126         bool    SvPOK(SV* sv)
2127
2128 =for hackers
2129 Found in file sv.h
2130
2131 =item SvPOKp
2132
2133 Returns a boolean indicating whether the SV contains a character string.
2134 Checks the B<private> setting.  Use C<SvPOK>.
2135
2136         bool    SvPOKp(SV* sv)
2137
2138 =for hackers
2139 Found in file sv.h
2140
2141 =item SvPOK_off
2142
2143 Unsets the PV status of an SV.
2144
2145         void    SvPOK_off(SV* sv)
2146
2147 =for hackers
2148 Found in file sv.h
2149
2150 =item SvPOK_on
2151
2152 Tells an SV that it is a string.
2153
2154         void    SvPOK_on(SV* sv)
2155
2156 =for hackers
2157 Found in file sv.h
2158
2159 =item SvPOK_only
2160
2161 Tells an SV that it is a string and disables all other OK bits.
2162
2163         void    SvPOK_only(SV* sv)
2164
2165 =for hackers
2166 Found in file sv.h
2167
2168 =item SvPOK_only_UTF8
2169
2170 Tells an SV that it is a UTF8 string (do not use frivolously)
2171 and disables all other OK bits.
2172   
2173         void    SvPOK_only_UTF8(SV* sv)
2174
2175 =for hackers
2176 Found in file sv.h
2177
2178 =item SvPV
2179
2180 Returns a pointer to the string in the SV, or a stringified form of the SV
2181 if the SV does not contain a string.  Handles 'get' magic.
2182
2183         char*   SvPV(SV* sv, STRLEN len)
2184
2185 =for hackers
2186 Found in file sv.h
2187
2188 =item SvPVX
2189
2190 Returns a pointer to the string in the SV.  The SV must contain a
2191 string.
2192
2193         char*   SvPVX(SV* sv)
2194
2195 =for hackers
2196 Found in file sv.h
2197
2198 =item SvPV_force
2199
2200 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
2201 force if you are going to update the SvPVX directly.
2202
2203         char*   SvPV_force(SV* sv, STRLEN len)
2204
2205 =for hackers
2206 Found in file sv.h
2207
2208 =item SvPV_nolen
2209
2210 Returns a pointer to the string in the SV, or a stringified form of the SV
2211 if the SV does not contain a string.  Handles 'get' magic.
2212
2213         char*   SvPV_nolen(SV* sv)
2214
2215 =for hackers
2216 Found in file sv.h
2217
2218 =item SvREFCNT
2219
2220 Returns the value of the object's reference count.
2221
2222         U32     SvREFCNT(SV* sv)
2223
2224 =for hackers
2225 Found in file sv.h
2226
2227 =item SvREFCNT_dec
2228
2229 Decrements the reference count of the given SV.
2230
2231         void    SvREFCNT_dec(SV* sv)
2232
2233 =for hackers
2234 Found in file sv.h
2235
2236 =item SvREFCNT_inc
2237
2238 Increments the reference count of the given SV.
2239
2240         SV*     SvREFCNT_inc(SV* sv)
2241
2242 =for hackers
2243 Found in file sv.h
2244
2245 =item SvROK
2246
2247 Tests if the SV is an RV.
2248
2249         bool    SvROK(SV* sv)
2250
2251 =for hackers
2252 Found in file sv.h
2253
2254 =item SvROK_off
2255
2256 Unsets the RV status of an SV.
2257
2258         void    SvROK_off(SV* sv)
2259
2260 =for hackers
2261 Found in file sv.h
2262
2263 =item SvROK_on
2264
2265 Tells an SV that it is an RV.
2266
2267         void    SvROK_on(SV* sv)
2268
2269 =for hackers
2270 Found in file sv.h
2271
2272 =item SvRV
2273
2274 Dereferences an RV to return the SV.
2275
2276         SV*     SvRV(SV* sv)
2277
2278 =for hackers
2279 Found in file sv.h
2280
2281 =item SvSETMAGIC
2282
2283 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
2284 argument more than once.
2285
2286         void    SvSETMAGIC(SV* sv)
2287
2288 =for hackers
2289 Found in file sv.h
2290
2291 =item SvSetSV
2292
2293 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
2294 more than once.
2295
2296         void    SvSetSV(SV* dsb, SV* ssv)
2297
2298 =for hackers
2299 Found in file sv.h
2300
2301 =item SvSetSV_nosteal
2302
2303 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2304 ssv. May evaluate arguments more than once.
2305
2306         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
2307
2308 =for hackers
2309 Found in file sv.h
2310
2311 =item SvSTASH
2312
2313 Returns the stash of the SV.
2314
2315         HV*     SvSTASH(SV* sv)
2316
2317 =for hackers
2318 Found in file sv.h
2319
2320 =item SvTAINT
2321
2322 Taints an SV if tainting is enabled
2323
2324         void    SvTAINT(SV* sv)
2325
2326 =for hackers
2327 Found in file sv.h
2328
2329 =item SvTAINTED
2330
2331 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2332 not.
2333
2334         bool    SvTAINTED(SV* sv)
2335
2336 =for hackers
2337 Found in file sv.h
2338
2339 =item SvTAINTED_off
2340
2341 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2342 some of Perl's fundamental security features. XS module authors should not
2343 use this function unless they fully understand all the implications of
2344 unconditionally untainting the value. Untainting should be done in the
2345 standard perl fashion, via a carefully crafted regexp, rather than directly
2346 untainting variables.
2347
2348         void    SvTAINTED_off(SV* sv)
2349
2350 =for hackers
2351 Found in file sv.h
2352
2353 =item SvTAINTED_on
2354
2355 Marks an SV as tainted.
2356
2357         void    SvTAINTED_on(SV* sv)
2358
2359 =for hackers
2360 Found in file sv.h
2361
2362 =item SvTRUE
2363
2364 Returns a boolean indicating whether Perl would evaluate the SV as true or
2365 false, defined or undefined.  Does not handle 'get' magic.
2366
2367         bool    SvTRUE(SV* sv)
2368
2369 =for hackers
2370 Found in file sv.h
2371
2372 =item SvTYPE
2373
2374 Returns the type of the SV.  See C<svtype>.
2375
2376         svtype  SvTYPE(SV* sv)
2377
2378 =for hackers
2379 Found in file sv.h
2380
2381 =item svtype
2382
2383 An enum of flags for Perl types.  These are found in the file B<sv.h> 
2384 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
2385
2386 =for hackers
2387 Found in file sv.h
2388
2389 =item SVt_IV
2390
2391 Integer type flag for scalars.  See C<svtype>.
2392
2393 =for hackers
2394 Found in file sv.h
2395
2396 =item SVt_NV
2397
2398 Double type flag for scalars.  See C<svtype>.
2399
2400 =for hackers
2401 Found in file sv.h
2402
2403 =item SVt_PV
2404
2405 Pointer type flag for scalars.  See C<svtype>.
2406
2407 =for hackers
2408 Found in file sv.h
2409
2410 =item SVt_PVAV
2411
2412 Type flag for arrays.  See C<svtype>.
2413
2414 =for hackers
2415 Found in file sv.h
2416
2417 =item SVt_PVCV
2418
2419 Type flag for code refs.  See C<svtype>.
2420
2421 =for hackers
2422 Found in file sv.h
2423
2424 =item SVt_PVHV
2425
2426 Type flag for hashes.  See C<svtype>.
2427
2428 =for hackers
2429 Found in file sv.h
2430
2431 =item SVt_PVMG
2432
2433 Type flag for blessed scalars.  See C<svtype>.
2434
2435 =for hackers
2436 Found in file sv.h
2437
2438 =item SvUOK
2439
2440 Returns a boolean indicating whether the SV contains an unsigned integer.
2441
2442         void    SvUOK(SV* sv)
2443
2444 =for hackers
2445 Found in file sv.h
2446
2447 =item SvUPGRADE
2448
2449 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
2450 perform the upgrade if necessary.  See C<svtype>.
2451
2452         void    SvUPGRADE(SV* sv, svtype type)
2453
2454 =for hackers
2455 Found in file sv.h
2456
2457 =item SvUTF8
2458
2459 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
2460
2461         void    SvUTF8(SV* sv)
2462
2463 =for hackers
2464 Found in file sv.h
2465
2466 =item SvUTF8_off
2467
2468 Unsets the UTF8 status of an SV.
2469
2470         void    SvUTF8_off(SV *sv)
2471
2472 =for hackers
2473 Found in file sv.h
2474
2475 =item SvUTF8_on
2476
2477 Tells an SV that it is a string and encoded in UTF8.  Do not use frivolously.
2478
2479         void    SvUTF8_on(SV *sv)
2480
2481 =for hackers
2482 Found in file sv.h
2483
2484 =item SvUV
2485
2486 Coerces the given SV to an unsigned integer and returns it.
2487
2488         UV      SvUV(SV* sv)
2489
2490 =for hackers
2491 Found in file sv.h
2492
2493 =item SvUVX
2494
2495 Returns the unsigned integer which is stored in the SV, assuming SvIOK is
2496 true.
2497
2498         UV      SvUVX(SV* sv)
2499
2500 =for hackers
2501 Found in file sv.h
2502
2503 =item sv_2mortal
2504
2505 Marks an SV as mortal.  The SV will be destroyed when the current context
2506 ends.
2507
2508         SV*     sv_2mortal(SV* sv)
2509
2510 =for hackers
2511 Found in file sv.c
2512
2513 =item sv_bless
2514
2515 Blesses an SV into a specified package.  The SV must be an RV.  The package
2516 must be designated by its stash (see C<gv_stashpv()>).  The reference count
2517 of the SV is unaffected.
2518
2519         SV*     sv_bless(SV* sv, HV* stash)
2520
2521 =for hackers
2522 Found in file sv.c
2523
2524 =item sv_catpv
2525
2526 Concatenates the string onto the end of the string which is in the SV.
2527 Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
2528
2529         void    sv_catpv(SV* sv, const char* ptr)
2530
2531 =for hackers
2532 Found in file sv.c
2533
2534 =item sv_catpvf
2535
2536 Processes its arguments like C<sprintf> and appends the formatted output
2537 to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
2538 typically be called after calling this function to handle 'set' magic.
2539
2540         void    sv_catpvf(SV* sv, const char* pat, ...)
2541
2542 =for hackers
2543 Found in file sv.c
2544
2545 =item sv_catpvf_mg
2546
2547 Like C<sv_catpvf>, but also handles 'set' magic.
2548
2549         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
2550
2551 =for hackers
2552 Found in file sv.c
2553
2554 =item sv_catpvn
2555
2556 Concatenates the string onto the end of the string which is in the SV.  The
2557 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
2558 'set' magic.  See C<sv_catpvn_mg>.
2559
2560         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
2561
2562 =for hackers
2563 Found in file sv.c
2564
2565 =item sv_catpvn_mg
2566
2567 Like C<sv_catpvn>, but also handles 'set' magic.
2568
2569         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
2570
2571 =for hackers
2572 Found in file sv.c
2573
2574 =item sv_catpv_mg
2575
2576 Like C<sv_catpv>, but also handles 'set' magic.
2577
2578         void    sv_catpv_mg(SV *sv, const char *ptr)
2579
2580 =for hackers
2581 Found in file sv.c
2582
2583 =item sv_catsv
2584
2585 Concatenates the string from SV C<ssv> onto the end of the string in SV
2586 C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
2587
2588         void    sv_catsv(SV* dsv, SV* ssv)
2589
2590 =for hackers
2591 Found in file sv.c
2592
2593 =item sv_catsv_mg
2594
2595 Like C<sv_catsv>, but also handles 'set' magic.
2596
2597         void    sv_catsv_mg(SV *dstr, SV *sstr)
2598
2599 =for hackers
2600 Found in file sv.c
2601
2602 =item sv_chop
2603
2604 Efficient removal of characters from the beginning of the string buffer.
2605 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
2606 the string buffer.  The C<ptr> becomes the first character of the adjusted
2607 string.
2608
2609         void    sv_chop(SV* sv, char* ptr)
2610
2611 =for hackers
2612 Found in file sv.c
2613
2614 =item sv_clear
2615
2616 Clear an SV, making it empty. Does not free the memory used by the SV
2617 itself.
2618
2619         void    sv_clear(SV* sv)
2620
2621 =for hackers
2622 Found in file sv.c
2623
2624 =item sv_cmp
2625
2626 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
2627 string in C<sv1> is less than, equal to, or greater than the string in
2628 C<sv2>.
2629
2630         I32     sv_cmp(SV* sv1, SV* sv2)
2631
2632 =for hackers
2633 Found in file sv.c
2634
2635 =item sv_cmp_locale
2636
2637 Compares the strings in two SVs in a locale-aware manner. See
2638 L</sv_cmp_locale>
2639
2640         I32     sv_cmp_locale(SV* sv1, SV* sv2)
2641
2642 =for hackers
2643 Found in file sv.c
2644
2645 =item sv_dec
2646
2647 Auto-decrement of the value in the SV.
2648
2649         void    sv_dec(SV* sv)
2650
2651 =for hackers
2652 Found in file sv.c
2653
2654 =item sv_derived_from
2655
2656 Returns a boolean indicating whether the SV is derived from the specified
2657 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
2658 for class names as well as for objects.
2659
2660         bool    sv_derived_from(SV* sv, const char* name)
2661
2662 =for hackers
2663 Found in file universal.c
2664
2665 =item sv_eq
2666
2667 Returns a boolean indicating whether the strings in the two SVs are
2668 identical.
2669
2670         I32     sv_eq(SV* sv1, SV* sv2)
2671
2672 =for hackers
2673 Found in file sv.c
2674
2675 =item sv_free
2676
2677 Free the memory used by an SV.
2678
2679         void    sv_free(SV* sv)
2680
2681 =for hackers
2682 Found in file sv.c
2683
2684 =item sv_gets
2685
2686 Get a line from the filehandle and store it into the SV, optionally
2687 appending to the currently-stored string.
2688
2689         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
2690
2691 =for hackers
2692 Found in file sv.c
2693
2694 =item sv_grow
2695
2696 Expands the character buffer in the SV.  This will use C<sv_unref> and will
2697 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
2698 Use C<SvGROW>.
2699
2700         char*   sv_grow(SV* sv, STRLEN newlen)
2701
2702 =for hackers
2703 Found in file sv.c
2704
2705 =item sv_inc
2706
2707 Auto-increment of the value in the SV.
2708
2709         void    sv_inc(SV* sv)
2710
2711 =for hackers
2712 Found in file sv.c
2713
2714 =item sv_insert
2715
2716 Inserts a string at the specified offset/length within the SV. Similar to
2717 the Perl substr() function.
2718
2719         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2720
2721 =for hackers
2722 Found in file sv.c
2723
2724 =item sv_isa
2725
2726 Returns a boolean indicating whether the SV is blessed into the specified
2727 class.  This does not check for subtypes; use C<sv_derived_from> to verify
2728 an inheritance relationship.
2729
2730         int     sv_isa(SV* sv, const char* name)
2731
2732 =for hackers
2733 Found in file sv.c
2734
2735 =item sv_isobject
2736
2737 Returns a boolean indicating whether the SV is an RV pointing to a blessed
2738 object.  If the SV is not an RV, or if the object is not blessed, then this
2739 will return false.
2740
2741         int     sv_isobject(SV* sv)
2742
2743 =for hackers
2744 Found in file sv.c
2745
2746 =item sv_len
2747
2748 Returns the length of the string in the SV.  See also C<SvCUR>.
2749
2750         STRLEN  sv_len(SV* sv)
2751
2752 =for hackers
2753 Found in file sv.c
2754
2755 =item sv_len_utf8
2756
2757 Returns the number of characters in the string in an SV, counting wide
2758 UTF8 bytes as a single character.
2759
2760         STRLEN  sv_len_utf8(SV* sv)
2761
2762 =for hackers
2763 Found in file sv.c
2764
2765 =item sv_magic
2766
2767 Adds magic to an SV.
2768
2769         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2770
2771 =for hackers
2772 Found in file sv.c
2773
2774 =item sv_mortalcopy
2775
2776 Creates a new SV which is a copy of the original SV.  The new SV is marked
2777 as mortal.
2778
2779         SV*     sv_mortalcopy(SV* oldsv)
2780
2781 =for hackers
2782 Found in file sv.c
2783
2784 =item sv_newmortal
2785
2786 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
2787
2788         SV*     sv_newmortal()
2789
2790 =for hackers
2791 Found in file sv.c
2792
2793 =item sv_pvn_force
2794
2795 Get a sensible string out of the SV somehow.
2796
2797         char*   sv_pvn_force(SV* sv, STRLEN* lp)
2798
2799 =for hackers
2800 Found in file sv.c
2801
2802 =item sv_pvutf8n_force
2803
2804 Get a sensible UTF8-encoded string out of the SV somehow. See
2805 L</sv_pvn_force>.
2806
2807         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
2808
2809 =for hackers
2810 Found in file sv.c
2811
2812 =item sv_reftype
2813
2814 Returns a string describing what the SV is a reference to.
2815
2816         char*   sv_reftype(SV* sv, int ob)
2817
2818 =for hackers
2819 Found in file sv.c
2820
2821 =item sv_replace
2822
2823 Make the first argument a copy of the second, then delete the original.
2824
2825         void    sv_replace(SV* sv, SV* nsv)
2826
2827 =for hackers
2828 Found in file sv.c
2829
2830 =item sv_rvweaken
2831
2832 Weaken a reference.
2833
2834         SV*     sv_rvweaken(SV *sv)
2835
2836 =for hackers
2837 Found in file sv.c
2838
2839 =item sv_setiv
2840
2841 Copies an integer into the given SV.  Does not handle 'set' magic.  See
2842 C<sv_setiv_mg>.
2843
2844         void    sv_setiv(SV* sv, IV num)
2845
2846 =for hackers
2847 Found in file sv.c
2848
2849 =item sv_setiv_mg
2850
2851 Like C<sv_setiv>, but also handles 'set' magic.
2852
2853         void    sv_setiv_mg(SV *sv, IV i)
2854
2855 =for hackers
2856 Found in file sv.c
2857
2858 =item sv_setnv
2859
2860 Copies a double into the given SV.  Does not handle 'set' magic.  See
2861 C<sv_setnv_mg>.
2862
2863         void    sv_setnv(SV* sv, NV num)
2864
2865 =for hackers
2866 Found in file sv.c
2867
2868 =item sv_setnv_mg
2869
2870 Like C<sv_setnv>, but also handles 'set' magic.
2871
2872         void    sv_setnv_mg(SV *sv, NV num)
2873
2874 =for hackers
2875 Found in file sv.c
2876
2877 =item sv_setpv
2878
2879 Copies a string into an SV.  The string must be null-terminated.  Does not
2880 handle 'set' magic.  See C<sv_setpv_mg>.
2881
2882         void    sv_setpv(SV* sv, const char* ptr)
2883
2884 =for hackers
2885 Found in file sv.c
2886
2887 =item sv_setpvf
2888
2889 Processes its arguments like C<sprintf> and sets an SV to the formatted
2890 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
2891
2892         void    sv_setpvf(SV* sv, const char* pat, ...)
2893
2894 =for hackers
2895 Found in file sv.c
2896
2897 =item sv_setpvf_mg
2898
2899 Like C<sv_setpvf>, but also handles 'set' magic.
2900
2901         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
2902
2903 =for hackers
2904 Found in file sv.c
2905
2906 =item sv_setpviv
2907
2908 Copies an integer into the given SV, also updating its string value.
2909 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
2910
2911         void    sv_setpviv(SV* sv, IV num)
2912
2913 =for hackers
2914 Found in file sv.c
2915
2916 =item sv_setpviv_mg
2917
2918 Like C<sv_setpviv>, but also handles 'set' magic.
2919
2920         void    sv_setpviv_mg(SV *sv, IV iv)
2921
2922 =for hackers
2923 Found in file sv.c
2924
2925 =item sv_setpvn
2926
2927 Copies a string into an SV.  The C<len> parameter indicates the number of
2928 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
2929
2930         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2931
2932 =for hackers
2933 Found in file sv.c
2934
2935 =item sv_setpvn_mg
2936
2937 Like C<sv_setpvn>, but also handles 'set' magic.
2938
2939         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2940
2941 =for hackers
2942 Found in file sv.c
2943
2944 =item sv_setpv_mg
2945
2946 Like C<sv_setpv>, but also handles 'set' magic.
2947
2948         void    sv_setpv_mg(SV *sv, const char *ptr)
2949
2950 =for hackers
2951 Found in file sv.c
2952
2953 =item sv_setref_iv
2954
2955 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
2956 argument will be upgraded to an RV.  That RV will be modified to point to
2957 the new SV.  The C<classname> argument indicates the package for the
2958 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2959 will be returned and will have a reference count of 1.
2960
2961         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
2962
2963 =for hackers
2964 Found in file sv.c
2965
2966 =item sv_setref_nv
2967
2968 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
2969 argument will be upgraded to an RV.  That RV will be modified to point to
2970 the new SV.  The C<classname> argument indicates the package for the
2971 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2972 will be returned and will have a reference count of 1.
2973
2974         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
2975
2976 =for hackers
2977 Found in file sv.c
2978
2979 =item sv_setref_pv
2980
2981 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
2982 argument will be upgraded to an RV.  That RV will be modified to point to
2983 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2984 into the SV.  The C<classname> argument indicates the package for the
2985 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2986 will be returned and will have a reference count of 1.
2987
2988 Do not use with other Perl types such as HV, AV, SV, CV, because those
2989 objects will become corrupted by the pointer copy process.
2990
2991 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2992
2993         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
2994
2995 =for hackers
2996 Found in file sv.c
2997
2998 =item sv_setref_pvn
2999
3000 Copies a string into a new SV, optionally blessing the SV.  The length of the
3001 string must be specified with C<n>.  The C<rv> argument will be upgraded to
3002 an RV.  That RV will be modified to point to the new SV.  The C<classname>
3003 argument indicates the package for the blessing.  Set C<classname> to
3004 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
3005 a reference count of 1.
3006
3007 Note that C<sv_setref_pv> copies the pointer while this copies the string.
3008
3009         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
3010
3011 =for hackers
3012 Found in file sv.c
3013
3014 =item sv_setsv
3015
3016 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
3017 The source SV may be destroyed if it is mortal.  Does not handle 'set'
3018 magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
3019 C<sv_setsv_mg>.
3020
3021         void    sv_setsv(SV* dsv, SV* ssv)
3022
3023 =for hackers
3024 Found in file sv.c
3025
3026 =item sv_setsv_mg
3027
3028 Like C<sv_setsv>, but also handles 'set' magic.
3029
3030         void    sv_setsv_mg(SV *dstr, SV *sstr)
3031
3032 =for hackers
3033 Found in file sv.c
3034
3035 =item sv_setuv
3036
3037 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
3038 See C<sv_setuv_mg>.
3039
3040         void    sv_setuv(SV* sv, UV num)
3041
3042 =for hackers
3043 Found in file sv.c
3044
3045 =item sv_setuv_mg
3046
3047 Like C<sv_setuv>, but also handles 'set' magic.
3048
3049         void    sv_setuv_mg(SV *sv, UV u)
3050
3051 =for hackers
3052 Found in file sv.c
3053
3054 =item sv_true
3055
3056 Returns true if the SV has a true value by Perl's rules.
3057
3058         I32     sv_true(SV *sv)
3059
3060 =for hackers
3061 Found in file sv.c
3062
3063 =item sv_unmagic
3064
3065 Removes magic from an SV.
3066
3067         int     sv_unmagic(SV* sv, int type)
3068
3069 =for hackers
3070 Found in file sv.c
3071
3072 =item sv_unref
3073
3074 Unsets the RV status of the SV, and decrements the reference count of
3075 whatever was being referenced by the RV.  This can almost be thought of
3076 as a reversal of C<newSVrv>.  This is C<sv_unref_flags> with the C<flag>
3077 being zero.  See C<SvROK_off>.
3078
3079         void    sv_unref(SV* sv)
3080
3081 =for hackers
3082 Found in file sv.c
3083
3084 =item sv_unref_flags
3085
3086 Unsets the RV status of the SV, and decrements the reference count of
3087 whatever was being referenced by the RV.  This can almost be thought of
3088 as a reversal of C<newSVrv>.  The C<cflags> argument can contain
3089 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
3090 (otherwise the decrementing is conditional on the reference count being
3091 different from one or the reference being a readonly SV).
3092 See C<SvROK_off>.
3093
3094         void    sv_unref_flags(SV* sv, U32 flags)
3095
3096 =for hackers
3097 Found in file sv.c
3098
3099 =item sv_upgrade
3100
3101 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
3102 C<svtype>.
3103
3104         bool    sv_upgrade(SV* sv, U32 mt)
3105
3106 =for hackers
3107 Found in file sv.c
3108
3109 =item sv_usepvn
3110
3111 Tells an SV to use C<ptr> to find its string value.  Normally the string is
3112 stored inside the SV but sv_usepvn allows the SV to use an outside string.
3113 The C<ptr> should point to memory that was allocated by C<malloc>.  The
3114 string length, C<len>, must be supplied.  This function will realloc the
3115 memory pointed to by C<ptr>, so that pointer should not be freed or used by
3116 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
3117 See C<sv_usepvn_mg>.
3118
3119         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
3120
3121 =for hackers
3122 Found in file sv.c
3123
3124 =item sv_usepvn_mg
3125
3126 Like C<sv_usepvn>, but also handles 'set' magic.
3127
3128         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3129
3130 =for hackers
3131 Found in file sv.c
3132
3133 =item sv_utf8_downgrade
3134
3135 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3136 This may not be possible if the PV contains non-byte encoding characters;
3137 if this is the case, either returns false or, if C<fail_ok> is not
3138 true, croaks.
3139
3140 NOTE: this function is experimental and may change or be
3141 removed without notice.
3142
3143         bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
3144
3145 =for hackers
3146 Found in file sv.c
3147
3148 =item sv_utf8_encode
3149
3150 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
3151 flag so that it looks like bytes again. Nothing calls this.
3152
3153 NOTE: this function is experimental and may change or be
3154 removed without notice.
3155
3156         void    sv_utf8_encode(SV *sv)
3157
3158 =for hackers
3159 Found in file sv.c
3160
3161 =item sv_utf8_upgrade
3162
3163 Convert the PV of an SV to its UTF8-encoded form.
3164
3165         void    sv_utf8_upgrade(SV *sv)
3166
3167 =for hackers
3168 Found in file sv.c
3169
3170 =item sv_vcatpvfn
3171
3172 Processes its arguments like C<vsprintf> and appends the formatted output
3173 to an SV.  Uses an array of SVs if the C style variable argument list is
3174 missing (NULL).  When running with taint checks enabled, indicates via
3175 C<maybe_tainted> if results are untrustworthy (often due to the use of
3176 locales).
3177
3178         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3179
3180 =for hackers
3181 Found in file sv.c
3182
3183 =item sv_vsetpvfn
3184
3185 Works like C<vcatpvfn> but copies the text into the SV instead of
3186 appending it.
3187
3188         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3189
3190 =for hackers
3191 Found in file sv.c
3192
3193 =item THIS
3194
3195 Variable which is setup by C<xsubpp> to designate the object in a C++ 
3196 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
3197 L<perlxs/"Using XS With C++">.
3198
3199         (whatever)      THIS
3200
3201 =for hackers
3202 Found in file XSUB.h
3203
3204 =item toLOWER
3205
3206 Converts the specified character to lowercase.
3207
3208         char    toLOWER(char ch)
3209
3210 =for hackers
3211 Found in file handy.h
3212
3213 =item toUPPER
3214
3215 Converts the specified character to uppercase.
3216
3217         char    toUPPER(char ch)
3218
3219 =for hackers
3220 Found in file handy.h
3221
3222 =item U8 *s
3223
3224 Returns true if first C<len> bytes of the given string form valid a UTF8
3225 string, false otherwise.
3226
3227         is_utf8_string  U8 *s(STRLEN len)
3228
3229 =for hackers
3230 Found in file utf8.c
3231
3232 =item utf8_distance
3233
3234 Returns the number of UTF8 characters between the UTF-8 pointers C<a>
3235 and C<b>.
3236
3237 WARNING: use only if you *know* that the pointers point inside the
3238 same UTF-8 buffer.
3239
3240         IV      utf8_distance(U8 *a, U8 *b)
3241
3242 =for hackers
3243 Found in file utf8.c
3244
3245 =item utf8_hop
3246
3247 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
3248 forward or backward.
3249
3250 WARNING: do not use the following unless you *know* C<off> is within
3251 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
3252 on the first byte of character or just after the last byte of a character.
3253
3254         U8*     utf8_hop(U8 *s, I32 off)
3255
3256 =for hackers
3257 Found in file utf8.c
3258
3259 =item utf8_length
3260
3261 Return the length of the UTF-8 char encoded string C<s> in characters.
3262 Stops at C<e> (inclusive).  If C<e E<lt> s> or if the scan would end
3263 up past C<e>, croaks.
3264
3265         STRLEN  utf8_length(U8* s, U8 *e)
3266
3267 =for hackers
3268 Found in file utf8.c
3269
3270 =item utf8_to_bytes
3271
3272 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
3273 Unlike C<bytes_to_utf8>, this over-writes the original string, and
3274 updates len to contain the new length.
3275 Returns zero on failure, setting C<len> to -1.
3276
3277         U8 *    utf8_to_bytes(U8 *s, STRLEN *len)
3278
3279 =for hackers
3280 Found in file utf8.c
3281
3282 =item utf8_to_uv
3283
3284 Returns the character value of the first character in the string C<s>
3285 which is assumed to be in UTF8 encoding and no longer than C<curlen>;
3286 C<retlen> will be set to the length, in bytes, of that character,
3287 and the pointer C<s> will be advanced to the end of the character.
3288
3289 If C<s> does not point to a well-formed UTF8 character, the behaviour
3290 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
3291 it is assumed that the caller will raise a warning, and this function
3292 will silently just set C<retlen> to C<-1> and return zero.  If the
3293 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
3294 malformations will be given, C<retlen> will be set to the expected
3295 length of the UTF-8 character in bytes, and zero will be returned.
3296
3297 The C<flags> can also contain various flags to allow deviations from
3298 the strict UTF-8 encoding (see F<utf8.h>).
3299
3300         U8* s   utf8_to_uv(STRLEN curlen, STRLEN *retlen, U32 flags)
3301
3302 =for hackers
3303 Found in file utf8.c
3304
3305 =item utf8_to_uv_simple
3306
3307 Returns the character value of the first character in the string C<s>
3308 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
3309 length, in bytes, of that character, and the pointer C<s> will be
3310 advanced to the end of the character.
3311
3312 If C<s> does not point to a well-formed UTF8 character, zero is
3313 returned and retlen is set, if possible, to -1.
3314
3315         U8* s   utf8_to_uv_simple(STRLEN *retlen)
3316
3317 =for hackers
3318 Found in file utf8.c
3319
3320 =item warn
3321
3322 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
3323 function the same way you use the C C<printf> function.  See
3324 C<croak>.
3325
3326         void    warn(const char* pat, ...)
3327
3328 =for hackers
3329 Found in file util.c
3330
3331 =item XPUSHi
3332
3333 Push an integer onto the stack, extending the stack if necessary.  Handles
3334 'set' magic. See C<PUSHi>.
3335
3336         void    XPUSHi(IV iv)
3337
3338 =for hackers
3339 Found in file pp.h
3340
3341 =item XPUSHn
3342
3343 Push a double onto the stack, extending the stack if necessary.  Handles
3344 'set' magic.  See C<PUSHn>.
3345
3346         void    XPUSHn(NV nv)
3347
3348 =for hackers
3349 Found in file pp.h
3350
3351 =item XPUSHp
3352
3353 Push a string onto the stack, extending the stack if necessary.  The C<len>
3354 indicates the length of the string.  Handles 'set' magic.  See
3355 C<PUSHp>.
3356
3357         void    XPUSHp(char* str, STRLEN len)
3358
3359 =for hackers
3360 Found in file pp.h
3361
3362 =item XPUSHs
3363
3364 Push an SV onto the stack, extending the stack if necessary.  Does not
3365 handle 'set' magic.  See C<PUSHs>.
3366
3367         void    XPUSHs(SV* sv)
3368
3369 =for hackers
3370 Found in file pp.h
3371
3372 =item XPUSHu
3373
3374 Push an unsigned integer onto the stack, extending the stack if necessary.
3375 See C<PUSHu>.
3376
3377         void    XPUSHu(UV uv)
3378
3379 =for hackers
3380 Found in file pp.h
3381
3382 =item XS
3383
3384 Macro to declare an XSUB and its C parameter list.  This is handled by
3385 C<xsubpp>.
3386
3387 =for hackers
3388 Found in file XSUB.h
3389
3390 =item XSRETURN
3391
3392 Return from XSUB, indicating number of items on the stack.  This is usually
3393 handled by C<xsubpp>.
3394
3395         void    XSRETURN(int nitems)
3396
3397 =for hackers
3398 Found in file XSUB.h
3399
3400 =item XSRETURN_EMPTY
3401
3402 Return an empty list from an XSUB immediately.
3403
3404                 XSRETURN_EMPTY;
3405
3406 =for hackers
3407 Found in file XSUB.h
3408
3409 =item XSRETURN_IV
3410
3411 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3412
3413         void    XSRETURN_IV(IV iv)
3414
3415 =for hackers
3416 Found in file XSUB.h
3417
3418 =item XSRETURN_NO
3419
3420 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3421
3422                 XSRETURN_NO;
3423
3424 =for hackers
3425 Found in file XSUB.h
3426
3427 =item XSRETURN_NV
3428
3429 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
3430
3431         void    XSRETURN_NV(NV nv)
3432
3433 =for hackers
3434 Found in file XSUB.h
3435
3436 =item XSRETURN_PV
3437
3438 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3439
3440         void    XSRETURN_PV(char* str)
3441
3442 =for hackers
3443 Found in file XSUB.h
3444
3445 =item XSRETURN_UNDEF
3446
3447 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3448
3449                 XSRETURN_UNDEF;
3450
3451 =for hackers
3452 Found in file XSUB.h
3453
3454 =item XSRETURN_YES
3455
3456 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3457
3458                 XSRETURN_YES;
3459
3460 =for hackers
3461 Found in file XSUB.h
3462
3463 =item XST_mIV
3464
3465 Place an integer into the specified position C<pos> on the stack.  The
3466 value is stored in a new mortal SV.
3467
3468         void    XST_mIV(int pos, IV iv)
3469
3470 =for hackers
3471 Found in file XSUB.h
3472
3473 =item XST_mNO
3474
3475 Place C<&PL_sv_no> into the specified position C<pos> on the
3476 stack.
3477
3478         void    XST_mNO(int pos)
3479
3480 =for hackers
3481 Found in file XSUB.h
3482
3483 =item XST_mNV
3484
3485 Place a double into the specified position C<pos> on the stack.  The value
3486 is stored in a new mortal SV.
3487
3488         void    XST_mNV(int pos, NV nv)
3489
3490 =for hackers
3491 Found in file XSUB.h
3492
3493 =item XST_mPV
3494
3495 Place a copy of a string into the specified position C<pos> on the stack. 
3496 The value is stored in a new mortal SV.
3497
3498         void    XST_mPV(int pos, char* str)
3499
3500 =for hackers
3501 Found in file XSUB.h
3502
3503 =item XST_mUNDEF
3504
3505 Place C<&PL_sv_undef> into the specified position C<pos> on the
3506 stack.
3507
3508         void    XST_mUNDEF(int pos)
3509
3510 =for hackers
3511 Found in file XSUB.h
3512
3513 =item XST_mYES
3514
3515 Place C<&PL_sv_yes> into the specified position C<pos> on the
3516 stack.
3517
3518         void    XST_mYES(int pos)
3519
3520 =for hackers
3521 Found in file XSUB.h
3522
3523 =item XS_VERSION
3524
3525 The version identifier for an XS module.  This is usually
3526 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
3527
3528 =for hackers
3529 Found in file XSUB.h
3530
3531 =item XS_VERSION_BOOTCHECK
3532
3533 Macro to verify that a PM module's $VERSION variable matches the XS
3534 module's C<XS_VERSION> variable.  This is usually handled automatically by
3535 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
3536
3537                 XS_VERSION_BOOTCHECK;
3538
3539 =for hackers
3540 Found in file XSUB.h
3541
3542 =item Zero
3543
3544 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
3545 destination, C<nitems> is the number of items, and C<type> is the type.
3546
3547         void    Zero(void* dest, int nitems, type)
3548
3549 =for hackers
3550 Found in file handy.h
3551
3552 =back
3553
3554 =head1 AUTHORS
3555
3556 Until May 1997, this document was maintained by Jeff Okamoto
3557 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
3558
3559 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3560 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3561 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3562 Stephen McCamant, and Gurusamy Sarathy.
3563
3564 API Listing originally by Dean Roehrich <roehrich@cray.com>.
3565
3566 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3567
3568 =head1 SEE ALSO
3569
3570 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3571