This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[doc-patch] clarify -Accflags in INSTALL
[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
JH
2024
2025Fill up memory with a pattern (byte 0xAB over and over again) that
2026hopefully catches attempts to access uninitialized memory.
2027
2028 void Poison(void* dest, int nitems, type)
2029
2030=for hackers
2031Found in file handy.h
2032
94bdecf9 2033=item Renew
d8c40edc 2034X<Renew>
954c1994 2035
94bdecf9 2036The XSUB-writer's interface to the C C<realloc> function.
954c1994 2037
94bdecf9 2038 void Renew(void* ptr, int nitems, type)
954c1994 2039
497711e7
GS
2040=for hackers
2041Found in file handy.h
2042
94bdecf9 2043=item Renewc
d8c40edc 2044X<Renewc>
954c1994 2045
94bdecf9
JH
2046The XSUB-writer's interface to the C C<realloc> function, with
2047cast.
954c1994 2048
94bdecf9 2049 void Renewc(void* ptr, int nitems, type, cast)
954c1994 2050
497711e7 2051=for hackers
94bdecf9 2052Found in file handy.h
497711e7 2053
94bdecf9 2054=item Safefree
d8c40edc 2055X<Safefree>
954c1994 2056
94bdecf9 2057The XSUB-writer's interface to the C C<free> function.
954c1994 2058
94bdecf9 2059 void Safefree(void* ptr)
954c1994 2060
497711e7
GS
2061=for hackers
2062Found in file handy.h
2063
94bdecf9 2064=item savepv
d8c40edc 2065X<savepv>
954c1994 2066
641d4181
JH
2067Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2068string which is a duplicate of C<pv>. The size of the string is
2069determined by C<strlen()>. The memory allocated for the new string can
2070be freed with the C<Safefree()> function.
954c1994 2071
641d4181 2072 char* savepv(const char* pv)
954c1994 2073
497711e7 2074=for hackers
94bdecf9 2075Found in file util.c
497711e7 2076
94bdecf9 2077=item savepvn
d8c40edc 2078X<savepvn>
954c1994 2079
641d4181
JH
2080Perl's version of what C<strndup()> would be if it existed. Returns a
2081pointer to a newly allocated string which is a duplicate of the first
2082C<len> bytes from C<pv>. The memory allocated for the new string can be
2083freed with the C<Safefree()> function.
954c1994 2084
641d4181 2085 char* savepvn(const char* pv, I32 len)
954c1994 2086
497711e7 2087=for hackers
94bdecf9 2088Found in file util.c
497711e7 2089
a4f1a029 2090=item savesharedpv
d8c40edc 2091X<savesharedpv>
a4f1a029 2092
641d4181
JH
2093A version of C<savepv()> which allocates the duplicate string in memory
2094which is shared between threads.
a4f1a029 2095
641d4181 2096 char* savesharedpv(const char* pv)
a4f1a029
NIS
2097
2098=for hackers
2099Found in file util.c
2100
766f8916 2101=item savesvpv
d8c40edc 2102X<savesvpv>
766f8916 2103
9c2fe30c 2104A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
766f8916
MHM
2105the passed in SV using C<SvPV()>
2106
2107 char* savesvpv(SV* sv)
2108
2109=for hackers
2110Found in file util.c
2111
94bdecf9 2112=item StructCopy
d8c40edc 2113X<StructCopy>
954c1994 2114
94bdecf9 2115This is an architecture-independent macro to copy one structure to another.
954c1994 2116
94bdecf9 2117 void StructCopy(type src, type dest, type)
954c1994 2118
497711e7 2119=for hackers
94bdecf9 2120Found in file handy.h
497711e7 2121
94bdecf9 2122=item Zero
d8c40edc 2123X<Zero>
954c1994 2124
94bdecf9
JH
2125The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
2126destination, C<nitems> is the number of items, and C<type> is the type.
954c1994 2127
94bdecf9 2128 void Zero(void* dest, int nitems, type)
954c1994 2129
497711e7 2130=for hackers
94bdecf9 2131Found in file handy.h
497711e7 2132
e90e2364 2133=item ZeroD
d8c40edc 2134X<ZeroD>
e90e2364
NC
2135
2136Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2137optimise.
2138
2139 void * ZeroD(void* dest, int nitems, type)
2140
2141=for hackers
2142Found in file handy.h
2143
954c1994 2144
94bdecf9 2145=back
954c1994 2146
94bdecf9 2147=head1 Miscellaneous Functions
954c1994 2148
94bdecf9 2149=over 8
497711e7 2150
94bdecf9 2151=item fbm_compile
d8c40edc 2152X<fbm_compile>
8b4ac5a4 2153
94bdecf9
JH
2154Analyses the string in order to make fast searches on it using fbm_instr()
2155-- the Boyer-Moore algorithm.
8b4ac5a4 2156
94bdecf9 2157 void fbm_compile(SV* sv, U32 flags)
8b4ac5a4
JH
2158
2159=for hackers
94bdecf9 2160Found in file util.c
8b4ac5a4 2161
94bdecf9 2162=item fbm_instr
d8c40edc 2163X<fbm_instr>
954c1994 2164
94bdecf9 2165Returns the location of the SV in the string delimited by C<str> and
bd61b366 2166C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
94bdecf9
JH
2167does not have to be fbm_compiled, but the search will not be as fast
2168then.
954c1994 2169
94bdecf9 2170 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
954c1994 2171
497711e7 2172=for hackers
94bdecf9 2173Found in file util.c
497711e7 2174
94bdecf9 2175=item form
d8c40edc 2176X<form>
954c1994 2177
94bdecf9
JH
2178Takes a sprintf-style format pattern and conventional
2179(non-SV) arguments and returns the formatted string.
954c1994 2180
94bdecf9 2181 (char *) Perl_form(pTHX_ const char* pat, ...)
954c1994 2182
94bdecf9 2183can be used any place a string (char *) is required:
497711e7 2184
94bdecf9 2185 char * s = Perl_form("%d.%d",major,minor);
954c1994 2186
94bdecf9
JH
2187Uses a single private buffer so if you want to format several strings you
2188must explicitly copy the earlier strings away (and free the copies when you
2189are done).
954c1994 2190
94bdecf9 2191 char* form(const char* pat, ...)
954c1994 2192
497711e7 2193=for hackers
94bdecf9 2194Found in file util.c
497711e7 2195
94bdecf9 2196=item getcwd_sv
d8c40edc 2197X<getcwd_sv>
954c1994 2198
94bdecf9 2199Fill the sv with current working directory
954c1994 2200
94bdecf9 2201 int getcwd_sv(SV* sv)
954c1994 2202
497711e7 2203=for hackers
94bdecf9 2204Found in file util.c
497711e7 2205
9244d4ad
RGS
2206=item my_sprintf
2207X<my_sprintf>
2208
2209The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2210the length of the string written to the buffer. Only rare pre-ANSI systems
2211need the wrapper function - usually this is a direct call to C<sprintf>.
2212
2213 int my_sprintf(char *buffer, const char *pat, ...)
2214
2215=for hackers
2216Found in file util.c
2217
f333445c 2218=item new_version
d8c40edc 2219X<new_version>
f333445c
JP
2220
2221Returns a new version object based on the passed in SV:
2222
2223 SV *sv = new_version(SV *ver);
2224
2225Does not alter the passed in ver SV. See "upg_version" if you
2226want to upgrade the SV.
2227
2228 SV* new_version(SV *ver)
2229
2230=for hackers
2231Found in file util.c
2232
2233=item scan_version
d8c40edc 2234X<scan_version>
f333445c
JP
2235
2236Returns a pointer to the next character after the parsed
2237version string, as well as upgrading the passed in SV to
2238an RV.
2239
2240Function must be called with an already existing SV like
2241
137d6fc0
JP
2242 sv = newSV(0);
2243 s = scan_version(s,SV *sv, bool qv);
f333445c
JP
2244
2245Performs some preprocessing to the string to ensure that
2246it has the correct characteristics of a version. Flags the
2247object if it contains an underscore (which denotes this
137d6fc0
JP
2248is a alpha version). The boolean qv denotes that the version
2249should be interpreted as if it had multiple decimals, even if
2250it doesn't.
f333445c 2251
9137345a 2252 const char* scan_version(const char *vstr, SV *sv, bool qv)
f333445c
JP
2253
2254=for hackers
2255Found in file util.c
2256
94bdecf9 2257=item strEQ
d8c40edc 2258X<strEQ>
954c1994 2259
94bdecf9 2260Test two strings to see if they are equal. Returns true or false.
954c1994 2261
94bdecf9 2262 bool strEQ(char* s1, char* s2)
954c1994 2263
497711e7 2264=for hackers
94bdecf9 2265Found in file handy.h
497711e7 2266
94bdecf9 2267=item strGE
d8c40edc 2268X<strGE>
1c846c1f 2269
94bdecf9
JH
2270Test two strings to see if the first, C<s1>, is greater than or equal to
2271the second, C<s2>. Returns true or false.
1c846c1f 2272
94bdecf9 2273 bool strGE(char* s1, char* s2)
1c846c1f
NIS
2274
2275=for hackers
94bdecf9 2276Found in file handy.h
1c846c1f 2277
94bdecf9 2278=item strGT
d8c40edc 2279X<strGT>
954c1994 2280
94bdecf9
JH
2281Test two strings to see if the first, C<s1>, is greater than the second,
2282C<s2>. Returns true or false.
954c1994 2283
94bdecf9 2284 bool strGT(char* s1, char* s2)
954c1994 2285
497711e7 2286=for hackers
94bdecf9 2287Found in file handy.h
497711e7 2288
94bdecf9 2289=item strLE
d8c40edc 2290X<strLE>
954c1994 2291
94bdecf9
JH
2292Test two strings to see if the first, C<s1>, is less than or equal to the
2293second, C<s2>. Returns true or false.
954c1994 2294
94bdecf9 2295 bool strLE(char* s1, char* s2)
954c1994 2296
497711e7 2297=for hackers
94bdecf9 2298Found in file handy.h
497711e7 2299
94bdecf9 2300=item strLT
d8c40edc 2301X<strLT>
1a3327fb 2302
94bdecf9
JH
2303Test two strings to see if the first, C<s1>, is less than the second,
2304C<s2>. Returns true or false.
1a3327fb 2305
94bdecf9 2306 bool strLT(char* s1, char* s2)
1a3327fb 2307
497711e7 2308=for hackers
94bdecf9 2309Found in file handy.h
497711e7 2310
94bdecf9 2311=item strNE
d8c40edc 2312X<strNE>
954c1994 2313
94bdecf9
JH
2314Test two strings to see if they are different. Returns true or
2315false.
2316
2317 bool strNE(char* s1, char* s2)
954c1994 2318
497711e7 2319=for hackers
94bdecf9 2320Found in file handy.h
497711e7 2321
94bdecf9 2322=item strnEQ
d8c40edc 2323X<strnEQ>
954c1994 2324
94bdecf9
JH
2325Test two strings to see if they are equal. The C<len> parameter indicates
2326the number of bytes to compare. Returns true or false. (A wrapper for
2327C<strncmp>).
2328
2329 bool strnEQ(char* s1, char* s2, STRLEN len)
954c1994 2330
497711e7 2331=for hackers
94bdecf9 2332Found in file handy.h
497711e7 2333
94bdecf9 2334=item strnNE
d8c40edc 2335X<strnNE>
954c1994 2336
94bdecf9
JH
2337Test two strings to see if they are different. The C<len> parameter
2338indicates the number of bytes to compare. Returns true or false. (A
2339wrapper for C<strncmp>).
954c1994 2340
94bdecf9 2341 bool strnNE(char* s1, char* s2, STRLEN len)
954c1994 2342
497711e7
GS
2343=for hackers
2344Found in file handy.h
2345
f333445c 2346=item sv_nosharing
d8c40edc 2347X<sv_nosharing>
f333445c
JP
2348
2349Dummy routine which "shares" an SV when there is no sharing module present.
9244d4ad
RGS
2350Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2351Exists to avoid test for a NULL function pointer and because it could
2352potentially warn under some level of strict-ness.
f333445c 2353
c48640ec 2354 void sv_nosharing(SV *sv)
f333445c
JP
2355
2356=for hackers
2357Found in file util.c
2358
f333445c 2359=item upg_version
d8c40edc 2360X<upg_version>
f333445c
JP
2361
2362In-place upgrade of the supplied SV to a version object.
2363
2364 SV *sv = upg_version(SV *sv);
2365
2366Returns a pointer to the upgraded SV.
2367
2368 SV* upg_version(SV *ver)
2369
2370=for hackers
2371Found in file util.c
2372
2373=item vcmp
d8c40edc 2374X<vcmp>
f333445c
JP
2375
2376Version object aware cmp. Both operands must already have been
2377converted into version objects.
2378
2379 int vcmp(SV *lvs, SV *rvs)
2380
2381=for hackers
2382Found in file util.c
2383
b9381830 2384=item vnormal
d8c40edc 2385X<vnormal>
b9381830
JP
2386
2387Accepts a version object and returns the normalized string
2388representation. Call like:
2389
2390 sv = vnormal(rv);
2391
2392NOTE: you can pass either the object directly or the SV
2393contained within the RV.
2394
2395 SV* vnormal(SV *vs)
2396
2397=for hackers
2398Found in file util.c
2399
f333445c 2400=item vnumify
d8c40edc 2401X<vnumify>
f333445c
JP
2402
2403Accepts a version object and returns the normalized floating
2404point representation. Call like:
2405
2406 sv = vnumify(rv);
2407
2408NOTE: you can pass either the object directly or the SV
2409contained within the RV.
2410
2411 SV* vnumify(SV *vs)
2412
2413=for hackers
2414Found in file util.c
2415
2416=item vstringify
d8c40edc 2417X<vstringify>
f333445c 2418
b9381830
JP
2419In order to maintain maximum compatibility with earlier versions
2420of Perl, this function will return either the floating point
2421notation or the multiple dotted notation, depending on whether
2422the original version contained 1 or more dots, respectively
f333445c
JP
2423
2424 SV* vstringify(SV *vs)
2425
2426=for hackers
2427Found in file util.c
2428
e0218a61 2429=item vverify
d8c40edc 2430X<vverify>
e0218a61
JP
2431
2432Validates that the SV contains a valid version object.
2433
2434 bool vverify(SV *vobj);
2435
2436Note that it only confirms the bare minimum structure (so as not to get
2437confused by derived classes which may contain additional hash entries):
2438
2439 bool vverify(SV *vs)
2440
2441=for hackers
2442Found in file util.c
2443
f4758303 2444
94bdecf9 2445=back
7207e29d 2446
cd299c6e
RGS
2447=head1 Multicall Functions
2448
2449=over 8
2450
2451=item dMULTICALL
2452X<dMULTICALL>
2453
2454Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2455
2456 dMULTICALL;
2457
2458=for hackers
2459Found in file cop.h
2460
2461=item MULTICALL
2462X<MULTICALL>
2463
2464Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2465
2466 MULTICALL;
2467
2468=for hackers
2469Found in file cop.h
2470
2471=item POP_MULTICALL
2472X<POP_MULTICALL>
2473
2474Closing bracket for a lightweight callback.
2475See L<perlcall/Lightweight Callbacks>.
2476
2477 POP_MULTICALL;
2478
2479=for hackers
2480Found in file cop.h
2481
2482=item PUSH_MULTICALL
2483X<PUSH_MULTICALL>
2484
2485Opening bracket for a lightweight callback.
2486See L<perlcall/Lightweight Callbacks>.
2487
2488 PUSH_MULTICALL;
2489
2490=for hackers
2491Found in file cop.h
2492
2493
2494=back
2495
94bdecf9 2496=head1 Numeric functions
7207e29d 2497
94bdecf9 2498=over 8
f4758303 2499
94bdecf9 2500=item grok_bin
d8c40edc 2501X<grok_bin>
f4758303 2502
94bdecf9
JH
2503converts a string representing a binary number to numeric form.
2504
2505On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2506conversion flags, and I<result> should be NULL or a pointer to an NV.
2507The scan stops at the end of the string, or the first invalid character.
7b667b5f
MHM
2508Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2509invalid character will also trigger a warning.
2510On return I<*len> is set to the length of the scanned string,
2511and I<*flags> gives output flags.
94bdecf9 2512
7fc63493 2513If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
94bdecf9
JH
2514and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2515returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2516and writes the value to I<*result> (or the value is discarded if I<result>
2517is NULL).
2518
7b667b5f 2519The binary number may optionally be prefixed with "0b" or "b" unless
94bdecf9
JH
2520C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2521C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2522number may use '_' characters to separate digits.
2523
a3b680e6 2524 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
f4758303
JP
2525
2526=for hackers
94bdecf9 2527Found in file numeric.c
f4758303 2528
94bdecf9 2529=item grok_hex
d8c40edc 2530X<grok_hex>
954c1994 2531
94bdecf9
JH
2532converts a string representing a hex number to numeric form.
2533
2534On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2535conversion flags, and I<result> should be NULL or a pointer to an NV.
7b667b5f
MHM
2536The scan stops at the end of the string, or the first invalid character.
2537Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2538invalid character will also trigger a warning.
2539On return I<*len> is set to the length of the scanned string,
2540and I<*flags> gives output flags.
94bdecf9
JH
2541
2542If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2543and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2544returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2545and writes the value to I<*result> (or the value is discarded if I<result>
2546is NULL).
2547
2548The hex number may optionally be prefixed with "0x" or "x" unless
2549C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2550C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2551number may use '_' characters to separate digits.
2552
a3b680e6 2553 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2554
497711e7 2555=for hackers
94bdecf9 2556Found in file numeric.c
497711e7 2557
94bdecf9 2558=item grok_number
d8c40edc 2559X<grok_number>
954c1994 2560
94bdecf9
JH
2561Recognise (or not) a number. The type of the number is returned
2562(0 if unrecognised), otherwise it is a bit-ORed combination of
2563IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2564IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2565
2566If the value of the number can fit an in UV, it is returned in the *valuep
2567IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2568will never be set unless *valuep is valid, but *valuep may have been assigned
2569to during processing even though IS_NUMBER_IN_UV is not set on return.
2570If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2571valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2572
2573IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2574seen (in which case *valuep gives the true value truncated to an integer), and
2575IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2576absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
2577number is larger than a UV.
2578
2579 int grok_number(const char *pv, STRLEN len, UV *valuep)
954c1994 2580
497711e7 2581=for hackers
94bdecf9 2582Found in file numeric.c
497711e7 2583
94bdecf9 2584=item grok_numeric_radix
d8c40edc 2585X<grok_numeric_radix>
954c1994 2586
94bdecf9
JH
2587Scan and skip for a numeric decimal separator (radix).
2588
2589 bool grok_numeric_radix(const char **sp, const char *send)
954c1994 2590
497711e7 2591=for hackers
94bdecf9 2592Found in file numeric.c
497711e7 2593
94bdecf9 2594=item grok_oct
d8c40edc 2595X<grok_oct>
954c1994 2596
7b667b5f
MHM
2597converts a string representing an octal number to numeric form.
2598
2599On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2600conversion flags, and I<result> should be NULL or a pointer to an NV.
2601The scan stops at the end of the string, or the first invalid character.
2602Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2603invalid character will also trigger a warning.
2604On return I<*len> is set to the length of the scanned string,
2605and I<*flags> gives output flags.
2606
2607If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2608and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2609returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2610and writes the value to I<*result> (or the value is discarded if I<result>
2611is NULL).
2612
2613If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2614number may use '_' characters to separate digits.
94bdecf9 2615
a3b680e6 2616 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
954c1994 2617
497711e7 2618=for hackers
94bdecf9 2619Found in file numeric.c
497711e7 2620
94bdecf9 2621=item scan_bin
d8c40edc 2622X<scan_bin>
954c1994 2623
94bdecf9
JH
2624For backwards compatibility. Use C<grok_bin> instead.
2625
73d840c0 2626 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2627
497711e7 2628=for hackers
94bdecf9 2629Found in file numeric.c
497711e7 2630
94bdecf9 2631=item scan_hex
d8c40edc 2632X<scan_hex>
954c1994 2633
94bdecf9
JH
2634For backwards compatibility. Use C<grok_hex> instead.
2635
73d840c0 2636 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2637
497711e7 2638=for hackers
94bdecf9 2639Found in file numeric.c
497711e7 2640
94bdecf9 2641=item scan_oct
d8c40edc 2642X<scan_oct>
954c1994 2643
94bdecf9 2644For backwards compatibility. Use C<grok_oct> instead.
954c1994 2645
73d840c0 2646 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
954c1994 2647
497711e7 2648=for hackers
94bdecf9 2649Found in file numeric.c
497711e7 2650
645c22ef 2651
94bdecf9 2652=back
645c22ef 2653
94bdecf9
JH
2654=head1 Optree Manipulation Functions
2655
2656=over 8
2657
2658=item cv_const_sv
d8c40edc 2659X<cv_const_sv>
94bdecf9
JH
2660
2661If C<cv> is a constant sub eligible for inlining. returns the constant
2662value returned by the sub. Otherwise, returns NULL.
2663
2664Constant subs can be created with C<newCONSTSUB> or as described in
2665L<perlsub/"Constant Functions">.
2666
2667 SV* cv_const_sv(CV* cv)
645c22ef
DM
2668
2669=for hackers
94bdecf9 2670Found in file op.c
645c22ef 2671
94bdecf9 2672=item newCONSTSUB
d8c40edc 2673X<newCONSTSUB>
954c1994 2674
94bdecf9
JH
2675Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
2676eligible for inlining at compile-time.
954c1994 2677
e1ec3a88 2678 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
954c1994 2679
497711e7 2680=for hackers
94bdecf9 2681Found in file op.c
497711e7 2682
94bdecf9 2683=item newXS
d8c40edc 2684X<newXS>
954c1994 2685
94bdecf9 2686Used by C<xsubpp> to hook up XSUBs as Perl subs.
954c1994 2687
94bdecf9
JH
2688=for hackers
2689Found in file op.c
2690
2691
2692=back
2693
dd2155a4
DM
2694=head1 Pad Data Structures
2695
2696=over 8
2697
2698=item pad_sv
d8c40edc 2699X<pad_sv>
dd2155a4
DM
2700
2701Get the value at offset po in the current pad.
2702Use macro PAD_SV instead of calling this function directly.
2703
2704 SV* pad_sv(PADOFFSET po)
2705
2706=for hackers
2707Found in file pad.c
2708
2709
2710=back
2711
59887a99
MHM
2712=head1 Simple Exception Handling Macros
2713
2714=over 8
2715
2716=item dXCPT
d8c40edc 2717X<dXCPT>
59887a99 2718
2dfe1b17 2719Set up necessary local variables for exception handling.
59887a99
MHM
2720See L<perlguts/"Exception Handling">.
2721
2722 dXCPT;
2723
2724=for hackers
2725Found in file XSUB.h
2726
2727=item XCPT_CATCH
d8c40edc 2728X<XCPT_CATCH>
59887a99
MHM
2729
2730Introduces a catch block. See L<perlguts/"Exception Handling">.
2731
2732=for hackers
2733Found in file XSUB.h
2734
2735=item XCPT_RETHROW
d8c40edc 2736X<XCPT_RETHROW>
59887a99
MHM
2737
2738Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
2739
2740 XCPT_RETHROW;
2741
2742=for hackers
2743Found in file XSUB.h
2744
2745=item XCPT_TRY_END
d8c40edc 2746X<XCPT_TRY_END>
59887a99
MHM
2747
2748Ends a try block. See L<perlguts/"Exception Handling">.
2749
2750=for hackers
2751Found in file XSUB.h
2752
2753=item XCPT_TRY_START
d8c40edc 2754X<XCPT_TRY_START>
59887a99
MHM
2755
2756Starts a try block. See L<perlguts/"Exception Handling">.
2757
2758=for hackers
2759Found in file XSUB.h
2760
2761
2762=back
2763
94bdecf9
JH
2764=head1 Stack Manipulation Macros
2765
2766=over 8
2767
2768=item dMARK
d8c40edc 2769X<dMARK>
954c1994 2770
94bdecf9
JH
2771Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
2772C<dORIGMARK>.
954c1994 2773
94bdecf9 2774 dMARK;
954c1994 2775
497711e7 2776=for hackers
94bdecf9 2777Found in file pp.h
497711e7 2778
94bdecf9 2779=item dORIGMARK
d8c40edc 2780X<dORIGMARK>
954c1994 2781
94bdecf9 2782Saves the original stack mark for the XSUB. See C<ORIGMARK>.
954c1994 2783
94bdecf9 2784 dORIGMARK;
954c1994 2785
497711e7 2786=for hackers
94bdecf9 2787Found in file pp.h
497711e7 2788
94bdecf9 2789=item dSP
d8c40edc 2790X<dSP>
954c1994 2791
94bdecf9
JH
2792Declares a local copy of perl's stack pointer for the XSUB, available via
2793the C<SP> macro. See C<SP>.
954c1994 2794
94bdecf9 2795 dSP;
954c1994 2796
497711e7 2797=for hackers
94bdecf9 2798Found in file pp.h
497711e7 2799
94bdecf9 2800=item EXTEND
d8c40edc 2801X<EXTEND>
954c1994 2802
94bdecf9
JH
2803Used to extend the argument stack for an XSUB's return values. Once
2804used, guarantees that there is room for at least C<nitems> to be pushed
2805onto the stack.
954c1994 2806
94bdecf9 2807 void EXTEND(SP, int nitems)
954c1994 2808
497711e7 2809=for hackers
94bdecf9 2810Found in file pp.h
954c1994 2811
94bdecf9 2812=item MARK
d8c40edc 2813X<MARK>
954c1994 2814
94bdecf9 2815Stack marker variable for the XSUB. See C<dMARK>.
954c1994 2816
497711e7 2817=for hackers
94bdecf9 2818Found in file pp.h
954c1994 2819
d82b684c 2820=item mPUSHi
d8c40edc 2821X<mPUSHi>
d82b684c
SH
2822
2823Push an integer onto the stack. The stack must have room for this element.
de4f2208
RGS
2824Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
2825and C<XPUSHi>.
d82b684c
SH
2826
2827 void mPUSHi(IV iv)
2828
2829=for hackers
2830Found in file pp.h
2831
2832=item mPUSHn
d8c40edc 2833X<mPUSHn>
d82b684c
SH
2834
2835Push a double onto the stack. The stack must have room for this element.
de4f2208
RGS
2836Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
2837and C<XPUSHn>.
d82b684c
SH
2838
2839 void mPUSHn(NV nv)
2840
2841=for hackers
2842Found in file pp.h
2843
2844=item mPUSHp
d8c40edc 2845X<mPUSHp>
d82b684c
SH
2846
2847Push a string onto the stack. The stack must have room for this element.
de4f2208
RGS
2848The C<len> indicates the length of the string. Handles 'set' magic. Does
2849not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
d82b684c
SH
2850
2851 void mPUSHp(char* str, STRLEN len)
2852
2853=for hackers
2854Found in file pp.h
2855
2856=item mPUSHu
d8c40edc 2857X<mPUSHu>
d82b684c
SH
2858
2859Push an unsigned integer onto the stack. The stack must have room for this
de4f2208
RGS
2860element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
2861C<mXPUSHu> and C<XPUSHu>.
d82b684c
SH
2862
2863 void mPUSHu(UV uv)
2864
2865=for hackers
2866Found in file pp.h
2867
2868=item mXPUSHi
d8c40edc 2869X<mXPUSHi>
d82b684c 2870
de4f2208
RGS
2871Push an integer onto the stack, extending the stack if necessary. Handles
2872'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
2873C<PUSHi>.
d82b684c
SH
2874
2875 void mXPUSHi(IV iv)
2876
2877=for hackers
2878Found in file pp.h
2879
2880=item mXPUSHn
d8c40edc 2881X<mXPUSHn>
d82b684c 2882
de4f2208
RGS
2883Push a double onto the stack, extending the stack if necessary. Handles
2884'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
2885C<PUSHn>.
d82b684c
SH
2886
2887 void mXPUSHn(NV nv)
2888
2889=for hackers
2890Found in file pp.h
2891
2892=item mXPUSHp
d8c40edc 2893X<mXPUSHp>
d82b684c
SH
2894
2895Push a string onto the stack, extending the stack if necessary. The C<len>
de4f2208
RGS
2896indicates the length of the string. Handles 'set' magic. Does not use
2897C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
d82b684c
SH
2898
2899 void mXPUSHp(char* str, STRLEN len)
2900
2901=for hackers
2902Found in file pp.h
2903
2904=item mXPUSHu
d8c40edc 2905X<mXPUSHu>
d82b684c
SH
2906
2907Push an unsigned integer onto the stack, extending the stack if necessary.
de4f2208
RGS
2908Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
2909and C<PUSHu>.
d82b684c
SH
2910
2911 void mXPUSHu(UV uv)
2912
2913=for hackers
2914Found in file pp.h
2915
94bdecf9 2916=item ORIGMARK
d8c40edc 2917X<ORIGMARK>
954c1994 2918
94bdecf9 2919The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 2920
497711e7 2921=for hackers
94bdecf9 2922Found in file pp.h
497711e7 2923
954c1994 2924=item POPi
d8c40edc 2925X<POPi>
954c1994
GS
2926
2927Pops an integer off the stack.
2928
2929 IV POPi
2930
497711e7
GS
2931=for hackers
2932Found in file pp.h
2933
954c1994 2934=item POPl
d8c40edc 2935X<POPl>
954c1994
GS
2936
2937Pops a long off the stack.
2938
2939 long POPl
2940
497711e7
GS
2941=for hackers
2942Found in file pp.h
2943
954c1994 2944=item POPn
d8c40edc 2945X<POPn>
954c1994
GS
2946
2947Pops a double off the stack.
2948
2949 NV POPn
2950
497711e7
GS
2951=for hackers
2952Found in file pp.h
2953
954c1994 2954=item POPp
d8c40edc 2955X<POPp>
954c1994 2956
184499a4 2957Pops a string off the stack. Deprecated. New code should use POPpx.
954c1994
GS
2958
2959 char* POPp
2960
497711e7
GS
2961=for hackers
2962Found in file pp.h
2963
fa519979 2964=item POPpbytex
d8c40edc 2965X<POPpbytex>
fa519979
JH
2966
2967Pops a string off the stack which must consist of bytes i.e. characters < 256.
fa519979
JH
2968
2969 char* POPpbytex
2970
2971=for hackers
2972Found in file pp.h
2973
2974=item POPpx
d8c40edc 2975X<POPpx>
fa519979
JH
2976
2977Pops a string off the stack.
fa519979
JH
2978
2979 char* POPpx
2980
2981=for hackers
2982Found in file pp.h
2983
954c1994 2984=item POPs
d8c40edc 2985X<POPs>
954c1994
GS
2986
2987Pops an SV off the stack.
2988
2989 SV* POPs
2990
497711e7
GS
2991=for hackers
2992Found in file pp.h
2993
954c1994 2994=item PUSHi
d8c40edc 2995X<PUSHi>
954c1994
GS
2996
2997Push an integer onto the stack. The stack must have room for this element.
d82b684c
SH
2998Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
2999called to declare it. Do not call multiple C<TARG>-oriented macros to
3000return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
3001C<mXPUSHi>.
954c1994
GS
3002
3003 void PUSHi(IV iv)
3004
497711e7
GS
3005=for hackers
3006Found in file pp.h
3007
954c1994 3008=item PUSHMARK
d8c40edc 3009X<PUSHMARK>
954c1994
GS
3010
3011Opening bracket for arguments on a callback. See C<PUTBACK> and
3012L<perlcall>.
3013
c578083c 3014 void PUSHMARK(SP)
954c1994 3015
497711e7
GS
3016=for hackers
3017Found in file pp.h
3018
d82b684c 3019=item PUSHmortal
d8c40edc 3020X<PUSHmortal>
d82b684c
SH
3021
3022Push a new mortal SV onto the stack. The stack must have room for this
3023element. Does not handle 'set' magic. Does not use C<TARG>. See also
3024C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3025
3026 void PUSHmortal()
3027
3028=for hackers
3029Found in file pp.h
3030
954c1994 3031=item PUSHn
d8c40edc 3032X<PUSHn>
954c1994
GS
3033
3034Push a double onto the stack. The stack must have room for this element.
d82b684c
SH
3035Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3036called to declare it. Do not call multiple C<TARG>-oriented macros to
3037return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
3038C<mXPUSHn>.
954c1994
GS
3039
3040 void PUSHn(NV nv)
3041
497711e7
GS
3042=for hackers
3043Found in file pp.h
3044
954c1994 3045=item PUSHp
d8c40edc 3046X<PUSHp>
954c1994
GS
3047
3048Push a string onto the stack. The stack must have room for this element.
d82b684c
SH
3049The C<len> indicates the length of the string. Handles 'set' magic. Uses
3050C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
3051call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3052C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
954c1994
GS
3053
3054 void PUSHp(char* str, STRLEN len)
3055
497711e7
GS
3056=for hackers
3057Found in file pp.h
3058
954c1994 3059=item PUSHs
d8c40edc 3060X<PUSHs>
954c1994 3061
1c846c1f 3062Push an SV onto the stack. The stack must have room for this element.
d82b684c
SH
3063Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
3064C<XPUSHs> and C<XPUSHmortal>.
954c1994
GS
3065
3066 void PUSHs(SV* sv)
3067
497711e7
GS
3068=for hackers
3069Found in file pp.h
3070
954c1994 3071=item PUSHu
d8c40edc 3072X<PUSHu>
954c1994
GS
3073
3074Push an unsigned integer onto the stack. The stack must have room for this
d82b684c
SH
3075element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3076should be called to declare it. Do not call multiple C<TARG>-oriented
3077macros to return lists from XSUB's - see C<mPUSHu> instead. See also
3078C<XPUSHu> and C<mXPUSHu>.
954c1994
GS
3079
3080 void PUSHu(UV uv)
3081
497711e7
GS
3082=for hackers
3083Found in file pp.h
3084
954c1994 3085=item PUTBACK
d8c40edc 3086X<PUTBACK>
954c1994
GS
3087
3088Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
3089See C<PUSHMARK> and L<perlcall> for other uses.
3090
3091 PUTBACK;
3092
497711e7
GS
3093=for hackers
3094Found in file pp.h
3095
94bdecf9 3096=item SP
d8c40edc 3097X<SP>
d2cc3551 3098
94bdecf9
JH
3099Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
3100C<SPAGAIN>.
d2cc3551 3101
94bdecf9
JH
3102=for hackers
3103Found in file pp.h
3104
3105=item SPAGAIN
d8c40edc 3106X<SPAGAIN>
94bdecf9
JH
3107
3108Refetch the stack pointer. Used after a callback. See L<perlcall>.
3109
3110 SPAGAIN;
d2cc3551
JH
3111
3112=for hackers
94bdecf9 3113Found in file pp.h
d2cc3551 3114
94bdecf9 3115=item XPUSHi
d8c40edc 3116X<XPUSHi>
954c1994 3117
94bdecf9 3118Push an integer onto the stack, extending the stack if necessary. Handles
d82b684c
SH
3119'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3120declare it. Do not call multiple C<TARG>-oriented macros to return lists
3121from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
954c1994 3122
94bdecf9 3123 void XPUSHi(IV iv)
954c1994 3124
497711e7 3125=for hackers
94bdecf9 3126Found in file pp.h
497711e7 3127
d82b684c 3128=item XPUSHmortal
d8c40edc 3129X<XPUSHmortal>
d82b684c
SH
3130
3131Push a new mortal SV onto the stack, extending the stack if necessary. Does
3132not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>,
3133C<PUSHmortal> and C<PUSHs>.
3134
3135 void XPUSHmortal()
3136
3137=for hackers
3138Found in file pp.h
3139
94bdecf9 3140=item XPUSHn
d8c40edc 3141X<XPUSHn>
954c1994 3142
94bdecf9 3143Push a double onto the stack, extending the stack if necessary. Handles
d82b684c
SH
3144'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3145declare it. Do not call multiple C<TARG>-oriented macros to return lists
3146from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
954c1994 3147
94bdecf9 3148 void XPUSHn(NV nv)
954c1994 3149
497711e7 3150=for hackers
94bdecf9 3151Found in file pp.h
497711e7 3152
94bdecf9 3153=item XPUSHp
d8c40edc 3154X<XPUSHp>
954c1994 3155
94bdecf9 3156Push a string onto the stack, extending the stack if necessary. The C<len>
d82b684c
SH
3157indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
3158C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
3159multiple C<TARG>-oriented macros to return lists from XSUB's - see
3160C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
954c1994 3161
94bdecf9 3162 void XPUSHp(char* str, STRLEN len)
954c1994 3163
94bdecf9
JH
3164=for hackers
3165Found in file pp.h
3166
3167=item XPUSHs
d8c40edc 3168X<XPUSHs>
94bdecf9
JH
3169
3170Push an SV onto the stack, extending the stack if necessary. Does not
d82b684c
SH
3171handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
3172C<PUSHs> and C<PUSHmortal>.
94bdecf9
JH
3173
3174 void XPUSHs(SV* sv)
954c1994 3175
497711e7 3176=for hackers
94bdecf9 3177Found in file pp.h
497711e7 3178
94bdecf9 3179=item XPUSHu
d8c40edc 3180X<XPUSHu>
954c1994 3181
94bdecf9 3182Push an unsigned integer onto the stack, extending the stack if necessary.
d82b684c
SH
3183Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3184called to declare it. Do not call multiple C<TARG>-oriented macros to
3185return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
3186C<mPUSHu>.
954c1994 3187
94bdecf9
JH
3188 void XPUSHu(UV uv)
3189
3190=for hackers
3191Found in file pp.h
3192
3193=item XSRETURN
d8c40edc 3194X<XSRETURN>
94bdecf9
JH
3195
3196Return from XSUB, indicating number of items on the stack. This is usually
3197handled by C<xsubpp>.
3198
3199 void XSRETURN(int nitems)
954c1994 3200
497711e7
GS
3201=for hackers
3202Found in file XSUB.h
3203
e509e693 3204=item XSRETURN_EMPTY
d8c40edc 3205X<XSRETURN_EMPTY>
e509e693
SH
3206
3207Return an empty list from an XSUB immediately.
3208
3209 XSRETURN_EMPTY;
3210
3211=for hackers
3212Found in file XSUB.h
3213
94bdecf9 3214=item XSRETURN_IV
d8c40edc 3215X<XSRETURN_IV>
954c1994 3216
94bdecf9 3217Return an integer from an XSUB immediately. Uses C<XST_mIV>.
954c1994 3218
94bdecf9 3219 void XSRETURN_IV(IV iv)
954c1994 3220
497711e7 3221=for hackers
94bdecf9 3222Found in file XSUB.h
497711e7 3223
94bdecf9 3224=item XSRETURN_NO
d8c40edc 3225X<XSRETURN_NO>
954c1994 3226
94bdecf9 3227Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
954c1994 3228
94bdecf9 3229 XSRETURN_NO;
954c1994 3230
497711e7 3231=for hackers
94bdecf9 3232Found in file XSUB.h
497711e7 3233
94bdecf9 3234=item XSRETURN_NV
d8c40edc 3235X<XSRETURN_NV>
954c1994 3236
94bdecf9 3237Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994 3238
94bdecf9 3239 void XSRETURN_NV(NV nv)
954c1994 3240
497711e7 3241=for hackers
94bdecf9
JH
3242Found in file XSUB.h
3243
3244=item XSRETURN_PV
d8c40edc 3245X<XSRETURN_PV>
94bdecf9
JH
3246
3247Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3248
3249 void XSRETURN_PV(char* str)
3250
3251=for hackers
3252Found in file XSUB.h
3253
3254=item XSRETURN_UNDEF
d8c40edc 3255X<XSRETURN_UNDEF>
94bdecf9
JH
3256
3257Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3258
3259 XSRETURN_UNDEF;
3260
3261=for hackers
3262Found in file XSUB.h
3263
0ee80f49 3264=item XSRETURN_UV
d8c40edc 3265X<XSRETURN_UV>
0ee80f49
JH
3266
3267Return an integer from an XSUB immediately. Uses C<XST_mUV>.
3268
3269 void XSRETURN_UV(IV uv)
3270
3271=for hackers
3272Found in file XSUB.h
3273
94bdecf9 3274=item XSRETURN_YES
d8c40edc 3275X<XSRETURN_YES>
94bdecf9
JH
3276
3277Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3278
3279 XSRETURN_YES;
3280
3281=for hackers
3282Found in file XSUB.h
3283
3284=item XST_mIV
d8c40edc 3285X<XST_mIV>
94bdecf9
JH
3286
3287Place an integer into the specified position C<pos> on the stack. The
3288value is stored in a new mortal SV.
3289
3290 void XST_mIV(int pos, IV iv)
3291
3292=for hackers
3293Found in file XSUB.h
3294
3295=item XST_mNO
d8c40edc 3296X<XST_mNO>
94bdecf9
JH
3297
3298Place C<&PL_sv_no> into the specified position C<pos> on the
3299stack.
3300
3301 void XST_mNO(int pos)
3302
3303=for hackers
3304Found in file XSUB.h
3305
3306=item XST_mNV
d8c40edc 3307X<XST_mNV>
94bdecf9
JH
3308
3309Place a double into the specified position C<pos> on the stack. The value
3310is stored in a new mortal SV.
3311
3312 void XST_mNV(int pos, NV nv)
3313
3314=for hackers
3315Found in file XSUB.h
3316
3317=item XST_mPV
d8c40edc 3318X<XST_mPV>
94bdecf9
JH
3319
3320Place a copy of a string into the specified position C<pos> on the stack.
3321The value is stored in a new mortal SV.
3322
3323 void XST_mPV(int pos, char* str)
3324
3325=for hackers
3326Found in file XSUB.h
3327
3328=item XST_mUNDEF
d8c40edc 3329X<XST_mUNDEF>
94bdecf9
JH
3330
3331Place C<&PL_sv_undef> into the specified position C<pos> on the
3332stack.
3333
3334 void XST_mUNDEF(int pos)
3335
3336=for hackers
3337Found in file XSUB.h
3338
3339=item XST_mYES
d8c40edc 3340X<XST_mYES>
94bdecf9
JH
3341
3342Place C<&PL_sv_yes> into the specified position C<pos> on the
3343stack.
3344
3345 void XST_mYES(int pos)
3346
3347=for hackers
3348Found in file XSUB.h
3349
3350
3351=back
3352
3353=head1 SV Flags
497711e7 3354
94bdecf9 3355=over 8
954c1994 3356
94bdecf9 3357=item svtype
d8c40edc 3358X<svtype>
954c1994 3359
94bdecf9
JH
3360An enum of flags for Perl types. These are found in the file B<sv.h>
3361in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 3362
497711e7 3363=for hackers
94bdecf9 3364Found in file sv.h
6e9d1081 3365
94bdecf9 3366=item SVt_IV
d8c40edc 3367X<SVt_IV>
6e9d1081 3368
94bdecf9 3369Integer type flag for scalars. See C<svtype>.
6e9d1081
NC
3370
3371=for hackers
94bdecf9 3372Found in file sv.h
6e9d1081 3373
94bdecf9 3374=item SVt_NV
d8c40edc 3375X<SVt_NV>
6e9d1081 3376
94bdecf9 3377Double type flag for scalars. See C<svtype>.
6e9d1081
NC
3378
3379=for hackers
94bdecf9 3380Found in file sv.h
6e9d1081 3381
94bdecf9 3382=item SVt_PV
d8c40edc 3383X<SVt_PV>
6e9d1081 3384
94bdecf9 3385Pointer type flag for scalars. See C<svtype>.
6e9d1081
NC
3386
3387=for hackers
94bdecf9 3388Found in file sv.h
cd1ee231 3389
94bdecf9 3390=item SVt_PVAV
d8c40edc 3391X<SVt_PVAV>
cd1ee231 3392
94bdecf9 3393Type flag for arrays. See C<svtype>.
cd1ee231
JH
3394
3395=for hackers
94bdecf9 3396Found in file sv.h
cd1ee231 3397
94bdecf9 3398=item SVt_PVCV
d8c40edc 3399X<SVt_PVCV>
cd1ee231 3400
94bdecf9