Minor doc patch: handy.h
[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 array 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 array 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 newSVrv
1266
1267 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
1268 it will be upgraded to one.  If C<classname> is non-null then the new SV will
1269 be blessed in the specified package.  The new SV is returned and its
1270 reference count is 1.
1271
1272         SV*     newSVrv(SV* rv, const char* classname)
1273
1274 =for hackers
1275 Found in file sv.c
1276
1277 =item newSVsv
1278
1279 Creates a new SV which is an exact duplicate of the original SV.
1280
1281         SV*     newSVsv(SV* old)
1282
1283 =for hackers
1284 Found in file sv.c
1285
1286 =item newSVuv
1287
1288 Creates a new SV and copies an unsigned integer into it.
1289 The reference count for the SV is set to 1.
1290
1291         SV*     newSVuv(UV u)
1292
1293 =for hackers
1294 Found in file sv.c
1295
1296 =item newXS
1297
1298 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1299
1300 =for hackers
1301 Found in file op.c
1302
1303 =item newXSproto
1304
1305 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
1306 the subs.
1307
1308 =for hackers
1309 Found in file XSUB.h
1310
1311 =item Newz
1312
1313 The XSUB-writer's interface to the C C<malloc> function.  The allocated
1314 memory is zeroed with C<memzero>.
1315
1316         void    Newz(int id, void* ptr, int nitems, type)
1317
1318 =for hackers
1319 Found in file handy.h
1320
1321 =item Nullav
1322
1323 Null AV pointer.
1324
1325 =for hackers
1326 Found in file av.h
1327
1328 =item Nullch
1329
1330 Null character pointer.
1331
1332 =for hackers
1333 Found in file handy.h
1334
1335 =item Nullcv
1336
1337 Null CV pointer.
1338
1339 =for hackers
1340 Found in file cv.h
1341
1342 =item Nullhv
1343
1344 Null HV pointer.
1345
1346 =for hackers
1347 Found in file hv.h
1348
1349 =item Nullsv
1350
1351 Null SV pointer.
1352
1353 =for hackers
1354 Found in file handy.h
1355
1356 =item ORIGMARK
1357
1358 The original stack mark for the XSUB.  See C<dORIGMARK>.
1359
1360 =for hackers
1361 Found in file pp.h
1362
1363 =item perl_alloc
1364
1365 Allocates a new Perl interpreter.  See L<perlembed>.
1366
1367         PerlInterpreter*        perl_alloc()
1368
1369 =for hackers
1370 Found in file perl.c
1371
1372 =item perl_construct
1373
1374 Initializes a new Perl interpreter.  See L<perlembed>.
1375
1376         void    perl_construct(PerlInterpreter* interp)
1377
1378 =for hackers
1379 Found in file perl.c
1380
1381 =item perl_destruct
1382
1383 Shuts down a Perl interpreter.  See L<perlembed>.
1384
1385         void    perl_destruct(PerlInterpreter* interp)
1386
1387 =for hackers
1388 Found in file perl.c
1389
1390 =item perl_free
1391
1392 Releases a Perl interpreter.  See L<perlembed>.
1393
1394         void    perl_free(PerlInterpreter* interp)
1395
1396 =for hackers
1397 Found in file perl.c
1398
1399 =item perl_parse
1400
1401 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
1402
1403         int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1404
1405 =for hackers
1406 Found in file perl.c
1407
1408 =item perl_run
1409
1410 Tells a Perl interpreter to run.  See L<perlembed>.
1411
1412         int     perl_run(PerlInterpreter* interp)
1413
1414 =for hackers
1415 Found in file perl.c
1416
1417 =item PL_DBsingle
1418
1419 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1420 boolean which indicates whether subs are being single-stepped. 
1421 Single-stepping is automatically turned on after every step.  This is the C
1422 variable which corresponds to Perl's $DB::single variable.  See
1423 C<PL_DBsub>.
1424
1425         SV *    PL_DBsingle
1426
1427 =for hackers
1428 Found in file intrpvar.h
1429
1430 =item PL_DBsub
1431
1432 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
1433 the SV which holds the name of the sub being debugged.  This is the C
1434 variable which corresponds to Perl's $DB::sub variable.  See
1435 C<PL_DBsingle>.
1436
1437         GV *    PL_DBsub
1438
1439 =for hackers
1440 Found in file intrpvar.h
1441
1442 =item PL_DBtrace
1443
1444 Trace variable used when Perl is run in debugging mode, with the B<-d>
1445 switch.  This is the C variable which corresponds to Perl's $DB::trace
1446 variable.  See C<PL_DBsingle>.
1447
1448         SV *    PL_DBtrace
1449
1450 =for hackers
1451 Found in file intrpvar.h
1452
1453 =item PL_dowarn
1454
1455 The C variable which corresponds to Perl's $^W warning variable.
1456
1457         bool    PL_dowarn
1458
1459 =for hackers
1460 Found in file intrpvar.h
1461
1462 =item PL_modglobal
1463
1464 C<PL_modglobal> is a general purpose, interpreter global HV for use by 
1465 extensions that need to keep information on a per-interpreter basis.
1466 In a pinch, it can also be used as a symbol table for extensions 
1467 to share data among each other.  It is a good idea to use keys 
1468 prefixed by the package name of the extension that owns the data.
1469
1470         HV*     PL_modglobal
1471
1472 =for hackers
1473 Found in file intrpvar.h
1474
1475 =item PL_na
1476
1477 A convenience variable which is typically used with C<SvPV> when one
1478 doesn't care about the length of the string.  It is usually more efficient
1479 to either declare a local variable and use that instead or to use the
1480 C<SvPV_nolen> macro.
1481
1482         STRLEN  PL_na
1483
1484 =for hackers
1485 Found in file thrdvar.h
1486
1487 =item PL_sv_no
1488
1489 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
1490 C<&PL_sv_no>.
1491
1492         SV      PL_sv_no
1493
1494 =for hackers
1495 Found in file intrpvar.h
1496
1497 =item PL_sv_undef
1498
1499 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
1500
1501         SV      PL_sv_undef
1502
1503 =for hackers
1504 Found in file intrpvar.h
1505
1506 =item PL_sv_yes
1507
1508 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
1509 C<&PL_sv_yes>.
1510
1511         SV      PL_sv_yes
1512
1513 =for hackers
1514 Found in file intrpvar.h
1515
1516 =item POPi
1517
1518 Pops an integer off the stack.
1519
1520         IV      POPi
1521
1522 =for hackers
1523 Found in file pp.h
1524
1525 =item POPl
1526
1527 Pops a long off the stack.
1528
1529         long    POPl
1530
1531 =for hackers
1532 Found in file pp.h
1533
1534 =item POPn
1535
1536 Pops a double off the stack.
1537
1538         NV      POPn
1539
1540 =for hackers
1541 Found in file pp.h
1542
1543 =item POPp
1544
1545 Pops a string off the stack.
1546
1547         char*   POPp
1548
1549 =for hackers
1550 Found in file pp.h
1551
1552 =item POPs
1553
1554 Pops an SV off the stack.
1555
1556         SV*     POPs
1557
1558 =for hackers
1559 Found in file pp.h
1560
1561 =item PUSHi
1562
1563 Push an integer onto the stack.  The stack must have room for this element.
1564 Handles 'set' magic.  See C<XPUSHi>.
1565
1566         void    PUSHi(IV iv)
1567
1568 =for hackers
1569 Found in file pp.h
1570
1571 =item PUSHMARK
1572
1573 Opening bracket for arguments on a callback.  See C<PUTBACK> and
1574 L<perlcall>.
1575
1576                 PUSHMARK;
1577
1578 =for hackers
1579 Found in file pp.h
1580
1581 =item PUSHn
1582
1583 Push a double onto the stack.  The stack must have room for this element.
1584 Handles 'set' magic.  See C<XPUSHn>.
1585
1586         void    PUSHn(NV nv)
1587
1588 =for hackers
1589 Found in file pp.h
1590
1591 =item PUSHp
1592
1593 Push a string onto the stack.  The stack must have room for this element.
1594 The C<len> indicates the length of the string.  Handles 'set' magic.  See
1595 C<XPUSHp>.
1596
1597         void    PUSHp(char* str, STRLEN len)
1598
1599 =for hackers
1600 Found in file pp.h
1601
1602 =item PUSHs
1603
1604 Push an SV onto the stack.  The stack must have room for this element. 
1605 Does not handle 'set' magic.  See C<XPUSHs>.
1606
1607         void    PUSHs(SV* sv)
1608
1609 =for hackers
1610 Found in file pp.h
1611
1612 =item PUSHu
1613
1614 Push an unsigned integer onto the stack.  The stack must have room for this
1615 element.  See C<XPUSHu>.
1616
1617         void    PUSHu(UV uv)
1618
1619 =for hackers
1620 Found in file pp.h
1621
1622 =item PUTBACK
1623
1624 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
1625 See C<PUSHMARK> and L<perlcall> for other uses.
1626
1627                 PUTBACK;
1628
1629 =for hackers
1630 Found in file pp.h
1631
1632 =item Renew
1633
1634 The XSUB-writer's interface to the C C<realloc> function.
1635
1636         void    Renew(void* ptr, int nitems, type)
1637
1638 =for hackers
1639 Found in file handy.h
1640
1641 =item Renewc
1642
1643 The XSUB-writer's interface to the C C<realloc> function, with
1644 cast.
1645
1646         void    Renewc(void* ptr, int nitems, type, cast)
1647
1648 =for hackers
1649 Found in file handy.h
1650
1651 =item require_pv
1652
1653 Tells Perl to C<require> a module.
1654
1655 NOTE: the perl_ form of this function is deprecated.
1656
1657         void    require_pv(const char* pv)
1658
1659 =for hackers
1660 Found in file perl.c
1661
1662 =item RETVAL
1663
1664 Variable which is setup by C<xsubpp> to hold the return value for an 
1665 XSUB. This is always the proper type for the XSUB. See 
1666 L<perlxs/"The RETVAL Variable">.
1667
1668         (whatever)      RETVAL
1669
1670 =for hackers
1671 Found in file XSUB.h
1672
1673 =item Safefree
1674
1675 The XSUB-writer's interface to the C C<free> function.
1676
1677         void    Safefree(void* ptr)
1678
1679 =for hackers
1680 Found in file handy.h
1681
1682 =item savepv
1683
1684 Copy a string to a safe spot.  This does not use an SV.
1685
1686         char*   savepv(const char* sv)
1687
1688 =for hackers
1689 Found in file util.c
1690
1691 =item savepvn
1692
1693 Copy a string to a safe spot.  The C<len> indicates number of bytes to
1694 copy.  This does not use an SV.
1695
1696         char*   savepvn(const char* sv, I32 len)
1697
1698 =for hackers
1699 Found in file util.c
1700
1701 =item SAVETMPS
1702
1703 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
1704 L<perlcall>.
1705
1706                 SAVETMPS;
1707
1708 =for hackers
1709 Found in file scope.h
1710
1711 =item SP
1712
1713 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
1714 C<SPAGAIN>.
1715
1716 =for hackers
1717 Found in file pp.h
1718
1719 =item SPAGAIN
1720
1721 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
1722
1723                 SPAGAIN;
1724
1725 =for hackers
1726 Found in file pp.h
1727
1728 =item ST
1729
1730 Used to access elements on the XSUB's stack.
1731
1732         SV*     ST(int ix)
1733
1734 =for hackers
1735 Found in file XSUB.h
1736
1737 =item strEQ
1738
1739 Test two strings to see if they are equal.  Returns true or false.
1740
1741         bool    strEQ(char* s1, char* s2)
1742
1743 =for hackers
1744 Found in file handy.h
1745
1746 =item strGE
1747
1748 Test two strings to see if the first, C<s1>, is greater than or equal to
1749 the second, C<s2>.  Returns true or false.
1750
1751         bool    strGE(char* s1, char* s2)
1752
1753 =for hackers
1754 Found in file handy.h
1755
1756 =item strGT
1757
1758 Test two strings to see if the first, C<s1>, is greater than the second,
1759 C<s2>.  Returns true or false.
1760
1761         bool    strGT(char* s1, char* s2)
1762
1763 =for hackers
1764 Found in file handy.h
1765
1766 =item strLE
1767
1768 Test two strings to see if the first, C<s1>, is less than or equal to the
1769 second, C<s2>.  Returns true or false.
1770
1771         bool    strLE(char* s1, char* s2)
1772
1773 =for hackers
1774 Found in file handy.h
1775
1776 =item strLT
1777
1778 Test two strings to see if the first, C<s1>, is less than the second,
1779 C<s2>.  Returns true or false.
1780
1781         bool    strLT(char* s1, char* s2)
1782
1783 =for hackers
1784 Found in file handy.h
1785
1786 =item strNE
1787
1788 Test two strings to see if they are different.  Returns true or
1789 false.
1790
1791         bool    strNE(char* s1, char* s2)
1792
1793 =for hackers
1794 Found in file handy.h
1795
1796 =item strnEQ
1797
1798 Test two strings to see if they are equal.  The C<len> parameter indicates
1799 the number of bytes to compare.  Returns true or false. (A wrapper for
1800 C<strncmp>).
1801
1802         bool    strnEQ(char* s1, char* s2, STRLEN len)
1803
1804 =for hackers
1805 Found in file handy.h
1806
1807 =item strnNE
1808
1809 Test two strings to see if they are different.  The C<len> parameter
1810 indicates the number of bytes to compare.  Returns true or false. (A
1811 wrapper for C<strncmp>).
1812
1813         bool    strnNE(char* s1, char* s2, STRLEN len)
1814
1815 =for hackers
1816 Found in file handy.h
1817
1818 =item StructCopy
1819
1820 This is an architecture-independent macro to copy one structure to another.
1821
1822         void    StructCopy(type src, type dest, type)
1823
1824 =for hackers
1825 Found in file handy.h
1826
1827 =item SvCUR
1828
1829 Returns the length of the string which is in the SV.  See C<SvLEN>.
1830
1831         STRLEN  SvCUR(SV* sv)
1832
1833 =for hackers
1834 Found in file sv.h
1835
1836 =item SvCUR_set
1837
1838 Set the length of the string which is in the SV.  See C<SvCUR>.
1839
1840         void    SvCUR_set(SV* sv, STRLEN len)
1841
1842 =for hackers
1843 Found in file sv.h
1844
1845 =item SvEND
1846
1847 Returns a pointer to the last character in the string which is in the SV.
1848 See C<SvCUR>.  Access the character as *(SvEND(sv)).
1849
1850         char*   SvEND(SV* sv)
1851
1852 =for hackers
1853 Found in file sv.h
1854
1855 =item SvGETMAGIC
1856
1857 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
1858 argument more than once.
1859
1860         void    SvGETMAGIC(SV* sv)
1861
1862 =for hackers
1863 Found in file sv.h
1864
1865 =item SvGROW
1866
1867 Expands the character buffer in the SV so that it has room for the
1868 indicated number of bytes (remember to reserve space for an extra trailing
1869 NUL character).  Calls C<sv_grow> to perform the expansion if necessary. 
1870 Returns a pointer to the character buffer.
1871
1872         void    SvGROW(SV* sv, STRLEN len)
1873
1874 =for hackers
1875 Found in file sv.h
1876
1877 =item SvIOK
1878
1879 Returns a boolean indicating whether the SV contains an integer.
1880
1881         bool    SvIOK(SV* sv)
1882
1883 =for hackers
1884 Found in file sv.h
1885
1886 =item SvIOKp
1887
1888 Returns a boolean indicating whether the SV contains an integer.  Checks
1889 the B<private> setting.  Use C<SvIOK>.
1890
1891         bool    SvIOKp(SV* sv)
1892
1893 =for hackers
1894 Found in file sv.h
1895
1896 =item SvIOK_off
1897
1898 Unsets the IV status of an SV.
1899
1900         void    SvIOK_off(SV* sv)
1901
1902 =for hackers
1903 Found in file sv.h
1904
1905 =item SvIOK_on
1906
1907 Tells an SV that it is an integer.
1908
1909         void    SvIOK_on(SV* sv)
1910
1911 =for hackers
1912 Found in file sv.h
1913
1914 =item SvIOK_only
1915
1916 Tells an SV that it is an integer and disables all other OK bits.
1917
1918         void    SvIOK_only(SV* sv)
1919
1920 =for hackers
1921 Found in file sv.h
1922
1923 =item SvIV
1924
1925 Coerces the given SV to an integer and returns it.
1926
1927         IV      SvIV(SV* sv)
1928
1929 =for hackers
1930 Found in file sv.h
1931
1932 =item SvIVX
1933
1934 Returns the integer which is stored in the SV, assuming SvIOK is
1935 true.
1936
1937         IV      SvIVX(SV* sv)
1938
1939 =for hackers
1940 Found in file sv.h
1941
1942 =item SvLEN
1943
1944 Returns the size of the string buffer in the SV.  See C<SvCUR>.
1945
1946         STRLEN  SvLEN(SV* sv)
1947
1948 =for hackers
1949 Found in file sv.h
1950
1951 =item SvNIOK
1952
1953 Returns a boolean indicating whether the SV contains a number, integer or
1954 double.
1955
1956         bool    SvNIOK(SV* sv)
1957
1958 =for hackers
1959 Found in file sv.h
1960
1961 =item SvNIOKp
1962
1963 Returns a boolean indicating whether the SV contains a number, integer or
1964 double.  Checks the B<private> setting.  Use C<SvNIOK>.
1965
1966         bool    SvNIOKp(SV* sv)
1967
1968 =for hackers
1969 Found in file sv.h
1970
1971 =item SvNIOK_off
1972
1973 Unsets the NV/IV status of an SV.
1974
1975         void    SvNIOK_off(SV* sv)
1976
1977 =for hackers
1978 Found in file sv.h
1979
1980 =item SvNOK
1981
1982 Returns a boolean indicating whether the SV contains a double.
1983
1984         bool    SvNOK(SV* sv)
1985
1986 =for hackers
1987 Found in file sv.h
1988
1989 =item SvNOKp
1990
1991 Returns a boolean indicating whether the SV contains a double.  Checks the
1992 B<private> setting.  Use C<SvNOK>.
1993
1994         bool    SvNOKp(SV* sv)
1995
1996 =for hackers
1997 Found in file sv.h
1998
1999 =item SvNOK_off
2000
2001 Unsets the NV status of an SV.
2002
2003         void    SvNOK_off(SV* sv)
2004
2005 =for hackers
2006 Found in file sv.h
2007
2008 =item SvNOK_on
2009
2010 Tells an SV that it is a double.
2011
2012         void    SvNOK_on(SV* sv)
2013
2014 =for hackers
2015 Found in file sv.h
2016
2017 =item SvNOK_only
2018
2019 Tells an SV that it is a double and disables all other OK bits.
2020
2021         void    SvNOK_only(SV* sv)
2022
2023 =for hackers
2024 Found in file sv.h
2025
2026 =item SvNV
2027
2028 Coerce the given SV to a double and return it.
2029
2030         NV      SvNV(SV* sv)
2031
2032 =for hackers
2033 Found in file sv.h
2034
2035 =item SvNVX
2036
2037 Returns the double which is stored in the SV, assuming SvNOK is
2038 true.
2039
2040         NV      SvNVX(SV* sv)
2041
2042 =for hackers
2043 Found in file sv.h
2044
2045 =item SvOK
2046
2047 Returns a boolean indicating whether the value is an SV.
2048
2049         bool    SvOK(SV* sv)
2050
2051 =for hackers
2052 Found in file sv.h
2053
2054 =item SvOOK
2055
2056 Returns a boolean indicating whether the SvIVX is a valid offset value for
2057 the SvPVX.  This hack is used internally to speed up removal of characters
2058 from the beginning of a SvPV.  When SvOOK is true, then the start of the
2059 allocated string buffer is really (SvPVX - SvIVX).
2060
2061         bool    SvOOK(SV* sv)
2062
2063 =for hackers
2064 Found in file sv.h
2065
2066 =item SvPOK
2067
2068 Returns a boolean indicating whether the SV contains a character
2069 string.
2070
2071         bool    SvPOK(SV* sv)
2072
2073 =for hackers
2074 Found in file sv.h
2075
2076 =item SvPOKp
2077
2078 Returns a boolean indicating whether the SV contains a character string.
2079 Checks the B<private> setting.  Use C<SvPOK>.
2080
2081         bool    SvPOKp(SV* sv)
2082
2083 =for hackers
2084 Found in file sv.h
2085
2086 =item SvPOK_off
2087
2088 Unsets the PV status of an SV.
2089
2090         void    SvPOK_off(SV* sv)
2091
2092 =for hackers
2093 Found in file sv.h
2094
2095 =item SvPOK_on
2096
2097 Tells an SV that it is a string.
2098
2099         void    SvPOK_on(SV* sv)
2100
2101 =for hackers
2102 Found in file sv.h
2103
2104 =item SvPOK_only
2105
2106 Tells an SV that it is a string and disables all other OK bits.
2107
2108         void    SvPOK_only(SV* sv)
2109
2110 =for hackers
2111 Found in file sv.h
2112
2113 =item SvPV
2114
2115 Returns a pointer to the string in the SV, or a stringified form of the SV
2116 if the SV does not contain a string.  Handles 'get' magic.
2117
2118         char*   SvPV(SV* sv, STRLEN len)
2119
2120 =for hackers
2121 Found in file sv.h
2122
2123 =item SvPVX
2124
2125 Returns a pointer to the string in the SV.  The SV must contain a
2126 string.
2127
2128         char*   SvPVX(SV* sv)
2129
2130 =for hackers
2131 Found in file sv.h
2132
2133 =item SvPV_force
2134
2135 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
2136 force if you are going to update the SvPVX directly.
2137
2138         char*   SvPV_force(SV* sv, STRLEN len)
2139
2140 =for hackers
2141 Found in file sv.h
2142
2143 =item SvPV_nolen
2144
2145 Returns a pointer to the string in the SV, or a stringified form of the SV
2146 if the SV does not contain a string.  Handles 'get' magic.
2147
2148         char*   SvPV_nolen(SV* sv)
2149
2150 =for hackers
2151 Found in file sv.h
2152
2153 =item SvREFCNT
2154
2155 Returns the value of the object's reference count.
2156
2157         U32     SvREFCNT(SV* sv)
2158
2159 =for hackers
2160 Found in file sv.h
2161
2162 =item SvREFCNT_dec
2163
2164 Decrements the reference count of the given SV.
2165
2166         void    SvREFCNT_dec(SV* sv)
2167
2168 =for hackers
2169 Found in file sv.h
2170
2171 =item SvREFCNT_inc
2172
2173 Increments the reference count of the given SV.
2174
2175         SV*     SvREFCNT_inc(SV* sv)
2176
2177 =for hackers
2178 Found in file sv.h
2179
2180 =item SvROK
2181
2182 Tests if the SV is an RV.
2183
2184         bool    SvROK(SV* sv)
2185
2186 =for hackers
2187 Found in file sv.h
2188
2189 =item SvROK_off
2190
2191 Unsets the RV status of an SV.
2192
2193         void    SvROK_off(SV* sv)
2194
2195 =for hackers
2196 Found in file sv.h
2197
2198 =item SvROK_on
2199
2200 Tells an SV that it is an RV.
2201
2202         void    SvROK_on(SV* sv)
2203
2204 =for hackers
2205 Found in file sv.h
2206
2207 =item SvRV
2208
2209 Dereferences an RV to return the SV.
2210
2211         SV*     SvRV(SV* sv)
2212
2213 =for hackers
2214 Found in file sv.h
2215
2216 =item SvSETMAGIC
2217
2218 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
2219 argument more than once.
2220
2221         void    SvSETMAGIC(SV* sv)
2222
2223 =for hackers
2224 Found in file sv.h
2225
2226 =item SvSetSV
2227
2228 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
2229 more than once.
2230
2231         void    SvSetSV(SV* dsb, SV* ssv)
2232
2233 =for hackers
2234 Found in file sv.h
2235
2236 =item SvSetSV_nosteal
2237
2238 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2239 ssv. May evaluate arguments more than once.
2240
2241         void    SvSetSV_nosteal(SV* dsv, SV* ssv)
2242
2243 =for hackers
2244 Found in file sv.h
2245
2246 =item SvSTASH
2247
2248 Returns the stash of the SV.
2249
2250         HV*     SvSTASH(SV* sv)
2251
2252 =for hackers
2253 Found in file sv.h
2254
2255 =item SvTAINT
2256
2257 Taints an SV if tainting is enabled
2258
2259         void    SvTAINT(SV* sv)
2260
2261 =for hackers
2262 Found in file sv.h
2263
2264 =item SvTAINTED
2265
2266 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2267 not.
2268
2269         bool    SvTAINTED(SV* sv)
2270
2271 =for hackers
2272 Found in file sv.h
2273
2274 =item SvTAINTED_off
2275
2276 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2277 some of Perl's fundamental security features. XS module authors should not
2278 use this function unless they fully understand all the implications of
2279 unconditionally untainting the value. Untainting should be done in the
2280 standard perl fashion, via a carefully crafted regexp, rather than directly
2281 untainting variables.
2282
2283         void    SvTAINTED_off(SV* sv)
2284
2285 =for hackers
2286 Found in file sv.h
2287
2288 =item SvTAINTED_on
2289
2290 Marks an SV as tainted.
2291
2292         void    SvTAINTED_on(SV* sv)
2293
2294 =for hackers
2295 Found in file sv.h
2296
2297 =item SvTRUE
2298
2299 Returns a boolean indicating whether Perl would evaluate the SV as true or
2300 false, defined or undefined.  Does not handle 'get' magic.
2301
2302         bool    SvTRUE(SV* sv)
2303
2304 =for hackers
2305 Found in file sv.h
2306
2307 =item svtype
2308
2309 An enum of flags for Perl types.  These are found in the file B<sv.h> 
2310 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
2311
2312 =for hackers
2313 Found in file sv.h
2314
2315 =item SvTYPE
2316
2317 Returns the type of the SV.  See C<svtype>.
2318
2319         svtype  SvTYPE(SV* sv)
2320
2321 =for hackers
2322 Found in file sv.h
2323
2324 =item SVt_IV
2325
2326 Integer type flag for scalars.  See C<svtype>.
2327
2328 =for hackers
2329 Found in file sv.h
2330
2331 =item SVt_NV
2332
2333 Double type flag for scalars.  See C<svtype>.
2334
2335 =for hackers
2336 Found in file sv.h
2337
2338 =item SVt_PV
2339
2340 Pointer type flag for scalars.  See C<svtype>.
2341
2342 =for hackers
2343 Found in file sv.h
2344
2345 =item SVt_PVAV
2346
2347 Type flag for arrays.  See C<svtype>.
2348
2349 =for hackers
2350 Found in file sv.h
2351
2352 =item SVt_PVCV
2353
2354 Type flag for code refs.  See C<svtype>.
2355
2356 =for hackers
2357 Found in file sv.h
2358
2359 =item SVt_PVHV
2360
2361 Type flag for hashes.  See C<svtype>.
2362
2363 =for hackers
2364 Found in file sv.h
2365
2366 =item SVt_PVMG
2367
2368 Type flag for blessed scalars.  See C<svtype>.
2369
2370 =for hackers
2371 Found in file sv.h
2372
2373 =item SvUPGRADE
2374
2375 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
2376 perform the upgrade if necessary.  See C<svtype>.
2377
2378         void    SvUPGRADE(SV* sv, svtype type)
2379
2380 =for hackers
2381 Found in file sv.h
2382
2383 =item SvUV
2384
2385 Coerces the given SV to an unsigned integer and returns it.
2386
2387         UV      SvUV(SV* sv)
2388
2389 =for hackers
2390 Found in file sv.h
2391
2392 =item SvUVX
2393
2394 Returns the unsigned integer which is stored in the SV, assuming SvIOK is
2395 true.
2396
2397         UV      SvUVX(SV* sv)
2398
2399 =for hackers
2400 Found in file sv.h
2401
2402 =item sv_2mortal
2403
2404 Marks an SV as mortal.  The SV will be destroyed when the current context
2405 ends.
2406
2407         SV*     sv_2mortal(SV* sv)
2408
2409 =for hackers
2410 Found in file sv.c
2411
2412 =item sv_bless
2413
2414 Blesses an SV into a specified package.  The SV must be an RV.  The package
2415 must be designated by its stash (see C<gv_stashpv()>).  The reference count
2416 of the SV is unaffected.
2417
2418         SV*     sv_bless(SV* sv, HV* stash)
2419
2420 =for hackers
2421 Found in file sv.c
2422
2423 =item sv_catpv
2424
2425 Concatenates the string onto the end of the string which is in the SV.
2426 Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
2427
2428         void    sv_catpv(SV* sv, const char* ptr)
2429
2430 =for hackers
2431 Found in file sv.c
2432
2433 =item sv_catpvf
2434
2435 Processes its arguments like C<sprintf> and appends the formatted output
2436 to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
2437 typically be called after calling this function to handle 'set' magic.
2438
2439         void    sv_catpvf(SV* sv, const char* pat, ...)
2440
2441 =for hackers
2442 Found in file sv.c
2443
2444 =item sv_catpvf_mg
2445
2446 Like C<sv_catpvf>, but also handles 'set' magic.
2447
2448         void    sv_catpvf_mg(SV *sv, const char* pat, ...)
2449
2450 =for hackers
2451 Found in file sv.c
2452
2453 =item sv_catpvn
2454
2455 Concatenates the string onto the end of the string which is in the SV.  The
2456 C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
2457 'set' magic.  See C<sv_catpvn_mg>.
2458
2459         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
2460
2461 =for hackers
2462 Found in file sv.c
2463
2464 =item sv_catpvn_mg
2465
2466 Like C<sv_catpvn>, but also handles 'set' magic.
2467
2468         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
2469
2470 =for hackers
2471 Found in file sv.c
2472
2473 =item sv_catpv_mg
2474
2475 Like C<sv_catpv>, but also handles 'set' magic.
2476
2477         void    sv_catpv_mg(SV *sv, const char *ptr)
2478
2479 =for hackers
2480 Found in file sv.c
2481
2482 =item sv_catsv
2483
2484 Concatenates the string from SV C<ssv> onto the end of the string in SV
2485 C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
2486
2487         void    sv_catsv(SV* dsv, SV* ssv)
2488
2489 =for hackers
2490 Found in file sv.c
2491
2492 =item sv_catsv_mg
2493
2494 Like C<sv_catsv>, but also handles 'set' magic.
2495
2496         void    sv_catsv_mg(SV *dstr, SV *sstr)
2497
2498 =for hackers
2499 Found in file sv.c
2500
2501 =item sv_chop
2502
2503 Efficient removal of characters from the beginning of the string buffer. 
2504 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
2505 the string buffer.  The C<ptr> becomes the first character of the adjusted
2506 string.
2507
2508         void    sv_chop(SV* sv, char* ptr)
2509
2510 =for hackers
2511 Found in file sv.c
2512
2513 =item sv_clear
2514
2515 Clear an SV, making it empty. Does not free the memory used by the SV
2516 itself.
2517
2518         void    sv_clear(SV* sv)
2519
2520 =for hackers
2521 Found in file sv.c
2522
2523 =item sv_cmp
2524
2525 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
2526 string in C<sv1> is less than, equal to, or greater than the string in
2527 C<sv2>.
2528
2529         I32     sv_cmp(SV* sv1, SV* sv2)
2530
2531 =for hackers
2532 Found in file sv.c
2533
2534 =item sv_cmp_locale
2535
2536 Compares the strings in two SVs in a locale-aware manner. See
2537 L</sv_cmp_locale>
2538
2539         I32     sv_cmp_locale(SV* sv1, SV* sv2)
2540
2541 =for hackers
2542 Found in file sv.c
2543
2544 =item sv_dec
2545
2546 Auto-decrement of the value in the SV.
2547
2548         void    sv_dec(SV* sv)
2549
2550 =for hackers
2551 Found in file sv.c
2552
2553 =item sv_derived_from
2554
2555 Returns a boolean indicating whether the SV is derived from the specified
2556 class.  This is the function that implements C<UNIVERSAL::isa>.  It works
2557 for class names as well as for objects.
2558
2559         bool    sv_derived_from(SV* sv, const char* name)
2560
2561 =for hackers
2562 Found in file universal.c
2563
2564 =item sv_eq
2565
2566 Returns a boolean indicating whether the strings in the two SVs are
2567 identical.
2568
2569         I32     sv_eq(SV* sv1, SV* sv2)
2570
2571 =for hackers
2572 Found in file sv.c
2573
2574 =item sv_free
2575
2576 Free the memory used by an SV.
2577
2578         void    sv_free(SV* sv)
2579
2580 =for hackers
2581 Found in file sv.c
2582
2583 =item sv_gets
2584
2585 Get a line from the filehandle and store it into the SV, optionally
2586 appending to the currently-stored string.
2587
2588         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
2589
2590 =for hackers
2591 Found in file sv.c
2592
2593 =item sv_grow
2594
2595 Expands the character buffer in the SV.  This will use C<sv_unref> and will
2596 upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
2597 Use C<SvGROW>.
2598
2599         char*   sv_grow(SV* sv, STRLEN newlen)
2600
2601 =for hackers
2602 Found in file sv.c
2603
2604 =item sv_inc
2605
2606 Auto-increment of the value in the SV.
2607
2608         void    sv_inc(SV* sv)
2609
2610 =for hackers
2611 Found in file sv.c
2612
2613 =item sv_insert
2614
2615 Inserts a string at the specified offset/length within the SV. Similar to
2616 the Perl substr() function.
2617
2618         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2619
2620 =for hackers
2621 Found in file sv.c
2622
2623 =item sv_isa
2624
2625 Returns a boolean indicating whether the SV is blessed into the specified
2626 class.  This does not check for subtypes; use C<sv_derived_from> to verify
2627 an inheritance relationship.
2628
2629         int     sv_isa(SV* sv, const char* name)
2630
2631 =for hackers
2632 Found in file sv.c
2633
2634 =item sv_isobject
2635
2636 Returns a boolean indicating whether the SV is an RV pointing to a blessed
2637 object.  If the SV is not an RV, or if the object is not blessed, then this
2638 will return false.
2639
2640         int     sv_isobject(SV* sv)
2641
2642 =for hackers
2643 Found in file sv.c
2644
2645 =item sv_len
2646
2647 Returns the length of the string in the SV.  See also C<SvCUR>.
2648
2649         STRLEN  sv_len(SV* sv)
2650
2651 =for hackers
2652 Found in file sv.c
2653
2654 =item sv_len_utf8
2655
2656 Returns the number of characters in the string in an SV, counting wide
2657 UTF8 bytes as a single character.
2658
2659         STRLEN  sv_len_utf8(SV* sv)
2660
2661 =for hackers
2662 Found in file sv.c
2663
2664 =item sv_magic
2665
2666 Adds magic to an SV.
2667
2668         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2669
2670 =for hackers
2671 Found in file sv.c
2672
2673 =item sv_mortalcopy
2674
2675 Creates a new SV which is a copy of the original SV.  The new SV is marked
2676 as mortal.
2677
2678         SV*     sv_mortalcopy(SV* oldsv)
2679
2680 =for hackers
2681 Found in file sv.c
2682
2683 =item sv_newmortal
2684
2685 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
2686
2687         SV*     sv_newmortal()
2688
2689 =for hackers
2690 Found in file sv.c
2691
2692 =item sv_pvn_force
2693
2694 Get a sensible string out of the SV somehow.
2695
2696         char*   sv_pvn_force(SV* sv, STRLEN* lp)
2697
2698 =for hackers
2699 Found in file sv.c
2700
2701 =item sv_pvutf8n_force
2702
2703 Get a sensible UTF8-encoded string out of the SV somehow. See
2704 L</sv_pvn_force>.
2705
2706         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
2707
2708 =for hackers
2709 Found in file sv.c
2710
2711 =item sv_reftype
2712
2713 Returns a string describing what the SV is a reference to.
2714
2715         char*   sv_reftype(SV* sv, int ob)
2716
2717 =for hackers
2718 Found in file sv.c
2719
2720 =item sv_replace
2721
2722 Make the first argument a copy of the second, then delete the original.
2723
2724         void    sv_replace(SV* sv, SV* nsv)
2725
2726 =for hackers
2727 Found in file sv.c
2728
2729 =item sv_rvweaken
2730
2731 Weaken a reference.
2732
2733         SV*     sv_rvweaken(SV *sv)
2734
2735 =for hackers
2736 Found in file sv.c
2737
2738 =item sv_setiv
2739
2740 Copies an integer into the given SV.  Does not handle 'set' magic.  See
2741 C<sv_setiv_mg>.
2742
2743         void    sv_setiv(SV* sv, IV num)
2744
2745 =for hackers
2746 Found in file sv.c
2747
2748 =item sv_setiv_mg
2749
2750 Like C<sv_setiv>, but also handles 'set' magic.
2751
2752         void    sv_setiv_mg(SV *sv, IV i)
2753
2754 =for hackers
2755 Found in file sv.c
2756
2757 =item sv_setnv
2758
2759 Copies a double into the given SV.  Does not handle 'set' magic.  See
2760 C<sv_setnv_mg>.
2761
2762         void    sv_setnv(SV* sv, NV num)
2763
2764 =for hackers
2765 Found in file sv.c
2766
2767 =item sv_setnv_mg
2768
2769 Like C<sv_setnv>, but also handles 'set' magic.
2770
2771         void    sv_setnv_mg(SV *sv, NV num)
2772
2773 =for hackers
2774 Found in file sv.c
2775
2776 =item sv_setpv
2777
2778 Copies a string into an SV.  The string must be null-terminated.  Does not
2779 handle 'set' magic.  See C<sv_setpv_mg>.
2780
2781         void    sv_setpv(SV* sv, const char* ptr)
2782
2783 =for hackers
2784 Found in file sv.c
2785
2786 =item sv_setpvf
2787
2788 Processes its arguments like C<sprintf> and sets an SV to the formatted
2789 output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
2790
2791         void    sv_setpvf(SV* sv, const char* pat, ...)
2792
2793 =for hackers
2794 Found in file sv.c
2795
2796 =item sv_setpvf_mg
2797
2798 Like C<sv_setpvf>, but also handles 'set' magic.
2799
2800         void    sv_setpvf_mg(SV *sv, const char* pat, ...)
2801
2802 =for hackers
2803 Found in file sv.c
2804
2805 =item sv_setpviv
2806
2807 Copies an integer into the given SV, also updating its string value.
2808 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
2809
2810         void    sv_setpviv(SV* sv, IV num)
2811
2812 =for hackers
2813 Found in file sv.c
2814
2815 =item sv_setpviv_mg
2816
2817 Like C<sv_setpviv>, but also handles 'set' magic.
2818
2819         void    sv_setpviv_mg(SV *sv, IV iv)
2820
2821 =for hackers
2822 Found in file sv.c
2823
2824 =item sv_setpvn
2825
2826 Copies a string into an SV.  The C<len> parameter indicates the number of
2827 bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
2828
2829         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2830
2831 =for hackers
2832 Found in file sv.c
2833
2834 =item sv_setpvn_mg
2835
2836 Like C<sv_setpvn>, but also handles 'set' magic.
2837
2838         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2839
2840 =for hackers
2841 Found in file sv.c
2842
2843 =item sv_setpv_mg
2844
2845 Like C<sv_setpv>, but also handles 'set' magic.
2846
2847         void    sv_setpv_mg(SV *sv, const char *ptr)
2848
2849 =for hackers
2850 Found in file sv.c
2851
2852 =item sv_setref_iv
2853
2854 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
2855 argument will be upgraded to an RV.  That RV will be modified to point to
2856 the new SV.  The C<classname> argument indicates the package for the
2857 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2858 will be returned and will have a reference count of 1.
2859
2860         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
2861
2862 =for hackers
2863 Found in file sv.c
2864
2865 =item sv_setref_nv
2866
2867 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
2868 argument will be upgraded to an RV.  That RV will be modified to point to
2869 the new SV.  The C<classname> argument indicates the package for the
2870 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2871 will be returned and will have a reference count of 1.
2872
2873         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
2874
2875 =for hackers
2876 Found in file sv.c
2877
2878 =item sv_setref_pv
2879
2880 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
2881 argument will be upgraded to an RV.  That RV will be modified to point to
2882 the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
2883 into the SV.  The C<classname> argument indicates the package for the
2884 blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
2885 will be returned and will have a reference count of 1.
2886
2887 Do not use with other Perl types such as HV, AV, SV, CV, because those
2888 objects will become corrupted by the pointer copy process.
2889
2890 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2891
2892         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
2893
2894 =for hackers
2895 Found in file sv.c
2896
2897 =item sv_setref_pvn
2898
2899 Copies a string into a new SV, optionally blessing the SV.  The length of the
2900 string must be specified with C<n>.  The C<rv> argument will be upgraded to
2901 an RV.  That RV will be modified to point to the new SV.  The C<classname>
2902 argument indicates the package for the blessing.  Set C<classname> to
2903 C<Nullch> to avoid the blessing.  The new SV will be returned and will have
2904 a reference count of 1.
2905
2906 Note that C<sv_setref_pv> copies the pointer while this copies the string.
2907
2908         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2909
2910 =for hackers
2911 Found in file sv.c
2912
2913 =item sv_setsv
2914
2915 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
2916 The source SV may be destroyed if it is mortal.  Does not handle 'set'
2917 magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
2918 C<sv_setsv_mg>.
2919
2920         void    sv_setsv(SV* dsv, SV* ssv)
2921
2922 =for hackers
2923 Found in file sv.c
2924
2925 =item sv_setsv_mg
2926
2927 Like C<sv_setsv>, but also handles 'set' magic.
2928
2929         void    sv_setsv_mg(SV *dstr, SV *sstr)
2930
2931 =for hackers
2932 Found in file sv.c
2933
2934 =item sv_setuv
2935
2936 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
2937 See C<sv_setuv_mg>.
2938
2939         void    sv_setuv(SV* sv, UV num)
2940
2941 =for hackers
2942 Found in file sv.c
2943
2944 =item sv_setuv_mg
2945
2946 Like C<sv_setuv>, but also handles 'set' magic.
2947
2948         void    sv_setuv_mg(SV *sv, UV u)
2949
2950 =for hackers
2951 Found in file sv.c
2952
2953 =item sv_true
2954
2955 Returns true if the SV has a true value by Perl's rules.
2956
2957         I32     sv_true(SV *sv)
2958
2959 =for hackers
2960 Found in file sv.c
2961
2962 =item sv_unmagic
2963
2964 Removes magic from an SV.
2965
2966         int     sv_unmagic(SV* sv, int type)
2967
2968 =for hackers
2969 Found in file sv.c
2970
2971 =item sv_unref
2972
2973 Unsets the RV status of the SV, and decrements the reference count of
2974 whatever was being referenced by the RV.  This can almost be thought of
2975 as a reversal of C<newSVrv>.  See C<SvROK_off>.
2976
2977         void    sv_unref(SV* sv)
2978
2979 =for hackers
2980 Found in file sv.c
2981
2982 =item sv_upgrade
2983
2984 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
2985 C<svtype>.
2986
2987         bool    sv_upgrade(SV* sv, U32 mt)
2988
2989 =for hackers
2990 Found in file sv.c
2991
2992 =item sv_usepvn
2993
2994 Tells an SV to use C<ptr> to find its string value.  Normally the string is
2995 stored inside the SV but sv_usepvn allows the SV to use an outside string. 
2996 The C<ptr> should point to memory that was allocated by C<malloc>.  The
2997 string length, C<len>, must be supplied.  This function will realloc the
2998 memory pointed to by C<ptr>, so that pointer should not be freed or used by
2999 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
3000 See C<sv_usepvn_mg>.
3001
3002         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
3003
3004 =for hackers
3005 Found in file sv.c
3006
3007 =item sv_usepvn_mg
3008
3009 Like C<sv_usepvn>, but also handles 'set' magic.
3010
3011         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
3012
3013 =for hackers
3014 Found in file sv.c
3015
3016 =item sv_utf8_downgrade
3017
3018 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
3019 This may not be possible if the PV contains non-byte encoding characters;
3020 if this is the case, either returns false or, if C<fail_ok> is not
3021 true, croaks.
3022
3023 NOTE: this function is experimental and may change or be
3024 removed without notice.
3025
3026         bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
3027
3028 =for hackers
3029 Found in file sv.c
3030
3031 =item sv_utf8_encode
3032
3033 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
3034 flag so that it looks like bytes again. Nothing calls this. 
3035
3036 NOTE: this function is experimental and may change or be
3037 removed without notice.
3038
3039         void    sv_utf8_encode(SV *sv)
3040
3041 =for hackers
3042 Found in file sv.c
3043
3044 =item sv_utf8_upgrade
3045
3046 Convert the PV of an SV to its UTF8-encoded form.
3047
3048         void    sv_utf8_upgrade(SV *sv)
3049
3050 =for hackers
3051 Found in file sv.c
3052
3053 =item sv_vcatpvfn
3054
3055 Processes its arguments like C<vsprintf> and appends the formatted output
3056 to an SV.  Uses an array of SVs if the C style variable argument list is
3057 missing (NULL).  When running with taint checks enabled, indicates via
3058 C<maybe_tainted> if results are untrustworthy (often due to the use of
3059 locales).
3060
3061         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3062
3063 =for hackers
3064 Found in file sv.c
3065
3066 =item sv_vsetpvfn
3067
3068 Works like C<vcatpvfn> but copies the text into the SV instead of
3069 appending it.
3070
3071         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3072
3073 =for hackers
3074 Found in file sv.c
3075
3076 =item THIS
3077
3078 Variable which is setup by C<xsubpp> to designate the object in a C++ 
3079 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
3080 L<perlxs/"Using XS With C++">.
3081
3082         (whatever)      THIS
3083
3084 =for hackers
3085 Found in file XSUB.h
3086
3087 =item toLOWER
3088
3089 Converts the specified character to lowercase.
3090
3091         char    toLOWER(char ch)
3092
3093 =for hackers
3094 Found in file handy.h
3095
3096 =item toUPPER
3097
3098 Converts the specified character to uppercase.
3099
3100         char    toUPPER(char ch)
3101
3102 =for hackers
3103 Found in file handy.h
3104
3105 =item U8 *s
3106
3107 Returns true if first C<len> bytes of the given string form valid a UTF8
3108 string, false otherwise.
3109
3110         bool_utf8_string        U8 *s(STRLEN len)
3111
3112 =for hackers
3113 Found in file utf8.c
3114
3115 =item utf8_to_bytes
3116
3117 Converts a string C<s> of length C<len> from UTF8 into ASCII encoding.
3118 Unlike C<bytes_to_utf8>, this over-writes the original string.
3119 Returns zero on failure after converting as much as possible.
3120
3121         U8 *    utf8_to_bytes(U8 *s, STRLEN len)
3122
3123 =for hackers
3124 Found in file utf8.c
3125
3126 =item warn
3127
3128 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
3129 function the same way you use the C C<printf> function.  See
3130 C<croak>.
3131
3132         void    warn(const char* pat, ...)
3133
3134 =for hackers
3135 Found in file util.c
3136
3137 =item XPUSHi
3138
3139 Push an integer onto the stack, extending the stack if necessary.  Handles
3140 'set' magic. See C<PUSHi>.
3141
3142         void    XPUSHi(IV iv)
3143
3144 =for hackers
3145 Found in file pp.h
3146
3147 =item XPUSHn
3148
3149 Push a double onto the stack, extending the stack if necessary.  Handles
3150 'set' magic.  See C<PUSHn>.
3151
3152         void    XPUSHn(NV nv)
3153
3154 =for hackers
3155 Found in file pp.h
3156
3157 =item XPUSHp
3158
3159 Push a string onto the stack, extending the stack if necessary.  The C<len>
3160 indicates the length of the string.  Handles 'set' magic.  See
3161 C<PUSHp>.
3162
3163         void    XPUSHp(char* str, STRLEN len)
3164
3165 =for hackers
3166 Found in file pp.h
3167
3168 =item XPUSHs
3169
3170 Push an SV onto the stack, extending the stack if necessary.  Does not
3171 handle 'set' magic.  See C<PUSHs>.
3172
3173         void    XPUSHs(SV* sv)
3174
3175 =for hackers
3176 Found in file pp.h
3177
3178 =item XPUSHu
3179
3180 Push an unsigned integer onto the stack, extending the stack if necessary. 
3181 See C<PUSHu>.
3182
3183         void    XPUSHu(UV uv)
3184
3185 =for hackers
3186 Found in file pp.h
3187
3188 =item XS
3189
3190 Macro to declare an XSUB and its C parameter list.  This is handled by
3191 C<xsubpp>.
3192
3193 =for hackers
3194 Found in file XSUB.h
3195
3196 =item XSRETURN
3197
3198 Return from XSUB, indicating number of items on the stack.  This is usually
3199 handled by C<xsubpp>.
3200
3201         void    XSRETURN(int nitems)
3202
3203 =for hackers
3204 Found in file XSUB.h
3205
3206 =item XSRETURN_EMPTY
3207
3208 Return an empty list from an XSUB immediately.
3209
3210                 XSRETURN_EMPTY;
3211
3212 =for hackers
3213 Found in file XSUB.h
3214
3215 =item XSRETURN_IV
3216
3217 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
3218
3219         void    XSRETURN_IV(IV iv)
3220
3221 =for hackers
3222 Found in file XSUB.h
3223
3224 =item XSRETURN_NO
3225
3226 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
3227
3228                 XSRETURN_NO;
3229
3230 =for hackers
3231 Found in file XSUB.h
3232
3233 =item XSRETURN_NV
3234
3235 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
3236
3237         void    XSRETURN_NV(NV nv)
3238
3239 =for hackers
3240 Found in file XSUB.h
3241
3242 =item XSRETURN_PV
3243
3244 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
3245
3246         void    XSRETURN_PV(char* str)
3247
3248 =for hackers
3249 Found in file XSUB.h
3250
3251 =item XSRETURN_UNDEF
3252
3253 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
3254
3255                 XSRETURN_UNDEF;
3256
3257 =for hackers
3258 Found in file XSUB.h
3259
3260 =item XSRETURN_YES
3261
3262 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
3263
3264                 XSRETURN_YES;
3265
3266 =for hackers
3267 Found in file XSUB.h
3268
3269 =item XST_mIV
3270
3271 Place an integer into the specified position C<pos> on the stack.  The
3272 value is stored in a new mortal SV.
3273
3274         void    XST_mIV(int pos, IV iv)
3275
3276 =for hackers
3277 Found in file XSUB.h
3278
3279 =item XST_mNO
3280
3281 Place C<&PL_sv_no> into the specified position C<pos> on the
3282 stack.
3283
3284         void    XST_mNO(int pos)
3285
3286 =for hackers
3287 Found in file XSUB.h
3288
3289 =item XST_mNV
3290
3291 Place a double into the specified position C<pos> on the stack.  The value
3292 is stored in a new mortal SV.
3293
3294         void    XST_mNV(int pos, NV nv)
3295
3296 =for hackers
3297 Found in file XSUB.h
3298
3299 =item XST_mPV
3300
3301 Place a copy of a string into the specified position C<pos> on the stack. 
3302 The value is stored in a new mortal SV.
3303
3304         void    XST_mPV(int pos, char* str)
3305
3306 =for hackers
3307 Found in file XSUB.h
3308
3309 =item XST_mUNDEF
3310
3311 Place C<&PL_sv_undef> into the specified position C<pos> on the
3312 stack.
3313
3314         void    XST_mUNDEF(int pos)
3315
3316 =for hackers
3317 Found in file XSUB.h
3318
3319 =item XST_mYES
3320
3321 Place C<&PL_sv_yes> into the specified position C<pos> on the
3322 stack.
3323
3324         void    XST_mYES(int pos)
3325
3326 =for hackers
3327 Found in file XSUB.h
3328
3329 =item XS_VERSION
3330
3331 The version identifier for an XS module.  This is usually
3332 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
3333
3334 =for hackers
3335 Found in file XSUB.h
3336
3337 =item XS_VERSION_BOOTCHECK
3338
3339 Macro to verify that a PM module's $VERSION variable matches the XS
3340 module's C<XS_VERSION> variable.  This is usually handled automatically by
3341 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
3342
3343                 XS_VERSION_BOOTCHECK;
3344
3345 =for hackers
3346 Found in file XSUB.h
3347
3348 =item Zero
3349
3350 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
3351 destination, C<nitems> is the number of items, and C<type> is the type.
3352
3353         void    Zero(void* dest, int nitems, type)
3354
3355 =for hackers
3356 Found in file handy.h
3357
3358 =back
3359
3360 =head1 AUTHORS
3361
3362 Until May 1997, this document was maintained by Jeff Okamoto
3363 <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
3364
3365 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3366 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
3367 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3368 Stephen McCamant, and Gurusamy Sarathy.
3369
3370 API Listing originally by Dean Roehrich <roehrich@cray.com>.
3371
3372 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
3373
3374 =head1 SEE ALSO
3375
3376 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3377