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