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