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