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