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