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