This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[patch] typo in perlop
[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
dd2155a4 874=item Nullch
94bdecf9
JH
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
9965345d
JH
1490=item Poison
1491
1492Fill up memory with a pattern (byte 0xAB over and over again) that
1493hopefully catches attempts to access uninitialized memory.
1494
1495 void Poison(void* dest, int nitems, type)
1496
1497=for hackers
1498Found in file handy.h
1499
94bdecf9 1500=item Renew
954c1994 1501
94bdecf9 1502The XSUB-writer's interface to the C C<realloc> function.
954c1994 1503
94bdecf9 1504 void Renew(void* ptr, int nitems, type)
954c1994 1505
497711e7
GS
1506=for hackers
1507Found in file handy.h
1508
94bdecf9 1509=item Renewc
954c1994 1510
94bdecf9
JH
1511The XSUB-writer's interface to the C C<realloc> function, with
1512cast.
954c1994 1513
94bdecf9 1514 void Renewc(void* ptr, int nitems, type, cast)
954c1994 1515
497711e7 1516=for hackers
94bdecf9 1517Found in file handy.h
497711e7 1518
94bdecf9 1519=item Safefree
954c1994 1520
94bdecf9 1521The XSUB-writer's interface to the C C<free> function.
954c1994 1522
94bdecf9 1523 void Safefree(void* ptr)
954c1994 1524
497711e7
GS
1525=for hackers
1526Found in file handy.h
1527
94bdecf9 1528=item savepv
954c1994 1529
641d4181
JH
1530Perl's version of C<strdup()>. Returns a pointer to a newly allocated
1531string which is a duplicate of C<pv>. The size of the string is
1532determined by C<strlen()>. The memory allocated for the new string can
1533be freed with the C<Safefree()> function.
954c1994 1534
641d4181 1535 char* savepv(const char* pv)
954c1994 1536
497711e7 1537=for hackers
94bdecf9 1538Found in file util.c
497711e7 1539
94bdecf9 1540=item savepvn
954c1994 1541
641d4181
JH
1542Perl's version of what C<strndup()> would be if it existed. Returns a
1543pointer to a newly allocated string which is a duplicate of the first
1544C<len> bytes from C<pv>. The memory allocated for the new string can be
1545freed with the C<Safefree()> function.
954c1994 1546
641d4181 1547 char* savepvn(const char* pv, I32 len)
954c1994 1548
497711e7 1549=for hackers
94bdecf9 1550Found in file util.c
497711e7 1551
a4f1a029
NIS
1552=item savesharedpv
1553
641d4181
JH
1554A version of C<savepv()> which allocates the duplicate string in memory
1555which is shared between threads.
a4f1a029 1556
641d4181 1557 char* savesharedpv(const char* pv)
a4f1a029
NIS
1558
1559=for hackers
1560Found in file util.c
1561
94bdecf9 1562=item StructCopy
954c1994 1563
94bdecf9 1564This is an architecture-independent macro to copy one structure to another.
954c1994 1565
94bdecf9 1566 void StructCopy(type src, type dest, type)
954c1994 1567
497711e7 1568=for hackers
94bdecf9 1569Found in file handy.h
497711e7 1570
94bdecf9 1571=item Zero
954c1994 1572
94bdecf9
JH
1573The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
1574destination, C<nitems> is the number of items, and C<type> is the type.
954c1994 1575
94bdecf9 1576 void Zero(void* dest, int nitems, type)
954c1994 1577
497711e7 1578=for hackers
94bdecf9 1579Found in file handy.h
497711e7 1580
954c1994 1581
94bdecf9 1582=back
954c1994 1583
94bdecf9 1584=head1 Miscellaneous Functions
954c1994 1585
94bdecf9 1586=over 8
497711e7 1587
94bdecf9 1588=item fbm_compile
8b4ac5a4 1589
94bdecf9
JH
1590Analyses the string in order to make fast searches on it using fbm_instr()
1591-- the Boyer-Moore algorithm.
8b4ac5a4 1592
94bdecf9 1593 void fbm_compile(SV* sv, U32 flags)
8b4ac5a4
JH
1594
1595=for hackers
94bdecf9 1596Found in file util.c
8b4ac5a4 1597
94bdecf9 1598=item fbm_instr
954c1994 1599
94bdecf9
JH
1600Returns the location of the SV in the string delimited by C<str> and
1601C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
1602does not have to be fbm_compiled, but the search will not be as fast
1603then.
954c1994 1604
94bdecf9 1605 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
954c1994 1606
497711e7 1607=for hackers
94bdecf9 1608Found in file util.c
497711e7 1609
94bdecf9 1610=item form
954c1994 1611
94bdecf9
JH
1612Takes a sprintf-style format pattern and conventional
1613(non-SV) arguments and returns the formatted string.
954c1994 1614
94bdecf9 1615 (char *) Perl_form(pTHX_ const char* pat, ...)
954c1994 1616
94bdecf9 1617can be used any place a string (char *) is required:
497711e7 1618
94bdecf9 1619 char * s = Perl_form("%d.%d",major,minor);
954c1994 1620
94bdecf9
JH
1621Uses a single private buffer so if you want to format several strings you
1622must explicitly copy the earlier strings away (and free the copies when you
1623are done).
954c1994 1624
94bdecf9 1625 char* form(const char* pat, ...)
954c1994 1626
497711e7 1627=for hackers
94bdecf9 1628Found in file util.c
497711e7 1629
94bdecf9 1630=item getcwd_sv
954c1994 1631
94bdecf9 1632Fill the sv with current working directory
954c1994 1633
94bdecf9 1634 int getcwd_sv(SV* sv)
954c1994 1635
497711e7 1636=for hackers
94bdecf9 1637Found in file util.c
497711e7 1638
94bdecf9 1639=item strEQ
954c1994 1640
94bdecf9 1641Test two strings to see if they are equal. Returns true or false.
954c1994 1642
94bdecf9 1643 bool strEQ(char* s1, char* s2)
954c1994 1644
497711e7 1645=for hackers
94bdecf9 1646Found in file handy.h
497711e7 1647
94bdecf9 1648=item strGE
1c846c1f 1649
94bdecf9
JH
1650Test two strings to see if the first, C<s1>, is greater than or equal to
1651the second, C<s2>. Returns true or false.
1c846c1f 1652
94bdecf9 1653 bool strGE(char* s1, char* s2)
1c846c1f
NIS
1654
1655=for hackers
94bdecf9 1656Found in file handy.h
1c846c1f 1657
94bdecf9 1658=item strGT
954c1994 1659
94bdecf9
JH
1660Test two strings to see if the first, C<s1>, is greater than the second,
1661C<s2>. Returns true or false.
954c1994 1662
94bdecf9 1663 bool strGT(char* s1, char* s2)
954c1994 1664
497711e7 1665=for hackers
94bdecf9 1666Found in file handy.h
497711e7 1667
94bdecf9 1668=item strLE
954c1994 1669
94bdecf9
JH
1670Test two strings to see if the first, C<s1>, is less than or equal to the
1671second, C<s2>. Returns true or false.
954c1994 1672
94bdecf9 1673 bool strLE(char* s1, char* s2)
954c1994 1674
497711e7 1675=for hackers
94bdecf9 1676Found in file handy.h
497711e7 1677
94bdecf9 1678=item strLT
1a3327fb 1679
94bdecf9
JH
1680Test two strings to see if the first, C<s1>, is less than the second,
1681C<s2>. Returns true or false.
1a3327fb 1682
94bdecf9 1683 bool strLT(char* s1, char* s2)
1a3327fb 1684
497711e7 1685=for hackers
94bdecf9 1686Found in file handy.h
497711e7 1687
94bdecf9 1688=item strNE
954c1994 1689
94bdecf9
JH
1690Test two strings to see if they are different. Returns true or
1691false.
1692
1693 bool strNE(char* s1, char* s2)
954c1994 1694
497711e7 1695=for hackers
94bdecf9 1696Found in file handy.h
497711e7 1697
94bdecf9 1698=item strnEQ
954c1994 1699
94bdecf9
JH
1700Test two strings to see if they are equal. The C<len> parameter indicates
1701the number of bytes to compare. Returns true or false. (A wrapper for
1702C<strncmp>).
1703
1704 bool strnEQ(char* s1, char* s2, STRLEN len)
954c1994 1705
497711e7 1706=for hackers
94bdecf9 1707Found in file handy.h
497711e7 1708
94bdecf9 1709=item strnNE
954c1994 1710
94bdecf9
JH
1711Test two strings to see if they are different. The C<len> parameter
1712indicates the number of bytes to compare. Returns true or false. (A
1713wrapper for C<strncmp>).
954c1994 1714
94bdecf9 1715 bool strnNE(char* s1, char* s2, STRLEN len)
954c1994 1716
497711e7
GS
1717=for hackers
1718Found in file handy.h
1719
f4758303 1720
94bdecf9 1721=back
7207e29d 1722
94bdecf9 1723=head1 Numeric functions
7207e29d 1724
94bdecf9 1725=over 8
f4758303 1726
94bdecf9 1727=item grok_bin
f4758303 1728
94bdecf9
JH
1729converts a string representing a binary number to numeric form.
1730
1731On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1732conversion flags, and I<result> should be NULL or a pointer to an NV.
1733The scan stops at the end of the string, or the first invalid character.
1734On return I<*len> is set to the length scanned string, and I<*flags> gives
1735output flags.
1736
1737If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1738and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
1739returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1740and writes the value to I<*result> (or the value is discarded if I<result>
1741is NULL).
1742
1743The hex number may optionally be prefixed with "0b" or "b" unless
1744C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1745C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
1746number may use '_' characters to separate digits.
1747
1748 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
f4758303
JP
1749
1750=for hackers
94bdecf9 1751Found in file numeric.c
f4758303 1752
94bdecf9 1753=item grok_hex
954c1994 1754
94bdecf9
JH
1755converts a string representing a hex number to numeric form.
1756
1757On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1758conversion flags, and I<result> should be NULL or a pointer to an NV.
1759The scan stops at the end of the string, or the first non-hex-digit character.
1760On return I<*len> is set to the length scanned string, and I<*flags> gives
1761output flags.
1762
1763If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1764and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
1765returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1766and writes the value to I<*result> (or the value is discarded if I<result>
1767is NULL).
1768
1769The hex number may optionally be prefixed with "0x" or "x" unless
1770C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1771C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
1772number may use '_' characters to separate digits.
1773
1774 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
954c1994 1775
497711e7 1776=for hackers
94bdecf9 1777Found in file numeric.c
497711e7 1778
94bdecf9 1779=item grok_number
954c1994 1780
94bdecf9
JH
1781Recognise (or not) a number. The type of the number is returned
1782(0 if unrecognised), otherwise it is a bit-ORed combination of
1783IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
1784IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
1785
1786If the value of the number can fit an in UV, it is returned in the *valuep
1787IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
1788will never be set unless *valuep is valid, but *valuep may have been assigned
1789to during processing even though IS_NUMBER_IN_UV is not set on return.
1790If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
1791valuep is non-NULL, but no actual assignment (or SEGV) will occur.
1792
1793IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
1794seen (in which case *valuep gives the true value truncated to an integer), and
1795IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
1796absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
1797number is larger than a UV.
1798
1799 int grok_number(const char *pv, STRLEN len, UV *valuep)
954c1994 1800
497711e7 1801=for hackers
94bdecf9 1802Found in file numeric.c
497711e7 1803
94bdecf9 1804=item grok_numeric_radix
954c1994 1805
94bdecf9
JH
1806Scan and skip for a numeric decimal separator (radix).
1807
1808 bool grok_numeric_radix(const char **sp, const char *send)
954c1994 1809
497711e7 1810=for hackers
94bdecf9 1811Found in file numeric.c
497711e7 1812
94bdecf9 1813=item grok_oct
954c1994 1814
94bdecf9
JH
1815
1816 UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
954c1994 1817
497711e7 1818=for hackers
94bdecf9 1819Found in file numeric.c
497711e7 1820
94bdecf9 1821=item scan_bin
954c1994 1822
94bdecf9
JH
1823For backwards compatibility. Use C<grok_bin> instead.
1824
1825 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
954c1994 1826
497711e7 1827=for hackers
94bdecf9 1828Found in file numeric.c
497711e7 1829
94bdecf9 1830=item scan_hex
954c1994 1831
94bdecf9
JH
1832For backwards compatibility. Use C<grok_hex> instead.
1833
1834 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
954c1994 1835
497711e7 1836=for hackers
94bdecf9 1837Found in file numeric.c
497711e7 1838
94bdecf9 1839=item scan_oct
954c1994 1840
94bdecf9 1841For backwards compatibility. Use C<grok_oct> instead.
954c1994 1842
94bdecf9 1843 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
954c1994 1844
497711e7 1845=for hackers
94bdecf9 1846Found in file numeric.c
497711e7 1847
645c22ef 1848
94bdecf9 1849=back
645c22ef 1850
94bdecf9
JH
1851=head1 Optree Manipulation Functions
1852
1853=over 8
1854
1855=item cv_const_sv
1856
1857If C<cv> is a constant sub eligible for inlining. returns the constant
1858value returned by the sub. Otherwise, returns NULL.
1859
1860Constant subs can be created with C<newCONSTSUB> or as described in
1861L<perlsub/"Constant Functions">.
1862
1863 SV* cv_const_sv(CV* cv)
645c22ef
DM
1864
1865=for hackers
94bdecf9 1866Found in file op.c
645c22ef 1867
94bdecf9 1868=item newCONSTSUB
954c1994 1869
94bdecf9
JH
1870Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1871eligible for inlining at compile-time.
954c1994 1872
94bdecf9 1873 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
954c1994 1874
497711e7 1875=for hackers
94bdecf9 1876Found in file op.c
497711e7 1877
94bdecf9 1878=item newXS
954c1994 1879
94bdecf9 1880Used by C<xsubpp> to hook up XSUBs as Perl subs.
954c1994 1881
94bdecf9
JH
1882=for hackers
1883Found in file op.c
1884
1885
1886=back
1887
dd2155a4
DM
1888=head1 Pad Data Structures
1889
1890=over 8
1891
1892=item pad_sv
1893
1894Get the value at offset po in the current pad.
1895Use macro PAD_SV instead of calling this function directly.
1896
1897 SV* pad_sv(PADOFFSET po)
1898
1899=for hackers
1900Found in file pad.c
1901
1902
1903=back
1904
94bdecf9
JH
1905=head1 Stack Manipulation Macros
1906
1907=over 8
1908
1909=item dMARK
954c1994 1910
94bdecf9
JH
1911Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1912C<dORIGMARK>.
954c1994 1913
94bdecf9 1914 dMARK;
954c1994 1915
497711e7 1916=for hackers
94bdecf9 1917Found in file pp.h
497711e7 1918
94bdecf9 1919=item dORIGMARK
954c1994 1920
94bdecf9 1921Saves the original stack mark for the XSUB. See C<ORIGMARK>.
954c1994 1922
94bdecf9 1923 dORIGMARK;
954c1994 1924
497711e7 1925=for hackers
94bdecf9 1926Found in file pp.h
497711e7 1927
94bdecf9 1928=item dSP
954c1994 1929
94bdecf9
JH
1930Declares a local copy of perl's stack pointer for the XSUB, available via
1931the C<SP> macro. See C<SP>.
954c1994 1932
94bdecf9 1933 dSP;
954c1994 1934
497711e7 1935=for hackers
94bdecf9 1936Found in file pp.h
497711e7 1937
94bdecf9 1938=item EXTEND
954c1994 1939
94bdecf9
JH
1940Used to extend the argument stack for an XSUB's return values. Once
1941used, guarantees that there is room for at least C<nitems> to be pushed
1942onto the stack.
954c1994 1943
94bdecf9 1944 void EXTEND(SP, int nitems)
954c1994 1945
497711e7 1946=for hackers
94bdecf9 1947Found in file pp.h
954c1994 1948
94bdecf9 1949=item MARK
954c1994 1950
94bdecf9 1951Stack marker variable for the XSUB. See C<dMARK>.
954c1994 1952
497711e7 1953=for hackers
94bdecf9 1954Found in file pp.h
954c1994 1955
94bdecf9 1956=item ORIGMARK
954c1994 1957
94bdecf9 1958The original stack mark for the XSUB. See C<dORIGMARK>.
954c1994 1959
497711e7 1960=for hackers
94bdecf9 1961Found in file pp.h
497711e7 1962
954c1994
GS
1963=item POPi
1964
1965Pops an integer off the stack.
1966
1967 IV POPi
1968
497711e7
GS
1969=for hackers
1970Found in file pp.h
1971
954c1994
GS
1972=item POPl
1973
1974Pops a long off the stack.
1975
1976 long POPl
1977
497711e7
GS
1978=for hackers
1979Found in file pp.h
1980
954c1994
GS
1981=item POPn
1982
1983Pops a double off the stack.
1984
1985 NV POPn
1986
497711e7
GS
1987=for hackers
1988Found in file pp.h
1989
954c1994
GS
1990=item POPp
1991
fa519979
JH
1992Pops a string off the stack. Deprecated. New code should provide
1993a STRLEN n_a and use POPpx.
954c1994
GS
1994
1995 char* POPp
1996
497711e7
GS
1997=for hackers
1998Found in file pp.h
1999
fa519979
JH
2000=item POPpbytex
2001
2002Pops a string off the stack which must consist of bytes i.e. characters < 256.
2003Requires a variable STRLEN n_a in scope.
2004
2005 char* POPpbytex
2006
2007=for hackers
2008Found in file pp.h
2009
2010=item POPpx
2011
2012Pops a string off the stack.
2013Requires a variable STRLEN n_a in scope.
2014
2015 char* POPpx
2016
2017=for hackers
2018Found in file pp.h
2019
954c1994
GS
2020=item POPs
2021
2022Pops an SV off the stack.
2023
2024 SV* POPs
2025
497711e7
GS
2026=for hackers
2027Found in file pp.h
2028
954c1994
GS
2029=item PUSHi
2030
2031Push an integer onto the stack. The stack must have room for this element.
2032Handles 'set' magic. See C<XPUSHi>.
2033
2034 void PUSHi(IV iv)
2035
497711e7
GS
2036=for hackers
2037Found in file pp.h
2038
954c1994
GS
2039=item PUSHMARK
2040
2041Opening bracket for arguments on a callback. See C<PUTBACK> and
2042L<perlcall>.
2043
2044 PUSHMARK;
2045
497711e7
GS
2046=for hackers
2047Found in file pp.h
2048
954c1994
GS
2049=item PUSHn
2050
2051Push a double onto the stack. The stack must have room for this element.
2052Handles 'set' magic. See C<XPUSHn>.
2053
2054 void PUSHn(NV nv)
2055
497711e7
GS
2056=for hackers
2057Found in file pp.h
2058
954c1994
GS
2059=item PUSHp
2060
2061Push a string onto the stack. The stack must have room for this element.
2062The C<len> indicates the length of the string. Handles 'set' magic. See
2063C<XPUSHp>.
2064
2065 void PUSHp(char* str, STRLEN len)
2066
497711e7
GS
2067=for hackers
2068Found in file pp.h
2069
954c1994
GS
2070=item PUSHs
2071
1c846c1f 2072Push an SV onto the stack. The stack must have room for this element.
954c1994
GS
2073Does not handle 'set' magic. See C<XPUSHs>.
2074
2075 void PUSHs(SV* sv)
2076
497711e7
GS
2077=for hackers
2078Found in file pp.h
2079
954c1994
GS
2080=item PUSHu
2081
2082Push an unsigned integer onto the stack. The stack must have room for this
2083element. See C<XPUSHu>.
2084
2085 void PUSHu(UV uv)
2086
497711e7
GS
2087=for hackers
2088Found in file pp.h
2089
954c1994
GS
2090=item PUTBACK
2091
2092Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2093See C<PUSHMARK> and L<perlcall> for other uses.
2094
2095 PUTBACK;
2096
497711e7
GS
2097=for hackers
2098Found in file pp.h
2099
94bdecf9 2100=item SP
d2cc3551 2101
94bdecf9
JH
2102Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2103C<SPAGAIN>.
d2cc3551 2104
94bdecf9
JH
2105=for hackers
2106Found in file pp.h
2107
2108=item SPAGAIN
2109
2110Refetch the stack pointer. Used after a callback. See L<perlcall>.
2111
2112 SPAGAIN;
d2cc3551
JH
2113
2114=for hackers
94bdecf9 2115Found in file pp.h
d2cc3551 2116
94bdecf9 2117=item XPUSHi
954c1994 2118
94bdecf9
JH
2119Push an integer onto the stack, extending the stack if necessary. Handles
2120'set' magic. See C<PUSHi>.
954c1994 2121
94bdecf9 2122 void XPUSHi(IV iv)
954c1994 2123
497711e7 2124=for hackers
94bdecf9 2125Found in file pp.h
497711e7 2126
94bdecf9 2127=item XPUSHn
954c1994 2128
94bdecf9
JH
2129Push a double onto the stack, extending the stack if necessary. Handles
2130'set' magic. See C<PUSHn>.
954c1994 2131
94bdecf9 2132 void XPUSHn(NV nv)
954c1994 2133
497711e7 2134=for hackers
94bdecf9 2135Found in file pp.h
497711e7 2136
94bdecf9 2137=item XPUSHp
954c1994 2138
94bdecf9
JH
2139Push a string onto the stack, extending the stack if necessary. The C<len>
2140indicates the length of the string. Handles 'set' magic. See
2141C<PUSHp>.
954c1994 2142
94bdecf9 2143 void XPUSHp(char* str, STRLEN len)
954c1994 2144
94bdecf9
JH
2145=for hackers
2146Found in file pp.h
2147
2148=item XPUSHs
2149
2150Push an SV onto the stack, extending the stack if necessary. Does not
2151handle 'set' magic. See C<PUSHs>.
2152
2153 void XPUSHs(SV* sv)
954c1994 2154
497711e7 2155=for hackers
94bdecf9 2156Found in file pp.h
497711e7 2157
94bdecf9 2158=item XPUSHu
954c1994 2159
94bdecf9
JH
2160Push an unsigned integer onto the stack, extending the stack if necessary.
2161See C<PUSHu>.
954c1994 2162
94bdecf9
JH
2163 void XPUSHu(UV uv)
2164
2165=for hackers
2166Found in file pp.h
2167
2168=item XSRETURN
2169
2170Return from XSUB, indicating number of items on the stack. This is usually
2171handled by C<xsubpp>.
2172
2173 void XSRETURN(int nitems)
954c1994 2174
497711e7
GS
2175=for hackers
2176Found in file XSUB.h
2177
94bdecf9 2178=item XSRETURN_IV
954c1994 2179
94bdecf9 2180Return an integer from an XSUB immediately. Uses C<XST_mIV>.
954c1994 2181
94bdecf9 2182 void XSRETURN_IV(IV iv)
954c1994 2183
497711e7 2184=for hackers
94bdecf9 2185Found in file XSUB.h
497711e7 2186
94bdecf9 2187=item XSRETURN_NO
954c1994 2188
94bdecf9 2189Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
954c1994 2190
94bdecf9 2191 XSRETURN_NO;
954c1994 2192
497711e7 2193=for hackers
94bdecf9 2194Found in file XSUB.h
497711e7 2195
94bdecf9 2196=item XSRETURN_NV
954c1994 2197
94bdecf9 2198Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994 2199
94bdecf9 2200 void XSRETURN_NV(NV nv)
954c1994 2201
497711e7 2202=for hackers
94bdecf9
JH
2203Found in file XSUB.h
2204
2205=item XSRETURN_PV
2206
2207Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2208
2209 void XSRETURN_PV(char* str)
2210
2211=for hackers
2212Found in file XSUB.h
2213
2214=item XSRETURN_UNDEF
2215
2216Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2217
2218 XSRETURN_UNDEF;
2219
2220=for hackers
2221Found in file XSUB.h
2222
2223=item XSRETURN_YES
2224
2225Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2226
2227 XSRETURN_YES;
2228
2229=for hackers
2230Found in file XSUB.h
2231
2232=item XST_mIV
2233
2234Place an integer into the specified position C<pos> on the stack. The
2235value is stored in a new mortal SV.
2236
2237 void XST_mIV(int pos, IV iv)
2238
2239=for hackers
2240Found in file XSUB.h
2241
2242=item XST_mNO
2243
2244Place C<&PL_sv_no> into the specified position C<pos> on the
2245stack.
2246
2247 void XST_mNO(int pos)
2248
2249=for hackers
2250Found in file XSUB.h
2251
2252=item XST_mNV
2253
2254Place a double into the specified position C<pos> on the stack. The value
2255is stored in a new mortal SV.
2256
2257 void XST_mNV(int pos, NV nv)
2258
2259=for hackers
2260Found in file XSUB.h
2261
2262=item XST_mPV
2263
2264Place a copy of a string into the specified position C<pos> on the stack.
2265The value is stored in a new mortal SV.
2266
2267 void XST_mPV(int pos, char* str)
2268
2269=for hackers
2270Found in file XSUB.h
2271
2272=item XST_mUNDEF
2273
2274Place C<&PL_sv_undef> into the specified position C<pos> on the
2275stack.
2276
2277 void XST_mUNDEF(int pos)
2278
2279=for hackers
2280Found in file XSUB.h
2281
2282=item XST_mYES
2283
2284Place C<&PL_sv_yes> into the specified position C<pos> on the
2285stack.
2286
2287 void XST_mYES(int pos)
2288
2289=for hackers
2290Found in file XSUB.h
2291
2292
2293=back
2294
2295=head1 SV Flags
497711e7 2296
94bdecf9 2297=over 8
954c1994 2298
94bdecf9 2299=item svtype
954c1994 2300
94bdecf9
JH
2301An enum of flags for Perl types. These are found in the file B<sv.h>
2302in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
954c1994 2303
497711e7 2304=for hackers
94bdecf9 2305Found in file sv.h
6e9d1081 2306
94bdecf9 2307=item SVt_IV
6e9d1081 2308
94bdecf9 2309Integer type flag for scalars. See C<svtype>.
6e9d1081
NC
2310
2311=for hackers
94bdecf9 2312Found in file sv.h
6e9d1081 2313
94bdecf9 2314=item SVt_NV
6e9d1081 2315
94bdecf9 2316Double type flag for scalars. See C<svtype>.
6e9d1081
NC
2317
2318=for hackers
94bdecf9 2319Found in file sv.h
6e9d1081 2320
94bdecf9 2321=item SVt_PV
6e9d1081 2322
94bdecf9 2323Pointer type flag for scalars. See C<svtype>.
6e9d1081
NC
2324
2325=for hackers
94bdecf9 2326Found in file sv.h
cd1ee231 2327
94bdecf9 2328=item SVt_PVAV
cd1ee231 2329
94bdecf9 2330Type flag for arrays. See C<svtype>.
cd1ee231
JH
2331
2332=for hackers
94bdecf9 2333Found in file sv.h
cd1ee231 2334
94bdecf9 2335=item SVt_PVCV
cd1ee231 2336
94bdecf9 2337Type flag for code refs. See C<svtype>.
cd1ee231
JH
2338
2339=for hackers
94bdecf9 2340Found in file sv.h
cd1ee231 2341
94bdecf9 2342=item SVt_PVHV
cd1ee231 2343
94bdecf9 2344Type flag for hashes. See C<svtype>.
cd1ee231
JH
2345
2346=for hackers
94bdecf9 2347Found in file sv.h
cd1ee231 2348
94bdecf9 2349=item SVt_PVMG
cd1ee231 2350
94bdecf9 2351Type flag for blessed scalars. See C<svtype>.
cd1ee231
JH
2352
2353=for hackers
94bdecf9 2354Found in file sv.h
cd1ee231 2355
cd1ee231 2356
94bdecf9 2357=back
cd1ee231 2358
94bdecf9 2359=head1 SV Manipulation Functions
cd1ee231 2360
94bdecf9 2361=over 8
cd1ee231 2362
94bdecf9 2363=item get_sv
cd1ee231 2364
94bdecf9
JH
2365Returns the SV of the specified Perl scalar. If C<create> is set and the
2366Perl variable does not exist then it will be created. If C<create> is not
2367set and the variable does not exist then NULL is returned.
2368
2369NOTE: the perl_ form of this function is deprecated.
2370
2371 SV* get_sv(const char* name, I32 create)
cd1ee231
JH
2372
2373=for hackers
94bdecf9 2374Found in file perl.c
cd1ee231 2375
94bdecf9 2376=item looks_like_number
cd1ee231 2377
94bdecf9
JH
2378Test if the content of an SV looks like a number (or is a number).
2379C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2380non-numeric warning), even if your atof() doesn't grok them.
cd1ee231 2381
94bdecf9 2382 I32 looks_like_number(SV* sv)
cd1ee231
JH
2383
2384=for hackers
94bdecf9 2385Found in file sv.c
2a5a0c38 2386
94bdecf9 2387=item newRV_inc
2a5a0c38 2388
94bdecf9
JH
2389Creates an RV wrapper for an SV. The reference count for the original SV is
2390incremented.
2a5a0c38 2391
94bdecf9 2392 SV* newRV_inc(SV* sv)
2a5a0c38
JH
2393
2394=for hackers
94bdecf9 2395Found in file sv.h
2a5a0c38 2396
94bdecf9 2397=item newRV_noinc
954c1994 2398
94bdecf9
JH
2399Creates an RV wrapper for an SV. The reference count for the original
2400SV is B<not> incremented.
2401
2402 SV* newRV_noinc(SV *sv)
954c1994 2403
497711e7 2404=for hackers
94bdecf9 2405Found in file sv.c
497711e7 2406
94bdecf9 2407=item newSV
954c1994 2408
94bdecf9
JH
2409Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2410with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2411macro.
954c1994 2412
94bdecf9 2413 SV* newSV(STRLEN len)
954c1994 2414
497711e7 2415=for hackers
94bdecf9 2416Found in file sv.c
497711e7 2417
94bdecf9 2418=item newSViv
954c1994 2419
94bdecf9
JH
2420Creates a new SV and copies an integer into it. The reference count for the
2421SV is set to 1.
954c1994 2422
94bdecf9 2423 SV* newSViv(IV i)
954c1994 2424
497711e7 2425=for hackers
94bdecf9 2426Found in file sv.c
497711e7 2427
94bdecf9 2428=item newSVnv
954c1994 2429
94bdecf9
JH
2430Creates a new SV and copies a floating point value into it.
2431The reference count for the SV is set to 1.
954c1994 2432
94bdecf9 2433 SV* newSVnv(NV n)
954c1994 2434
497711e7 2435=for hackers
94bdecf9 2436Found in file sv.c
497711e7 2437
94bdecf9 2438=item newSVpv
954c1994 2439
94bdecf9
JH
2440Creates a new SV and copies a string into it. The reference count for the
2441SV is set to 1. If C<len> is zero, Perl will compute the length using
2442strlen(). For efficiency, consider using C<newSVpvn> instead.
954c1994 2443
94bdecf9 2444 SV* newSVpv(const char* s, STRLEN len)
954c1994 2445
497711e7 2446=for hackers
94bdecf9 2447Found in file sv.c
497711e7 2448
94bdecf9 2449=item newSVpvf
954c1994 2450
94bdecf9
JH
2451Creates a new SV and initializes it with the string formatted like
2452C<sprintf>.
954c1994 2453
94bdecf9 2454 SV* newSVpvf(const char* pat, ...)
954c1994 2455
497711e7 2456=for hackers
94bdecf9 2457Found in file sv.c
497711e7 2458
94bdecf9 2459=item newSVpvn
954c1994 2460
94bdecf9
JH
2461Creates a new SV and copies a string into it. The reference count for the
2462SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
2463string. You are responsible for ensuring that the source string is at least
2464C<len> bytes long.
954c1994 2465
94bdecf9 2466 SV* newSVpvn(const char* s, STRLEN len)
954c1994 2467
497711e7 2468=for hackers
94bdecf9 2469Found in file sv.c
497711e7 2470
94bdecf9 2471=item newSVpvn_share
954c1994 2472
94bdecf9
JH
2473Creates a new SV with its SvPVX pointing to a shared string in the string
2474table. If the string does not already exist in the table, it is created
2475first. Turns on READONLY and FAKE. The string's hash is stored in the UV
2476slot of the SV; if the C<hash> parameter is non-zero, that value is used;
2477otherwise the hash is computed. The idea here is that as the string table
2478is used for shared hash keys these strings will have SvPVX == HeKEY and
2479hash lookup will avoid string compare.
954c1994 2480
94bdecf9 2481 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
954c1994 2482
497711e7 2483=for hackers
94bdecf9 2484Found in file sv.c
497711e7 2485
94bdecf9 2486=item newSVrv
954c1994 2487
94bdecf9
JH
2488Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
2489it will be upgraded to one. If C<classname> is non-null then the new SV will
2490be blessed in the specified package. The new SV is returned and its
2491reference count is 1.
954c1994 2492
94bdecf9 2493 SV* newSVrv(SV* rv, const char* classname)
954c1994 2494
497711e7 2495=for hackers
94bdecf9 2496Found in file sv.c
497711e7 2497
94bdecf9 2498=item newSVsv
954c1994 2499
94bdecf9
JH
2500Creates a new SV which is an exact duplicate of the original SV.
2501(Uses C<sv_setsv>).
954c1994 2502
94bdecf9 2503 SV* newSVsv(SV* old)
954c1994 2504
497711e7 2505=for hackers
94bdecf9 2506Found in file sv.c
497711e7 2507
94bdecf9 2508=item newSVuv
954c1994 2509
94bdecf9
JH
2510Creates a new SV and copies an unsigned integer into it.
2511The reference count for the SV is set to 1.
954c1994 2512
94bdecf9 2513 SV* newSVuv(UV u)
954c1994 2514
497711e7 2515=for hackers
94bdecf9 2516Found in file sv.c
497711e7 2517
b0f01acb
JP
2518=item new_version
2519
2520Returns a new version object based on the passed in SV:
2521
2522 SV *sv = new_version(SV *ver);
2523
2524Does not alter the passed in ver SV. See "upg_version" if you
2525want to upgrade the SV.
2526
2527 SV* new_version(SV *ver)
2528
2529=for hackers
2530Found in file util.c
2531
2532=item scan_version
2533
2534Returns a pointer to the next character after the parsed
2535version string, as well as upgrading the passed in SV to
2536an RV.
2537
2538Function must be called with an already existing SV like
2539
2540 sv = NEWSV(92,0);
2541 s = scan_version(s,sv);
2542
2543Performs some preprocessing to the string to ensure that
2544it has the correct characteristics of a version. Flags the
2545object if it contains an underscore (which denotes this
2546is a beta version).
2547
2548 char* scan_version(char *vstr, SV *sv)
2549
2550=for hackers
2551Found in file util.c
2552
2553=item scan_vstring
954c1994 2554
94bdecf9
JH
2555Returns a pointer to the next character after the parsed
2556vstring, as well as updating the passed in sv.
954c1994 2557
94bdecf9
JH
2558Function must be called like
2559
b0f01acb
JP
2560 sv = NEWSV(92,5);
2561 s = scan_vstring(s,sv);
94bdecf9 2562
b0f01acb
JP
2563The sv should already be large enough to store the vstring
2564passed in, for performance reasons.
94bdecf9 2565
b0f01acb 2566 char* scan_vstring(char *vstr, SV *sv)
954c1994 2567
497711e7 2568=for hackers
94bdecf9 2569Found in file util.c
497711e7 2570
954c1994
GS
2571=item SvCUR
2572
2573Returns the length of the string which is in the SV. See C<SvLEN>.
2574
2575 STRLEN SvCUR(SV* sv)
2576
497711e7
GS
2577=for hackers
2578Found in file sv.h
2579
954c1994
GS
2580=item SvCUR_set
2581
2582Set the length of the string which is in the SV. See C<SvCUR>.
2583
2584 void SvCUR_set(SV* sv, STRLEN len)
2585
497711e7
GS
2586=for hackers
2587Found in file sv.h
2588
94bdecf9 2589=item SvEND
954c1994 2590
94bdecf9
JH
2591Returns a pointer to the last character in the string which is in the SV.
2592See C<SvCUR>. Access the character as *(SvEND(sv)).
954c1994 2593
94bdecf9 2594 char* SvEND(SV* sv)
954c1994 2595
497711e7
GS
2596=for hackers
2597Found in file sv.h
2598
954c1994
GS
2599=item SvGROW
2600
2601Expands the character buffer in the SV so that it has room for the
2602indicated number of bytes (remember to reserve space for an extra trailing
8cf8f3d1 2603NUL character). Calls C<sv_grow> to perform the expansion if necessary.
954c1994
GS
2604Returns a pointer to the character buffer.
2605
679ac26e 2606 char * SvGROW(SV* sv, STRLEN len)
954c1994 2607
497711e7
GS
2608=for hackers
2609Found in file sv.h
2610
954c1994
GS
2611=item SvIOK
2612
2613Returns a boolean indicating whether the SV contains an integer.
2614
2615 bool SvIOK(SV* sv)
2616
497711e7
GS
2617=for hackers
2618Found in file sv.h
2619
954c1994
GS
2620=item SvIOKp
2621
2622Returns a boolean indicating whether the SV contains an integer. Checks
2623the B<private> setting. Use C<SvIOK>.
2624
2625 bool SvIOKp(SV* sv)
2626
497711e7
GS
2627=for hackers
2628Found in file sv.h
2629
e331fc52
JH
2630=item SvIOK_notUV
2631
f4758303 2632Returns a boolean indicating whether the SV contains a signed integer.
e331fc52
JH
2633
2634 void SvIOK_notUV(SV* sv)
2635
2636=for hackers
2637Found in file sv.h
2638
954c1994
GS
2639=item SvIOK_off
2640
2641Unsets the IV status of an SV.
2642
2643 void SvIOK_off(SV* sv)
2644
497711e7
GS
2645=for hackers
2646Found in file sv.h
2647
954c1994
GS
2648=item SvIOK_on
2649
2650Tells an SV that it is an integer.
2651
2652 void SvIOK_on(SV* sv)
2653
497711e7
GS
2654=for hackers
2655Found in file sv.h
2656
954c1994
GS
2657=item SvIOK_only
2658
2659Tells an SV that it is an integer and disables all other OK bits.
2660
2661 void SvIOK_only(SV* sv)
2662
497711e7
GS
2663=for hackers
2664Found in file sv.h
2665
e331fc52
JH
2666=item SvIOK_only_UV
2667
2668Tells and SV that it is an unsigned integer and disables all other OK bits.
2669
2670 void SvIOK_only_UV(SV* sv)
2671
2672=for hackers
2673Found in file sv.h
2674
2675=item SvIOK_UV
2676
2677Returns a boolean indicating whether the SV contains an unsigned integer.
2678
2679 void SvIOK_UV(SV* sv)
2680
2681=for hackers
2682Found in file sv.h
2683
954c1994
GS
2684=item SvIV
2685
645c22ef
DM
2686Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2687version which guarantees to evaluate sv only once.
954c1994
GS
2688
2689 IV SvIV(SV* sv)
2690
497711e7
GS
2691=for hackers
2692Found in file sv.h
2693
baca2b92 2694=item SvIVx
954c1994 2695
baca2b92
DM
2696Coerces the given SV to an integer and returns it. Guarantees to evaluate
2697sv only once. Use the more efficient C<SvIV> otherwise.
954c1994 2698
baca2b92 2699 IV SvIVx(SV* sv)
954c1994 2700
497711e7
GS
2701=for hackers
2702Found in file sv.h
2703
baca2b92 2704=item SvIVX
645c22ef 2705
baca2b92
DM
2706Returns the raw value in the SV's IV slot, without checks or conversions.
2707Only use when you are sure SvIOK is true. See also C<SvIV()>.
645c22ef 2708
baca2b92 2709 IV SvIVX(SV* sv)
645c22ef
DM
2710
2711=for hackers
2712Found in file sv.h
2713
954c1994
GS
2714=item SvLEN
2715
91e74348
JH
2716Returns the size of the string buffer in the SV, not including any part
2717attributable to C<SvOOK>. See C<SvCUR>.
954c1994
GS
2718
2719 STRLEN SvLEN(SV* sv)
2720
497711e7
GS
2721=for hackers
2722Found in file sv.h
2723
954c1994
GS
2724=item SvNIOK
2725
2726Returns a boolean indicating whether the SV contains a number, integer or
2727double.
2728
2729 bool SvNIOK(SV* sv)
2730
497711e7
GS
2731=for hackers
2732Found in file sv.h
2733
954c1994
GS
2734=item SvNIOKp
2735
2736Returns a boolean indicating whether the SV contains a number, integer or
2737double. Checks the B<private> setting. Use C<SvNIOK>.
2738
2739 bool SvNIOKp(SV* sv)
2740
497711e7
GS
2741=for hackers
2742Found in file sv.h
2743
954c1994
GS
2744=item SvNIOK_off
2745
2746Unsets the NV/IV status of an SV.
2747
2748 void SvNIOK_off(SV* sv)
2749
497711e7
GS
2750=for hackers
2751Found in file sv.h
2752
954c1994
GS
2753=item SvNOK
2754
2755Returns a boolean indicating whether the SV contains a double.
2756
2757 bool SvNOK(SV* sv)
2758
497711e7
GS
2759=for hackers
2760Found in file sv.h
2761
954c1994
GS
2762=item SvNOKp
2763
2764Returns a boolean indicating whether the SV contains a double. Checks the
2765B<private> setting. Use C<SvNOK>.
2766
2767 bool SvNOKp(SV* sv)
2768
497711e7
GS
2769=for hackers
2770Found in file sv.h
2771
954c1994
GS
2772=item SvNOK_off
2773
2774Unsets the NV status of an SV.
2775
2776 void SvNOK_off(SV* sv)
2777
497711e7
GS
2778=for hackers
2779Found in file sv.h
2780
954c1994
GS
2781=item SvNOK_on
2782
2783Tells an SV that it is a double.
2784
2785 void SvNOK_on(SV* sv)
2786
497711e7
GS
2787=for hackers
2788Found in file sv.h
2789
954c1994
GS
2790=item SvNOK_only
2791
2792Tells an SV that it is a double and disables all other OK bits.
2793
2794 void SvNOK_only(SV* sv)
2795
497711e7
GS
2796=for hackers
2797Found in file sv.h
2798
954c1994
GS
2799=item SvNV
2800
645c22ef
DM
2801Coerce the given SV to a double and return it. See C<SvNVx> for a version
2802which guarantees to evaluate sv only once.
954c1994
GS
2803
2804 NV SvNV(SV* sv)
2805
497711e7
GS
2806=for hackers
2807Found in file sv.h
2808
baca2b92 2809=item SvNVX
645c22ef 2810
baca2b92
DM
2811Returns the raw value in the SV's NV slot, without checks or conversions.
2812Only use when you are sure SvNOK is true. See also C<SvNV()>.
645c22ef 2813
baca2b92 2814 NV SvNVX(SV* sv)
645c22ef
DM
2815
2816=for hackers
2817Found in file sv.h
2818
baca2b92 2819=item SvNVx
954c1994 2820
baca2b92
DM
2821Coerces the given SV to a double and returns it. Guarantees to evaluate
2822sv only once. Use the more efficient C<SvNV> otherwise.
954c1994 2823
baca2b92 2824 NV SvNVx(SV* sv)
954c1994 2825
497711e7
GS
2826=for hackers
2827Found in file sv.h
2828
954c1994
GS
2829=item SvOK
2830
2831Returns a boolean indicating whether the value is an SV.
2832
2833 bool SvOK(SV* sv)
2834
497711e7
GS
2835=for hackers
2836Found in file sv.h
2837
954c1994
GS
2838=item SvOOK
2839
2840Returns a boolean indicating whether the SvIVX is a valid offset value for
2841the SvPVX. This hack is used internally to speed up removal of characters
2842from the beginning of a SvPV. When SvOOK is true, then the start of the
2843allocated string buffer is really (SvPVX - SvIVX).
2844
2845 bool SvOOK(SV* sv)
2846
497711e7
GS
2847=for hackers
2848Found in file sv.h
2849
954c1994
GS
2850=item SvPOK
2851
2852Returns a boolean indicating whether the SV contains a character
2853string.
2854
2855 bool SvPOK(SV* sv)
2856
497711e7
GS
2857=for hackers
2858Found in file sv.h
2859
954c1994
GS
2860=item SvPOKp
2861
2862Returns a boolean indicating whether the SV contains a character string.
2863Checks the B<private> setting. Use C<SvPOK>.
2864
2865 bool SvPOKp(SV* sv)
2866
497711e7
GS
2867=for hackers
2868Found in file sv.h
2869
954c1994
GS
2870=item SvPOK_off
2871
2872Unsets the PV status of an SV.
2873
2874 void SvPOK_off(SV* sv)
2875
497711e7
GS
2876=for hackers
2877Found in file sv.h
2878
954c1994
GS
2879=item SvPOK_on
2880
2881Tells an SV that it is a string.
2882
2883 void SvPOK_on(SV* sv)
2884
497711e7
GS
2885=for hackers
2886Found in file sv.h
2887
954c1994
GS
2888=item SvPOK_only
2889
2890Tells an SV that it is a string and disables all other OK bits.
d5ce4a7c 2891Will also turn off the UTF8 status.
954c1994
GS
2892
2893 void SvPOK_only(SV* sv)
2894
497711e7
GS
2895=for hackers
2896Found in file sv.h
2897
914184e1
JH
2898=item SvPOK_only_UTF8
2899
d5ce4a7c
GA
2900Tells an SV that it is a string and disables all other OK bits,
2901and leaves the UTF8 status as it was.
f1a1024e 2902
914184e1
JH
2903 void SvPOK_only_UTF8(SV* sv)
2904
2905=for hackers
2906Found in file sv.h
2907
954c1994
GS
2908=item SvPV
2909
12b7c5c7
JH
2910Returns a pointer to the string in the SV, or a stringified form of
2911the SV if the SV does not contain a string. The SV may cache the
2912stringified version becoming C<SvPOK>. Handles 'get' magic. See also
645c22ef 2913C<SvPVx> for a version which guarantees to evaluate sv only once.
954c1994
GS
2914
2915 char* SvPV(SV* sv, STRLEN len)
2916
497711e7
GS
2917=for hackers
2918Found in file sv.h
2919
645c22ef
DM
2920=item SvPVbyte
2921
2922Like C<SvPV>, but converts sv to byte representation first if necessary.
2923
2924 char* SvPVbyte(SV* sv, STRLEN len)
2925
2926=for hackers
2927Found in file sv.h
2928
2929=item SvPVbytex
2930
2931Like C<SvPV>, but converts sv to byte representation first if necessary.
d1be9408 2932Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
645c22ef
DM
2933otherwise.
2934
2935
2936 char* SvPVbytex(SV* sv, STRLEN len)
2937
2938=for hackers
2939Found in file sv.h
2940
2941=item SvPVbytex_force
2942
2943Like C<SvPV_force>, but converts sv to byte representation first if necessary.
d1be9408 2944Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
645c22ef
DM
2945otherwise.
2946
2947 char* SvPVbytex_force(SV* sv, STRLEN len)
2948
2949=for hackers
2950Found in file sv.h
2951
2952=item SvPVbyte_force
2953
2954Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2955
2956 char* SvPVbyte_force(SV* sv, STRLEN len)
2957
2958=for hackers
2959Found in file sv.h
2960
2961=item SvPVbyte_nolen
2962
2963Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2964
1fdc5aa6 2965 char* SvPVbyte_nolen(SV* sv)
645c22ef
DM
2966
2967=for hackers
2968Found in file sv.h
2969
2970=item SvPVutf8
2971
1fdc5aa6 2972Like C<SvPV>, but converts sv to utf8 first if necessary.
645c22ef
DM
2973
2974 char* SvPVutf8(SV* sv, STRLEN len)
2975
2976=for hackers
2977Found in file sv.h
2978
2979=item SvPVutf8x
2980
1fdc5aa6 2981Like C<SvPV>, but converts sv to utf8 first if necessary.
d1be9408 2982Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
645c22ef
DM
2983otherwise.
2984
2985 char* SvPVutf8x(SV* sv, STRLEN len)
2986
2987=for hackers
2988Found in file sv.h
2989
2990=item SvPVutf8x_force
2991
1fdc5aa6 2992Like C<SvPV_force>, but converts sv to utf8 first if necessary.
d1be9408 2993Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
645c22ef
DM
2994otherwise.
2995
2996 char* SvPVutf8x_force(SV* sv, STRLEN len)
2997
2998=for hackers
2999Found in file sv.h
3000
3001=item SvPVutf8_force
3002
1fdc5aa6 3003Like C<SvPV_force>, but converts sv to utf8 first if necessary.
645c22ef
DM
3004
3005 char* SvPVutf8_force(SV* sv, STRLEN len)
3006
3007=for hackers
3008Found in file sv.h
3009
3010=item SvPVutf8_nolen
3011
1fdc5aa6 3012Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
645c22ef 3013
1fdc5aa6 3014 char* SvPVutf8_nolen(SV* sv)
645c22ef
DM
3015
3016=for hackers
3017Found in file sv.h
3018
b0f01acb 3019=item SvPVx
645c22ef 3020
b0f01acb 3021A version of C<SvPV> which guarantees to evaluate sv only once.
645c22ef 3022
b0f01acb 3023 char* SvPVx(SV* sv, STRLEN len)
645c22ef
DM
3024
3025=for hackers
3026Found in file sv.h
3027
b0f01acb 3028=item SvPVX
954c1994 3029
b0f01acb
JP
3030Returns a pointer to the physical string in the SV. The SV must contain a
3031string.
954c1994 3032
b0f01acb 3033 char* SvPVX(SV* sv)
954c1994 3034
497711e7
GS
3035=for hackers
3036Found in file sv.h
3037
954c1994
GS
3038=item SvPV_force
3039
12b7c5c7
JH
3040Like C<SvPV> but will force the SV into containing just a string
3041(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3042directly.
954c1994
GS
3043
3044 char* SvPV_force(SV* sv, STRLEN len)
3045
497711e7
GS
3046=for hackers
3047Found in file sv.h
3048
645c22ef
DM
3049=item SvPV_force_nomg
3050
12b7c5c7
JH
3051Like C<SvPV> but will force the SV into containing just a string
3052(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
3053directly. Doesn't process magic.
645c22ef
DM
3054
3055 char* SvPV_force_nomg(SV* sv, STRLEN len)
3056
3057=for hackers
3058Found in file sv.h
3059
954c1994
GS
3060=item SvPV_nolen
3061
12b7c5c7
JH
3062Returns a pointer to the string in the SV, or a stringified form of
3063the SV if the SV does not contain a string. The SV may cache the
3064stringified form becoming C<SvPOK>. Handles 'get' magic.
954c1994
GS
3065
3066 char* SvPV_nolen(SV* sv)
3067
497711e7
GS
3068=for hackers
3069Found in file sv.h
3070
954c1994
GS
3071=item SvREFCNT
3072
3073Returns the value of the object's reference count.
3074
3075 U32 SvREFCNT(SV* sv)
3076
497711e7
GS
3077=for hackers
3078Found in file sv.h
3079
954c1994
GS
3080=item SvREFCNT_dec
3081
3082Decrements the reference count of the given SV.
3083
3084 void SvREFCNT_dec(SV* sv)
3085
497711e7
GS
3086=for hackers
3087Found in file sv.h
3088
954c1994
GS
3089=item SvREFCNT_inc
3090
3091Increments the reference count of the given SV.
3092
3093 SV* SvREFCNT_inc(SV* sv)
3094
497711e7
GS
3095=for hackers
3096Found in file sv.h
3097
954c1994
GS
3098=item SvROK
3099
3100Tests if the SV is an RV.
3101
3102 bool SvROK(SV* sv)
3103
497711e7
GS
3104=for hackers
3105Found in file sv.h
3106
954c1994
GS
3107=item SvROK_off
3108
3109Unsets the RV status of an SV.
3110
3111 void SvROK_off(SV* sv)
3112
497711e7
GS
3113=for hackers
3114Found in file sv.h
3115
954c1994
GS
3116=item SvROK_on
3117
3118Tells an SV that it is an RV.
3119
3120 void SvROK_on(SV* sv)
3121
497711e7
GS
3122=for hackers
3123Found in file sv.h
3124
954c1994
GS
3125=item SvRV
3126
3127Dereferences an RV to return the SV.
3128
3129 SV* SvRV(SV* sv)
3130
497711e7
GS
3131=for hackers
3132Found in file sv.h
3133
954c1994
GS
3134=item SvSTASH
3135
3136Returns the stash of the SV.
3137
3138 HV* SvSTASH(SV* sv)
3139
497711e7
GS
3140=for hackers
3141Found in file sv.h
3142
954c1994
GS
3143=item SvTAINT
3144
3145Taints an SV if tainting is enabled
3146
3147 void SvTAINT(SV* sv)
3148
497711e7
GS
3149=for hackers
3150Found in file sv.h
3151
954c1994
GS
3152=item SvTAINTED
3153
3154Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3155not.
3156
3157 bool SvTAINTED(SV* sv)
3158
497711e7
GS
3159=for hackers
3160Found in file sv.h
3161
954c1994
GS
3162=item SvTAINTED_off
3163
3164Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3165some of Perl's fundamental security features. XS module authors should not
3166use this function unless they fully understand all the implications of
3167unconditionally untainting the value. Untainting should be done in the
3168standard perl fashion, via a carefully crafted regexp, rather than directly
3169untainting variables.
3170
3171 void SvTAINTED_off(SV* sv)
3172
497711e7
GS
3173=for hackers
3174Found in file sv.h
3175
954c1994
GS
3176=item SvTAINTED_on
3177
3178Marks an SV as tainted.
3179
3180 void SvTAINTED_on(SV* sv)
3181
497711e7
GS
3182=for hackers
3183Found in file sv.h
3184
954c1994
GS
3185=item SvTRUE
3186
3187Returns a boolean indicating whether Perl would evaluate the SV as true or
3188false, defined or undefined. Does not handle 'get' magic.
3189
3190 bool SvTRUE(SV* sv)
3191
497711e7
GS
3192=for hackers
3193Found in file sv.h
3194
9f4817db 3195=item SvTYPE
af3c7592 3196
9f4817db
JH
3197Returns the type of the SV. See C<svtype>.
3198
3199 svtype SvTYPE(SV* sv)
954c1994 3200
497711e7
GS
3201=for hackers
3202Found in file sv.h
3203
a4f1a029
NIS
3204=item SvUNLOCK
3205
3206Releases a mutual exclusion lock on sv if a suitable module
3207has been loaded.
3208
3209
3210 void SvUNLOCK(SV* sv)
3211
3212=for hackers
3213Found in file sv.h
3214
a8586c98
JH
3215=item SvUOK
3216
3217Returns a boolean indicating whether the SV contains an unsigned integer.
3218
3219 void SvUOK(SV* sv)
3220
3221=for hackers
3222Found in file sv.h
3223
954c1994
GS
3224=item SvUPGRADE
3225
3226Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
3227perform the upgrade if necessary. See C<svtype>.
3228
3229 void SvUPGRADE(SV* sv, svtype type)
3230
497711e7
GS
3231=for hackers
3232Found in file sv.h
3233
914184e1
JH
3234=item SvUTF8
3235
3236Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3237
3238 void SvUTF8(SV* sv)
3239
3240=for hackers
3241Found in file sv.h
3242
3243=item SvUTF8_off
3244
3245Unsets the UTF8 status of an SV.
3246
3247 void SvUTF8_off(SV *sv)
3248
3249=for hackers
3250Found in file sv.h
3251
3252=item SvUTF8_on
3253
d5ce4a7c
GA
3254Turn on the UTF8 status of an SV (the data is not changed, just the flag).
3255Do not use frivolously.
914184e1
JH
3256
3257 void SvUTF8_on(SV *sv)
3258
3259=for hackers
3260Found in file sv.h
3261
954c1994
GS
3262=item SvUV
3263
645c22ef
DM
3264Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
3265for a version which guarantees to evaluate sv only once.
954c1994
GS
3266
3267 UV SvUV(SV* sv)
3268
497711e7
GS
3269=for hackers
3270Found in file sv.h
3271
b0f01acb
JP
3272=item SvUVX
3273
3274Returns the raw value in the SV's UV slot, without checks or conversions.
3275Only use when you are sure SvIOK is true. See also C<SvUV()>.
3276
3277 UV SvUVX(SV* sv)
3278
3279=for hackers
3280Found in file sv.h
3281
d6721266 3282=item SvUVx
954c1994 3283
d6721266
DM
3284Coerces the given SV to an unsigned integer and returns it. Guarantees to
3285evaluate sv only once. Use the more efficient C<SvUV> otherwise.
954c1994 3286
d6721266 3287 UV SvUVx(SV* sv)
954c1994 3288
497711e7
GS
3289=for hackers
3290Found in file sv.h
3291
b0f01acb 3292=item SvVOK
645c22ef 3293
b0f01acb 3294Returns a boolean indicating whether the SV contains a v-string.
645c22ef 3295
b0f01acb 3296 bool SvVOK(SV* sv)
645c22ef
DM
3297
3298=for hackers
3299Found in file sv.h
3300
3301=item sv_2bool
3302
3303This function is only called on magical items, and is only used by
8cf8f3d1 3304sv_true() or its macro equivalent.
645c22ef
DM
3305
3306 bool sv_2bool(SV* sv)
3307
3308=for hackers
3309Found in file sv.c
3310
3311=item sv_2cv
3312
3313Using various gambits, try to get a CV from an SV; in addition, try if
3314possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3315
3316 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3317
3318=for hackers
3319Found in file sv.c
3320
3321=item sv_2io
3322
3323Using various gambits, try to get an IO from an SV: the IO slot if its a
3324GV; or the recursive result if we're an RV; or the IO slot of the symbol
3325named after the PV if we're a string.
3326
3327 IO* sv_2io(SV* sv)
3328
3329=for hackers
3330Found in file sv.c
3331
3332=item sv_2iv
3333
3334Return the integer value of an SV, doing any necessary string conversion,
3335magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3336
3337 IV sv_2iv(SV* sv)
3338
3339=for hackers
3340Found in file sv.c
3341
954c1994
GS
3342=item sv_2mortal
3343
793edb8a
JH
3344Marks an existing SV as mortal. The SV will be destroyed "soon", either
3345by an explicit call to FREETMPS, or by an implicit call at places such as
3346statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
954c1994
GS
3347
3348 SV* sv_2mortal(SV* sv)
3349
497711e7
GS
3350=for hackers
3351Found in file sv.c
3352
645c22ef
DM
3353=item sv_2nv
3354
3355Return the num value of an SV, doing any necessary string or integer
3356conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3357macros.
3358
3359 NV sv_2nv(SV* sv)
3360
3361=for hackers
3362Found in file sv.c
3363
451be7b1
DM
3364=item sv_2pvbyte
3365
3366Return a pointer to the byte-encoded representation of the SV, and set *lp
3367to its length. May cause the SV to be downgraded from UTF8 as a
3368side-effect.
3369
3370Usually accessed via the C<SvPVbyte> macro.
3371
3372 char* sv_2pvbyte(SV* sv, STRLEN* lp)
3373
3374=for hackers
3375Found in file sv.c
3376
645c22ef
DM
3377=item sv_2pvbyte_nolen
3378
3379Return a pointer to the byte-encoded representation of the SV.
3380May cause the SV to be downgraded from UTF8 as a side-effect.
3381
3382Usually accessed via the C<SvPVbyte_nolen> macro.
3383
3384 char* sv_2pvbyte_nolen(SV* sv)
3385
3386=for hackers
3387Found in file sv.c
3388
451be7b1
DM
3389=item sv_2pvutf8
3390
3391Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3392to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
3393
3394Usually accessed via the C<SvPVutf8> macro.
3395
3396 char* sv_2pvutf8(SV* sv, STRLEN* lp)
3397
3398=for hackers
3399Found in file sv.c
3400
645c22ef
DM
3401=item sv_2pvutf8_nolen
3402
3403Return a pointer to the UTF8-encoded representation of the SV.
3404May cause the SV to be upgraded to UTF8 as a side-effect.
3405
3406Usually accessed via the C<SvPVutf8_nolen> macro.
3407
3408 char* sv_2pvutf8_nolen(SV* sv)
3409
3410=for hackers
3411Found in file sv.c
3412
3413=item sv_2pv_flags
3414
ff276b08 3415Returns a pointer to the string value of an SV, and sets *lp to its length.
645c22ef
DM
3416If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3417if necessary.
3418Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3419usually end up here too.
3420
3421 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3422
3423=for hackers
3424Found in file sv.c
3425
3426=item sv_2pv_nolen
3427
3428Like C<sv_2pv()>, but doesn't return the length too. You should usually
3429use the macro wrapper C<SvPV_nolen(sv)> instead.
3430 char* sv_2pv_nolen(SV* sv)
3431
3432=for hackers
3433Found in file sv.c
3434
3435=item sv_2uv
3436
3437Return the unsigned integer value of an SV, doing any necessary string
3438conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3439macros.
3440
3441 UV sv_2uv(SV* sv)
3442
3443=for hackers
3444Found in file sv.c
3445
3446=item sv_backoff
3447
3448Remove any string offset. You should normally use the C<SvOOK_off> macro
3449wrapper instead.
3450
3451 int sv_backoff(SV* sv)
3452
3453=for hackers
3454Found in file sv.c
3455
954c1994
GS
3456=item sv_bless
3457
3458Blesses an SV into a specified package. The SV must be an RV. The package
3459must be designated by its stash (see C<gv_stashpv()>). The reference count
3460of the SV is unaffected.
3461
3462 SV* sv_bless(SV* sv, HV* stash)
3463
497711e7
GS
3464=for hackers
3465Found in file sv.c
3466
954c1994
GS
3467=item sv_catpv
3468
3469Concatenates the string onto the end of the string which is in the SV.
d5ce4a7c
GA
3470If the SV has the UTF8 status set, then the bytes appended should be
3471valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
954c1994
GS
3472
3473 void sv_catpv(SV* sv, const char* ptr)
3474
497711e7
GS
3475=for hackers
3476Found in file sv.c
3477
954c1994
GS
3478=item sv_catpvf
3479
d5ce4a7c
GA
3480Processes its arguments like C<sprintf> and appends the formatted
3481output to an SV. If the appended data contains "wide" characters
3482(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3483and characters >255 formatted with %c), the original SV might get
3484upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
3485C<SvSETMAGIC()> must typically be called after calling this function
3486to handle 'set' magic.
954c1994
GS
3487
3488 void sv_catpvf(SV* sv, const char* pat, ...)
3489
497711e7
GS
3490=for hackers
3491Found in file sv.c
3492
954c1994
GS
3493=item sv_catpvf_mg
3494
3495Like C<sv_catpvf>, but also handles 'set' magic.
3496
3497 void sv_catpvf_mg(SV *sv, const char* pat, ...)