This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Understand "ok" with no number
[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
94bdecf9 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
a02a5408 1606 void Newx(void* ptr, int nitems, type)
954c1994 1607
497711e7 1608=for hackers
94bdecf9 1609Found in file handy.h
497711e7 1610
a02a5408 1611=item Newxc
954c1994 1612
94bdecf9
JH
1613The XSUB-writer's interface to the C C<malloc> function, with
1614cast.
954c1994 1615
a02a5408 1616 void Newxc(void* ptr, int nitems, type, cast)
954c1994 1617
497711e7 1618=for hackers
94bdecf9 1619Found in file handy.h
954c1994 1620
a02a5408 1621=item Newxz
954c1994 1622
94bdecf9
JH
1623The XSUB-writer's interface to the C C<malloc> function. The allocated
1624memory is zeroed with C<memzero>.
954c1994 1625
a02a5408
JC
1626In 5.9.3, we removed the 1st parameter, a debug aid, from the api. It
1627was used to uniquely identify each usage of these allocation
1628functions, but was deemed unnecessary with the availability of better
1629memory tracking tools, valgrind for example.
1630
1631 void Newxz(void* ptr, int nitems, type)
954c1994 1632
497711e7
GS
1633=for hackers
1634Found in file handy.h
1635
9965345d
JH
1636=item Poison
1637
1638Fill up memory with a pattern (byte 0xAB over and over again) that
1639hopefully catches attempts to access uninitialized memory.
1640
1641 void Poison(void* dest, int nitems, type)
1642
1643=for hackers
1644Found in file handy.h
1645
94bdecf9 1646=item Renew
954c1994 1647
94bdecf9 1648The XSUB-writer's interface to the C C<realloc> function.
954c1994 1649
94bdecf9 1650 void Renew(void* ptr, int nitems, type)
954c1994 1651
497711e7
GS
1652=for hackers
1653Found in file handy.h
1654
94bdecf9 1655=item Renewc
954c1994 1656
94bdecf9
JH
1657The XSUB-writer's interface to the C C<realloc> function, with
1658cast.
954c1994 1659
94bdecf9 1660 void Renewc(void* ptr, int nitems, type, cast)
954c1994 1661
497711e7 1662=for hackers
94bdecf9 1663Found in file handy.h
497711e7 1664
94bdecf9 1665=item Safefree
954c1994 1666
94bdecf9 1667The XSUB-writer's interface to the C C<free> function.
954c1994 1668
94bdecf9 1669 void Safefree(void* ptr)
954c1994 1670
497711e7
GS
1671=for hackers
1672Found in file handy.h
1673
94bdecf9 1674=item savepv
954c1994 1675
641d4181
JH
1676Perl's version of C<strdup()>. Returns a pointer to a newly allocated
1677string which is a duplicate of C<pv>. The size of the string is
1678determined by C<strlen()>. The memory allocated for the new string can
1679be freed with the C<Safefree()> function.
954c1994 1680
641d4181 1681 char* savepv(const char* pv)
954c1994 1682
497711e7 1683=for hackers
94bdecf9 1684Found in file util.c
497711e7 1685
94bdecf9 1686=item savepvn
954c1994 1687
641d4181
JH
1688Perl's version of what C<strndup()> would be if it existed. Returns a
1689pointer to a newly allocated string which is a duplicate of the first
1690C<len> bytes from C<pv>. The memory allocated for the new string can be
1691freed with the C<Safefree()> function.
954c1994 1692
641d4181 1693 char* savepvn(const char* pv, I32 len)
954c1994 1694
497711e7 1695=for hackers
94bdecf9 1696Found in file util.c
497711e7 1697
a4f1a029
NIS
1698=item savesharedpv
1699
641d4181
JH
1700A version of C<savepv()> which allocates the duplicate string in memory
1701which is shared between threads.
a4f1a029 1702
641d4181 1703 char* savesharedpv(const char* pv)
a4f1a029
NIS
1704
1705=for hackers
1706Found in file util.c
1707
766f8916
MHM
1708=item savesvpv
1709
9c2fe30c 1710A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
766f8916
MHM
1711the passed in SV using C<SvPV()>
1712
1713 char* savesvpv(SV* sv)
1714
1715=for hackers
1716Found in file util.c
1717
94bdecf9 1718=item StructCopy
954c1994 1719
94bdecf9 1720This is an architecture-independent macro to copy one structure to another.
954c1994 1721
94bdecf9 1722 void StructCopy(type src, type dest, type)
954c1994 1723
497711e7 1724=for hackers
94bdecf9 1725Found in file handy.h
497711e7 1726
94bdecf9 1727=item Zero
954c1994 1728
94bdecf9
JH
1729The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
1730destination, C<nitems> is the number of items, and C<type> is the type.
954c1994 1731
94bdecf9 1732 void Zero(void* dest, int nitems, type)
954c1994 1733
497711e7 1734=for hackers
94bdecf9 1735Found in file handy.h
497711e7 1736
e90e2364
NC
1737=item ZeroD
1738
1739Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
1740optimise.
1741
1742 void * ZeroD(void* dest, int nitems, type)
1743
1744=for hackers
1745Found in file handy.h
1746
954c1994 1747
94bdecf9 1748=back
954c1994 1749
94bdecf9 1750=head1 Miscellaneous Functions
954c1994 1751
94bdecf9 1752=over 8
497711e7 1753
94bdecf9 1754=item fbm_compile
8b4ac5a4 1755
94bdecf9
JH
1756Analyses the string in order to make fast searches on it using fbm_instr()
1757-- the Boyer-Moore algorithm.
8b4ac5a4 1758
94bdecf9 1759 void fbm_compile(SV* sv, U32 flags)
8b4ac5a4
JH
1760
1761=for hackers
94bdecf9 1762Found in file util.c
8b4ac5a4 1763
94bdecf9 1764=item fbm_instr
954c1994 1765
94bdecf9
JH
1766Returns the location of the SV in the string delimited by C<str> and
1767C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
1768does not have to be fbm_compiled, but the search will not be as fast
1769then.
954c1994 1770
94bdecf9 1771 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
954c1994 1772
497711e7 1773=for hackers
94bdecf9 1774Found in file util.c
497711e7 1775
94bdecf9 1776=item form
954c1994 1777
94bdecf9
JH
1778Takes a sprintf-style format pattern and conventional
1779(non-SV) arguments and returns the formatted string.
954c1994 1780
94bdecf9 1781 (char *) Perl_form(pTHX_ const char* pat, ...)
954c1994 1782
94bdecf9 1783can be used any place a string (char *) is required:
497711e7 1784
94bdecf9 1785 char * s = Perl_form("%d.%d",major,minor);
954c1994 1786
94bdecf9
JH
1787Uses a single private buffer so if you want to format several strings you
1788must explicitly copy the earlier strings away (and free the copies when you
1789are done).
954c1994 1790
94bdecf9 1791 char* form(const char* pat, ...)
954c1994 1792
497711e7 1793=for hackers
94bdecf9 1794Found in file util.c
497711e7 1795
94bdecf9 1796=item getcwd_sv
954c1994 1797
94bdecf9 1798Fill the sv with current working directory
954c1994 1799
94bdecf9 1800 int getcwd_sv(SV* sv)
954c1994 1801
497711e7 1802=for hackers
94bdecf9 1803Found in file util.c
497711e7 1804
f333445c
JP
1805=item new_version
1806
1807Returns a new version object based on the passed in SV:
1808
1809 SV *sv = new_version(SV *ver);
1810
1811Does not alter the passed in ver SV. See "upg_version" if you
1812want to upgrade the SV.
1813
1814 SV* new_version(SV *ver)
1815
1816=for hackers
1817Found in file util.c
1818
1819=item scan_version
1820
1821Returns a pointer to the next character after the parsed
1822version string, as well as upgrading the passed in SV to
1823an RV.
1824
1825Function must be called with an already existing SV like
1826
137d6fc0
JP
1827 sv = newSV(0);
1828 s = scan_version(s,SV *sv, bool qv);
f333445c
JP
1829
1830Performs some preprocessing to the string to ensure that
1831it has the correct characteristics of a version. Flags the
1832object if it contains an underscore (which denotes this
137d6fc0
JP
1833is a alpha version). The boolean qv denotes that the version
1834should be interpreted as if it had multiple decimals, even if
1835it doesn't.
f333445c 1836
9137345a 1837 const char* scan_version(const char *vstr, SV *sv, bool qv)
f333445c
JP
1838
1839=for hackers
1840Found in file util.c
1841
94bdecf9 1842=item strEQ
954c1994 1843
94bdecf9 1844Test two strings to see if they are equal. Returns true or false.
954c1994 1845
94bdecf9 1846 bool strEQ(char* s1, char* s2)
954c1994 1847
497711e7 1848=for hackers
94bdecf9 1849Found in file handy.h
497711e7 1850
94bdecf9 1851=item strGE
1c846c1f 1852
94bdecf9
JH
1853Test two strings to see if the first, C<s1>, is greater than or equal to
1854the second, C<s2>. Returns true or false.
1c846c1f 1855
94bdecf9 1856 bool strGE(char* s1, char* s2)
1c846c1f
NIS
1857
1858=for hackers
94bdecf9 1859Found in file handy.h
1c846c1f 1860
94bdecf9 1861=item strGT
954c1994 1862
94bdecf9
JH
1863Test two strings to see if the first, C<s1>, is greater than the second,
1864C<s2>. Returns true or false.
954c1994 1865
94bdecf9 1866 bool strGT(char* s1, char* s2)
954c1994 1867
497711e7 1868=for hackers
94bdecf9 1869Found in file handy.h
497711e7 1870
94bdecf9 1871=item strLE
954c1994 1872
94bdecf9
JH
1873Test two strings to see if the first, C<s1>, is less than or equal to the
1874second, C<s2>. Returns true or false.
954c1994 1875
94bdecf9 1876 bool strLE(char* s1, char* s2)
954c1994 1877
497711e7 1878=for hackers
94bdecf9 1879Found in file handy.h
497711e7 1880
94bdecf9 1881=item strLT
1a3327fb 1882
94bdecf9
JH
1883Test two strings to see if the first, C<s1>, is less than the second,
1884C<s2>. Returns true or false.
1a3327fb 1885
94bdecf9 1886 bool strLT(char* s1, char* s2)
1a3327fb 1887
497711e7 1888=for hackers
94bdecf9 1889Found in file handy.h
497711e7 1890
94bdecf9 1891=item strNE
954c1994 1892
94bdecf9
JH
1893Test two strings to see if they are different. Returns true or
1894false.
1895
1896 bool strNE(char* s1, char* s2)
954c1994 1897
497711e7 1898=for hackers
94bdecf9 1899Found in file handy.h
497711e7 1900
94bdecf9 1901=item strnEQ
954c1994 1902
94bdecf9
JH
1903Test two strings to see if they are equal. The C<len> parameter indicates
1904the number of bytes to compare. Returns true or false. (A wrapper for
1905C<strncmp>).
1906
1907 bool strnEQ(char* s1, char* s2, STRLEN len)
954c1994 1908
497711e7 1909=for hackers
94bdecf9 1910Found in file handy.h
497711e7 1911
94bdecf9 1912=item strnNE
954c1994 1913
94bdecf9
JH
1914Test two strings to see if they are different. The C<len> parameter
1915indicates the number of bytes to compare. Returns true or false. (A
1916wrapper for C<strncmp>).
954c1994 1917
94bdecf9 1918 bool strnNE(char* s1, char* s2, STRLEN len)
954c1994 1919
497711e7
GS
1920=for hackers
1921Found in file handy.h
1922
f333445c
JP
1923=item sv_nolocking
1924
1925Dummy routine which "locks" an SV when there is no locking module present.
1926Exists to avoid test for a NULL function pointer and because it could potentially warn under
1927some level of strict-ness.
1928
1929 void sv_nolocking(SV *)
1930
1931=for hackers
1932Found in file util.c
1933
1934=item sv_nosharing
1935
1936Dummy routine which "shares" an SV when there is no sharing module present.
1937Exists to avoid test for a NULL function pointer and because it could potentially warn under
1938some level of strict-ness.
1939
1940 void sv_nosharing(SV *)
1941
1942=for hackers
1943Found in file util.c
1944
1945=item sv_nounlocking
1946
1947Dummy routine which "unlocks" an SV when there is no locking module present.
1948Exists to avoid test for a NULL function pointer and because it could potentially warn under
1949some level of strict-ness.
1950
1951 void sv_nounlocking(SV *)
1952
1953=for hackers
1954Found in file util.c
1955
1956=item upg_version
1957
1958In-place upgrade of the supplied SV to a version object.
1959
1960 SV *sv = upg_version(SV *sv);
1961
1962Returns a pointer to the upgraded SV.
1963
1964 SV* upg_version(SV *ver)
1965
1966=for hackers
1967Found in file util.c
1968
1969=item vcmp
1970
1971Version object aware cmp. Both operands must already have been
1972converted into version objects.
1973
1974 int vcmp(SV *lvs, SV *rvs)
1975
1976=for hackers
1977Found in file util.c
1978
b9381830
JP
1979=item vnormal
1980
1981Accepts a version object and returns the normalized string
1982representation. Call like:
1983
1984 sv = vnormal(rv);
1985
1986NOTE: you can pass either the object directly or the SV
1987contained within the RV.
1988
1989 SV* vnormal(SV *vs)
1990
1991=for hackers
1992Found in file util.c
1993
f333445c
JP
1994=item vnumify
1995
1996Accepts a version object and returns the normalized floating
1997point representation. Call like:
1998
1999 sv = vnumify(rv);
2000
2001NOTE: you can pass either the object directly or the SV
2002contained within the RV.
2003
2004 SV* vnumify(SV *vs)
2005
2006=for hackers
2007Found in file util.c
2008
2009=item vstringify
2010
b9381830
JP
2011In order to maintain maximum compatibility with earlier versions
2012of Perl, this function will return either the floating point
2013notation or the multiple dotted notation, depending on whether
2014the original version contained 1 or more dots, respectively
f333445c
JP
2015
2016 SV* vstringify(SV *vs)
2017
2018=for hackers
2019Found in file util.c
2020
f4758303 2021
94bdecf9 2022=back
7207e29d 2023
94bdecf9 2024=head1 Numeric functions
7207e29d 2025
94bdecf9 2026=over 8
f4758303 2027
94bdecf9 2028=item grok_bin
f4758303 2029
94bdecf9
JH
2030converts a string representing a binary number to numeric form.
2031
2032On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2033conversion flags, and I<result> should be NULL or a pointer to an NV.
2034The scan stops at the end of the string, or the first invalid character.
7b667b5f
MHM
2035Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2036invalid character will also trigger a warning.
2037On return I<*len> is set to the length of the scanned string,
2038and I<*flags> gives output flags.
94bdecf9 2039
7fc63493 2040If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
94bdecf9
JH
2041and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2042returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2043and writes the value to I<*result> (or the value is discarded if I<result>
2044is NULL).
2045
7b667b5f 2046The binary number may optionally be prefixed with "0b" or "b" unless
94bdecf9
JH
2047C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2048C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2049number may use '_' characters to separate digits.
2050
a3b680e6 2051 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
f4758303
JP
2052
2053=for hackers
94bdecf9 2054Found in file numeric.c
f4758303 2055
94bdecf9 2056=item grok_hex
954c1994 2057
94bdecf9
JH
2058converts a string representing a hex number to numeric form.
2059
2060On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2061conversion flags, and I<result> should be NULL or a pointer to an NV.
7b667b5f
MHM
2062The scan stops at the end of the string, or the first invalid character.
2063Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2064invalid character will also trigger a warning.
2065On return I<*len> is set to the length of the scanned string,
2066and I<*flags> gives output flags.
94bdecf9
JH
2067
2068If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2069and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2070returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2071and writes the value to I<*result> (or the value is discarded if I<result>
2072is NULL).
2073
2074The hex number may optionally be prefixed with "0x" or "x" unless
2075C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2076C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2077number may use '_' characters to separate digits.
2078
a3b680e6 2079 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2080
497711e7 2081=for hackers
94bdecf9 2082Found in file numeric.c
497711e7 2083
94bdecf9 2084=item grok_number
954c1994 2085
94bdecf9
JH
2086Recognise (or not) a number. The type of the number is returned
2087(0 if unrecognised), otherwise it is a bit-ORed combination of
2088IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2089IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2090
2091If the value of the number can fit an in UV, it is returned in the *valuep
2092IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2093will never be set unless *valuep is valid, but *valuep may have been assigned
2094to during processing even though IS_NUMBER_IN_UV is not set on return.
2095If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2096valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2097
2098IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2099seen (in which case *valuep gives the true value truncated to an integer), and
2100IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2101absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
2102number is larger than a UV.
2103
2104 int grok_number(const char *pv, STRLEN len, UV *valuep)
954c1994 2105
497711e7 2106=for hackers
94bdecf9 2107Found in file numeric.c
497711e7 2108
94bdecf9 2109=item grok_numeric_radix
954c1994 2110
94bdecf9
JH
2111Scan and skip for a numeric decimal separator (radix).
2112
2113 bool grok_numeric_radix(const char **sp, const char *send)
954c1994 2114
497711e7 2115=for hackers
94bdecf9 2116Found in file numeric.c
497711e7 2117
94bdecf9 2118=item grok_oct
954c1994 2119
7b667b5f
MHM
2120converts a string representing an octal number to numeric form.
2121
2122On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2123conversion flags, and I<result> should be NULL or a pointer to an NV.
2124The scan stops at the end of the string, or the first invalid character.
2125Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2126invalid character will also trigger a warning.
2127On return I<*len> is set to the length of the scanned string,
2128and I<*flags> gives output flags.
2129
2130If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2131and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2132returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2133and writes the value to I<*result> (or the value is discarded if I<result>
2134is NULL).
2135
2136If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2137number may use '_' characters to separate digits.
94bdecf9 2138
a3b680e6 2139 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2140
497711e7 2141=for hackers
94bdecf9 2142Found in file numeric.c
497711e7 2143
94bdecf9 2144=item scan_bin
954c1994 2145
94bdecf9
JH
2146For backwards compatibility. Use C<grok_bin> instead.
2147
73d840c0 2148 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2149
497711e7 2150=for hackers
94bdecf9 2151Found in file numeric.c
497711e7 2152
94bdecf9 2153=item scan_hex
954c1994 2154
94bdecf9
JH
2155For backwards compatibility. Use C<grok_hex> instead.
2156
73d840c0 2157 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2158
497711e7 2159=for hackers
94bdecf9 2160Found in file numeric.c
497711e7 2161
94bdecf9 2162=item scan_oct
954c1994 2163
94bdecf9 2164For backwards compatibility. Use C<grok_oct> instead.
954c1994 2165
73d840c0 2166 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2167
497711e7 2168=for hackers
94bdecf9 2169Found in file numeric.c
497711e7 2170
645c22ef 2171
94bdecf9 2172=back
645c22ef 2173
94bdecf9
JH
2174=head1 Optree Manipulation Functions
2175
2176=over 8
2177
2178=item cv_const_sv
2179
2180If C<cv> is a constant sub eligible for inlining. returns the constant
2181value returned by the sub. Otherwise, returns NULL.
2182
2183Constant subs can be created with C<newCONSTSUB> or as described in
2184L<perlsub/"Constant Functions">.
2185
2186 SV* cv_const_sv(CV* cv)
645c22ef
DM
2187
2188=for hackers
94bdecf9 2189Found in file op.c
645c22ef 2190
94bdecf9 2191=item newCONSTSUB
954c1994 2192
94bdecf9
JH
2193Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
2194eligible for inlining at compile-time.
954c1994 2195
e1ec3a88 2196 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
954c1994 2197
497711e7 2198=for hackers
94bdecf9 2199Found in file op.c
497711e7 2200
94bdecf9 2201=item newXS
954c1994 2202
94bdecf9 2203Used by C<xsubpp> to hook up XSUBs as Perl subs.
954c1994 2204
94bdecf9
JH
2205=for hackers
2206Found in file op.c
2207
2208
2209=back
2210
dd2155a4
DM
2211=head1 Pad Data Structures
2212
2213=over 8
2214
2215=item pad_sv
2216
2217Get the value at offset po in the current pad.
2218Use macro PAD_SV instead of calling this function directly.
2219
2220 SV* pad_sv(PADOFFSET po)
2221
2222=for hackers
2223Found in file pad.c
2224
2225
2226=back
2227
59887a99
MHM
2228=head1 Simple Exception Handling Macros
2229
2230=over 8
2231
2232=item dXCPT
2233
2234Set up neccessary local variables for exception handling.
2235See L<perlguts/"Exception Handling">.
2236
2237 dXCPT;
2238
2239=for hackers
2240Found in file XSUB.h
2241
2242=item XCPT_CATCH
2243
2244Introduces a catch block. See L<perlguts/"Exception Handling">.
2245
2246=for hackers
2247Found in file XSUB.h
2248
2249=item XCPT_RETHROW
2250
2251Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
2252
2253 XCPT_RETHROW;
2254
2255=for hackers
2256Found in file XSUB.h
2257
2258=item XCPT_TRY_END
2259
2260Ends a try block. See L<perlguts/"Exception Handling">.
2261
2262=for hackers
2263Found in file XSUB.h
2264
2265=item XCPT_TRY_START
2266
2267Starts a try block. See L<perlguts/"Exception Handling">.
2268
2269=for hackers
2270Found in file XSUB.h
2271
2272
2273=back
2274
94bdecf9
JH
2275=head1 Stack Manipulation Macros
2276
2277=over 8
2278
2279=item dMARK
954c1994 2280
94bdecf9
JH
2281Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
2282C<dORIGMARK>.
954c1994 2283
94bdecf9 2284 dMARK;
954c1994 2285
497711e7 2286=for hackers
94bdecf9 2287Found in file pp.h
497711e7 2288
94bdecf9 2289=item dORIGMARK
954c1994 2290
94bdecf9 2291Saves the original stack mark for the XSUB. See C<ORIGMARK>.
954c1994 2292
94bdecf9 2293 dORIGMARK;
954c1994 2294
497711e7 2295=for hackers
94bdecf9 2296Found in file pp.h
497711e7 2297
94bdecf9 2298=item dSP
954c1994 2299
94bdecf9
JH
2300Declares a local copy of perl's stack pointer for the XSUB, available via
2301the C<SP> macro. See C<SP>.
954c1994 2302
94bdecf9 2303 dSP;
954c1994 2304
497711e7 2305=for hackers
94bdecf9 2306Found in file pp.h
497711e7 2307
94bdecf9 2308=item EXTEND
954c1994 2309
94bdecf9
JH
2310Used to extend the argument stack for an XSUB's return values. Once
2311used, guarantees that there is room for at least C<nitems> to be pushed
2312onto the stack.
954c1994 2313
94bdecf9 2314 void EXTEND(SP, int nitems)
954c1994 2315
497711e7 2316=for hackers
94bdecf9 2317Found in file pp.h
954c1994 2318
94bdecf9 2319=item MARK
954c1994 2320
94bdecf9 2321Stack marker variable for the XSUB. See C<dMARK>.
954c1994 2322
497711e7 2323=for hackers
94bdecf9 2324Found in file pp.h
954c1994 2325
d82b684c
SH
2326=item mPUSHi
2327
2328Push an integer onto the stack. The stack must have room for this element.
de4f2208
RGS
2329Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
2330and C<XPUSHi>.
d82b684c
SH
2331
2332 void mPUSHi(IV iv)
2333
2334=for hackers
2335Found in file pp.h
2336
2337=item mPUSHn
2338
2339Push a double onto the stack. The stack must have room for this element.
de4f2208
RGS
2340Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
2341and C<XPUSHn>.
d82b684c
SH
2342
2343 void mPUSHn(NV nv)
2344
2345=for hackers
2346Found in file pp.h
2347
2348=item mPUSHp
2349
2350Push a string onto the stack. The stack must have room for this element.
de4f2208
RGS
2351The C<len> indicates the length of the string. Handles 'set' magic. Does
2352not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
d82b684c
SH
2353
2354 void mPUSHp(char* str, STRLEN len)
2355
2356=for hackers
2357Found in file pp.h
2358
2359=item mPUSHu
2360
2361Push an unsigned integer onto the stack. The stack must have room for this
de4f2208
RGS
2362element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
2363C<mXPUSHu> and C<XPUSHu>.
d82b684c
SH
2364
2365 void mPUSHu(UV uv)
2366
2367=for hackers
2368Found in file pp.h
2369
2370=item mXPUSHi
2371
de4f2208
RGS
2372Push an integer onto the stack, extending the stack if necessary. Handles
2373'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
2374C<PUSHi>.
d82b684c
SH
2375
2376 void mXPUSHi(IV iv)
2377
2378=for hackers
2379Found in file pp.h
2380
2381=item mXPUSHn
2382
de4f2208
RGS
2383Push a double onto the stack, extending the stack if necessary. Handles
2384'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
2385C<PUSHn>.
d82b684c
SH
2386
2387 void mXPUSHn(NV nv)
2388
2389=for hackers
2390Found in file pp.h
2391
2392=item mXPUSHp
2393
2394Push a string onto the stack, extending the stack if necessary. The C<len>
de4f2208
RGS
2395indicates the length of the string. Handles 'set' magic. Does not use
2396C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
d82b684c
SH
2397
2398 void mXPUSHp(char* str, STRLEN len)
2399
2400=for hackers
2401Found in file pp.h
2402
2403=item mXPUSHu
2404
2405Push an unsigned integer onto the stack, extending the stack if necessary.
de4f2208
RGS
2406Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
2407and C<PUSHu>.
d82b684c
SH
2408
2409 void mXPUSHu(UV uv)
2410
2411=for hackers
2412Found in file pp.h
2413
94bdecf9 2414=item ORIGMARK
954c1994 2415
94bdecf9 2416The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 2417
497711e7 2418=for hackers
94bdecf9 2419Found in file pp.h
497711e7 2420
954c1994
GS
2421=item POPi
2422
2423Pops an integer off the stack.
2424
2425 IV POPi
2426
497711e7
GS
2427=for hackers
2428Found in file pp.h
2429
954c1994
GS
2430=item POPl
2431
2432Pops a long off the stack.
2433
2434 long POPl
2435
497711e7
GS
2436=for hackers
2437Found in file pp.h
2438
954c1994
GS
2439=item POPn
2440
2441Pops a double off the stack.
2442
2443 NV POPn
2444
497711e7
GS
2445=for hackers
2446Found in file pp.h
2447
954c1994
GS
2448=item POPp
2449
184499a4 2450Pops a string off the stack. Deprecated. New code should use POPpx.
954c1994
GS
2451
2452 char* POPp
2453
497711e7
GS
2454=for hackers
2455Found in file pp.h
2456
fa519979
JH
2457=item POPpbytex
2458
2459Pops a string off the stack which must consist of bytes i.e. characters < 256.
fa519979
JH
2460
2461 char* POPpbytex
2462
2463=for hackers
2464Found in file pp.h
2465
2466=item POPpx
2467
2468Pops a string off the stack.
fa519979
JH
2469
2470 char* POPpx
2471
2472=for hackers
2473Found in file pp.h
2474
954c1994
GS
2475=item POPs
2476
2477Pops an SV off the stack.
2478
2479 SV* POPs
2480
497711e7
GS
2481=for hackers
2482Found in file pp.h
2483
954c1994
GS
2484=item PUSHi
2485
2486Push an integer onto the stack. The stack must have room for this element.
d82b684c
SH
2487Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
2488called to declare it. Do not call multiple C<TARG>-oriented macros to
2489return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
2490C<mXPUSHi>.
954c1994
GS
2491
2492 void PUSHi(IV iv)
2493
497711e7
GS
2494=for hackers
2495Found in file pp.h
2496
954c1994
GS
2497=item PUSHMARK
2498
2499Opening bracket for arguments on a callback. See C<PUTBACK> and
2500L<perlcall>.
2501
c578083c 2502 void PUSHMARK(SP)
954c1994 2503
497711e7
GS
2504=for hackers
2505Found in file pp.h
2506
d82b684c
SH
2507=item PUSHmortal
2508
2509Push a new mortal SV onto the stack. The stack must have room for this
2510element. Does not handle 'set' magic. Does not use C<TARG>. See also
2511C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
2512
2513 void PUSHmortal()
2514
2515=for hackers
2516Found in file pp.h
2517
954c1994
GS
2518=item PUSHn
2519
2520Push a double onto the stack. The stack must have room for this element.
d82b684c
SH
2521Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
2522called to declare it. Do not call multiple C<TARG>-oriented macros to
2523return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
2524C<mXPUSHn>.
954c1994
GS
2525
2526 void PUSHn(NV nv)
2527
497711e7
GS
2528=for hackers
2529Found in file pp.h
2530
954c1994
GS
2531=item PUSHp
2532
2533Push a string onto the stack. The stack must have room for this element.
d82b684c
SH
2534The C<len> indicates the length of the string. Handles 'set' magic. Uses
2535C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
2536call multiple C<TARG>-oriented macros to return lists from XSUB's - see
2537C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
954c1994
GS
2538
2539 void PUSHp(char* str, STRLEN len)
2540
497711e7
GS
2541=for hackers
2542Found in file pp.h
2543
954c1994
GS
2544=item PUSHs
2545
1c846c1f 2546Push an SV onto the stack. The stack must have room for this element.
d82b684c
SH
2547Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
2548C<XPUSHs> and C<XPUSHmortal>.
954c1994
GS
2549
2550 void PUSHs(SV* sv)
2551
497711e7
GS
2552=for hackers
2553Found in file pp.h
2554
954c1994
GS
2555=item PUSHu
2556
2557Push an unsigned integer onto the stack. The stack must have room for this
d82b684c
SH
2558element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
2559should be called to declare it. Do not call multiple C<TARG>-oriented
2560macros to return lists from XSUB's - see C<mPUSHu> instead. See also
2561C<XPUSHu> and C<mXPUSHu>.
954c1994
GS
2562
2563 void PUSHu(UV uv)
2564
497711e7
GS
2565=for hackers
2566Found in file pp.h
2567
954c1994
GS
2568=item PUTBACK
2569
2570Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2571See C<PUSHMARK> and L<perlcall> for other uses.
2572
2573 PUTBACK;
2574
497711e7
GS
2575=for hackers
2576Found in file pp.h
2577
94bdecf9 2578=item SP
d2cc3551 2579
94bdecf9
JH
2580Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2581C<SPAGAIN>.
d2cc3551 2582
94bdecf9
JH
2583=for hackers
2584Found in file pp.h
2585
2586=item SPAGAIN
2587
2588Refetch the stack pointer. Used after a callback. See L<perlcall>.
2589
2590 SPAGAIN;
d2cc3551
JH
2591
2592=for hackers
94bdecf9 2593Found in file pp.h
d2cc3551 2594
94bdecf9 2595=item XPUSHi
954c1994 2596
94bdecf9 2597Push an integer onto the stack, extending the stack if necessary. Handles
d82b684c
SH
2598'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
2599declare it. Do not call multiple C<TARG>-oriented macros to return lists
2600from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
954c1994 2601
94bdecf9 2602 void XPUSHi(IV iv)
954c1994 2603
497711e7 2604=for hackers
94bdecf9 2605Found in file pp.h
497711e7 2606
d82b684c
SH
2607=item XPUSHmortal
2608
2609Push a new mortal SV onto the stack, extending the stack if necessary. Does
2610not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>,
2611C<PUSHmortal> and C<PUSHs>.
2612
2613 void XPUSHmortal()
2614
2615=for hackers
2616Found in file pp.h
2617
94bdecf9 2618=item XPUSHn
954c1994 2619
94bdecf9 2620Push a double onto the stack, extending the stack if necessary. Handles
d82b684c
SH
2621'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
2622declare it. Do not call multiple C<TARG>-oriented macros to return lists
2623from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
954c1994 2624
94bdecf9 2625 void XPUSHn(NV nv)
954c1994 2626
497711e7 2627=for hackers
94bdecf9 2628Found in file pp.h
497711e7 2629
94bdecf9 2630=item XPUSHp
954c1994 2631
94bdecf9 2632Push a string onto the stack, extending the stack if necessary. The C<len>
d82b684c
SH
2633indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
2634C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
2635multiple C<TARG>-oriented macros to return lists from XSUB's - see
2636C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
954c1994 2637
94bdecf9 2638 void XPUSHp(char* str, STRLEN len)
954c1994 2639
94bdecf9
JH
2640=for hackers
2641Found in file pp.h
2642
2643=item XPUSHs
2644
2645Push an SV onto the stack, extending the stack if necessary. Does not
d82b684c
SH
2646handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
2647C<PUSHs> and C<PUSHmortal>.
94bdecf9
JH
2648
2649 void XPUSHs(SV* sv)
954c1994 2650
497711e7 2651=for hackers
94bdecf9 2652Found in file pp.h
497711e7 2653
94bdecf9 2654=item XPUSHu
954c1994 2655
94bdecf9 2656Push an unsigned integer onto the stack, extending the stack if necessary.
d82b684c
SH
2657Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
2658called to declare it. Do not call multiple C<TARG>-oriented macros to
2659return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
2660C<mPUSHu>.
954c1994 2661
94bdecf9
JH
2662 void XPUSHu(UV uv)
2663
2664=for hackers
2665Found in file pp.h
2666
2667=item XSRETURN
2668
2669Return from XSUB, indicating number of items on the stack. This is usually
2670handled by C<xsubpp>.
2671
2672 void XSRETURN(int nitems)
954c1994 2673
497711e7
GS
2674=for hackers
2675Found in file XSUB.h
2676
e509e693
SH
2677=item XSRETURN_EMPTY
2678
2679Return an empty list from an XSUB immediately.
2680
2681 XSRETURN_EMPTY;
2682
2683=for hackers
2684Found in file XSUB.h
2685
94bdecf9 2686=item XSRETURN_IV
954c1994 2687
94bdecf9 2688Return an integer from an XSUB immediately. Uses C<XST_mIV>.
954c1994 2689
94bdecf9 2690 void XSRETURN_IV(IV iv)
954c1994 2691
497711e7 2692=for hackers
94bdecf9 2693Found in file XSUB.h
497711e7 2694
94bdecf9 2695=item XSRETURN_NO
954c1994 2696
94bdecf9 2697Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
954c1994 2698
94bdecf9 2699 XSRETURN_NO;
954c1994 2700
497711e7 2701=for hackers
94bdecf9 2702Found in file XSUB.h
497711e7 2703
94bdecf9 2704=item XSRETURN_NV
954c1994 2705
94bdecf9 2706Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994 2707
94bdecf9 2708 void XSRETURN_NV(NV nv)
954c1994 2709
497711e7 2710=for hackers
94bdecf9
JH
2711Found in file XSUB.h
2712
2713=item XSRETURN_PV
2714
2715Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2716
2717 void XSRETURN_PV(char* str)
2718
2719=for hackers
2720Found in file XSUB.h
2721
2722=item XSRETURN_UNDEF
2723
2724Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2725
2726 XSRETURN_UNDEF;
2727
2728=for hackers
2729Found in file XSUB.h
2730
0ee80f49
JH
2731=item XSRETURN_UV
2732
2733Return an integer from an XSUB immediately. Uses C<XST_mUV>.
2734
2735 void XSRETURN_UV(IV uv)
2736
2737=for hackers
2738Found in file XSUB.h
2739
94bdecf9
JH
2740=item XSRETURN_YES
2741
2742Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2743
2744 XSRETURN_YES;
2745
2746=for hackers
2747Found in file XSUB.h
2748
2749=item XST_mIV
2750
2751Place an integer into the specified position C<pos> on the stack. The
2752value is stored in a new mortal SV.
2753
2754 void XST_mIV(int pos, IV iv)
2755
2756=for hackers
2757Found in file XSUB.h
2758
2759=item XST_mNO
2760
2761Place C<&PL_sv_no> into the specified position C<pos> on the
2762stack.
2763
2764 void XST_mNO(int pos)
2765
2766=for hackers
2767Found in file XSUB.h
2768
2769=item XST_mNV
2770
2771Place a double into the specified position C<pos> on the stack. The value
2772is stored in a new mortal SV.
2773
2774 void XST_mNV(int pos, NV nv)
2775
2776=for hackers
2777Found in file XSUB.h
2778
2779=item XST_mPV
2780
2781Place a copy of a string into the specified position C<pos> on the stack.
2782The value is stored in a new mortal SV.
2783
2784 void XST_mPV(int pos, char* str)
2785
2786=for hackers
2787Found in file XSUB.h
2788
2789=item XST_mUNDEF
2790
2791Place C<&PL_sv_undef> into the specified position C<pos> on the
2792stack.
2793
2794 void XST_mUNDEF(int pos)
2795
2796=for hackers
2797Found in file XSUB.h
2798
2799=item XST_mYES
2800
2801Place C<&PL_sv_yes> into the specified position C<pos> on the
2802stack.
2803
2804 void XST_mYES(int pos)
2805
2806=for hackers
2807Found in file XSUB.h
2808
2809
2810=back
2811
2812=head1 SV Flags
497711e7 2813
94bdecf9 2814=over 8
954c1994 2815
94bdecf9 2816=item svtype
954c1994 2817
94bdecf9
JH
2818An enum of flags for Perl types. These are found in the file B<sv.h>
2819in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2820
497711e7 2821=for hackers
94bdecf9 2822Found in file sv.h
6e9d1081 2823
94bdecf9 2824=item SVt_IV
6e9d1081 2825
94bdecf9 2826Integer type flag for scalars. See C<svtype>.
6e9d1081
NC
2827
2828=for hackers
94bdecf9 2829Found in file sv.h
6e9d1081 2830
94bdecf9 2831=item SVt_NV
6e9d1081 2832
94bdecf9 2833Double type flag for scalars. See C<svtype>.
6e9d1081
NC
2834
2835=for hackers
94bdecf9 2836Found in file sv.h
6e9d1081 2837
94bdecf9 2838=item SVt_PV
6e9d1081 2839
94bdecf9 2840Pointer type flag for scalars. See C<svtype>.
6e9d1081
NC
2841
2842=for hackers
94bdecf9 2843Found in file sv.h
cd1ee231 2844
94bdecf9 2845=item SVt_PVAV
cd1ee231 2846
94bdecf9 2847Type flag for arrays. See C<svtype>.
cd1ee231
JH
2848
2849=for hackers
94bdecf9 2850Found in file sv.h
cd1ee231 2851
94bdecf9 2852=item SVt_PVCV
cd1ee231 2853
94bdecf9 2854Type flag for code refs. See C<svtype>.
cd1ee231
JH
2855
2856=for hackers
94bdecf9 2857Found in file sv.h
cd1ee231 2858
94bdecf9 2859=item SVt_PVHV
cd1ee231 2860
94bdecf9 2861Type flag for hashes. See C<svtype>.
cd1ee231
JH
2862
2863=for hackers
94bdecf9 2864Found in file sv.h
cd1ee231 2865
94bdecf9 2866=item SVt_PVMG
cd1ee231 2867
94bdecf9 2868Type flag for blessed scalars. See C<svtype>.
cd1ee231
JH
2869
2870=for hackers
94bdecf9 2871Found in file sv.h
cd1ee231 2872
cd1ee231 2873
94bdecf9 2874=back
cd1ee231 2875
94bdecf9 2876=head1 SV Manipulation Functions
cd1ee231 2877
94bdecf9 2878=over 8
cd1ee231 2879
94bdecf9 2880=item get_sv
cd1ee231 2881
94bdecf9
JH
2882Returns the SV of the specified Perl scalar. If C<create> is set and the
2883Perl variable does not exist then it will be created. If C<create> is not
2884set and the variable does not exist then NULL is returned.
2885
2886NOTE: the perl_ form of this function is deprecated.
2887
2888 SV* get_sv(const char* name, I32 create)
cd1ee231
JH
2889
2890=for hackers
94bdecf9 2891Found in file perl.c
cd1ee231 2892
94bdecf9 2893=item looks_like_number
cd1ee231 2894
94bdecf9
JH
2895Test if the content of an SV looks like a number (or is a number).
2896C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2897non-numeric warning), even if your atof() doesn't grok them.
cd1ee231 2898
94bdecf9 2899 I32 looks_like_number(SV* sv)
cd1ee231
JH
2900
2901=for hackers
94bdecf9 2902Found in file sv.c
2a5a0c38 2903
94bdecf9 2904=item newRV_inc
2a5a0c38 2905
94bdecf9
JH
2906Creates an RV wrapper for an SV. The reference count for the original SV is
2907incremented.
2a5a0c38 2908
94bdecf9 2909 SV* newRV_inc(SV* sv)
2a5a0c38
JH
2910
2911=for hackers
94bdecf9 2912Found in file sv.h
2a5a0c38 2913
94bdecf9 2914=item newRV_noinc
954c1994 2915
94bdecf9
JH
2916Creates an RV wrapper for an SV. The reference count for the original
2917SV is B<not> incremented.
2918
2919 SV* newRV_noinc(SV *sv)
954c1994 2920
497711e7 2921=for hackers
94bdecf9 2922Found in file sv.c
497711e7 2923
e509e693
SH
2924=item NEWSV
2925
2926Creates a new SV. A non-zero C<len> parameter indicates the number of
2927bytes of preallocated string space the SV should have. An extra byte for a
2928tailing NUL is also reserved. (SvPOK is not set for the SV even if string
2929space is allocated.) The reference count for the new SV is set to 1.
2930C<id> is an integer id between 0 and 1299 (used to identify leaks).
2931
2932 SV* NEWSV(int id, STRLEN len)
2933
2934=for hackers
2935Found in file handy.h
2936
94bdecf9 2937=item newSV
954c1994 2938
94bdecf9
JH
2939Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2940with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2941macro.
954c1994 2942
94bdecf9 2943 SV* newSV(STRLEN len)
954c1994 2944
497711e7 2945=for hackers
94bdecf9 2946Found in file sv.c
497711e7 2947
926f8064
RGS
2948=item newSVhek
2949
2950Creates a new SV from the hash key structure. It will generate scalars that
2951point to the shared string table where possible. Returns a new (undefined)
2952SV if the hek is NULL.
2953
2954 SV* newSVhek(const HEK *hek)
2955
2956=for hackers
2957Found in file sv.c
2958
94bdecf9 2959=item newSViv
954c1994 2960
94bdecf9
JH
2961Creates a new SV and copies an integer into it. The reference count for the
2962SV is set to 1.
954c1994 2963
94bdecf9 2964 SV* newSViv(IV i)
954c1994 2965
497711e7 2966=for hackers
94bdecf9 2967Found in file sv.c
497711e7 2968
94bdecf9 2969=item newSVnv
954c1994 2970
94bdecf9
JH
2971Creates a new SV and copies a floating point value into it.
2972The reference count for the SV is set to 1.
954c1994 2973
94bdecf9 2974 SV* newSVnv(NV n)
954c1994 2975
497711e7 2976=for hackers
94bdecf9 2977Found in file sv.c
497711e7 2978
94bdecf9 2979=item newSVpv
954c1994 2980
94bdecf9
JH
2981Creates a new SV and copies a string into it. The reference count for the
2982SV is set to 1. If C<len> is zero, Perl will compute the length using
2983strlen(). For efficiency, consider using C<newSVpvn> instead.
954c1994 2984
94bdecf9 2985 SV* newSVpv(const char* s, STRLEN len)
954c1994 2986
497711e7 2987=for hackers
94bdecf9 2988Found in file sv.c
497711e7 2989
94bdecf9 2990=item newSVpvf
954c1994 2991
94bdecf9
JH
2992Creates a new SV and initializes it with the string formatted like
2993C<sprintf>.
954c1994 2994
94bdecf9 2995 SV* newSVpvf(const char* pat, ...)
954c1994 2996
497711e7 2997=for hackers
94bdecf9 2998Found in file sv.c
497711e7 2999
94bdecf9 3000=item newSVpvn
954c1994 3001
94bdecf9
JH
3002Creates a new SV and copies a string into it. The reference count for the
3003SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
3004string. You are responsible for ensuring that the source string is at least
9e09f5f2 3005C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
954c1994 3006
94bdecf9 3007 SV* newSVpvn(const char* s, STRLEN len)
954c1994 3008
497711e7 3009=for hackers
94bdecf9 3010Found in file sv.c
497711e7 3011
94bdecf9 3012=item newSVpvn_share
954c1994 3013
3f7c398e 3014Creates a new SV with its SvPVX_const pointing to a shared string in the string
94bdecf9
JH
3015table. If the string does not already exist in the table, it is created
3016first. Turns on READONLY and FAKE. The string's hash is stored in the UV
3017slot of the SV; if the C<hash> parameter is non-zero, that value is used;
3018otherwise the hash is computed. The idea here is that as the string table
3f7c398e 3019is used for shared hash keys these strings will have SvPVX_const == HeKEY and
94bdecf9 3020hash lookup will avoid string compare.
954c1994 3021
94bdecf9 3022 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
954c1994 3023
497711e7 3024=for hackers
94bdecf9 3025Found in file sv.c
497711e7 3026
94bdecf9 3027=item newSVrv
954c1994 3028
94bdecf9
JH
3029Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
3030it will be upgraded to one. If C<classname> is non-null then the new SV will
3031be blessed in the specified package. The new SV is returned and its
3032reference count is 1.
954c1994 3033
94bdecf9 3034 SV* newSVrv(SV* rv, const char* classname)
954c1994 3035
497711e7 3036=for hackers
94bdecf9 3037Found in file sv.c
497711e7 3038
94bdecf9 3039=item newSVsv
954c1994 3040
94bdecf9
JH
3041Creates a new SV which is an exact duplicate of the original SV.
3042(Uses C<sv_setsv>).
954c1994 3043
94bdecf9 3044 SV* newSVsv(SV* old)
954c1994 3045
497711e7 3046=for hackers
94bdecf9 3047Found in file sv.c
497711e7 3048
94bdecf9 3049=item newSVuv
954c1994 3050
94bdecf9
JH
3051Creates a new SV and copies an unsigned integer into it.
3052The reference count for the SV is set to 1.
954c1994 3053
94bdecf9 3054 SV* newSVuv(UV u)
954c1994 3055
497711e7 3056=for hackers
94bdecf9 3057Found in file sv.c
497711e7 3058
954c1994
GS
3059=item SvCUR
3060
3061Returns the length of the string which is in the SV. See C<SvLEN>.
3062
3063 STRLEN SvCUR(SV* sv)
3064
497711e7
GS
3065=for hackers
3066Found in file sv.h
3067
954c1994
GS
3068=item SvCUR_set
3069
20799e15
SP
3070Set the current length of the string which is in the SV. See C<SvCUR>
3071and C<SvIV_set>.
954c1994
GS
3072
3073 void SvCUR_set(SV* sv, STRLEN len)
3074
497711e7
GS
3075=for hackers
3076Found in file sv.h
3077
94bdecf9 3078=item SvEND
954c1994 3079
94bdecf9
JH
3080Returns a pointer to the last character in the string which is in the SV.
3081See C<SvCUR>. Access the character as *(SvEND(sv)).
954c1994 3082
94bdecf9 3083 char* SvEND(SV* sv)
954c1994 3084
497711e7
GS
3085=for hackers
3086Found in file sv.h
3087
954c1994
GS
3088=item SvGROW
3089
3090Expands the character buffer in the SV so that it has room for the
3091indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 3092NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
3093Returns a pointer to the character buffer.
3094
679ac26e 3095 char * SvGROW(SV* sv, STRLEN len)
954c1994 3096
497711e7
GS
3097=for hackers
3098Found in file sv.h
3099
954c1994
GS
3100=item SvIOK
3101
3102Returns a boolean indicating whether the SV contains an integer.
3103
3104 bool SvIOK(SV* sv)
3105
497711e7
GS
3106=for hackers
3107Found in file sv.h
3108
954c1994
GS
3109=item SvIOKp
3110
3111Returns a boolean indicating whether the SV contains an integer. Checks
3112the B<private> setting. Use C<SvIOK>.
3113
3114 bool SvIOKp(SV* sv)
3115
497711e7
GS
3116=for hackers
3117Found in file sv.h
3118
e331fc52
JH
3119=item SvIOK_notUV
3120
f4758303 3121Returns a boolean indicating whether the SV contains a signed integer.
e331fc52 3122
12fa07df 3123 bool SvIOK_notUV(SV* sv)
e331fc52
JH
3124
3125=for hackers
3126Found in file sv.h
3127
954c1994
GS
3128=item SvIOK_off
3129
3130Unsets the IV status of an SV.
3131
3132 void SvIOK_off(SV* sv)
3133
497711e7
GS
3134=for hackers
3135Found in file sv.h
3136
954c1994
GS
3137=item SvIOK_on
3138
3139Tells an SV that it is an integer.
3140
3141 void SvIOK_on(SV* sv)
3142
497711e7
GS
3143=for hackers
3144Found in file sv.h
3145
954c1994
GS
3146=item SvIOK_only
3147
3148Tells an SV that it is an integer and disables all other OK bits.
3149
3150 void SvIOK_only(SV* sv)
3151
497711e7
GS
3152=for hackers
3153Found in file sv.h
3154
e331fc52
JH
3155=item SvIOK_only_UV
3156
3157Tells and SV that it is an unsigned integer and disables all other OK bits.
3158
3159 void SvIOK_only_UV(SV* sv)
3160
3161=for hackers
3162Found in file sv.h
3163
3164=item SvIOK_UV
3165
3166Returns a boolean indicating whether the SV contains an unsigned integer.
3167
12fa07df 3168 bool SvIOK_UV(SV* sv)
e331fc52
JH
3169
3170=for hackers
3171Found in file sv.h
3172
19dbb8f1
NC
3173=item SvIsCOW
3174
3175Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
3176hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
3177COW)
3178
3179 bool SvIsCOW(SV* sv)
3180
3181=for hackers
3182Found in file sv.h
3183
3184=item SvIsCOW_shared_hash
3185
3186Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
3187scalar.
3188
3189 bool SvIsCOW_shared_hash(SV* sv)
3190
3191=for hackers
3192Found in file sv.h
3193
954c1994
GS
3194=item SvIV
3195
645c22ef
DM
3196Coerces the given SV to an integer and returns it. See C<SvIVx> for a
3197version which guarantees to evaluate sv only once.
954c1994
GS
3198
3199 IV SvIV(SV* sv)
3200
497711e7
GS
3201=for hackers
3202Found in file sv.h
3203
df344c0f 3204=item SvIVX
954c1994 3205
df344c0f
NC
3206Returns the raw value in the SV's IV slot, without checks or conversions.
3207Only use when you are sure SvIOK is true. See also C<SvIV()>.
954c1994 3208
df344c0f 3209 IV SvIVX(SV* sv)
954c1994 3210
497711e7
GS
3211=for hackers
3212Found in file sv.h
3213
df344c0f 3214=item SvIVx
645c22ef 3215
df344c0f
NC
3216Coerces the given SV to an integer and returns it. Guarantees to evaluate
3217sv only once. Use the more efficient C<SvIV> otherwise.
645c22ef 3218
df344c0f 3219 IV SvIVx(SV* sv)
645c22ef
DM
3220
3221=for hackers
3222Found in file sv.h
3223
891f9566
YST
3224=item SvIV_nomg
3225
3226Like C<SvIV> but doesn't process magic.
3227
3228 IV SvIV_nomg(SV* sv)
3229
3230=for hackers
3231Found in file sv.h
3232
672994ce
SP
3233=item SvIV_set
3234
20799e15
SP
3235Set the value of the IV pointer in sv to val. It is possible to perform
3236the same function of this macro with an lvalue assignment to C<SvIVX>.
3237With future Perls, however, it will be more efficient to use
3238C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
672994ce
SP
3239
3240 void SvIV_set(SV* sv, IV val)
3241
3242=for hackers
3243Found in file sv.h
3244
954c1994
GS
3245=item SvLEN
3246
91e74348
JH
3247Returns the size of the string buffer in the SV, not including any part
3248attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
3249
3250 STRLEN SvLEN(SV* sv)
3251
497711e7
GS
3252=for hackers
3253Found in file sv.h
3254
672994ce
SP
3255=item SvLEN_set
3256
20799e15 3257Set the actual length of the string which is in the SV. See C<SvIV_set>.
672994ce
SP
3258
3259 void SvLEN_set(SV* sv, STRLEN len)
3260
3261=for hackers
3262Found in file sv.h
3263
3264=item SvMAGIC_set
3265
20799e15 3266Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
672994ce
SP
3267
3268 void SvMAGIC_set(SV* sv, MAGIC* val)
3269
3270=for hackers
3271Found in file sv.h
3272
954c1994
GS
3273=item SvNIOK
3274
3275Returns a boolean indicating whether the SV contains a number, integer or
3276double.
3277
3278 bool SvNIOK(SV* sv)
3279
497711e7
GS
3280=for hackers
3281Found in file sv.h
3282
954c1994
GS
3283=item SvNIOKp
3284
3285Returns a boolean indicating whether the SV contains a number, integer or
3286double. Checks the B<private> setting. Use C<SvNIOK>.
3287
3288 bool SvNIOKp(SV* sv)
3289
497711e7
GS
3290=for hackers
3291Found in file sv.h
3292
954c1994
GS
3293=item SvNIOK_off
3294
3295Unsets the NV/IV status of an SV.
3296
3297 void SvNIOK_off(SV* sv)
3298
497711e7
GS
3299=for hackers
3300Found in file sv.h
3301
954c1994
GS
3302=item SvNOK
3303
3304Returns a boolean indicating whether the SV contains a double.
3305
3306 bool SvNOK(SV* sv)
3307
497711e7
GS
3308=for hackers
3309Found in file sv.h
3310
954c1994
GS
3311=item SvNOKp
3312
3313Returns a boolean indicating whether the SV contains a double. Checks the
3314B<private> setting. Use C<SvNOK>.
3315
3316 bool SvNOKp(SV* sv)
3317
497711e7
GS
3318=for hackers
3319Found in file sv.h
3320
954c1994
GS
3321=item SvNOK_off
3322
3323Unsets the NV status of an SV.
3324
3325 void SvNOK_off(SV* sv)
3326
497711e7
GS
3327=for hackers
3328Found in file sv.h
3329
954c1994
GS
3330=item SvNOK_on
3331
3332Tells an SV that it is a double.
3333
3334 void SvNOK_on(SV* sv)
3335
497711e7
GS
3336=for hackers
3337Found in file sv.h
3338
954c1994
GS
3339=item SvNOK_only
3340
3341Tells an SV that it is a double and disables all other OK bits.
3342
3343 void SvNOK_only(SV* sv)
3344
497711e7
GS
3345=for hackers
3346Found in file sv.h
3347
954c1994
GS
3348=item SvNV
3349
645c22ef
DM
3350Coerce the given SV to a double and return it. See C<SvNVx> for a version
3351which guarantees to evaluate sv only once.
954c1994
GS
3352
3353 NV SvNV(SV* sv)
3354
497711e7
GS
3355=for hackers
3356Found in file sv.h
3357
b9381830 3358=item SvNVX
645c22ef 3359
b9381830
JP
3360Returns the raw value in the SV's NV slot, without checks or conversions.
3361Only use when you are sure SvNOK is true. See also C<SvNV()>.
645c22ef 3362
b9381830 3363 NV SvNVX(SV* sv)
645c22ef
DM
3364
3365=for hackers
3366Found in file sv.h
3367
b9381830 3368=item SvNVx
954c1994 3369
b9381830
JP
3370Coerces the given SV to a double and returns it. Guarantees to evaluate
3371sv only once. Use the more efficient C<SvNV> otherwise.
954c1994 3372
b9381830 3373 NV SvNVx(SV* sv)
954c1994 3374
497711e7
GS
3375=for hackers
3376Found in file sv.h
3377
672994ce
SP
3378=item SvNV_set
3379
20799e15 3380Set the value of the NV pointer in sv to val. See C<SvIV_set>.
672994ce
SP
3381
3382 void SvNV_set(SV* sv, NV val)
3383
3384=for hackers
3385Found in file sv.h
3386
954c1994
GS
3387=item SvOK
3388
9adebda4
SB
3389Returns a boolean indicating whether the value is an SV. It also tells
3390whether the value is defined or not.
954c1994
GS
3391
3392 bool SvOK(SV* sv)
3393
497711e7
GS
3394=for hackers
3395Found in file sv.h
3396
954c1994
GS
3397=item SvOOK
3398
3399Returns a boolean indicating whether the SvIVX is a valid offset value for
3400the SvPVX. This hack is used internally to speed up removal of characters
3401from the beginning of a SvPV. When SvOOK is true, then the start of the
3402allocated string buffer is really (SvPVX - SvIVX).
3403
3404 bool SvOOK(SV* sv)
3405
497711e7
GS
3406=for hackers
3407Found in file sv.h
3408
954c1994
GS
3409=item SvPOK
3410
3411Returns a boolean indicating whether the SV contains a character
3412string.
3413
3414 bool SvPOK(SV* sv)
3415
497711e7
GS
3416=for hackers
3417Found in file sv.h
3418
954c1994
GS
3419=item SvPOKp
3420
3421Returns a boolean indicating whether the SV contains a character string.
3422Checks the B<private> setting. Use C<SvPOK>.
3423
3424 bool SvPOKp(SV* sv)
3425
497711e7
GS
3426=for hackers
3427Found in file sv.h
3428
954c1994
GS
3429=item SvPOK_off
3430
3431Unsets the PV status of an SV.
3432
3433 void SvPOK_off(SV* sv)
3434
497711e7
GS
3435=for hackers
3436Found in file sv.h
3437
954c1994
GS
3438=item SvPOK_on
3439
3440Tells an SV that it is a string.
3441
3442 void SvPOK_on(SV* sv)
3443
497711e7
GS
3444=for hackers
3445Found in file sv.h
3446
954c1994
GS
3447=item SvPOK_only
3448
3449Tells an SV that it is a string and disables all other OK bits.
1e54db1a 3450Will also turn off the UTF-8 status.
954c1994
GS
3451
3452 void SvPOK_only(SV* sv)
3453
497711e7
GS
3454=for hackers
3455Found in file sv.h
3456
914184e1
JH
3457=item SvPOK_only_UTF8
3458
d5ce4a7c 3459Tells an SV that it is a string and disables all other OK bits,
1e54db1a 3460and leaves the UTF-8 status as it was.
f1a1024e 3461
914184e1
JH
3462 void SvPOK_only_UTF8(SV* sv)
3463
3464=for hackers
3465Found in file sv.h
3466
954c1994
GS
3467=item SvPV
3468
12b7c5c7
JH
3469Returns a pointer to the string in the SV, or a stringified form of
3470the SV if the SV does not contain a string. The SV may cache the
3471stringified version becoming C<SvPOK>. Handles 'get' magic. See also
645c22ef 3472C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
3473
3474 char* SvPV(SV* sv, STRLEN len)
3475
497711e7
GS
3476=for hackers
3477Found in file sv.h
3478
645c22ef
DM
3479=item SvPVbyte
3480
3481Like C<SvPV>, but converts sv to byte representation first if necessary.
3482
3483 char* SvPVbyte(SV* sv, STRLEN len)
3484
3485=for hackers
3486Found in file sv.h
3487
3488=item SvPVbytex
3489
3490Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 3491Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
3492otherwise.</