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