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