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