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