This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to version.pm 0.71, by John Peacock
[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 Global Variables
954c1994 1227
94bdecf9 1228=over 8
497711e7 1229
94bdecf9 1230=item PL_modglobal
d8c40edc 1231X<PL_modglobal>
954c1994 1232
94bdecf9
JH
1233C<PL_modglobal> is a general purpose, interpreter global HV for use by
1234extensions that need to keep information on a per-interpreter basis.
1235In a pinch, it can also be used as a symbol table for extensions
1236to share data among each other. It is a good idea to use keys
1237prefixed by the package name of the extension that owns the data.
954c1994 1238
94bdecf9 1239 HV* PL_modglobal
954c1994 1240
497711e7 1241=for hackers
94bdecf9 1242Found in file intrpvar.h
497711e7 1243
94bdecf9 1244=item PL_na
d8c40edc 1245X<PL_na>
6e9d1081 1246
94bdecf9
JH
1247A convenience variable which is typically used with C<SvPV> when one
1248doesn't care about the length of the string. It is usually more efficient
1249to either declare a local variable and use that instead or to use the
1250C<SvPV_nolen> macro.
6e9d1081 1251
94bdecf9 1252 STRLEN PL_na
6e9d1081 1253
94bdecf9
JH
1254=for hackers
1255Found in file thrdvar.h
6e9d1081 1256
94bdecf9 1257=item PL_sv_no
d8c40edc 1258X<PL_sv_no>
6e9d1081 1259
94bdecf9
JH
1260This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1261C<&PL_sv_no>.
1262
1263 SV PL_sv_no
6e9d1081
NC
1264
1265=for hackers
94bdecf9 1266Found in file intrpvar.h
6e9d1081 1267
94bdecf9 1268=item PL_sv_undef
d8c40edc 1269X<PL_sv_undef>
6e9d1081 1270
94bdecf9 1271This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
6e9d1081 1272
94bdecf9 1273 SV PL_sv_undef
6e9d1081 1274
94bdecf9
JH
1275=for hackers
1276Found in file intrpvar.h
6e9d1081 1277
94bdecf9 1278=item PL_sv_yes
d8c40edc 1279X<PL_sv_yes>
6e9d1081 1280
94bdecf9
JH
1281This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1282C<&PL_sv_yes>.
1283
1284 SV PL_sv_yes
6e9d1081
NC
1285
1286=for hackers
94bdecf9 1287Found in file intrpvar.h
6e9d1081 1288
6e9d1081 1289
94bdecf9 1290=back
6e9d1081 1291
94bdecf9 1292=head1 GV Functions
6e9d1081 1293
94bdecf9 1294=over 8
6e9d1081 1295
954c1994 1296=item GvSV
d8c40edc 1297X<GvSV>
954c1994
GS
1298
1299Return the SV from the GV.
1300
1301 SV* GvSV(GV* gv)
1302
497711e7
GS
1303=for hackers
1304Found in file gv.h
1305
9f435386
RGS
1306=item gv_const_sv
1307X<gv_const_sv>
1308
1309If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1310inlining, or C<gv> is a placeholder reference that would be promoted to such
1311a typeglob, then returns the value returned by the sub. Otherwise, returns
1312NULL.
1313
1314 SV* gv_const_sv(GV* gv)
1315
1316=for hackers
1317Found in file gv.c
1318
954c1994 1319=item gv_fetchmeth
d8c40edc 1320X<gv_fetchmeth>
954c1994
GS
1321
1322Returns the glob with the given C<name> and a defined subroutine or
1323C<NULL>. The glob lives in the given C<stash>, or in the stashes
a453c169 1324accessible via @ISA and UNIVERSAL::.
954c1994
GS
1325
1326The argument C<level> should be either 0 or -1. If C<level==0>, as a
1327side-effect creates a glob with the given C<name> in the given C<stash>
1328which in the case of success contains an alias for the subroutine, and sets
1c846c1f 1329up caching info for this glob. Similarly for all the searched stashes.
954c1994
GS
1330
1331This function grants C<"SUPER"> token as a postfix of the stash name. The
1332GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
4929bf7b 1333visible to Perl code. So when calling C<call_sv>, you should not use
954c1994 1334the GV directly; instead, you should use the method's CV, which can be
1c846c1f 1335obtained from the GV with the C<GvCV> macro.
954c1994
GS
1336
1337 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1338
497711e7
GS
1339=for hackers
1340Found in file gv.c
1341
954c1994 1342=item gv_fetchmethod_autoload
d8c40edc 1343X<gv_fetchmethod_autoload>
954c1994
GS
1344
1345Returns the glob which contains the subroutine to call to invoke the method
1346on the C<stash>. In fact in the presence of autoloading this may be the
1347glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
1c846c1f 1348already setup.
954c1994
GS
1349
1350The third parameter of C<gv_fetchmethod_autoload> determines whether
1351AUTOLOAD lookup is performed if the given method is not present: non-zero
1c846c1f 1352means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
954c1994 1353Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1c846c1f 1354with a non-zero C<autoload> parameter.
954c1994
GS
1355
1356These functions grant C<"SUPER"> token as a prefix of the method name. Note
1357that if you want to keep the returned glob for a long time, you need to
1358check for it being "AUTOLOAD", since at the later time the call may load a
1359different subroutine due to $AUTOLOAD changing its value. Use the glob
1c846c1f 1360created via a side effect to do this.
954c1994
GS
1361
1362These functions have the same side-effects and as C<gv_fetchmeth> with
1363C<level==0>. C<name> should be writable if contains C<':'> or C<'
1364''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1c846c1f 1365C<call_sv> apply equally to these functions.
954c1994
GS
1366
1367 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1368
497711e7
GS
1369=for hackers
1370Found in file gv.c
1371
0c81b680 1372=item gv_fetchmeth_autoload
d8c40edc 1373X<gv_fetchmeth_autoload>
0c81b680
JH
1374
1375Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1376Returns a glob for the subroutine.
1377
1378For an autoloaded subroutine without a GV, will create a GV even
1379if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
1380of the result may be zero.
1381
1382 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1383
1384=for hackers
1385Found in file gv.c
1386
954c1994 1387=item gv_stashpv
d8c40edc 1388X<gv_stashpv>
954c1994 1389
da51bb9b 1390Returns a pointer to the stash for a specified package. Uses C<strlen> to
75c442e4 1391determine the length of C<name>, then calls C<gv_stashpvn()>.
bc96cb06 1392
da51bb9b 1393 HV* gv_stashpv(const char* name, I32 flags)
bc96cb06
SH
1394
1395=for hackers
1396Found in file gv.c
1397
1398=item gv_stashpvn
d8c40edc 1399X<gv_stashpvn>
bc96cb06 1400
da51bb9b
NC
1401Returns a pointer to the stash for a specified package. The C<namelen>
1402parameter indicates the length of the C<name>, in bytes. C<flags> is passed
1403to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
1404created if it does not already exist. If the package does not exist and
1405C<flags> is 0 (or any other setting that does not create packages) then NULL
1406is returned.
954c1994 1407
da51bb9b
NC
1408
1409 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
954c1994 1410
497711e7
GS
1411=for hackers
1412Found in file gv.c
1413
3fe05580
MHM
1414=item gv_stashpvs
1415X<gv_stashpvs>
1416
1417Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1418
1419 HV* gv_stashpvs(const char* name, I32 create)
1420
1421=for hackers
1422Found in file handy.h
1423
954c1994 1424=item gv_stashsv
d8c40edc 1425X<gv_stashsv>
954c1994 1426
da51bb9b 1427Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
954c1994 1428
da51bb9b 1429 HV* gv_stashsv(SV* sv, I32 flags)
954c1994 1430
497711e7
GS
1431=for hackers
1432Found in file gv.c
1433
954c1994 1434
94bdecf9 1435=back
954c1994 1436
94bdecf9 1437=head1 Handy Values
497711e7 1438
94bdecf9 1439=over 8
954c1994 1440
e509e693 1441=item Nullav
d8c40edc 1442X<Nullav>
497711e7 1443
e509e693 1444Null AV pointer.
954c1994 1445
94bdecf9 1446=for hackers
e509e693 1447Found in file av.h
954c1994 1448
dd2155a4 1449=item Nullch
d8c40edc 1450X<Nullch>
94bdecf9
JH
1451
1452Null character pointer.
2307c6d0 1453
497711e7 1454=for hackers
94bdecf9 1455Found in file handy.h
497711e7 1456
e509e693 1457=item Nullcv
d8c40edc 1458X<Nullcv>
e509e693
SH
1459
1460Null CV pointer.
1461
1462=for hackers
1463Found in file cv.h
1464
1465=item Nullhv
d8c40edc 1466X<Nullhv>
e509e693
SH
1467
1468Null HV pointer.
1469
1470=for hackers
1471Found in file hv.h
1472
94bdecf9 1473=item Nullsv
d8c40edc 1474X<Nullsv>
954c1994 1475
94bdecf9 1476Null SV pointer.
954c1994 1477
497711e7 1478=for hackers
94bdecf9 1479Found in file handy.h
497711e7 1480
954c1994 1481
94bdecf9 1482=back
954c1994 1483
94bdecf9 1484=head1 Hash Manipulation Functions
497711e7 1485
94bdecf9 1486=over 8
954c1994 1487
94bdecf9 1488=item get_hv
d8c40edc 1489X<get_hv>
954c1994 1490
94bdecf9
JH
1491Returns the HV of the specified Perl hash. If C<create> is set and the
1492Perl variable does not exist then it will be created. If C<create> is not
1493set and the variable does not exist then NULL is returned.
497711e7 1494
94bdecf9 1495NOTE: the perl_ form of this function is deprecated.
954c1994 1496
94bdecf9 1497 HV* get_hv(const char* name, I32 create)
954c1994 1498
497711e7 1499=for hackers
94bdecf9 1500Found in file perl.c
497711e7 1501
e509e693 1502=item HEf_SVKEY
d8c40edc 1503X<HEf_SVKEY>
e509e693
SH
1504
1505This flag, used in the length slot of hash entries and magic structures,
1506specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1507is to be expected. (For information only--not to be used).
1508
1509=for hackers
1510Found in file hv.h
1511
954c1994 1512=item HeHASH
d8c40edc 1513X<HeHASH>
954c1994
GS
1514
1515Returns the computed hash stored in the hash entry.
1516
1517 U32 HeHASH(HE* he)
1518
497711e7
GS
1519=for hackers
1520Found in file hv.h
1521
954c1994 1522=item HeKEY
d8c40edc 1523X<HeKEY>
954c1994
GS
1524
1525Returns the actual pointer stored in the key slot of the hash entry. The
1526pointer may be either C<char*> or C<SV*>, depending on the value of
1527C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
1528usually preferable for finding the value of a key.
1529
1530 void* HeKEY(HE* he)
1531
497711e7
GS
1532=for hackers
1533Found in file hv.h
1534
954c1994 1535=item HeKLEN
d8c40edc 1536X<HeKLEN>
954c1994
GS
1537
1538If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1539holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
1540be assigned to. The C<HePV()> macro is usually preferable for finding key
1541lengths.
1542
1543 STRLEN HeKLEN(HE* he)
1544
497711e7
GS
1545=for hackers
1546Found in file hv.h
1547
954c1994 1548=item HePV
d8c40edc 1549X<HePV>
954c1994
GS
1550
1551Returns the key slot of the hash entry as a C<char*> value, doing any
1552necessary dereferencing of possibly C<SV*> keys. The length of the string
1553is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
1554not care about what the length of the key is, you may use the global
1555variable C<PL_na>, though this is rather less efficient than using a local
1556variable. Remember though, that hash keys in perl are free to contain
1557embedded nulls, so using C<strlen()> or similar is not a good way to find
1558the length of hash keys. This is very similar to the C<SvPV()> macro
1559described elsewhere in this document.
1560
1561 char* HePV(HE* he, STRLEN len)
1562
497711e7
GS
1563=for hackers
1564Found in file hv.h
1565
954c1994 1566=item HeSVKEY
d8c40edc 1567X<HeSVKEY>
954c1994 1568
458cb9d2 1569Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
954c1994
GS
1570contain an C<SV*> key.
1571
1572 SV* HeSVKEY(HE* he)
1573
497711e7
GS
1574=for hackers
1575Found in file hv.h
1576
954c1994 1577=item HeSVKEY_force
d8c40edc 1578X<HeSVKEY_force>
954c1994
GS
1579
1580Returns the key as an C<SV*>. Will create and return a temporary mortal
1581C<SV*> if the hash entry contains only a C<char*> key.
1582
1583 SV* HeSVKEY_force(HE* he)
1584
497711e7
GS
1585=for hackers
1586Found in file hv.h
1587
954c1994 1588=item HeSVKEY_set
d8c40edc 1589X<HeSVKEY_set>
954c1994
GS
1590
1591Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1592indicate the presence of an C<SV*> key, and returns the same
1593C<SV*>.
1594
1595 SV* HeSVKEY_set(HE* he, SV* sv)
1596
497711e7
GS
1597=for hackers
1598Found in file hv.h
1599
954c1994 1600=item HeVAL
d8c40edc 1601X<HeVAL>
954c1994
GS
1602
1603Returns the value slot (type C<SV*>) stored in the hash entry.
1604
1605 SV* HeVAL(HE* he)
1606
497711e7
GS
1607=for hackers
1608Found in file hv.h
1609
954c1994 1610=item HvNAME
d8c40edc 1611X<HvNAME>
954c1994 1612
9282b5fd
SH
1613Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1614See C<SvSTASH>, C<CvSTASH>.
954c1994
GS
1615
1616 char* HvNAME(HV* stash)
1617
497711e7
GS
1618=for hackers
1619Found in file hv.h
1620
ecae49c0 1621=item hv_assert
d8c40edc 1622X<hv_assert>
ecae49c0
NC
1623
1624Check that a hash is in an internally consistent state.
1625
1626 void hv_assert(HV* tb)
1627
1628=for hackers
1629Found in file hv.c
1630
954c1994 1631=item hv_clear
d8c40edc 1632X<hv_clear>
954c1994
GS
1633
1634Clears a hash, making it empty.
1635
1636 void hv_clear(HV* tb)
1637
497711e7
GS
1638=for hackers
1639Found in file hv.c
1640
3540d4ce 1641=item hv_clear_placeholders
d8c40edc 1642X<hv_clear_placeholders>
3540d4ce
AB
1643
1644Clears any placeholders from a hash. If a restricted hash has any of its keys
1645marked as readonly and the key is subsequently deleted, the key is not actually
1646deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
1647it so it will be ignored by future operations such as iterating over the hash,
fa11829f 1648but will still allow the hash to have a value reassigned to the key at some
3540d4ce
AB
1649future point. This function clears any such placeholder keys from the hash.
1650See Hash::Util::lock_keys() for an example of its use.
1651
1652 void hv_clear_placeholders(HV* hb)
1653
1654=for hackers
1655Found in file hv.c
1656
954c1994 1657=item hv_delete
d8c40edc 1658X<hv_delete>
954c1994
GS
1659
1660Deletes a key/value pair in the hash. The value SV is removed from the
1c846c1f 1661hash and returned to the caller. The C<klen> is the length of the key.
954c1994
GS
1662The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1663will be returned.
1664
da58a35d 1665 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
954c1994 1666
497711e7
GS
1667=for hackers
1668Found in file hv.c
1669
954c1994 1670=item hv_delete_ent
d8c40edc 1671X<hv_delete_ent>
954c1994
GS
1672
1673Deletes a key/value pair in the hash. The value SV is removed from the
1674hash and returned to the caller. The C<flags> value will normally be zero;
1675if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
1676precomputed hash value, or 0 to ask for it to be computed.
1677
1678 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1679
497711e7
GS
1680=for hackers
1681Found in file hv.c
1682
954c1994 1683=item hv_exists
d8c40edc 1684X<hv_exists>
954c1994
GS
1685
1686Returns a boolean indicating whether the specified hash key exists. The
1687C<klen> is the length of the key.
1688
da58a35d 1689 bool hv_exists(HV* tb, const char* key, I32 klen)
954c1994 1690
497711e7
GS
1691=for hackers
1692Found in file hv.c
1693
954c1994 1694=item hv_exists_ent
d8c40edc 1695X<hv_exists_ent>
954c1994
GS
1696
1697Returns a boolean indicating whether the specified hash key exists. C<hash>
1698can be a valid precomputed hash value, or 0 to ask for it to be
1699computed.
1700
1701 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
1702
497711e7
GS
1703=for hackers
1704Found in file hv.c
1705
954c1994 1706=item hv_fetch
d8c40edc 1707X<hv_fetch>
954c1994
GS
1708
1709Returns the SV which corresponds to the specified key in the hash. The
1710C<klen> is the length of the key. If C<lval> is set then the fetch will be
1711part of a store. Check that the return value is non-null before
f4758303 1712dereferencing it to an C<SV*>.
954c1994 1713
96f1132b 1714See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1715information on how to use this function on tied hashes.
1716
da58a35d 1717 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
954c1994 1718
497711e7
GS
1719=for hackers
1720Found in file hv.c
1721
3fe05580
MHM
1722=item hv_fetchs
1723X<hv_fetchs>
1724
1725Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1726
1727 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
1728
1729=for hackers
1730Found in file handy.h
1731
954c1994 1732=item hv_fetch_ent
d8c40edc 1733X<hv_fetch_ent>
954c1994
GS
1734
1735Returns the hash entry which corresponds to the specified key in the hash.
1736C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1737if you want the function to compute it. IF C<lval> is set then the fetch
1738will be part of a store. Make sure the return value is non-null before
1739accessing it. The return value when C<tb> is a tied hash is a pointer to a
1740static location, so be sure to make a copy of the structure if you need to
1c846c1f 1741store it somewhere.
954c1994 1742
96f1132b 1743See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1744information on how to use this function on tied hashes.
1745
1746 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1747
497711e7
GS
1748=for hackers
1749Found in file hv.c
1750
954c1994 1751=item hv_iterinit
d8c40edc 1752X<hv_iterinit>
954c1994
GS
1753
1754Prepares a starting point to traverse a hash table. Returns the number of
1755keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1c846c1f 1756currently only meaningful for hashes without tie magic.
954c1994
GS
1757
1758NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1759hash buckets that happen to be in use. If you still need that esoteric
1760value, you can get it through the macro C<HvFILL(tb)>.
1761
641d4181 1762
954c1994
GS
1763 I32 hv_iterinit(HV* tb)
1764
497711e7
GS
1765=for hackers
1766Found in file hv.c
1767
954c1994 1768=item hv_iterkey
d8c40edc 1769X<hv_iterkey>
954c1994
GS
1770
1771Returns the key from the current position of the hash iterator. See
1772C<hv_iterinit>.
1773
1774 char* hv_iterkey(HE* entry, I32* retlen)
1775
497711e7
GS
1776=for hackers
1777Found in file hv.c
1778
954c1994 1779=item hv_iterkeysv
d8c40edc 1780X<hv_iterkeysv>
954c1994
GS
1781
1782Returns the key as an C<SV*> from the current position of the hash
1783iterator. The return value will always be a mortal copy of the key. Also
1784see C<hv_iterinit>.
1785
1786 SV* hv_iterkeysv(HE* entry)
1787
497711e7
GS
1788=for hackers
1789Found in file hv.c
1790
954c1994 1791=item hv_iternext
d8c40edc 1792X<hv_iternext>
954c1994
GS
1793
1794Returns entries from a hash iterator. See C<hv_iterinit>.
1795
641d4181
JH
1796You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1797iterator currently points to, without losing your place or invalidating your
1798iterator. Note that in this case the current entry is deleted from the hash
1799with your iterator holding the last reference to it. Your iterator is flagged
1800to free the entry on the next call to C<hv_iternext>, so you must not discard
1801your iterator immediately else the entry will leak - call C<hv_iternext> to
1802trigger the resource deallocation.
1803
954c1994
GS
1804 HE* hv_iternext(HV* tb)
1805
497711e7
GS
1806=for hackers
1807Found in file hv.c
1808
954c1994 1809=item hv_iternextsv
d8c40edc 1810X<hv_iternextsv>
954c1994
GS
1811
1812Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1813operation.
1814
1815 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1816
497711e7
GS
1817=for hackers
1818Found in file hv.c
1819
641d4181 1820=item hv_iternext_flags
d8c40edc 1821X<hv_iternext_flags>
641d4181
JH
1822
1823Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
1824The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1825set the placeholders keys (for restricted hashes) will be returned in addition
1826to normal keys. By default placeholders are automatically skipped over.
384679aa
RGS
1827Currently a placeholder is implemented with a value that is
1828C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
641d4181
JH
1829restricted hashes may change, and the implementation currently is
1830insufficiently abstracted for any change to be tidy.
1831
1832NOTE: this function is experimental and may change or be
1833removed without notice.
1834
1835 HE* hv_iternext_flags(HV* tb, I32 flags)
1836
1837=for hackers
1838Found in file hv.c
1839
954c1994 1840=item hv_iterval
d8c40edc 1841X<hv_iterval>
954c1994
GS
1842
1843Returns the value from the current position of the hash iterator. See
1844C<hv_iterkey>.
1845
1846 SV* hv_iterval(HV* tb, HE* entry)
1847
497711e7
GS
1848=for hackers
1849Found in file hv.c
1850
954c1994 1851=item hv_magic
d8c40edc 1852X<hv_magic>
954c1994
GS
1853
1854Adds magic to a hash. See C<sv_magic>.
1855
1856 void hv_magic(HV* hv, GV* gv, int how)
1857
497711e7
GS
1858=for hackers
1859Found in file hv.c
1860
a3bcc51e 1861=item hv_scalar
d8c40edc 1862X<hv_scalar>
a3bcc51e
TP
1863
1864Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1865
1866 SV* hv_scalar(HV* hv)
1867
1868=for hackers
1869Found in file hv.c
1870
954c1994 1871=item hv_store
d8c40edc 1872X<hv_store>
954c1994
GS
1873
1874Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1875the length of the key. The C<hash> parameter is the precomputed hash
1876value; if it is zero then Perl will compute it. The return value will be
1877NULL if the operation failed or if the value did not need to be actually
1878stored within the hash (as in the case of tied hashes). Otherwise it can
1879be dereferenced to get the original C<SV*>. Note that the caller is
1880responsible for suitably incrementing the reference count of C<val> before
7e8c5dac
HS
1881the call, and decrementing it if the function returned NULL. Effectively
1882a successful hv_store takes ownership of one reference to C<val>. This is
1883usually what you want; a newly created SV has a reference count of one, so
1884if all your code does is create SVs then store them in a hash, hv_store
1885will own the only reference to the new SV, and your code doesn't need to do
1886anything further to tidy up. hv_store is not implemented as a call to
1887hv_store_ent, and does not create a temporary SV for the key, so if your
1888key data is not already in SV form then use hv_store in preference to
1889hv_store_ent.
954c1994 1890
96f1132b 1891See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1892information on how to use this function on tied hashes.
1893
da58a35d 1894 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
954c1994 1895
497711e7
GS
1896=for hackers
1897Found in file hv.c
1898
3fe05580
MHM
1899=item hv_stores
1900X<hv_stores>
1901
1902Like C<hv_store>, but takes a literal string instead of a string/length pair
1903and omits the hash parameter.
1904
1905 SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
1906
1907=for hackers
1908Found in file handy.h
1909
954c1994 1910=item hv_store_ent
d8c40edc 1911X<hv_store_ent>
954c1994
GS
1912
1913Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1914parameter is the precomputed hash value; if it is zero then Perl will
1915compute it. The return value is the new hash entry so created. It will be
1916NULL if the operation failed or if the value did not need to be actually
1917stored within the hash (as in the case of tied hashes). Otherwise the
f22d8e4b 1918contents of the return value can be accessed using the C<He?> macros
954c1994
GS
1919described here. Note that the caller is responsible for suitably
1920incrementing the reference count of C<val> before the call, and
7e8c5dac
HS
1921decrementing it if the function returned NULL. Effectively a successful
1922hv_store_ent takes ownership of one reference to C<val>. This is
1923usually what you want; a newly created SV has a reference count of one, so
1924if all your code does is create SVs then store them in a hash, hv_store
1925will own the only reference to the new SV, and your code doesn't need to do
1926anything further to tidy up. Note that hv_store_ent only reads the C<key>;
1927unlike C<val> it does not take ownership of it, so maintaining the correct
1928reference count on C<key> is entirely the caller's responsibility. hv_store
1929is not implemented as a call to hv_store_ent, and does not create a temporary
1930SV for the key, so if your key data is not already in SV form then use
1931hv_store in preference to hv_store_ent.
954c1994 1932
96f1132b 1933See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
954c1994
GS
1934information on how to use this function on tied hashes.
1935
1936 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1937
497711e7
GS
1938=for hackers
1939Found in file hv.c
1940
954c1994 1941=item hv_undef
d8c40edc 1942X<hv_undef>
954c1994
GS
1943
1944Undefines the hash.
1945
1946 void hv_undef(HV* tb)
1947
497711e7
GS
1948=for hackers
1949Found in file hv.c
1950
94bdecf9 1951=item newHV
d8c40edc 1952X<newHV>
d2cc3551 1953
94bdecf9 1954Creates a new HV. The reference count is set to 1.
d2cc3551 1955
94bdecf9 1956 HV* newHV()
d2cc3551
JH
1957
1958=for hackers
94bdecf9 1959Found in file hv.c
d2cc3551 1960
954c1994 1961
94bdecf9 1962=back
954c1994 1963
94bdecf9 1964=head1 Magical Functions
954c1994 1965
94bdecf9 1966=over 8
497711e7 1967
94bdecf9 1968=item mg_clear
d8c40edc 1969X<mg_clear>
954c1994 1970
94bdecf9 1971Clear something magical that the SV represents. See C<sv_magic>.
954c1994 1972
94bdecf9 1973 int mg_clear(SV* sv)
954c1994 1974
497711e7 1975=for hackers
94bdecf9 1976Found in file mg.c
497711e7 1977
94bdecf9 1978=item mg_copy
d8c40edc 1979X<mg_copy>
954c1994 1980
94bdecf9 1981Copies the magic from one SV to another. See C<sv_magic>.
954c1994 1982
94bdecf9 1983 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
954c1994 1984
497711e7 1985=for hackers
94bdecf9 1986Found in file mg.c
497711e7 1987
94bdecf9 1988=item mg_find
d8c40edc 1989X<mg_find>
954c1994 1990
94bdecf9 1991Finds the magic pointer for type matching the SV. See C<sv_magic>.
954c1994 1992
35a4481c 1993 MAGIC* mg_find(const SV* sv, int type)
954c1994 1994
497711e7 1995=for hackers
94bdecf9 1996Found in file mg.c
497711e7 1997
94bdecf9 1998=item mg_free
d8c40edc 1999X<mg_free>
954c1994 2000
94bdecf9 2001Free any magic storage used by the SV. See C<sv_magic>.
954c1994 2002
94bdecf9 2003 int mg_free(SV* sv)
954c1994 2004
497711e7 2005=for hackers
94bdecf9 2006Found in file mg.c
497711e7 2007
94bdecf9 2008=item mg_get
d8c40edc 2009X<mg_get>
eebe1485 2010
94bdecf9 2011Do magic after a value is retrieved from the SV. See C<sv_magic>.
282f25c9 2012
94bdecf9 2013 int mg_get(SV* sv)
eebe1485
SC
2014
2015=for hackers
94bdecf9 2016Found in file mg.c
eebe1485 2017
94bdecf9 2018=item mg_length
d8c40edc 2019X<mg_length>
eebe1485 2020
94bdecf9 2021Report on the SV's length. See C<sv_magic>.
eebe1485 2022
94bdecf9 2023 U32 mg_length(SV* sv)
eebe1485
SC
2024
2025=for hackers
94bdecf9 2026Found in file mg.c
eebe1485 2027
94bdecf9 2028=item mg_magical
d8c40edc 2029X<mg_magical>
954c1994 2030
94bdecf9 2031Turns on the magical status of an SV. See C<sv_magic>.
954c1994 2032
94bdecf9 2033 void mg_magical(SV* sv)
954c1994 2034
497711e7 2035=for hackers
94bdecf9 2036Found in file mg.c
497711e7 2037
94bdecf9 2038=item mg_set
d8c40edc 2039X<mg_set>
954c1994 2040
94bdecf9 2041Do magic after a value is assigned to the SV. See C<sv_magic>.
954c1994 2042
94bdecf9 2043 int mg_set(SV* sv)
954c1994 2044
497711e7 2045=for hackers
94bdecf9 2046Found in file mg.c
497711e7 2047
94bdecf9 2048=item SvGETMAGIC
d8c40edc 2049X<SvGETMAGIC>
954c1994 2050
94bdecf9
JH
2051Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2052argument more than once.
954c1994 2053
94bdecf9 2054 void SvGETMAGIC(SV* sv)
954c1994 2055
497711e7 2056=for hackers
94bdecf9 2057Found in file sv.h
497711e7 2058
a4f1a029 2059=item SvLOCK
d8c40edc 2060X<SvLOCK>
a4f1a029
NIS
2061
2062Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
2063has been loaded.
2064
2065 void SvLOCK(SV* sv)
2066
2067=for hackers
2068Found in file sv.h
2069
94bdecf9 2070=item SvSETMAGIC
d8c40edc 2071X<SvSETMAGIC>
7d3fb230 2072
94bdecf9
JH
2073Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2074argument more than once.
7d3fb230 2075
94bdecf9 2076 void SvSETMAGIC(SV* sv)
7d3fb230
BS
2077
2078=for hackers
94bdecf9 2079Found in file sv.h
7d3fb230 2080
94bdecf9 2081=item SvSetMagicSV
d8c40edc 2082X<SvSetMagicSV>
954c1994 2083
94bdecf9 2084Like C<SvSetSV>, but does any set magic required afterwards.
954c1994 2085
94bdecf9 2086 void SvSetMagicSV(SV* dsb, SV* ssv)
954c1994 2087
497711e7 2088=for hackers
94bdecf9 2089Found in file sv.h
497711e7 2090
a4f1a029 2091=item SvSetMagicSV_nosteal
d8c40edc 2092X<SvSetMagicSV_nosteal>
a4f1a029 2093
80663158 2094Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
a4f1a029
NIS
2095
2096 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2097
2098=for hackers
2099Found in file sv.h
2100
94bdecf9 2101=item SvSetSV
d8c40edc 2102X<SvSetSV>
954c1994 2103
94bdecf9
JH
2104Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2105more than once.
2106
2107 void SvSetSV(SV* dsb, SV* ssv)
954c1994 2108
497711e7 2109=for hackers
94bdecf9 2110Found in file sv.h
497711e7 2111
94bdecf9 2112=item SvSetSV_nosteal
d8c40edc 2113X<SvSetSV_nosteal>
954c1994 2114
94bdecf9
JH
2115Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2116ssv. May evaluate arguments more than once.
954c1994 2117
94bdecf9 2118 void SvSetSV_nosteal(SV* dsv, SV* ssv)
954c1994 2119
497711e7 2120=for hackers
94bdecf9 2121Found in file sv.h
497711e7 2122
a4f1a029 2123=item SvSHARE
d8c40edc 2124X<SvSHARE>
a4f1a029
NIS
2125
2126Arranges for sv to be shared between threads if a suitable module
2127has been loaded.
2128
2129 void SvSHARE(SV* sv)
2130
2131=for hackers
2132Found in file sv.h
2133
e509e693 2134=item SvUNLOCK
d8c40edc 2135X<SvUNLOCK>
e509e693
SH
2136
2137Releases a mutual exclusion lock on sv if a suitable module
2138has been loaded.
2139
2140 void SvUNLOCK(SV* sv)
2141
2142=for hackers
2143Found in file sv.h
2144
954c1994 2145
94bdecf9 2146=back
954c1994 2147
94bdecf9 2148=head1 Memory Management
954c1994 2149
94bdecf9 2150=over 8
497711e7 2151
94bdecf9 2152=item Copy
d8c40edc 2153X<Copy>
954c1994 2154
94bdecf9
JH
2155The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
2156source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2157the type. May fail on overlapping copies. See also C<Move>.
954c1994 2158
94bdecf9 2159 void Copy(void* src, void* dest, int nitems, type)
954c1994 2160
497711e7 2161=for hackers
94bdecf9 2162Found in file handy.h
497711e7 2163
e90e2364 2164=item CopyD
d8c40edc 2165X<CopyD>
e90e2364
NC
2166
2167Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2168optimise.
2169
2170 void * CopyD(void* src, void* dest, int nitems, type)
2171
2172=for hackers
2173Found in file handy.h
2174
94bdecf9 2175=item Move
d8c40edc 2176X<Move>
954c1994 2177
94bdecf9
JH
2178The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
2179source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2180the type. Can do overlapping moves. See also C<Copy>.
954c1994 2181
94bdecf9 2182 void Move(void* src, void* dest, int nitems, type)
954c1994 2183
497711e7 2184=for hackers
94bdecf9 2185Found in file handy.h
497711e7 2186
e90e2364 2187=item MoveD
d8c40edc 2188X<MoveD>
e90e2364
NC
2189
2190Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2191optimise.
2192
2193 void * MoveD(void* src, void* dest, int nitems, type)
2194
2195=for hackers
2196Found in file handy.h
2197
a02a5408 2198=item Newx
d8c40edc 2199X<Newx>
954c1994 2200
94bdecf9 2201The XSUB-writer's interface to the C C<malloc> function.
954c1994 2202
c5008215
JC
2203In 5.9.3, Newx() and friends replace the older New() API, and drops
2204the first parameter, I<x>, a debug aid which allowed callers to identify
37b8b4c9 2205themselves. This aid has been superseded by a new build option,
c5008215
JC
2206PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
2207there for use in XS modules supporting older perls.
2208
a02a5408 2209 void Newx(void* ptr, int nitems, type)
954c1994 2210
497711e7 2211=for hackers
94bdecf9 2212Found in file handy.h
497711e7 2213
a02a5408 2214=item Newxc
d8c40edc 2215X<Newxc>
954c1994 2216
94bdecf9 2217The XSUB-writer's interface to the C C<malloc> function, with
c5008215 2218cast. See also C<Newx>.
954c1994 2219
a02a5408 2220 void Newxc(void* ptr, int nitems, type, cast)
954c1994 2221
497711e7 2222=for hackers
94bdecf9 2223Found in file handy.h
954c1994 2224
a02a5408 2225=item Newxz
d8c40edc 2226X<Newxz>
954c1994 2227
94bdecf9 2228The XSUB-writer's interface to the C C<malloc> function. The allocated
c5008215 2229memory is zeroed with C<memzero>. See also C<Newx>.
a02a5408
JC
2230
2231 void Newxz(void* ptr, int nitems, type)
954c1994 2232
497711e7
GS
2233=for hackers
2234Found in file handy.h
2235
9965345d 2236=item Poison
d8c40edc 2237X<Poison>
9965345d 2238
7e337ee0 2239PoisonWith(0xEF) for catching access to freed memory.
9965345d
JH
2240
2241 void Poison(void* dest, int nitems, type)
2242
2243=for hackers
2244Found in file handy.h
2245
3fe05580
MHM
2246=item PoisonFree
2247X<PoisonFree>
2248
2249PoisonWith(0xEF) for catching access to freed memory.
2250
2251 void PoisonFree(void* dest, int nitems, type)
2252
2253=for hackers
2254Found in file handy.h
2255
7e337ee0
JH
2256=item PoisonNew
2257X<PoisonNew>
2258
2259PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2260
2261 void PoisonNew(void* dest, int nitems, type)
2262
2263=for hackers
2264Found in file handy.h
2265
2266=item PoisonWith
2267X<PoisonWith>
2268
2269Fill up memory with a byte pattern (a byte repeated over and over
2270again) that hopefully catches attempts to access uninitialized memory.
2271
2272 void PoisonWith(void* dest, int nitems, type, U8 byte)
2273
2274=for hackers
2275Found in file handy.h
2276
94bdecf9 2277=item Renew
d8c40edc 2278X<Renew>
954c1994 2279
94bdecf9 2280The XSUB-writer's interface to the C C<realloc> function.
954c1994 2281
94bdecf9 2282 void Renew(void* ptr, int nitems, type)
954c1994 2283
497711e7
GS
2284=for hackers
2285Found in file handy.h
2286
94bdecf9 2287=item Renewc
d8c40edc 2288X<Renewc>
954c1994 2289
94bdecf9
JH
2290The XSUB-writer's interface to the C C<realloc> function, with
2291cast.
954c1994 2292
94bdecf9 2293 void Renewc(void* ptr, int nitems, type, cast)
954c1994 2294
497711e7 2295=for hackers
94bdecf9 2296Found in file handy.h
497711e7 2297
94bdecf9 2298=item Safefree
d8c40edc 2299X<Safefree>
954c1994 2300
94bdecf9 2301The XSUB-writer's interface to the C C<free> function.
954c1994 2302
94bdecf9 2303 void Safefree(void* ptr)
954c1994 2304
497711e7
GS
2305=for hackers
2306Found in file handy.h
2307
94bdecf9 2308=item savepv
d8c40edc 2309X<savepv>
954c1994 2310
641d4181
JH
2311Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2312string which is a duplicate of C<pv>. The size of the string is
2313determined by C<strlen()>. The memory allocated for the new string can
2314be freed with the C<Safefree()> function.
954c1994 2315
641d4181 2316 char* savepv(const char* pv)
954c1994 2317
497711e7 2318=for hackers
94bdecf9 2319Found in file util.c
497711e7 2320
94bdecf9 2321=item savepvn
d8c40edc 2322X<savepvn>
954c1994 2323
641d4181
JH
2324Perl's version of what C<strndup()> would be if it existed. Returns a
2325pointer to a newly allocated string which is a duplicate of the first
cbf82dd0
NC
2326C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2327the new string can be freed with the C<Safefree()> function.
954c1994 2328
641d4181 2329 char* savepvn(const char* pv, I32 len)
954c1994 2330
497711e7 2331=for hackers
94bdecf9 2332Found in file util.c
497711e7 2333
3fe05580
MHM
2334=item savepvs
2335X<savepvs>
2336
2337Like C<savepvn>, but takes a literal string instead of a string/length pair.
2338
2339 char* savepvs(const char* s)
2340
2341=for hackers
2342Found in file handy.h
2343
a4f1a029 2344=item savesharedpv
d8c40edc 2345X<savesharedpv>
a4f1a029 2346
641d4181
JH
2347A version of C<savepv()> which allocates the duplicate string in memory
2348which is shared between threads.
a4f1a029 2349
641d4181 2350 char* savesharedpv(const char* pv)
a4f1a029
NIS
2351
2352=for hackers
2353Found in file util.c
2354
d9095cec
NC
2355=item savesharedpvn
2356X<savesharedpvn>
2357
2358A version of C<savepvn()> which allocates the duplicate string in memory
2359which is shared between threads. (With the specific difference that a NULL
2360pointer is not acceptable)
2361
2362 char* savesharedpvn(const char *const pv, const STRLEN len)
2363
2364=for hackers
2365Found in file util.c
2366
766f8916 2367=item savesvpv
d8c40edc 2368X<savesvpv>
766f8916 2369
9c2fe30c 2370A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
766f8916
MHM
2371the passed in SV using C<SvPV()>
2372
2373 char* savesvpv(SV* sv)
2374
2375=for hackers
2376Found in file util.c
2377
94bdecf9 2378=item StructCopy
d8c40edc 2379X<StructCopy>
954c1994 2380
94bdecf9 2381This is an architecture-independent macro to copy one structure to another.
954c1994 2382
94bdecf9 2383 void StructCopy(type src, type dest, type)
954c1994 2384
497711e7 2385=for hackers
94bdecf9 2386Found in file handy.h
497711e7 2387
94bdecf9 2388=item Zero
d8c40edc 2389X<Zero>
954c1994 2390
94bdecf9
JH
2391The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
2392destination, C<nitems> is the number of items, and C<type> is the type.
954c1994 2393
94bdecf9 2394 void Zero(void* dest, int nitems, type)
954c1994 2395
497711e7 2396=for hackers
94bdecf9 2397Found in file handy.h
497711e7 2398
e90e2364 2399=item ZeroD
d8c40edc 2400X<ZeroD>
e90e2364
NC
2401
2402Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2403optimise.
2404
2405 void * ZeroD(void* dest, int nitems, type)
2406
2407=for hackers
2408Found in file handy.h
2409
954c1994 2410
94bdecf9 2411=back
954c1994 2412
94bdecf9 2413=head1 Miscellaneous Functions
954c1994 2414
94bdecf9 2415=over 8
497711e7 2416
94bdecf9 2417=item fbm_compile
d8c40edc 2418X<fbm_compile>
8b4ac5a4 2419
94bdecf9
JH
2420Analyses the string in order to make fast searches on it using fbm_instr()
2421-- the Boyer-Moore algorithm.
8b4ac5a4 2422
94bdecf9 2423 void fbm_compile(SV* sv, U32 flags)
8b4ac5a4
JH
2424
2425=for hackers
94bdecf9 2426Found in file util.c
8b4ac5a4 2427
94bdecf9 2428=item fbm_instr
d8c40edc 2429X<fbm_instr>
954c1994 2430
94bdecf9 2431Returns the location of the SV in the string delimited by C<str> and
bd61b366 2432C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
94bdecf9
JH
2433does not have to be fbm_compiled, but the search will not be as fast
2434then.
954c1994 2435
94bdecf9 2436 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
954c1994 2437
497711e7 2438=for hackers
94bdecf9 2439Found in file util.c
497711e7 2440
94bdecf9 2441=item form
d8c40edc 2442X<form>
954c1994 2443
94bdecf9
JH
2444Takes a sprintf-style format pattern and conventional
2445(non-SV) arguments and returns the formatted string.
954c1994 2446
94bdecf9 2447 (char *) Perl_form(pTHX_ const char* pat, ...)
954c1994 2448
94bdecf9 2449can be used any place a string (char *) is required:
497711e7 2450
94bdecf9 2451 char * s = Perl_form("%d.%d",major,minor);
954c1994 2452
94bdecf9
JH
2453Uses a single private buffer so if you want to format several strings you
2454must explicitly copy the earlier strings away (and free the copies when you
2455are done).
954c1994 2456
94bdecf9 2457 char* form(const char* pat, ...)
954c1994 2458
497711e7 2459=for hackers
94bdecf9 2460Found in file util.c
497711e7 2461
94bdecf9 2462=item getcwd_sv
d8c40edc 2463X<getcwd_sv>
954c1994 2464
94bdecf9 2465Fill the sv with current working directory
954c1994 2466
94bdecf9 2467 int getcwd_sv(SV* sv)
954c1994 2468
497711e7 2469=for hackers
94bdecf9 2470Found in file util.c
497711e7 2471
d9fad198
JH
2472=item my_snprintf
2473X<my_snprintf>
2474
2475The C library C<snprintf> functionality, if available and
5b692037 2476standards-compliant (uses C<vsnprintf>, actually). However, if the
d9fad198 2477C<vsnprintf> is not available, will unfortunately use the unsafe
5b692037
JH
2478C<vsprintf> which can overrun the buffer (there is an overrun check,
2479but that may be too late). Consider using C<sv_vcatpvf> instead, or
2480getting C<vsnprintf>.
d9fad198
JH
2481
2482 int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2483
2484=for hackers
2485Found in file util.c
2486
9244d4ad
RGS
2487=item my_sprintf
2488X<my_sprintf>
2489
2490The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2491the length of the string written to the buffer. Only rare pre-ANSI systems
2492need the wrapper function - usually this is a direct call to C<sprintf>.
2493
2494 int my_sprintf(char *buffer, const char *pat, ...)
2495
2496=for hackers
2497Found in file util.c
2498
d9fad198
JH
2499=item my_vsnprintf
2500X<my_vsnprintf>
2501
5b692037
JH
2502The C library C<vsnprintf> if available and standards-compliant.
2503However, if if the C<vsnprintf> is not available, will unfortunately
2504use the unsafe C<vsprintf> which can overrun the buffer (there is an
2505overrun check, but that may be too late). Consider using
2506C<sv_vcatpvf> instead, or getting C<vsnprintf>.
d9fad198
JH
2507
2508 int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2509
2510=for hackers
2511Found in file util.c
2512
f333445c 2513=item new_version
d8c40edc 2514X<new_version>
f333445c
JP
2515
2516Returns a new version object based on the passed in SV:
2517
2518 SV *sv = new_version(SV *ver);
2519
2520Does not alter the passed in ver SV. See "upg_version" if you
2521want to upgrade the SV.
2522
2523 SV* new_version(SV *ver)
2524
2525=for hackers
2526Found in file util.c
2527
2528=item scan_version
d8c40edc 2529X<scan_version>
f333445c
JP
2530
2531Returns a pointer to the next character after the parsed
2532version string, as well as upgrading the passed in SV to
2533an RV.
2534
2535Function must be called with an already existing SV like
2536
137d6fc0 2537 sv = newSV(0);
8a0be661 2538 s = scan_version(s, SV *sv, bool qv);
f333445c
JP
2539
2540Performs some preprocessing to the string to ensure that
2541it has the correct characteristics of a version. Flags the
2542object if it contains an underscore (which denotes this
8a0be661 2543is an alpha version). The boolean qv denotes that the version
137d6fc0
JP
2544should be interpreted as if it had multiple decimals, even if
2545it doesn't.
f333445c 2546
9137345a 2547 const char* scan_version(const char *vstr, SV *sv, bool qv)
f333445c
JP
2548
2549=for hackers
2550Found in file util.c
2551
94bdecf9 2552=item strEQ
d8c40edc 2553X<strEQ>
954c1994 2554
94bdecf9 2555Test two strings to see if they are equal. Returns true or false.
954c1994 2556
94bdecf9 2557 bool strEQ(char* s1, char* s2)
954c1994 2558
497711e7 2559=for hackers
94bdecf9 2560Found in file handy.h
497711e7 2561
94bdecf9 2562=item strGE
d8c40edc 2563X<strGE>
1c846c1f 2564
94bdecf9
JH
2565Test two strings to see if the first, C<s1>, is greater than or equal to
2566the second, C<s2>. Returns true or false.
1c846c1f 2567
94bdecf9 2568 bool strGE(char* s1, char* s2)
1c846c1f
NIS
2569
2570=for hackers
94bdecf9 2571Found in file handy.h
1c846c1f 2572
94bdecf9 2573=item strGT
d8c40edc 2574X<strGT>
954c1994 2575
94bdecf9
JH
2576Test two strings to see if the first, C<s1>, is greater than the second,
2577C<s2>. Returns true or false.
954c1994 2578
94bdecf9 2579 bool strGT(char* s1, char* s2)
954c1994 2580
497711e7 2581=for hackers
94bdecf9 2582Found in file handy.h
497711e7 2583
94bdecf9 2584=item strLE
d8c40edc 2585X<strLE>
954c1994 2586
94bdecf9
JH
2587Test two strings to see if the first, C<s1>, is less than or equal to the
2588second, C<s2>. Returns true or false.
954c1994 2589
94bdecf9 2590 bool strLE(char* s1, char* s2)
954c1994 2591
497711e7 2592=for hackers
94bdecf9 2593Found in file handy.h
497711e7 2594
94bdecf9 2595=item strLT
d8c40edc 2596X<strLT>
1a3327fb 2597
94bdecf9
JH
2598Test two strings to see if the first, C<s1>, is less than the second,
2599C<s2>. Returns true or false.
1a3327fb 2600
94bdecf9 2601 bool strLT(char* s1, char* s2)
1a3327fb 2602
497711e7 2603=for hackers
94bdecf9 2604Found in file handy.h
497711e7 2605
94bdecf9 2606=item strNE
d8c40edc 2607X<strNE>
954c1994 2608
94bdecf9
JH
2609Test two strings to see if they are different. Returns true or
2610false.
2611
2612 bool strNE(char* s1, char* s2)
954c1994 2613
497711e7 2614=for hackers
94bdecf9 2615Found in file handy.h
497711e7 2616
94bdecf9 2617=item strnEQ
d8c40edc 2618X<strnEQ>
954c1994 2619
94bdecf9
JH
2620Test two strings to see if they are equal. The C<len> parameter indicates
2621the number of bytes to compare. Returns true or false. (A wrapper for
2622C<strncmp>).
2623
2624 bool strnEQ(char* s1, char* s2, STRLEN len)
954c1994 2625
497711e7 2626=for hackers
94bdecf9 2627Found in file handy.h
497711e7 2628
94bdecf9 2629=item strnNE
d8c40edc 2630X<strnNE>
954c1994 2631
94bdecf9
JH
2632Test two strings to see if they are different. The C<len> parameter
2633indicates the number of bytes to compare. Returns true or false. (A
2634wrapper for C<strncmp>).
954c1994 2635
94bdecf9 2636 bool strnNE(char* s1, char* s2, STRLEN len)
954c1994 2637
497711e7
GS
2638=for hackers
2639Found in file handy.h
2640
f333445c 2641=item sv_nosharing
d8c40edc 2642X<sv_nosharing>
f333445c
JP
2643
2644Dummy routine which "shares" an SV when there is no sharing module present.
9244d4ad
RGS
2645Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2646Exists to avoid test for a NULL function pointer and because it could
2647potentially warn under some level of strict-ness.
f333445c 2648
c48640ec 2649 void sv_nosharing(SV *sv)
f333445c
JP
2650
2651=for hackers
2652Found in file util.c
2653
f333445c 2654=item upg_version
d8c40edc 2655X<upg_version>
f333445c
JP
2656
2657In-place upgrade of the supplied SV to a version object.
2658
ac0e6a2f 2659 SV *sv = upg_version(SV *sv, bool qv);
f333445c 2660
ac0e6a2f
RGS
2661Returns a pointer to the upgraded SV. Set the boolean qv if you want
2662to force this SV to be interpreted as an "extended" version.
f333445c 2663
ac0e6a2f 2664 SV* upg_version(SV *ver, bool qv)
f333445c
JP
2665
2666=for hackers
2667Found in file util.c
2668
2669=item vcmp
d8c40edc 2670X<vcmp>
f333445c
JP
2671
2672Version object aware cmp. Both operands must already have been
2673converted into version objects.
2674
2675 int vcmp(SV *lvs, SV *rvs)
2676
2677=for hackers
2678Found in file util.c
2679
b9381830 2680=item vnormal
d8c40edc 2681X<vnormal>
b9381830
JP
2682
2683Accepts a version object and returns the normalized string
2684representation. Call like:
2685
2686 sv = vnormal(rv);
2687
2688NOTE: you can pass either the object directly or the SV
2689contained within the RV.
2690
2691 SV* vnormal(SV *vs)
2692
2693=for hackers
2694Found in file util.c
2695
f333445c 2696=item vnumify
d8c40edc 2697X<vnumify>
f333445c
JP
2698
2699Accepts a version object and returns the normalized floating
2700point representation. Call like:
2701
2702 sv = vnumify(rv);
2703
2704NOTE: you can pass either the object directly or the SV
2705contained within the RV.
2706
2707 SV* vnumify(SV *vs)
2708
2709=for hackers
2710Found in file util.c
2711
2712=item vstringify
d8c40edc 2713X<vstringify>
f333445c 2714
b9381830
JP
2715In order to maintain maximum compatibility with earlier versions
2716of Perl, this function will return either the floating point
2717notation or the multiple dotted notation, depending on whether
2718the original version contained 1 or more dots, respectively
f333445c
JP
2719
2720 SV* vstringify(SV *vs)
2721
2722=for hackers
2723Found in file util.c
2724
e0218a61 2725=item vverify
d8c40edc 2726X<vverify>
e0218a61
JP
2727
2728Validates that the SV contains a valid version object.
2729
2730 bool vverify(SV *vobj);
2731
2732Note that it only confirms the bare minimum structure (so as not to get
2733confused by derived classes which may contain additional hash entries):
2734
2735 bool vverify(SV *vs)
2736
2737=for hackers
2738Found in file util.c
2739
f4758303 2740
94bdecf9 2741=back
7207e29d 2742
cd299c6e
RGS
2743=head1 Multicall Functions
2744
2745=over 8
2746
2747=item dMULTICALL
2748X<dMULTICALL>
2749
2750Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2751
2752 dMULTICALL;
2753
2754=for hackers
2755Found in file cop.h
2756
2757=item MULTICALL
2758X<MULTICALL>
2759
2760Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2761
2762 MULTICALL;
2763
2764=for hackers
2765Found in file cop.h
2766
2767=item POP_MULTICALL
2768X<POP_MULTICALL>
2769
2770Closing bracket for a lightweight callback.
2771See L<perlcall/Lightweight Callbacks>.
2772
2773 POP_MULTICALL;
2774
2775=for hackers
2776Found in file cop.h
2777
2778=item PUSH_MULTICALL
2779X<PUSH_MULTICALL>
2780
2781Opening bracket for a lightweight callback.
2782See L<perlcall/Lightweight Callbacks>.
2783
2784 PUSH_MULTICALL;
2785
2786=for hackers
2787Found in file cop.h
2788
2789
2790=back
2791
94bdecf9 2792=head1 Numeric functions
7207e29d 2793
94bdecf9 2794=over 8
f4758303 2795
94bdecf9 2796=item grok_bin
d8c40edc 2797X<grok_bin>
f4758303 2798
94bdecf9
JH
2799converts a string representing a binary number to numeric form.
2800
2801On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2802conversion flags, and I<result> should be NULL or a pointer to an NV.
2803The scan stops at the end of the string, or the first invalid character.
7b667b5f
MHM
2804Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2805invalid character will also trigger a warning.
2806On return I<*len> is set to the length of the scanned string,
2807and I<*flags> gives output flags.
94bdecf9 2808
7fc63493 2809If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
94bdecf9
JH
2810and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2811returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2812and writes the value to I<*result> (or the value is discarded if I<result>
2813is NULL).
2814
7b667b5f 2815The binary number may optionally be prefixed with "0b" or "b" unless
94bdecf9
JH
2816C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2817C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2818number may use '_' characters to separate digits.
2819
a3b680e6 2820 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
f4758303
JP
2821
2822=for hackers
94bdecf9 2823Found in file numeric.c
f4758303 2824
94bdecf9 2825=item grok_hex
d8c40edc 2826X<grok_hex>
954c1994 2827
94bdecf9
JH
2828converts a string representing a hex number to numeric form.
2829
2830On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2831conversion flags, and I<result> should be NULL or a pointer to an NV.
7b667b5f
MHM
2832The scan stops at the end of the string, or the first invalid character.
2833Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2834invalid character will also trigger a warning.
2835On return I<*len> is set to the length of the scanned string,
2836and I<*flags> gives output flags.
94bdecf9
JH
2837
2838If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2839and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2840returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2841and writes the value to I<*result> (or the value is discarded if I<result>
2842is NULL).
2843
2844The hex number may optionally be prefixed with "0x" or "x" unless
2845C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2846C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2847number may use '_' characters to separate digits.
2848
a3b680e6 2849 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2850
497711e7 2851=for hackers
94bdecf9 2852Found in file numeric.c
497711e7 2853
94bdecf9 2854=item grok_number
d8c40edc 2855X<grok_number>
954c1994 2856
94bdecf9
JH
2857Recognise (or not) a number. The type of the number is returned
2858(0 if unrecognised), otherwise it is a bit-ORed combination of
2859IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2860IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2861
2862If the value of the number can fit an in UV, it is returned in the *valuep
2863IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2864will never be set unless *valuep is valid, but *valuep may have been assigned
2865to during processing even though IS_NUMBER_IN_UV is not set on return.
2866If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2867valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2868
2869IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2870seen (in which case *valuep gives the true value truncated to an integer), and
2871IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2872absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
2873number is larger than a UV.
2874
2875 int grok_number(const char *pv, STRLEN len, UV *valuep)
954c1994 2876
497711e7 2877=for hackers
94bdecf9 2878Found in file numeric.c
497711e7 2879
94bdecf9 2880=item grok_numeric_radix
d8c40edc 2881X<grok_numeric_radix>
954c1994 2882
94bdecf9
JH
2883Scan and skip for a numeric decimal separator (radix).
2884
2885 bool grok_numeric_radix(const char **sp, const char *send)
954c1994 2886
497711e7 2887=for hackers
94bdecf9 2888Found in file numeric.c
497711e7 2889
94bdecf9 2890=item grok_oct
d8c40edc 2891X<grok_oct>
954c1994 2892
7b667b5f
MHM
2893converts a string representing an octal number to numeric form.
2894
2895On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2896conversion flags, and I<result> should be NULL or a pointer to an NV.
2897The scan stops at the end of the string, or the first invalid character.
2898Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2899invalid character will also trigger a warning.
2900On return I<*len> is set to the length of the scanned string,
2901and I<*flags> gives output flags.
2902
2903If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2904and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2905returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2906and writes the value to I<*result> (or the value is discarded if I<result>
2907is NULL).
2908
2909If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2910number may use '_' characters to separate digits.
94bdecf9 2911
a3b680e6 2912 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2913
497711e7 2914=for hackers
94bdecf9 2915Found in file numeric.c
497711e7 2916
ed140128
AD
2917=item Perl_signbit
2918X<Perl_signbit>
2919
2920Return a non-zero integer if the sign bit on an NV is set, and 0 if
2921it is not.
2922
2923If Configure detects this system has a signbit() that will work with
2924our NVs, then we just use it via the #define in perl.h. Otherwise,
2925fall back on this implementation. As a first pass, this gets everything
2926right except -0.0. Alas, catching -0.0 is the main use for this function,
2927so this is not too helpful yet. Still, at least we have the scaffolding
2928in place to support other systems, should that prove useful.
2929
2930
2931Configure notes: This function is called 'Perl_signbit' instead of a
2932plain 'signbit' because it is easy to imagine a system having a signbit()
2933function or macro that doesn't happen to work with our particular choice
2934of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
2935the standard system headers to be happy. Also, this is a no-context
2936function (no pTHX_) because Perl_signbit() is usually re-#defined in
2937perl.h as a simple macro call to the system's signbit().
2938Users should just always call Perl_signbit().
2939
2940NOTE: this function is experimental and may change or be
2941removed without notice.
2942
2943 int Perl_signbit(NV f)
2944
2945=for hackers
2946Found in file numeric.c
2947
94bdecf9 2948=item scan_bin
d8c40edc 2949X<scan_bin>
954c1994 2950
94bdecf9
JH
2951For backwards compatibility. Use C<grok_bin> instead.
2952
73d840c0 2953 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2954
497711e7 2955=for hackers
94bdecf9 2956Found in file numeric.c
497711e7 2957
94bdecf9 2958=item scan_hex
d8c40edc 2959X<scan_hex>
954c1994 2960
94bdecf9
JH
2961For backwards compatibility. Use C<grok_hex> instead.
2962
73d840c0 2963 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2964
497711e7 2965=for hackers
94bdecf9 2966Found in file numeric.c
497711e7 2967
94bdecf9 2968=item scan_oct
d8c40edc 2969X<scan_oct>
954c1994 2970
94bdecf9 2971For backwards compatibility. Use C<grok_oct> instead.
954c1994 2972
73d840c0 2973 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2974
497711e7 2975=for hackers
94bdecf9 2976Found in file numeric.c
497711e7 2977
645c22ef 2978
94bdecf9 2979=back
645c22ef 2980
94bdecf9
JH
2981=head1 Optree Manipulation Functions
2982
2983=over 8
2984
2985=item cv_const_sv
d8c40edc 2986X<cv_const_sv>
94bdecf9
JH
2987
2988If C<cv> is a constant sub eligible for inlining. returns the constant
2989value returned by the sub. Otherwise, returns NULL.
2990
2991Constant subs can be created with C<newCONSTSUB> or as described in
2992L<perlsub/"Constant Functions">.
2993
2994 SV* cv_const_sv(CV* cv)
645c22ef
DM
2995
2996=for hackers
94bdecf9 2997Found in file op.c
645c22ef 2998
94bdecf9 2999=item newCONSTSUB
d8c40edc 3000X<newCONSTSUB>
954c1994 3001
94bdecf9
JH
3002Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
3003eligible for inlining at compile-time.
954c1994 3004
e1ec3a88 3005 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
954c1994 3006
497711e7 3007=for hackers
94bdecf9 3008Found in file op.c
497711e7 3009
94bdecf9 3010=item newXS
d8c40edc 3011X<newXS>
954c1994 3012
77004dee
NC
3013Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
3014static storage, as it is used directly as CvFILE(), without a copy being made.
954c1994 3015
94bdecf9
JH
3016=for hackers
3017Found in file op.c
3018
3019
3020=back
3021
dd2155a4
DM
3022=head1 Pad Data Structures
3023
3024=over 8
3025
3026=item pad_sv
d8c40edc 3027X<pad_sv>
dd2155a4
DM
3028
3029Get the value at offset po in the current pad.
3030Use macro PAD_SV instead of calling this function directly.
3031
3032 SV* pad_sv(PADOFFSET po)
3033
3034=for hackers
3035Found in file pad.c
3036
3037
3038=back
3039
59887a99
MHM
3040=head1 Simple Exception Handling Macros
3041
3042=over 8
3043
3044=item dXCPT
d8c40edc 3045X<dXCPT>
59887a99 3046
2dfe1b17 3047Set up necessary local variables for exception handling.
59887a99
MHM
3048See L<perlguts/"Exception Handling">.
3049
3050 dXCPT;
3051
3052=for hackers
3053Found in file XSUB.h
3054
3055=item XCPT_CATCH
d8c40edc 3056X<XCPT_CATCH>
59887a99
MHM
3057
3058Introduces a catch block. See L<perlguts/"Exception Handling">.
3059
3060=for hackers
3061Found in file XSUB.h
3062
3063=item XCPT_RETHROW
d8c40edc 3064X<XCPT_RETHROW>
59887a99
MHM
3065
3066Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
3067
3068 XCPT_RETHROW;
3069
3070=for hackers
3071Found in file XSUB.h
3072
3073=item XCPT_TRY_END
d8c40edc 3074X<XCPT_TRY_END>
59887a99
MHM
3075
3076Ends a try block. See L<perlguts/"Exception Handling">.
3077
3078=for hackers
3079Found in file XSUB.h
3080
3081=item XCPT_TRY_START
d8c40edc 3082X<XCPT_TRY_START>
59887a99
MHM
3083
3084Starts a try block. See L<perlguts/"Exception Handling">.
3085
3086=for hackers
3087Found in file XSUB.h
3088
3089
3090=back
3091
94bdecf9
JH
3092=head1 Stack Manipulation Macros
3093
3094=over 8
3095
3096=item dMARK
d8c40edc 3097X<dMARK>
954c1994 3098
94bdecf9
JH
3099Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
3100C<dORIGMARK>.
954c1994 3101
94bdecf9 3102 dMARK;
954c1994 3103
497711e7 3104=for hackers
94bdecf9 3105Found in file pp.h
497711e7 3106
94bdecf9 3107=item dORIGMARK
d8c40edc 3108X<dORIGMARK>
954c1994 3109
94bdecf9 3110Saves the original stack mark for the XSUB. See C<ORIGMARK>.
954c1994 3111
94bdecf9 3112 dORIGMARK;
954c1994 3113
497711e7 3114=for hackers
94bdecf9 3115Found in file pp.h
497711e7 3116
94bdecf9 3117=item dSP
d8c40edc 3118X<dSP>
954c1994 3119
94bdecf9
JH
3120Declares a local copy of perl's stack pointer for the XSUB, available via
3121the C<SP> macro. See C<SP>.
954c1994 3122
94bdecf9 3123 dSP;
954c1994 3124
497711e7 3125=for hackers
94bdecf9 3126Found in file pp.h
497711e7 3127
94bdecf9 3128=item EXTEND
d8c40edc 3129X<EXTEND>
954c1994 3130
94bdecf9
JH
3131Used to extend the argument stack for an XSUB's return values. Once
3132used, guarantees that there is room for at least C<nitems> to be pushed
3133onto the stack.
954c1994 3134
94bdecf9 3135 void EXTEND(SP, int nitems)
954c1994 3136
497711e7 3137=for hackers
94bdecf9 3138Found in file pp.h
954c1994 3139
94bdecf9 3140=item MARK
d8c40edc 3141X<MARK>
954c1994 3142
94bdecf9 3143Stack marker variable for the XSUB. See C<dMARK>.
954c1994 3144
497711e7 3145=for hackers
94bdecf9 3146Found in file pp.h
954c1994 3147
d82b684c 3148=item mPUSHi
d8c40edc 3149X<mPUSHi>
d82b684c
SH
3150
3151Push an integer onto the stack. The stack must have room for this element.
de4f2208
RGS
3152Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
3153and C<XPUSHi>.
d82b684c
SH
3154
3155 void mPUSHi(IV iv)
3156
3157=for hackers
3158Found in file pp.h
3159
3160=item mPUSHn
d8c40edc 3161X<mPUSHn>
d82b684c
SH
3162
3163Push a double onto the stack. The stack must have room for this element.
de4f2208
RGS
3164Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
3165and C<XPUSHn>.
d82b684c
SH
3166
3167 void mPUSHn(NV nv)
3168
3169=for hackers
3170Found in file pp.h
3171
3172=item mPUSHp
d8c40edc 3173X<mPUSHp>
d82b684c
SH
3174
3175Push a string onto the stack. The stack must have room for this element.
de4f2208
RGS
3176The C<len> indicates the length of the string. Handles 'set' magic. Does
3177not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
d82b684c
SH
3178
3179 void mPUSHp(char* str, STRLEN len)
3180
3181=for hackers
3182Found in file pp.h
3183
3184=item mPUSHu
d8c40edc 3185X<mPUSHu>
d82b684c
SH
3186
3187Push an unsigned integer onto the stack. The stack must have room for this
de4f2208
RGS
3188element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
3189C<mXPUSHu> and C<XPUSHu>.
d82b684c
SH
3190
3191 void mPUSHu(UV uv)
3192
3193=for hackers
3194Found in file pp.h
3195
3196=item mXPUSHi
d8c40edc 3197X<mXPUSHi>
d82b684c 3198
de4f2208
RGS
3199Push an integer onto the stack, extending the stack if necessary. Handles
3200'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
3201C<PUSHi>.
d82b684c
SH
3202
3203 void mXPUSHi(IV iv)
3204
3205=for hackers
3206Found in file pp.h
3207
3208=item mXPUSHn
d8c40edc 3209X<mXPUSHn>
d82b684c 3210
de4f2208
RGS
3211Push a double onto the stack, extending the stack if necessary. Handles
3212'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
3213C<PUSHn>.
d82b684c
SH
3214
3215 void mXPUSHn(NV nv)
3216
3217=for hackers
3218Found in file pp.h
3219
3220=item mXPUSHp
d8c40edc 3221X<mXPUSHp>
d82b684c
SH
3222
3223Push a string onto the stack, extending the stack if necessary. The C<len>
de4f2208
RGS
3224indicates the length of the string. Handles 'set' magic. Does not use
3225C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
d82b684c
SH
3226
3227 void mXPUSHp(char* str, STRLEN len)
3228
3229=for hackers
3230Found in file pp.h
3231
3232=item mXPUSHu
d8c40edc 3233X<mXPUSHu>
d82b684c
SH
3234
3235Push an unsigned integer onto the stack, extending the stack if necessary.
de4f2208
RGS
3236Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
3237and C<PUSHu>.
d82b684c
SH
3238
3239 void mXPUSHu(UV uv)
3240
3241=for hackers
3242Found in file pp.h
3243
94bdecf9 3244=item ORIGMARK
d8c40edc 3245X<ORIGMARK>
954c1994 3246
94bdecf9 3247The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 3248
497711e7 3249=for hackers
94bdecf9 3250Found in file pp.h
497711e7 3251
954c1994 3252=item POPi
d8c40edc 3253X<POPi>
954c1994
GS
3254
3255Pops an integer off the stack.
3256
3257 IV POPi
3258
497711e7
GS
3259=for hackers
3260Found in file pp.h
3261
954c1994 3262=item POPl
d8c40edc 3263X<POPl>
954c1994
GS
3264
3265Pops a long off the stack.
3266
3267 long POPl
3268
497711e7
GS
3269=for hackers
3270Found in file pp.h
3271
954c1994 3272=item POPn
d8c40edc 3273X<POPn>
954c1994
GS
3274
3275Pops a double off the stack.
3276
3277 NV POPn
3278
497711e7
GS
3279=for hackers
3280Found in file pp.h
3281
954c1994 3282=item POPp
d8c40edc 3283X<POPp>
954c1994 3284
184499a4 3285Pops a string off the stack. Deprecated. New code should use POPpx.
954c1994
GS
3286
3287 char* POPp
3288
497711e7
GS
3289=for hackers
3290Found in file pp.h
3291
fa519979 3292=item POPpbytex
d8c40edc 3293X<POPpbytex>
fa519979
JH
3294
3295Pops a string off the stack which must consist of bytes i.e. characters < 256.
fa519979
JH
3296
3297 char* POPpbytex
3298
3299=for hackers
3300Found in file pp.h
3301
3302=item POPpx
d8c40edc 3303X<POPpx>
fa519979
JH
3304
3305Pops a string off the stack.
fa519979
JH
3306
3307 char* POPpx
3308
3309=for hackers
3310Found in file pp.h
3311
954c1994 3312=item POPs
d8c40edc 3313X<POPs>
954c1994
GS
3314
3315Pops an SV off the stack.
3316
3317 SV* POPs
3318
497711e7
GS
3319=for hackers
3320Found in file pp.h
3321
954c1994 3322=item PUSHi
d8c40edc 3323X<PUSHi>
954c1994
GS
3324
3325Push an integer onto the stack. The stack must have room for this element.
d82b684c
SH
3326Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3327called to declare it. Do not call multiple C<TARG>-oriented macros to
3328return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
3329C<mXPUSHi>.
954c1994
GS
3330
3331 void PUSHi(IV iv)
3332
497711e7
GS
3333=for hackers
3334Found in file pp.h
3335
954c1994 3336=item PUSHMARK
d8c40edc 3337X<PUSHMARK>
954c1994
GS
3338
3339Opening bracket for arguments on a callback. See C<PUTBACK> and
3340L<perlcall>.
3341
c578083c 3342 void PUSHMARK(SP)
954c1994 3343
497711e7
GS
3344=for hackers
3345Found in file pp.h
3346
d82b684c 3347=item PUSHmortal
d8c40edc 3348X<PUSHmortal>
d82b684c
SH
3349
3350Push a new mortal SV onto the stack. The stack must have room for this
3351element. Does not handle 'set' magic. Does not use C<TARG>. See also
3352C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3353
3354 void PUSHmortal()
3355
3356=for hackers
3357Found in file pp.h
3358
954c1994 3359=item PUSHn
d8c40edc 3360X<PUSHn>
954c1994
GS
3361
3362Push a double onto the stack. The stack must have room for this element.
d82b684c
SH
3363Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3364called to declare it. Do not call multiple C<TARG>-oriented macros to
3365return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
3366C<mXPUSHn>.
954c1994
GS
3367
3368 void PUSHn(NV nv)
3369
497711e7
GS
3370=for hackers
3371Found in file pp.h
3372
954c1994 3373=item PUSHp
d8c40edc 3374X<PUSHp>
954c1994
GS
3375
3376Push a string onto the stack. The stack must have room for this element.
d82b684c
SH
3377The C<len> indicates the length of the string. Handles 'set' magic. Uses
3378C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
3379call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3380C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
954c1994
GS
3381
3382 void PUSHp(char* str, STRLEN len)
3383
497711e7
GS
3384=for hackers
3385Found in file pp.h
3386
954c1994 3387=item PUSHs
d8c40edc 3388X<PUSHs>
954c1994 3389
1c846c1f 3390Push an SV onto the stack. The stack must have room for this element.
d82b684c
SH
3391Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
3392C<XPUSHs> and C<XPUSHmortal>.
954c1994
GS
3393
3394 void PUSHs(SV* sv)
3395
497711e7
GS
3396=for hackers
3397Found in file pp.h
3398
954c1994 3399=item PUSHu
d8c40edc 3400X<PUSHu>
954c1994
GS
3401
3402Push an unsigned integer onto the stack. The stack must have room for this
d82b684c
SH
3403element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3404should be called to declare it. Do not call multiple C<TARG>-oriented
3405macros to return lists from XSUB's - see C<mPUSHu> instead. See also
3406C<XPUSHu> and C<mXPUSHu>.
954c1994
GS
3407
3408 void PUSHu(UV uv)
3409
497711e7
GS
3410=for hackers
3411Found in file pp.h
3412
954c1994 3413=item PUTBACK
d8c40edc 3414X<PUTBACK>
954c1994
GS
3415
3416Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
3417See C<PUSHMARK> and L<perlcall> for other uses.
3418
3419 PUTBACK;
3420
497711e7
GS
3421=for hackers
3422Found in file pp.h
3423
94bdecf9 3424=item SP
d8c40edc 3425X<SP>
d2cc3551 3426
94bdecf9
JH
3427Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
3428C<SPAGAIN>.
d2cc3551 3429
94bdecf9
JH
3430=for hackers
3431Found in file pp.h
3432
3433=item SPAGAIN
d8c40edc 3434X<SPAGAIN>
94bdecf9
JH
3435
3436Refetch the stack pointer. Used after a callback. See L<perlcall>.
3437
3438 SPAGAIN;
d2cc3551
JH
3439
3440=for hackers
94bdecf9 3441Found in file pp.h
d2cc3551 3442
94bdecf9 3443=item XPUSHi
d8c40edc 3444X<XPUSHi>
954c1994 3445
94bdecf9 3446Push an integer onto the stack, extending the stack if necessary. Handles
d82b684c
SH
3447'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3448declare it. Do not call multiple C<TARG>-oriented macros to return lists
3449from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
954c1994 3450
94bdecf9 3451 void XPUSHi(IV iv)
954c1994 3452
497711e7 3453=for hackers
94bdecf9