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