This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update perlhist with 5.6.2.
[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
954c1994
GS
1070=item hv_clear
1071
1072Clears a hash, making it empty.
1073
1074 void hv_clear(HV* tb)
1075
497711e7
GS
1076=for hackers
1077Found in file hv.c
1078
954c1994
GS
1079=item hv_delete
1080
1081Deletes a key/value pair in the hash. The value SV is removed from the
1c846c1f 1082hash and returned to the caller. The C<klen> is the length of the key.
954c1994
GS
1083The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1084will be returned.
1085
da58a35d 1086 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
954c1994 1087
497711e7
GS
1088=for hackers
1089Found in file hv.c
1090
954c1994
GS
1091=item hv_delete_ent
1092
1093Deletes a key/value pair in the hash. The value SV is removed from the
1094hash and returned to the caller. The C<flags> value will normally be zero;
1095if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
1096precomputed hash value, or 0 to ask for it to be computed.
1097
1098 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1099
497711e7
GS
1100=for hackers
1101Found in file hv.c
1102
954c1994
GS
1103=item hv_exists
1104
1105Returns a boolean indicating whether the specified hash key exists. The
1106C<klen> is the length of the key.
1107
da58a35d 1108 bool hv_exists(HV* tb, const char* key, I32 klen)
954c1994 1109
497711e7
GS
1110=for hackers
1111Found in file hv.c
1112
954c1994
GS
1113=item hv_exists_ent
1114
1115Returns a boolean indicating whether the specified hash key exists. C<hash>
1116can be a valid precomputed hash value, or 0 to ask for it to be
1117computed.
1118
1119 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
1120
497711e7
GS
1121=for hackers
1122Found in file hv.c
1123
954c1994
GS
1124=item hv_fetch
1125
1126Returns the SV which corresponds to the specified key in the hash. The
1127C<klen> is the length of the key. If C<lval> is set then the fetch will be
1128part of a store. Check that the return value is non-null before
f4758303 1129dereferencing it to an C<SV*>.
954c1994 1130
96f1132b 1131See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1132information on how to use this function on tied hashes.
1133
da58a35d 1134 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
954c1994 1135
497711e7
GS
1136=for hackers
1137Found in file hv.c
1138
954c1994
GS
1139=item hv_fetch_ent
1140
1141Returns the hash entry which corresponds to the specified key in the hash.
1142C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1143if you want the function to compute it. IF C<lval> is set then the fetch
1144will be part of a store. Make sure the return value is non-null before
1145accessing it. The return value when C<tb> is a tied hash is a pointer to a
1146static location, so be sure to make a copy of the structure if you need to
1c846c1f 1147store it somewhere.
954c1994 1148
96f1132b 1149See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1150information on how to use this function on tied hashes.
1151
1152 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1153
497711e7
GS
1154=for hackers
1155Found in file hv.c
1156
954c1994
GS
1157=item hv_iterinit
1158
1159Prepares a starting point to traverse a hash table. Returns the number of
1160keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1c846c1f 1161currently only meaningful for hashes without tie magic.
954c1994
GS
1162
1163NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1164hash buckets that happen to be in use. If you still need that esoteric
1165value, you can get it through the macro C<HvFILL(tb)>.
1166
641d4181 1167
954c1994
GS
1168 I32 hv_iterinit(HV* tb)
1169
497711e7
GS
1170=for hackers
1171Found in file hv.c
1172
954c1994
GS
1173=item hv_iterkey
1174
1175Returns the key from the current position of the hash iterator. See
1176C<hv_iterinit>.
1177
1178 char* hv_iterkey(HE* entry, I32* retlen)
1179
497711e7
GS
1180=for hackers
1181Found in file hv.c
1182
954c1994
GS
1183=item hv_iterkeysv
1184
1185Returns the key as an C<SV*> from the current position of the hash
1186iterator. The return value will always be a mortal copy of the key. Also
1187see C<hv_iterinit>.
1188
1189 SV* hv_iterkeysv(HE* entry)
1190
497711e7
GS
1191=for hackers
1192Found in file hv.c
1193
954c1994
GS
1194=item hv_iternext
1195
1196Returns entries from a hash iterator. See C<hv_iterinit>.
1197
641d4181
JH
1198You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1199iterator currently points to, without losing your place or invalidating your
1200iterator. Note that in this case the current entry is deleted from the hash
1201with your iterator holding the last reference to it. Your iterator is flagged
1202to free the entry on the next call to C<hv_iternext>, so you must not discard
1203your iterator immediately else the entry will leak - call C<hv_iternext> to
1204trigger the resource deallocation.
1205
954c1994
GS
1206 HE* hv_iternext(HV* tb)
1207
497711e7
GS
1208=for hackers
1209Found in file hv.c
1210
954c1994
GS
1211=item hv_iternextsv
1212
1213Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1214operation.
1215
1216 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1217
497711e7
GS
1218=for hackers
1219Found in file hv.c
1220
641d4181
JH
1221=item hv_iternext_flags
1222
1223Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
1224The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1225set the placeholders keys (for restricted hashes) will be returned in addition
1226to normal keys. By default placeholders are automatically skipped over.
384679aa
RGS
1227Currently a placeholder is implemented with a value that is
1228C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
641d4181
JH
1229restricted hashes may change, and the implementation currently is
1230insufficiently abstracted for any change to be tidy.
1231
1232NOTE: this function is experimental and may change or be
1233removed without notice.
1234
1235 HE* hv_iternext_flags(HV* tb, I32 flags)
1236
1237=for hackers
1238Found in file hv.c
1239
954c1994
GS
1240=item hv_iterval
1241
1242Returns the value from the current position of the hash iterator. See
1243C<hv_iterkey>.
1244
1245 SV* hv_iterval(HV* tb, HE* entry)
1246
497711e7
GS
1247=for hackers
1248Found in file hv.c
1249
954c1994
GS
1250=item hv_magic
1251
1252Adds magic to a hash. See C<sv_magic>.
1253
1254 void hv_magic(HV* hv, GV* gv, int how)
1255
497711e7
GS
1256=for hackers
1257Found in file hv.c
1258
954c1994
GS
1259=item hv_store
1260
1261Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1262the length of the key. The C<hash> parameter is the precomputed hash
1263value; if it is zero then Perl will compute it. The return value will be
1264NULL if the operation failed or if the value did not need to be actually
1265stored within the hash (as in the case of tied hashes). Otherwise it can
1266be dereferenced to get the original C<SV*>. Note that the caller is
1267responsible for suitably incrementing the reference count of C<val> before
7e8c5dac
HS
1268the call, and decrementing it if the function returned NULL. Effectively
1269a successful hv_store takes ownership of one reference to C<val>. This is
1270usually what you want; a newly created SV has a reference count of one, so
1271if all your code does is create SVs then store them in a hash, hv_store
1272will own the only reference to the new SV, and your code doesn't need to do
1273anything further to tidy up. hv_store is not implemented as a call to
1274hv_store_ent, and does not create a temporary SV for the key, so if your
1275key data is not already in SV form then use hv_store in preference to
1276hv_store_ent.
954c1994 1277
96f1132b 1278See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1279information on how to use this function on tied hashes.
1280
da58a35d 1281 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
954c1994 1282
497711e7
GS
1283=for hackers
1284Found in file hv.c
1285
954c1994
GS
1286=item hv_store_ent
1287
1288Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1289parameter is the precomputed hash value; if it is zero then Perl will
1290compute it. The return value is the new hash entry so created. It will be
1291NULL if the operation failed or if the value did not need to be actually
1292stored within the hash (as in the case of tied hashes). Otherwise the
f22d8e4b 1293contents of the return value can be accessed using the C<He?> macros
954c1994
GS
1294described here. Note that the caller is responsible for suitably
1295incrementing the reference count of C<val> before the call, and
7e8c5dac
HS
1296decrementing it if the function returned NULL. Effectively a successful
1297hv_store_ent takes ownership of one reference to C<val>. This is
1298usually what you want; a newly created SV has a reference count of one, so
1299if all your code does is create SVs then store them in a hash, hv_store
1300will own the only reference to the new SV, and your code doesn't need to do
1301anything further to tidy up. Note that hv_store_ent only reads the C<key>;
1302unlike C<val> it does not take ownership of it, so maintaining the correct
1303reference count on C<key> is entirely the caller's responsibility. hv_store
1304is not implemented as a call to hv_store_ent, and does not create a temporary
1305SV for the key, so if your key data is not already in SV form then use
1306hv_store in preference to hv_store_ent.
954c1994 1307
96f1132b 1308See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1309information on how to use this function on tied hashes.
1310
1311 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1312
497711e7
GS
1313=for hackers
1314Found in file hv.c
1315
954c1994
GS
1316=item hv_undef
1317
1318Undefines the hash.
1319
1320 void hv_undef(HV* tb)
1321
497711e7
GS
1322=for hackers
1323Found in file hv.c
1324
94bdecf9 1325=item newHV
d2cc3551 1326
94bdecf9 1327Creates a new HV. The reference count is set to 1.
d2cc3551 1328
94bdecf9 1329 HV* newHV()
d2cc3551
JH
1330
1331=for hackers
94bdecf9 1332Found in file hv.c
d2cc3551 1333
94bdecf9 1334=item Nullhv
954c1994 1335
94bdecf9 1336Null HV pointer.
954c1994 1337
954c1994 1338
497711e7 1339=for hackers
94bdecf9 1340Found in file hv.h
497711e7 1341
954c1994 1342
94bdecf9 1343=back
954c1994 1344
94bdecf9 1345=head1 Magical Functions
954c1994 1346
94bdecf9 1347=over 8
497711e7 1348
94bdecf9 1349=item mg_clear
954c1994 1350
94bdecf9 1351Clear something magical that the SV represents. See C<sv_magic>.
954c1994 1352
94bdecf9 1353 int mg_clear(SV* sv)
954c1994 1354
497711e7 1355=for hackers
94bdecf9 1356Found in file mg.c
497711e7 1357
94bdecf9 1358=item mg_copy
954c1994 1359
94bdecf9 1360Copies the magic from one SV to another. See C<sv_magic>.
954c1994 1361
94bdecf9 1362 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
954c1994 1363
497711e7 1364=for hackers
94bdecf9 1365Found in file mg.c
497711e7 1366
94bdecf9 1367=item mg_find
954c1994 1368
94bdecf9 1369Finds the magic pointer for type matching the SV. See C<sv_magic>.
954c1994 1370
94bdecf9 1371 MAGIC* mg_find(SV* sv, int type)
954c1994 1372
497711e7 1373=for hackers
94bdecf9 1374Found in file mg.c
497711e7 1375
94bdecf9 1376=item mg_free
954c1994 1377
94bdecf9 1378Free any magic storage used by the SV. See C<sv_magic>.
954c1994 1379
94bdecf9 1380 int mg_free(SV* sv)
954c1994 1381
497711e7 1382=for hackers
94bdecf9 1383Found in file mg.c
497711e7 1384
94bdecf9 1385=item mg_get
eebe1485 1386
94bdecf9 1387Do magic after a value is retrieved from the SV. See C<sv_magic>.
282f25c9 1388
94bdecf9 1389 int mg_get(SV* sv)
eebe1485
SC
1390
1391=for hackers
94bdecf9 1392Found in file mg.c
eebe1485 1393
94bdecf9 1394=item mg_length
eebe1485 1395
94bdecf9 1396Report on the SV's length. See C<sv_magic>.
eebe1485 1397
94bdecf9 1398 U32 mg_length(SV* sv)
eebe1485
SC
1399
1400=for hackers
94bdecf9 1401Found in file mg.c
eebe1485 1402
94bdecf9 1403=item mg_magical
954c1994 1404
94bdecf9 1405Turns on the magical status of an SV. See C<sv_magic>.
954c1994 1406
94bdecf9 1407 void mg_magical(SV* sv)
954c1994 1408
497711e7 1409=for hackers
94bdecf9 1410Found in file mg.c
497711e7 1411
94bdecf9 1412=item mg_set
954c1994 1413
94bdecf9 1414Do magic after a value is assigned to the SV. See C<sv_magic>.
954c1994 1415
94bdecf9 1416 int mg_set(SV* sv)
954c1994 1417
497711e7 1418=for hackers
94bdecf9 1419Found in file mg.c
497711e7 1420
94bdecf9 1421=item SvGETMAGIC
954c1994 1422
94bdecf9
JH
1423Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1424argument more than once.
954c1994 1425
94bdecf9 1426 void SvGETMAGIC(SV* sv)
954c1994 1427
497711e7 1428=for hackers
94bdecf9 1429Found in file sv.h
497711e7 1430
a4f1a029
NIS
1431=item SvLOCK
1432
1433Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1434has been loaded.
1435
1436 void SvLOCK(SV* sv)
1437
1438=for hackers
1439Found in file sv.h
1440
94bdecf9 1441=item SvSETMAGIC
7d3fb230 1442
94bdecf9
JH
1443Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
1444argument more than once.
7d3fb230 1445
94bdecf9 1446 void SvSETMAGIC(SV* sv)
7d3fb230
BS
1447
1448=for hackers
94bdecf9 1449Found in file sv.h
7d3fb230 1450
94bdecf9 1451=item SvSetMagicSV
954c1994 1452
94bdecf9 1453Like C<SvSetSV>, but does any set magic required afterwards.
954c1994 1454
94bdecf9 1455 void SvSetMagicSV(SV* dsb, SV* ssv)
954c1994 1456
497711e7 1457=for hackers
94bdecf9 1458Found in file sv.h
497711e7 1459
a4f1a029
NIS
1460=item SvSetMagicSV_nosteal
1461
1462Like C<SvSetMagicSV>, but does any set magic required afterwards.
1463
1464 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1465
1466=for hackers
1467Found in file sv.h
1468
94bdecf9 1469=item SvSetSV
954c1994 1470
94bdecf9
JH
1471Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
1472more than once.
1473
1474 void SvSetSV(SV* dsb, SV* ssv)
954c1994 1475
497711e7 1476=for hackers
94bdecf9 1477Found in file sv.h
497711e7 1478
94bdecf9 1479=item SvSetSV_nosteal
954c1994 1480
94bdecf9
JH
1481Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1482ssv. May evaluate arguments more than once.
954c1994 1483
94bdecf9 1484 void SvSetSV_nosteal(SV* dsv, SV* ssv)
954c1994 1485
497711e7 1486=for hackers
94bdecf9 1487Found in file sv.h
497711e7 1488
a4f1a029
NIS
1489=item SvSHARE
1490
1491Arranges for sv to be shared between threads if a suitable module
1492has been loaded.
1493
1494 void SvSHARE(SV* sv)
1495
1496=for hackers
1497Found in file sv.h
1498
954c1994 1499
94bdecf9 1500=back
954c1994 1501
94bdecf9 1502=head1 Memory Management
954c1994 1503
94bdecf9 1504=over 8
497711e7 1505
94bdecf9 1506=item Copy
954c1994 1507
94bdecf9
JH
1508The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
1509source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1510the type. May fail on overlapping copies. See also C<Move>.
954c1994 1511
94bdecf9 1512 void Copy(void* src, void* dest, int nitems, type)
954c1994 1513
497711e7 1514=for hackers
94bdecf9 1515Found in file handy.h
497711e7 1516
94bdecf9 1517=item Move
954c1994 1518
94bdecf9
JH
1519The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
1520source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1521the type. Can do overlapping moves. See also C<Copy>.
954c1994 1522
94bdecf9 1523 void Move(void* src, void* dest, int nitems, type)
954c1994 1524
497711e7 1525=for hackers
94bdecf9 1526Found in file handy.h
497711e7 1527
94bdecf9 1528=item New
954c1994 1529
94bdecf9 1530The XSUB-writer's interface to the C C<malloc> function.
954c1994 1531
94bdecf9 1532 void New(int id, void* ptr, int nitems, type)
954c1994 1533
497711e7 1534=for hackers
94bdecf9 1535Found in file handy.h
497711e7 1536
94bdecf9 1537=item Newc
954c1994 1538
94bdecf9
JH
1539The XSUB-writer's interface to the C C<malloc> function, with
1540cast.
954c1994 1541
94bdecf9 1542 void Newc(int id, void* ptr, int nitems, type, cast)
954c1994 1543
497711e7 1544=for hackers
94bdecf9 1545Found in file handy.h
954c1994 1546
94bdecf9 1547=item NEWSV
497711e7 1548
94bdecf9
JH
1549Creates a new SV. A non-zero C<len> parameter indicates the number of
1550bytes of preallocated string space the SV should have. An extra byte for a
1551tailing NUL is also reserved. (SvPOK is not set for the SV even if string
1552space is allocated.) The reference count for the new SV is set to 1.
1553C<id> is an integer id between 0 and 1299 (used to identify leaks).
954c1994 1554
954c1994 1555
94bdecf9 1556 SV* NEWSV(int id, STRLEN len)
954c1994 1557
497711e7 1558=for hackers
94bdecf9 1559Found in file handy.h
497711e7 1560
94bdecf9 1561=item Newz
954c1994 1562
94bdecf9
JH
1563The XSUB-writer's interface to the C C<malloc> function. The allocated
1564memory is zeroed with C<memzero>.
954c1994 1565
94bdecf9 1566 void Newz(int id, void* ptr, int nitems, type)
954c1994 1567
497711e7
GS
1568=for hackers
1569Found in file handy.h
1570
9965345d
JH
1571=item Poison
1572
1573Fill up memory with a pattern (byte 0xAB over and over again) that
1574hopefully catches attempts to access uninitialized memory.
1575
1576 void Poison(void* dest, int nitems, type)
1577
1578=for hackers
1579Found in file handy.h
1580
94bdecf9 1581=item Renew
954c1994 1582
94bdecf9 1583The XSUB-writer's interface to the C C<realloc> function.
954c1994 1584
94bdecf9 1585 void Renew(void* ptr, int nitems, type)
954c1994 1586
497711e7
GS
1587=for hackers
1588Found in file handy.h
1589
94bdecf9 1590=item Renewc
954c1994 1591
94bdecf9
JH
1592The XSUB-writer's interface to the C C<realloc> function, with
1593cast.
954c1994 1594
94bdecf9 1595 void Renewc(void* ptr, int nitems, type, cast)
954c1994 1596
497711e7 1597=for hackers
94bdecf9 1598Found in file handy.h
497711e7 1599
94bdecf9 1600=item Safefree
954c1994 1601
94bdecf9 1602The XSUB-writer's interface to the C C<free> function.
954c1994 1603
94bdecf9 1604 void Safefree(void* ptr)
954c1994 1605
497711e7
GS
1606=for hackers
1607Found in file handy.h
1608
94bdecf9 1609=item savepv
954c1994 1610
641d4181
JH
1611Perl's version of C<strdup()>. Returns a pointer to a newly allocated
1612string which is a duplicate of C<pv>. The size of the string is
1613determined by C<strlen()>. The memory allocated for the new string can
1614be freed with the C<Safefree()> function.
954c1994 1615
641d4181 1616 char* savepv(const char* pv)
954c1994 1617
497711e7 1618=for hackers
94bdecf9 1619Found in file util.c
497711e7 1620
94bdecf9 1621=item savepvn
954c1994 1622
641d4181
JH
1623Perl's version of what C<strndup()> would be if it existed. Returns a
1624pointer to a newly allocated string which is a duplicate of the first
1625C<len> bytes from C<pv>. The memory allocated for the new string can be
1626freed with the C<Safefree()> function.
954c1994 1627
641d4181 1628 char* savepvn(const char* pv, I32 len)
954c1994 1629
497711e7 1630=for hackers
94bdecf9 1631Found in file util.c
497711e7 1632
a4f1a029
NIS
1633=item savesharedpv
1634
641d4181
JH
1635A version of C<savepv()> which allocates the duplicate string in memory
1636which is shared between threads.
a4f1a029 1637
641d4181 1638 char* savesharedpv(const char* pv)
a4f1a029
NIS
1639
1640=for hackers
1641Found in file util.c
1642
94bdecf9 1643=item StructCopy
954c1994 1644
94bdecf9 1645This is an architecture-independent macro to copy one structure to another.
954c1994 1646
94bdecf9 1647 void StructCopy(type src, type dest, type)
954c1994 1648
497711e7 1649=for hackers
94bdecf9 1650Found in file handy.h
497711e7 1651
94bdecf9 1652=item Zero
954c1994 1653
94bdecf9
JH
1654The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
1655destination, C<nitems> is the number of items, and C<type> is the type.
954c1994 1656
94bdecf9 1657 void Zero(void* dest, int nitems, type)
954c1994 1658
497711e7 1659=for hackers
94bdecf9 1660Found in file handy.h
497711e7 1661
954c1994 1662
94bdecf9 1663=back
954c1994 1664
94bdecf9 1665=head1 Miscellaneous Functions
954c1994 1666
94bdecf9 1667=over 8
497711e7 1668
94bdecf9 1669=item fbm_compile
8b4ac5a4 1670
94bdecf9
JH
1671Analyses the string in order to make fast searches on it using fbm_instr()
1672-- the Boyer-Moore algorithm.
8b4ac5a4 1673
94bdecf9 1674 void fbm_compile(SV* sv, U32 flags)
8b4ac5a4
JH
1675
1676=for hackers
94bdecf9 1677Found in file util.c
8b4ac5a4 1678
94bdecf9 1679=item fbm_instr
954c1994 1680
94bdecf9
JH
1681Returns the location of the SV in the string delimited by C<str> and
1682C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
1683does not have to be fbm_compiled, but the search will not be as fast
1684then.
954c1994 1685
94bdecf9 1686 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
954c1994 1687
497711e7 1688=for hackers
94bdecf9 1689Found in file util.c
497711e7 1690
94bdecf9 1691=item form
954c1994 1692
94bdecf9
JH
1693Takes a sprintf-style format pattern and conventional
1694(non-SV) arguments and returns the formatted string.
954c1994 1695
94bdecf9 1696 (char *) Perl_form(pTHX_ const char* pat, ...)
954c1994 1697
94bdecf9 1698can be used any place a string (char *) is required:
497711e7 1699
94bdecf9 1700 char * s = Perl_form("%d.%d",major,minor);
954c1994 1701
94bdecf9
JH
1702Uses a single private buffer so if you want to format several strings you
1703must explicitly copy the earlier strings away (and free the copies when you
1704are done).
954c1994 1705
94bdecf9 1706 char* form(const char* pat, ...)
954c1994 1707
497711e7 1708=for hackers
94bdecf9 1709Found in file util.c
497711e7 1710
94bdecf9 1711=item getcwd_sv
954c1994 1712
94bdecf9 1713Fill the sv with current working directory
954c1994 1714
94bdecf9 1715 int getcwd_sv(SV* sv)
954c1994 1716
497711e7 1717=for hackers
94bdecf9 1718Found in file util.c
497711e7 1719
f333445c
JP
1720=item new_version
1721
1722Returns a new version object based on the passed in SV:
1723
1724 SV *sv = new_version(SV *ver);
1725
1726Does not alter the passed in ver SV. See "upg_version" if you
1727want to upgrade the SV.
1728
1729 SV* new_version(SV *ver)
1730
1731=for hackers
1732Found in file util.c
1733
1734=item scan_version
1735
1736Returns a pointer to the next character after the parsed
1737version string, as well as upgrading the passed in SV to
1738an RV.
1739
1740Function must be called with an already existing SV like
1741
1742 sv = NEWSV(92,0);
1743 s = scan_version(s,sv);
1744
1745Performs some preprocessing to the string to ensure that
1746it has the correct characteristics of a version. Flags the
1747object if it contains an underscore (which denotes this
1748is a beta version).
1749
1750 char* scan_version(char *vstr, SV *sv)
1751
1752=for hackers
1753Found in file util.c
1754
94bdecf9 1755=item strEQ
954c1994 1756
94bdecf9 1757Test two strings to see if they are equal. Returns true or false.
954c1994 1758
94bdecf9 1759 bool strEQ(char* s1, char* s2)
954c1994 1760
497711e7 1761=for hackers
94bdecf9 1762Found in file handy.h
497711e7 1763
94bdecf9 1764=item strGE
1c846c1f 1765
94bdecf9
JH
1766Test two strings to see if the first, C<s1>, is greater than or equal to
1767the second, C<s2>. Returns true or false.
1c846c1f 1768
94bdecf9 1769 bool strGE(char* s1, char* s2)
1c846c1f
NIS
1770
1771=for hackers
94bdecf9 1772Found in file handy.h
1c846c1f 1773
94bdecf9 1774=item strGT
954c1994 1775
94bdecf9
JH
1776Test two strings to see if the first, C<s1>, is greater than the second,
1777C<s2>. Returns true or false.
954c1994 1778
94bdecf9 1779 bool strGT(char* s1, char* s2)
954c1994 1780
497711e7 1781=for hackers
94bdecf9 1782Found in file handy.h
497711e7 1783
94bdecf9 1784=item strLE
954c1994 1785
94bdecf9
JH
1786Test two strings to see if the first, C<s1>, is less than or equal to the
1787second, C<s2>. Returns true or false.
954c1994 1788
94bdecf9 1789 bool strLE(char* s1, char* s2)
954c1994 1790
497711e7 1791=for hackers
94bdecf9 1792Found in file handy.h
497711e7 1793
94bdecf9 1794=item strLT
1a3327fb 1795
94bdecf9
JH
1796Test two strings to see if the first, C<s1>, is less than the second,
1797C<s2>. Returns true or false.
1a3327fb 1798
94bdecf9 1799 bool strLT(char* s1, char* s2)
1a3327fb 1800
497711e7 1801=for hackers
94bdecf9 1802Found in file handy.h
497711e7 1803
94bdecf9 1804=item strNE
954c1994 1805
94bdecf9
JH
1806Test two strings to see if they are different. Returns true or
1807false.
1808
1809 bool strNE(char* s1, char* s2)
954c1994 1810
497711e7 1811=for hackers
94bdecf9 1812Found in file handy.h
497711e7 1813
94bdecf9 1814=item strnEQ
954c1994 1815
94bdecf9
JH
1816Test two strings to see if they are equal. The C<len> parameter indicates
1817the number of bytes to compare. Returns true or false. (A wrapper for
1818C<strncmp>).
1819
1820 bool strnEQ(char* s1, char* s2, STRLEN len)
954c1994 1821
497711e7 1822=for hackers
94bdecf9 1823Found in file handy.h
497711e7 1824
94bdecf9 1825=item strnNE
954c1994 1826
94bdecf9
JH
1827Test two strings to see if they are different. The C<len> parameter
1828indicates the number of bytes to compare. Returns true or false. (A
1829wrapper for C<strncmp>).
954c1994 1830
94bdecf9 1831 bool strnNE(char* s1, char* s2, STRLEN len)
954c1994 1832
497711e7
GS
1833=for hackers
1834Found in file handy.h
1835
f333445c
JP
1836=item sv_nolocking
1837
1838Dummy routine which "locks" an SV when there is no locking module present.
1839Exists to avoid test for a NULL function pointer and because it could potentially warn under
1840some level of strict-ness.
1841
1842 void sv_nolocking(SV *)
1843
1844=for hackers
1845Found in file util.c
1846
1847=item sv_nosharing
1848
1849Dummy routine which "shares" an SV when there is no sharing module present.
1850Exists to avoid test for a NULL function pointer and because it could potentially warn under
1851some level of strict-ness.
1852
1853 void sv_nosharing(SV *)
1854
1855=for hackers
1856Found in file util.c
1857
1858=item sv_nounlocking
1859
1860Dummy routine which "unlocks" an SV when there is no locking module present.
1861Exists to avoid test for a NULL function pointer and because it could potentially warn under
1862some level of strict-ness.
1863
1864 void sv_nounlocking(SV *)
1865
1866=for hackers
1867Found in file util.c
1868
1869=item upg_version
1870
1871In-place upgrade of the supplied SV to a version object.
1872
1873 SV *sv = upg_version(SV *sv);
1874
1875Returns a pointer to the upgraded SV.
1876
1877 SV* upg_version(SV *ver)
1878
1879=for hackers
1880Found in file util.c
1881
1882=item vcmp
1883
1884Version object aware cmp. Both operands must already have been
1885converted into version objects.
1886
1887 int vcmp(SV *lvs, SV *rvs)
1888
1889=for hackers
1890Found in file util.c
1891
1892=item vnumify
1893
1894Accepts a version object and returns the normalized floating
1895point representation. Call like:
1896
1897 sv = vnumify(rv);
1898
1899NOTE: you can pass either the object directly or the SV
1900contained within the RV.
1901
1902 SV* vnumify(SV *vs)
1903
1904=for hackers
1905Found in file util.c
1906
1907=item vstringify
1908
1909Accepts a version object and returns the normalized string
1910representation. Call like:
1911
1912 sv = vstringify(rv);
1913
1914NOTE: you can pass either the object directly or the SV
1915contained within the RV.
1916
1917 SV* vstringify(SV *vs)
1918
1919=for hackers
1920Found in file util.c
1921
f4758303 1922
94bdecf9 1923=back
7207e29d 1924
94bdecf9 1925=head1 Numeric functions
7207e29d 1926
94bdecf9 1927=over 8
f4758303 1928
94bdecf9 1929=item grok_bin
f4758303 1930
94bdecf9
JH
1931converts a string representing a binary number to numeric form.
1932
1933On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1934conversion flags, and I<result> should be NULL or a pointer to an NV.
1935The scan stops at the end of the string, or the first invalid character.
1936On return I<*len> is set to the length scanned string, and I<*flags> gives
1937output flags.
1938
1939If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1940and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
1941returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1942and writes the value to I<*result> (or the value is discarded if I<result>
1943is NULL).
1944
1945The hex number may optionally be prefixed with "0b" or "b" unless
1946C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1947C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
1948number may use '_' characters to separate digits.
1949
1950 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
f4758303
JP
1951
1952=for hackers
94bdecf9 1953Found in file numeric.c
f4758303 1954
94bdecf9 1955=item grok_hex
954c1994 1956
94bdecf9
JH
1957converts a string representing a hex number to numeric form.
1958
1959On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1960conversion flags, and I<result> should be NULL or a pointer to an NV.
1961The scan stops at the end of the string, or the first non-hex-digit character.
1962On return I<*len> is set to the length scanned string, and I<*flags> gives
1963output flags.
1964
1965If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1966and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
1967returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1968and writes the value to I<*result> (or the value is discarded if I<result>
1969is NULL).
1970
1971The hex number may optionally be prefixed with "0x" or "x" unless
1972C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1973C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
1974number may use '_' characters to separate digits.
1975
1976 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
954c1994 1977
497711e7 1978=for hackers
94bdecf9 1979Found in file numeric.c
497711e7 1980
94bdecf9 1981=item grok_number
954c1994 1982
94bdecf9
JH
1983Recognise (or not) a number. The type of the number is returned
1984(0 if unrecognised), otherwise it is a bit-ORed combination of
1985IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
1986IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
1987
1988If the value of the number can fit an in UV, it is returned in the *valuep
1989IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
1990will never be set unless *valuep is valid, but *valuep may have been assigned
1991to during processing even though IS_NUMBER_IN_UV is not set on return.
1992If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
1993valuep is non-NULL, but no actual assignment (or SEGV) will occur.
1994
1995IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
1996seen (in which case *valuep gives the true value truncated to an integer), and
1997IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
1998absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
1999number is larger than a UV.
2000
2001 int grok_number(const char *pv, STRLEN len, UV *valuep)
954c1994 2002
497711e7 2003=for hackers
94bdecf9 2004Found in file numeric.c
497711e7 2005
94bdecf9 2006=item grok_numeric_radix
954c1994 2007
94bdecf9
JH
2008Scan and skip for a numeric decimal separator (radix).
2009
2010 bool grok_numeric_radix(const char **sp, const char *send)
954c1994 2011
497711e7 2012=for hackers
94bdecf9 2013Found in file numeric.c
497711e7 2014
94bdecf9 2015=item grok_oct
954c1994 2016
94bdecf9
JH
2017
2018 UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
954c1994 2019
497711e7 2020=for hackers
94bdecf9 2021Found in file numeric.c
497711e7 2022
94bdecf9 2023=item scan_bin
954c1994 2024
94bdecf9
JH
2025For backwards compatibility. Use C<grok_bin> instead.
2026
2027 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
954c1994 2028
497711e7 2029=for hackers
94bdecf9 2030Found in file numeric.c
497711e7 2031
94bdecf9 2032=item scan_hex
954c1994 2033
94bdecf9
JH
2034For backwards compatibility. Use C<grok_hex> instead.
2035
2036 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
954c1994 2037
497711e7 2038=for hackers
94bdecf9 2039Found in file numeric.c
497711e7 2040
94bdecf9 2041=item scan_oct
954c1994 2042
94bdecf9 2043For backwards compatibility. Use C<grok_oct> instead.
954c1994 2044
94bdecf9 2045 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
954c1994 2046
497711e7 2047=for hackers
94bdecf9 2048Found in file numeric.c
497711e7 2049
645c22ef 2050
94bdecf9 2051=back
645c22ef 2052
94bdecf9
JH
2053=head1 Optree Manipulation Functions
2054
2055=over 8
2056
2057=item cv_const_sv
2058
2059If C<cv> is a constant sub eligible for inlining. returns the constant
2060value returned by the sub. Otherwise, returns NULL.
2061
2062Constant subs can be created with C<newCONSTSUB> or as described in
2063L<perlsub/"Constant Functions">.
2064
2065 SV* cv_const_sv(CV* cv)
645c22ef
DM
2066
2067=for hackers
94bdecf9 2068Found in file op.c
645c22ef 2069
94bdecf9 2070=item newCONSTSUB
954c1994 2071
94bdecf9
JH
2072Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
2073eligible for inlining at compile-time.
954c1994 2074
94bdecf9 2075 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
954c1994 2076
497711e7 2077=for hackers
94bdecf9 2078Found in file op.c
497711e7 2079
94bdecf9 2080=item newXS
954c1994 2081
94bdecf9 2082Used by C<xsubpp> to hook up XSUBs as Perl subs.
954c1994 2083
94bdecf9
JH
2084=for hackers
2085Found in file op.c
2086
2087
2088=back
2089
dd2155a4
DM
2090=head1 Pad Data Structures
2091
2092=over 8
2093
2094=item pad_sv
2095
2096Get the value at offset po in the current pad.
2097Use macro PAD_SV instead of calling this function directly.
2098
2099 SV* pad_sv(PADOFFSET po)
2100
2101=for hackers
2102Found in file pad.c
2103
2104
2105=back
2106
94bdecf9
JH
2107=head1 Stack Manipulation Macros
2108
2109=over 8
2110
2111=item dMARK
954c1994 2112
94bdecf9
JH
2113Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
2114C<dORIGMARK>.
954c1994 2115
94bdecf9 2116 dMARK;
954c1994 2117
497711e7 2118=for hackers
94bdecf9 2119Found in file pp.h
497711e7 2120
94bdecf9 2121=item dORIGMARK
954c1994 2122
94bdecf9 2123Saves the original stack mark for the XSUB. See C<ORIGMARK>.
954c1994 2124
94bdecf9 2125 dORIGMARK;
954c1994 2126
497711e7 2127=for hackers
94bdecf9 2128Found in file pp.h
497711e7 2129
94bdecf9 2130=item dSP
954c1994 2131
94bdecf9
JH
2132Declares a local copy of perl's stack pointer for the XSUB, available via
2133the C<SP> macro. See C<SP>.
954c1994 2134
94bdecf9 2135 dSP;
954c1994 2136
497711e7 2137=for hackers
94bdecf9 2138Found in file pp.h
497711e7 2139
94bdecf9 2140=item EXTEND
954c1994 2141
94bdecf9
JH
2142Used to extend the argument stack for an XSUB's return values. Once
2143used, guarantees that there is room for at least C<nitems> to be pushed
2144onto the stack.
954c1994 2145
94bdecf9 2146 void EXTEND(SP, int nitems)
954c1994 2147
497711e7 2148=for hackers
94bdecf9 2149Found in file pp.h
954c1994 2150
94bdecf9 2151=item MARK
954c1994 2152
94bdecf9 2153Stack marker variable for the XSUB. See C<dMARK>.
954c1994 2154
497711e7 2155=for hackers
94bdecf9 2156Found in file pp.h
954c1994 2157
94bdecf9 2158=item ORIGMARK
954c1994 2159
94bdecf9 2160The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 2161
497711e7 2162=for hackers
94bdecf9 2163Found in file pp.h
497711e7 2164
954c1994
GS
2165=item POPi
2166
2167Pops an integer off the stack.
2168
2169 IV POPi
2170
497711e7
GS
2171=for hackers
2172Found in file pp.h
2173
954c1994
GS
2174=item POPl
2175
2176Pops a long off the stack.
2177
2178 long POPl
2179
497711e7
GS
2180=for hackers
2181Found in file pp.h
2182
954c1994
GS
2183=item POPn
2184
2185Pops a double off the stack.
2186
2187 NV POPn
2188
497711e7
GS
2189=for hackers
2190Found in file pp.h
2191
954c1994
GS
2192=item POPp
2193
fa519979
JH
2194Pops a string off the stack. Deprecated. New code should provide
2195a STRLEN n_a and use POPpx.
954c1994
GS
2196
2197 char* POPp
2198
497711e7
GS
2199=for hackers
2200Found in file pp.h
2201
fa519979
JH
2202=item POPpbytex
2203
2204Pops a string off the stack which must consist of bytes i.e. characters < 256.
2205Requires a variable STRLEN n_a in scope.
2206
2207 char* POPpbytex
2208
2209=for hackers
2210Found in file pp.h
2211
2212=item POPpx
2213
2214Pops a string off the stack.
2215Requires a variable STRLEN n_a in scope.
2216
2217 char* POPpx
2218
2219=for hackers
2220Found in file pp.h
2221
954c1994
GS
2222=item POPs
2223
2224Pops an SV off the stack.
2225
2226 SV* POPs
2227
497711e7
GS
2228=for hackers
2229Found in file pp.h
2230
954c1994
GS
2231=item PUSHi
2232
2233Push an integer onto the stack. The stack must have room for this element.
2234Handles 'set' magic. See C<XPUSHi>.
2235
2236 void PUSHi(IV iv)
2237
497711e7
GS
2238=for hackers
2239Found in file pp.h
2240
954c1994
GS
2241=item PUSHMARK
2242
2243Opening bracket for arguments on a callback. See C<PUTBACK> and
2244L<perlcall>.
2245
2246 PUSHMARK;
2247
497711e7
GS
2248=for hackers
2249Found in file pp.h
2250
954c1994
GS
2251=item PUSHn
2252
2253Push a double onto the stack. The stack must have room for this element.
2254Handles 'set' magic. See C<XPUSHn>.
2255
2256 void PUSHn(NV nv)
2257
497711e7
GS
2258=for hackers
2259Found in file pp.h
2260
954c1994
GS
2261=item PUSHp
2262
2263Push a string onto the stack. The stack must have room for this element.
2264The C<len> indicates the length of the string. Handles 'set' magic. See
2265C<XPUSHp>.
2266
2267 void PUSHp(char* str, STRLEN len)
2268
497711e7
GS
2269=for hackers
2270Found in file pp.h
2271
954c1994
GS
2272=item PUSHs
2273
1c846c1f 2274Push an SV onto the stack. The stack must have room for this element.
954c1994
GS
2275Does not handle 'set' magic. See C<XPUSHs>.
2276
2277 void PUSHs(SV* sv)
2278
497711e7
GS
2279=for hackers
2280Found in file pp.h
2281
954c1994
GS
2282=item PUSHu
2283
2284Push an unsigned integer onto the stack. The stack must have room for this
2285element. See C<XPUSHu>.
2286
2287 void PUSHu(UV uv)
2288
497711e7
GS
2289=for hackers
2290Found in file pp.h
2291
954c1994
GS
2292=item PUTBACK
2293
2294Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2295See C<PUSHMARK> and L<perlcall> for other uses.
2296
2297 PUTBACK;
2298
497711e7
GS
2299=for hackers
2300Found in file pp.h
2301
94bdecf9 2302=item SP
d2cc3551 2303
94bdecf9
JH
2304Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2305C<SPAGAIN>.
d2cc3551 2306
94bdecf9
JH
2307=for hackers
2308Found in file pp.h
2309
2310=item SPAGAIN
2311
2312Refetch the stack pointer. Used after a callback. See L<perlcall>.
2313
2314 SPAGAIN;
d2cc3551
JH
2315
2316=for hackers
94bdecf9 2317Found in file pp.h
d2cc3551 2318
94bdecf9 2319=item XPUSHi
954c1994 2320
94bdecf9
JH
2321Push an integer onto the stack, extending the stack if necessary. Handles
2322'set' magic. See C<PUSHi>.
954c1994 2323
94bdecf9 2324 void XPUSHi(IV iv)
954c1994 2325
497711e7 2326=for hackers
94bdecf9 2327Found in file pp.h
497711e7 2328
94bdecf9 2329=item XPUSHn
954c1994 2330
94bdecf9
JH
2331Push a double onto the stack, extending the stack if necessary. Handles
2332'set' magic. See C<PUSHn>.
954c1994 2333
94bdecf9 2334 void XPUSHn(NV nv)
954c1994 2335
497711e7 2336=for hackers
94bdecf9 2337Found in file pp.h
497711e7 2338
94bdecf9 2339=item XPUSHp
954c1994 2340
94bdecf9
JH
2341Push a string onto the stack, extending the stack if necessary. The C<len>
2342indicates the length of the string. Handles 'set' magic. See
2343C<PUSHp>.
954c1994 2344
94bdecf9 2345 void XPUSHp(char* str, STRLEN len)
954c1994 2346
94bdecf9
JH
2347=for hackers
2348Found in file pp.h
2349
2350=item XPUSHs
2351
2352Push an SV onto the stack, extending the stack if necessary. Does not
2353handle 'set' magic. See C<PUSHs>.
2354
2355 void XPUSHs(SV* sv)
954c1994 2356
497711e7 2357=for hackers
94bdecf9 2358Found in file pp.h
497711e7 2359
94bdecf9 2360=item XPUSHu
954c1994 2361
94bdecf9
JH
2362Push an unsigned integer onto the stack, extending the stack if necessary.
2363See C<PUSHu>.
954c1994 2364
94bdecf9
JH
2365 void XPUSHu(UV uv)
2366
2367=for hackers
2368Found in file pp.h
2369
2370=item XSRETURN
2371
2372Return from XSUB, indicating number of items on the stack. This is usually
2373handled by C<xsubpp>.
2374
2375 void XSRETURN(int nitems)
954c1994 2376
497711e7
GS
2377=for hackers
2378Found in file XSUB.h
2379
94bdecf9 2380=item XSRETURN_IV
954c1994 2381
94bdecf9 2382Return an integer from an XSUB immediately. Uses C<XST_mIV>.
954c1994 2383
94bdecf9 2384 void XSRETURN_IV(IV iv)
954c1994 2385
497711e7 2386=for hackers
94bdecf9 2387Found in file XSUB.h
497711e7 2388
94bdecf9 2389=item XSRETURN_NO
954c1994 2390
94bdecf9 2391Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
954c1994 2392
94bdecf9 2393 XSRETURN_NO;
954c1994 2394
497711e7 2395=for hackers
94bdecf9 2396Found in file XSUB.h
497711e7 2397
94bdecf9 2398=item XSRETURN_NV
954c1994 2399
94bdecf9 2400Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994 2401
94bdecf9 2402 void XSRETURN_NV(NV nv)
954c1994 2403
497711e7 2404=for hackers
94bdecf9
JH
2405Found in file XSUB.h
2406
2407=item XSRETURN_PV
2408
2409Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2410
2411 void XSRETURN_PV(char* str)
2412
2413=for hackers
2414Found in file XSUB.h
2415
2416=item XSRETURN_UNDEF
2417
2418Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2419
2420 XSRETURN_UNDEF;
2421
2422=for hackers
2423Found in file XSUB.h
2424
0ee80f49
JH
2425=item XSRETURN_UV
2426
2427Return an integer from an XSUB immediately. Uses C<XST_mUV>.
2428
2429 void XSRETURN_UV(IV uv)
2430
2431=for hackers
2432Found in file XSUB.h
2433
94bdecf9
JH
2434=item XSRETURN_YES
2435
2436Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2437
2438 XSRETURN_YES;
2439
2440=for hackers
2441Found in file XSUB.h
2442
2443=item XST_mIV
2444
2445Place an integer into the specified position C<pos> on the stack. The
2446value is stored in a new mortal SV.
2447
2448 void XST_mIV(int pos, IV iv)
2449
2450=for hackers
2451Found in file XSUB.h
2452
2453=item XST_mNO
2454
2455Place C<&PL_sv_no> into the specified position C<pos> on the
2456stack.
2457
2458 void XST_mNO(int pos)
2459
2460=for hackers
2461Found in file XSUB.h
2462
2463=item XST_mNV
2464
2465Place a double into the specified position C<pos> on the stack. The value
2466is stored in a new mortal SV.
2467
2468 void XST_mNV(int pos, NV nv)
2469
2470=for hackers
2471Found in file XSUB.h
2472
2473=item XST_mPV
2474
2475Place a copy of a string into the specified position C<pos> on the stack.
2476The value is stored in a new mortal SV.
2477
2478 void XST_mPV(int pos, char* str)
2479
2480=for hackers
2481Found in file XSUB.h
2482
2483=item XST_mUNDEF
2484
2485Place C<&PL_sv_undef> into the specified position C<pos> on the
2486stack.
2487
2488 void XST_mUNDEF(int pos)
2489
2490=for hackers
2491Found in file XSUB.h
2492
2493=item XST_mYES
2494
2495Place C<&PL_sv_yes> into the specified position C<pos> on the
2496stack.
2497
2498 void XST_mYES(int pos)
2499
2500=for hackers
2501Found in file XSUB.h
2502
2503
2504=back
2505
2506=head1 SV Flags
497711e7 2507
94bdecf9 2508=over 8
954c1994 2509
94bdecf9 2510=item svtype
954c1994 2511
94bdecf9
JH
2512An enum of flags for Perl types. These are found in the file B<sv.h>
2513in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2514
497711e7 2515=for hackers
94bdecf9 2516Found in file sv.h
6e9d1081 2517
94bdecf9 2518=item SVt_IV
6e9d1081 2519
94bdecf9 2520Integer type flag for scalars. See C<svtype>.
6e9d1081
NC
2521
2522=for hackers
94bdecf9 2523Found in file sv.h
6e9d1081 2524
94bdecf9 2525=item SVt_NV
6e9d1081 2526
94bdecf9 2527Double type flag for scalars. See C<svtype>.
6e9d1081
NC
2528
2529=for hackers
94bdecf9 2530Found in file sv.h
6e9d1081 2531
94bdecf9 2532=item SVt_PV
6e9d1081 2533
94bdecf9 2534Pointer type flag for scalars. See C<svtype>.
6e9d1081
NC
2535
2536=for hackers
94bdecf9 2537Found in file sv.h
cd1ee231 2538
94bdecf9 2539=item SVt_PVAV
cd1ee231 2540
94bdecf9 2541Type flag for arrays. See C<svtype>.
cd1ee231
JH
2542
2543=for hackers
94bdecf9 2544Found in file sv.h
cd1ee231 2545
94bdecf9 2546=item SVt_PVCV
cd1ee231 2547
94bdecf9 2548Type flag for code refs. See C<svtype>.
cd1ee231
JH
2549
2550=for hackers
94bdecf9 2551Found in file sv.h
cd1ee231 2552
94bdecf9 2553=item SVt_PVHV
cd1ee231 2554
94bdecf9 2555Type flag for hashes. See C<svtype>.
cd1ee231
JH
2556
2557=for hackers
94bdecf9 2558Found in file sv.h
cd1ee231 2559
94bdecf9 2560=item SVt_PVMG
cd1ee231 2561
94bdecf9 2562Type flag for blessed scalars. See C<svtype>.
cd1ee231
JH
2563
2564=for hackers
94bdecf9 2565Found in file sv.h
cd1ee231 2566
cd1ee231 2567
94bdecf9 2568=back
cd1ee231 2569
94bdecf9 2570=head1 SV Manipulation Functions
cd1ee231 2571
94bdecf9 2572=over 8
cd1ee231 2573
94bdecf9 2574=item get_sv
cd1ee231 2575
94bdecf9
JH
2576Returns the SV of the specified Perl scalar. If C<create> is set and the
2577Perl variable does not exist then it will be created. If C<create> is not
2578set and the variable does not exist then NULL is returned.
2579
2580NOTE: the perl_ form of this function is deprecated.
2581
2582 SV* get_sv(const char* name, I32 create)
cd1ee231
JH
2583
2584=for hackers
94bdecf9 2585Found in file perl.c
cd1ee231 2586
94bdecf9 2587=item looks_like_number
cd1ee231 2588
94bdecf9
JH
2589Test if the content of an SV looks like a number (or is a number).
2590C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2591non-numeric warning), even if your atof() doesn't grok them.
cd1ee231 2592
94bdecf9 2593 I32 looks_like_number(SV* sv)
cd1ee231
JH
2594
2595=for hackers
94bdecf9 2596Found in file sv.c
2a5a0c38 2597
94bdecf9 2598=item newRV_inc
2a5a0c38 2599
94bdecf9
JH
2600Creates an RV wrapper for an SV. The reference count for the original SV is
2601incremented.
2a5a0c38 2602
94bdecf9 2603 SV* newRV_inc(SV* sv)
2a5a0c38
JH
2604
2605=for hackers
94bdecf9 2606Found in file sv.h
2a5a0c38 2607
94bdecf9 2608=item newRV_noinc
954c1994 2609
94bdecf9
JH
2610Creates an RV wrapper for an SV. The reference count for the original
2611SV is B<not> incremented.
2612
2613 SV* newRV_noinc(SV *sv)
954c1994 2614
497711e7 2615=for hackers
94bdecf9 2616Found in file sv.c
497711e7 2617
94bdecf9 2618=item newSV
954c1994 2619
94bdecf9
JH
2620Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2621with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2622macro.
954c1994 2623
94bdecf9 2624 SV* newSV(STRLEN len)
954c1994 2625
497711e7 2626=for hackers
94bdecf9 2627Found in file sv.c
497711e7 2628
94bdecf9 2629=item newSViv
954c1994 2630
94bdecf9
JH
2631Creates a new SV and copies an integer into it. The reference count for the
2632SV is set to 1.
954c1994 2633
94bdecf9 2634 SV* newSViv(IV i)
954c1994 2635
497711e7 2636=for hackers
94bdecf9 2637Found in file sv.c
497711e7 2638
94bdecf9 2639=item newSVnv
954c1994 2640
94bdecf9
JH
2641Creates a new SV and copies a floating point value into it.
2642The reference count for the SV is set to 1.
954c1994 2643
94bdecf9 2644 SV* newSVnv(NV n)
954c1994 2645
497711e7 2646=for hackers
94bdecf9 2647Found in file sv.c
497711e7 2648
94bdecf9 2649=item newSVpv
954c1994 2650
94bdecf9
JH
2651Creates a new SV and copies a string into it. The reference count for the
2652SV is set to 1. If C<len> is zero, Perl will compute the length using
2653strlen(). For efficiency, consider using C<newSVpvn> instead.
954c1994 2654
94bdecf9 2655 SV* newSVpv(const char* s, STRLEN len)
954c1994 2656
497711e7 2657=for hackers
94bdecf9 2658Found in file sv.c
497711e7 2659
94bdecf9 2660=item newSVpvf
954c1994 2661
94bdecf9
JH
2662Creates a new SV and initializes it with the string formatted like
2663C<sprintf>.
954c1994 2664
94bdecf9 2665 SV* newSVpvf(const char* pat, ...)
954c1994 2666
497711e7 2667=for hackers
94bdecf9 2668Found in file sv.c
497711e7 2669
94bdecf9 2670=item newSVpvn
954c1994 2671
94bdecf9
JH
2672Creates a new SV and copies a string into it. The reference count for the
2673SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
2674string. You are responsible for ensuring that the source string is at least
2675C<len> bytes long.
954c1994 2676
94bdecf9 2677 SV* newSVpvn(const char* s, STRLEN len)
954c1994 2678
497711e7 2679=for hackers
94bdecf9 2680Found in file sv.c
497711e7 2681
94bdecf9 2682=item newSVpvn_share
954c1994 2683
94bdecf9
JH
2684Creates a new SV with its SvPVX pointing to a shared string in the string
2685table. If the string does not already exist in the table, it is created
2686first. Turns on READONLY and FAKE. The string's hash is stored in the UV
2687slot of the SV; if the C<hash> parameter is non-zero, that value is used;
2688otherwise the hash is computed. The idea here is that as the string table
2689is used for shared hash keys these strings will have SvPVX == HeKEY and
2690hash lookup will avoid string compare.
954c1994 2691
94bdecf9 2692 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
954c1994 2693
497711e7 2694=for hackers
94bdecf9 2695Found in file sv.c
497711e7 2696
94bdecf9 2697=item newSVrv
954c1994 2698
94bdecf9
JH
2699Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
2700it will be upgraded to one. If C<classname> is non-null then the new SV will
2701be blessed in the specified package. The new SV is returned and its
2702reference count is 1.
954c1994 2703
94bdecf9 2704 SV* newSVrv(SV* rv, const char* classname)
954c1994 2705
497711e7 2706=for hackers
94bdecf9 2707Found in file sv.c
497711e7 2708
94bdecf9 2709=item newSVsv
954c1994 2710
94bdecf9
JH
2711Creates a new SV which is an exact duplicate of the original SV.
2712(Uses C<sv_setsv>).
954c1994 2713
94bdecf9 2714 SV* newSVsv(SV* old)
954c1994 2715
497711e7 2716=for hackers
94bdecf9 2717Found in file sv.c
497711e7 2718
94bdecf9 2719=item newSVuv
954c1994 2720
94bdecf9
JH
2721Creates a new SV and copies an unsigned integer into it.
2722The reference count for the SV is set to 1.
954c1994 2723
94bdecf9 2724 SV* newSVuv(UV u)
954c1994 2725
497711e7 2726=for hackers
94bdecf9 2727Found in file sv.c
497711e7 2728
954c1994
GS
2729=item SvCUR
2730
2731Returns the length of the string which is in the SV. See C<SvLEN>.
2732
2733 STRLEN SvCUR(SV* sv)
2734
497711e7
GS
2735=for hackers
2736Found in file sv.h
2737
954c1994
GS
2738=item SvCUR_set
2739
2740Set the length of the string which is in the SV. See C<SvCUR>.
2741
2742 void SvCUR_set(SV* sv, STRLEN len)
2743
497711e7
GS
2744=for hackers
2745Found in file sv.h
2746
94bdecf9 2747=item SvEND
954c1994 2748
94bdecf9
JH
2749Returns a pointer to the last character in the string which is in the SV.
2750See C<SvCUR>. Access the character as *(SvEND(sv)).
954c1994 2751
94bdecf9 2752 char* SvEND(SV* sv)
954c1994 2753
497711e7
GS
2754=for hackers
2755Found in file sv.h
2756
954c1994
GS
2757=item SvGROW
2758
2759Expands the character buffer in the SV so that it has room for the
2760indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 2761NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
2762Returns a pointer to the character buffer.
2763
679ac26e 2764 char * SvGROW(SV* sv, STRLEN len)
954c1994 2765
497711e7
GS
2766=for hackers
2767Found in file sv.h
2768
954c1994
GS
2769=item SvIOK
2770
2771Returns a boolean indicating whether the SV contains an integer.
2772
2773 bool SvIOK(SV* sv)
2774
497711e7
GS
2775=for hackers
2776Found in file sv.h
2777
954c1994
GS
2778=item SvIOKp
2779
2780Returns a boolean indicating whether the SV contains an integer. Checks
2781the B<private> setting. Use C<SvIOK>.
2782
2783 bool SvIOKp(SV* sv)
2784
497711e7
GS
2785=for hackers
2786Found in file sv.h
2787
e331fc52
JH
2788=item SvIOK_notUV
2789
f4758303 2790Returns a boolean indicating whether the SV contains a signed integer.
e331fc52
JH
2791
2792 void SvIOK_notUV(SV* sv)
2793
2794=for hackers
2795Found in file sv.h
2796
954c1994
GS
2797=item SvIOK_off
2798
2799Unsets the IV status of an SV.
2800
2801 void SvIOK_off(SV* sv)
2802
497711e7
GS
2803=for hackers
2804Found in file sv.h
2805
954c1994
GS
2806=item SvIOK_on
2807
2808Tells an SV that it is an integer.
2809
2810 void SvIOK_on(SV* sv)
2811
497711e7
GS
2812=for hackers
2813Found in file sv.h
2814
954c1994
GS
2815=item SvIOK_only
2816
2817Tells an SV that it is an integer and disables all other OK bits.
2818
2819 void SvIOK_only(SV* sv)
2820
497711e7
GS
2821=for hackers
2822Found in file sv.h
2823
e331fc52
JH
2824=item SvIOK_only_UV
2825
2826Tells and SV that it is an unsigned integer and disables all other OK bits.
2827
2828 void SvIOK_only_UV(SV* sv)
2829
2830=for hackers
2831Found in file sv.h
2832
2833=item SvIOK_UV
2834
2835Returns a boolean indicating whether the SV contains an unsigned integer.
2836
2837 void SvIOK_UV(SV* sv)
2838
2839=for hackers
2840Found in file sv.h
2841
19dbb8f1
NC
2842=item SvIsCOW
2843
2844Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
2845hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
2846COW)
2847
2848 bool SvIsCOW(SV* sv)
2849
2850=for hackers
2851Found in file sv.h
2852
2853=item SvIsCOW_shared_hash
2854
2855Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
2856scalar.
2857
2858 bool SvIsCOW_shared_hash(SV* sv)
2859
2860=for hackers
2861Found in file sv.h
2862
954c1994
GS
2863=item SvIV
2864
645c22ef
DM
2865Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2866version which guarantees to evaluate sv only once.
954c1994
GS
2867
2868 IV SvIV(SV* sv)
2869
497711e7
GS
2870=for hackers
2871Found in file sv.h
2872
6a477168 2873=item SvIVx
954c1994 2874
6a477168
HS
2875Coerces the given SV to an integer and returns it. Guarantees to evaluate
2876sv only once. Use the more efficient C<SvIV> otherwise.
954c1994 2877
6a477168 2878 IV SvIVx(SV* sv)
954c1994 2879
497711e7
GS
2880=for hackers
2881Found in file sv.h
2882
6a477168 2883=item SvIVX
645c22ef 2884
6a477168
HS
2885Returns the raw value in the SV's IV slot, without checks or conversions.
2886Only use when you are sure SvIOK is true. See also C<SvIV()>.
645c22ef 2887
6a477168 2888 IV SvIVX(SV* sv)
645c22ef
DM
2889
2890=for hackers
2891Found in file sv.h
2892
954c1994
GS
2893=item SvLEN
2894
91e74348
JH
2895Returns the size of the string buffer in the SV, not including any part
2896attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
2897
2898 STRLEN SvLEN(SV* sv)
2899
497711e7
GS
2900=for hackers
2901Found in file sv.h
2902
954c1994
GS
2903=item SvNIOK
2904
2905Returns a boolean indicating whether the SV contains a number, integer or
2906double.
2907
2908 bool SvNIOK(SV* sv)
2909
497711e7
GS
2910=for hackers
2911Found in file sv.h
2912
954c1994
GS
2913=item SvNIOKp
2914
2915Returns a boolean indicating whether the SV contains a number, integer or
2916double. Checks the B<private> setting. Use C<SvNIOK>.
2917
2918 bool SvNIOKp(SV* sv)
2919
497711e7
GS
2920=for hackers
2921Found in file sv.h
2922
954c1994
GS
2923=item SvNIOK_off
2924
2925Unsets the NV/IV status of an SV.
2926
2927 void SvNIOK_off(SV* sv)
2928
497711e7
GS
2929=for hackers
2930Found in file sv.h
2931
954c1994
GS
2932=item SvNOK
2933
2934Returns a boolean indicating whether the SV contains a double.
2935
2936 bool SvNOK(SV* sv)
2937
497711e7
GS
2938=for hackers
2939Found in file sv.h
2940
954c1994
GS
2941=item SvNOKp
2942
2943Returns a boolean indicating whether the SV contains a double. Checks the
2944B<private> setting. Use C<SvNOK>.
2945
2946 bool SvNOKp(SV* sv)
2947
497711e7
GS
2948=for hackers
2949Found in file sv.h
2950
954c1994
GS
2951=item SvNOK_off
2952
2953Unsets the NV status of an SV.
2954
2955 void SvNOK_off(SV* sv)
2956
497711e7
GS
2957=for hackers
2958Found in file sv.h
2959
954c1994
GS
2960=item SvNOK_on
2961
2962Tells an SV that it is a double.
2963
2964 void SvNOK_on(SV* sv)
2965
497711e7
GS
2966=for hackers
2967Found in file sv.h
2968
954c1994
GS
2969=item SvNOK_only
2970
2971Tells an SV that it is a double and disables all other OK bits.
2972
2973 void SvNOK_only(SV* sv)
2974
497711e7
GS
2975=for hackers
2976Found in file sv.h
2977
954c1994
GS
2978=item SvNV
2979
645c22ef
DM
2980Coerce the given SV to a double and return it. See C<SvNVx> for a version
2981which guarantees to evaluate sv only once.
954c1994
GS
2982
2983 NV SvNV(SV* sv)
2984
497711e7
GS
2985=for hackers
2986Found in file sv.h
2987
6a477168 2988=item SvNVX
645c22ef 2989
6a477168
HS
2990Returns the raw value in the SV's NV slot, without checks or conversions.
2991Only use when you are sure SvNOK is true. See also C<SvNV()>.
645c22ef 2992
6a477168 2993 NV SvNVX(SV* sv)
645c22ef
DM
2994
2995=for hackers
2996Found in file sv.h
2997
6a477168 2998=item SvNVx
954c1994 2999
6a477168
HS
3000Coerces the given SV to a double and returns it. Guarantees to evaluate
3001sv only once. Use the more efficient C<SvNV> otherwise.
954c1994 3002
6a477168 3003 NV SvNVx(SV* sv)
954c1994 3004
497711e7
GS
3005=for hackers
3006Found in file sv.h
3007
954c1994
GS
3008=item SvOK
3009
3010Returns a boolean indicating whether the value is an SV.
3011
3012 bool SvOK(SV* sv)
3013
497711e7
GS
3014=for hackers
3015Found in file sv.h
3016
954c1994
GS
3017=item SvOOK
3018
3019Returns a boolean indicating whether the SvIVX is a valid offset value for
3020the SvPVX. This hack is used internally to speed up removal of characters
3021from the beginning of a SvPV. When SvOOK is true, then the start of the
3022allocated string buffer is really (SvPVX - SvIVX).
3023
3024 bool SvOOK(SV* sv)
3025
497711e7
GS
3026=for hackers
3027Found in file sv.h
3028
954c1994
GS
3029=item SvPOK
3030
3031Returns a boolean indicating whether the SV contains a character
3032string.
3033
3034 bool SvPOK(SV* sv)
3035
497711e7
GS
3036=for hackers
3037Found in file sv.h
3038
954c1994
GS
3039=item SvPOKp
3040
3041Returns a boolean indicating whether the SV contains a character string.
3042Checks the B<private> setting. Use C<SvPOK>.
3043
3044 bool SvPOKp(SV* sv)
3045
497711e7
GS
3046=for hackers
3047Found in file sv.h
3048
954c1994
GS
3049=item SvPOK_off
3050
3051Unsets the PV status of an SV.
3052
3053 void SvPOK_off(SV* sv)
3054
497711e7
GS
3055=for hackers
3056Found in file sv.h
3057
954c1994
GS
3058=item SvPOK_on
3059
3060Tells an SV that it is a string.
3061
3062 void SvPOK_on(SV* sv)
3063
497711e7
GS
3064=for hackers
3065Found in file sv.h
3066
954c1994
GS
3067=item SvPOK_only
3068
3069Tells an SV that it is a string and disables all other OK bits.
1e54db1a 3070Will also turn off the UTF-8 status.
954c1994
GS
3071
3072 void SvPOK_only(SV* sv)
3073
497711e7
GS
3074=for hackers
3075Found in file sv.h
3076
914184e1
JH
3077=item SvPOK_only_UTF8
3078
d5ce4a7c 3079Tells an SV that it is a string and disables all other OK bits,
1e54db1a 3080and leaves the UTF-8 status as it was.
f1a1024e 3081
914184e1
JH
3082 void SvPOK_only_UTF8(SV* sv)
3083
3084=for hackers
3085Found in file sv.h
3086
954c1994
GS
3087=item SvPV
3088
12b7c5c7
JH
3089Returns a pointer to the string in the SV, or a stringified form of
3090the SV if the SV does not contain a string. The SV may cache the
3091stringified version becoming C<SvPOK>. Handles 'get' magic. See also
645c22ef 3092C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
3093
3094 char* SvPV(SV* sv, STRLEN len)
3095
497711e7
GS
3096=for hackers
3097Found in file sv.h
3098
645c22ef
DM
3099=item SvPVbyte
3100
3101Like C<SvPV>, but converts sv to byte representation first if necessary.
3102
3103 char* SvPVbyte(SV* sv, STRLEN len)
3104
3105=for hackers
3106Found in file sv.h
3107
3108=item SvPVbytex
3109
3110Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 3111Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
3112otherwise.
3113
645c22ef
DM
3114 char* SvPVbytex(SV* sv, STRLEN len)
3115
3116=for hackers
3117Found in file sv.h
3118
3119=item SvPVbytex_force
3120
3121Like C<SvPV_force>, but converts sv to byte representation first if necessary.
d1be9408 3122Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
645c22ef
DM
3123otherwise.
3124
3125 char* SvPVbytex_force(SV* sv, STRLEN len)
3126
3127=for hackers
3128Found in file sv.h
3129
3130=item SvPVbyte_force
3131
3132Like C<SvPV_force>, but converts sv to byte representation first if necessary.
3133
3134 char* SvPVbyte_force(SV* sv, STRLEN len)
3135
3136=for hackers
3137Found in file sv.h
3138
3139=item SvPVbyte_nolen
3140
3141Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
3142
1fdc5aa6 3143 char* SvPVbyte_nolen(SV* sv)
645c22ef
DM
3144
3145=for hackers
3146Found in file sv.h
3147
3148=item SvPVutf8
3149
1fdc5aa6 3150Like C<SvPV>, but converts sv to utf8 first if necessary.
645c22ef
DM
3151
3152 char* SvPVutf8(SV* sv, STRLEN len)
3153
3154=for hackers
3155Found in file sv.h
3156
3157=item SvPVutf8x
3158
1fdc5aa6 3159Like C<SvPV>, but converts sv to utf8 first if necessary.
d1be9408 3160Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
645c22ef
DM
3161otherwise.
3162
3163 char* SvPVutf8x(SV* sv, STRLEN len)
3164
3165=for hackers
3166Found in file sv.h
3167
3168=item SvPVutf8x_force
3169
1fdc5aa6 3170Like C<SvPV_force>, but converts sv to utf8 first if necessary.
d1be9408 3171Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
645c22ef
DM
3172otherwise.
3173
3174 char* SvPVutf8x_force(SV* sv, STRLEN len)
3175
3176=for hackers
3177Found in file sv.h
3178
3179=item SvPVutf8_force
3180
1fdc5aa6 3181Like C<SvPV_force>, but converts sv to utf8 first if necessary.
645c22ef
DM
3182
3183 char* SvPVutf8_force(SV* sv, STRLEN len)
3184
3185=for hackers
3186Found in file sv.h
3187
3188=item SvPVutf8_nolen
3189
1fdc5aa6 3190Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
645c22ef 3191
1fdc5aa6 3192 char* SvPVutf8_nolen(SV* sv)
645c22ef
DM
3193
3194=for hackers
3195Found in file sv.h
3196
6a477168 3197=item SvPVx
645c22ef 3198
6a477168 3199A version of C<SvPV> which guarantees to evaluate sv only once.
645c22ef 3200
6a477168 3201 char* SvPVx(SV* sv, STRLEN len)
645c22ef
DM
3202
3203=for hackers
3204Found in file sv.h
3205
6a477168 3206=item SvPVX
954c1994 3207
6a477168
HS
3208Returns a pointer to the physical string in the SV. The SV must contain a
3209string.
954c1994 3210
6a477168 3211 char* SvPVX(SV* sv)
954c1994 3212
497711e7
GS
3213=for hackers
3214Found in file sv.h
3215
954c1994
GS
3216=item SvPV_force
3217
12b7c5c7
JH
3218Like C<SvPV> but will force the SV into containing just a string
3219(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3220directly.
954c1994
GS
3221
3222 char* SvPV_force(SV* sv, STRLEN len)
3223
497711e7
GS
3224=for hackers
3225Found in file sv.h
3226
645c22ef
DM
3227=item SvPV_force_nomg
3228
12b7c5c7
JH
3229Like C<SvPV> but will force the SV into containing just a string
3230(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3231directly. Doesn't process magic.
645c22ef
DM
3232
3233 char* SvPV_force_nomg(SV* sv, STRLEN len)
3234
3235=for hackers
3236Found in file sv.h
3237
954c1994
GS
3238=item SvPV_nolen
3239
12b7c5c7
JH
3240Returns a pointer to the string in the SV, or a stringified form of
3241the SV if the SV does not contain a string. The SV may cache the
3242stringified form becoming C<SvPOK>. Handles 'get' magic.
954c1994
GS
3243
3244 char* SvPV_nolen(SV* sv)
3245
497711e7
GS
3246=for hackers
3247Found in file sv.h
3248
954c1994
GS
3249=item SvREFCNT
3250
3251Returns the value of the object's reference count.
3252
3253 U32 SvREFCNT(SV* sv)
3254
497711e7
GS
3255=for hackers
3256Found in file sv.h
3257
954c1994
GS
3258=item SvREFCNT_dec
3259
3260Decrements the reference count of the given SV.
3261
3262 void SvREFCNT_dec(SV* sv)
3263
497711e7
GS
3264=for hackers
3265Found in file sv.h
3266
954c1994
GS
3267=item SvREFCNT_inc
3268
3269Increments the reference count of the given SV.
3270
3271 SV* SvREFCNT_inc(SV* sv)
3272
497711e7
GS
3273=for hackers
3274Found in file sv.h
3275
954c1994
GS
3276=item SvROK
3277
3278Tests if the SV is an RV.
3279
3280 bool SvROK(SV* sv)
3281
497711e7
GS
3282=for hackers
3283Found in file sv.h
3284
954c1994
GS
3285=item SvROK_off
3286
3287Unsets the RV status of an SV.
3288
3289 void SvROK_off(SV* sv)
3290
497711e7
GS
3291=for hackers
3292Found in file sv.h
3293
954c1994
GS
3294=item SvROK_on
3295
3296Tells an SV that it is an RV.
3297
3298 void SvROK_on(SV* sv)
3299
497711e7
GS
3300=for hackers
3301Found in file sv.h
3302
954c1994
GS
3303=item SvRV
3304
3305Dereferences an RV to return the SV.
3306
3307 SV* SvRV(SV* sv)
3308
497711e7
GS
3309=for hackers
3310Found in file sv.h
3311
954c1994
GS
3312=item SvSTASH
3313
3314Returns the stash of the SV.
3315
3316 HV* SvSTASH(SV* sv)
3317
497711e7
GS
3318=for hackers
3319Found in file sv.h
3320
954c1994
GS
3321=item SvTAINT
3322
c55831ac 3323Taints an SV if tainting is enabled.
954c1994
GS
3324
3325 void SvTAINT(SV* sv)
3326
497711e7
GS
3327=for hackers
3328Found in file sv.h
3329
954c1994
GS
3330=item SvTAINTED
3331
3332Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3333not.
3334
3335 bool SvTAINTED(SV* sv)
3336
497711e7
GS
3337=for hackers
3338Found in file sv.h
3339
954c1994
GS
3340=item SvTAINTED_off
3341
3342Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3343some of Perl's fundamental security features. XS module authors should not
3344use this function unless they fully understand all the implications of
3345unconditionally untainting the value. Untainting should be done in the
3346standard perl fashion, via a carefully crafted regexp, rather than directly
3347untainting variables.
3348
3349 void SvTAINTED_off(SV* sv)
3350
497711e7
GS
3351=for hackers
3352Found in file sv.h
3353
954c1994
GS
3354=item SvTAINTED_on
3355
c55831ac 3356Marks an SV as tainted if tainting is enabled.
954c1994
GS
3357
3358 void SvTAINTED_on(SV* sv)
3359
497711e7
GS
3360=for hackers
3361Found in file sv.h
3362
954c1994
GS
3363=item SvTRUE
3364
3365Returns a boolean indicating whether Perl would evaluate the SV as true or
3366false, defined or undefined. Does not handle 'get' magic.
3367
3368 bool SvTRUE(SV* sv)
3369
497711e7
GS
3370=for hackers
3371Found in file sv.h
3372
9f4817db 3373=item SvTYPE
af3c7592 3374
9f4817db
JH
3375Returns the type of the SV. See C<svtype>.
3376
3377 svtype SvTYPE(SV* sv)
954c1994 3378
497711e7
GS
3379=for hackers
3380Found in file sv.h
3381
a4f1a029
NIS
3382=item SvUNLOCK
3383
3384Releases a mutual exclusion lock on sv if a suitable module
3385has been loaded.
3386
3387
3388 void SvUNLOCK(SV* sv)
3389
3390=for hackers
3391Found in file sv.h
3392
a8586c98
JH
3393=item SvUOK
3394
3395Returns a boolean indicating whether the SV contains an unsigned integer.
3396
3397 void SvUOK(SV* sv)
3398
3399=for hackers
3400Found in file sv.h
3401
954c1994
GS
3402=item SvUPGRADE
3403
3404Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
3405perform the upgrade if necessary. See C<svtype>.
3406
3407 void SvUPGRADE(SV* sv, svtype type)
3408
497711e7
GS
3409=for hackers
3410Found in file sv.h
3411
914184e1
JH
3412=item SvUTF8
3413
3414Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3415
3416 void SvUTF8(SV* sv)
3417
3418=for hackers
3419Found in file sv.h
3420
3421=item SvUTF8_off
3422
1e54db1a 3423Unsets the UTF-8 status of an SV.
914184e1
JH
3424
3425 void SvUTF8_off(SV *sv)
3426
3427=for hackers
3428Found in file sv.h
3429
3430=item SvUTF8_on
3431
1e54db1a 3432Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
d5ce4a7c 3433Do not use frivolously.
914184e1
JH
3434
3435 void SvUTF8_on(SV *sv)
3436
3437=for hackers
3438Found in file sv.h
3439
954c1994
GS
3440=item SvUV
3441
645c22ef
DM
3442Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
3443for a version which guarantees to evaluate sv only once.
954c1994
GS
3444
3445 UV SvUV(SV* sv)
3446
497711e7
GS
3447=for hackers
3448Found in file sv.h
3449
b0f01acb
JP
3450=item SvUVX
3451
3452Returns the raw value in the SV's UV slot, without checks or conversions.
3453Only use when you are sure SvIOK is true. See also C<SvUV()>.
3454
3455 UV SvUVX(SV* sv)
3456
3457=for hackers
3458Found in file sv.h
3459
d6721266 3460=item SvUVx
954c1994 3461
d6721266
DM
3462Coerces the given SV to an unsigned integer and returns it. Guarantees to
3463evaluate sv only once. Use the more efficient C<SvUV> otherwise.
954c1994 3464
d6721266 3465 UV SvUVx(SV* sv)
954c1994 3466
497711e7
GS
3467=for hackers
3468Found in file sv.h
3469
b0f01acb 3470=item SvVOK
645c22ef 3471
b0f01acb 3472Returns a boolean indicating whether the SV contains a v-string.
645c22ef 3473
b0f01acb 3474 bool SvVOK(SV* sv)
645c22ef
DM
3475
3476=for hackers
3477Found in file sv.h
3478
3479=item sv_2bool
3480
3481This function is only called on magical items, and is only used by
8cf8f3d1 3482sv_true() or its macro equivalent.
645c22ef
DM
3483
3484 bool sv_2bool(SV* sv)
3485
3486=for hackers
3487Found in file sv.c
3488
3489=item sv_2cv
3490
3491Using various gambits, try to get a CV from an SV; in addition, try if
3492possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3493
3494 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3495
3496=for hackers
3497Found in file sv.c
3498