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