This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
s/\bthe the\b/the/g *.pod
[perl5.git] / pod / perlguts.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlguts - Perl's Internal Functions
4
5=head1 DESCRIPTION
6
7This document attempts to describe some of the internal functions of the
8Perl executable. It is far from complete and probably contains many errors.
9Please refer any questions or comments to the author below.
10
0a753a76
PP
11=head1 Variables
12
5f05dabc 13=head2 Datatypes
a0d0e21e
LW
14
15Perl has three typedefs that handle Perl's three main data types:
16
17 SV Scalar Value
18 AV Array Value
19 HV Hash Value
20
d1b91892 21Each typedef has specific routines that manipulate the various data types.
a0d0e21e
LW
22
23=head2 What is an "IV"?
24
5f05dabc
PP
25Perl uses a special typedef IV which is a simple integer type that is
26guaranteed to be large enough to hold a pointer (as well as an integer).
a0d0e21e 27
d1b91892
AD
28Perl also uses two special typedefs, I32 and I16, which will always be at
29least 32-bits and 16-bits long, respectively.
a0d0e21e 30
54310121 31=head2 Working with SVs
a0d0e21e
LW
32
33An SV can be created and loaded with one command. There are four types of
34values that can be loaded: an integer value (IV), a double (NV), a string,
35(PV), and another scalar (SV).
36
9da1e3b5 37The six routines are:
a0d0e21e
LW
38
39 SV* newSViv(IV);
40 SV* newSVnv(double);
41 SV* newSVpv(char*, int);
9da1e3b5 42 SV* newSVpvn(char*, int);
46fc3d4c 43 SV* newSVpvf(const char*, ...);
a0d0e21e
LW
44 SV* newSVsv(SV*);
45
deb3007b 46To change the value of an *already-existing* SV, there are seven routines:
a0d0e21e
LW
47
48 void sv_setiv(SV*, IV);
deb3007b 49 void sv_setuv(SV*, UV);
a0d0e21e 50 void sv_setnv(SV*, double);
a0d0e21e 51 void sv_setpv(SV*, char*);
46fc3d4c
PP
52 void sv_setpvn(SV*, char*, int)
53 void sv_setpvf(SV*, const char*, ...);
9abd00ed 54 void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
a0d0e21e
LW
55 void sv_setsv(SV*, SV*);
56
57Notice that you can choose to specify the length of the string to be
9da1e3b5
MUN
58assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
59allow Perl to calculate the length by using C<sv_setpv> or by specifying
600 as the second argument to C<newSVpv>. Be warned, though, that Perl will
61determine the string's length by using C<strlen>, which depends on the
9abd00ed
GS
62string terminating with a NUL character.
63
64The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
65formatted output becomes the value.
66
67C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify
68either a pointer to a variable argument list or the address and length of
69an array of SVs. The last argument points to a boolean; on return, if that
70boolean is true, then locale-specific information has been used to format
71the string, and the string's contents are therefore untrustworty (see
72L<perlsec>). This pointer may be NULL if that information is not
73important. Note that this function requires you to specify the length of
74the format.
75
9da1e3b5
MUN
76The C<sv_set*()> functions are not generic enough to operate on values
77that have "magic". See L<Magic Virtual Tables> later in this document.
a0d0e21e 78
a3cb178b
GS
79All SVs that contain strings should be terminated with a NUL character.
80If it is not NUL-terminated there is a risk of
5f05dabc
PP
81core dumps and corruptions from code which passes the string to C
82functions or system calls which expect a NUL-terminated string.
83Perl's own functions typically add a trailing NUL for this reason.
84Nevertheless, you should be very careful when you pass a string stored
85in an SV to a C function or system call.
86
a0d0e21e
LW
87To access the actual value that an SV points to, you can use the macros:
88
89 SvIV(SV*)
90 SvNV(SV*)
91 SvPV(SV*, STRLEN len)
92
93which will automatically coerce the actual scalar type into an IV, double,
94or string.
95
96In the C<SvPV> macro, the length of the string returned is placed into the
97variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
2d8e6c8d
GS
98care what the length of the data is, use the global variable C<PL_na>, though
99this is rather less efficient than using a local variable. Remember,
a0d0e21e 100however, that Perl allows arbitrary strings of data that may both contain
54310121 101NULs and might not be terminated by a NUL.
a0d0e21e 102
07fa94a1 103If you want to know if the scalar value is TRUE, you can use:
a0d0e21e
LW
104
105 SvTRUE(SV*)
106
107Although Perl will automatically grow strings for you, if you need to force
108Perl to allocate more memory for your SV, you can use the macro
109
110 SvGROW(SV*, STRLEN newlen)
111
112which will determine if more memory needs to be allocated. If so, it will
113call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
5f05dabc
PP
114decrease, the allocated memory of an SV and that it does not automatically
115add a byte for the a trailing NUL (perl's own string functions typically do
8ebc5c01 116C<SvGROW(sv, len + 1)>).
a0d0e21e
LW
117
118If you have an SV and want to know what kind of data Perl thinks is stored
119in it, you can use the following macros to check the type of SV you have.
120
121 SvIOK(SV*)
122 SvNOK(SV*)
123 SvPOK(SV*)
124
125You can get and set the current length of the string stored in an SV with
126the following macros:
127
128 SvCUR(SV*)
129 SvCUR_set(SV*, I32 val)
130
cb1a09d0
AD
131You can also get a pointer to the end of the string stored in the SV
132with the macro:
133
134 SvEND(SV*)
135
136But note that these last three macros are valid only if C<SvPOK()> is true.
a0d0e21e 137
d1b91892
AD
138If you want to append something to the end of string stored in an C<SV*>,
139you can use the following functions:
140
141 void sv_catpv(SV*, char*);
142 void sv_catpvn(SV*, char*, int);
46fc3d4c 143 void sv_catpvf(SV*, const char*, ...);
9abd00ed 144 void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
d1b91892
AD
145 void sv_catsv(SV*, SV*);
146
147The first function calculates the length of the string to be appended by
148using C<strlen>. In the second, you specify the length of the string
46fc3d4c 149yourself. The third function processes its arguments like C<sprintf> and
9abd00ed
GS
150appends the formatted output. The fourth function works like C<vsprintf>.
151You can specify the address and length of an array of SVs instead of the
152va_list argument. The fifth function extends the string stored in the first
153SV with the string stored in the second SV. It also forces the second SV
154to be interpreted as a string.
155
156The C<sv_cat*()> functions are not generic enough to operate on values that
157have "magic". See L<Magic Virtual Tables> later in this document.
d1b91892 158
a0d0e21e
LW
159If you know the name of a scalar variable, you can get a pointer to its SV
160by using the following:
161
5f05dabc 162 SV* perl_get_sv("package::varname", FALSE);
a0d0e21e
LW
163
164This returns NULL if the variable does not exist.
165
d1b91892 166If you want to know if this variable (or any other SV) is actually C<defined>,
a0d0e21e
LW
167you can call:
168
169 SvOK(SV*)
170
9cde0e7f 171The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>. Its
a0d0e21e
LW
172address can be used whenever an C<SV*> is needed.
173
9cde0e7f
GS
174There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
175TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their addresses can
a0d0e21e
LW
176be used whenever an C<SV*> is needed.
177
9cde0e7f 178Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
a0d0e21e
LW
179Take this code:
180
181 SV* sv = (SV*) 0;
182 if (I-am-to-return-a-real-value) {
183 sv = sv_2mortal(newSViv(42));
184 }
185 sv_setsv(ST(0), sv);
186
187This code tries to return a new SV (which contains the value 42) if it should
04343c6d 188return a real value, or undef otherwise. Instead it has returned a NULL
a0d0e21e 189pointer which, somewhere down the line, will cause a segmentation violation,
9cde0e7f 190bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the first
5f05dabc 191line and all will be well.
a0d0e21e
LW
192
193To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
3fe9a6f1 194call is not necessary (see L<Reference Counts and Mortality>).
a0d0e21e 195
d1b91892 196=head2 What's Really Stored in an SV?
a0d0e21e
LW
197
198Recall that the usual method of determining the type of scalar you have is
5f05dabc 199to use C<Sv*OK> macros. Because a scalar can be both a number and a string,
d1b91892 200usually these macros will always return TRUE and calling the C<Sv*V>
a0d0e21e
LW
201macros will do the appropriate conversion of string to integer/double or
202integer/double to string.
203
204If you I<really> need to know if you have an integer, double, or string
205pointer in an SV, you can use the following three macros instead:
206
207 SvIOKp(SV*)
208 SvNOKp(SV*)
209 SvPOKp(SV*)
210
211These will tell you if you truly have an integer, double, or string pointer
d1b91892 212stored in your SV. The "p" stands for private.
a0d0e21e 213
07fa94a1 214In general, though, it's best to use the C<Sv*V> macros.
a0d0e21e 215
54310121 216=head2 Working with AVs
a0d0e21e 217
07fa94a1
JO
218There are two ways to create and load an AV. The first method creates an
219empty AV:
a0d0e21e
LW
220
221 AV* newAV();
222
54310121 223The second method both creates the AV and initially populates it with SVs:
a0d0e21e
LW
224
225 AV* av_make(I32 num, SV **ptr);
226
5f05dabc 227The second argument points to an array containing C<num> C<SV*>'s. Once the
54310121 228AV has been created, the SVs can be destroyed, if so desired.
a0d0e21e 229
54310121 230Once the AV has been created, the following operations are possible on AVs:
a0d0e21e
LW
231
232 void av_push(AV*, SV*);
233 SV* av_pop(AV*);
234 SV* av_shift(AV*);
235 void av_unshift(AV*, I32 num);
236
237These should be familiar operations, with the exception of C<av_unshift>.
238This routine adds C<num> elements at the front of the array with the C<undef>
239value. You must then use C<av_store> (described below) to assign values
240to these new elements.
241
242Here are some other functions:
243
5f05dabc 244 I32 av_len(AV*);
a0d0e21e 245 SV** av_fetch(AV*, I32 key, I32 lval);
a0d0e21e 246 SV** av_store(AV*, I32 key, SV* val);
a0d0e21e 247
5f05dabc
PP
248The C<av_len> function returns the highest index value in array (just
249like $#array in Perl). If the array is empty, -1 is returned. The
250C<av_fetch> function returns the value at index C<key>, but if C<lval>
251is non-zero, then C<av_fetch> will store an undef value at that index.
04343c6d
GS
252The C<av_store> function stores the value C<val> at index C<key>, and does
253not increment the reference count of C<val>. Thus the caller is responsible
254for taking care of that, and if C<av_store> returns NULL, the caller will
255have to decrement the reference count to avoid a memory leak. Note that
256C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
257return value.
d1b91892 258
a0d0e21e 259 void av_clear(AV*);
a0d0e21e 260 void av_undef(AV*);
cb1a09d0 261 void av_extend(AV*, I32 key);
5f05dabc
PP
262
263The C<av_clear> function deletes all the elements in the AV* array, but
264does not actually delete the array itself. The C<av_undef> function will
265delete all the elements in the array plus the array itself. The
266C<av_extend> function extends the array so that it contains C<key>
267elements. If C<key> is less than the current length of the array, then
268nothing is done.
a0d0e21e
LW
269
270If you know the name of an array variable, you can get a pointer to its AV
271by using the following:
272
5f05dabc 273 AV* perl_get_av("package::varname", FALSE);
a0d0e21e
LW
274
275This returns NULL if the variable does not exist.
276
04343c6d
GS
277See L<Understanding the Magic of Tied Hashes and Arrays> for more
278information on how to use the array access functions on tied arrays.
279
54310121 280=head2 Working with HVs
a0d0e21e
LW
281
282To create an HV, you use the following routine:
283
284 HV* newHV();
285
54310121 286Once the HV has been created, the following operations are possible on HVs:
a0d0e21e
LW
287
288 SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
289 SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
290
5f05dabc
PP
291The C<klen> parameter is the length of the key being passed in (Note that
292you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
293length of the key). The C<val> argument contains the SV pointer to the
54310121 294scalar being stored, and C<hash> is the precomputed hash value (zero if
5f05dabc
PP
295you want C<hv_store> to calculate it for you). The C<lval> parameter
296indicates whether this fetch is actually a part of a store operation, in
297which case a new undefined value will be added to the HV with the supplied
298key and C<hv_fetch> will return as if the value had already existed.
a0d0e21e 299
5f05dabc
PP
300Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
301C<SV*>. To access the scalar value, you must first dereference the return
302value. However, you should check to make sure that the return value is
303not NULL before dereferencing it.
a0d0e21e
LW
304
305These two functions check if a hash table entry exists, and deletes it.
306
307 bool hv_exists(HV*, char* key, U32 klen);
d1b91892 308 SV* hv_delete(HV*, char* key, U32 klen, I32 flags);
a0d0e21e 309
5f05dabc
PP
310If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
311create and return a mortal copy of the deleted value.
312
a0d0e21e
LW
313And more miscellaneous functions:
314
315 void hv_clear(HV*);
a0d0e21e 316 void hv_undef(HV*);
5f05dabc
PP
317
318Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
319table but does not actually delete the hash table. The C<hv_undef> deletes
320both the entries and the hash table itself.
a0d0e21e 321
d1b91892
AD
322Perl keeps the actual data in linked list of structures with a typedef of HE.
323These contain the actual key and value pointers (plus extra administrative
324overhead). The key is a string pointer; the value is an C<SV*>. However,
325once you have an C<HE*>, to get the actual key and value, use the routines
326specified below.
327
a0d0e21e
LW
328 I32 hv_iterinit(HV*);
329 /* Prepares starting point to traverse hash table */
330 HE* hv_iternext(HV*);
331 /* Get the next entry, and return a pointer to a
332 structure that has both the key and value */
333 char* hv_iterkey(HE* entry, I32* retlen);
334 /* Get the key from an HE structure and also return
335 the length of the key string */
cb1a09d0 336 SV* hv_iterval(HV*, HE* entry);
a0d0e21e
LW
337 /* Return a SV pointer to the value of the HE
338 structure */
cb1a09d0 339 SV* hv_iternextsv(HV*, char** key, I32* retlen);
d1b91892
AD
340 /* This convenience routine combines hv_iternext,
341 hv_iterkey, and hv_iterval. The key and retlen
342 arguments are return values for the key and its
343 length. The value is returned in the SV* argument */
a0d0e21e
LW
344
345If you know the name of a hash variable, you can get a pointer to its HV
346by using the following:
347
5f05dabc 348 HV* perl_get_hv("package::varname", FALSE);
a0d0e21e
LW
349
350This returns NULL if the variable does not exist.
351
8ebc5c01 352The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
a0d0e21e 353
a0d0e21e 354 hash = 0;
ab192400
GS
355 while (klen--)
356 hash = (hash * 33) + *key++;
357 hash = hash + (hash >> 5); /* after 5.006 */
358
359The last step was added in version 5.006 to improve distribution of
360lower bits in the resulting hash value.
a0d0e21e 361
04343c6d
GS
362See L<Understanding the Magic of Tied Hashes and Arrays> for more
363information on how to use the hash access functions on tied hashes.
364
1e422769
PP
365=head2 Hash API Extensions
366
367Beginning with version 5.004, the following functions are also supported:
368
369 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
370 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
371
372 bool hv_exists_ent (HV* tb, SV* key, U32 hash);
373 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
374
375 SV* hv_iterkeysv (HE* entry);
376
377Note that these functions take C<SV*> keys, which simplifies writing
378of extension code that deals with hash structures. These functions
379also allow passing of C<SV*> keys to C<tie> functions without forcing
380you to stringify the keys (unlike the previous set of functions).
381
382They also return and accept whole hash entries (C<HE*>), making their
383use more efficient (since the hash number for a particular string
384doesn't have to be recomputed every time). See L<API LISTING> later in
385this document for detailed descriptions.
386
387The following macros must always be used to access the contents of hash
388entries. Note that the arguments to these macros must be simple
389variables, since they may get evaluated more than once. See
390L<API LISTING> later in this document for detailed descriptions of these
391macros.
392
393 HePV(HE* he, STRLEN len)
394 HeVAL(HE* he)
395 HeHASH(HE* he)
396 HeSVKEY(HE* he)
397 HeSVKEY_force(HE* he)
398 HeSVKEY_set(HE* he, SV* sv)
399
400These two lower level macros are defined, but must only be used when
401dealing with keys that are not C<SV*>s:
402
403 HeKEY(HE* he)
404 HeKLEN(HE* he)
405
04343c6d
GS
406Note that both C<hv_store> and C<hv_store_ent> do not increment the
407reference count of the stored C<val>, which is the caller's responsibility.
408If these functions return a NULL value, the caller will usually have to
409decrement the reference count of C<val> to avoid a memory leak.
1e422769 410
a0d0e21e
LW
411=head2 References
412
d1b91892
AD
413References are a special type of scalar that point to other data types
414(including references).
a0d0e21e 415
07fa94a1 416To create a reference, use either of the following functions:
a0d0e21e 417
5f05dabc
PP
418 SV* newRV_inc((SV*) thing);
419 SV* newRV_noinc((SV*) thing);
a0d0e21e 420
5f05dabc 421The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
07fa94a1
JO
422functions are identical except that C<newRV_inc> increments the reference
423count of the C<thing>, while C<newRV_noinc> does not. For historical
424reasons, C<newRV> is a synonym for C<newRV_inc>.
425
426Once you have a reference, you can use the following macro to dereference
427the reference:
a0d0e21e
LW
428
429 SvRV(SV*)
430
431then call the appropriate routines, casting the returned C<SV*> to either an
d1b91892 432C<AV*> or C<HV*>, if required.
a0d0e21e 433
d1b91892 434To determine if an SV is a reference, you can use the following macro:
a0d0e21e
LW
435
436 SvROK(SV*)
437
07fa94a1
JO
438To discover what type of value the reference refers to, use the following
439macro and then check the return value.
d1b91892
AD
440
441 SvTYPE(SvRV(SV*))
442
443The most useful types that will be returned are:
444
445 SVt_IV Scalar
446 SVt_NV Scalar
447 SVt_PV Scalar
5f05dabc 448 SVt_RV Scalar
d1b91892
AD
449 SVt_PVAV Array
450 SVt_PVHV Hash
451 SVt_PVCV Code
5f05dabc
PP
452 SVt_PVGV Glob (possible a file handle)
453 SVt_PVMG Blessed or Magical Scalar
454
455 See the sv.h header file for more details.
d1b91892 456
cb1a09d0
AD
457=head2 Blessed References and Class Objects
458
459References are also used to support object-oriented programming. In the
460OO lexicon, an object is simply a reference that has been blessed into a
461package (or class). Once blessed, the programmer may now use the reference
462to access the various methods in the class.
463
464A reference can be blessed into a package with the following function:
465
466 SV* sv_bless(SV* sv, HV* stash);
467
468The C<sv> argument must be a reference. The C<stash> argument specifies
3fe9a6f1 469which class the reference will belong to. See
2ae324a7 470L<Stashes and Globs> for information on converting class names into stashes.
cb1a09d0
AD
471
472/* Still under construction */
473
474Upgrades rv to reference if not already one. Creates new SV for rv to
8ebc5c01
PP
475point to. If C<classname> is non-null, the SV is blessed into the specified
476class. SV is returned.
cb1a09d0
AD
477
478 SV* newSVrv(SV* rv, char* classname);
479
8ebc5c01
PP
480Copies integer or double into an SV whose reference is C<rv>. SV is blessed
481if C<classname> is non-null.
cb1a09d0
AD
482
483 SV* sv_setref_iv(SV* rv, char* classname, IV iv);
484 SV* sv_setref_nv(SV* rv, char* classname, NV iv);
485
5f05dabc 486Copies the pointer value (I<the address, not the string!>) into an SV whose
8ebc5c01 487reference is rv. SV is blessed if C<classname> is non-null.
cb1a09d0
AD
488
489 SV* sv_setref_pv(SV* rv, char* classname, PV iv);
490
8ebc5c01
PP
491Copies string into an SV whose reference is C<rv>. Set length to 0 to let
492Perl calculate the string length. SV is blessed if C<classname> is non-null.
cb1a09d0
AD
493
494 SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
495
9abd00ed
GS
496Tests whether the SV is blessed into the specified class. It does not
497check inheritance relationships.
498
499 int sv_isa(SV* sv, char* name);
500
501Tests whether the SV is a reference to a blessed object.
502
503 int sv_isobject(SV* sv);
504
505Tests whether the SV is derived from the specified class. SV can be either
506a reference to a blessed object or a string containing a class name. This
507is the function implementing the C<UNIVERSAL::isa> functionality.
508
509 bool sv_derived_from(SV* sv, char* name);
510
511To check if you've got an object derived from a specific class you have
512to write:
513
514 if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
cb1a09d0 515
5f05dabc 516=head2 Creating New Variables
cb1a09d0 517
5f05dabc
PP
518To create a new Perl variable with an undef value which can be accessed from
519your Perl script, use the following routines, depending on the variable type.
cb1a09d0 520
5f05dabc
PP
521 SV* perl_get_sv("package::varname", TRUE);
522 AV* perl_get_av("package::varname", TRUE);
523 HV* perl_get_hv("package::varname", TRUE);
cb1a09d0
AD
524
525Notice the use of TRUE as the second parameter. The new variable can now
526be set, using the routines appropriate to the data type.
527
5f05dabc
PP
528There are additional macros whose values may be bitwise OR'ed with the
529C<TRUE> argument to enable certain extra features. Those bits are:
cb1a09d0 530
5f05dabc 531 GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
54310121 532 "Name <varname> used only once: possible typo" warning.
07fa94a1
JO
533 GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
534 the variable did not exist before the function was called.
cb1a09d0 535
07fa94a1
JO
536If you do not specify a package name, the variable is created in the current
537package.
cb1a09d0 538
5f05dabc 539=head2 Reference Counts and Mortality
a0d0e21e 540
54310121
PP
541Perl uses an reference count-driven garbage collection mechanism. SVs,
542AVs, or HVs (xV for short in the following) start their life with a
55497cff 543reference count of 1. If the reference count of an xV ever drops to 0,
07fa94a1 544then it will be destroyed and its memory made available for reuse.
55497cff
PP
545
546This normally doesn't happen at the Perl level unless a variable is
5f05dabc
PP
547undef'ed or the last variable holding a reference to it is changed or
548overwritten. At the internal level, however, reference counts can be
55497cff
PP
549manipulated with the following macros:
550
551 int SvREFCNT(SV* sv);
5f05dabc 552 SV* SvREFCNT_inc(SV* sv);
55497cff
PP
553 void SvREFCNT_dec(SV* sv);
554
555However, there is one other function which manipulates the reference
07fa94a1
JO
556count of its argument. The C<newRV_inc> function, you will recall,
557creates a reference to the specified argument. As a side effect,
558it increments the argument's reference count. If this is not what
559you want, use C<newRV_noinc> instead.
560
561For example, imagine you want to return a reference from an XSUB function.
562Inside the XSUB routine, you create an SV which initially has a reference
563count of one. Then you call C<newRV_inc>, passing it the just-created SV.
5f05dabc
PP
564This returns the reference as a new SV, but the reference count of the
565SV you passed to C<newRV_inc> has been incremented to two. Now you
07fa94a1
JO
566return the reference from the XSUB routine and forget about the SV.
567But Perl hasn't! Whenever the returned reference is destroyed, the
568reference count of the original SV is decreased to one and nothing happens.
569The SV will hang around without any way to access it until Perl itself
570terminates. This is a memory leak.
5f05dabc
PP
571
572The correct procedure, then, is to use C<newRV_noinc> instead of
faed5253
JO
573C<newRV_inc>. Then, if and when the last reference is destroyed,
574the reference count of the SV will go to zero and it will be destroyed,
07fa94a1 575stopping any memory leak.
55497cff 576
5f05dabc 577There are some convenience functions available that can help with the
54310121 578destruction of xVs. These functions introduce the concept of "mortality".
07fa94a1
JO
579An xV that is mortal has had its reference count marked to be decremented,
580but not actually decremented, until "a short time later". Generally the
581term "short time later" means a single Perl statement, such as a call to
54310121 582an XSUB function. The actual determinant for when mortal xVs have their
07fa94a1
JO
583reference count decremented depends on two macros, SAVETMPS and FREETMPS.
584See L<perlcall> and L<perlxs> for more details on these macros.
55497cff
PP
585
586"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
587However, if you mortalize a variable twice, the reference count will
588later be decremented twice.
589
590You should be careful about creating mortal variables. Strange things
591can happen if you make the same value mortal within multiple contexts,
5f05dabc 592or if you make a variable mortal multiple times.
a0d0e21e
LW
593
594To create a mortal variable, use the functions:
595
596 SV* sv_newmortal()
597 SV* sv_2mortal(SV*)
598 SV* sv_mortalcopy(SV*)
599
5f05dabc
PP
600The first call creates a mortal SV, the second converts an existing
601SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
602third creates a mortal copy of an existing SV.
a0d0e21e 603
54310121 604The mortal routines are not just for SVs -- AVs and HVs can be
faed5253 605made mortal by passing their address (type-casted to C<SV*>) to the
07fa94a1 606C<sv_2mortal> or C<sv_mortalcopy> routines.
a0d0e21e 607
5f05dabc 608=head2 Stashes and Globs
a0d0e21e 609
aa689395
PP
610A "stash" is a hash that contains all of the different objects that
611are contained within a package. Each key of the stash is a symbol
612name (shared by all the different types of objects that have the same
613name), and each value in the hash table is a GV (Glob Value). This GV
614in turn contains references to the various objects of that name,
615including (but not limited to) the following:
cb1a09d0 616
a0d0e21e
LW
617 Scalar Value
618 Array Value
619 Hash Value
a3cb178b 620 I/O Handle
a0d0e21e
LW
621 Format
622 Subroutine
623
9cde0e7f 624There is a single stash called "PL_defstash" that holds the items that exist
5f05dabc
PP
625in the "main" package. To get at the items in other packages, append the
626string "::" to the package name. The items in the "Foo" package are in
9cde0e7f 627the stash "Foo::" in PL_defstash. The items in the "Bar::Baz" package are
5f05dabc 628in the stash "Baz::" in "Bar::"'s stash.
a0d0e21e 629
d1b91892 630To get the stash pointer for a particular package, use the function:
a0d0e21e
LW
631
632 HV* gv_stashpv(char* name, I32 create)
633 HV* gv_stashsv(SV*, I32 create)
634
635The first function takes a literal string, the second uses the string stored
d1b91892 636in the SV. Remember that a stash is just a hash table, so you get back an
cb1a09d0 637C<HV*>. The C<create> flag will create a new package if it is set.
a0d0e21e
LW
638
639The name that C<gv_stash*v> wants is the name of the package whose symbol table
640you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
641packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
642language itself.
a0d0e21e
LW
643
644Alternately, if you have an SV that is a blessed reference, you can find
645out the stash pointer by using:
646
647 HV* SvSTASH(SvRV(SV*));
648
649then use the following to get the package name itself:
650
651 char* HvNAME(HV* stash);
652
5f05dabc
PP
653If you need to bless or re-bless an object you can use the following
654function:
a0d0e21e
LW
655
656 SV* sv_bless(SV*, HV* stash)
657
658where the first argument, an C<SV*>, must be a reference, and the second
659argument is a stash. The returned C<SV*> can now be used in the same way
660as any other SV.
661
d1b91892
AD
662For more information on references and blessings, consult L<perlref>.
663
54310121 664=head2 Double-Typed SVs
0a753a76
PP
665
666Scalar variables normally contain only one type of value, an integer,
667double, pointer, or reference. Perl will automatically convert the
668actual scalar data from the stored type into the requested type.
669
670Some scalar variables contain more than one type of scalar data. For
671example, the variable C<$!> contains either the numeric value of C<errno>
672or its string equivalent from either C<strerror> or C<sys_errlist[]>.
673
674To force multiple data values into an SV, you must do two things: use the
675C<sv_set*v> routines to add the additional scalar type, then set a flag
676so that Perl will believe it contains more than one type of data. The
677four macros to set the flags are:
678
679 SvIOK_on
680 SvNOK_on
681 SvPOK_on
682 SvROK_on
683
684The particular macro you must use depends on which C<sv_set*v> routine
685you called first. This is because every C<sv_set*v> routine turns on
686only the bit for the particular type of data being set, and turns off
687all the rest.
688
689For example, to create a new Perl variable called "dberror" that contains
690both the numeric and descriptive string error values, you could use the
691following code:
692
693 extern int dberror;
694 extern char *dberror_list;
695
696 SV* sv = perl_get_sv("dberror", TRUE);
697 sv_setiv(sv, (IV) dberror);
698 sv_setpv(sv, dberror_list[dberror]);
699 SvIOK_on(sv);
700
701If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
702macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
703
704=head2 Magic Variables
a0d0e21e 705
d1b91892
AD
706[This section still under construction. Ignore everything here. Post no
707bills. Everything not permitted is forbidden.]
708
d1b91892
AD
709Any SV may be magical, that is, it has special features that a normal
710SV does not have. These features are stored in the SV structure in a
5f05dabc 711linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
d1b91892
AD
712
713 struct magic {
714 MAGIC* mg_moremagic;
715 MGVTBL* mg_virtual;
716 U16 mg_private;
717 char mg_type;
718 U8 mg_flags;
719 SV* mg_obj;
720 char* mg_ptr;
721 I32 mg_len;
722 };
723
724Note this is current as of patchlevel 0, and could change at any time.
725
726=head2 Assigning Magic
727
728Perl adds magic to an SV using the sv_magic function:
729
730 void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
731
732The C<sv> argument is a pointer to the SV that is to acquire a new magical
733feature.
734
735If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
736set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
737it to the beginning of the linked list of magical features. Any prior
738entry of the same type of magic is deleted. Note that this can be
5fb8527f 739overridden, and multiple instances of the same type of magic can be
d1b91892
AD
740associated with an SV.
741
54310121
PP
742The C<name> and C<namlen> arguments are used to associate a string with
743the magic, typically the name of a variable. C<namlen> is stored in the
744C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
d1b91892
AD
745copy of the name is stored in C<mg_ptr> field.
746
747The sv_magic function uses C<how> to determine which, if any, predefined
748"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
cb1a09d0
AD
749See the "Magic Virtual Table" section below. The C<how> argument is also
750stored in the C<mg_type> field.
d1b91892
AD
751
752The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
753structure. If it is not the same as the C<sv> argument, the reference
754count of the C<obj> object is incremented. If it is the same, or if
04343c6d 755the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
d1b91892
AD
756merely stored, without the reference count being incremented.
757
cb1a09d0
AD
758There is also a function to add magic to an C<HV>:
759
760 void hv_magic(HV *hv, GV *gv, int how);
761
762This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
763
764To remove the magic from an SV, call the function sv_unmagic:
765
766 void sv_unmagic(SV *sv, int type);
767
768The C<type> argument should be equal to the C<how> value when the C<SV>
769was initially made magical.
770
d1b91892
AD
771=head2 Magic Virtual Tables
772
773The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
774C<MGVTBL>, which is a structure of function pointers and stands for
775"Magic Virtual Table" to handle the various operations that might be
776applied to that variable.
777
778The C<MGVTBL> has five pointers to the following routine types:
779
780 int (*svt_get)(SV* sv, MAGIC* mg);
781 int (*svt_set)(SV* sv, MAGIC* mg);
782 U32 (*svt_len)(SV* sv, MAGIC* mg);
783 int (*svt_clear)(SV* sv, MAGIC* mg);
784 int (*svt_free)(SV* sv, MAGIC* mg);
785
786This MGVTBL structure is set at compile-time in C<perl.h> and there are
787currently 19 types (or 21 with overloading turned on). These different
788structures contain pointers to various routines that perform additional
789actions depending on which function is being called.
790
791 Function pointer Action taken
792 ---------------- ------------
793 svt_get Do something after the value of the SV is retrieved.
794 svt_set Do something after the SV is assigned a value.
795 svt_len Report on the SV's length.
796 svt_clear Clear something the SV represents.
797 svt_free Free any extra storage associated with the SV.
798
799For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
800to an C<mg_type> of '\0') contains:
801
802 { magic_get, magic_set, magic_len, 0, 0 }
803
804Thus, when an SV is determined to be magical and of type '\0', if a get
805operation is being performed, the routine C<magic_get> is called. All
806the various routines for the various magical types begin with C<magic_>.
807
808The current kinds of Magic Virtual Tables are:
809
bdbeb323 810 mg_type MGVTBL Type of magic
5f05dabc 811 ------- ------ ----------------------------
bdbeb323
SM
812 \0 vtbl_sv Special scalar variable
813 A vtbl_amagic %OVERLOAD hash
814 a vtbl_amagicelem %OVERLOAD hash element
815 c (none) Holds overload table (AMT) on stash
816 B vtbl_bm Boyer-Moore (fast string search)
d1b91892
AD
817 E vtbl_env %ENV hash
818 e vtbl_envelem %ENV hash element
bdbeb323
SM
819 f vtbl_fm Formline ('compiled' format)
820 g vtbl_mglob m//g target / study()ed string
d1b91892
AD
821 I vtbl_isa @ISA array
822 i vtbl_isaelem @ISA array element
bdbeb323
SM
823 k vtbl_nkeys scalar(keys()) lvalue
824 L (none) Debugger %_<filename
825 l vtbl_dbline Debugger %_<filename element
44a8e56a 826 o vtbl_collxfrm Locale transformation
bdbeb323
SM
827 P vtbl_pack Tied array or hash
828 p vtbl_packelem Tied array or hash element
829 q vtbl_packelem Tied scalar or handle
830 S vtbl_sig %SIG hash
831 s vtbl_sigelem %SIG hash element
d1b91892 832 t vtbl_taint Taintedness
bdbeb323
SM
833 U vtbl_uvar Available for use by extensions
834 v vtbl_vec vec() lvalue
835 x vtbl_substr substr() lvalue
836 y vtbl_defelem Shadow "foreach" iterator variable /
837 smart parameter vivification
838 * vtbl_glob GV (typeglob)
839 # vtbl_arylen Array length ($#ary)
840 . vtbl_pos pos() lvalue
841 ~ (none) Available for use by extensions
d1b91892 842
68dc0745
PP
843When an uppercase and lowercase letter both exist in the table, then the
844uppercase letter is used to represent some kind of composite type (a list
845or a hash), and the lowercase letter is used to represent an element of
d1b91892
AD
846that composite type.
847
bdbeb323
SM
848The '~' and 'U' magic types are defined specifically for use by
849extensions and will not be used by perl itself. Extensions can use
850'~' magic to 'attach' private information to variables (typically
851objects). This is especially useful because there is no way for
852normal perl code to corrupt this private information (unlike using
853extra elements of a hash object).
854
855Similarly, 'U' magic can be used much like tie() to call a C function
856any time a scalar's value is used or changed. The C<MAGIC>'s
857C<mg_ptr> field points to a C<ufuncs> structure:
858
859 struct ufuncs {
860 I32 (*uf_val)(IV, SV*);
861 I32 (*uf_set)(IV, SV*);
862 IV uf_index;
863 };
864
865When the SV is read from or written to, the C<uf_val> or C<uf_set>
866function will be called with C<uf_index> as the first arg and a
1526ead6
AB
867pointer to the SV as the second. A simple example of how to add 'U'
868magic is shown below. Note that the ufuncs structure is copied by
869sv_magic, so you can safely allocate it on the stack.
870
871 void
872 Umagic(sv)
873 SV *sv;
874 PREINIT:
875 struct ufuncs uf;
876 CODE:
877 uf.uf_val = &my_get_fn;
878 uf.uf_set = &my_set_fn;
879 uf.uf_index = 0;
880 sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf));
5f05dabc 881
bdbeb323
SM
882Note that because multiple extensions may be using '~' or 'U' magic,
883it is important for extensions to take extra care to avoid conflict.
884Typically only using the magic on objects blessed into the same class
885as the extension is sufficient. For '~' magic, it may also be
886appropriate to add an I32 'signature' at the top of the private data
887area and check that.
5f05dabc 888
ef50df4b
GS
889Also note that the C<sv_set*()> and C<sv_cat*()> functions described
890earlier do B<not> invoke 'set' magic on their targets. This must
891be done by the user either by calling the C<SvSETMAGIC()> macro after
892calling these functions, or by using one of the C<sv_set*_mg()> or
893C<sv_cat*_mg()> functions. Similarly, generic C code must call the
894C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
895obtained from external sources in functions that don't handle magic.
896L<API LISTING> later in this document identifies such functions.
189b2af5
GS
897For example, calls to the C<sv_cat*()> functions typically need to be
898followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
899since their implementation handles 'get' magic.
900
d1b91892
AD
901=head2 Finding Magic
902
903 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
904
905This routine returns a pointer to the C<MAGIC> structure stored in the SV.
906If the SV does not have that magical feature, C<NULL> is returned. Also,
54310121 907if the SV is not of type SVt_PVMG, Perl may core dump.
d1b91892
AD
908
909 int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
910
911This routine checks to see what types of magic C<sv> has. If the mg_type
68dc0745
PP
912field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
913the mg_type field is changed to be the lowercase letter.
a0d0e21e 914
04343c6d
GS
915=head2 Understanding the Magic of Tied Hashes and Arrays
916
917Tied hashes and arrays are magical beasts of the 'P' magic type.
9edb2b46
GS
918
919WARNING: As of the 5.004 release, proper usage of the array and hash
920access functions requires understanding a few caveats. Some
921of these caveats are actually considered bugs in the API, to be fixed
922in later releases, and are bracketed with [MAYCHANGE] below. If
923you find yourself actually applying such information in this section, be
924aware that the behavior may change in the future, umm, without warning.
04343c6d 925
1526ead6
AB
926The perl tie function associates a variable with an object that implements
927the various GET, SET etc methods. To perform the equivalent of the perl
928tie function from an XSUB, you must mimic this behaviour. The code below
929carries out the necessary steps - firstly it creates a new hash, and then
930creates a second hash which it blesses into the class which will implement
931the tie methods. Lastly it ties the two hashes together, and returns a
932reference to the new tied hash. Note that the code below does NOT call the
933TIEHASH method in the MyTie class -
934see L<Calling Perl Routines from within C Programs> for details on how
935to do this.
936
937 SV*
938 mytie()
939 PREINIT:
940 HV *hash;
941 HV *stash;
942 SV *tie;
943 CODE:
944 hash = newHV();
945 tie = newRV_noinc((SV*)newHV());
946 stash = gv_stashpv("MyTie", TRUE);
947 sv_bless(tie, stash);
948 hv_magic(hash, tie, 'P');
949 RETVAL = newRV_noinc(hash);
950 OUTPUT:
951 RETVAL
952
04343c6d
GS
953The C<av_store> function, when given a tied array argument, merely
954copies the magic of the array onto the value to be "stored", using
955C<mg_copy>. It may also return NULL, indicating that the value did not
9edb2b46
GS
956actually need to be stored in the array. [MAYCHANGE] After a call to
957C<av_store> on a tied array, the caller will usually need to call
958C<mg_set(val)> to actually invoke the perl level "STORE" method on the
959TIEARRAY object. If C<av_store> did return NULL, a call to
960C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
961leak. [/MAYCHANGE]
04343c6d
GS
962
963The previous paragraph is applicable verbatim to tied hash access using the
964C<hv_store> and C<hv_store_ent> functions as well.
965
966C<av_fetch> and the corresponding hash functions C<hv_fetch> and
967C<hv_fetch_ent> actually return an undefined mortal value whose magic
968has been initialized using C<mg_copy>. Note the value so returned does not
9edb2b46
GS
969need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
970need to call C<mg_get()> on the returned value in order to actually invoke
971the perl level "FETCH" method on the underlying TIE object. Similarly,
04343c6d
GS
972you may also call C<mg_set()> on the return value after possibly assigning
973a suitable value to it using C<sv_setsv>, which will invoke the "STORE"
9edb2b46 974method on the TIE object. [/MAYCHANGE]
04343c6d 975
9edb2b46 976[MAYCHANGE]
04343c6d
GS
977In other words, the array or hash fetch/store functions don't really
978fetch and store actual values in the case of tied arrays and hashes. They
979merely call C<mg_copy> to attach magic to the values that were meant to be
980"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually
981do the job of invoking the TIE methods on the underlying objects. Thus
9edb2b46 982the magic mechanism currently implements a kind of lazy access to arrays
04343c6d
GS
983and hashes.
984
985Currently (as of perl version 5.004), use of the hash and array access
986functions requires the user to be aware of whether they are operating on
9edb2b46
GS
987"normal" hashes and arrays, or on their tied variants. The API may be
988changed to provide more transparent access to both tied and normal data
989types in future versions.
990[/MAYCHANGE]
04343c6d
GS
991
992You would do well to understand that the TIEARRAY and TIEHASH interfaces
993are mere sugar to invoke some perl method calls while using the uniform hash
994and array syntax. The use of this sugar imposes some overhead (typically
995about two to four extra opcodes per FETCH/STORE operation, in addition to
996the creation of all the mortal variables required to invoke the methods).
997This overhead will be comparatively small if the TIE methods are themselves
998substantial, but if they are only a few statements long, the overhead
999will not be insignificant.
1000
d1c897a1
IZ
1001=head2 Localizing changes
1002
1003Perl has a very handy construction
1004
1005 {
1006 local $var = 2;
1007 ...
1008 }
1009
1010This construction is I<approximately> equivalent to
1011
1012 {
1013 my $oldvar = $var;
1014 $var = 2;
1015 ...
1016 $var = $oldvar;
1017 }
1018
1019The biggest difference is that the first construction would
1020reinstate the initial value of $var, irrespective of how control exits
1021the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
1022more efficient as well.
1023
1024There is a way to achieve a similar task from C via Perl API: create a
1025I<pseudo-block>, and arrange for some changes to be automatically
1026undone at the end of it, either explicit, or via a non-local exit (via
1027die()). A I<block>-like construct is created by a pair of
b687b08b
TC
1028C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
1029Such a construct may be created specially for some important localized
1030task, or an existing one (like boundaries of enclosing Perl
1031subroutine/block, or an existing pair for freeing TMPs) may be
1032used. (In the second case the overhead of additional localization must
1033be almost negligible.) Note that any XSUB is automatically enclosed in
1034an C<ENTER>/C<LEAVE> pair.
d1c897a1
IZ
1035
1036Inside such a I<pseudo-block> the following service is available:
1037
1038=over
1039
1040=item C<SAVEINT(int i)>
1041
1042=item C<SAVEIV(IV i)>
1043
1044=item C<SAVEI32(I32 i)>
1045
1046=item C<SAVELONG(long i)>
1047
1048These macros arrange things to restore the value of integer variable
1049C<i> at the end of enclosing I<pseudo-block>.
1050
1051=item C<SAVESPTR(s)>
1052
1053=item C<SAVEPPTR(p)>
1054
1055These macros arrange things to restore the value of pointers C<s> and
1056C<p>. C<s> must be a pointer of a type which survives conversion to
1057C<SV*> and back, C<p> should be able to survive conversion to C<char*>
1058and back.
1059
1060=item C<SAVEFREESV(SV *sv)>
1061
1062The refcount of C<sv> would be decremented at the end of
1063I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
1064used instead.
1065
1066=item C<SAVEFREEOP(OP *op)>
1067
1068The C<OP *> is op_free()ed at the end of I<pseudo-block>.
1069
1070=item C<SAVEFREEPV(p)>
1071
1072The chunk of memory which is pointed to by C<p> is Safefree()ed at the
1073end of I<pseudo-block>.
1074
1075=item C<SAVECLEARSV(SV *sv)>
1076
1077Clears a slot in the current scratchpad which corresponds to C<sv> at
1078the end of I<pseudo-block>.
1079
1080=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
1081
1082The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
1083string pointed to by C<key> is Safefree()ed. If one has a I<key> in
1084short-lived storage, the corresponding string may be reallocated like
1085this:
1086
9cde0e7f 1087 SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
d1c897a1
IZ
1088
1089=item C<SAVEDESTRUCTOR(f,p)>
1090
1091At the end of I<pseudo-block> the function C<f> is called with the
1092only argument (of type C<void*>) C<p>.
1093
1094=item C<SAVESTACK_POS()>
1095
1096The current offset on the Perl internal stack (cf. C<SP>) is restored
1097at the end of I<pseudo-block>.
1098
1099=back
1100
1101The following API list contains functions, thus one needs to
1102provide pointers to the modifiable data explicitly (either C pointers,
1103or Perlish C<GV *>s). Where the above macros take C<int>, a similar
1104function takes C<int *>.
1105
1106=over
1107
1108=item C<SV* save_scalar(GV *gv)>
1109
1110Equivalent to Perl code C<local $gv>.
1111
1112=item C<AV* save_ary(GV *gv)>
1113
1114=item C<HV* save_hash(GV *gv)>
1115
1116Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
1117
1118=item C<void save_item(SV *item)>
1119
1120Duplicates the current value of C<SV>, on the exit from the current
1121C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
1122using the stored value.
1123
1124=item C<void save_list(SV **sarg, I32 maxsarg)>
1125
1126A variant of C<save_item> which takes multiple arguments via an array
1127C<sarg> of C<SV*> of length C<maxsarg>.
1128
1129=item C<SV* save_svref(SV **sptr)>
1130
1131Similar to C<save_scalar>, but will reinstate a C<SV *>.
1132
1133=item C<void save_aptr(AV **aptr)>
1134
1135=item C<void save_hptr(HV **hptr)>
1136
1137Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
1138
1139=back
1140
1141The C<Alias> module implements localization of the basic types within the
1142I<caller's scope>. People who are interested in how to localize things in
1143the containing scope should take a look there too.
1144
0a753a76 1145=head1 Subroutines
a0d0e21e 1146
68dc0745 1147=head2 XSUBs and the Argument Stack
5f05dabc
PP
1148
1149The XSUB mechanism is a simple way for Perl programs to access C subroutines.
1150An XSUB routine will have a stack that contains the arguments from the Perl
1151program, and a way to map from the Perl data structures to a C equivalent.
1152
1153The stack arguments are accessible through the C<ST(n)> macro, which returns
1154the C<n>'th stack argument. Argument 0 is the first argument passed in the
1155Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
1156an C<SV*> is used.
1157
1158Most of the time, output from the C routine can be handled through use of
1159the RETVAL and OUTPUT directives. However, there are some cases where the
1160argument stack is not already long enough to handle all the return values.
1161An example is the POSIX tzname() call, which takes no arguments, but returns
1162two, the local time zone's standard and summer time abbreviations.
1163
1164To handle this situation, the PPCODE directive is used and the stack is
1165extended using the macro:
1166
924508f0 1167 EXTEND(SP, num);
5f05dabc 1168
924508f0
GS
1169where C<SP> is the macro that represents the local copy of the stack pointer,
1170and C<num> is the number of elements the stack should be extended by.
5f05dabc
PP
1171
1172Now that there is room on the stack, values can be pushed on it using the
54310121 1173macros to push IVs, doubles, strings, and SV pointers respectively:
5f05dabc
PP
1174
1175 PUSHi(IV)
1176 PUSHn(double)
1177 PUSHp(char*, I32)
1178 PUSHs(SV*)
1179
1180And now the Perl program calling C<tzname>, the two values will be assigned
1181as in:
1182
1183 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
1184
1185An alternate (and possibly simpler) method to pushing values on the stack is
1186to use the macros:
1187
1188 XPUSHi(IV)
1189 XPUSHn(double)
1190 XPUSHp(char*, I32)
1191 XPUSHs(SV*)
1192
1193These macros automatically adjust the stack for you, if needed. Thus, you
1194do not need to call C<EXTEND> to extend the stack.
1195
1196For more information, consult L<perlxs> and L<perlxstut>.
1197
1198=head2 Calling Perl Routines from within C Programs
a0d0e21e
LW
1199
1200There are four routines that can be used to call a Perl subroutine from
1201within a C program. These four are:
1202
1203 I32 perl_call_sv(SV*, I32);
1204 I32 perl_call_pv(char*, I32);
1205 I32 perl_call_method(char*, I32);
1206 I32 perl_call_argv(char*, I32, register char**);
1207
d1b91892
AD
1208The routine most often used is C<perl_call_sv>. The C<SV*> argument
1209contains either the name of the Perl subroutine to be called, or a
1210reference to the subroutine. The second argument consists of flags
1211that control the context in which the subroutine is called, whether
1212or not the subroutine is being passed arguments, how errors should be
1213trapped, and how to treat return values.
a0d0e21e
LW
1214
1215All four routines return the number of arguments that the subroutine returned
1216on the Perl stack.
1217
d1b91892
AD
1218When using any of these routines (except C<perl_call_argv>), the programmer
1219must manipulate the Perl stack. These include the following macros and
1220functions:
a0d0e21e
LW
1221
1222 dSP
924508f0 1223 SP
a0d0e21e
LW
1224 PUSHMARK()
1225 PUTBACK
1226 SPAGAIN
1227 ENTER
1228 SAVETMPS
1229 FREETMPS
1230 LEAVE
1231 XPUSH*()
cb1a09d0 1232 POP*()
a0d0e21e 1233
5f05dabc
PP
1234For a detailed description of calling conventions from C to Perl,
1235consult L<perlcall>.
a0d0e21e 1236
5f05dabc 1237=head2 Memory Allocation
a0d0e21e 1238
5f05dabc
PP
1239It is suggested that you use the version of malloc that is distributed
1240with Perl. It keeps pools of various sizes of unallocated memory in
07fa94a1
JO
1241order to satisfy allocation requests more quickly. However, on some
1242platforms, it may cause spurious malloc or free errors.
d1b91892
AD
1243
1244 New(x, pointer, number, type);
1245 Newc(x, pointer, number, type, cast);
1246 Newz(x, pointer, number, type);
1247
07fa94a1 1248These three macros are used to initially allocate memory.
5f05dabc
PP
1249
1250The first argument C<x> was a "magic cookie" that was used to keep track
1251of who called the macro, to help when debugging memory problems. However,
07fa94a1
JO
1252the current code makes no use of this feature (most Perl developers now
1253use run-time memory checkers), so this argument can be any number.
5f05dabc
PP
1254
1255The second argument C<pointer> should be the name of a variable that will
1256point to the newly allocated memory.
d1b91892 1257
d1b91892
AD
1258The third and fourth arguments C<number> and C<type> specify how many of
1259the specified type of data structure should be allocated. The argument
1260C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
1261should be used if the C<pointer> argument is different from the C<type>
1262argument.
1263
1264Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
1265to zero out all the newly allocated memory.
1266
1267 Renew(pointer, number, type);
1268 Renewc(pointer, number, type, cast);
1269 Safefree(pointer)
1270
1271These three macros are used to change a memory buffer size or to free a
1272piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
1273match those of C<New> and C<Newc> with the exception of not needing the
1274"magic cookie" argument.
1275
1276 Move(source, dest, number, type);
1277 Copy(source, dest, number, type);
1278 Zero(dest, number, type);
1279
1280These three macros are used to move, copy, or zero out previously allocated
1281memory. The C<source> and C<dest> arguments point to the source and
1282destination starting points. Perl will move, copy, or zero out C<number>
1283instances of the size of the C<type> data structure (using the C<sizeof>
1284function).
a0d0e21e 1285
5f05dabc 1286=head2 PerlIO
ce3d39e2 1287
5f05dabc
PP
1288The most recent development releases of Perl has been experimenting with
1289removing Perl's dependency on the "normal" standard I/O suite and allowing
1290other stdio implementations to be used. This involves creating a new
1291abstraction layer that then calls whichever implementation of stdio Perl
68dc0745 1292was compiled with. All XSUBs should now use the functions in the PerlIO
5f05dabc
PP
1293abstraction layer and not make any assumptions about what kind of stdio
1294is being used.
1295
1296For a complete description of the PerlIO abstraction, consult L<perlapio>.
1297
8ebc5c01 1298=head2 Putting a C value on Perl stack
ce3d39e2
IZ
1299
1300A lot of opcodes (this is an elementary operation in the internal perl
1301stack machine) put an SV* on the stack. However, as an optimization
1302the corresponding SV is (usually) not recreated each time. The opcodes
1303reuse specially assigned SVs (I<target>s) which are (as a corollary)
1304not constantly freed/created.
1305
0a753a76 1306Each of the targets is created only once (but see
ce3d39e2
IZ
1307L<Scratchpads and recursion> below), and when an opcode needs to put
1308an integer, a double, or a string on stack, it just sets the
1309corresponding parts of its I<target> and puts the I<target> on stack.
1310
1311The macro to put this target on stack is C<PUSHTARG>, and it is
1312directly used in some opcodes, as well as indirectly in zillions of
1313others, which use it via C<(X)PUSH[pni]>.
1314
8ebc5c01 1315=head2 Scratchpads
ce3d39e2 1316
54310121 1317The question remains on when the SVs which are I<target>s for opcodes
5f05dabc
PP
1318are created. The answer is that they are created when the current unit --
1319a subroutine or a file (for opcodes for statements outside of
1320subroutines) -- is compiled. During this time a special anonymous Perl
ce3d39e2
IZ
1321array is created, which is called a scratchpad for the current
1322unit.
1323
54310121 1324A scratchpad keeps SVs which are lexicals for the current unit and are
ce3d39e2
IZ
1325targets for opcodes. One can deduce that an SV lives on a scratchpad
1326by looking on its flags: lexicals have C<SVs_PADMY> set, and
1327I<target>s have C<SVs_PADTMP> set.
1328
54310121
PP
1329The correspondence between OPs and I<target>s is not 1-to-1. Different
1330OPs in the compile tree of the unit can use the same target, if this
ce3d39e2
IZ
1331would not conflict with the expected life of the temporary.
1332
2ae324a7 1333=head2 Scratchpads and recursion
ce3d39e2
IZ
1334
1335In fact it is not 100% true that a compiled unit contains a pointer to
1336the scratchpad AV. In fact it contains a pointer to an AV of
1337(initially) one element, and this element is the scratchpad AV. Why do
1338we need an extra level of indirection?
1339
1340The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1341these can create several execution pointers going into the same
1342subroutine. For the subroutine-child not write over the temporaries
1343for the subroutine-parent (lifespan of which covers the call to the
1344child), the parent and the child should have different
1345scratchpads. (I<And> the lexicals should be separate anyway!)
1346
5f05dabc
PP
1347So each subroutine is born with an array of scratchpads (of length 1).
1348On each entry to the subroutine it is checked that the current
ce3d39e2
IZ
1349depth of the recursion is not more than the length of this array, and
1350if it is, new scratchpad is created and pushed into the array.
1351
1352The I<target>s on this scratchpad are C<undef>s, but they are already
1353marked with correct flags.
1354
0a753a76
PP
1355=head1 Compiled code
1356
1357=head2 Code tree
1358
1359Here we describe the internal form your code is converted to by
1360Perl. Start with a simple example:
1361
1362 $a = $b + $c;
1363
1364This is converted to a tree similar to this one:
1365
1366 assign-to
1367 / \
1368 + $a
1369 / \
1370 $b $c
1371
7b8d334a 1372(but slightly more complicated). This tree reflects the way Perl
0a753a76
PP
1373parsed your code, but has nothing to do with the execution order.
1374There is an additional "thread" going through the nodes of the tree
1375which shows the order of execution of the nodes. In our simplified
1376example above it looks like:
1377
1378 $b ---> $c ---> + ---> $a ---> assign-to
1379
1380But with the actual compile tree for C<$a = $b + $c> it is different:
1381some nodes I<optimized away>. As a corollary, though the actual tree
1382contains more nodes than our simplified example, the execution order
1383is the same as in our example.
1384
1385=head2 Examining the tree
1386
1387If you have your perl compiled for debugging (usually done with C<-D
1388optimize=-g> on C<Configure> command line), you may examine the
1389compiled tree by specifying C<-Dx> on the Perl command line. The
1390output takes several lines per node, and for C<$b+$c> it looks like
1391this:
1392
1393 5 TYPE = add ===> 6
1394 TARG = 1
1395 FLAGS = (SCALAR,KIDS)
1396 {
1397 TYPE = null ===> (4)
1398 (was rv2sv)
1399 FLAGS = (SCALAR,KIDS)
1400 {
1401 3 TYPE = gvsv ===> 4
1402 FLAGS = (SCALAR)
1403 GV = main::b
1404 }
1405 }
1406 {
1407 TYPE = null ===> (5)
1408 (was rv2sv)
1409 FLAGS = (SCALAR,KIDS)
1410 {
1411 4 TYPE = gvsv ===> 5
1412 FLAGS = (SCALAR)
1413 GV = main::c
1414 }
1415 }
1416
1417This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1418not optimized away (one per number in the left column). The immediate
1419children of the given node correspond to C<{}> pairs on the same level
1420of indentation, thus this listing corresponds to the tree:
1421
1422 add
1423 / \
1424 null null
1425 | |
1426 gvsv gvsv
1427
1428The execution order is indicated by C<===E<gt>> marks, thus it is C<3
14294 5 6> (node C<6> is not included into above listing), i.e.,
1430C<gvsv gvsv add whatever>.
1431
1432=head2 Compile pass 1: check routines
1433
1434The tree is created by the I<pseudo-compiler> while yacc code feeds it
1435the constructions it recognizes. Since yacc works bottom-up, so does
1436the first pass of perl compilation.
1437
1438What makes this pass interesting for perl developers is that some
1439optimization may be performed on this pass. This is optimization by
1440so-called I<check routines>. The correspondence between node names
1441and corresponding check routines is described in F<opcode.pl> (do not
1442forget to run C<make regen_headers> if you modify this file).
1443
1444A check routine is called when the node is fully constructed except
7b8d334a 1445for the execution-order thread. Since at this time there are no
0a753a76
PP
1446back-links to the currently constructed node, one can do most any
1447operation to the top-level node, including freeing it and/or creating
1448new nodes above/below it.
1449
1450The check routine returns the node which should be inserted into the
1451tree (if the top-level node was not modified, check routine returns
1452its argument).
1453
1454By convention, check routines have names C<ck_*>. They are usually
1455called from C<new*OP> subroutines (or C<convert>) (which in turn are
1456called from F<perly.y>).
1457
1458=head2 Compile pass 1a: constant folding
1459
1460Immediately after the check routine is called the returned node is
1461checked for being compile-time executable. If it is (the value is
1462judged to be constant) it is immediately executed, and a I<constant>
1463node with the "return value" of the corresponding subtree is
1464substituted instead. The subtree is deleted.
1465
1466If constant folding was not performed, the execution-order thread is
1467created.
1468
1469=head2 Compile pass 2: context propagation
1470
1471When a context for a part of compile tree is known, it is propagated
a3cb178b 1472down through the tree. At this time the context can have 5 values
0a753a76
PP
1473(instead of 2 for runtime context): void, boolean, scalar, list, and
1474lvalue. In contrast with the pass 1 this pass is processed from top
1475to bottom: a node's context determines the context for its children.
1476
1477Additional context-dependent optimizations are performed at this time.
1478Since at this moment the compile tree contains back-references (via
1479"thread" pointers), nodes cannot be free()d now. To allow
1480optimized-away nodes at this stage, such nodes are null()ified instead
1481of free()ing (i.e. their type is changed to OP_NULL).
1482
1483=head2 Compile pass 3: peephole optimization
1484
1485After the compile tree for a subroutine (or for an C<eval> or a file)
1486is created, an additional pass over the code is performed. This pass
1487is neither top-down or bottom-up, but in the execution order (with
7b8d334a 1488additional complications for conditionals). These optimizations are
0a753a76
PP
1489done in the subroutine peep(). Optimizations performed at this stage
1490are subject to the same restrictions as in the pass 2.
1491
1492=head1 API LISTING
a0d0e21e 1493
cb1a09d0
AD
1494This is a listing of functions, macros, flags, and variables that may be
1495useful to extension writers or that may be found while reading other
1496extensions.
9cde0e7f
GS
1497
1498Note that all Perl API global variables must be referenced with the C<PL_>
1499prefix. Some macros are provided for compatibility with the older,
1500unadorned names, but this support will be removed in a future release.
1501
1502It is strongly recommended that all Perl API functions that don't begin
1503with C<perl> be referenced with an explicit C<Perl_> prefix.
1504
e89caa19 1505The sort order of the listing is case insensitive, with any
b5a41e52 1506occurrences of '_' ignored for the purpose of sorting.
a0d0e21e 1507
cb1a09d0 1508=over 8
a0d0e21e 1509
cb1a09d0
AD
1510=item av_clear
1511
0146554f
GA
1512Clears an array, making it empty. Does not free the memory used by the
1513array itself.
cb1a09d0 1514
ef50df4b 1515 void av_clear (AV* ar)
cb1a09d0
AD
1516
1517=item av_extend
1518
1519Pre-extend an array. The C<key> is the index to which the array should be
1520extended.
1521
ef50df4b 1522 void av_extend (AV* ar, I32 key)
cb1a09d0
AD
1523
1524=item av_fetch
1525
1526Returns the SV at the specified index in the array. The C<key> is the
1527index. If C<lval> is set then the fetch will be part of a store. Check
1528that the return value is non-null before dereferencing it to a C<SV*>.
1529
04343c6d
GS
1530See L<Understanding the Magic of Tied Hashes and Arrays> for more
1531information on how to use this function on tied arrays.
1532
ef50df4b 1533 SV** av_fetch (AV* ar, I32 key, I32 lval)
cb1a09d0 1534
e89caa19
GA
1535=item AvFILL
1536
95906810 1537Same as C<av_len()>. Deprecated, use C<av_len()> instead.
e89caa19 1538
cb1a09d0
AD
1539=item av_len
1540
1541Returns the highest index in the array. Returns -1 if the array is empty.
1542
ef50df4b 1543 I32 av_len (AV* ar)
cb1a09d0
AD
1544
1545=item av_make
1546
5fb8527f
PP
1547Creates a new AV and populates it with a list of SVs. The SVs are copied
1548into the array, so they may be freed after the call to av_make. The new AV
5f05dabc 1549will have a reference count of 1.
cb1a09d0 1550
ef50df4b 1551 AV* av_make (I32 size, SV** svp)
cb1a09d0
AD
1552
1553=item av_pop
1554
9cde0e7f 1555Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is
cb1a09d0
AD
1556empty.
1557
ef50df4b 1558 SV* av_pop (AV* ar)
cb1a09d0
AD
1559
1560=item av_push
1561
5fb8527f
PP
1562Pushes an SV onto the end of the array. The array will grow automatically
1563to accommodate the addition.
cb1a09d0 1564
ef50df4b 1565 void av_push (AV* ar, SV* val)
cb1a09d0
AD
1566
1567=item av_shift
1568
1569Shifts an SV off the beginning of the array.
1570
ef50df4b 1571 SV* av_shift (AV* ar)
cb1a09d0
AD
1572
1573=item av_store
1574
1575Stores an SV in an array. The array index is specified as C<key>. The
04343c6d
GS
1576return value will be NULL if the operation failed or if the value did not
1577need to be actually stored within the array (as in the case of tied arrays).
1578Otherwise it can be dereferenced to get the original C<SV*>. Note that the
1579caller is responsible for suitably incrementing the reference count of C<val>
1580before the call, and decrementing it if the function returned NULL.
1581
1582See L<Understanding the Magic of Tied Hashes and Arrays> for more
1583information on how to use this function on tied arrays.
cb1a09d0 1584
ef50df4b 1585 SV** av_store (AV* ar, I32 key, SV* val)
cb1a09d0
AD
1586
1587=item av_undef
1588
0146554f 1589Undefines the array. Frees the memory used by the array itself.
cb1a09d0 1590
ef50df4b 1591 void av_undef (AV* ar)
cb1a09d0
AD
1592
1593=item av_unshift
1594
0146554f
GA
1595Unshift the given number of C<undef> values onto the beginning of the
1596array. The array will grow automatically to accommodate the addition.
1597You must then use C<av_store> to assign values to these new elements.
cb1a09d0 1598
ef50df4b 1599 void av_unshift (AV* ar, I32 num)
cb1a09d0
AD
1600
1601=item CLASS
1602
1603Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
5fb8527f
PP
1604constructor. This is always a C<char*>. See C<THIS> and
1605L<perlxs/"Using XS With C++">.
cb1a09d0
AD
1606
1607=item Copy
1608
1609The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1610source, C<d> is the destination, C<n> is the number of items, and C<t> is
0146554f 1611the type. May fail on overlapping copies. See also C<Move>.
cb1a09d0 1612
e89caa19 1613 void Copy( s, d, n, t )
cb1a09d0
AD
1614
1615=item croak
1616
1617This is the XSUB-writer's interface to Perl's C<die> function. Use this
1618function the same way you use the C C<printf> function. See C<warn>.
1619
1620=item CvSTASH
1621
1622Returns the stash of the CV.
1623
e89caa19 1624 HV* CvSTASH( SV* sv )
cb1a09d0 1625
9cde0e7f 1626=item PL_DBsingle
cb1a09d0
AD
1627
1628When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1629boolean which indicates whether subs are being single-stepped.
5fb8527f 1630Single-stepping is automatically turned on after every step. This is the C
9cde0e7f 1631variable which corresponds to Perl's $DB::single variable. See C<PL_DBsub>.
cb1a09d0 1632
9cde0e7f 1633=item PL_DBsub
cb1a09d0
AD
1634
1635When Perl is run in debugging mode, with the B<-d> switch, this GV contains
5fb8527f 1636the SV which holds the name of the sub being debugged. This is the C
9cde0e7f 1637variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>.
cb1a09d0
AD
1638The sub name can be found by
1639
2d8e6c8d 1640 SvPV( GvSV( PL_DBsub ), len )
cb1a09d0 1641
9cde0e7f 1642=item PL_DBtrace
5fb8527f
PP
1643
1644Trace variable used when Perl is run in debugging mode, with the B<-d>
1645switch. This is the C variable which corresponds to Perl's $DB::trace
9cde0e7f 1646variable. See C<PL_DBsingle>.
5fb8527f 1647
cb1a09d0
AD
1648=item dMARK
1649
5fb8527f
PP
1650Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1651C<dORIGMARK>.
cb1a09d0
AD
1652
1653=item dORIGMARK
1654
1655Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1656
9cde0e7f 1657=item PL_dowarn
5fb8527f
PP
1658
1659The C variable which corresponds to Perl's $^W warning variable.
1660
cb1a09d0
AD
1661=item dSP
1662
924508f0
GS
1663Declares a local copy of perl's stack pointer for the XSUB, available via
1664the C<SP> macro. See C<SP>.
cb1a09d0
AD
1665
1666=item dXSARGS
1667
1668Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1669usually handled automatically by C<xsubpp>. Declares the C<items> variable
1670to indicate the number of items on the stack.
1671
5fb8527f
PP
1672=item dXSI32
1673
1674Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1675handled automatically by C<xsubpp>.
1676
491527d0
GS
1677=item do_binmode
1678
1679Switches filehandle to binmode. C<iotype> is what C<IoTYPE(io)> would
1680contain.
1681
1682 do_binmode(fp, iotype, TRUE);
1683
cb1a09d0
AD
1684=item ENTER
1685
1686Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1687
1688 ENTER;
1689
1690=item EXTEND
1691
1692Used to extend the argument stack for an XSUB's return values.
1693
ef50df4b 1694 EXTEND( sp, int x )
cb1a09d0 1695
e89caa19
GA
1696=item fbm_compile
1697
1698Analyses the string in order to make fast searches on it using fbm_instr() --
1699the Boyer-Moore algorithm.
1700
411d5715 1701 void fbm_compile(SV* sv, U32 flags)
e89caa19
GA
1702
1703=item fbm_instr
1704
1705Returns the location of the SV in the string delimited by C<str> and
1706C<strend>. It returns C<Nullch> if the string can't be found. The
1707C<sv> does not have to be fbm_compiled, but the search will not be as
1708fast then.
1709
411d5715 1710 char* fbm_instr(char *str, char *strend, SV *sv, U32 flags)
e89caa19 1711
cb1a09d0
AD
1712=item FREETMPS
1713
1714Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1715L<perlcall>.
1716
1717 FREETMPS;
1718
1719=item G_ARRAY
1720
54310121 1721Used to indicate array context. See C<GIMME_V>, C<GIMME> and L<perlcall>.
cb1a09d0
AD
1722
1723=item G_DISCARD
1724
1725Indicates that arguments returned from a callback should be discarded. See
1726L<perlcall>.
1727
1728=item G_EVAL
1729
1730Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1731
1732=item GIMME
1733
54310121
PP
1734A backward-compatible version of C<GIMME_V> which can only return
1735C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
1736
1737=item GIMME_V
1738
1739The XSUB-writer's equivalent to Perl's C<wantarray>. Returns
1740C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
1741context, respectively.
cb1a09d0
AD
1742
1743=item G_NOARGS
1744
1745Indicates that no arguments are being sent to a callback. See L<perlcall>.
1746
1747=item G_SCALAR
1748
54310121
PP
1749Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>.
1750
faed5253
JO
1751=item gv_fetchmeth
1752
1753Returns the glob with the given C<name> and a defined subroutine or
9607fc9c 1754C<NULL>. The glob lives in the given C<stash>, or in the stashes
f86cebdf 1755accessible via @ISA and @UNIVERSAL.
faed5253 1756
9607fc9c 1757The argument C<level> should be either 0 or -1. If C<level==0>, as a
0a753a76
PP
1758side-effect creates a glob with the given C<name> in the given
1759C<stash> which in the case of success contains an alias for the
1760subroutine, and sets up caching info for this glob. Similarly for all
1761the searched stashes.
1762
9607fc9c
PP
1763This function grants C<"SUPER"> token as a postfix of the stash name.
1764
0a753a76
PP
1765The GV returned from C<gv_fetchmeth> may be a method cache entry,
1766which is not visible to Perl code. So when calling C<perl_call_sv>,
1767you should not use the GV directly; instead, you should use the
1768method's CV, which can be obtained from the GV with the C<GvCV> macro.
faed5253 1769
ef50df4b 1770 GV* gv_fetchmeth (HV* stash, char* name, STRLEN len, I32 level)
faed5253
JO
1771
1772=item gv_fetchmethod
1773
dc848c6f
PP
1774=item gv_fetchmethod_autoload
1775
faed5253 1776Returns the glob which contains the subroutine to call to invoke the
dc848c6f
PP
1777method on the C<stash>. In fact in the presense of autoloading this may
1778be the glob for "AUTOLOAD". In this case the corresponding variable
faed5253
JO
1779$AUTOLOAD is already setup.
1780
dc848c6f
PP
1781The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
1782lookup is performed if the given method is not present: non-zero means
1783yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling
1784C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
1785non-zero C<autoload> parameter.
1786
1787These functions grant C<"SUPER"> token as a prefix of the method name.
1788
1789Note that if you want to keep the returned glob for a long time, you
1790need to check for it being "AUTOLOAD", since at the later time the call
faed5253
JO
1791may load a different subroutine due to $AUTOLOAD changing its value.
1792Use the glob created via a side effect to do this.
1793
dc848c6f
PP
1794These functions have the same side-effects and as C<gv_fetchmeth> with
1795C<level==0>. C<name> should be writable if contains C<':'> or C<'\''>.
0a753a76 1796The warning against passing the GV returned by C<gv_fetchmeth> to
dc848c6f 1797C<perl_call_sv> apply equally to these functions.
faed5253 1798
ef50df4b
GS
1799 GV* gv_fetchmethod (HV* stash, char* name)
1800 GV* gv_fetchmethod_autoload (HV* stash, char* name, I32 autoload)
faed5253 1801
e89caa19
GA
1802=item G_VOID
1803
1804Used to indicate void context. See C<GIMME_V> and L<perlcall>.
1805
cb1a09d0
AD
1806=item gv_stashpv
1807
1808Returns a pointer to the stash for a specified package. If C<create> is set
1809then the package will be created if it does not already exist. If C<create>
1810is not set and the package does not exist then NULL is returned.
1811
ef50df4b 1812 HV* gv_stashpv (char* name, I32 create)
cb1a09d0
AD
1813
1814=item gv_stashsv
1815
1816Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1817
ef50df4b 1818 HV* gv_stashsv (SV* sv, I32 create)
cb1a09d0 1819
e5581bf4 1820=item GvSV
cb1a09d0 1821
e5581bf4 1822Return the SV from the GV.
44a8e56a 1823
1e422769
PP
1824=item HEf_SVKEY
1825
1826This flag, used in the length slot of hash entries and magic
1827structures, specifies the structure contains a C<SV*> pointer where a
1828C<char*> pointer is to be expected. (For information only--not to be used).
1829
1e422769
PP
1830=item HeHASH
1831
e89caa19 1832Returns the computed hash stored in the hash entry.
1e422769 1833
e89caa19 1834 U32 HeHASH(HE* he)
1e422769
PP
1835
1836=item HeKEY
1837
1838Returns the actual pointer stored in the key slot of the hash entry.
1839The pointer may be either C<char*> or C<SV*>, depending on the value of
1840C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros
1841are usually preferable for finding the value of a key.
1842
e89caa19 1843 char* HeKEY(HE* he)
1e422769
PP
1844
1845=item HeKLEN
1846
1847If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1848holds an C<SV*> key. Otherwise, holds the actual length of the key.
1849Can be assigned to. The C<HePV()> macro is usually preferable for finding
1850key lengths.
1851
e89caa19 1852 int HeKLEN(HE* he)
1e422769
PP
1853
1854=item HePV
1855
1856Returns the key slot of the hash entry as a C<char*> value, doing any
1857necessary dereferencing of possibly C<SV*> keys. The length of
1858the string is placed in C<len> (this is a macro, so do I<not> use
1859C<&len>). If you do not care about what the length of the key is,
2d8e6c8d
GS
1860you may use the global variable C<PL_na>, though this is rather less
1861efficient than using a local variable. Remember though, that hash
1e422769
PP
1862keys in perl are free to contain embedded nulls, so using C<strlen()>
1863or similar is not a good way to find the length of hash keys.
1864This is very similar to the C<SvPV()> macro described elsewhere in
1865this document.
1866
e89caa19 1867 char* HePV(HE* he, STRLEN len)
1e422769
PP
1868
1869=item HeSVKEY
1870
1871Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
1872does not contain an C<SV*> key.
1873
1874 HeSVKEY(HE* he)
1875
1876=item HeSVKEY_force
1877
1878Returns the key as an C<SV*>. Will create and return a temporary
1879mortal C<SV*> if the hash entry contains only a C<char*> key.
1880
1881 HeSVKEY_force(HE* he)
1882
1883=item HeSVKEY_set
1884
1885Sets the key to a given C<SV*>, taking care to set the appropriate flags
1886to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
1887
1888 HeSVKEY_set(HE* he, SV* sv)
1889
1890=item HeVAL
1891
1892Returns the value slot (type C<SV*>) stored in the hash entry.
1893
1894 HeVAL(HE* he)
1895
cb1a09d0
AD
1896=item hv_clear
1897
1898Clears a hash, making it empty.
1899
ef50df4b 1900 void hv_clear (HV* tb)
cb1a09d0
AD
1901
1902=item hv_delete
1903
1904Deletes a key/value pair in the hash. The value SV is removed from the hash
5fb8527f 1905and returned to the caller. The C<klen> is the length of the key. The
04343c6d 1906C<flags> value will normally be zero; if set to G_DISCARD then NULL will be
cb1a09d0
AD
1907returned.
1908
ef50df4b 1909 SV* hv_delete (HV* tb, char* key, U32 klen, I32 flags)
cb1a09d0 1910
1e422769
PP
1911=item hv_delete_ent
1912
1913Deletes a key/value pair in the hash. The value SV is removed from the hash
1914and returned to the caller. The C<flags> value will normally be zero; if set
04343c6d 1915to G_DISCARD then NULL will be returned. C<hash> can be a valid precomputed
1e422769
PP
1916hash value, or 0 to ask for it to be computed.
1917
ef50df4b 1918 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash)
1e422769 1919
cb1a09d0
AD
1920=item hv_exists
1921
1922Returns a boolean indicating whether the specified hash key exists. The
5fb8527f 1923C<klen> is the length of the key.
cb1a09d0 1924
ef50df4b 1925 bool hv_exists (HV* tb, char* key, U32 klen)
cb1a09d0 1926
1e422769
PP
1927=item hv_exists_ent
1928
1929Returns a boolean indicating whether the specified hash key exists. C<hash>
54310121 1930can be a valid precomputed hash value, or 0 to ask for it to be computed.
1e422769 1931
ef50df4b 1932 bool hv_exists_ent (HV* tb, SV* key, U32 hash)
1e422769 1933
cb1a09d0
AD
1934=item hv_fetch
1935
1936Returns the SV which corresponds to the specified key in the hash. The
5fb8527f 1937C<klen> is the length of the key. If C<lval> is set then the fetch will be
cb1a09d0
AD
1938part of a store. Check that the return value is non-null before
1939dereferencing it to a C<SV*>.
1940
04343c6d
GS
1941See L<Understanding the Magic of Tied Hashes and Arrays> for more
1942information on how to use this function on tied hashes.
1943
ef50df4b 1944 SV** hv_fetch (HV* tb, char* key, U32 klen, I32 lval)
cb1a09d0 1945
1e422769
PP
1946=item hv_fetch_ent
1947
1948Returns the hash entry which corresponds to the specified key in the hash.
54310121 1949C<hash> must be a valid precomputed hash number for the given C<key>, or
1e422769
PP
19500 if you want the function to compute it. IF C<lval> is set then the
1951fetch will be part of a store. Make sure the return value is non-null
1952before accessing it. The return value when C<tb> is a tied hash
1953is a pointer to a static location, so be sure to make a copy of the
1954structure if you need to store it somewhere.
1955
04343c6d
GS
1956See L<Understanding the Magic of Tied Hashes and Arrays> for more
1957information on how to use this function on tied hashes.
1958
ef50df4b 1959 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash)
1e422769 1960
cb1a09d0
AD
1961=item hv_iterinit
1962
1963Prepares a starting point to traverse a hash table.
1964
ef50df4b 1965 I32 hv_iterinit (HV* tb)
cb1a09d0 1966
c6601927
SI
1967Returns the number of keys in the hash (i.e. the same as C<HvKEYS(tb)>).
1968The return value is currently only meaningful for hashes without tie
1969magic.
1970
1971NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number
1972of hash buckets that happen to be in use. If you still need that
1973esoteric value, you can get it through the macro C<HvFILL(tb)>.
fb73857a 1974
cb1a09d0
AD
1975=item hv_iterkey
1976
1977Returns the key from the current position of the hash iterator. See
1978C<hv_iterinit>.
1979
ef50df4b 1980 char* hv_iterkey (HE* entry, I32* retlen)
cb1a09d0 1981
1e422769 1982=item hv_iterkeysv
3fe9a6f1 1983
1e422769
PP
1984Returns the key as an C<SV*> from the current position of the hash
1985iterator. The return value will always be a mortal copy of the
1986key. Also see C<hv_iterinit>.
1987
ef50df4b 1988 SV* hv_iterkeysv (HE* entry)
1e422769 1989
cb1a09d0
AD
1990=item hv_iternext
1991
1992Returns entries from a hash iterator. See C<hv_iterinit>.
1993
ef50df4b 1994 HE* hv_iternext (HV* tb)
cb1a09d0
AD
1995
1996=item hv_iternextsv
1997
1998Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1999operation.
2000
e89caa19 2001 SV* hv_iternextsv (HV* hv, char** key, I32* retlen)
cb1a09d0
AD
2002
2003=item hv_iterval
2004
2005Returns the value from the current position of the hash iterator. See
2006C<hv_iterkey>.
2007
ef50df4b 2008 SV* hv_iterval (HV* tb, HE* entry)
cb1a09d0
AD
2009
2010=item hv_magic
2011
2012Adds magic to a hash. See C<sv_magic>.
2013
ef50df4b 2014 void hv_magic (HV* hv, GV* gv, int how)
cb1a09d0
AD
2015
2016=item HvNAME
2017
2018Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
2019
e89caa19 2020 char* HvNAME (HV* stash)
cb1a09d0
AD
2021
2022=item hv_store
2023
2024Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
54310121 2025the length of the key. The C<hash> parameter is the precomputed hash
cb1a09d0 2026value; if it is zero then Perl will compute it. The return value will be
04343c6d
GS
2027NULL if the operation failed or if the value did not need to be actually
2028stored within the hash (as in the case of tied hashes). Otherwise it can
2029be dereferenced to get the original C<SV*>. Note that the caller is
2030responsible for suitably incrementing the reference count of C<val>
2031before the call, and decrementing it if the function returned NULL.
2032
2033See L<Understanding the Magic of Tied Hashes and Arrays> for more
2034information on how to use this function on tied hashes.
cb1a09d0 2035
ef50df4b 2036 SV** hv_store (HV* tb, char* key, U32 klen, SV* val, U32 hash)
cb1a09d0 2037
1e422769
PP
2038=item hv_store_ent
2039
2040Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
54310121 2041parameter is the precomputed hash value; if it is zero then Perl will
1e422769 2042compute it. The return value is the new hash entry so created. It will be
04343c6d
GS
2043NULL if the operation failed or if the value did not need to be actually
2044stored within the hash (as in the case of tied hashes). Otherwise the
2045contents of the return value can be accessed using the C<He???> macros
2046described here. Note that the caller is responsible for suitably
2047incrementing the reference count of C<val> before the call, and decrementing
2048it if the function returned NULL.
2049
2050See L<Understanding the Magic of Tied Hashes and Arrays> for more
2051information on how to use this function on tied hashes.
1e422769 2052
ef50df4b 2053 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash)
1e422769 2054
cb1a09d0
AD
2055=item hv_undef
2056
2057Undefines the hash.
2058
ef50df4b 2059 void hv_undef (HV* tb)
cb1a09d0
AD
2060
2061=item isALNUM
2062
2063Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
5f05dabc 2064character or digit.
cb1a09d0 2065
e89caa19 2066 int isALNUM (char c)
cb1a09d0
AD
2067
2068=item isALPHA
2069
5fb8527f 2070Returns a boolean indicating whether the C C<char> is an ascii alphabetic
cb1a09d0
AD
2071character.
2072
e89caa19 2073 int isALPHA (char c)
cb1a09d0
AD
2074
2075=item isDIGIT
2076
2077Returns a boolean indicating whether the C C<char> is an ascii digit.
2078
e89caa19 2079 int isDIGIT (char c)
cb1a09d0
AD
2080
2081=item isLOWER
2082
2083Returns a boolean indicating whether the C C<char> is a lowercase character.
2084
e89caa19 2085 int isLOWER (char c)
cb1a09d0
AD
2086
2087=item isSPACE
2088
2089Returns a boolean indicating whether the C C<char> is whitespace.
2090
e89caa19 2091 int isSPACE (char c)
cb1a09d0
AD
2092
2093=item isUPPER
2094
2095Returns a boolean indicating whether the C C<char> is an uppercase character.
2096
e89caa19 2097 int isUPPER (char c)
cb1a09d0
AD
2098
2099=item items
2100
2101Variable which is setup by C<xsubpp> to indicate the number of items on the
5fb8527f
PP
2102stack. See L<perlxs/"Variable-length Parameter Lists">.
2103
2104=item ix
2105
2106Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
2107was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
cb1a09d0
AD
2108
2109=item LEAVE
2110
2111Closing bracket on a callback. See C<ENTER> and L<perlcall>.
2112
2113 LEAVE;
2114
e89caa19
GA
2115=item looks_like_number
2116
2117Test if an the content of an SV looks like a number (or is a number).
2118
2119 int looks_like_number(SV*)
2120
2121
cb1a09d0
AD
2122=item MARK
2123
5fb8527f 2124Stack marker variable for the XSUB. See C<dMARK>.
cb1a09d0
AD
2125
2126=item mg_clear
2127
2128Clear something magical that the SV represents. See C<sv_magic>.
2129
ef50df4b 2130 int mg_clear (SV* sv)
cb1a09d0
AD
2131
2132=item mg_copy
2133
2134Copies the magic from one SV to another. See C<sv_magic>.
2135
ef50df4b 2136 int mg_copy (SV *, SV *, char *, STRLEN)
cb1a09d0
AD
2137
2138=item mg_find
2139
2140Finds the magic pointer for type matching the SV. See C<sv_magic>.
2141
ef50df4b 2142 MAGIC* mg_find (SV* sv, int type)
cb1a09d0
AD
2143
2144=item mg_free
2145
2146Free any magic storage used by the SV. See C<sv_magic>.
2147
ef50df4b 2148 int mg_free (SV* sv)
cb1a09d0
AD
2149
2150=item mg_get
2151
2152Do magic after a value is retrieved from the SV. See C<sv_magic>.
2153
ef50df4b 2154 int mg_get (SV* sv)
cb1a09d0
AD
2155
2156=item mg_len
2157
2158Report on the SV's length. See C<sv_magic>.
2159
ef50df4b 2160 U32 mg_len (SV* sv)
cb1a09d0
AD
2161
2162=item mg_magical
2163
2164Turns on the magical status of an SV. See C<sv_magic>.
2165
ef50df4b 2166 void mg_magical (SV* sv)
cb1a09d0
AD
2167
2168=item mg_set
2169
2170Do magic after a value is assigned to the SV. See C<sv_magic>.
2171
ef50df4b 2172 int mg_set (SV* sv)
cb1a09d0
AD
2173
2174=item Move
2175
2176The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
2177source, C<d> is the destination, C<n> is the number of items, and C<t> is
0146554f 2178the type. Can do overlapping moves. See also C<Copy>.
cb1a09d0 2179
e89caa19 2180 void Move( s, d, n, t )
cb1a09d0 2181
9cde0e7f 2182=item PL_na
cb1a09d0 2183
2d8e6c8d
GS
2184A convenience variable which is typically used with C<SvPV> when one doesn't
2185care about the length of the string. It is usually more efficient to
2186declare a local variable and use that instead.
cb1a09d0
AD
2187
2188=item New
2189
2190The XSUB-writer's interface to the C C<malloc> function.
2191
e89caa19 2192 void* New( x, void *ptr, int size, type )
cb1a09d0
AD
2193
2194=item newAV
2195
5f05dabc 2196Creates a new AV. The reference count is set to 1.
cb1a09d0 2197
ef50df4b 2198 AV* newAV (void)
cb1a09d0 2199
e89caa19
GA
2200=item Newc
2201
2202The XSUB-writer's interface to the C C<malloc> function, with cast.
2203
2204 void* Newc( x, void *ptr, int size, type, cast )
2205
5476c433
JD
2206=item newCONSTSUB
2207
2208Creates a constant sub equivalent to Perl C<sub FOO () { 123 }>
2209which is eligible for inlining at compile-time.
2210
2211 void newCONSTSUB(HV* stash, char* name, SV* sv)
2212
cb1a09d0
AD
2213=item newHV
2214
5f05dabc 2215Creates a new HV. The reference count is set to 1.
cb1a09d0 2216
ef50df4b 2217 HV* newHV (void)
cb1a09d0 2218
5f05dabc 2219=item newRV_inc
cb1a09d0 2220
5f05dabc 2221Creates an RV wrapper for an SV. The reference count for the original SV is
cb1a09d0
AD
2222incremented.
2223
ef50df4b 2224 SV* newRV_inc (SV* ref)
5f05dabc
PP
2225
2226For historical reasons, "newRV" is a synonym for "newRV_inc".
2227
2228=item newRV_noinc
2229
2230Creates an RV wrapper for an SV. The reference count for the original
2231SV is B<not> incremented.
2232
ef50df4b 2233 SV* newRV_noinc (SV* ref)
cb1a09d0 2234
8c52afec 2235=item NEWSV
cb1a09d0 2236
e89caa19
GA
2237Creates a new SV. A non-zero C<len> parameter indicates the number of
2238bytes of preallocated string space the SV should have. An extra byte
2239for a tailing NUL is also reserved. (SvPOK is not set for the SV even
2240if string space is allocated.) The reference count for the new SV is
2241set to 1. C<id> is an integer id between 0 and 1299 (used to identify
2242leaks).
cb1a09d0 2243
ef50df4b 2244 SV* NEWSV (int id, STRLEN len)
cb1a09d0
AD
2245
2246=item newSViv
2247
07fa94a1
JO
2248Creates a new SV and copies an integer into it. The reference count for the
2249SV is set to 1.
cb1a09d0 2250
ef50df4b 2251 SV* newSViv (IV i)
cb1a09d0
AD
2252
2253=item newSVnv
2254
07fa94a1
JO
2255Creates a new SV and copies a double into it. The reference count for the
2256SV is set to 1.
cb1a09d0 2257
ef50df4b 2258 SV* newSVnv (NV i)
cb1a09d0
AD
2259
2260=item newSVpv
2261
07fa94a1
JO
2262Creates a new SV and copies a string into it. The reference count for the
2263SV is set to 1. If C<len> is zero then Perl will compute the length.
cb1a09d0 2264
ef50df4b 2265 SV* newSVpv (char* s, STRLEN len)
cb1a09d0 2266
e89caa19
GA
2267=item newSVpvf
2268
2269Creates a new SV an initialize it with the string formatted like
2270C<sprintf>.
2271
2272 SV* newSVpvf(const char* pat, ...);
2273
9da1e3b5
MUN
2274=item newSVpvn
2275
2276Creates a new SV and copies a string into it. The reference count for the
2277SV is set to 1. If C<len> is zero then Perl will create a zero length
2278string.
2279
ef50df4b 2280 SV* newSVpvn (char* s, STRLEN len)
9da1e3b5 2281
cb1a09d0
AD
2282=item newSVrv
2283
2284Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5fb8527f 2285it will be upgraded to one. If C<classname> is non-null then the new SV will
cb1a09d0 2286be blessed in the specified package. The new SV is returned and its
5f05dabc 2287reference count is 1.
8ebc5c01 2288
ef50df4b 2289 SV* newSVrv (SV* rv, char* classname)
cb1a09d0
AD
2290
2291=item newSVsv
2292
5fb8527f 2293Creates a new SV which is an exact duplicate of the original SV.
cb1a09d0 2294
ef50df4b 2295 SV* newSVsv (SV* old)
cb1a09d0
AD
2296
2297=item newXS
2298
2299Used by C<xsubpp> to hook up XSUBs as Perl subs.
2300
2301=item newXSproto
2302
2303Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
2304the subs.
2305
e89caa19
GA
2306=item Newz
2307
2308The XSUB-writer's interface to the C C<malloc> function. The allocated
2309memory is zeroed with C<memzero>.
2310
2311 void* Newz( x, void *ptr, int size, type )
2312
cb1a09d0
AD
2313=item Nullav
2314
2315Null AV pointer.
2316
2317=item Nullch
2318
2319Null character pointer.
2320
2321=item Nullcv
2322
2323Null CV pointer.
2324
2325=item Nullhv
2326
2327Null HV pointer.
2328
2329=item Nullsv
2330
2331Null SV pointer.
2332
2333=item ORIGMARK
2334
2335The original stack mark for the XSUB. See C<dORIGMARK>.
2336
2337=item perl_alloc
2338
2339Allocates a new Perl interpreter. See L<perlembed>.
2340
2341=item perl_call_argv
2342
2343Performs a callback to the specified Perl sub. See L<perlcall>.
2344
ef50df4b 2345 I32 perl_call_argv (char* subname, I32 flags, char** argv)
cb1a09d0
AD
2346
2347=item perl_call_method
2348
2349Performs a callback to the specified Perl method. The blessed object must
2350be on the stack. See L<perlcall>.
2351
ef50df4b 2352 I32 perl_call_method (char* methname, I32 flags)
cb1a09d0
AD
2353
2354=item perl_call_pv
2355
2356Performs a callback to the specified Perl sub. See L<perlcall>.
2357
ef50df4b 2358 I32 perl_call_pv (char* subname, I32 flags)
cb1a09d0
AD
2359
2360=item perl_call_sv
2361
2362Performs a callback to the Perl sub whose name is in the SV. See
2363L<perlcall>.
2364
ef50df4b 2365 I32 perl_call_sv (SV* sv, I32 flags)
cb1a09d0
AD
2366
2367=item perl_construct
2368
2369Initializes a new Perl interpreter. See L<perlembed>.
2370
2371=item perl_destruct
2372
2373Shuts down a Perl interpreter. See L<perlembed>.
2374
2375=item perl_eval_sv
2376
2377Tells Perl to C<eval> the string in the SV.
2378
ef50df4b 2379 I32 perl_eval_sv (SV* sv, I32 flags)
cb1a09d0 2380
137443ea
PP
2381=item perl_eval_pv
2382
2383Tells Perl to C<eval> the given string and return an SV* result.
2384
ef50df4b 2385 SV* perl_eval_pv (char* p, I32 croak_on_error)
137443ea 2386
cb1a09d0
AD
2387=item perl_free
2388
2389Releases a Perl interpreter. See L<perlembed>.
2390
2391=item perl_get_av
2392
2393Returns the AV of the specified Perl array. If C<create> is set and the
2394Perl variable does not exist then it will be created. If C<create> is not
04343c6d 2395set and the variable does not exist then NULL is returned.
cb1a09d0 2396
ef50df4b 2397 AV* perl_get_av (char* name, I32 create)
cb1a09d0
AD
2398
2399=item perl_get_cv
2400
2401Returns the CV of the specified Perl sub. If C<create> is set and the Perl
2402variable does not exist then it will be created. If C<create> is not
04343c6d 2403set and the variable does not exist then NULL is returned.
cb1a09d0 2404
ef50df4b 2405 CV* perl_get_cv (char* name, I32 create)
cb1a09d0
AD
2406
2407=item perl_get_hv
2408
2409Returns the HV of the specified Perl hash. If C<create> is set and the Perl
2410variable does not exist then it will be created. If C<create> is not
04343c6d 2411set and the variable does not exist then NULL is returned.
cb1a09d0 2412
ef50df4b 2413 HV* perl_get_hv (char* name, I32 create)
cb1a09d0
AD
2414
2415=item perl_get_sv
2416
2417Returns the SV of the specified Perl scalar. If C<create> is set and the
2418Perl variable does not exist then it will be created. If C<create> is not
04343c6d 2419set and the variable does not exist then NULL is returned.
cb1a09d0 2420
ef50df4b 2421 SV* perl_get_sv (char* name, I32 create)
cb1a09d0
AD
2422
2423=item perl_parse
2424
2425Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
2426
2427=item perl_require_pv
2428
2429Tells Perl to C<require> a module.
2430
ef50df4b 2431 void perl_require_pv (char* pv)
cb1a09d0
AD
2432
2433=item perl_run
2434
2435Tells a Perl interpreter to run. See L<perlembed>.
2436
2437=item POPi
2438
2439Pops an integer off the stack.
2440
e89caa19 2441 int POPi()
cb1a09d0
AD
2442
2443=item POPl
2444
2445Pops a long off the stack.
2446
e89caa19 2447 long POPl()
cb1a09d0
AD
2448
2449=item POPp
2450
2451Pops a string off the stack.
2452
e89caa19 2453 char* POPp()
cb1a09d0
AD
2454
2455=item POPn
2456
2457Pops a double off the stack.
2458
e89caa19 2459 double POPn()
cb1a09d0
AD
2460
2461=item POPs
2462
2463Pops an SV off the stack.
2464
e89caa19 2465 SV* POPs()
cb1a09d0
AD
2466
2467=item PUSHMARK
2468
2469Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
2470
2471 PUSHMARK(p)
2472
2473=item PUSHi
2474
2475Push an integer onto the stack. The stack must have room for this element.
189b2af5 2476Handles 'set' magic. See C<XPUSHi>.
cb1a09d0 2477
e89caa19 2478 void PUSHi(int d)
cb1a09d0
AD
2479
2480=item PUSHn
2481
2482Push a double onto the stack. The stack must have room for this element.
189b2af5 2483Handles 'set' magic. See C<XPUSHn>.
cb1a09d0 2484
e89caa19 2485 void PUSHn(double d)
cb1a09d0
AD
2486
2487=item PUSHp
2488
2489Push a string onto the stack. The stack must have room for this element.
189b2af5
GS
2490The C<len> indicates the length of the string. Handles 'set' magic. See
2491C<XPUSHp>.
cb1a09d0 2492
e89caa19 2493 void PUSHp(char *c, int len )
cb1a09d0
AD
2494
2495=item PUSHs
2496
189b2af5
GS
2497Push an SV onto the stack. The stack must have room for this element. Does
2498not handle 'set' magic. See C<XPUSHs>.
cb1a09d0 2499
e89caa19
GA
2500 void PUSHs(sv)
2501
2502=item PUSHu
2503
2504Push an unsigned integer onto the stack. The stack must have room for
2505this element. See C<XPUSHu>.
2506
2507 void PUSHu(unsigned int d)
2508
cb1a09d0
AD
2509
2510=item PUTBACK
2511
2512Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2513See C<PUSHMARK> and L<perlcall> for other uses.
2514
2515 PUTBACK;
2516
2517=item Renew
2518
2519The XSUB-writer's interface to the C C<realloc> function.
2520
e89caa19 2521 void* Renew( void *ptr, int size, type )
cb1a09d0
AD
2522
2523=item Renewc
2524
2525The XSUB-writer's interface to the C C<realloc> function, with cast.
2526
e89caa19 2527 void* Renewc( void *ptr, int size, type, cast )
cb1a09d0
AD
2528
2529=item RETVAL
2530
2531Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
5fb8527f
PP
2532This is always the proper type for the XSUB.
2533See L<perlxs/"The RETVAL Variable">.
cb1a09d0
AD
2534
2535=item safefree
2536
2537The XSUB-writer's interface to the C C<free> function.
2538
2539=item safemalloc
2540
2541The XSUB-writer's interface to the C C<malloc> function.
2542
2543=item saferealloc
2544
2545The XSUB-writer's interface to the C C<realloc> function.
2546
2547=item savepv
2548
2549Copy a string to a safe spot. This does not use an SV.
2550
ef50df4b 2551 char* savepv (char* sv)
cb1a09d0
AD
2552
2553=item savepvn
2554
2555Copy a string to a safe spot. The C<len> indicates number of bytes to
2556copy. This does not use an SV.
2557
ef50df4b 2558 char* savepvn (char* sv, I32 len)
cb1a09d0
AD
2559
2560=item SAVETMPS
2561
2562Opening bracket for temporaries on a callback. See C<FREETMPS> and
2563L<perlcall>.
2564
2565 SAVETMPS;
2566
2567=item SP
2568
2569Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2570C<SPAGAIN>.
2571
2572=item SPAGAIN
2573
54310121 2574Refetch the stack pointer. Used after a callback. See L<perlcall>.
cb1a09d0
AD
2575
2576 SPAGAIN;
2577
2578=item ST
2579
2580Used to access elements on the XSUB's stack.
2581
e89caa19 2582 SV* ST(int x)
cb1a09d0
AD
2583
2584=item strEQ
2585
2586Test two strings to see if they are equal. Returns true or false.
2587
e89caa19 2588 int strEQ( char *s1, char *s2 )
cb1a09d0
AD
2589
2590=item strGE
2591
2592Test two strings to see if the first, C<s1>, is greater than or equal to the
2593second, C<s2>. Returns true or false.
2594
e89caa19 2595 int strGE( char *s1, char *s2 )
cb1a09d0
AD
2596
2597=item strGT
2598
2599Test two strings to see if the first, C<s1>, is greater than the second,
2600C<s2>. Returns true or false.
2601
e89caa19 2602 int strGT( char *s1, char *s2 )
cb1a09d0
AD
2603
2604=item strLE
2605
2606Test two strings to see if the first, C<s1>, is less than or equal to the
2607second, C<s2>. Returns true or false.
2608
e89caa19 2609 int strLE( char *s1, char *s2 )
cb1a09d0
AD
2610
2611=item strLT
2612
2613Test two strings to see if the first, C<s1>, is less than the second,
2614C<s2>. Returns true or false.
2615
e89caa19 2616 int strLT( char *s1, char *s2 )
cb1a09d0
AD
2617
2618=item strNE
2619
2620Test two strings to see if they are different. Returns true or false.
2621
e89caa19 2622 int strNE( char *s1, char *s2 )
cb1a09d0
AD
2623
2624=item strnEQ
2625
2626Test two strings to see if they are equal. The C<len> parameter indicates
2627the number of bytes to compare. Returns true or false.
2628
e89caa19 2629 int strnEQ( char *s1, char *s2 )
cb1a09d0
AD
2630
2631=item strnNE
2632
2633Test two strings to see if they are different. The C<len> parameter
2634indicates the number of bytes to compare. Returns true or false.
2635
e89caa19 2636 int strnNE( char *s1, char *s2, int len )
cb1a09d0
AD
2637
2638=item sv_2mortal
2639
2640Marks an SV as mortal. The SV will be destroyed when the current context
2641ends.
2642
ef50df4b 2643 SV* sv_2mortal (SV* sv)
cb1a09d0
AD
2644
2645=item sv_bless
2646
2647Blesses an SV into a specified package. The SV must be an RV. The package
07fa94a1
JO
2648must be designated by its stash (see C<gv_stashpv()>). The reference count
2649of the SV is unaffected.
cb1a09d0 2650
ef50df4b 2651 SV* sv_bless (SV* sv, HV* stash)
cb1a09d0 2652
ef50df4b 2653=item sv_catpv
189b2af5 2654
ef50df4b
GS
2655Concatenates the string onto the end of the string which is in the SV.
2656Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
189b2af5 2657
ef50df4b 2658 void sv_catpv (SV* sv, char* ptr)
189b2af5 2659
ef50df4b 2660=item sv_catpv_mg
cb1a09d0 2661
ef50df4b 2662Like C<sv_catpv>, but also handles 'set' magic.
cb1a09d0 2663
ef50df4b 2664 void sv_catpvn (SV* sv, char* ptr)
cb1a09d0
AD
2665
2666=item sv_catpvn
2667
2668Concatenates the string onto the end of the string which is in the SV. The
189b2af5 2669C<len> indicates number of bytes to copy. Handles 'get' magic, but not
ef50df4b 2670'set' magic. See C<sv_catpvn_mg>.
cb1a09d0 2671
ef50df4b
GS
2672 void sv_catpvn (SV* sv, char* ptr, STRLEN len)
2673
2674=item sv_catpvn_mg
2675
2676Like C<sv_catpvn>, but also handles 'set' magic.
2677
2678 void sv_catpvn_mg (SV* sv, char* ptr, STRLEN len)
cb1a09d0 2679
46fc3d4c
PP
2680=item sv_catpvf
2681
2682Processes its arguments like C<sprintf> and appends the formatted output
189b2af5
GS
2683to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
2684typically be called after calling this function to handle 'set' magic.
46fc3d4c 2685
ef50df4b
GS
2686 void sv_catpvf (SV* sv, const char* pat, ...)
2687
2688=item sv_catpvf_mg
2689
2690Like C<sv_catpvf>, but also handles 'set' magic.
2691
2692 void sv_catpvf_mg (SV* sv, const char* pat, ...)
46fc3d4c 2693
cb1a09d0
AD
2694=item sv_catsv
2695
5fb8527f 2696Concatenates the string from SV C<ssv> onto the end of the string in SV
ef50df4b
GS
2697C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
2698
2699 void sv_catsv (SV* dsv, SV* ssv)
2700
2701=item sv_catsv_mg
cb1a09d0 2702
ef50df4b
GS
2703Like C<sv_catsv>, but also handles 'set' magic.
2704
2705 void sv_catsv_mg (SV* dsv, SV* ssv)
cb1a09d0 2706
e89caa19
GA
2707=item sv_chop
2708
2709Efficient removal of characters from the beginning of the string
2710buffer. SvPOK(sv) must be true and the C<ptr> must be a pointer to
2711somewhere inside the string buffer. The C<ptr> becomes the first
2712character of the adjusted string.
2713
2714 void sv_chop(SV* sv, char *ptr)
2715
2716
5fb8527f
PP
2717=item sv_cmp
2718
2719Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2720string in C<sv1> is less than, equal to, or greater than the string in
2721C<sv2>.
2722
ef50df4b 2723 I32 sv_cmp (SV* sv1, SV* sv2)
5fb8527f 2724
cb1a09d0
AD
2725=item SvCUR
2726
2727Returns the length of the string which is in the SV. See C<SvLEN>.
2728
e89caa19 2729 int SvCUR (SV* sv)
cb1a09d0
AD
2730
2731=item SvCUR_set
2732
2733Set the length of the string which is in the SV. See C<SvCUR>.
2734
e89caa19 2735 void SvCUR_set (SV* sv, int val )
cb1a09d0 2736
5fb8527f
PP
2737=item sv_dec
2738
5f05dabc 2739Auto-decrement of the value in the SV.
5fb8527f 2740
ef50df4b 2741 void sv_dec (SV* sv)
5fb8527f 2742
e89caa19
GA
2743=item sv_derived_from
2744
2745Returns a boolean indicating whether the SV is a subclass of the
2746specified class.
2747
2748 int sv_derived_from(SV* sv, char* class)
2749
9abd00ed
GS
2750=item sv_derived_from
2751
2752Returns a boolean indicating whether the SV is derived from the specified
2753class. This is the function that implements C<UNIVERSAL::isa>. It works
2754for class names as well as for objects.
2755
2756 bool sv_derived_from _((SV* sv, char* name));
2757
cb1a09d0
AD
2758=item SvEND
2759
2760Returns a pointer to the last character in the string which is in the SV.
2761See C<SvCUR>. Access the character as
2762
e89caa19 2763 char* SvEND(sv)
cb1a09d0 2764
5fb8527f
PP
2765=item sv_eq
2766
2767Returns a boolean indicating whether the strings in the two SVs are
2768identical.
2769
ef50df4b 2770 I32 sv_eq (SV* sv1, SV* sv2)
5fb8527f 2771
189b2af5
GS
2772=item SvGETMAGIC
2773
2774Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates
2775its argument more than once.
2776
2777 void SvGETMAGIC( SV *sv )
2778
cb1a09d0
AD
2779=item SvGROW
2780
e89caa19
GA
2781Expands the character buffer in the SV so that it has room for the
2782indicated number of bytes (remember to reserve space for an extra
2783trailing NUL character). Calls C<sv_grow> to perform the expansion if
2784necessary. Returns a pointer to the character buffer.
cb1a09d0 2785
22c35a8c 2786 char* SvGROW( SV* sv, STRLEN len )
cb1a09d0 2787
5fb8527f
PP
2788=item sv_grow
2789
2790Expands the character buffer in the SV. This will use C<sv_unref> and will
2791upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2792Use C<SvGROW>.
2793
2794=item sv_inc
2795
07fa94a1 2796Auto-increment of the value in the SV.
5fb8527f 2797
ef50df4b 2798 void sv_inc (SV* sv)
5fb8527f 2799
e89caa19
GA
2800=item sv_insert
2801
2802Inserts a string at the specified offset/length within the SV.
2803Similar to the Perl substr() function.
2804
2805 void sv_insert(SV *sv, STRLEN offset, STRLEN len,
2806 char *str, STRLEN strlen)
2807
cb1a09d0
AD
2808=item SvIOK
2809
2810Returns a boolean indicating whether the SV contains an integer.
2811
e89caa19 2812 int SvIOK (SV* SV)
cb1a09d0
AD
2813
2814=item SvIOK_off
2815
2816Unsets the IV status of an SV.
2817
e89caa19 2818 void SvIOK_off (SV* sv)
cb1a09d0
AD
2819
2820=item SvIOK_on
2821
2822Tells an SV that it is an integer.
2823
e89caa19 2824 void SvIOK_on (SV* sv)
cb1a09d0 2825
5fb8527f
PP
2826=item SvIOK_only
2827
2828Tells an SV that it is an integer and disables all other OK bits.
2829
e89caa19 2830 void SvIOK_only (SV* sv)
5fb8527f 2831
cb1a09d0
AD
2832=item SvIOKp
2833
2834Returns a boolean indicating whether the SV contains an integer. Checks the
2835B<private> setting. Use C<SvIOK>.
2836
e89caa19 2837 int SvIOKp (SV* SV)
cb1a09d0
AD
2838
2839=item sv_isa
2840
2841Returns a boolean indicating whether the SV is blessed into the specified
9abd00ed 2842class. This does not check for subtypes; use C<sv_derived_from> to verify
cb1a09d0
AD
2843an inheritance relationship.
2844
ef50df4b 2845 int sv_isa (SV* sv, char* name)
cb1a09d0 2846
cb1a09d0
AD
2847=item sv_isobject
2848
2849Returns a boolean indicating whether the SV is an RV pointing to a blessed
2850object. If the SV is not an RV, or if the object is not blessed, then this
2851will return false.
2852
ef50df4b 2853 int sv_isobject (SV* sv)
cb1a09d0 2854
e89caa19
GA
2855=item SvIV
2856
2857Returns the integer which is in the SV.
2858
9abd00ed 2859 int SvIV (SV* sv)
a59f3522 2860
cb1a09d0
AD
2861=item SvIVX
2862
2863Returns the integer which is stored in the SV.
2864
e89caa19 2865 int SvIVX (SV* sv)
cb1a09d0
AD
2866
2867=item SvLEN
2868
2869Returns the size of the string buffer in the SV. See C<SvCUR>.
2870
e89caa19 2871 int SvLEN (SV* sv)
cb1a09d0 2872
5fb8527f
PP
2873=item sv_len
2874
2875Returns the length of the string in the SV. Use C<SvCUR>.
2876
ef50df4b 2877 STRLEN sv_len (SV* sv)
5fb8527f 2878
cb1a09d0
AD
2879=item sv_magic
2880
2881Adds magic to an SV.
2882
ef50df4b 2883 void sv_magic (SV* sv, SV* obj, int how, char* name, I32 namlen)
cb1a09d0
AD
2884
2885=item sv_mortalcopy
2886
2887Creates a new SV which is a copy of the original SV. The new SV is marked
5f05dabc 2888as mortal.
cb1a09d0 2889
ef50df4b 2890 SV* sv_mortalcopy (SV* oldsv)
cb1a09d0 2891
cb1a09d0
AD
2892=item sv_newmortal
2893
5f05dabc 2894Creates a new SV which is mortal. The reference count of the SV is set to 1.
cb1a09d0 2895
ef50df4b 2896 SV* sv_newmortal (void)
cb1a09d0 2897
cb1a09d0
AD
2898=item SvNIOK
2899
2900Returns a boolean indicating whether the SV contains a number, integer or
2901double.
2902
e89caa19 2903 int SvNIOK (SV* SV)
cb1a09d0
AD
2904
2905=item SvNIOK_off
2906
2907Unsets the NV/IV status of an SV.
2908
e89caa19 2909 void SvNIOK_off (SV* sv)
cb1a09d0
AD
2910
2911=item SvNIOKp
2912
2913Returns a boolean indicating whether the SV contains a number, integer or
2914double. Checks the B<private> setting. Use C<SvNIOK>.
2915
e89caa19
GA
2916 int SvNIOKp (SV* SV)
2917
9cde0e7f 2918=item PL_sv_no
e89caa19 2919
9cde0e7f 2920This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as C<&PL_sv_no>.
cb1a09d0
AD
2921
2922=item SvNOK
2923
2924Returns a boolean indicating whether the SV contains a double.
2925
e89caa19 2926 int SvNOK (SV* SV)
cb1a09d0
AD
2927
2928=item SvNOK_off
2929
2930Unsets the NV status of an SV.
2931
e89caa19 2932 void SvNOK_off (SV* sv)
cb1a09d0
AD
2933
2934=item SvNOK_on
2935
2936Tells an SV that it is a double.
2937
e89caa19 2938 void SvNOK_on (SV* sv)
cb1a09d0 2939
5fb8527f
PP
2940=item SvNOK_only
2941
2942Tells an SV that it is a double and disables all other OK bits.
2943
e89caa19 2944 void SvNOK_only (SV* sv)
5fb8527f 2945
cb1a09d0
AD
2946=item SvNOKp
2947
2948Returns a boolean indicating whether the SV contains a double. Checks the
2949B<private> setting. Use C<SvNOK>.
2950
e89caa19 2951 int SvNOKp (SV* SV)
cb1a09d0
AD
2952
2953=item SvNV
2954
2955Returns the double which is stored in the SV.
2956
e89caa19 2957 double SvNV (SV* sv)
cb1a09d0
AD
2958
2959=item SvNVX
2960
2961Returns the double which is stored in the SV.
2962
e89caa19
GA
2963 double SvNVX (SV* sv)
2964
2965=item SvOK
2966
2967Returns a boolean indicating whether the value is an SV.
2968
2969 int SvOK (SV* sv)
2970
2971=item SvOOK
2972
2973Returns a boolean indicating whether the SvIVX is a valid offset value
2974for the SvPVX. This hack is used internally to speed up removal of
2975characters from the beginning of a SvPV. When SvOOK is true, then the
2976start of the allocated string buffer is really (SvPVX - SvIVX).
2977
9cde0e7f 2978 int SvOOK(SV* sv)
cb1a09d0
AD
2979
2980=item SvPOK
2981
2982Returns a boolean indicating whether the SV contains a character string.
2983
e89caa19 2984 int SvPOK (SV* SV)
cb1a09d0
AD
2985
2986=item SvPOK_off
2987
2988Unsets the PV status of an SV.
2989
e89caa19 2990 void SvPOK_off (SV* sv)
cb1a09d0
AD
2991
2992=item SvPOK_on
2993
2994Tells an SV that it is a string.
2995
e89caa19 2996 void SvPOK_on (SV* sv)
cb1a09d0 2997
5fb8527f
PP
2998=item SvPOK_only
2999
3000Tells an SV that it is a string and disables all other OK bits.
3001
e89caa19 3002 void SvPOK_only (SV* sv)
5fb8527f 3003
cb1a09d0
AD
3004=item SvPOKp
3005
3006Returns a boolean indicating whether the SV contains a character string.
3007Checks the B<private> setting. Use C<SvPOK>.
3008
e89caa19 3009 int SvPOKp (SV* SV)
cb1a09d0
AD
3010
3011=item SvPV
3012
3013Returns a pointer to the string in the SV, or a stringified form of the SV
2d8e6c8d 3014if the SV does not contain a string. Handles 'get' magic.
cb1a09d0 3015
e89caa19
GA
3016 char* SvPV (SV* sv, int len )
3017
3018=item SvPV_force
3019
3020Like <SvPV> but will force the SV into becoming a string (SvPOK). You
3021want force if you are going to update the SvPVX directly.
3022
3023 char* SvPV_force(SV* sv, int len)
3024
cb1a09d0
AD
3025
3026=item SvPVX
3027
3028Returns a pointer to the string in the SV. The SV must contain a string.
3029
e89caa19 3030 char* SvPVX (SV* sv)
cb1a09d0
AD
3031
3032=item SvREFCNT
3033
5f05dabc 3034Returns the value of the object's reference count.
cb1a09d0 3035
e89caa19 3036 int SvREFCNT (SV* sv)
cb1a09d0
AD
3037
3038=item SvREFCNT_dec
3039
5f05dabc 3040Decrements the reference count of the given SV.
cb1a09d0 3041
e89caa19 3042 void SvREFCNT_dec (SV* sv)
cb1a09d0
AD
3043
3044=item SvREFCNT_inc
3045
5f05dabc 3046Increments the reference count of the given SV.
cb1a09d0 3047
e89caa19 3048 void SvREFCNT_inc (SV* sv)
cb1a09d0
AD
3049
3050=item SvROK
3051
3052Tests if the SV is an RV.
3053
e89caa19 3054 int SvROK (SV* sv)
cb1a09d0
AD
3055
3056=item SvROK_off
3057
3058Unsets the RV status of an SV.
3059
e89caa19 3060 void SvROK_off (SV* sv)
cb1a09d0
AD
3061
3062=item SvROK_on
3063
3064Tells an SV that it is an RV.
3065
e89caa19 3066 void SvROK_on (SV* sv)
cb1a09d0
AD
3067
3068=item SvRV
3069
3070Dereferences an RV to return the SV.
3071
ef50df4b 3072 SV* SvRV (SV* sv)
cb1a09d0 3073
189b2af5
GS
3074=item SvSETMAGIC
3075
3076Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates
3077its argument more than once.
3078
3079 void SvSETMAGIC( SV *sv )
3080
ef50df4b 3081=item sv_setiv
189b2af5 3082
ef50df4b
GS
3083Copies an integer into the given SV. Does not handle 'set' magic.
3084See C<sv_setiv_mg>.
189b2af5 3085
ef50df4b 3086 void sv_setiv (SV* sv, IV num)
189b2af5 3087
ef50df4b 3088=item sv_setiv_mg
189b2af5 3089
ef50df4b 3090Like C<sv_setiv>, but also handles 'set' magic.
189b2af5 3091
ef50df4b 3092 void sv_setiv_mg (SV* sv, IV num)
189b2af5 3093
ef50df4b 3094=item sv_setnv
189b2af5 3095
ef50df4b
GS
3096Copies a double into the given SV. Does not handle 'set' magic.
3097See C<sv_setnv_mg>.
189b2af5 3098
ef50df4b 3099 void sv_setnv (SV* sv, double num)
189b2af5 3100
ef50df4b 3101=item sv_setnv_mg
189b2af5 3102
ef50df4b 3103Like C<sv_setnv>, but also handles 'set' magic.
189b2af5 3104
ef50df4b 3105 void sv_setnv_mg (SV* sv, double num)
189b2af5 3106
ef50df4b 3107=item sv_setpv
189b2af5 3108
ef50df4b
GS
3109Copies a string into an SV. The string must be null-terminated.
3110Does not handle 'set' magic. See C<sv_setpv_mg>.
189b2af5 3111
ef50df4b 3112 void sv_setpv (SV* sv, char* ptr)
189b2af5 3113
ef50df4b 3114=item sv_setpv_mg
189b2af5 3115
ef50df4b 3116Like C<sv_setpv>, but also handles 'set' magic.
189b2af5 3117
ef50df4b 3118 void sv_setpv_mg (SV* sv, char* ptr)
189b2af5 3119
ef50df4b 3120=item sv_setpviv
cb1a09d0 3121
ef50df4b
GS
3122Copies an integer into the given SV, also updating its string value.
3123Does not handle 'set' magic. See C<sv_setpviv_mg>.
cb1a09d0 3124
ef50df4b 3125 void sv_setpviv (SV* sv, IV num)
cb1a09d0 3126
ef50df4b 3127=item sv_setpviv_mg
cb1a09d0 3128
ef50df4b 3129Like C<sv_setpviv>, but also handles 'set' magic.
cb1a09d0 3130
ef50df4b 3131 void sv_setpviv_mg (SV* sv, IV num)
cb1a09d0 3132
ef50df4b 3133=item sv_setpvn
cb1a09d0 3134
ef50df4b
GS
3135Copies a string into an SV. The C<len> parameter indicates the number of
3136bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
cb1a09d0 3137
ef50df4b 3138 void sv_setpvn (SV* sv, char* ptr, STRLEN len)
cb1a09d0 3139
ef50df4b 3140=item sv_setpvn_mg
189b2af5 3141
ef50df4b 3142Like C<sv_setpvn>, but also handles 'set' magic.
189b2af5 3143
ef50df4b 3144 void sv_setpvn_mg (SV* sv, char* ptr, STRLEN len)
189b2af5 3145
ef50df4b 3146=item sv_setpvf
cb1a09d0 3147
ef50df4b
GS
3148Processes its arguments like C<sprintf> and sets an SV to the formatted
3149output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
cb1a09d0 3150
ef50df4b 3151 void sv_setpvf (SV* sv, const char* pat, ...)
cb1a09d0 3152
ef50df4b 3153=item sv_setpvf_mg
46fc3d4c 3154
ef50df4b 3155Like C<sv_setpvf>, but also handles 'set' magic.
46fc3d4c 3156
ef50df4b 3157 void sv_setpvf_mg (SV* sv, const char* pat, ...)
46fc3d4c 3158
cb1a09d0
AD
3159=item sv_setref_iv
3160
5fb8527f
PP
3161Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3162argument will be upgraded to an RV. That RV will be modified to point to
3163the new SV. The C<classname> argument indicates the package for the
3164blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3165will be returned and will have a reference count of 1.
cb1a09d0 3166
ef50df4b 3167 SV* sv_setref_iv (SV *rv, char *classname, IV iv)
cb1a09d0
AD
3168
3169=item sv_setref_nv
3170
5fb8527f
PP
3171Copies a double into a new SV, optionally blessing the SV. The C<rv>
3172argument will be upgraded to an RV. That RV will be modified to point to
3173the new SV. The C<classname> argument indicates the package for the
3174blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3175will be returned and will have a reference count of 1.
cb1a09d0 3176
ef50df4b 3177 SV* sv_setref_nv (SV *rv, char *classname, double nv)
cb1a09d0
AD
3178
3179=item sv_setref_pv
3180
5fb8527f
PP
3181Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3182argument will be upgraded to an RV. That RV will be modified to point to
9cde0e7f 3183the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
5fb8527f
PP
3184into the SV. The C<classname> argument indicates the package for the
3185blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3186will be returned and will have a reference count of 1.
cb1a09d0 3187
ef50df4b 3188 SV* sv_setref_pv (SV *rv, char *classname, void* pv)
cb1a09d0
AD
3189
3190Do not use with integral Perl types such as HV, AV, SV, CV, because those
3191objects will become corrupted by the pointer copy process.
3192
3193Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3194
3195=item sv_setref_pvn
3196
5fb8527f
PP
3197Copies a string into a new SV, optionally blessing the SV. The length of the
3198string must be specified with C<n>. The C<rv> argument will be upgraded to
3199an RV. That RV will be modified to point to the new SV. The C<classname>
cb1a09d0
AD
3200argument indicates the package for the blessing. Set C<classname> to
3201C<Nullch> to avoid the blessing. The new SV will be returned and will have
5f05dabc 3202a reference count of 1.
cb1a09d0 3203
ef50df4b 3204 SV* sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n)
cb1a09d0
AD
3205
3206Note that C<sv_setref_pv> copies the pointer while this copies the string.
3207
189b2af5
GS
3208=item SvSetSV
3209
3210Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
3211more than once.
3212
3213 void SvSetSV (SV* dsv, SV* ssv)
3214
3215=item SvSetSV_nosteal
3216
3217Calls a non-destructive version of C<sv_setsv> if dsv is not the same as ssv.
3218May evaluate arguments more than once.
3219
3220 void SvSetSV_nosteal (SV* dsv, SV* ssv)
3221
cb1a09d0
AD
3222=item sv_setsv
3223
3224Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
189b2af5 3225The source SV may be destroyed if it is mortal. Does not handle 'set' magic.
ef50df4b
GS
3226See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and C<sv_setsv_mg>.
3227
3228 void sv_setsv (SV* dsv, SV* ssv)
3229
3230=item sv_setsv_mg
3231
3232Like C<sv_setsv>, but also handles 'set' magic.
cb1a09d0 3233
ef50df4b 3234 void sv_setsv_mg (SV* dsv, SV* ssv)
cb1a09d0 3235
189b2af5
GS
3236=item sv_setuv
3237
3238Copies an unsigned integer into the given SV. Does not handle 'set' magic.
ef50df4b 3239See C<sv_setuv_mg>.
189b2af5 3240
ef50df4b
GS
3241 void sv_setuv (SV* sv, UV num)
3242
3243=item sv_setuv_mg
3244
3245Like C<sv_setuv>, but also handles 'set' magic.
3246
3247 void sv_setuv_mg (SV* sv, UV num)
189b2af5 3248
cb1a09d0
AD
3249=item SvSTASH
3250
3251Returns the stash of the SV.
3252
e89caa19
GA
3253 HV* SvSTASH (SV* sv)
3254
3255=item SvTAINT
3256
3257Taints an SV if tainting is enabled
3258
3259 void SvTAINT (SV* sv)
3260
3261=item SvTAINTED
3262
3263Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.
3264
3265 int SvTAINTED (SV* sv)
3266
3267=item SvTAINTED_off
3268
3269Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3270some of Perl's fundamental security features. XS module authors should
3271not use this function unless they fully understand all the implications
3272of unconditionally untainting the value. Untainting should be done in
3273the standard perl fashion, via a carefully crafted regexp, rather than
3274directly untainting variables.
3275
3276 void SvTAINTED_off (SV* sv)
3277
3278=item SvTAINTED_on
3279
3280Marks an SV as tainted.
3281
3282 void SvTAINTED_on (SV* sv)
cb1a09d0
AD
3283
3284=item SVt_IV
3285
3286Integer type flag for scalars. See C<svtype>.
3287
3288=item SVt_PV
3289
3290Pointer type flag for scalars. See C<svtype>.
3291
3292=item SVt_PVAV
3293
3294Type flag for arrays. See C<svtype>.
3295
3296=item SVt_PVCV
3297
3298Type flag for code refs. See C<svtype>.
3299
3300=item SVt_PVHV
3301
3302Type flag for hashes. See C<svtype>.
3303
3304=item SVt_PVMG
3305
3306Type flag for blessed scalars. See C<svtype>.
3307
3308=item SVt_NV
3309
3310Double type flag for scalars. See C<svtype>.
3311
3312=item SvTRUE
3313
3314Returns a boolean indicating whether Perl would evaluate the SV as true or
189b2af5 3315false, defined or undefined. Does not handle 'get' magic.
cb1a09d0 3316
e89caa19 3317 int SvTRUE (SV* sv)
cb1a09d0
AD
3318
3319=item SvTYPE
3320
3321Returns the type of the SV. See C<svtype>.
3322
3323 svtype SvTYPE (SV* sv)
3324
3325=item svtype
3326
3327An enum of flags for Perl types. These are found in the file B<sv.h> in the
3328C<svtype> enum. Test these flags with the C<SvTYPE> macro.
3329
9cde0e7f 3330=item PL_sv_undef
cb1a09d0 3331
9cde0e7f 3332This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
cb1a09d0 3333
5fb8527f
PP
3334=item sv_unref
3335
07fa94a1
JO
3336Unsets the RV status of the SV, and decrements the reference count of
3337whatever was being referenced by the RV. This can almost be thought of
3338as a reversal of C<newSVrv>. See C<SvROK_off>.
5fb8527f 3339
ef50df4b 3340 void sv_unref (SV* sv)
189b2af5 3341
e89caa19
GA
3342=item SvUPGRADE
3343
3344Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
3345the upgrade if necessary. See C<svtype>.
3346
3347 bool SvUPGRADE (SV* sv, svtype mt)
3348
3349=item sv_upgrade
3350
3351Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
3352
cb1a09d0
AD
3353=item sv_usepvn
3354
3355Tells an SV to use C<ptr> to find its string value. Normally the string is
5fb8527f
PP
3356stored inside the SV but sv_usepvn allows the SV to use an outside string.
3357The C<ptr> should point to memory that was allocated by C<malloc>. The
cb1a09d0
AD
3358string length, C<len>, must be supplied. This function will realloc the
3359memory pointed to by C<ptr>, so that pointer should not be freed or used by
189b2af5 3360the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
ef50df4b
GS
3361See C<sv_usepvn_mg>.
3362
3363 void sv_usepvn (SV* sv, char* ptr, STRLEN len)
3364
3365=item sv_usepvn_mg
3366
3367Like C<sv_usepvn>, but also handles 'set' magic.
cb1a09d0 3368
ef50df4b 3369 void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
cb1a09d0 3370
9abd00ed
GS
3371=item sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3372
3373Processes its arguments like C<vsprintf> and appends the formatted output
3374to an SV. Uses an array of SVs if the C style variable argument list is
3375missing (NULL). Indicates if locale information has been used for formatting.
3376
3377 void sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen,
3378 va_list *args, SV **svargs, I32 svmax,
3379 bool *used_locale));
3380
3381=item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3382
3383Works like C<vcatpvfn> but copies the text into the SV instead of
3384appending it.
3385
3386 void sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen,
3387 va_list *args, SV **svargs, I32 svmax,
3388 bool *used_locale));
3389
e89caa19
GA
3390=item SvUV
3391
3392Returns the unsigned integer which is in the SV.
3393
3394 UV SvUV(SV* sv)
3395
3396=item SvUVX
3397
3398Returns the unsigned integer which is stored in the SV.
3399
3400 UV SvUVX(SV* sv)
3401
9cde0e7f 3402=item PL_sv_yes
cb1a09d0 3403
9cde0e7f 3404This is the C<true> SV. See C<PL_sv_no>. Always refer to this as C<&PL_sv_yes>.
cb1a09d0
AD
3405
3406=item THIS
3407
3408Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
3409This is always the proper type for the C++ object. See C<CLASS> and
5fb8527f 3410L<perlxs/"Using XS With C++">.
cb1a09d0
AD
3411
3412=item toLOWER
3413
3414Converts the specified character to lowercase.
3415
e89caa19 3416 int toLOWER (char c)
cb1a09d0
AD
3417
3418=item toUPPER
3419
3420Converts the specified character to uppercase.
3421
e89caa19 3422 int toUPPER (char c)
cb1a09d0
AD
3423
3424=item warn
3425
3426This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3427function the same way you use the C C<printf> function. See C<croak()>.
3428
3429=item XPUSHi
3430
189b2af5
GS
3431Push an integer onto the stack, extending the stack if necessary. Handles
3432'set' magic. See C<PUSHi>.
cb1a09d0
AD
3433
3434 XPUSHi(int d)
3435
3436=item XPUSHn
3437
189b2af5
GS
3438Push a double onto the stack, extending the stack if necessary. Handles 'set'
3439magic. See C<PUSHn>.
cb1a09d0
AD
3440
3441 XPUSHn(double d)
3442
3443=item XPUSHp
3444
3445Push a string onto the stack, extending the stack if necessary. The C<len>
189b2af5 3446indicates the length of the string. Handles 'set' magic. See C<PUSHp>.
cb1a09d0
AD
3447
3448 XPUSHp(char *c, int len)
3449
3450=item XPUSHs
3451
189b2af5
GS
3452Push an SV onto the stack, extending the stack if necessary. Does not
3453handle 'set' magic. See C<PUSHs>.
cb1a09d0
AD
3454
3455 XPUSHs(sv)
3456
e89caa19
GA
3457=item XPUSHu
3458
3459Push an unsigned integer onto the stack, extending the stack if
3460necessary. See C<PUSHu>.
3461
5fb8527f
PP
3462=item XS
3463
3464Macro to declare an XSUB and its C parameter list. This is handled by
3465C<xsubpp>.
3466
cb1a09d0
AD
3467=item XSRETURN
3468
3469Return from XSUB, indicating number of items on the stack. This is usually
3470handled by C<xsubpp>.
3471
ef50df4b 3472 XSRETURN(int x)
cb1a09d0
AD
3473
3474=item XSRETURN_EMPTY
3475
5fb8527f 3476Return an empty list from an XSUB immediately.
cb1a09d0
AD
3477
3478 XSRETURN_EMPTY;
3479
5fb8527f
PP
3480=item XSRETURN_IV
3481
3482Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3483
ef50df4b 3484 XSRETURN_IV(IV v)
5fb8527f 3485
cb1a09d0
AD
3486=item XSRETURN_NO
3487
9cde0e7f 3488Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
cb1a09d0
AD
3489
3490 XSRETURN_NO;
3491
5fb8527f
PP
3492=item XSRETURN_NV
3493
3494Return an double from an XSUB immediately. Uses C<XST_mNV>.
3495
ef50df4b 3496 XSRETURN_NV(NV v)
5fb8527f
PP
3497
3498=item XSRETURN_PV
3499
3500Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3501
ef50df4b 3502 XSRETURN_PV(char *v)
5fb8527f 3503
cb1a09d0
AD
3504=item XSRETURN_UNDEF
3505
9cde0e7f 3506Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
cb1a09d0
AD
3507
3508 XSRETURN_UNDEF;
3509
3510=item XSRETURN_YES
3511
9cde0e7f 3512Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
cb1a09d0
AD
3513
3514 XSRETURN_YES;
3515
5fb8527f
PP
3516=item XST_mIV
3517
3518Place an integer into the specified position C<i> on the stack. The value is
3519stored in a new mortal SV.
3520
ef50df4b 3521 XST_mIV( int i, IV v )
5fb8527f
PP
3522
3523=item XST_mNV
3524
3525Place a double into the specified position C<i> on the stack. The value is
3526stored in a new mortal SV.
3527
ef50df4b 3528 XST_mNV( int i, NV v )
5fb8527f
PP
3529
3530=item XST_mNO
3531
9cde0e7f 3532Place C<&PL_sv_no> into the specified position C<i> on the stack.
5fb8527f 3533
ef50df4b 3534 XST_mNO( int i )
5fb8527f
PP
3535
3536=item XST_mPV
3537
3538Place a copy of a string into the specified position C<i> on the stack. The
3539value is stored in a new mortal SV.
3540
ef50df4b 3541 XST_mPV( int i, char *v )
5fb8527f
PP
3542
3543=item XST_mUNDEF
3544
9cde0e7f 3545Place C<&PL_sv_undef> into the specified position C<i> on the stack.
5fb8527f 3546
ef50df4b 3547 XST_mUNDEF( int i )
5fb8527f
PP
3548
3549=item XST_mYES
3550
9cde0e7f 3551Place C<&PL_sv_yes> into the specified position C<i> on the stack.
5fb8527f 3552
ef50df4b 3553 XST_mYES( int i )
5fb8527f
PP
3554
3555=item XS_VERSION
3556
3557The version identifier for an XS module. This is usually handled
3558automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3559
3560=item XS_VERSION_BOOTCHECK
3561
3562Macro to verify that a PM module's $VERSION variable matches the XS module's
3563C<XS_VERSION> variable. This is usually handled automatically by
3564C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3565
cb1a09d0
AD
3566=item Zero
3567
3568The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
3569destination, C<n> is the number of items, and C<t> is the type.
3570
e89caa19 3571 void Zero( d, n, t )
cb1a09d0
AD
3572
3573=back
3574
9cecd9f2 3575=head1 AUTHORS
cb1a09d0 3576
9cecd9f2
GA
3577Until May 1997, this document was maintained by Jeff Okamoto
3578<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
cb1a09d0
AD
3579
3580With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3581Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
189b2af5
GS
3582Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3583Stephen McCamant, and Gurusamy Sarathy.
cb1a09d0 3584
9cecd9f2 3585API Listing originally by Dean Roehrich <roehrich@cray.com>.