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