This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
elide stray effluvium
[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
adc882cf
GS
266C<av_extend> function extends the array so that it contains at least C<key+1>
267elements. If C<key+1> is less than the currently allocated length of the array,
268then nothing 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
86058a2d
GS
1239All memory meant to be used with the Perl API functions should be manipulated
1240using the macros described in this section. The macros provide the necessary
1241transparency between differences in the actual malloc implementation that is
1242used within perl.
1243
1244It is suggested that you enable the version of malloc that is distributed
5f05dabc 1245with Perl. It keeps pools of various sizes of unallocated memory in
07fa94a1
JO
1246order to satisfy allocation requests more quickly. However, on some
1247platforms, it may cause spurious malloc or free errors.
d1b91892
AD
1248
1249 New(x, pointer, number, type);
1250 Newc(x, pointer, number, type, cast);
1251 Newz(x, pointer, number, type);
1252
07fa94a1 1253These three macros are used to initially allocate memory.
5f05dabc
PP
1254
1255The first argument C<x> was a "magic cookie" that was used to keep track
1256of who called the macro, to help when debugging memory problems. However,
07fa94a1
JO
1257the current code makes no use of this feature (most Perl developers now
1258use run-time memory checkers), so this argument can be any number.
5f05dabc
PP
1259
1260The second argument C<pointer> should be the name of a variable that will
1261point to the newly allocated memory.
d1b91892 1262
d1b91892
AD
1263The third and fourth arguments C<number> and C<type> specify how many of
1264the specified type of data structure should be allocated. The argument
1265C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
1266should be used if the C<pointer> argument is different from the C<type>
1267argument.
1268
1269Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
1270to zero out all the newly allocated memory.
1271
1272 Renew(pointer, number, type);
1273 Renewc(pointer, number, type, cast);
1274 Safefree(pointer)
1275
1276These three macros are used to change a memory buffer size or to free a
1277piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
1278match those of C<New> and C<Newc> with the exception of not needing the
1279"magic cookie" argument.
1280
1281 Move(source, dest, number, type);
1282 Copy(source, dest, number, type);
1283 Zero(dest, number, type);
1284
1285These three macros are used to move, copy, or zero out previously allocated
1286memory. The C<source> and C<dest> arguments point to the source and
1287destination starting points. Perl will move, copy, or zero out C<number>
1288instances of the size of the C<type> data structure (using the C<sizeof>
1289function).
a0d0e21e 1290
5f05dabc 1291=head2 PerlIO
ce3d39e2 1292
5f05dabc
PP
1293The most recent development releases of Perl has been experimenting with
1294removing Perl's dependency on the "normal" standard I/O suite and allowing
1295other stdio implementations to be used. This involves creating a new
1296abstraction layer that then calls whichever implementation of stdio Perl
68dc0745 1297was compiled with. All XSUBs should now use the functions in the PerlIO
5f05dabc
PP
1298abstraction layer and not make any assumptions about what kind of stdio
1299is being used.
1300
1301For a complete description of the PerlIO abstraction, consult L<perlapio>.
1302
8ebc5c01 1303=head2 Putting a C value on Perl stack
ce3d39e2
IZ
1304
1305A lot of opcodes (this is an elementary operation in the internal perl
1306stack machine) put an SV* on the stack. However, as an optimization
1307the corresponding SV is (usually) not recreated each time. The opcodes
1308reuse specially assigned SVs (I<target>s) which are (as a corollary)
1309not constantly freed/created.
1310
0a753a76 1311Each of the targets is created only once (but see
ce3d39e2
IZ
1312L<Scratchpads and recursion> below), and when an opcode needs to put
1313an integer, a double, or a string on stack, it just sets the
1314corresponding parts of its I<target> and puts the I<target> on stack.
1315
1316The macro to put this target on stack is C<PUSHTARG>, and it is
1317directly used in some opcodes, as well as indirectly in zillions of
1318others, which use it via C<(X)PUSH[pni]>.
1319
8ebc5c01 1320=head2 Scratchpads
ce3d39e2 1321
54310121 1322The question remains on when the SVs which are I<target>s for opcodes
5f05dabc
PP
1323are created. The answer is that they are created when the current unit --
1324a subroutine or a file (for opcodes for statements outside of
1325subroutines) -- is compiled. During this time a special anonymous Perl
ce3d39e2
IZ
1326array is created, which is called a scratchpad for the current
1327unit.
1328
54310121 1329A scratchpad keeps SVs which are lexicals for the current unit and are
ce3d39e2
IZ
1330targets for opcodes. One can deduce that an SV lives on a scratchpad
1331by looking on its flags: lexicals have C<SVs_PADMY> set, and
1332I<target>s have C<SVs_PADTMP> set.
1333
54310121
PP
1334The correspondence between OPs and I<target>s is not 1-to-1. Different
1335OPs in the compile tree of the unit can use the same target, if this
ce3d39e2
IZ
1336would not conflict with the expected life of the temporary.
1337
2ae324a7 1338=head2 Scratchpads and recursion
ce3d39e2
IZ
1339
1340In fact it is not 100% true that a compiled unit contains a pointer to
1341the scratchpad AV. In fact it contains a pointer to an AV of
1342(initially) one element, and this element is the scratchpad AV. Why do
1343we need an extra level of indirection?
1344
1345The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1346these can create several execution pointers going into the same
1347subroutine. For the subroutine-child not write over the temporaries
1348for the subroutine-parent (lifespan of which covers the call to the
1349child), the parent and the child should have different
1350scratchpads. (I<And> the lexicals should be separate anyway!)
1351
5f05dabc
PP
1352So each subroutine is born with an array of scratchpads (of length 1).
1353On each entry to the subroutine it is checked that the current
ce3d39e2
IZ
1354depth of the recursion is not more than the length of this array, and
1355if it is, new scratchpad is created and pushed into the array.
1356
1357The I<target>s on this scratchpad are C<undef>s, but they are already
1358marked with correct flags.
1359
0a753a76
PP
1360=head1 Compiled code
1361
1362=head2 Code tree
1363
1364Here we describe the internal form your code is converted to by
1365Perl. Start with a simple example:
1366
1367 $a = $b + $c;
1368
1369This is converted to a tree similar to this one:
1370
1371 assign-to
1372 / \
1373 + $a
1374 / \
1375 $b $c
1376
7b8d334a 1377(but slightly more complicated). This tree reflects the way Perl
0a753a76
PP
1378parsed your code, but has nothing to do with the execution order.
1379There is an additional "thread" going through the nodes of the tree
1380which shows the order of execution of the nodes. In our simplified
1381example above it looks like:
1382
1383 $b ---> $c ---> + ---> $a ---> assign-to
1384
1385But with the actual compile tree for C<$a = $b + $c> it is different:
1386some nodes I<optimized away>. As a corollary, though the actual tree
1387contains more nodes than our simplified example, the execution order
1388is the same as in our example.
1389
1390=head2 Examining the tree
1391
1392If you have your perl compiled for debugging (usually done with C<-D
1393optimize=-g> on C<Configure> command line), you may examine the
1394compiled tree by specifying C<-Dx> on the Perl command line. The
1395output takes several lines per node, and for C<$b+$c> it looks like
1396this:
1397
1398 5 TYPE = add ===> 6
1399 TARG = 1
1400 FLAGS = (SCALAR,KIDS)
1401 {
1402 TYPE = null ===> (4)
1403 (was rv2sv)
1404 FLAGS = (SCALAR,KIDS)
1405 {
1406 3 TYPE = gvsv ===> 4
1407 FLAGS = (SCALAR)
1408 GV = main::b
1409 }
1410 }
1411 {
1412 TYPE = null ===> (5)
1413 (was rv2sv)
1414 FLAGS = (SCALAR,KIDS)
1415 {
1416 4 TYPE = gvsv ===> 5
1417 FLAGS = (SCALAR)
1418 GV = main::c
1419 }
1420 }
1421
1422This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1423not optimized away (one per number in the left column). The immediate
1424children of the given node correspond to C<{}> pairs on the same level
1425of indentation, thus this listing corresponds to the tree:
1426
1427 add
1428 / \
1429 null null
1430 | |
1431 gvsv gvsv
1432
1433The execution order is indicated by C<===E<gt>> marks, thus it is C<3
14344 5 6> (node C<6> is not included into above listing), i.e.,
1435C<gvsv gvsv add whatever>.
1436
1437=head2 Compile pass 1: check routines
1438
1439The tree is created by the I<pseudo-compiler> while yacc code feeds it
1440the constructions it recognizes. Since yacc works bottom-up, so does
1441the first pass of perl compilation.
1442
1443What makes this pass interesting for perl developers is that some
1444optimization may be performed on this pass. This is optimization by
1445so-called I<check routines>. The correspondence between node names
1446and corresponding check routines is described in F<opcode.pl> (do not
1447forget to run C<make regen_headers> if you modify this file).
1448
1449A check routine is called when the node is fully constructed except
7b8d334a 1450for the execution-order thread. Since at this time there are no
0a753a76
PP
1451back-links to the currently constructed node, one can do most any
1452operation to the top-level node, including freeing it and/or creating
1453new nodes above/below it.
1454
1455The check routine returns the node which should be inserted into the
1456tree (if the top-level node was not modified, check routine returns
1457its argument).
1458
1459By convention, check routines have names C<ck_*>. They are usually
1460called from C<new*OP> subroutines (or C<convert>) (which in turn are
1461called from F<perly.y>).
1462
1463=head2 Compile pass 1a: constant folding
1464
1465Immediately after the check routine is called the returned node is
1466checked for being compile-time executable. If it is (the value is
1467judged to be constant) it is immediately executed, and a I<constant>
1468node with the "return value" of the corresponding subtree is
1469substituted instead. The subtree is deleted.
1470
1471If constant folding was not performed, the execution-order thread is
1472created.
1473
1474=head2 Compile pass 2: context propagation
1475
1476When a context for a part of compile tree is known, it is propagated
a3cb178b 1477down through the tree. At this time the context can have 5 values
0a753a76
PP
1478(instead of 2 for runtime context): void, boolean, scalar, list, and
1479lvalue. In contrast with the pass 1 this pass is processed from top
1480to bottom: a node's context determines the context for its children.
1481
1482Additional context-dependent optimizations are performed at this time.
1483Since at this moment the compile tree contains back-references (via
1484"thread" pointers), nodes cannot be free()d now. To allow
1485optimized-away nodes at this stage, such nodes are null()ified instead
1486of free()ing (i.e. their type is changed to OP_NULL).
1487
1488=head2 Compile pass 3: peephole optimization
1489
1490After the compile tree for a subroutine (or for an C<eval> or a file)
1491is created, an additional pass over the code is performed. This pass
1492is neither top-down or bottom-up, but in the execution order (with
7b8d334a 1493additional complications for conditionals). These optimizations are
0a753a76
PP
1494done in the subroutine peep(). Optimizations performed at this stage
1495are subject to the same restrictions as in the pass 2.
1496
1497=head1 API LISTING
a0d0e21e 1498
cb1a09d0
AD
1499This is a listing of functions, macros, flags, and variables that may be
1500useful to extension writers or that may be found while reading other
1501extensions.
9cde0e7f
GS
1502
1503Note that all Perl API global variables must be referenced with the C<PL_>
1504prefix. Some macros are provided for compatibility with the older,
1505unadorned names, but this support will be removed in a future release.
1506
1507It is strongly recommended that all Perl API functions that don't begin
1508with C<perl> be referenced with an explicit C<Perl_> prefix.
1509
e89caa19 1510The sort order of the listing is case insensitive, with any
b5a41e52 1511occurrences of '_' ignored for the purpose of sorting.
a0d0e21e 1512
cb1a09d0 1513=over 8
a0d0e21e 1514
cb1a09d0
AD
1515=item av_clear
1516
0146554f
GA
1517Clears an array, making it empty. Does not free the memory used by the
1518array itself.
cb1a09d0 1519
ef50df4b 1520 void av_clear (AV* ar)
cb1a09d0
AD
1521
1522=item av_extend
1523
1524Pre-extend an array. The C<key> is the index to which the array should be
1525extended.
1526
ef50df4b 1527 void av_extend (AV* ar, I32 key)
cb1a09d0
AD
1528
1529=item av_fetch
1530
1531Returns the SV at the specified index in the array. The C<key> is the
1532index. If C<lval> is set then the fetch will be part of a store. Check
1533that the return value is non-null before dereferencing it to a C<SV*>.
1534
04343c6d
GS
1535See L<Understanding the Magic of Tied Hashes and Arrays> for more
1536information on how to use this function on tied arrays.
1537
ef50df4b 1538 SV** av_fetch (AV* ar, I32 key, I32 lval)
cb1a09d0 1539
e89caa19
GA
1540=item AvFILL
1541
95906810 1542Same as C<av_len()>. Deprecated, use C<av_len()> instead.
e89caa19 1543
cb1a09d0
AD
1544=item av_len
1545
1546Returns the highest index in the array. Returns -1 if the array is empty.
1547
ef50df4b 1548 I32 av_len (AV* ar)
cb1a09d0
AD
1549
1550=item av_make
1551
5fb8527f
PP
1552Creates a new AV and populates it with a list of SVs. The SVs are copied
1553into the array, so they may be freed after the call to av_make. The new AV
5f05dabc 1554will have a reference count of 1.
cb1a09d0 1555
ef50df4b 1556 AV* av_make (I32 size, SV** svp)
cb1a09d0
AD
1557
1558=item av_pop
1559
9cde0e7f 1560Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is
cb1a09d0
AD
1561empty.
1562
ef50df4b 1563 SV* av_pop (AV* ar)
cb1a09d0
AD
1564
1565=item av_push
1566
5fb8527f
PP
1567Pushes an SV onto the end of the array. The array will grow automatically
1568to accommodate the addition.
cb1a09d0 1569
ef50df4b 1570 void av_push (AV* ar, SV* val)
cb1a09d0
AD
1571
1572=item av_shift
1573
1574Shifts an SV off the beginning of the array.
1575
ef50df4b 1576 SV* av_shift (AV* ar)
cb1a09d0
AD
1577
1578=item av_store
1579
1580Stores an SV in an array. The array index is specified as C<key>. The
04343c6d
GS
1581return value will be NULL if the operation failed or if the value did not
1582need to be actually stored within the array (as in the case of tied arrays).
1583Otherwise it can be dereferenced to get the original C<SV*>. Note that the
1584caller is responsible for suitably incrementing the reference count of C<val>
1585before the call, and decrementing it if the function returned NULL.
1586
1587See L<Understanding the Magic of Tied Hashes and Arrays> for more
1588information on how to use this function on tied arrays.
cb1a09d0 1589
ef50df4b 1590 SV** av_store (AV* ar, I32 key, SV* val)
cb1a09d0
AD
1591
1592=item av_undef
1593
0146554f 1594Undefines the array. Frees the memory used by the array itself.
cb1a09d0 1595
ef50df4b 1596 void av_undef (AV* ar)
cb1a09d0
AD
1597
1598=item av_unshift
1599
0146554f
GA
1600Unshift the given number of C<undef> values onto the beginning of the
1601array. The array will grow automatically to accommodate the addition.
1602You must then use C<av_store> to assign values to these new elements.
cb1a09d0 1603
ef50df4b 1604 void av_unshift (AV* ar, I32 num)
cb1a09d0
AD
1605
1606=item CLASS
1607
1608Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
5fb8527f
PP
1609constructor. This is always a C<char*>. See C<THIS> and
1610L<perlxs/"Using XS With C++">.
cb1a09d0
AD
1611
1612=item Copy
1613
1614The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1615source, C<d> is the destination, C<n> is the number of items, and C<t> is
0146554f 1616the type. May fail on overlapping copies. See also C<Move>.
cb1a09d0 1617
e89caa19 1618 void Copy( s, d, n, t )
cb1a09d0
AD
1619
1620=item croak
1621
1622This is the XSUB-writer's interface to Perl's C<die> function. Use this
1623function the same way you use the C C<printf> function. See C<warn>.
1624
1625=item CvSTASH
1626
1627Returns the stash of the CV.
1628
e89caa19 1629 HV* CvSTASH( SV* sv )
cb1a09d0 1630
9cde0e7f 1631=item PL_DBsingle
cb1a09d0
AD
1632
1633When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1634boolean which indicates whether subs are being single-stepped.
5fb8527f 1635Single-stepping is automatically turned on after every step. This is the C
9cde0e7f 1636variable which corresponds to Perl's $DB::single variable. See C<PL_DBsub>.
cb1a09d0 1637
9cde0e7f 1638=item PL_DBsub
cb1a09d0
AD
1639
1640When Perl is run in debugging mode, with the B<-d> switch, this GV contains
5fb8527f 1641the SV which holds the name of the sub being debugged. This is the C
9cde0e7f 1642variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>.
cb1a09d0
AD
1643The sub name can be found by
1644
2d8e6c8d 1645 SvPV( GvSV( PL_DBsub ), len )
cb1a09d0 1646
9cde0e7f 1647=item PL_DBtrace
5fb8527f
PP
1648
1649Trace variable used when Perl is run in debugging mode, with the B<-d>
1650switch. This is the C variable which corresponds to Perl's $DB::trace
9cde0e7f 1651variable. See C<PL_DBsingle>.
5fb8527f 1652
cb1a09d0
AD
1653=item dMARK
1654
5fb8527f
PP
1655Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1656C<dORIGMARK>.
cb1a09d0
AD
1657
1658=item dORIGMARK
1659
1660Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1661
9cde0e7f 1662=item PL_dowarn
5fb8527f
PP
1663
1664The C variable which corresponds to Perl's $^W warning variable.
1665
cb1a09d0
AD
1666=item dSP
1667
924508f0
GS
1668Declares a local copy of perl's stack pointer for the XSUB, available via
1669the C<SP> macro. See C<SP>.
cb1a09d0
AD
1670
1671=item dXSARGS
1672
1673Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1674usually handled automatically by C<xsubpp>. Declares the C<items> variable
1675to indicate the number of items on the stack.
1676
5fb8527f
PP
1677=item dXSI32
1678
1679Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1680handled automatically by C<xsubpp>.
1681
491527d0
GS
1682=item do_binmode
1683
1684Switches filehandle to binmode. C<iotype> is what C<IoTYPE(io)> would
1685contain.
1686
1687 do_binmode(fp, iotype, TRUE);
1688
cb1a09d0
AD
1689=item ENTER
1690
1691Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1692
1693 ENTER;
1694
1695=item EXTEND
1696
1697Used to extend the argument stack for an XSUB's return values.
1698
ef50df4b 1699 EXTEND( sp, int x )
cb1a09d0 1700
e89caa19
GA
1701=item fbm_compile
1702
1703Analyses the string in order to make fast searches on it using fbm_instr() --
1704the Boyer-Moore algorithm.
1705
411d5715 1706 void fbm_compile(SV* sv, U32 flags)
e89caa19
GA
1707
1708=item fbm_instr
1709
1710Returns the location of the SV in the string delimited by C<str> and
1711C<strend>. It returns C<Nullch> if the string can't be found. The
1712C<sv> does not have to be fbm_compiled, but the search will not be as
1713fast then.
1714
411d5715 1715 char* fbm_instr(char *str, char *strend, SV *sv, U32 flags)
e89caa19 1716
cb1a09d0
AD
1717=item FREETMPS
1718
1719Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1720L<perlcall>.
1721
1722 FREETMPS;
1723
1724=item G_ARRAY
1725
54310121 1726Used to indicate array context. See C<GIMME_V>, C<GIMME> and L<perlcall>.
cb1a09d0
AD
1727
1728=item G_DISCARD
1729
1730Indicates that arguments returned from a callback should be discarded. See
1731L<perlcall>.
1732
1733=item G_EVAL
1734
1735Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1736
1737=item GIMME
1738
54310121
PP
1739A backward-compatible version of C<GIMME_V> which can only return
1740C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
1741
1742=item GIMME_V
1743
1744The XSUB-writer's equivalent to Perl's C<wantarray>. Returns
1745C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
1746context, respectively.
cb1a09d0
AD
1747
1748=item G_NOARGS
1749
1750Indicates that no arguments are being sent to a callback. See L<perlcall>.
1751
1752=item G_SCALAR
1753
54310121
PP
1754Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>.
1755
faed5253
JO
1756=item gv_fetchmeth
1757
1758Returns the glob with the given C<name> and a defined subroutine or
9607fc9c 1759C<NULL>. The glob lives in the given C<stash>, or in the stashes
f86cebdf 1760accessible via @ISA and @UNIVERSAL.
faed5253 1761
9607fc9c 1762The argument C<level> should be either 0 or -1. If C<level==0>, as a
0a753a76
PP
1763side-effect creates a glob with the given C<name> in the given
1764C<stash> which in the case of success contains an alias for the
1765subroutine, and sets up caching info for this glob. Similarly for all
1766the searched stashes.
1767
9607fc9c
PP
1768This function grants C<"SUPER"> token as a postfix of the stash name.
1769
0a753a76
PP
1770The GV returned from C<gv_fetchmeth> may be a method cache entry,
1771which is not visible to Perl code. So when calling C<perl_call_sv>,
1772you should not use the GV directly; instead, you should use the
1773method's CV, which can be obtained from the GV with the C<GvCV> macro.
faed5253 1774
ef50df4b 1775 GV* gv_fetchmeth (HV* stash, char* name, STRLEN len, I32 level)
faed5253
JO
1776
1777=item gv_fetchmethod
1778
dc848c6f
PP
1779=item gv_fetchmethod_autoload
1780
faed5253 1781Returns the glob which contains the subroutine to call to invoke the
dc848c6f
PP
1782method on the C<stash>. In fact in the presense of autoloading this may
1783be the glob for "AUTOLOAD". In this case the corresponding variable
faed5253
JO
1784$AUTOLOAD is already setup.
1785
dc848c6f
PP
1786The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
1787lookup is performed if the given method is not present: non-zero means
1788yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling
1789C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
1790non-zero C<autoload> parameter.
1791
1792These functions grant C<"SUPER"> token as a prefix of the method name.
1793
1794Note that if you want to keep the returned glob for a long time, you
1795need to check for it being "AUTOLOAD", since at the later time the call
faed5253
JO
1796may load a different subroutine due to $AUTOLOAD changing its value.
1797Use the glob created via a side effect to do this.
1798
dc848c6f
PP
1799These functions have the same side-effects and as C<gv_fetchmeth> with
1800C<level==0>. C<name> should be writable if contains C<':'> or C<'\''>.
0a753a76 1801The warning against passing the GV returned by C<gv_fetchmeth> to
dc848c6f 1802C<perl_call_sv> apply equally to these functions.
faed5253 1803
ef50df4b
GS
1804 GV* gv_fetchmethod (HV* stash, char* name)
1805 GV* gv_fetchmethod_autoload (HV* stash, char* name, I32 autoload)
faed5253 1806
e89caa19
GA
1807=item G_VOID
1808
1809Used to indicate void context. See C<GIMME_V> and L<perlcall>.
1810
cb1a09d0
AD
1811=item gv_stashpv
1812
1813Returns a pointer to the stash for a specified package. If C<create> is set
1814then the package will be created if it does not already exist. If C<create>
1815is not set and the package does not exist then NULL is returned.
1816
ef50df4b 1817 HV* gv_stashpv (char* name, I32 create)
cb1a09d0
AD
1818
1819=item gv_stashsv
1820
1821Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1822
ef50df4b 1823 HV* gv_stashsv (SV* sv, I32 create)
cb1a09d0 1824
e5581bf4 1825=item GvSV
cb1a09d0 1826
e5581bf4 1827Return the SV from the GV.
44a8e56a 1828
1e422769
PP
1829=item HEf_SVKEY
1830
1831This flag, used in the length slot of hash entries and magic
1832structures, specifies the structure contains a C<SV*> pointer where a
1833C<char*> pointer is to be expected. (For information only--not to be used).
1834
1e422769
PP
1835=item HeHASH
1836
e89caa19 1837Returns the computed hash stored in the hash entry.
1e422769 1838
e89caa19 1839 U32 HeHASH(HE* he)
1e422769
PP
1840
1841=item HeKEY
1842
1843Returns the actual pointer stored in the key slot of the hash entry.
1844The pointer may be either C<char*> or C<SV*>, depending on the value of
1845C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros
1846are usually preferable for finding the value of a key.
1847
e89caa19 1848 char* HeKEY(HE* he)
1e422769
PP
1849
1850=item HeKLEN
1851
1852If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1853holds an C<SV*> key. Otherwise, holds the actual length of the key.
1854Can be assigned to. The C<HePV()> macro is usually preferable for finding
1855key lengths.
1856
e89caa19 1857 int HeKLEN(HE* he)
1e422769
PP
1858
1859=item HePV
1860
1861Returns the key slot of the hash entry as a C<char*> value, doing any
1862necessary dereferencing of possibly C<SV*> keys. The length of
1863the string is placed in C<len> (this is a macro, so do I<not> use
1864C<&len>). If you do not care about what the length of the key is,
2d8e6c8d
GS
1865you may use the global variable C<PL_na>, though this is rather less
1866efficient than using a local variable. Remember though, that hash
1e422769
PP
1867keys in perl are free to contain embedded nulls, so using C<strlen()>
1868or similar is not a good way to find the length of hash keys.
1869This is very similar to the C<SvPV()> macro described elsewhere in
1870this document.
1871
e89caa19 1872 char* HePV(HE* he, STRLEN len)
1e422769
PP
1873
1874=item HeSVKEY
1875
1876Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
1877does not contain an C<SV*> key.
1878
1879 HeSVKEY(HE* he)
1880
1881=item HeSVKEY_force
1882
1883Returns the key as an C<SV*>. Will create and return a temporary
1884mortal C<SV*> if the hash entry contains only a C<char*> key.
1885
1886 HeSVKEY_force(HE* he)
1887
1888=item HeSVKEY_set
1889
1890Sets the key to a given C<SV*>, taking care to set the appropriate flags
1891to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
1892
1893 HeSVKEY_set(HE* he, SV* sv)
1894
1895=item HeVAL
1896
1897Returns the value slot (type C<SV*>) stored in the hash entry.
1898
1899 HeVAL(HE* he)
1900
cb1a09d0
AD
1901=item hv_clear
1902
1903Clears a hash, making it empty.
1904
ef50df4b 1905 void hv_clear (HV* tb)
cb1a09d0
AD
1906
1907=item hv_delete
1908
1909Deletes a key/value pair in the hash. The value SV is removed from the hash
5fb8527f 1910and returned to the caller. The C<klen> is the length of the key. The
04343c6d 1911C<flags> value will normally be zero; if set to G_DISCARD then NULL will be
cb1a09d0
AD
1912returned.
1913
ef50df4b 1914 SV* hv_delete (HV* tb, char* key, U32 klen, I32 flags)
cb1a09d0 1915
1e422769
PP
1916=item hv_delete_ent
1917
1918Deletes a key/value pair in the hash. The value SV is removed from the hash
1919and returned to the caller. The C<flags> value will normally be zero; if set
04343c6d 1920to G_DISCARD then NULL will be returned. C<hash> can be a valid precomputed
1e422769
PP
1921hash value, or 0 to ask for it to be computed.
1922
ef50df4b 1923 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash)
1e422769 1924
cb1a09d0
AD
1925=item hv_exists
1926
1927Returns a boolean indicating whether the specified hash key exists. The
5fb8527f 1928C<klen> is the length of the key.
cb1a09d0 1929
ef50df4b 1930 bool hv_exists (HV* tb, char* key, U32 klen)
cb1a09d0 1931
1e422769
PP
1932=item hv_exists_ent
1933
1934Returns a boolean indicating whether the specified hash key exists. C<hash>
54310121 1935can be a valid precomputed hash value, or 0 to ask for it to be computed.
1e422769 1936
ef50df4b 1937 bool hv_exists_ent (HV* tb, SV* key, U32 hash)
1e422769 1938
cb1a09d0
AD
1939=item hv_fetch
1940
1941Returns the SV which corresponds to the specified key in the hash. The
5fb8527f 1942C<klen> is the length of the key. If C<lval> is set then the fetch will be
cb1a09d0
AD
1943part of a store. Check that the return value is non-null before
1944dereferencing it to a C<SV*>.
1945
04343c6d
GS
1946See L<Understanding the Magic of Tied Hashes and Arrays> for more
1947information on how to use this function on tied hashes.
1948
ef50df4b 1949 SV** hv_fetch (HV* tb, char* key, U32 klen, I32 lval)
cb1a09d0 1950
1e422769
PP
1951=item hv_fetch_ent
1952
1953Returns the hash entry which corresponds to the specified key in the hash.
54310121 1954C<hash> must be a valid precomputed hash number for the given C<key>, or
1e422769
PP
19550 if you want the function to compute it. IF C<lval> is set then the
1956fetch will be part of a store. Make sure the return value is non-null
1957before accessing it. The return value when C<tb> is a tied hash
1958is a pointer to a static location, so be sure to make a copy of the
1959structure if you need to store it somewhere.
1960
04343c6d
GS
1961See L<Understanding the Magic of Tied Hashes and Arrays> for more
1962information on how to use this function on tied hashes.
1963
ef50df4b 1964 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash)
1e422769 1965
cb1a09d0
AD
1966=item hv_iterinit
1967
1968Prepares a starting point to traverse a hash table.
1969
ef50df4b 1970 I32 hv_iterinit (HV* tb)
cb1a09d0 1971
c6601927
SI
1972Returns the number of keys in the hash (i.e. the same as C<HvKEYS(tb)>).
1973The return value is currently only meaningful for hashes without tie
1974magic.
1975
1976NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number
1977of hash buckets that happen to be in use. If you still need that
1978esoteric value, you can get it through the macro C<HvFILL(tb)>.
fb73857a 1979
cb1a09d0
AD
1980=item hv_iterkey
1981
1982Returns the key from the current position of the hash iterator. See
1983C<hv_iterinit>.
1984
ef50df4b 1985 char* hv_iterkey (HE* entry, I32* retlen)
cb1a09d0 1986
1e422769 1987=item hv_iterkeysv
3fe9a6f1 1988
1e422769
PP
1989Returns the key as an C<SV*> from the current position of the hash
1990iterator. The return value will always be a mortal copy of the
1991key. Also see C<hv_iterinit>.
1992
ef50df4b 1993 SV* hv_iterkeysv (HE* entry)
1e422769 1994
cb1a09d0
AD
1995=item hv_iternext
1996
1997Returns entries from a hash iterator. See C<hv_iterinit>.
1998
ef50df4b 1999 HE* hv_iternext (HV* tb)
cb1a09d0
AD
2000
2001=item hv_iternextsv
2002
2003Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
2004operation.
2005
e89caa19 2006 SV* hv_iternextsv (HV* hv, char** key, I32* retlen)
cb1a09d0
AD
2007
2008=item hv_iterval
2009
2010Returns the value from the current position of the hash iterator. See
2011C<hv_iterkey>.
2012
ef50df4b 2013 SV* hv_iterval (HV* tb, HE* entry)
cb1a09d0
AD
2014
2015=item hv_magic
2016
2017Adds magic to a hash. See C<sv_magic>.
2018
ef50df4b 2019 void hv_magic (HV* hv, GV* gv, int how)
cb1a09d0
AD
2020
2021=item HvNAME
2022
2023Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
2024
e89caa19 2025 char* HvNAME (HV* stash)
cb1a09d0
AD
2026
2027=item hv_store
2028
2029Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
54310121 2030the length of the key. The C<hash> parameter is the precomputed hash
cb1a09d0 2031value; if it is zero then Perl will compute it. The return value will be
04343c6d
GS
2032NULL if the operation failed or if the value did not need to be actually
2033stored within the hash (as in the case of tied hashes). Otherwise it can
2034be dereferenced to get the original C<SV*>. Note that the caller is
2035responsible for suitably incrementing the reference count of C<val>
2036before the call, and decrementing it if the function returned NULL.
2037
2038See L<Understanding the Magic of Tied Hashes and Arrays> for more
2039information on how to use this function on tied hashes.
cb1a09d0 2040
ef50df4b 2041 SV** hv_store (HV* tb, char* key, U32 klen, SV* val, U32 hash)
cb1a09d0 2042
1e422769
PP
2043=item hv_store_ent
2044
2045Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
54310121 2046parameter is the precomputed hash value; if it is zero then Perl will
1e422769 2047compute it. The return value is the new hash entry so created. It will be
04343c6d
GS
2048NULL if the operation failed or if the value did not need to be actually
2049stored within the hash (as in the case of tied hashes). Otherwise the
2050contents of the return value can be accessed using the C<He???> macros
2051described here. Note that the caller is responsible for suitably
2052incrementing the reference count of C<val> before the call, and decrementing
2053it if the function returned NULL.
2054
2055See L<Understanding the Magic of Tied Hashes and Arrays> for more
2056information on how to use this function on tied hashes.
1e422769 2057
ef50df4b 2058 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash)
1e422769 2059
cb1a09d0
AD
2060=item hv_undef
2061
2062Undefines the hash.
2063
ef50df4b 2064 void hv_undef (HV* tb)
cb1a09d0
AD
2065
2066=item isALNUM
2067
2068Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
5f05dabc 2069character or digit.
cb1a09d0 2070
e89caa19 2071 int isALNUM (char c)
cb1a09d0
AD
2072
2073=item isALPHA
2074
5fb8527f 2075Returns a boolean indicating whether the C C<char> is an ascii alphabetic
cb1a09d0
AD
2076character.
2077
e89caa19 2078 int isALPHA (char c)
cb1a09d0
AD
2079
2080=item isDIGIT
2081
2082Returns a boolean indicating whether the C C<char> is an ascii digit.
2083
e89caa19 2084 int isDIGIT (char c)
cb1a09d0
AD
2085
2086=item isLOWER
2087
2088Returns a boolean indicating whether the C C<char> is a lowercase character.
2089
e89caa19 2090 int isLOWER (char c)
cb1a09d0
AD
2091
2092=item isSPACE
2093
2094Returns a boolean indicating whether the C C<char> is whitespace.
2095
e89caa19 2096 int isSPACE (char c)
cb1a09d0
AD
2097
2098=item isUPPER
2099
2100Returns a boolean indicating whether the C C<char> is an uppercase character.
2101
e89caa19 2102 int isUPPER (char c)
cb1a09d0
AD
2103
2104=item items
2105
2106Variable which is setup by C<xsubpp> to indicate the number of items on the
5fb8527f
PP
2107stack. See L<perlxs/"Variable-length Parameter Lists">.
2108
2109=item ix
2110
2111Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
2112was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
cb1a09d0
AD
2113
2114=item LEAVE
2115
2116Closing bracket on a callback. See C<ENTER> and L<perlcall>.
2117
2118 LEAVE;
2119
e89caa19
GA
2120=item looks_like_number
2121
2122Test if an the content of an SV looks like a number (or is a number).
2123
2124 int looks_like_number(SV*)
2125
2126
cb1a09d0
AD
2127=item MARK
2128
5fb8527f 2129Stack marker variable for the XSUB. See C<dMARK>.
cb1a09d0
AD
2130
2131=item mg_clear
2132
2133Clear something magical that the SV represents. See C<sv_magic>.
2134
ef50df4b 2135 int mg_clear (SV* sv)
cb1a09d0
AD
2136
2137=item mg_copy
2138
2139Copies the magic from one SV to another. See C<sv_magic>.
2140
ef50df4b 2141 int mg_copy (SV *, SV *, char *, STRLEN)
cb1a09d0
AD
2142
2143=item mg_find
2144
2145Finds the magic pointer for type matching the SV. See C<sv_magic>.
2146
ef50df4b 2147 MAGIC* mg_find (SV* sv, int type)
cb1a09d0
AD
2148
2149=item mg_free
2150
2151Free any magic storage used by the SV. See C<sv_magic>.
2152
ef50df4b 2153 int mg_free (SV* sv)
cb1a09d0
AD
2154
2155=item mg_get
2156
2157Do magic after a value is retrieved from the SV. See C<sv_magic>.
2158
ef50df4b 2159 int mg_get (SV* sv)
cb1a09d0
AD
2160
2161=item mg_len
2162
2163Report on the SV's length. See C<sv_magic>.
2164
ef50df4b 2165 U32 mg_len (SV* sv)
cb1a09d0
AD
2166
2167=item mg_magical
2168
2169Turns on the magical status of an SV. See C<sv_magic>.
2170
ef50df4b 2171 void mg_magical (SV* sv)
cb1a09d0
AD
2172
2173=item mg_set
2174
2175Do magic after a value is assigned to the SV. See C<sv_magic>.
2176
ef50df4b 2177 int mg_set (SV* sv)
cb1a09d0 2178
b0fffe30
JP
2179=item modglobal
2180
2181C<modglobal> is a general purpose, interpreter global HV for use by
db696efe
GS
2182extensions that need to keep information on a per-interpreter basis.
2183In a pinch, it can also be used as a symbol table for extensions
2184to share data among each other. It is a good idea to use keys
2185prefixed by the package name of the extension that owns the data.
b0fffe30 2186
cb1a09d0
AD
2187=item Move
2188
2189The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
2190source, C<d> is the destination, C<n> is the number of items, and C<t> is
0146554f 2191the type. Can do overlapping moves. See also C<Copy>.
cb1a09d0 2192
e89caa19 2193 void Move( s, d, n, t )
cb1a09d0 2194
9cde0e7f 2195=item PL_na
cb1a09d0 2196
2d8e6c8d
GS
2197A convenience variable which is typically used with C<SvPV> when one doesn't
2198care about the length of the string. It is usually more efficient to
2199declare a local variable and use that instead.
cb1a09d0
AD
2200
2201=item New
2202
2203The XSUB-writer's interface to the C C<malloc> function.
2204
e89caa19 2205 void* New( x, void *ptr, int size, type )
cb1a09d0
AD
2206
2207=item newAV
2208
5f05dabc 2209Creates a new AV. The reference count is set to 1.
cb1a09d0 2210
ef50df4b 2211 AV* newAV (void)
cb1a09d0 2212
e89caa19
GA
2213=item Newc
2214
2215The XSUB-writer's interface to the C C<malloc> function, with cast.
2216
2217 void* Newc( x, void *ptr, int size, type, cast )
2218
5476c433
JD
2219=item newCONSTSUB
2220
2221Creates a constant sub equivalent to Perl C<sub FOO () { 123 }>
2222which is eligible for inlining at compile-time.
2223
2224 void newCONSTSUB(HV* stash, char* name, SV* sv)
2225
cb1a09d0
AD
2226=item newHV
2227
5f05dabc 2228Creates a new HV. The reference count is set to 1.
cb1a09d0 2229
ef50df4b 2230 HV* newHV (void)
cb1a09d0 2231
5f05dabc 2232=item newRV_inc
cb1a09d0 2233
5f05dabc 2234Creates an RV wrapper for an SV. The reference count for the original SV is
cb1a09d0
AD
2235incremented.
2236
ef50df4b 2237 SV* newRV_inc (SV* ref)
5f05dabc
PP
2238
2239For historical reasons, "newRV" is a synonym for "newRV_inc".
2240
2241=item newRV_noinc
2242
2243Creates an RV wrapper for an SV. The reference count for the original
2244SV is B<not> incremented.
2245
ef50df4b 2246 SV* newRV_noinc (SV* ref)
cb1a09d0 2247
8c52afec 2248=item NEWSV
cb1a09d0 2249
e89caa19
GA
2250Creates a new SV. A non-zero C<len> parameter indicates the number of
2251bytes of preallocated string space the SV should have. An extra byte
2252for a tailing NUL is also reserved. (SvPOK is not set for the SV even
2253if string space is allocated.) The reference count for the new SV is
2254set to 1. C<id> is an integer id between 0 and 1299 (used to identify
2255leaks).
cb1a09d0 2256
ef50df4b 2257 SV* NEWSV (int id, STRLEN len)
cb1a09d0
AD
2258
2259=item newSViv
2260
07fa94a1
JO
2261Creates a new SV and copies an integer into it. The reference count for the
2262SV is set to 1.
cb1a09d0 2263
ef50df4b 2264 SV* newSViv (IV i)
cb1a09d0
AD
2265
2266=item newSVnv
2267
07fa94a1
JO
2268Creates a new SV and copies a double into it. The reference count for the
2269SV is set to 1.
cb1a09d0 2270
ef50df4b 2271 SV* newSVnv (NV i)
cb1a09d0
AD
2272
2273=item newSVpv
2274
07fa94a1
JO
2275Creates a new SV and copies a string into it. The reference count for the
2276SV is set to 1. If C<len> is zero then Perl will compute the length.
cb1a09d0 2277
ef50df4b 2278 SV* newSVpv (char* s, STRLEN len)
cb1a09d0 2279
e89caa19
GA
2280=item newSVpvf
2281
2282Creates a new SV an initialize it with the string formatted like
2283C<sprintf>.
2284
2285 SV* newSVpvf(const char* pat, ...);
2286
9da1e3b5
MUN
2287=item newSVpvn
2288
2289Creates a new SV and copies a string into it. The reference count for the
2290SV is set to 1. If C<len> is zero then Perl will create a zero length
2291string.
2292
ef50df4b 2293 SV* newSVpvn (char* s, STRLEN len)
9da1e3b5 2294
cb1a09d0
AD
2295=item newSVrv
2296
2297Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5fb8527f 2298it will be upgraded to one. If C<classname> is non-null then the new SV will
cb1a09d0 2299be blessed in the specified package. The new SV is returned and its
5f05dabc 2300reference count is 1.
8ebc5c01 2301
ef50df4b 2302 SV* newSVrv (SV* rv, char* classname)
cb1a09d0
AD
2303
2304=item newSVsv
2305
5fb8527f 2306Creates a new SV which is an exact duplicate of the original SV.
cb1a09d0 2307
ef50df4b 2308 SV* newSVsv (SV* old)
cb1a09d0
AD
2309
2310=item newXS
2311
2312Used by C<xsubpp> to hook up XSUBs as Perl subs.
2313
2314=item newXSproto
2315
2316Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
2317the subs.
2318
e89caa19
GA
2319=item Newz
2320
2321The XSUB-writer's interface to the C C<malloc> function. The allocated
2322memory is zeroed with C<memzero>.
2323
2324 void* Newz( x, void *ptr, int size, type )
2325
cb1a09d0
AD
2326=item Nullav
2327
2328Null AV pointer.
2329
2330=item Nullch
2331
2332Null character pointer.
2333
2334=item Nullcv
2335
2336Null CV pointer.
2337
2338=item Nullhv
2339
2340Null HV pointer.
2341
2342=item Nullsv
2343
2344Null SV pointer.
2345
2346=item ORIGMARK
2347
2348The original stack mark for the XSUB. See C<dORIGMARK>.
2349
2350=item perl_alloc
2351
2352Allocates a new Perl interpreter. See L<perlembed>.
2353
2354=item perl_call_argv
2355
2356Performs a callback to the specified Perl sub. See L<perlcall>.
2357
ef50df4b 2358 I32 perl_call_argv (char* subname, I32 flags, char** argv)
cb1a09d0
AD
2359
2360=item perl_call_method
2361
2362Performs a callback to the specified Perl method. The blessed object must
2363be on the stack. See L<perlcall>.
2364
ef50df4b 2365 I32 perl_call_method (char* methname, I32 flags)
cb1a09d0
AD
2366
2367=item perl_call_pv
2368
2369Performs a callback to the specified Perl sub. See L<perlcall>.
2370
ef50df4b 2371 I32 perl_call_pv (char* subname, I32 flags)
cb1a09d0
AD
2372
2373=item perl_call_sv
2374
2375Performs a callback to the Perl sub whose name is in the SV. See
2376L<perlcall>.
2377
ef50df4b 2378 I32 perl_call_sv (SV* sv, I32 flags)
cb1a09d0
AD
2379
2380=item perl_construct
2381
2382Initializes a new Perl interpreter. See L<perlembed>.
2383
2384=item perl_destruct
2385
2386Shuts down a Perl interpreter. See L<perlembed>.
2387
2388=item perl_eval_sv
2389
2390Tells Perl to C<eval> the string in the SV.
2391
ef50df4b 2392 I32 perl_eval_sv (SV* sv, I32 flags)
cb1a09d0 2393
137443ea
PP
2394=item perl_eval_pv
2395
2396Tells Perl to C<eval> the given string and return an SV* result.
2397
ef50df4b 2398 SV* perl_eval_pv (char* p, I32 croak_on_error)
137443ea 2399
cb1a09d0
AD
2400=item perl_free
2401
2402Releases a Perl interpreter. See L<perlembed>.
2403
2404=item perl_get_av
2405
2406Returns the AV of the specified Perl array. If C<create> is set and the
2407Perl variable does not exist then it will be created. If C<create> is not
04343c6d 2408set and the variable does not exist then NULL is returned.
cb1a09d0 2409
ef50df4b 2410 AV* perl_get_av (char* name, I32 create)
cb1a09d0
AD
2411
2412=item perl_get_cv
2413
2414Returns the CV of the specified Perl sub. If C<create> is set and the Perl
2415variable does not exist then it will be created. If C<create> is not
04343c6d 2416set and the variable does not exist then NULL is returned.
cb1a09d0 2417
ef50df4b 2418 CV* perl_get_cv (char* name, I32 create)
cb1a09d0
AD
2419
2420=item perl_get_hv
2421
2422Returns the HV of the specified Perl hash. If C<create> is set and the Perl
2423variable does not exist then it will be created. If C<create> is not
04343c6d 2424set and the variable does not exist then NULL is returned.
cb1a09d0 2425
ef50df4b 2426 HV* perl_get_hv (char* name, I32 create)
cb1a09d0
AD
2427
2428=item perl_get_sv
2429
2430Returns the SV of the specified Perl scalar. If C<create> is set and the
2431Perl variable does not exist then it will be created. If C<create> is not
04343c6d 2432set and the variable does not exist then NULL is returned.
cb1a09d0 2433
ef50df4b 2434 SV* perl_get_sv (char* name, I32 create)
cb1a09d0
AD
2435
2436=item perl_parse
2437
2438Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
2439
2440=item perl_require_pv
2441
2442Tells Perl to C<require> a module.
2443
ef50df4b 2444 void perl_require_pv (char* pv)
cb1a09d0
AD
2445
2446=item perl_run
2447
2448Tells a Perl interpreter to run. See L<perlembed>.
2449
2450=item POPi
2451
2452Pops an integer off the stack.
2453
e89caa19 2454 int POPi()
cb1a09d0
AD
2455
2456=item POPl
2457
2458Pops a long off the stack.
2459
e89caa19 2460 long POPl()
cb1a09d0
AD
2461
2462=item POPp
2463
2464Pops a string off the stack.
2465
e89caa19 2466 char* POPp()
cb1a09d0
AD
2467
2468=item POPn
2469
2470Pops a double off the stack.
2471
e89caa19 2472 double POPn()
cb1a09d0
AD
2473
2474=item POPs
2475
2476Pops an SV off the stack.
2477
e89caa19 2478 SV* POPs()
cb1a09d0
AD
2479
2480=item PUSHMARK
2481
2482Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
2483
2484 PUSHMARK(p)
2485
2486=item PUSHi
2487
2488Push an integer onto the stack. The stack must have room for this element.
189b2af5 2489Handles 'set' magic. See C<XPUSHi>.
cb1a09d0 2490
e89caa19 2491 void PUSHi(int d)
cb1a09d0
AD
2492
2493=item PUSHn
2494
2495Push a double onto the stack. The stack must have room for this element.
189b2af5 2496Handles 'set' magic. See C<XPUSHn>.
cb1a09d0 2497
e89caa19 2498 void PUSHn(double d)
cb1a09d0
AD
2499
2500=item PUSHp
2501
2502Push a string onto the stack. The stack must have room for this element.
189b2af5
GS
2503The C<len> indicates the length of the string. Handles 'set' magic. See
2504C<XPUSHp>.
cb1a09d0 2505
e89caa19 2506 void PUSHp(char *c, int len )
cb1a09d0
AD
2507
2508=item PUSHs
2509
189b2af5
GS
2510Push an SV onto the stack. The stack must have room for this element. Does
2511not handle 'set' magic. See C<XPUSHs>.
cb1a09d0 2512
e89caa19
GA
2513 void PUSHs(sv)
2514
2515=item PUSHu
2516
2517Push an unsigned integer onto the stack. The stack must have room for
2518this element. See C<XPUSHu>.
2519
2520 void PUSHu(unsigned int d)
2521
cb1a09d0
AD
2522
2523=item PUTBACK
2524
2525Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
2526See C<PUSHMARK> and L<perlcall> for other uses.
2527
2528 PUTBACK;
2529
2530=item Renew
2531
2532The XSUB-writer's interface to the C C<realloc> function.
2533
e89caa19 2534 void* Renew( void *ptr, int size, type )
cb1a09d0
AD
2535
2536=item Renewc
2537
2538The XSUB-writer's interface to the C C<realloc> function, with cast.
2539
e89caa19 2540 void* Renewc( void *ptr, int size, type, cast )
cb1a09d0
AD
2541
2542=item RETVAL
2543
2544Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
5fb8527f
PP
2545This is always the proper type for the XSUB.
2546See L<perlxs/"The RETVAL Variable">.
cb1a09d0
AD
2547
2548=item safefree
2549
2550The XSUB-writer's interface to the C C<free> function.
2551
2552=item safemalloc
2553
2554The XSUB-writer's interface to the C C<malloc> function.
2555
2556=item saferealloc
2557
2558The XSUB-writer's interface to the C C<realloc> function.
2559
2560=item savepv
2561
2562Copy a string to a safe spot. This does not use an SV.
2563
ef50df4b 2564 char* savepv (char* sv)
cb1a09d0
AD
2565
2566=item savepvn
2567
2568Copy a string to a safe spot. The C<len> indicates number of bytes to
2569copy. This does not use an SV.
2570
ef50df4b 2571 char* savepvn (char* sv, I32 len)
cb1a09d0
AD
2572
2573=item SAVETMPS
2574
2575Opening bracket for temporaries on a callback. See C<FREETMPS> and
2576L<perlcall>.
2577
2578 SAVETMPS;
2579
2580=item SP
2581
2582Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2583C<SPAGAIN>.
2584
2585=item SPAGAIN
2586
54310121 2587Refetch the stack pointer. Used after a callback. See L<perlcall>.
cb1a09d0
AD
2588
2589 SPAGAIN;
2590
2591=item ST
2592
2593Used to access elements on the XSUB's stack.
2594
e89caa19 2595 SV* ST(int x)
cb1a09d0
AD
2596
2597=item strEQ
2598
2599Test two strings to see if they are equal. Returns true or false.
2600
e89caa19 2601 int strEQ( char *s1, char *s2 )
cb1a09d0
AD
2602
2603=item strGE
2604
2605Test two strings to see if the first, C<s1>, is greater than or equal to the
2606second, C<s2>. Returns true or false.
2607
e89caa19 2608 int strGE( char *s1, char *s2 )
cb1a09d0
AD
2609
2610=item strGT
2611
2612Test two strings to see if the first, C<s1>, is greater than the second,
2613C<s2>. Returns true or false.
2614
e89caa19 2615 int strGT( char *s1, char *s2 )
cb1a09d0
AD
2616
2617=item strLE
2618
2619Test two strings to see if the first, C<s1>, is less than or equal to the
2620second, C<s2>. Returns true or false.
2621
e89caa19 2622 int strLE( char *s1, char *s2 )
cb1a09d0
AD
2623
2624=item strLT
2625
2626Test two strings to see if the first, C<s1>, is less than the second,
2627C<s2>. Returns true or false.
2628
e89caa19 2629 int strLT( char *s1, char *s2 )
cb1a09d0
AD
2630
2631=item strNE
2632
2633Test two strings to see if they are different. Returns true or false.
2634
e89caa19 2635 int strNE( char *s1, char *s2 )
cb1a09d0
AD
2636
2637=item strnEQ
2638
2639Test two strings to see if they are equal. The C<len> parameter indicates
2640the number of bytes to compare. Returns true or false.
2641
e89caa19 2642 int strnEQ( char *s1, char *s2 )
cb1a09d0
AD
2643
2644=item strnNE
2645
2646Test two strings to see if they are different. The C<len> parameter
2647indicates the number of bytes to compare. Returns true or false.
2648
e89caa19 2649 int strnNE( char *s1, char *s2, int len )
cb1a09d0
AD
2650
2651=item sv_2mortal
2652
2653Marks an SV as mortal. The SV will be destroyed when the current context
2654ends.
2655
ef50df4b 2656 SV* sv_2mortal (SV* sv)
cb1a09d0
AD
2657
2658=item sv_bless
2659
2660Blesses an SV into a specified package. The SV must be an RV. The package
07fa94a1
JO
2661must be designated by its stash (see C<gv_stashpv()>). The reference count
2662of the SV is unaffected.
cb1a09d0 2663
ef50df4b 2664 SV* sv_bless (SV* sv, HV* stash)
cb1a09d0 2665
ef50df4b 2666=item sv_catpv
189b2af5 2667
ef50df4b
GS
2668Concatenates the string onto the end of the string which is in the SV.
2669Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
189b2af5 2670
ef50df4b 2671 void sv_catpv (SV* sv, char* ptr)
189b2af5 2672
ef50df4b 2673=item sv_catpv_mg
cb1a09d0 2674
ef50df4b 2675Like C<sv_catpv>, but also handles 'set' magic.
cb1a09d0 2676
ef50df4b 2677 void sv_catpvn (SV* sv, char* ptr)
cb1a09d0
AD
2678
2679=item sv_catpvn
2680
2681Concatenates the string onto the end of the string which is in the SV. The
189b2af5 2682C<len> indicates number of bytes to copy. Handles 'get' magic, but not
ef50df4b 2683'set' magic. See C<sv_catpvn_mg>.
cb1a09d0 2684
ef50df4b
GS
2685 void sv_catpvn (SV* sv, char* ptr, STRLEN len)
2686
2687=item sv_catpvn_mg
2688
2689Like C<sv_catpvn>, but also handles 'set' magic.
2690
2691 void sv_catpvn_mg (SV* sv, char* ptr, STRLEN len)
cb1a09d0 2692
46fc3d4c
PP
2693=item sv_catpvf
2694
2695Processes its arguments like C<sprintf> and appends the formatted output
189b2af5
GS
2696to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
2697typically be called after calling this function to handle 'set' magic.
46fc3d4c 2698
ef50df4b
GS
2699 void sv_catpvf (SV* sv, const char* pat, ...)
2700
2701=item sv_catpvf_mg
2702
2703Like C<sv_catpvf>, but also handles 'set' magic.
2704
2705 void sv_catpvf_mg (SV* sv, const char* pat, ...)
46fc3d4c 2706
cb1a09d0
AD
2707=item sv_catsv
2708
5fb8527f 2709Concatenates the string from SV C<ssv> onto the end of the string in SV
ef50df4b
GS
2710C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
2711
2712 void sv_catsv (SV* dsv, SV* ssv)
2713
2714=item sv_catsv_mg
cb1a09d0 2715
ef50df4b
GS
2716Like C<sv_catsv>, but also handles 'set' magic.
2717
2718 void sv_catsv_mg (SV* dsv, SV* ssv)
cb1a09d0 2719
e89caa19
GA
2720=item sv_chop
2721
2722Efficient removal of characters from the beginning of the string
2723buffer. SvPOK(sv) must be true and the C<ptr> must be a pointer to
2724somewhere inside the string buffer. The C<ptr> becomes the first
2725character of the adjusted string.
2726
2727 void sv_chop(SV* sv, char *ptr)
2728
2729
5fb8527f
PP
2730=item sv_cmp
2731
2732Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
2733string in C<sv1> is less than, equal to, or greater than the string in
2734C<sv2>.
2735
ef50df4b 2736 I32 sv_cmp (SV* sv1, SV* sv2)
5fb8527f 2737
cb1a09d0
AD
2738=item SvCUR
2739
2740Returns the length of the string which is in the SV. See C<SvLEN>.
2741
e89caa19 2742 int SvCUR (SV* sv)
cb1a09d0
AD
2743
2744=item SvCUR_set
2745
2746Set the length of the string which is in the SV. See C<SvCUR>.
2747
e89caa19 2748 void SvCUR_set (SV* sv, int val )
cb1a09d0 2749
5fb8527f
PP
2750=item sv_dec
2751
5f05dabc 2752Auto-decrement of the value in the SV.
5fb8527f 2753
ef50df4b 2754 void sv_dec (SV* sv)
5fb8527f 2755
e89caa19
GA
2756=item sv_derived_from
2757
2758Returns a boolean indicating whether the SV is a subclass of the
2759specified class.
2760
2761 int sv_derived_from(SV* sv, char* class)
2762
9abd00ed
GS
2763=item sv_derived_from
2764
2765Returns a boolean indicating whether the SV is derived from the specified
2766class. This is the function that implements C<UNIVERSAL::isa>. It works
2767for class names as well as for objects.
2768
2769 bool sv_derived_from _((SV* sv, char* name));
2770
cb1a09d0
AD
2771=item SvEND
2772
2773Returns a pointer to the last character in the string which is in the SV.
2774See C<SvCUR>. Access the character as
2775
e89caa19 2776 char* SvEND(sv)
cb1a09d0 2777
5fb8527f
PP
2778=item sv_eq
2779
2780Returns a boolean indicating whether the strings in the two SVs are
2781identical.
2782
ef50df4b 2783 I32 sv_eq (SV* sv1, SV* sv2)
5fb8527f 2784
189b2af5
GS
2785=item SvGETMAGIC
2786
2787Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates
2788its argument more than once.
2789
2790 void SvGETMAGIC( SV *sv )
2791
cb1a09d0
AD
2792=item SvGROW
2793
e89caa19
GA
2794Expands the character buffer in the SV so that it has room for the
2795indicated number of bytes (remember to reserve space for an extra
2796trailing NUL character). Calls C<sv_grow> to perform the expansion if
2797necessary. Returns a pointer to the character buffer.
cb1a09d0 2798
22c35a8c 2799 char* SvGROW( SV* sv, STRLEN len )
cb1a09d0 2800
5fb8527f
PP
2801=item sv_grow
2802
2803Expands the character buffer in the SV. This will use C<sv_unref> and will
2804upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2805Use C<SvGROW>.
2806
2807=item sv_inc
2808
07fa94a1 2809Auto-increment of the value in the SV.
5fb8527f 2810
ef50df4b 2811 void sv_inc (SV* sv)
5fb8527f 2812
e89caa19
GA
2813=item sv_insert
2814
2815Inserts a string at the specified offset/length within the SV.
2816Similar to the Perl substr() function.
2817
2818 void sv_insert(SV *sv, STRLEN offset, STRLEN len,
2819 char *str, STRLEN strlen)
2820
cb1a09d0
AD
2821=item SvIOK
2822
2823Returns a boolean indicating whether the SV contains an integer.
2824
e89caa19 2825 int SvIOK (SV* SV)
cb1a09d0
AD
2826
2827=item SvIOK_off
2828
2829Unsets the IV status of an SV.
2830
e89caa19 2831 void SvIOK_off (SV* sv)
cb1a09d0
AD
2832
2833=item SvIOK_on
2834
2835Tells an SV that it is an integer.
2836
e89caa19 2837 void SvIOK_on (SV* sv)
cb1a09d0 2838
5fb8527f
PP
2839=item SvIOK_only
2840
2841Tells an SV that it is an integer and disables all other OK bits.
2842
e89caa19 2843 void SvIOK_only (SV* sv)
5fb8527f 2844
cb1a09d0
AD
2845=item SvIOKp
2846
2847Returns a boolean indicating whether the SV contains an integer. Checks the
2848B<private> setting. Use C<SvIOK>.
2849
e89caa19 2850 int SvIOKp (SV* SV)
cb1a09d0
AD
2851
2852=item sv_isa
2853
2854Returns a boolean indicating whether the SV is blessed into the specified
9abd00ed 2855class. This does not check for subtypes; use C<sv_derived_from> to verify
cb1a09d0
AD
2856an inheritance relationship.
2857
ef50df4b 2858 int sv_isa (SV* sv, char* name)
cb1a09d0 2859
cb1a09d0
AD
2860=item sv_isobject
2861
2862Returns a boolean indicating whether the SV is an RV pointing to a blessed
2863object. If the SV is not an RV, or if the object is not blessed, then this
2864will return false.
2865
ef50df4b 2866 int sv_isobject (SV* sv)
cb1a09d0 2867
e89caa19
GA
2868=item SvIV
2869
5c68b227 2870Coerces the given SV to an integer and returns it.
e89caa19 2871
9abd00ed 2872 int SvIV (SV* sv)
a59f3522 2873
cb1a09d0
AD
2874=item SvIVX
2875
5c68b227 2876Returns the integer which is stored in the SV, assuming SvIOK is true.
cb1a09d0 2877
e89caa19 2878 int SvIVX (SV* sv)
cb1a09d0
AD
2879
2880=item SvLEN
2881
2882Returns the size of the string buffer in the SV. See C<SvCUR>.
2883
e89caa19 2884 int SvLEN (SV* sv)
cb1a09d0 2885
5fb8527f
PP
2886=item sv_len
2887
2888Returns the length of the string in the SV. Use C<SvCUR>.
2889
ef50df4b 2890 STRLEN sv_len (SV* sv)
5fb8527f 2891
cb1a09d0
AD
2892=item sv_magic
2893
2894Adds magic to an SV.
2895
ef50df4b 2896 void sv_magic (SV* sv, SV* obj, int how, char* name, I32 namlen)
cb1a09d0
AD
2897
2898=item sv_mortalcopy
2899
2900Creates a new SV which is a copy of the original SV. The new SV is marked
5f05dabc 2901as mortal.
cb1a09d0 2902
ef50df4b 2903 SV* sv_mortalcopy (SV* oldsv)
cb1a09d0 2904
cb1a09d0
AD
2905=item sv_newmortal
2906
5f05dabc 2907Creates a new SV which is mortal. The reference count of the SV is set to 1.
cb1a09d0 2908
ef50df4b 2909 SV* sv_newmortal (void)
cb1a09d0 2910
cb1a09d0
AD
2911=item SvNIOK
2912
2913Returns a boolean indicating whether the SV contains a number, integer or
2914double.
2915
e89caa19 2916 int SvNIOK (SV* SV)
cb1a09d0
AD
2917
2918=item SvNIOK_off
2919
2920Unsets the NV/IV status of an SV.
2921
e89caa19 2922 void SvNIOK_off (SV* sv)
cb1a09d0
AD
2923
2924=item SvNIOKp
2925
2926Returns a boolean indicating whether the SV contains a number, integer or
2927double. Checks the B<private> setting. Use C<SvNIOK>.
2928
e89caa19
GA
2929 int SvNIOKp (SV* SV)
2930
9cde0e7f 2931=item PL_sv_no
e89caa19 2932
9cde0e7f 2933This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as C<&PL_sv_no>.
cb1a09d0
AD
2934
2935=item SvNOK
2936
2937Returns a boolean indicating whether the SV contains a double.
2938
e89caa19 2939 int SvNOK (SV* SV)
cb1a09d0
AD
2940
2941=item SvNOK_off
2942
2943Unsets the NV status of an SV.
2944
e89caa19 2945 void SvNOK_off (SV* sv)
cb1a09d0
AD
2946
2947=item SvNOK_on
2948
2949Tells an SV that it is a double.
2950
e89caa19 2951 void SvNOK_on (SV* sv)
cb1a09d0 2952
5fb8527f
PP
2953=item SvNOK_only
2954
2955Tells an SV that it is a double and disables all other OK bits.
2956
e89caa19 2957 void SvNOK_only (SV* sv)
5fb8527f 2958
cb1a09d0
AD
2959=item SvNOKp
2960
2961Returns a boolean indicating whether the SV contains a double. Checks the
2962B<private> setting. Use C<SvNOK>.
2963
e89caa19 2964 int SvNOKp (SV* SV)
cb1a09d0
AD
2965
2966=item SvNV
2967
5c68b227 2968Coerce the given SV to a double and return it.
cb1a09d0 2969
e89caa19 2970 double SvNV (SV* sv)
cb1a09d0
AD
2971
2972=item SvNVX
2973
5c68b227 2974Returns the double which is stored in the SV, assuming SvNOK is true.
cb1a09d0 2975
e89caa19
GA
2976 double SvNVX (SV* sv)
2977
2978=item SvOK
2979
2980Returns a boolean indicating whether the value is an SV.
2981
2982 int SvOK (SV* sv)
2983
2984=item SvOOK
2985
2986Returns a boolean indicating whether the SvIVX is a valid offset value
2987for the SvPVX. This hack is used internally to speed up removal of
2988characters from the beginning of a SvPV. When SvOOK is true, then the
2989start of the allocated string buffer is really (SvPVX - SvIVX).
2990
9cde0e7f 2991 int SvOOK(SV* sv)
cb1a09d0
AD
2992
2993=item SvPOK
2994
2995Returns a boolean indicating whether the SV contains a character string.
2996
e89caa19 2997 int SvPOK (SV* SV)
cb1a09d0
AD
2998
2999=item SvPOK_off
3000
3001Unsets the PV status of an SV.
3002
e89caa19 3003 void SvPOK_off (SV* sv)
cb1a09d0
AD
3004
3005=item SvPOK_on
3006
3007Tells an SV that it is a string.
3008
e89caa19 3009 void SvPOK_on (SV* sv)
cb1a09d0 3010
5fb8527f
PP
3011=item SvPOK_only
3012
3013Tells an SV that it is a string and disables all other OK bits.
3014
e89caa19 3015 void SvPOK_only (SV* sv)
5fb8527f 3016
cb1a09d0
AD
3017=item SvPOKp
3018
3019Returns a boolean indicating whether the SV contains a character string.
3020Checks the B<private> setting. Use C<SvPOK>.
3021
e89caa19 3022 int SvPOKp (SV* SV)
cb1a09d0
AD
3023
3024=item SvPV
3025
3026Returns a pointer to the string in the SV, or a stringified form of the SV
2d8e6c8d 3027if the SV does not contain a string. Handles 'get' magic.
cb1a09d0 3028
e89caa19
GA
3029 char* SvPV (SV* sv, int len )
3030
3031=item SvPV_force
3032
3033Like <SvPV> but will force the SV into becoming a string (SvPOK). You
3034want force if you are going to update the SvPVX directly.
3035
3036 char* SvPV_force(SV* sv, int len)
3037
cb1a09d0
AD
3038
3039=item SvPVX
3040
3041Returns a pointer to the string in the SV. The SV must contain a string.
3042
e89caa19 3043 char* SvPVX (SV* sv)
cb1a09d0
AD
3044
3045=item SvREFCNT
3046
5f05dabc 3047Returns the value of the object's reference count.
cb1a09d0 3048
e89caa19 3049 int SvREFCNT (SV* sv)
cb1a09d0
AD
3050
3051=item SvREFCNT_dec
3052
5f05dabc 3053Decrements the reference count of the given SV.
cb1a09d0 3054
e89caa19 3055 void SvREFCNT_dec (SV* sv)
cb1a09d0
AD
3056
3057=item SvREFCNT_inc
3058
5f05dabc 3059Increments the reference count of the given SV.
cb1a09d0 3060
e89caa19 3061 void SvREFCNT_inc (SV* sv)
cb1a09d0
AD
3062
3063=item SvROK
3064
3065Tests if the SV is an RV.
3066
e89caa19 3067 int SvROK (SV* sv)
cb1a09d0
AD
3068
3069=item SvROK_off
3070
3071Unsets the RV status of an SV.
3072
e89caa19 3073 void SvROK_off (SV* sv)
cb1a09d0
AD
3074
3075=item SvROK_on
3076
3077Tells an SV that it is an RV.
3078
e89caa19 3079 void SvROK_on (SV* sv)
cb1a09d0
AD
3080
3081=item SvRV
3082
3083Dereferences an RV to return the SV.
3084
ef50df4b 3085 SV* SvRV (SV* sv)
cb1a09d0 3086
189b2af5
GS
3087=item SvSETMAGIC
3088
3089Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates
3090its argument more than once.
3091
3092 void SvSETMAGIC( SV *sv )
3093
ef50df4b 3094=item sv_setiv
189b2af5 3095
ef50df4b
GS
3096Copies an integer into the given SV. Does not handle 'set' magic.
3097See C<sv_setiv_mg>.
189b2af5 3098
ef50df4b 3099 void sv_setiv (SV* sv, IV num)
189b2af5 3100
ef50df4b 3101=item sv_setiv_mg
189b2af5 3102
ef50df4b 3103Like C<sv_setiv>, but also handles 'set' magic.
189b2af5 3104
ef50df4b 3105 void sv_setiv_mg (SV* sv, IV num)
189b2af5 3106
ef50df4b 3107=item sv_setnv
189b2af5 3108
ef50df4b
GS
3109Copies a double into the given SV. Does not handle 'set' magic.
3110See C<sv_setnv_mg>.
189b2af5 3111
ef50df4b 3112 void sv_setnv (SV* sv, double num)
189b2af5 3113
ef50df4b 3114=item sv_setnv_mg
189b2af5 3115
ef50df4b 3116Like C<sv_setnv>, but also handles 'set' magic.
189b2af5 3117
ef50df4b 3118 void sv_setnv_mg (SV* sv, double num)
189b2af5 3119
ef50df4b 3120=item sv_setpv
189b2af5 3121
ef50df4b
GS
3122Copies a string into an SV. The string must be null-terminated.
3123Does not handle 'set' magic. See C<sv_setpv_mg>.
189b2af5 3124
ef50df4b 3125 void sv_setpv (SV* sv, char* ptr)
189b2af5 3126
ef50df4b 3127=item sv_setpv_mg
189b2af5 3128
ef50df4b 3129Like C<sv_setpv>, but also handles 'set' magic.
189b2af5 3130
ef50df4b 3131 void sv_setpv_mg (SV* sv, char* ptr)
189b2af5 3132
ef50df4b 3133=item sv_setpviv
cb1a09d0 3134
ef50df4b
GS
3135Copies an integer into the given SV, also updating its string value.
3136Does not handle 'set' magic. See C<sv_setpviv_mg>.
cb1a09d0 3137
ef50df4b 3138 void sv_setpviv (SV* sv, IV num)
cb1a09d0 3139
ef50df4b 3140=item sv_setpviv_mg
cb1a09d0 3141
ef50df4b 3142Like C<sv_setpviv>, but also handles 'set' magic.
cb1a09d0 3143
ef50df4b 3144 void sv_setpviv_mg (SV* sv, IV num)
cb1a09d0 3145
ef50df4b 3146=item sv_setpvn
cb1a09d0 3147
ef50df4b
GS
3148Copies a string into an SV. The C<len> parameter indicates the number of
3149bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
cb1a09d0 3150
ef50df4b 3151 void sv_setpvn (SV* sv, char* ptr, STRLEN len)
cb1a09d0 3152
ef50df4b 3153=item sv_setpvn_mg
189b2af5 3154
ef50df4b 3155Like C<sv_setpvn>, but also handles 'set' magic.
189b2af5 3156
ef50df4b 3157 void sv_setpvn_mg (SV* sv, char* ptr, STRLEN len)
189b2af5 3158
ef50df4b 3159=item sv_setpvf
cb1a09d0 3160
ef50df4b
GS
3161Processes its arguments like C<sprintf> and sets an SV to the formatted
3162output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
cb1a09d0 3163
ef50df4b 3164 void sv_setpvf (SV* sv, const char* pat, ...)
cb1a09d0 3165
ef50df4b 3166=item sv_setpvf_mg
46fc3d4c 3167
ef50df4b 3168Like C<sv_setpvf>, but also handles 'set' magic.
46fc3d4c 3169
ef50df4b 3170 void sv_setpvf_mg (SV* sv, const char* pat, ...)
46fc3d4c 3171
cb1a09d0
AD
3172=item sv_setref_iv
3173
5fb8527f
PP
3174Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3175argument will be upgraded to an RV. That RV will be modified to point to
3176the new SV. The C<classname> argument indicates the package for the
3177blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3178will be returned and will have a reference count of 1.
cb1a09d0 3179
ef50df4b 3180 SV* sv_setref_iv (SV *rv, char *classname, IV iv)
cb1a09d0
AD
3181
3182=item sv_setref_nv
3183
5fb8527f
PP
3184Copies a double into a new SV, optionally blessing the SV. The C<rv>
3185argument will be upgraded to an RV. That RV will be modified to point to
3186the new SV. The C<classname> argument indicates the package for the
3187blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3188will be returned and will have a reference count of 1.
cb1a09d0 3189
ef50df4b 3190 SV* sv_setref_nv (SV *rv, char *classname, double nv)
cb1a09d0
AD
3191
3192=item sv_setref_pv
3193
5fb8527f
PP
3194Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3195argument will be upgraded to an RV. That RV will be modified to point to
9cde0e7f 3196the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
5fb8527f
PP
3197into the SV. The C<classname> argument indicates the package for the
3198blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 3199will be returned and will have a reference count of 1.
cb1a09d0 3200
ef50df4b 3201 SV* sv_setref_pv (SV *rv, char *classname, void* pv)
cb1a09d0
AD
3202
3203Do not use with integral Perl types such as HV, AV, SV, CV, because those
3204objects will become corrupted by the pointer copy process.
3205
3206Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3207
3208=item sv_setref_pvn
3209
5fb8527f
PP
3210Copies a string into a new SV, optionally blessing the SV. The length of the
3211string must be specified with C<n>. The C<rv> argument will be upgraded to
3212an RV. That RV will be modified to point to the new SV. The C<classname>
cb1a09d0
AD
3213argument indicates the package for the blessing. Set C<classname> to
3214C<Nullch> to avoid the blessing. The new SV will be returned and will have
5f05dabc 3215a reference count of 1.
cb1a09d0 3216
ef50df4b 3217 SV* sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n)
cb1a09d0
AD
3218
3219Note that C<sv_setref_pv> copies the pointer while this copies the string.
3220
189b2af5
GS
3221=item SvSetSV
3222
3223Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
3224more than once.
3225
3226 void SvSetSV (SV* dsv, SV* ssv)
3227
3228=item SvSetSV_nosteal
3229
3230Calls a non-destructive version of C<sv_setsv> if dsv is not the same as ssv.
3231May evaluate arguments more than once.
3232
3233 void SvSetSV_nosteal (SV* dsv, SV* ssv)
3234
cb1a09d0
AD
3235=item sv_setsv
3236
3237Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
189b2af5 3238The source SV may be destroyed if it is mortal. Does not handle 'set' magic.
ef50df4b
GS
3239See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and C<sv_setsv_mg>.
3240
3241 void sv_setsv (SV* dsv, SV* ssv)
3242
3243=item sv_setsv_mg
3244
3245Like C<sv_setsv>, but also handles 'set' magic.
cb1a09d0 3246
ef50df4b 3247 void sv_setsv_mg (SV* dsv, SV* ssv)
cb1a09d0 3248
189b2af5
GS
3249=item sv_setuv
3250
3251Copies an unsigned integer into the given SV. Does not handle 'set' magic.
ef50df4b 3252See C<sv_setuv_mg>.
189b2af5 3253
ef50df4b
GS
3254 void sv_setuv (SV* sv, UV num)
3255
3256=item sv_setuv_mg
3257
3258Like C<sv_setuv>, but also handles 'set' magic.
3259
3260 void sv_setuv_mg (SV* sv, UV num)
189b2af5 3261
cb1a09d0
AD
3262=item SvSTASH
3263
3264Returns the stash of the SV.
3265
e89caa19
GA
3266 HV* SvSTASH (SV* sv)
3267
3268=item SvTAINT
3269
3270Taints an SV if tainting is enabled
3271
3272 void SvTAINT (SV* sv)
3273
3274=item SvTAINTED
3275
3276Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.
3277
3278 int SvTAINTED (SV* sv)
3279
3280=item SvTAINTED_off
3281
3282Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3283some of Perl's fundamental security features. XS module authors should
3284not use this function unless they fully understand all the implications
3285of unconditionally untainting the value. Untainting should be done in
3286the standard perl fashion, via a carefully crafted regexp, rather than
3287directly untainting variables.
3288
3289 void SvTAINTED_off (SV* sv)
3290
3291=item SvTAINTED_on
3292
3293Marks an SV as tainted.
3294
3295 void SvTAINTED_on (SV* sv)
cb1a09d0
AD
3296
3297=item SVt_IV
3298
3299Integer type flag for scalars. See C<svtype>.
3300
3301=item SVt_PV
3302
3303Pointer type flag for scalars. See C<svtype>.
3304
3305=item SVt_PVAV
3306
3307Type flag for arrays. See C<svtype>.
3308
3309=item SVt_PVCV
3310
3311Type flag for code refs. See C<svtype>.
3312
3313=item SVt_PVHV
3314
3315Type flag for hashes. See C<svtype>.
3316
3317=item SVt_PVMG
3318
3319Type flag for blessed scalars. See C<svtype>.
3320
3321=item SVt_NV
3322
3323Double type flag for scalars. See C<svtype>.
3324
3325=item SvTRUE
3326
3327Returns a boolean indicating whether Perl would evaluate the SV as true or
189b2af5 3328false, defined or undefined. Does not handle 'get' magic.
cb1a09d0 3329
e89caa19 3330 int SvTRUE (SV* sv)
cb1a09d0
AD
3331
3332=item SvTYPE
3333
3334Returns the type of the SV. See C<svtype>.
3335
3336 svtype SvTYPE (SV* sv)
3337
3338=item svtype
3339
3340An enum of flags for Perl types. These are found in the file B<sv.h> in the
3341C<svtype> enum. Test these flags with the C<SvTYPE> macro.
3342
9cde0e7f 3343=item PL_sv_undef
cb1a09d0 3344
9cde0e7f 3345This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
cb1a09d0 3346
5fb8527f
PP
3347=item sv_unref
3348
07fa94a1
JO
3349Unsets the RV status of the SV, and decrements the reference count of
3350whatever was being referenced by the RV. This can almost be thought of
3351as a reversal of C<newSVrv>. See C<SvROK_off>.
5fb8527f 3352
ef50df4b 3353 void sv_unref (SV* sv)
189b2af5 3354
e89caa19
GA
3355=item SvUPGRADE
3356
3357Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
3358the upgrade if necessary. See C<svtype>.
3359
3360 bool SvUPGRADE (SV* sv, svtype mt)
3361
3362=item sv_upgrade
3363
3364Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
3365
cb1a09d0
AD
3366=item sv_usepvn
3367
3368Tells an SV to use C<ptr> to find its string value. Normally the string is
5fb8527f
PP
3369stored inside the SV but sv_usepvn allows the SV to use an outside string.
3370The C<ptr> should point to memory that was allocated by C<malloc>. The
cb1a09d0
AD
3371string length, C<len>, must be supplied. This function will realloc the
3372memory pointed to by C<ptr>, so that pointer should not be freed or used by
189b2af5 3373the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
ef50df4b
GS
3374See C<sv_usepvn_mg>.
3375
3376 void sv_usepvn (SV* sv, char* ptr, STRLEN len)
3377
3378=item sv_usepvn_mg
3379
3380Like C<sv_usepvn>, but also handles 'set' magic.
cb1a09d0 3381
ef50df4b 3382 void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
cb1a09d0 3383
9abd00ed
GS
3384=item sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3385
3386Processes its arguments like C<vsprintf> and appends the formatted output
3387to an SV. Uses an array of SVs if the C style variable argument list is
3388missing (NULL). Indicates if locale information has been used for formatting.
3389
3390 void sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen,
3391 va_list *args, SV **svargs, I32 svmax,
3392 bool *used_locale));
3393
3394=item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
3395
3396Works like C<vcatpvfn> but copies the text into the SV instead of
3397appending it.
3398
3399 void sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen,
3400 va_list *args, SV **svargs, I32 svmax,
3401 bool *used_locale));
3402
e89caa19
GA
3403=item SvUV
3404
5c68b227 3405Coerces the given SV to an unsigned integer and returns it.
e89caa19
GA
3406
3407 UV SvUV(SV* sv)
3408
3409=item SvUVX
3410
5c68b227 3411Returns the unsigned integer which is stored in the SV, assuming SvIOK is true.
e89caa19
GA
3412
3413 UV SvUVX(SV* sv)
3414
9cde0e7f 3415=item PL_sv_yes
cb1a09d0 3416
9cde0e7f 3417This is the C<true> SV. See C<PL_sv_no>. Always refer to this as C<&PL_sv_yes>.
cb1a09d0
AD
3418
3419=item THIS
3420
3421Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
3422This is always the proper type for the C++ object. See C<CLASS> and
5fb8527f 3423L<perlxs/"Using XS With C++">.
cb1a09d0
AD
3424
3425=item toLOWER
3426
3427Converts the specified character to lowercase.
3428
e89caa19 3429 int toLOWER (char c)
cb1a09d0
AD
3430
3431=item toUPPER
3432
3433Converts the specified character to uppercase.
3434
e89caa19 3435 int toUPPER (char c)
cb1a09d0
AD
3436
3437=item warn
3438
3439This is the XSUB-writer's interface to Perl's C<warn> function. Use this
3440function the same way you use the C C<printf> function. See C<croak()>.
3441
3442=item XPUSHi
3443
189b2af5
GS
3444Push an integer onto the stack, extending the stack if necessary. Handles
3445'set' magic. See C<PUSHi>.
cb1a09d0
AD
3446
3447 XPUSHi(int d)
3448
3449=item XPUSHn
3450
189b2af5
GS
3451Push a double onto the stack, extending the stack if necessary. Handles 'set'
3452magic. See C<PUSHn>.
cb1a09d0
AD
3453
3454 XPUSHn(double d)
3455
3456=item XPUSHp
3457
3458Push a string onto the stack, extending the stack if necessary. The C<len>
189b2af5 3459indicates the length of the string. Handles 'set' magic. See C<PUSHp>.
cb1a09d0
AD
3460
3461 XPUSHp(char *c, int len)
3462
3463=item XPUSHs
3464
189b2af5
GS
3465Push an SV onto the stack, extending the stack if necessary. Does not
3466handle 'set' magic. See C<PUSHs>.
cb1a09d0
AD
3467
3468 XPUSHs(sv)
3469
e89caa19
GA
3470=item XPUSHu
3471
3472Push an unsigned integer onto the stack, extending the stack if
3473necessary. See C<PUSHu>.
3474
5fb8527f
PP
3475=item XS
3476
3477Macro to declare an XSUB and its C parameter list. This is handled by
3478C<xsubpp>.
3479
cb1a09d0
AD
3480=item XSRETURN
3481
3482Return from XSUB, indicating number of items on the stack. This is usually
3483handled by C<xsubpp>.
3484
ef50df4b 3485 XSRETURN(int x)
cb1a09d0
AD
3486
3487=item XSRETURN_EMPTY
3488
5fb8527f 3489Return an empty list from an XSUB immediately.
cb1a09d0
AD
3490
3491 XSRETURN_EMPTY;
3492
5fb8527f
PP
3493=item XSRETURN_IV
3494
3495Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3496
ef50df4b 3497 XSRETURN_IV(IV v)
5fb8527f 3498
cb1a09d0
AD
3499=item XSRETURN_NO
3500
9cde0e7f 3501Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
cb1a09d0
AD
3502
3503 XSRETURN_NO;
3504
5fb8527f
PP
3505=item XSRETURN_NV
3506
3507Return an double from an XSUB immediately. Uses C<XST_mNV>.
3508
ef50df4b 3509 XSRETURN_NV(NV v)
5fb8527f
PP
3510
3511=item XSRETURN_PV
3512
3513Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3514
ef50df4b 3515 XSRETURN_PV(char *v)
5fb8527f 3516
cb1a09d0
AD
3517=item XSRETURN_UNDEF
3518
9cde0e7f 3519Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
cb1a09d0
AD
3520
3521 XSRETURN_UNDEF;
3522
3523=item XSRETURN_YES
3524
9cde0e7f 3525Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
cb1a09d0
AD
3526
3527 XSRETURN_YES;
3528
5fb8527f
PP
3529=item XST_mIV
3530
3531Place an integer into the specified position C<i> on the stack. The value is
3532stored in a new mortal SV.
3533
ef50df4b 3534 XST_mIV( int i, IV v )
5fb8527f
PP
3535
3536=item XST_mNV
3537
3538Place a double into the specified position C<i> on the stack. The value is
3539stored in a new mortal SV.
3540
ef50df4b 3541 XST_mNV( int i, NV v )
5fb8527f
PP
3542
3543=item XST_mNO
3544
9cde0e7f 3545Place C<&PL_sv_no> into the specified position C<i> on the stack.
5fb8527f 3546
ef50df4b 3547 XST_mNO( int i )
5fb8527f
PP
3548
3549=item XST_mPV
3550
3551Place a copy of a string into the specified position C<i> on the stack. The
3552value is stored in a new mortal SV.
3553
ef50df4b 3554 XST_mPV( int i, char *v )
5fb8527f
PP
3555
3556=item XST_mUNDEF
3557
9cde0e7f 3558Place C<&PL_sv_undef> into the specified position C<i> on the stack.
5fb8527f 3559
ef50df4b 3560 XST_mUNDEF( int i )
5fb8527f
PP
3561
3562=item XST_mYES
3563
9cde0e7f 3564Place C<&PL_sv_yes> into the specified position C<i> on the stack.
5fb8527f 3565
ef50df4b 3566 XST_mYES( int i )
5fb8527f
PP
3567
3568=item XS_VERSION
3569
3570The version identifier for an XS module. This is usually handled
3571automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
3572
3573=item XS_VERSION_BOOTCHECK
3574
3575Macro to verify that a PM module's $VERSION variable matches the XS module's
3576C<XS_VERSION> variable. This is usually handled automatically by
3577C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
3578
cb1a09d0
AD
3579=item Zero
3580
3581The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
3582destination, C<n> is the number of items, and C<t> is the type.
3583
e89caa19 3584 void Zero( d, n, t )
cb1a09d0
AD
3585
3586=back
3587
9cecd9f2 3588=head1 AUTHORS
cb1a09d0 3589
9cecd9f2
GA
3590Until May 1997, this document was maintained by Jeff Okamoto
3591<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
cb1a09d0
AD
3592
3593With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3594Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
189b2af5
GS
3595Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
3596Stephen McCamant, and Gurusamy Sarathy.
cb1a09d0 3597
9cecd9f2 3598API Listing originally by Dean Roehrich <roehrich@cray.com>.