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