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