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