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