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