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