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