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