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