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