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