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