This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix 29149 - another UTF8 cache bug hit by substr.
[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
94bdecf9 2206=item ORIGMARK
954c1994 2207
94bdecf9 2208The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 2209
497711e7 2210=for hackers
94bdecf9 2211Found in file pp.h
497711e7 2212
954c1994
GS
2213=item POPi
2214
2215Pops an integer off the stack.
2216
2217 IV POPi
2218
497711e7
GS
2219=for hackers
2220Found in file pp.h
2221
954c1994
GS
2222=item POPl
2223
2224Pops a long off the stack.
2225
2226 long POPl
2227
497711e7
GS
2228=for hackers
2229Found in file pp.h
2230
954c1994
GS
2231=item POPn
2232
2233Pops a double off the stack.
2234
2235 NV POPn
2236
497711e7
GS
2237=for hackers
2238Found in file pp.h
2239
954c1994
GS
2240=item POPp
2241
fa519979
JH
2242Pops a string off the stack. Deprecated. New code should provide
2243a STRLEN n_a and use POPpx.
954c1994
GS
2244
2245 char* POPp
2246
497711e7
GS
2247=for hackers
2248Found in file pp.h
2249
fa519979
JH
2250=item POPpbytex
2251
2252Pops a string off the stack which must consist of bytes i.e. characters < 256.
2253Requires a variable STRLEN n_a in scope.
2254
2255 char* POPpbytex
2256
2257=for hackers
2258Found in file pp.h
2259
2260=item POPpx
2261
2262Pops a string off the stack.
2263Requires a variable STRLEN n_a in scope.
2264
2265 char* POPpx
2266
2267=for hackers
2268Found in file pp.h
2269
954c1994
GS
2270=item POPs
2271
2272Pops an SV off the stack.
2273
2274 SV* POPs
2275
497711e7
GS
2276=for hackers
2277Found in file pp.h
2278
954c1994
GS
2279=item PUSHi
2280
2281Push an integer onto the stack. The stack must have room for this element.
2282Handles 'set' magic. See C<XPUSHi>.
2283
2284 void PUSHi(IV iv)
2285
497711e7
GS
2286=for hackers
2287Found in file pp.h
2288
954c1994
GS
2289=item PUSHMARK
2290
2291Opening bracket for arguments on a callback. See C<PUTBACK> and
2292L<perlcall>.
2293
2294 PUSHMARK;
2295
497711e7
GS
2296=for hackers
2297Found in file pp.h
2298
954c1994
GS
2299=item PUSHn
2300
2301Push a double onto the stack. The stack must have room for this element.
2302Handles 'set' magic. See C<XPUSHn>.
2303
2304 void PUSHn(NV nv)
2305
497711e7
GS
2306=for hackers
2307Found in file pp.h
2308
954c1994
GS
2309=item PUSHp
2310
2311Push a string onto the stack. The stack must have room for this element.
2312The C<len> indicates the length of the string. Handles 'set' magic. See
2313C<XPUSHp>.
2314
2315 void PUSHp(char* str, STRLEN len)
2316
497711e7
GS
2317=for hackers
2318Found in file pp.h
2319
954c1994
GS
2320=item PUSHs
2321
1c846c1f 2322Push an SV onto the stack. The stack must have room for this element.
954c1994
GS
2323Does not handle 'set' magic. See C<XPUSHs>.
2324
2325 void PUSHs(SV* sv)
2326
497711e7
GS
2327=for hackers
2328Found in file pp.h
2329
954c1994
GS
2330=item PUSHu
2331
2332Push an unsigned integer onto the stack. The stack must have room for this
2333element. See C<XPUSHu>.
2334
2335 void PUSHu(UV uv)
2336
497711e7
GS
2337=for hackers
2338Found in file pp.h
2339
954c1994
GS
2340=item PUTBACK
2341
2342Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2343See C<PUSHMARK> and L<perlcall> for other uses.
2344
2345 PUTBACK;
2346
497711e7
GS
2347=for hackers
2348Found in file pp.h
2349
94bdecf9 2350=item SP
d2cc3551 2351
94bdecf9
JH
2352Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2353C<SPAGAIN>.
d2cc3551 2354
94bdecf9
JH
2355=for hackers
2356Found in file pp.h
2357
2358=item SPAGAIN
2359
2360Refetch the stack pointer. Used after a callback. See L<perlcall>.
2361
2362 SPAGAIN;
d2cc3551
JH
2363
2364=for hackers
94bdecf9 2365Found in file pp.h
d2cc3551 2366
94bdecf9 2367=item XPUSHi
954c1994 2368
94bdecf9
JH
2369Push an integer onto the stack, extending the stack if necessary. Handles
2370'set' magic. See C<PUSHi>.
954c1994 2371
94bdecf9 2372 void XPUSHi(IV iv)
954c1994 2373
497711e7 2374=for hackers
94bdecf9 2375Found in file pp.h
497711e7 2376
94bdecf9 2377=item XPUSHn
954c1994 2378
94bdecf9
JH
2379Push a double onto the stack, extending the stack if necessary. Handles
2380'set' magic. See C<PUSHn>.
954c1994 2381
94bdecf9 2382 void XPUSHn(NV nv)
954c1994 2383
497711e7 2384=for hackers
94bdecf9 2385Found in file pp.h
497711e7 2386
94bdecf9 2387=item XPUSHp
954c1994 2388
94bdecf9
JH
2389Push a string onto the stack, extending the stack if necessary. The C<len>
2390indicates the length of the string. Handles 'set' magic. See
2391C<PUSHp>.
954c1994 2392
94bdecf9 2393 void XPUSHp(char* str, STRLEN len)
954c1994 2394
94bdecf9
JH
2395=for hackers
2396Found in file pp.h
2397
2398=item XPUSHs
2399
2400Push an SV onto the stack, extending the stack if necessary. Does not
2401handle 'set' magic. See C<PUSHs>.
2402
2403 void XPUSHs(SV* sv)
954c1994 2404
497711e7 2405=for hackers
94bdecf9 2406Found in file pp.h
497711e7 2407
94bdecf9 2408=item XPUSHu
954c1994 2409
94bdecf9
JH
2410Push an unsigned integer onto the stack, extending the stack if necessary.
2411See C<PUSHu>.
954c1994 2412
94bdecf9
JH
2413 void XPUSHu(UV uv)
2414
2415=for hackers
2416Found in file pp.h
2417
2418=item XSRETURN
2419
2420Return from XSUB, indicating number of items on the stack. This is usually
2421handled by C<xsubpp>.
2422
2423 void XSRETURN(int nitems)
954c1994 2424
497711e7
GS
2425=for hackers
2426Found in file XSUB.h
2427
94bdecf9 2428=item XSRETURN_IV
954c1994 2429
94bdecf9 2430Return an integer from an XSUB immediately. Uses C<XST_mIV>.
954c1994 2431
94bdecf9 2432 void XSRETURN_IV(IV iv)
954c1994 2433
497711e7 2434=for hackers
94bdecf9 2435Found in file XSUB.h
497711e7 2436
94bdecf9 2437=item XSRETURN_NO
954c1994 2438
94bdecf9 2439Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
954c1994 2440
94bdecf9 2441 XSRETURN_NO;
954c1994 2442
497711e7 2443=for hackers
94bdecf9 2444Found in file XSUB.h
497711e7 2445
94bdecf9 2446=item XSRETURN_NV
954c1994 2447
94bdecf9 2448Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994 2449
94bdecf9 2450 void XSRETURN_NV(NV nv)
954c1994 2451
497711e7 2452=for hackers
94bdecf9
JH
2453Found in file XSUB.h
2454
2455=item XSRETURN_PV
2456
2457Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2458
2459 void XSRETURN_PV(char* str)
2460
2461=for hackers
2462Found in file XSUB.h
2463
2464=item XSRETURN_UNDEF
2465
2466Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2467
2468 XSRETURN_UNDEF;
2469
2470=for hackers
2471Found in file XSUB.h
2472
0ee80f49
JH
2473=item XSRETURN_UV
2474
2475Return an integer from an XSUB immediately. Uses C<XST_mUV>.
2476
2477 void XSRETURN_UV(IV uv)
2478
2479=for hackers
2480Found in file XSUB.h
2481
94bdecf9
JH
2482=item XSRETURN_YES
2483
2484Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2485
2486 XSRETURN_YES;
2487
2488=for hackers
2489Found in file XSUB.h
2490
2491=item XST_mIV
2492
2493Place an integer into the specified position C<pos> on the stack. The
2494value is stored in a new mortal SV.
2495
2496 void XST_mIV(int pos, IV iv)
2497
2498=for hackers
2499Found in file XSUB.h
2500
2501=item XST_mNO
2502
2503Place C<&PL_sv_no> into the specified position C<pos> on the
2504stack.
2505
2506 void XST_mNO(int pos)
2507
2508=for hackers
2509Found in file XSUB.h
2510
2511=item XST_mNV
2512
2513Place a double into the specified position C<pos> on the stack. The value
2514is stored in a new mortal SV.
2515
2516 void XST_mNV(int pos, NV nv)
2517
2518=for hackers
2519Found in file XSUB.h
2520
2521=item XST_mPV
2522
2523Place a copy of a string into the specified position C<pos> on the stack.
2524The value is stored in a new mortal SV.
2525
2526 void XST_mPV(int pos, char* str)
2527
2528=for hackers
2529Found in file XSUB.h
2530
2531=item XST_mUNDEF
2532
2533Place C<&PL_sv_undef> into the specified position C<pos> on the
2534stack.
2535
2536 void XST_mUNDEF(int pos)
2537
2538=for hackers
2539Found in file XSUB.h
2540
2541=item XST_mYES
2542
2543Place C<&PL_sv_yes> into the specified position C<pos> on the
2544stack.
2545
2546 void XST_mYES(int pos)
2547
2548=for hackers
2549Found in file XSUB.h
2550
2551
2552=back
2553
2554=head1 SV Flags
497711e7 2555
94bdecf9 2556=over 8
954c1994 2557
94bdecf9 2558=item svtype
954c1994 2559
94bdecf9
JH
2560An enum of flags for Perl types. These are found in the file B<sv.h>
2561in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2562
497711e7 2563=for hackers
94bdecf9 2564Found in file sv.h
6e9d1081 2565
94bdecf9 2566=item SVt_IV
6e9d1081 2567
94bdecf9 2568Integer type flag for scalars. See C<svtype>.
6e9d1081
NC
2569
2570=for hackers
94bdecf9 2571Found in file sv.h
6e9d1081 2572
94bdecf9 2573=item SVt_NV
6e9d1081 2574
94bdecf9 2575Double type flag for scalars. See C<svtype>.
6e9d1081
NC
2576
2577=for hackers
94bdecf9 2578Found in file sv.h
6e9d1081 2579
94bdecf9 2580=item SVt_PV
6e9d1081 2581
94bdecf9 2582Pointer type flag for scalars. See C<svtype>.
6e9d1081
NC
2583
2584=for hackers
94bdecf9 2585Found in file sv.h
cd1ee231 2586
94bdecf9 2587=item SVt_PVAV
cd1ee231 2588
94bdecf9 2589Type flag for arrays. See C<svtype>.
cd1ee231
JH
2590
2591=for hackers
94bdecf9 2592Found in file sv.h
cd1ee231 2593
94bdecf9 2594=item SVt_PVCV
cd1ee231 2595
94bdecf9 2596Type flag for code refs. See C<svtype>.
cd1ee231
JH
2597
2598=for hackers
94bdecf9 2599Found in file sv.h
cd1ee231 2600
94bdecf9 2601=item SVt_PVHV
cd1ee231 2602
94bdecf9 2603Type flag for hashes. See C<svtype>.
cd1ee231
JH
2604
2605=for hackers
94bdecf9 2606Found in file sv.h
cd1ee231 2607
94bdecf9 2608=item SVt_PVMG
cd1ee231 2609
94bdecf9 2610Type flag for blessed scalars. See C<svtype>.
cd1ee231
JH
2611
2612=for hackers
94bdecf9 2613Found in file sv.h
cd1ee231 2614
cd1ee231 2615
94bdecf9 2616=back
cd1ee231 2617
94bdecf9 2618=head1 SV Manipulation Functions
cd1ee231 2619
94bdecf9 2620=over 8
cd1ee231 2621
94bdecf9 2622=item get_sv
cd1ee231 2623
94bdecf9
JH
2624Returns the SV of the specified Perl scalar. If C<create> is set and the
2625Perl variable does not exist then it will be created. If C<create> is not
2626set and the variable does not exist then NULL is returned.
2627
2628NOTE: the perl_ form of this function is deprecated.
2629
2630 SV* get_sv(const char* name, I32 create)
cd1ee231
JH
2631
2632=for hackers
94bdecf9 2633Found in file perl.c
cd1ee231 2634
94bdecf9 2635=item looks_like_number
cd1ee231 2636
94bdecf9
JH
2637Test if the content of an SV looks like a number (or is a number).
2638C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2639non-numeric warning), even if your atof() doesn't grok them.
cd1ee231 2640
94bdecf9 2641 I32 looks_like_number(SV* sv)
cd1ee231
JH
2642
2643=for hackers
94bdecf9 2644Found in file sv.c
2a5a0c38 2645
94bdecf9 2646=item newRV_inc
2a5a0c38 2647
94bdecf9
JH
2648Creates an RV wrapper for an SV. The reference count for the original SV is
2649incremented.
2a5a0c38 2650
94bdecf9 2651 SV* newRV_inc(SV* sv)
2a5a0c38
JH
2652
2653=for hackers
94bdecf9 2654Found in file sv.h
2a5a0c38 2655
94bdecf9 2656=item newRV_noinc
954c1994 2657
94bdecf9
JH
2658Creates an RV wrapper for an SV. The reference count for the original
2659SV is B<not> incremented.
2660
2661 SV* newRV_noinc(SV *sv)
954c1994 2662
497711e7 2663=for hackers
94bdecf9 2664Found in file sv.c
497711e7 2665
94bdecf9 2666=item newSV
954c1994 2667
94bdecf9
JH
2668Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2669with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2670macro.
954c1994 2671
94bdecf9 2672 SV* newSV(STRLEN len)
954c1994 2673
497711e7 2674=for hackers
94bdecf9 2675Found in file sv.c
497711e7 2676
94bdecf9 2677=item newSViv
954c1994 2678
94bdecf9
JH
2679Creates a new SV and copies an integer into it. The reference count for the
2680SV is set to 1.
954c1994 2681
94bdecf9 2682 SV* newSViv(IV i)
954c1994 2683
497711e7 2684=for hackers
94bdecf9 2685Found in file sv.c
497711e7 2686
94bdecf9 2687=item newSVnv
954c1994 2688
94bdecf9
JH
2689Creates a new SV and copies a floating point value into it.
2690The reference count for the SV is set to 1.
954c1994 2691
94bdecf9 2692 SV* newSVnv(NV n)
954c1994 2693
497711e7 2694=for hackers
94bdecf9 2695Found in file sv.c
497711e7 2696
94bdecf9 2697=item newSVpv
954c1994 2698
94bdecf9
JH
2699Creates a new SV and copies a string into it. The reference count for the
2700SV is set to 1. If C<len> is zero, Perl will compute the length using
2701strlen(). For efficiency, consider using C<newSVpvn> instead.
954c1994 2702
94bdecf9 2703 SV* newSVpv(const char* s, STRLEN len)
954c1994 2704
497711e7 2705=for hackers
94bdecf9 2706Found in file sv.c
497711e7 2707
94bdecf9 2708=item newSVpvf
954c1994 2709
94bdecf9
JH
2710Creates a new SV and initializes it with the string formatted like
2711C<sprintf>.
954c1994 2712
94bdecf9 2713 SV* newSVpvf(const char* pat, ...)
954c1994 2714
497711e7 2715=for hackers
94bdecf9 2716Found in file sv.c
497711e7 2717
94bdecf9 2718=item newSVpvn
954c1994 2719
94bdecf9
JH
2720Creates a new SV and copies a string into it. The reference count for the
2721SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
2722string. You are responsible for ensuring that the source string is at least
2723C<len> bytes long.
954c1994 2724
94bdecf9 2725 SV* newSVpvn(const char* s, STRLEN len)
954c1994 2726
497711e7 2727=for hackers
94bdecf9 2728Found in file sv.c
497711e7 2729
94bdecf9 2730=item newSVpvn_share
954c1994 2731
94bdecf9
JH
2732Creates a new SV with its SvPVX pointing to a shared string in the string
2733table. If the string does not already exist in the table, it is created
2734first. Turns on READONLY and FAKE. The string's hash is stored in the UV
2735slot of the SV; if the C<hash> parameter is non-zero, that value is used;
2736otherwise the hash is computed. The idea here is that as the string table
2737is used for shared hash keys these strings will have SvPVX == HeKEY and
2738hash lookup will avoid string compare.
954c1994 2739
94bdecf9 2740 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
954c1994 2741
497711e7 2742=for hackers
94bdecf9 2743Found in file sv.c
497711e7 2744
94bdecf9 2745=item newSVrv
954c1994 2746
94bdecf9
JH
2747Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
2748it will be upgraded to one. If C<classname> is non-null then the new SV will
2749be blessed in the specified package. The new SV is returned and its
2750reference count is 1.
954c1994 2751
94bdecf9 2752 SV* newSVrv(SV* rv, const char* classname)
954c1994 2753
497711e7 2754=for hackers
94bdecf9 2755Found in file sv.c
497711e7 2756
94bdecf9 2757=item newSVsv
954c1994 2758
94bdecf9
JH
2759Creates a new SV which is an exact duplicate of the original SV.
2760(Uses C<sv_setsv>).
954c1994 2761
94bdecf9 2762 SV* newSVsv(SV* old)
954c1994 2763
497711e7 2764=for hackers
94bdecf9 2765Found in file sv.c
497711e7 2766
94bdecf9 2767=item newSVuv
954c1994 2768
94bdecf9
JH
2769Creates a new SV and copies an unsigned integer into it.
2770The reference count for the SV is set to 1.
954c1994 2771
94bdecf9 2772 SV* newSVuv(UV u)
954c1994 2773
497711e7 2774=for hackers
94bdecf9 2775Found in file sv.c
497711e7 2776
954c1994
GS
2777=item SvCUR
2778
2779Returns the length of the string which is in the SV. See C<SvLEN>.
2780
2781 STRLEN SvCUR(SV* sv)
2782
497711e7
GS
2783=for hackers
2784Found in file sv.h
2785
954c1994
GS
2786=item SvCUR_set
2787
2788Set the length of the string which is in the SV. See C<SvCUR>.
2789
2790 void SvCUR_set(SV* sv, STRLEN len)
2791
497711e7
GS
2792=for hackers
2793Found in file sv.h
2794
94bdecf9 2795=item SvEND
954c1994 2796
94bdecf9
JH
2797Returns a pointer to the last character in the string which is in the SV.
2798See C<SvCUR>. Access the character as *(SvEND(sv)).
954c1994 2799
94bdecf9 2800 char* SvEND(SV* sv)
954c1994 2801
497711e7
GS
2802=for hackers
2803Found in file sv.h
2804
954c1994
GS
2805=item SvGROW
2806
2807Expands the character buffer in the SV so that it has room for the
2808indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 2809NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
2810Returns a pointer to the character buffer.
2811
679ac26e 2812 char * SvGROW(SV* sv, STRLEN len)
954c1994 2813
497711e7
GS
2814=for hackers
2815Found in file sv.h
2816
954c1994
GS
2817=item SvIOK
2818
2819Returns a boolean indicating whether the SV contains an integer.
2820
2821 bool SvIOK(SV* sv)
2822
497711e7
GS
2823=for hackers
2824Found in file sv.h
2825
954c1994
GS
2826=item SvIOKp
2827
2828Returns a boolean indicating whether the SV contains an integer. Checks
2829the B<private> setting. Use C<SvIOK>.
2830
2831 bool SvIOKp(SV* sv)
2832
497711e7
GS
2833=for hackers
2834Found in file sv.h
2835
e331fc52
JH
2836=item SvIOK_notUV
2837
f4758303 2838Returns a boolean indicating whether the SV contains a signed integer.
e331fc52 2839
12fa07df 2840 bool SvIOK_notUV(SV* sv)
e331fc52
JH
2841
2842=for hackers
2843Found in file sv.h
2844
954c1994
GS
2845=item SvIOK_off
2846
2847Unsets the IV status of an SV.
2848
2849 void SvIOK_off(SV* sv)
2850
497711e7
GS
2851=for hackers
2852Found in file sv.h
2853
954c1994
GS
2854=item SvIOK_on
2855
2856Tells an SV that it is an integer.
2857
2858 void SvIOK_on(SV* sv)
2859
497711e7
GS
2860=for hackers
2861Found in file sv.h
2862
954c1994
GS
2863=item SvIOK_only
2864
2865Tells an SV that it is an integer and disables all other OK bits.
2866
2867 void SvIOK_only(SV* sv)
2868
497711e7
GS
2869=for hackers
2870Found in file sv.h
2871
e331fc52
JH
2872=item SvIOK_only_UV
2873
2874Tells and SV that it is an unsigned integer and disables all other OK bits.
2875
2876 void SvIOK_only_UV(SV* sv)
2877
2878=for hackers
2879Found in file sv.h
2880
2881=item SvIOK_UV
2882
2883Returns a boolean indicating whether the SV contains an unsigned integer.
2884
12fa07df 2885 bool SvIOK_UV(SV* sv)
e331fc52
JH
2886
2887=for hackers
2888Found in file sv.h
2889
19dbb8f1
NC
2890=item SvIsCOW
2891
2892Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
2893hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
2894COW)
2895
2896 bool SvIsCOW(SV* sv)
2897
2898=for hackers
2899Found in file sv.h
2900
2901=item SvIsCOW_shared_hash
2902
2903Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
2904scalar.
2905
2906 bool SvIsCOW_shared_hash(SV* sv)
2907
2908=for hackers
2909Found in file sv.h
2910
954c1994
GS
2911=item SvIV
2912
645c22ef
DM
2913Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2914version which guarantees to evaluate sv only once.
954c1994
GS
2915
2916 IV SvIV(SV* sv)
2917
497711e7
GS
2918=for hackers
2919Found in file sv.h
2920
2baadb76 2921=item SvIVx
954c1994 2922
2baadb76
RGS
2923Coerces the given SV to an integer and returns it. Guarantees to evaluate
2924sv only once. Use the more efficient C<SvIV> otherwise.
954c1994 2925
2baadb76 2926 IV SvIVx(SV* sv)
954c1994 2927
497711e7
GS
2928=for hackers
2929Found in file sv.h
2930
2baadb76 2931=item SvIVX
645c22ef 2932
2baadb76
RGS
2933Returns the raw value in the SV's IV slot, without checks or conversions.
2934Only use when you are sure SvIOK is true. See also C<SvIV()>.
645c22ef 2935
2baadb76 2936 IV SvIVX(SV* sv)
645c22ef
DM
2937
2938=for hackers
2939Found in file sv.h
2940
891f9566
YST
2941=item SvIV_nomg
2942
2943Like C<SvIV> but doesn't process magic.
2944
2945 IV SvIV_nomg(SV* sv)
2946
2947=for hackers
2948Found in file sv.h
2949
954c1994
GS
2950=item SvLEN
2951
91e74348
JH
2952Returns the size of the string buffer in the SV, not including any part
2953attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
2954
2955 STRLEN SvLEN(SV* sv)
2956
497711e7
GS
2957=for hackers
2958Found in file sv.h
2959
954c1994
GS
2960=item SvNIOK
2961
2962Returns a boolean indicating whether the SV contains a number, integer or
2963double.
2964
2965 bool SvNIOK(SV* sv)
2966
497711e7
GS
2967=for hackers
2968Found in file sv.h
2969
954c1994
GS
2970=item SvNIOKp
2971
2972Returns a boolean indicating whether the SV contains a number, integer or
2973double. Checks the B<private> setting. Use C<SvNIOK>.
2974
2975 bool SvNIOKp(SV* sv)
2976
497711e7
GS
2977=for hackers
2978Found in file sv.h
2979
954c1994
GS
2980=item SvNIOK_off
2981
2982Unsets the NV/IV status of an SV.
2983
2984 void SvNIOK_off(SV* sv)
2985
497711e7
GS
2986=for hackers
2987Found in file sv.h
2988
954c1994
GS
2989=item SvNOK
2990
2991Returns a boolean indicating whether the SV contains a double.
2992
2993 bool SvNOK(SV* sv)
2994
497711e7
GS
2995=for hackers
2996Found in file sv.h
2997
954c1994
GS
2998=item SvNOKp
2999
3000Returns a boolean indicating whether the SV contains a double. Checks the
3001B<private> setting. Use C<SvNOK>.
3002
3003 bool SvNOKp(SV* sv)
3004
497711e7
GS
3005=for hackers
3006Found in file sv.h
3007
954c1994
GS
3008=item SvNOK_off
3009
3010Unsets the NV status of an SV.
3011
3012 void SvNOK_off(SV* sv)
3013
497711e7
GS
3014=for hackers
3015Found in file sv.h
3016
954c1994
GS
3017=item SvNOK_on
3018
3019Tells an SV that it is a double.
3020
3021 void SvNOK_on(SV* sv)
3022
497711e7
GS
3023=for hackers
3024Found in file sv.h
3025
954c1994
GS
3026=item SvNOK_only
3027
3028Tells an SV that it is a double and disables all other OK bits.
3029
3030 void SvNOK_only(SV* sv)
3031
497711e7
GS
3032=for hackers
3033Found in file sv.h
3034
954c1994
GS
3035=item SvNV
3036
645c22ef
DM
3037Coerce the given SV to a double and return it. See C<SvNVx> for a version
3038which guarantees to evaluate sv only once.
954c1994
GS
3039
3040 NV SvNV(SV* sv)
3041
497711e7
GS
3042=for hackers
3043Found in file sv.h
3044
b9381830 3045=item SvNVX
645c22ef 3046
b9381830
JP
3047Returns the raw value in the SV's NV slot, without checks or conversions.
3048Only use when you are sure SvNOK is true. See also C<SvNV()>.
645c22ef 3049
b9381830 3050 NV SvNVX(SV* sv)
645c22ef
DM
3051
3052=for hackers
3053Found in file sv.h
3054
b9381830 3055=item SvNVx
954c1994 3056
b9381830
JP
3057Coerces the given SV to a double and returns it. Guarantees to evaluate
3058sv only once. Use the more efficient C<SvNV> otherwise.
954c1994 3059
b9381830 3060 NV SvNVx(SV* sv)
954c1994 3061
497711e7
GS
3062=for hackers
3063Found in file sv.h
3064
954c1994
GS
3065=item SvOK
3066
3067Returns a boolean indicating whether the value is an SV.
3068
3069 bool SvOK(SV* sv)
3070
497711e7
GS
3071=for hackers
3072Found in file sv.h
3073
954c1994
GS
3074=item SvOOK
3075
3076Returns a boolean indicating whether the SvIVX is a valid offset value for
3077the SvPVX. This hack is used internally to speed up removal of characters
3078from the beginning of a SvPV. When SvOOK is true, then the start of the
3079allocated string buffer is really (SvPVX - SvIVX).
3080
3081 bool SvOOK(SV* sv)
3082
497711e7
GS
3083=for hackers
3084Found in file sv.h
3085
954c1994
GS
3086=item SvPOK
3087
3088Returns a boolean indicating whether the SV contains a character
3089string.
3090
3091 bool SvPOK(SV* sv)
3092
497711e7
GS
3093=for hackers
3094Found in file sv.h
3095
954c1994
GS
3096=item SvPOKp
3097
3098Returns a boolean indicating whether the SV contains a character string.
3099Checks the B<private> setting. Use C<SvPOK>.
3100
3101 bool SvPOKp(SV* sv)
3102
497711e7
GS
3103=for hackers
3104Found in file sv.h
3105
954c1994
GS
3106=item SvPOK_off
3107
3108Unsets the PV status of an SV.
3109
3110 void SvPOK_off(SV* sv)
3111
497711e7
GS
3112=for hackers
3113Found in file sv.h
3114
954c1994
GS
3115=item SvPOK_on
3116
3117Tells an SV that it is a string.
3118
3119 void SvPOK_on(SV* sv)
3120
497711e7
GS
3121=for hackers
3122Found in file sv.h
3123
954c1994
GS
3124=item SvPOK_only
3125
3126Tells an SV that it is a string and disables all other OK bits.
1e54db1a 3127Will also turn off the UTF-8 status.
954c1994
GS
3128
3129 void SvPOK_only(SV* sv)
3130
497711e7
GS
3131=for hackers
3132Found in file sv.h
3133
914184e1
JH
3134=item SvPOK_only_UTF8
3135
d5ce4a7c 3136Tells an SV that it is a string and disables all other OK bits,
1e54db1a 3137and leaves the UTF-8 status as it was.
f1a1024e 3138
914184e1
JH
3139 void SvPOK_only_UTF8(SV* sv)
3140
3141=for hackers
3142Found in file sv.h
3143
954c1994
GS
3144=item SvPV
3145
12b7c5c7
JH
3146Returns a pointer to the string in the SV, or a stringified form of
3147the SV if the SV does not contain a string. The SV may cache the
3148stringified version becoming C<SvPOK>. Handles 'get' magic. See also
645c22ef 3149C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
3150
3151 char* SvPV(SV* sv, STRLEN len)
3152
497711e7
GS
3153=for hackers
3154Found in file sv.h
3155
645c22ef
DM
3156=item SvPVbyte
3157
3158Like C<SvPV>, but converts sv to byte representation first if necessary.
3159
3160 char* SvPVbyte(SV* sv, STRLEN len)
3161
3162=for hackers
3163Found in file sv.h
3164
3165=item SvPVbytex
3166
3167Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 3168Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
3169otherwise.
3170
645c22ef
DM
3171 char* SvPVbytex(SV* sv, STRLEN len)
3172
3173=for hackers
3174Found in file sv.h
3175
3176=item SvPVbytex_force
3177
3178Like C<SvPV_force>, but converts sv to byte representation first if necessary.
d1be9408 3179Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
645c22ef
DM
3180otherwise.
3181
3182 char* SvPVbytex_force(SV* sv, STRLEN len)
3183
3184=for hackers
3185Found in file sv.h
3186
3187=item SvPVbyte_force
3188
3189Like C<SvPV_force>, but converts sv to byte representation first if necessary.
3190
3191 char* SvPVbyte_force(SV* sv, STRLEN len)
3192
3193=for hackers
3194Found in file sv.h
3195
3196=item SvPVbyte_nolen
3197
3198Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
3199
1fdc5aa6 3200 char* SvPVbyte_nolen(SV* sv)
645c22ef
DM
3201
3202=for hackers
3203Found in file sv.h
3204
3205=item SvPVutf8
3206
1fdc5aa6 3207Like C<SvPV>, but converts sv to utf8 first if necessary.
645c22ef
DM
3208
3209 char* SvPVutf8(SV* sv, STRLEN len)
3210
3211=for hackers
3212Found in file sv.h
3213
3214=item SvPVutf8x
3215
1fdc5aa6 3216Like C<SvPV>, but converts sv to utf8 first if necessary.
d1be9408 3217Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
645c22ef
DM
3218otherwise.
3219
3220 char* SvPVutf8x(SV* sv, STRLEN len)
3221
3222=for hackers
3223Found in file sv.h
3224
3225=item SvPVutf8x_force
3226
1fdc5aa6 3227Like C<SvPV_force>, but converts sv to utf8 first if necessary.
d1be9408 3228Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
645c22ef
DM
3229otherwise.
3230
3231 char* SvPVutf8x_force(SV* sv, STRLEN len)
3232
3233=for hackers
3234Found in file sv.h
3235
3236=item SvPVutf8_force
3237
1fdc5aa6 3238Like C<SvPV_force>, but converts sv to utf8 first if necessary.
645c22ef
DM
3239
3240 char* SvPVutf8_force(SV* sv, STRLEN len)
3241
3242=for hackers
3243Found in file sv.h
3244
3245=item SvPVutf8_nolen
3246
1fdc5aa6 3247Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
645c22ef 3248
1fdc5aa6 3249 char* SvPVutf8_nolen(SV* sv)
645c22ef
DM
3250
3251=for hackers
3252Found in file sv.h
3253
b9381830 3254=item SvPVx
645c22ef 3255
b9381830 3256A version of C<SvPV> which guarantees to evaluate sv only once.
645c22ef 3257
b9381830 3258 char* SvPVx(SV* sv, STRLEN len)
645c22ef
DM
3259
3260=for hackers
3261Found in file sv.h
3262
b9381830 3263=item SvPVX
954c1994 3264
b9381830
JP
3265Returns a pointer to the physical string in the SV. The SV must contain a
3266string.
954c1994 3267
b9381830 3268 char* SvPVX(SV* sv)
954c1994 3269
497711e7
GS
3270=for hackers
3271Found in file sv.h
3272
954c1994
GS
3273=item SvPV_force
3274
12b7c5c7
JH
3275Like C<SvPV> but will force the SV into containing just a string
3276(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3277directly.
954c1994
GS
3278
3279 char* SvPV_force(SV* sv, STRLEN len)
3280
497711e7
GS
3281=for hackers
3282Found in file sv.h
3283
645c22ef
DM
3284=item SvPV_force_nomg
3285
12b7c5c7
JH
3286Like C<SvPV> but will force the SV into containing just a string
3287(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3288directly. Doesn't process magic.
645c22ef
DM
3289
3290 char* SvPV_force_nomg(SV* sv, STRLEN len)
3291
3292=for hackers
3293Found in file sv.h
3294
954c1994
GS
3295=item SvPV_nolen
3296
12b7c5c7
JH
3297Returns a pointer to the string in the SV, or a stringified form of
3298the SV if the SV does not contain a string. The SV may cache the
3299stringified form becoming C<SvPOK>. Handles 'get' magic.
954c1994
GS
3300
3301 char* SvPV_nolen(SV* sv)
3302
497711e7
GS
3303=for hackers
3304Found in file sv.h
3305
891f9566
YST
3306=item SvPV_nomg
3307
3308Like C<SvPV> but doesn't process magic.
3309
3310 char* SvPV_nomg(SV* sv, STRLEN len)
3311
3312=for hackers
3313Found in file sv.h
3314
954c1994
GS
3315=item SvREFCNT
3316
3317Returns the value of the object's reference count.
3318
3319 U32 SvREFCNT(SV* sv)
3320
497711e7
GS
3321=for hackers
3322Found in file sv.h
3323
954c1994
GS
3324=item SvREFCNT_dec
3325
3326Decrements the reference count of the given SV.
3327
3328 void SvREFCNT_dec(SV* sv)
3329
497711e7
GS
3330=for hackers
3331Found in file sv.h
3332
954c1994
GS
3333=item SvREFCNT_inc
3334
3335Increments the reference count of the given SV.
3336
3337 SV* SvREFCNT_inc(SV* sv)
3338
497711e7
GS
3339=for hackers
3340Found in file sv.h
3341
954c1994
GS
3342=item SvROK
3343
3344Tests if the SV is an RV.
3345
3346 bool SvROK(SV* sv)
3347
497711e7
GS
3348=for hackers
3349Found in file sv.h
3350
954c1994
GS
3351=item SvROK_off
3352
3353Unsets the RV status of an SV.
3354
3355 void SvROK_off(SV* sv)
3356
497711e7
GS
3357=for hackers
3358Found in file sv.h
3359
954c1994
GS
3360=item SvROK_on
3361
3362Tells an SV that it is an RV.
3363
3364 void SvROK_on(SV* sv)
3365
497711e7
GS
3366=for hackers
3367Found in file sv.h
3368
954c1994
GS
3369=item SvRV
3370
3371Dereferences an RV to return the SV.
3372
3373 SV* SvRV(SV* sv)
3374
497711e7
GS
3375=for hackers
3376Found in file sv.h
3377
954c1994
GS
3378=item SvSTASH
3379
3380Returns the stash of the SV.
3381
3382 HV* SvSTASH(SV* sv)
3383
497711e7
GS
3384=for hackers
3385Found in file sv.h
3386
954c1994
GS
3387=item SvTAINT
3388
c55831ac 3389Taints an SV if tainting is enabled.
954c1994
GS
3390
3391 void SvTAINT(SV* sv)
3392
497711e7
GS
3393=for hackers
3394Found in file sv.h
3395
954c1994
GS
3396=item SvTAINTED
3397
3398Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3399not.
3400
3401 bool SvTAINTED(SV* sv)
3402
497711e7
GS
3403=for hackers
3404Found in file sv.h
3405
954c1994
GS
3406=item SvTAINTED_off
3407
3408Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3409some of Perl's fundamental security features. XS module authors should not
3410use this function unless they fully understand all the implications of
3411unconditionally untainting the value. Untainting should be done in the
3412standard perl fashion, via a carefully crafted regexp, rather than directly
3413untainting variables.
3414
3415 void SvTAINTED_off(SV* sv)
3416
497711e7
GS
3417=for hackers
3418Found in file sv.h
3419
954c1994
GS
3420=item SvTAINTED_on
3421
c55831ac 3422Marks an SV as tainted if tainting is enabled.
954c1994
GS
3423
3424 void SvTAINTED_on(SV* sv)
3425
497711e7
GS
3426=for hackers
3427Found in file sv.h
3428
954c1994
GS
3429=item SvTRUE
3430
3431Returns a boolean indicating whether Perl would evaluate the SV as true or
3432false, defined or undefined. Does not handle 'get' magic.
3433
3434 bool SvTRUE(SV* sv)
3435
497711e7
GS
3436=for hackers
3437Found in file sv.h
3438
9f4817db 3439=item SvTYPE
af3c7592 3440
9f4817db
JH
3441Returns the type of the SV. See C<svtype>.
3442
3443 svtype SvTYPE(SV* sv)
954c1994 3444
497711e7
GS
3445=for hackers
3446Found in file sv.h
3447
a4f1a029
NIS
3448=item SvUNLOCK
3449
3450Releases a mutual exclusion lock on sv if a suitable module
3451has been loaded.
3452
3453
3454 void SvUNLOCK(SV* sv)
3455
3456=for hackers
3457Found in file sv.h
3458
a8586c98
JH
3459=item SvUOK
3460
3461Returns a boolean indicating whether the SV contains an unsigned integer.
3462
3463 void SvUOK(SV* sv)
3464
3465=for hackers
3466Found in file sv.h
3467
954c1994
GS
3468=item SvUPGRADE
3469
3470Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
3471perform the upgrade if necessary. See C<svtype>.
3472
3473 void SvUPGRADE(SV* sv, svtype type)
3474
497711e7
GS
3475=for hackers
3476Found in file sv.h
3477
914184e1
JH
3478=item SvUTF8
3479
3480Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3481
12fa07df 3482 bool SvUTF8(SV* sv)
914184e1
JH
3483
3484=for hackers
3485Found in file sv.h
3486
3487=item SvUTF8_off
3488
1e54db1a 3489Unsets the UTF-8 status of an SV.
914184e1
JH
3490
3491 void SvUTF8_off(SV *sv)
3492
3493=for hackers
3494Found in file sv.h
3495
3496=item