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