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