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