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