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