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