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