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