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