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