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