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