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