This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perllocale.pod -- second draft
[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
5f05dabc 80If you want to know simply 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
5f05dabc 183In general, though, it's best just to use the C<Sv*V> macros.
a0d0e21e 184
5f05dabc 185=head2 Working with AV's
a0d0e21e 186
5f05dabc 187There are two ways to create and load an AV. The first method creates just
a0d0e21e
LW
188an empty AV:
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
5f05dabc 328To create a reference, use the following functions:
a0d0e21e 329
5f05dabc
PP
330 SV* newRV_inc((SV*) thing);
331 SV* newRV_noinc((SV*) thing);
a0d0e21e 332
5f05dabc
PP
333The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
334functions are identical except that C<newRV_inc> increments the
335reference count of C<thing>, while C<newRV_noinc> does not. (For
336historical reasons, "newRV" is a synonym for "newRV_inc".) Once you
337have a reference, you can use the following macro to dereference the
d1b91892 338reference:
a0d0e21e
LW
339
340 SvRV(SV*)
341
342then call the appropriate routines, casting the returned C<SV*> to either an
d1b91892 343C<AV*> or C<HV*>, if required.
a0d0e21e 344
d1b91892 345To determine if an SV is a reference, you can use the following macro:
a0d0e21e
LW
346
347 SvROK(SV*)
348
5f05dabc
PP
349To discover what type of value the reference refers to, you must use the
350following macro and then check the value returned.
d1b91892
AD
351
352 SvTYPE(SvRV(SV*))
353
354The most useful types that will be returned are:
355
356 SVt_IV Scalar
357 SVt_NV Scalar
358 SVt_PV Scalar
5f05dabc 359 SVt_RV Scalar
d1b91892
AD
360 SVt_PVAV Array
361 SVt_PVHV Hash
362 SVt_PVCV Code
5f05dabc
PP
363 SVt_PVGV Glob (possible a file handle)
364 SVt_PVMG Blessed or Magical Scalar
365
366 See the sv.h header file for more details.
d1b91892 367
cb1a09d0
AD
368=head2 Blessed References and Class Objects
369
370References are also used to support object-oriented programming. In the
371OO lexicon, an object is simply a reference that has been blessed into a
372package (or class). Once blessed, the programmer may now use the reference
373to access the various methods in the class.
374
375A reference can be blessed into a package with the following function:
376
377 SV* sv_bless(SV* sv, HV* stash);
378
379The C<sv> argument must be a reference. The C<stash> argument specifies
55497cff 380which class the reference will belong to. See the section on L<Stashes>
cb1a09d0
AD
381for information on converting class names into stashes.
382
383/* Still under construction */
384
385Upgrades rv to reference if not already one. Creates new SV for rv to
386point to.
387If classname is non-null, the SV is blessed into the specified class.
388SV is returned.
389
390 SV* newSVrv(SV* rv, char* classname);
391
392Copies integer or double into an SV whose reference is rv. SV is blessed
393if classname is non-null.
394
395 SV* sv_setref_iv(SV* rv, char* classname, IV iv);
396 SV* sv_setref_nv(SV* rv, char* classname, NV iv);
397
5f05dabc
PP
398Copies the pointer value (I<the address, not the string!>) into an SV whose
399reference is rv. SV is blessed if classname is non-null.
cb1a09d0
AD
400
401 SV* sv_setref_pv(SV* rv, char* classname, PV iv);
402
403Copies string into an SV whose reference is rv.
404Set length to 0 to let Perl calculate the string length.
405SV is blessed if classname is non-null.
406
407 SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
408
409 int sv_isa(SV* sv, char* name);
410 int sv_isobject(SV* sv);
411
5f05dabc 412=head2 Creating New Variables
cb1a09d0 413
5f05dabc
PP
414To create a new Perl variable with an undef value which can be accessed from
415your Perl script, use the following routines, depending on the variable type.
cb1a09d0 416
5f05dabc
PP
417 SV* perl_get_sv("package::varname", TRUE);
418 AV* perl_get_av("package::varname", TRUE);
419 HV* perl_get_hv("package::varname", TRUE);
cb1a09d0
AD
420
421Notice the use of TRUE as the second parameter. The new variable can now
422be set, using the routines appropriate to the data type.
423
5f05dabc
PP
424There are additional macros whose values may be bitwise OR'ed with the
425C<TRUE> argument to enable certain extra features. Those bits are:
cb1a09d0 426
5f05dabc
PP
427 GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
428 "Indentifier <varname> used only once: possible typo" warning.
429 GV_ADDWARN Issues a "Had to create <varname> unexpectedly" warning if
430 the variable didn't actually exist. This is useful if
431 you expected the variable to exist already and want to
432 propagate this warning back to the user.
cb1a09d0
AD
433
434If the C<varname> argument does not contain a package specifier, it is
435created in the current package.
436
5f05dabc 437=head2 Reference Counts and Mortality
a0d0e21e 438
55497cff
PP
439Perl uses an reference count-driven garbage collection mechanism. SV's,
440AV's, or HV's (xV for short in the following) start their life with a
441reference count of 1. If the reference count of an xV ever drops to 0,
442then they will be destroyed and their memory made available for reuse.
443
444This normally doesn't happen at the Perl level unless a variable is
5f05dabc
PP
445undef'ed or the last variable holding a reference to it is changed or
446overwritten. At the internal level, however, reference counts can be
55497cff
PP
447manipulated with the following macros:
448
449 int SvREFCNT(SV* sv);
5f05dabc 450 SV* SvREFCNT_inc(SV* sv);
55497cff
PP
451 void SvREFCNT_dec(SV* sv);
452
453However, there is one other function which manipulates the reference
5f05dabc
PP
454count of its argument. The C<newRV_inc> function, as you should
455recall, creates a reference to the specified argument. As a side
456effect, it increments the argument's reference count. If this is not
457what you want, use C<newRV_noinc> instead.
458
459For example, imagine you want to return a reference from an XSUB
55497cff 460function. You create a new SV which initially has a reference count
5f05dabc
PP
461of one. Then you call C<newRV_inc>, passing the just-created SV.
462This returns the reference as a new SV, but the reference count of the
463SV you passed to C<newRV_inc> has been incremented to two. Now you
464return the reference and forget about the SV. But Perl hasn't!
465Whenever the returned reference is destroyed, the reference count of
466the original SV is decreased to one and nothing happens. The SV will
467hang around without any way to access it until Perl itself terminates.
468This is a memory leak.
469
470The correct procedure, then, is to use C<newRV_noinc> instead of
471C<newRV_inc>. Then, if and when the last reference is destroyed, the
472reference count of the SV will go to 0 and also be destroyed, stopping
55497cff
PP
473any memory leak.
474
5f05dabc
PP
475There are some convenience functions available that can help with the
476destruction of old xV objects. These functions introduce the concept
477of "mortality". An xV that is mortal has had its reference count
478marked to be decremented, but not actually decremented, until "a short
479time later". Generally the term "short time later" means a single
480Perl statement, such as a call to an XSUB function. The actual
481determinant for when mortal xV's have their reference count
482decremented depends on two macros, SAVETMPS and FREETMPS. Take a look
483at L<perlcall> and L<perlxs> for more details on these macros.
55497cff
PP
484
485"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
486However, if you mortalize a variable twice, the reference count will
487later be decremented twice.
488
489You should be careful about creating mortal variables. Strange things
490can happen if you make the same value mortal within multiple contexts,
5f05dabc 491or if you make a variable mortal multiple times.
a0d0e21e
LW
492
493To create a mortal variable, use the functions:
494
495 SV* sv_newmortal()
496 SV* sv_2mortal(SV*)
497 SV* sv_mortalcopy(SV*)
498
5f05dabc
PP
499The first call creates a mortal SV, the second converts an existing
500SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
501third creates a mortal copy of an existing SV.
a0d0e21e 502
5f05dabc
PP
503The mortal routines are not for just SV's -- AV's and HV's can be made
504mortal by passing their address (casted to C<SV*>) to the C<sv_2mortal> or
a0d0e21e
LW
505C<sv_mortalcopy> routines.
506
5f05dabc 507=head2 Stashes and Globs
a0d0e21e
LW
508
509A stash is a hash table (associative array) that contains all of the
510different objects that are contained within a package. Each key of the
d1b91892
AD
511stash is a symbol name (shared by all the different types of objects
512that have the same name), and each value in the hash table is called a
513GV (for Glob Value). This GV in turn contains references to the various
514objects of that name, including (but not limited to) the following:
cb1a09d0 515
a0d0e21e
LW
516 Scalar Value
517 Array Value
518 Hash Value
519 File Handle
520 Directory Handle
521 Format
522 Subroutine
523
5f05dabc
PP
524There is a single stash called "defstash" that holds the items that exist
525in the "main" package. To get at the items in other packages, append the
526string "::" to the package name. The items in the "Foo" package are in
527the stash "Foo::" in defstash. The items in the "Bar::Baz" package are
528in the stash "Baz::" in "Bar::"'s stash.
a0d0e21e 529
d1b91892 530To get the stash pointer for a particular package, use the function:
a0d0e21e
LW
531
532 HV* gv_stashpv(char* name, I32 create)
533 HV* gv_stashsv(SV*, I32 create)
534
535The first function takes a literal string, the second uses the string stored
d1b91892 536in the SV. Remember that a stash is just a hash table, so you get back an
cb1a09d0 537C<HV*>. The C<create> flag will create a new package if it is set.
a0d0e21e
LW
538
539The name that C<gv_stash*v> wants is the name of the package whose symbol table
540you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
541packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
542language itself.
a0d0e21e
LW
543
544Alternately, if you have an SV that is a blessed reference, you can find
545out the stash pointer by using:
546
547 HV* SvSTASH(SvRV(SV*));
548
549then use the following to get the package name itself:
550
551 char* HvNAME(HV* stash);
552
5f05dabc
PP
553If you need to bless or re-bless an object you can use the following
554function:
a0d0e21e
LW
555
556 SV* sv_bless(SV*, HV* stash)
557
558where the first argument, an C<SV*>, must be a reference, and the second
559argument is a stash. The returned C<SV*> can now be used in the same way
560as any other SV.
561
d1b91892
AD
562For more information on references and blessings, consult L<perlref>.
563
5f05dabc 564=head2 Magic
a0d0e21e 565
d1b91892
AD
566[This section still under construction. Ignore everything here. Post no
567bills. Everything not permitted is forbidden.]
568
d1b91892
AD
569Any SV may be magical, that is, it has special features that a normal
570SV does not have. These features are stored in the SV structure in a
5f05dabc 571linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
d1b91892
AD
572
573 struct magic {
574 MAGIC* mg_moremagic;
575 MGVTBL* mg_virtual;
576 U16 mg_private;
577 char mg_type;
578 U8 mg_flags;
579 SV* mg_obj;
580 char* mg_ptr;
581 I32 mg_len;
582 };
583
584Note this is current as of patchlevel 0, and could change at any time.
585
586=head2 Assigning Magic
587
588Perl adds magic to an SV using the sv_magic function:
589
590 void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
591
592The C<sv> argument is a pointer to the SV that is to acquire a new magical
593feature.
594
595If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
596set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
597it to the beginning of the linked list of magical features. Any prior
598entry of the same type of magic is deleted. Note that this can be
5fb8527f 599overridden, and multiple instances of the same type of magic can be
d1b91892
AD
600associated with an SV.
601
602The C<name> and C<namlem> arguments are used to associate a string with
603the magic, typically the name of a variable. C<namlem> is stored in the
55497cff 604C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
d1b91892
AD
605copy of the name is stored in C<mg_ptr> field.
606
607The sv_magic function uses C<how> to determine which, if any, predefined
608"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
cb1a09d0
AD
609See the "Magic Virtual Table" section below. The C<how> argument is also
610stored in the C<mg_type> field.
d1b91892
AD
611
612The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
613structure. If it is not the same as the C<sv> argument, the reference
614count of the C<obj> object is incremented. If it is the same, or if
615the C<how> argument is "#", or if it is a null pointer, then C<obj> is
616merely stored, without the reference count being incremented.
617
cb1a09d0
AD
618There is also a function to add magic to an C<HV>:
619
620 void hv_magic(HV *hv, GV *gv, int how);
621
622This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
623
624To remove the magic from an SV, call the function sv_unmagic:
625
626 void sv_unmagic(SV *sv, int type);
627
628The C<type> argument should be equal to the C<how> value when the C<SV>
629was initially made magical.
630
d1b91892
AD
631=head2 Magic Virtual Tables
632
633The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
634C<MGVTBL>, which is a structure of function pointers and stands for
635"Magic Virtual Table" to handle the various operations that might be
636applied to that variable.
637
638The C<MGVTBL> has five pointers to the following routine types:
639
640 int (*svt_get)(SV* sv, MAGIC* mg);
641 int (*svt_set)(SV* sv, MAGIC* mg);
642 U32 (*svt_len)(SV* sv, MAGIC* mg);
643 int (*svt_clear)(SV* sv, MAGIC* mg);
644 int (*svt_free)(SV* sv, MAGIC* mg);
645
646This MGVTBL structure is set at compile-time in C<perl.h> and there are
647currently 19 types (or 21 with overloading turned on). These different
648structures contain pointers to various routines that perform additional
649actions depending on which function is being called.
650
651 Function pointer Action taken
652 ---------------- ------------
653 svt_get Do something after the value of the SV is retrieved.
654 svt_set Do something after the SV is assigned a value.
655 svt_len Report on the SV's length.
656 svt_clear Clear something the SV represents.
657 svt_free Free any extra storage associated with the SV.
658
659For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
660to an C<mg_type> of '\0') contains:
661
662 { magic_get, magic_set, magic_len, 0, 0 }
663
664Thus, when an SV is determined to be magical and of type '\0', if a get
665operation is being performed, the routine C<magic_get> is called. All
666the various routines for the various magical types begin with C<magic_>.
667
668The current kinds of Magic Virtual Tables are:
669
5f05dabc
PP
670 mg_type MGVTBL Type of magic
671 ------- ------ ----------------------------
d1b91892
AD
672 \0 vtbl_sv Regexp???
673 A vtbl_amagic Operator Overloading
674 a vtbl_amagicelem Operator Overloading
675 c 0 Used in Operator Overloading
676 B vtbl_bm Boyer-Moore???
677 E vtbl_env %ENV hash
678 e vtbl_envelem %ENV hash element
679 g vtbl_mglob Regexp /g flag???
680 I vtbl_isa @ISA array
681 i vtbl_isaelem @ISA array element
682 L 0 (but sets RMAGICAL) Perl Module/Debugger???
683 l vtbl_dbline Debugger?
684 P vtbl_pack Tied Array or Hash
685 p vtbl_packelem Tied Array or Hash element
686 q vtbl_packelem Tied Scalar or Handle
687 S vtbl_sig Signal Hash
688 s vtbl_sigelem Signal Hash element
689 t vtbl_taint Taintedness
690 U vtbl_uvar ???
691 v vtbl_vec Vector
692 x vtbl_substr Substring???
693 * vtbl_glob GV???
694 # vtbl_arylen Array Length
695 . vtbl_pos $. scalar variable
5f05dabc 696 ~ None Used by certain extensions
d1b91892
AD
697
698When an upper-case and lower-case letter both exist in the table, then the
699upper-case letter is used to represent some kind of composite type (a list
700or a hash), and the lower-case letter is used to represent an element of
701that composite type.
702
5f05dabc
PP
703The '~' magic type is defined specifically for use by extensions and
704will not be used by perl itself. Extensions can use ~ magic to 'attach'
705private information to variables (typically objects). This is especially
706useful because there is no way for normal perl code to corrupt this
707private information (unlike using extra elements of a hash object).
708
709Note that because multiple extensions may be using ~ magic it is
710important for extensions to take extra care with it. Typically only
711using it on objects blessed into the same class as the extension
712is sufficient. It may also be appropriate to add an I32 'signature'
713at the top of the private data area and check that.
714
d1b91892
AD
715=head2 Finding Magic
716
717 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
718
719This routine returns a pointer to the C<MAGIC> structure stored in the SV.
720If the SV does not have that magical feature, C<NULL> is returned. Also,
721if the SV is not of type SVt_PVMG, Perl may core-dump.
722
723 int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
724
725This routine checks to see what types of magic C<sv> has. If the mg_type
726field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
727the mg_type field is changed to be the lower-case letter.
a0d0e21e 728
5f05dabc 729=head2 Double-Typed SV's
a0d0e21e
LW
730
731Scalar variables normally contain only one type of value, an integer,
732double, pointer, or reference. Perl will automatically convert the
733actual scalar data from the stored type into the requested type.
734
735Some scalar variables contain more than one type of scalar data. For
736example, the variable C<$!> contains either the numeric value of C<errno>
d1b91892 737or its string equivalent from either C<strerror> or C<sys_errlist[]>.
a0d0e21e
LW
738
739To force multiple data values into an SV, you must do two things: use the
740C<sv_set*v> routines to add the additional scalar type, then set a flag
741so that Perl will believe it contains more than one type of data. The
742four macros to set the flags are:
743
744 SvIOK_on
745 SvNOK_on
746 SvPOK_on
747 SvROK_on
748
749The particular macro you must use depends on which C<sv_set*v> routine
750you called first. This is because every C<sv_set*v> routine turns on
751only the bit for the particular type of data being set, and turns off
752all the rest.
753
754For example, to create a new Perl variable called "dberror" that contains
755both the numeric and descriptive string error values, you could use the
756following code:
757
758 extern int dberror;
759 extern char *dberror_list;
760
761 SV* sv = perl_get_sv("dberror", TRUE);
762 sv_setiv(sv, (IV) dberror);
763 sv_setpv(sv, dberror_list[dberror]);
764 SvIOK_on(sv);
765
766If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
767macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
768
5f05dabc
PP
769=head2 XSUB's and the Argument Stack
770
771The XSUB mechanism is a simple way for Perl programs to access C subroutines.
772An XSUB routine will have a stack that contains the arguments from the Perl
773program, and a way to map from the Perl data structures to a C equivalent.
774
775The stack arguments are accessible through the C<ST(n)> macro, which returns
776the C<n>'th stack argument. Argument 0 is the first argument passed in the
777Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
778an C<SV*> is used.
779
780Most of the time, output from the C routine can be handled through use of
781the RETVAL and OUTPUT directives. However, there are some cases where the
782argument stack is not already long enough to handle all the return values.
783An example is the POSIX tzname() call, which takes no arguments, but returns
784two, the local time zone's standard and summer time abbreviations.
785
786To handle this situation, the PPCODE directive is used and the stack is
787extended using the macro:
788
789 EXTEND(sp, num);
790
791where C<sp> is the stack pointer, and C<num> is the number of elements the
792stack should be extended by.
793
794Now that there is room on the stack, values can be pushed on it using the
795macros to push IV's, doubles, strings, and SV pointers respectively:
796
797 PUSHi(IV)
798 PUSHn(double)
799 PUSHp(char*, I32)
800 PUSHs(SV*)
801
802And now the Perl program calling C<tzname>, the two values will be assigned
803as in:
804
805 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
806
807An alternate (and possibly simpler) method to pushing values on the stack is
808to use the macros:
809
810 XPUSHi(IV)
811 XPUSHn(double)
812 XPUSHp(char*, I32)
813 XPUSHs(SV*)
814
815These macros automatically adjust the stack for you, if needed. Thus, you
816do not need to call C<EXTEND> to extend the stack.
817
818For more information, consult L<perlxs> and L<perlxstut>.
819
820=head2 Calling Perl Routines from within C Programs
a0d0e21e
LW
821
822There are four routines that can be used to call a Perl subroutine from
823within a C program. These four are:
824
825 I32 perl_call_sv(SV*, I32);
826 I32 perl_call_pv(char*, I32);
827 I32 perl_call_method(char*, I32);
828 I32 perl_call_argv(char*, I32, register char**);
829
d1b91892
AD
830The routine most often used is C<perl_call_sv>. The C<SV*> argument
831contains either the name of the Perl subroutine to be called, or a
832reference to the subroutine. The second argument consists of flags
833that control the context in which the subroutine is called, whether
834or not the subroutine is being passed arguments, how errors should be
835trapped, and how to treat return values.
a0d0e21e
LW
836
837All four routines return the number of arguments that the subroutine returned
838on the Perl stack.
839
d1b91892
AD
840When using any of these routines (except C<perl_call_argv>), the programmer
841must manipulate the Perl stack. These include the following macros and
842functions:
a0d0e21e
LW
843
844 dSP
845 PUSHMARK()
846 PUTBACK
847 SPAGAIN
848 ENTER
849 SAVETMPS
850 FREETMPS
851 LEAVE
852 XPUSH*()
cb1a09d0 853 POP*()
a0d0e21e 854
5f05dabc
PP
855For a detailed description of calling conventions from C to Perl,
856consult L<perlcall>.
a0d0e21e 857
5f05dabc 858=head2 Memory Allocation
a0d0e21e 859
5f05dabc
PP
860It is suggested that you use the version of malloc that is distributed
861with Perl. It keeps pools of various sizes of unallocated memory in
862satisfy allocation requests more quickly. However, on some platforms, it
863may cause spurious malloc or free errors.
d1b91892
AD
864
865 New(x, pointer, number, type);
866 Newc(x, pointer, number, type, cast);
867 Newz(x, pointer, number, type);
868
5f05dabc
PP
869These three macros are used to allocate memory.
870
871The first argument C<x> was a "magic cookie" that was used to keep track
872of who called the macro, to help when debugging memory problems. However,
873the current code makes no use of this feature (Larry has switched to using
874a run-time memory checker), so this argument can be any number.
875
876The second argument C<pointer> should be the name of a variable that will
877point to the newly allocated memory.
d1b91892 878
d1b91892
AD
879The third and fourth arguments C<number> and C<type> specify how many of
880the specified type of data structure should be allocated. The argument
881C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
882should be used if the C<pointer> argument is different from the C<type>
883argument.
884
885Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
886to zero out all the newly allocated memory.
887
888 Renew(pointer, number, type);
889 Renewc(pointer, number, type, cast);
890 Safefree(pointer)
891
892These three macros are used to change a memory buffer size or to free a
893piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
894match those of C<New> and C<Newc> with the exception of not needing the
895"magic cookie" argument.
896
897 Move(source, dest, number, type);
898 Copy(source, dest, number, type);
899 Zero(dest, number, type);
900
901These three macros are used to move, copy, or zero out previously allocated
902memory. The C<source> and C<dest> arguments point to the source and
903destination starting points. Perl will move, copy, or zero out C<number>
904instances of the size of the C<type> data structure (using the C<sizeof>
905function).
a0d0e21e 906
5f05dabc 907=head2 PerlIO
ce3d39e2 908
5f05dabc
PP
909The most recent development releases of Perl has been experimenting with
910removing Perl's dependency on the "normal" standard I/O suite and allowing
911other stdio implementations to be used. This involves creating a new
912abstraction layer that then calls whichever implementation of stdio Perl
913was compiled with. All XSUB's should now use the functions in the PerlIO
914abstraction layer and not make any assumptions about what kind of stdio
915is being used.
916
917For a complete description of the PerlIO abstraction, consult L<perlapio>.
918
919=head2 Scratchpads
920
921=head3 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
929Each of the targets is created only once (but see
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
5f05dabc 938=head3 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
5f05dabc 956=head3 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
5f05dabc 978=head2 API LISTING
a0d0e21e 979
cb1a09d0
AD
980This is a listing of functions, macros, flags, and variables that may be
981useful to extension writers or that may be found while reading other
982extensions.
a0d0e21e 983
cb1a09d0 984=over 8
a0d0e21e 985
cb1a09d0
AD
986=item AvFILL
987
988See C<av_len>.
989
990=item av_clear
991
992Clears an array, making it empty.
993
994 void av_clear _((AV* ar));
995
996=item av_extend
997
998Pre-extend an array. The C<key> is the index to which the array should be
999extended.
1000
1001 void av_extend _((AV* ar, I32 key));
1002
1003=item av_fetch
1004
1005Returns the SV at the specified index in the array. The C<key> is the
1006index. If C<lval> is set then the fetch will be part of a store. Check
1007that the return value is non-null before dereferencing it to a C<SV*>.
1008
1009 SV** av_fetch _((AV* ar, I32 key, I32 lval));
1010
1011=item av_len
1012
1013Returns the highest index in the array. Returns -1 if the array is empty.
1014
1015 I32 av_len _((AV* ar));
1016
1017=item av_make
1018
5fb8527f
PP
1019Creates a new AV and populates it with a list of SVs. The SVs are copied
1020into the array, so they may be freed after the call to av_make. The new AV
5f05dabc 1021will have a reference count of 1.
cb1a09d0
AD
1022
1023 AV* av_make _((I32 size, SV** svp));
1024
1025=item av_pop
1026
1027Pops an SV off the end of the array. Returns C<&sv_undef> if the array is
1028empty.
1029
1030 SV* av_pop _((AV* ar));
1031
1032=item av_push
1033
5fb8527f
PP
1034Pushes an SV onto the end of the array. The array will grow automatically
1035to accommodate the addition.
cb1a09d0
AD
1036
1037 void av_push _((AV* ar, SV* val));
1038
1039=item av_shift
1040
1041Shifts an SV off the beginning of the array.
1042
1043 SV* av_shift _((AV* ar));
1044
1045=item av_store
1046
1047Stores an SV in an array. The array index is specified as C<key>. The
1048return value will be null if the operation failed, otherwise it can be
1049dereferenced to get the original C<SV*>.
1050
1051 SV** av_store _((AV* ar, I32 key, SV* val));
1052
1053=item av_undef
1054
1055Undefines the array.
1056
1057 void av_undef _((AV* ar));
1058
1059=item av_unshift
1060
5fb8527f
PP
1061Unshift an SV onto the beginning of the array. The array will grow
1062automatically to accommodate the addition.
cb1a09d0
AD
1063
1064 void av_unshift _((AV* ar, I32 num));
1065
1066=item CLASS
1067
1068Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
5fb8527f
PP
1069constructor. This is always a C<char*>. See C<THIS> and
1070L<perlxs/"Using XS With C++">.
cb1a09d0
AD
1071
1072=item Copy
1073
1074The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1075source, C<d> is the destination, C<n> is the number of items, and C<t> is
1076the type.
1077
1078 (void) Copy( s, d, n, t );
1079
1080=item croak
1081
1082This is the XSUB-writer's interface to Perl's C<die> function. Use this
1083function the same way you use the C C<printf> function. See C<warn>.
1084
1085=item CvSTASH
1086
1087Returns the stash of the CV.
1088
1089 HV * CvSTASH( SV* sv )
1090
1091=item DBsingle
1092
1093When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1094boolean which indicates whether subs are being single-stepped.
5fb8527f
PP
1095Single-stepping is automatically turned on after every step. This is the C
1096variable which corresponds to Perl's $DB::single variable. See C<DBsub>.
cb1a09d0
AD
1097
1098=item DBsub
1099
1100When Perl is run in debugging mode, with the B<-d> switch, this GV contains
5fb8527f
PP
1101the SV which holds the name of the sub being debugged. This is the C
1102variable which corresponds to Perl's $DB::sub variable. See C<DBsingle>.
cb1a09d0
AD
1103The sub name can be found by
1104
1105 SvPV( GvSV( DBsub ), na )
1106
5fb8527f
PP
1107=item DBtrace
1108
1109Trace variable used when Perl is run in debugging mode, with the B<-d>
1110switch. This is the C variable which corresponds to Perl's $DB::trace
1111variable. See C<DBsingle>.
1112
cb1a09d0
AD
1113=item dMARK
1114
5fb8527f
PP
1115Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1116C<dORIGMARK>.
cb1a09d0
AD
1117
1118=item dORIGMARK
1119
1120Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1121
5fb8527f
PP
1122=item dowarn
1123
1124The C variable which corresponds to Perl's $^W warning variable.
1125
cb1a09d0
AD
1126=item dSP
1127
5fb8527f 1128Declares a stack pointer variable, C<sp>, for the XSUB. See C<SP>.
cb1a09d0
AD
1129
1130=item dXSARGS
1131
1132Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1133usually handled automatically by C<xsubpp>. Declares the C<items> variable
1134to indicate the number of items on the stack.
1135
5fb8527f
PP
1136=item dXSI32
1137
1138Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1139handled automatically by C<xsubpp>.
1140
1141=item dXSI32
1142
1143Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1144handled automatically by C<xsubpp>.
1145
cb1a09d0
AD
1146=item ENTER
1147
1148Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1149
1150 ENTER;
1151
1152=item EXTEND
1153
1154Used to extend the argument stack for an XSUB's return values.
1155
1156 EXTEND( sp, int x );
1157
1158=item FREETMPS
1159
1160Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1161L<perlcall>.
1162
1163 FREETMPS;
1164
1165=item G_ARRAY
1166
1167Used to indicate array context. See C<GIMME> and L<perlcall>.
1168
1169=item G_DISCARD
1170
1171Indicates that arguments returned from a callback should be discarded. See
1172L<perlcall>.
1173
1174=item G_EVAL
1175
1176Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1177
1178=item GIMME
1179
1180The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or
1181C<G_ARRAY> for scalar or array context.
1182
1183=item G_NOARGS
1184
1185Indicates that no arguments are being sent to a callback. See L<perlcall>.
1186
1187=item G_SCALAR
1188
1189Used to indicate scalar context. See C<GIMME> and L<perlcall>.
1190
1191=item gv_stashpv
1192
1193Returns a pointer to the stash for a specified package. If C<create> is set
1194then the package will be created if it does not already exist. If C<create>
1195is not set and the package does not exist then NULL is returned.
1196
1197 HV* gv_stashpv _((char* name, I32 create));
1198
1199=item gv_stashsv
1200
1201Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1202
1203 HV* gv_stashsv _((SV* sv, I32 create));
1204
1205=item GvSV
1206
1207Return the SV from the GV.
1208
1209=item he_free
1210
1211Releases a hash entry from an iterator. See C<hv_iternext>.
1212
1213=item hv_clear
1214
1215Clears a hash, making it empty.
1216
1217 void hv_clear _((HV* tb));
1218
1219=item hv_delete
1220
1221Deletes a key/value pair in the hash. The value SV is removed from the hash
5fb8527f 1222and returned to the caller. The C<klen> is the length of the key. The
cb1a09d0
AD
1223C<flags> value will normally be zero; if set to G_DISCARD then null will be
1224returned.
1225
1226 SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
1227
1228=item hv_exists
1229
1230Returns a boolean indicating whether the specified hash key exists. The
5fb8527f 1231C<klen> is the length of the key.
cb1a09d0
AD
1232
1233 bool hv_exists _((HV* tb, char* key, U32 klen));
1234
1235=item hv_fetch
1236
1237Returns the SV which corresponds to the specified key in the hash. The
5fb8527f 1238C<klen> is the length of the key. If C<lval> is set then the fetch will be
cb1a09d0
AD
1239part of a store. Check that the return value is non-null before
1240dereferencing it to a C<SV*>.
1241
1242 SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
1243
1244=item hv_iterinit
1245
1246Prepares a starting point to traverse a hash table.
1247
1248 I32 hv_iterinit _((HV* tb));
1249
1250=item hv_iterkey
1251
1252Returns the key from the current position of the hash iterator. See
1253C<hv_iterinit>.
1254
1255 char* hv_iterkey _((HE* entry, I32* retlen));
1256
1257=item hv_iternext
1258
1259Returns entries from a hash iterator. See C<hv_iterinit>.
1260
1261 HE* hv_iternext _((HV* tb));
1262
1263=item hv_iternextsv
1264
1265Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1266operation.
1267
1268 SV * hv_iternextsv _((HV* hv, char** key, I32* retlen));
1269
1270=item hv_iterval
1271
1272Returns the value from the current position of the hash iterator. See
1273C<hv_iterkey>.
1274
1275 SV* hv_iterval _((HV* tb, HE* entry));
1276
1277=item hv_magic
1278
1279Adds magic to a hash. See C<sv_magic>.
1280
1281 void hv_magic _((HV* hv, GV* gv, int how));
1282
1283=item HvNAME
1284
1285Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
1286
1287 char *HvNAME (HV* stash)
1288
1289=item hv_store
1290
1291Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1292the length of the key. The C<hash> parameter is the pre-computed hash
1293value; if it is zero then Perl will compute it. The return value will be
1294null if the operation failed, otherwise it can be dereferenced to get the
1295original C<SV*>.
1296
1297 SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
1298
1299=item hv_undef
1300
1301Undefines the hash.
1302
1303 void hv_undef _((HV* tb));
1304
1305=item isALNUM
1306
1307Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
5f05dabc 1308character or digit.
cb1a09d0
AD
1309
1310 int isALNUM (char c)
1311
1312=item isALPHA
1313
5fb8527f 1314Returns a boolean indicating whether the C C<char> is an ascii alphabetic
cb1a09d0
AD
1315character.
1316
1317 int isALPHA (char c)
1318
1319=item isDIGIT
1320
1321Returns a boolean indicating whether the C C<char> is an ascii digit.
1322
1323 int isDIGIT (char c)
1324
1325=item isLOWER
1326
1327Returns a boolean indicating whether the C C<char> is a lowercase character.
1328
1329 int isLOWER (char c)
1330
1331=item isSPACE
1332
1333Returns a boolean indicating whether the C C<char> is whitespace.
1334
1335 int isSPACE (char c)
1336
1337=item isUPPER
1338
1339Returns a boolean indicating whether the C C<char> is an uppercase character.
1340
1341 int isUPPER (char c)
1342
1343=item items
1344
1345Variable which is setup by C<xsubpp> to indicate the number of items on the
5fb8527f
PP
1346stack. See L<perlxs/"Variable-length Parameter Lists">.
1347
1348=item ix
1349
1350Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
1351was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
cb1a09d0
AD
1352
1353=item LEAVE
1354
1355Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1356
1357 LEAVE;
1358
1359=item MARK
1360
5fb8527f 1361Stack marker variable for the XSUB. See C<dMARK>.
cb1a09d0
AD
1362
1363=item mg_clear
1364
1365Clear something magical that the SV represents. See C<sv_magic>.
1366
1367 int mg_clear _((SV* sv));
1368
1369=item mg_copy
1370
1371Copies the magic from one SV to another. See C<sv_magic>.
1372
1373 int mg_copy _((SV *, SV *, char *, STRLEN));
1374
1375=item mg_find
1376
1377Finds the magic pointer for type matching the SV. See C<sv_magic>.
1378
1379 MAGIC* mg_find _((SV* sv, int type));
1380
1381=item mg_free
1382
1383Free any magic storage used by the SV. See C<sv_magic>.
1384
1385 int mg_free _((SV* sv));
1386
1387=item mg_get
1388
1389Do magic after a value is retrieved from the SV. See C<sv_magic>.
1390
1391 int mg_get _((SV* sv));
1392
1393=item mg_len
1394
1395Report on the SV's length. See C<sv_magic>.
1396
1397 U32 mg_len _((SV* sv));
1398
1399=item mg_magical
1400
1401Turns on the magical status of an SV. See C<sv_magic>.
1402
1403 void mg_magical _((SV* sv));
1404
1405=item mg_set
1406
1407Do magic after a value is assigned to the SV. See C<sv_magic>.
1408
1409 int mg_set _((SV* sv));
1410
1411=item Move
1412
1413The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
1414source, C<d> is the destination, C<n> is the number of items, and C<t> is
1415the type.
1416
1417 (void) Move( s, d, n, t );
1418
1419=item na
1420
1421A variable which may be used with C<SvPV> to tell Perl to calculate the
1422string length.
1423
1424=item New
1425
1426The XSUB-writer's interface to the C C<malloc> function.
1427
1428 void * New( x, void *ptr, int size, type )
1429
1430=item Newc
1431
1432The XSUB-writer's interface to the C C<malloc> function, with cast.
1433
1434 void * Newc( x, void *ptr, int size, type, cast )
1435
1436=item Newz
1437
1438The XSUB-writer's interface to the C C<malloc> function. The allocated
1439memory is zeroed with C<memzero>.
1440
1441 void * Newz( x, void *ptr, int size, type )
1442
1443=item newAV
1444
5f05dabc 1445Creates a new AV. The reference count is set to 1.
cb1a09d0
AD
1446
1447 AV* newAV _((void));
1448
1449=item newHV
1450
5f05dabc 1451Creates a new HV. The reference count is set to 1.
cb1a09d0
AD
1452
1453 HV* newHV _((void));
1454
5f05dabc 1455=item newRV_inc
cb1a09d0 1456
5f05dabc 1457Creates an RV wrapper for an SV. The reference count for the original SV is
cb1a09d0
AD
1458incremented.
1459
5f05dabc
PP
1460 SV* newRV_inc _((SV* ref));
1461
1462For historical reasons, "newRV" is a synonym for "newRV_inc".
1463
1464=item newRV_noinc
1465
1466Creates an RV wrapper for an SV. The reference count for the original
1467SV is B<not> incremented.
1468
1469 SV* newRV_noinc _((SV* ref));
cb1a09d0
AD
1470
1471=item newSV
1472
1473Creates a new SV. The C<len> parameter indicates the number of bytes of
5f05dabc 1474pre-allocated string space the SV should have. The reference count for the new SV
cb1a09d0
AD
1475is set to 1.
1476
1477 SV* newSV _((STRLEN len));
1478
1479=item newSViv
1480
5f05dabc 1481Creates a new SV and copies an integer into it. The reference count for the SV is
cb1a09d0
AD
1482set to 1.
1483
1484 SV* newSViv _((IV i));
1485
1486=item newSVnv
1487
5f05dabc 1488Creates a new SV and copies a double into it. The reference count for the SV is
cb1a09d0
AD
1489set to 1.
1490
1491 SV* newSVnv _((NV i));
1492
1493=item newSVpv
1494
5f05dabc 1495Creates a new SV and copies a string into it. The reference count for the SV is
cb1a09d0
AD
1496set to 1. If C<len> is zero then Perl will compute the length.
1497
1498 SV* newSVpv _((char* s, STRLEN len));
1499
1500=item newSVrv
1501
1502Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5fb8527f 1503it will be upgraded to one. If C<classname> is non-null then the new SV will
cb1a09d0 1504be blessed in the specified package. The new SV is returned and its
5f05dabc 1505reference count is 1.
cb1a09d0
AD
1506
1507 SV* newSVrv _((SV* rv, char* classname));
1508
1509=item newSVsv
1510
5fb8527f 1511Creates a new SV which is an exact duplicate of the original SV.
cb1a09d0
AD
1512
1513 SV* newSVsv _((SV* old));
1514
1515=item newXS
1516
1517Used by C<xsubpp> to hook up XSUBs as Perl subs.
1518
1519=item newXSproto
1520
1521Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1522the subs.
1523
1524=item Nullav
1525
1526Null AV pointer.
1527
1528=item Nullch
1529
1530Null character pointer.
1531
1532=item Nullcv
1533
1534Null CV pointer.
1535
1536=item Nullhv
1537
1538Null HV pointer.
1539
1540=item Nullsv
1541
1542Null SV pointer.
1543
1544=item ORIGMARK
1545
1546The original stack mark for the XSUB. See C<dORIGMARK>.
1547
1548=item perl_alloc
1549
1550Allocates a new Perl interpreter. See L<perlembed>.
1551
1552=item perl_call_argv
1553
1554Performs a callback to the specified Perl sub. See L<perlcall>.
1555
1556 I32 perl_call_argv _((char* subname, I32 flags, char** argv));
1557
1558=item perl_call_method
1559
1560Performs a callback to the specified Perl method. The blessed object must
1561be on the stack. See L<perlcall>.
1562
1563 I32 perl_call_method _((char* methname, I32 flags));
1564
1565=item perl_call_pv
1566
1567Performs a callback to the specified Perl sub. See L<perlcall>.
1568
1569 I32 perl_call_pv _((char* subname, I32 flags));
1570
1571=item perl_call_sv
1572
1573Performs a callback to the Perl sub whose name is in the SV. See
1574L<perlcall>.
1575
1576 I32 perl_call_sv _((SV* sv, I32 flags));
1577
1578=item perl_construct
1579
1580Initializes a new Perl interpreter. See L<perlembed>.
1581
1582=item perl_destruct
1583
1584Shuts down a Perl interpreter. See L<perlembed>.
1585
1586=item perl_eval_sv
1587
1588Tells Perl to C<eval> the string in the SV.
1589
1590 I32 perl_eval_sv _((SV* sv, I32 flags));
1591
1592=item perl_free
1593
1594Releases a Perl interpreter. See L<perlembed>.
1595
1596=item perl_get_av
1597
1598Returns the AV of the specified Perl array. If C<create> is set and the
1599Perl variable does not exist then it will be created. If C<create> is not
1600set and the variable does not exist then null is returned.
1601
1602 AV* perl_get_av _((char* name, I32 create));
1603
1604=item perl_get_cv
1605
1606Returns the CV of the specified Perl sub. If C<create> is set and the Perl
1607variable does not exist then it will be created. If C<create> is not
1608set and the variable does not exist then null is returned.
1609
1610 CV* perl_get_cv _((char* name, I32 create));
1611
1612=item perl_get_hv
1613
1614Returns the HV of the specified Perl hash. If C<create> is set and the Perl
1615variable does not exist then it will be created. If C<create> is not
1616set and the variable does not exist then null is returned.
1617
1618 HV* perl_get_hv _((char* name, I32 create));
1619
1620=item perl_get_sv
1621
1622Returns the SV of the specified Perl scalar. If C<create> is set and the
1623Perl variable does not exist then it will be created. If C<create> is not
1624set and the variable does not exist then null is returned.
1625
1626 SV* perl_get_sv _((char* name, I32 create));
1627
1628=item perl_parse
1629
1630Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1631
1632=item perl_require_pv
1633
1634Tells Perl to C<require> a module.
1635
1636 void perl_require_pv _((char* pv));
1637
1638=item perl_run
1639
1640Tells a Perl interpreter to run. See L<perlembed>.
1641
1642=item POPi
1643
1644Pops an integer off the stack.
1645
1646 int POPi();
1647
1648=item POPl
1649
1650Pops a long off the stack.
1651
1652 long POPl();
1653
1654=item POPp
1655
1656Pops a string off the stack.
1657
1658 char * POPp();
1659
1660=item POPn
1661
1662Pops a double off the stack.
1663
1664 double POPn();
1665
1666=item POPs
1667
1668Pops an SV off the stack.
1669
1670 SV* POPs();
1671
1672=item PUSHMARK
1673
1674Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
1675
1676 PUSHMARK(p)
1677
1678=item PUSHi
1679
1680Push an integer onto the stack. The stack must have room for this element.
1681See C<XPUSHi>.
1682
1683 PUSHi(int d)
1684
1685=item PUSHn
1686
1687Push a double onto the stack. The stack must have room for this element.
1688See C<XPUSHn>.
1689
1690 PUSHn(double d)
1691
1692=item PUSHp
1693
1694Push a string onto the stack. The stack must have room for this element.
1695The C<len> indicates the length of the string. See C<XPUSHp>.
1696
1697 PUSHp(char *c, int len )
1698
1699=item PUSHs
1700
1701Push an SV onto the stack. The stack must have room for this element. See
1702C<XPUSHs>.
1703
1704 PUSHs(sv)
1705
1706=item PUTBACK
1707
1708Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1709See C<PUSHMARK> and L<perlcall> for other uses.
1710
1711 PUTBACK;
1712
1713=item Renew
1714
1715The XSUB-writer's interface to the C C<realloc> function.
1716
1717 void * Renew( void *ptr, int size, type )
1718
1719=item Renewc
1720
1721The XSUB-writer's interface to the C C<realloc> function, with cast.
1722
1723 void * Renewc( void *ptr, int size, type, cast )
1724
1725=item RETVAL
1726
1727Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
5fb8527f
PP
1728This is always the proper type for the XSUB.
1729See L<perlxs/"The RETVAL Variable">.
cb1a09d0
AD
1730
1731=item safefree
1732
1733The XSUB-writer's interface to the C C<free> function.
1734
1735=item safemalloc
1736
1737The XSUB-writer's interface to the C C<malloc> function.
1738
1739=item saferealloc
1740
1741The XSUB-writer's interface to the C C<realloc> function.
1742
1743=item savepv
1744
1745Copy a string to a safe spot. This does not use an SV.
1746
1747 char* savepv _((char* sv));
1748
1749=item savepvn
1750
1751Copy a string to a safe spot. The C<len> indicates number of bytes to
1752copy. This does not use an SV.
1753
1754 char* savepvn _((char* sv, I32 len));
1755
1756=item SAVETMPS
1757
1758Opening bracket for temporaries on a callback. See C<FREETMPS> and
1759L<perlcall>.
1760
1761 SAVETMPS;
1762
1763=item SP
1764
1765Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1766C<SPAGAIN>.
1767
1768=item SPAGAIN
1769
5f05dabc 1770Re-fetch the stack pointer. Used after a callback. See L<perlcall>.
cb1a09d0
AD
1771
1772 SPAGAIN;
1773
1774=item ST
1775
1776Used to access elements on the XSUB's stack.
1777
1778 SV* ST(int x)
1779
1780=item strEQ
1781
1782Test two strings to see if they are equal. Returns true or false.
1783
1784 int strEQ( char *s1, char *s2 )
1785
1786=item strGE
1787
1788Test two strings to see if the first, C<s1>, is greater than or equal to the
1789second, C<s2>. Returns true or false.
1790
1791 int strGE( char *s1, char *s2 )
1792
1793=item strGT
1794
1795Test two strings to see if the first, C<s1>, is greater than the second,
1796C<s2>. Returns true or false.
1797
1798 int strGT( char *s1, char *s2 )
1799
1800=item strLE
1801
1802Test two strings to see if the first, C<s1>, is less than or equal to the
1803second, C<s2>. Returns true or false.
1804
1805 int strLE( char *s1, char *s2 )
1806
1807=item strLT
1808
1809Test two strings to see if the first, C<s1>, is less than the second,
1810C<s2>. Returns true or false.
1811
1812 int strLT( char *s1, char *s2 )
1813
1814=item strNE
1815
1816Test two strings to see if they are different. Returns true or false.
1817
1818 int strNE( char *s1, char *s2 )
1819
1820=item strnEQ
1821
1822Test two strings to see if they are equal. The C<len> parameter indicates
1823the number of bytes to compare. Returns true or false.
1824
1825 int strnEQ( char *s1, char *s2 )
1826
1827=item strnNE
1828
1829Test two strings to see if they are different. The C<len> parameter
1830indicates the number of bytes to compare. Returns true or false.
1831
1832 int strnNE( char *s1, char *s2, int len )
1833
1834=item sv_2mortal
1835
1836Marks an SV as mortal. The SV will be destroyed when the current context
1837ends.
1838
1839 SV* sv_2mortal _((SV* sv));
1840
1841=item sv_bless
1842
1843Blesses an SV into a specified package. The SV must be an RV. The package
5f05dabc 1844must be designated by its stash (see C<gv_stashpv()>). The reference count of the
cb1a09d0
AD
1845SV is unaffected.
1846
1847 SV* sv_bless _((SV* sv, HV* stash));
1848
1849=item sv_catpv
1850
1851Concatenates the string onto the end of the string which is in the SV.
1852
1853 void sv_catpv _((SV* sv, char* ptr));
1854
1855=item sv_catpvn
1856
1857Concatenates the string onto the end of the string which is in the SV. The
1858C<len> indicates number of bytes to copy.
1859
1860 void sv_catpvn _((SV* sv, char* ptr, STRLEN len));
1861
1862=item sv_catsv
1863
5fb8527f 1864Concatenates the string from SV C<ssv> onto the end of the string in SV
cb1a09d0
AD
1865C<dsv>.
1866
1867 void sv_catsv _((SV* dsv, SV* ssv));
1868
5fb8527f
PP
1869=item sv_cmp
1870
1871Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1872string in C<sv1> is less than, equal to, or greater than the string in
1873C<sv2>.
1874
1875 I32 sv_cmp _((SV* sv1, SV* sv2));
1876
1877=item sv_cmp
1878
1879Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1880string in C<sv1> is less than, equal to, or greater than the string in
1881C<sv2>.
1882
1883 I32 sv_cmp _((SV* sv1, SV* sv2));
1884
cb1a09d0
AD
1885=item SvCUR
1886
1887Returns the length of the string which is in the SV. See C<SvLEN>.
1888
1889 int SvCUR (SV* sv)
1890
1891=item SvCUR_set
1892
1893Set the length of the string which is in the SV. See C<SvCUR>.
1894
1895 SvCUR_set (SV* sv, int val )
1896
5fb8527f
PP
1897=item sv_dec
1898
5f05dabc 1899Auto-decrement of the value in the SV.
5fb8527f
PP
1900
1901 void sv_dec _((SV* sv));
1902
1903=item sv_dec
1904
5f05dabc 1905Auto-decrement of the value in the SV.
5fb8527f
PP
1906
1907 void sv_dec _((SV* sv));
1908
cb1a09d0
AD
1909=item SvEND
1910
1911Returns a pointer to the last character in the string which is in the SV.
1912See C<SvCUR>. Access the character as
1913
1914 *SvEND(sv)
1915
5fb8527f
PP
1916=item sv_eq
1917
1918Returns a boolean indicating whether the strings in the two SVs are
1919identical.
1920
1921 I32 sv_eq _((SV* sv1, SV* sv2));
1922
cb1a09d0
AD
1923=item SvGROW
1924
5fb8527f
PP
1925Expands the character buffer in the SV. Calls C<sv_grow> to perform the
1926expansion if necessary. Returns a pointer to the character buffer.
cb1a09d0
AD
1927
1928 char * SvGROW( SV* sv, int len )
1929
5fb8527f
PP
1930=item sv_grow
1931
1932Expands the character buffer in the SV. This will use C<sv_unref> and will
1933upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
1934Use C<SvGROW>.
1935
1936=item sv_inc
1937
5f05dabc 1938Auto increment of the value in the SV.
5fb8527f
PP
1939
1940 void sv_inc _((SV* sv));
1941
cb1a09d0
AD
1942=item SvIOK
1943
1944Returns a boolean indicating whether the SV contains an integer.
1945
1946 int SvIOK (SV* SV)
1947
1948=item SvIOK_off
1949
1950Unsets the IV status of an SV.
1951
1952 SvIOK_off (SV* sv)
1953
1954=item SvIOK_on
1955
1956Tells an SV that it is an integer.
1957
1958 SvIOK_on (SV* sv)
1959
5fb8527f
PP
1960=item SvIOK_only
1961
1962Tells an SV that it is an integer and disables all other OK bits.
1963
1964 SvIOK_on (SV* sv)
1965
1966=item SvIOK_only
1967
1968Tells an SV that it is an integer and disables all other OK bits.
1969
1970 SvIOK_on (SV* sv)
1971
cb1a09d0
AD
1972=item SvIOKp
1973
1974Returns a boolean indicating whether the SV contains an integer. Checks the
1975B<private> setting. Use C<SvIOK>.
1976
1977 int SvIOKp (SV* SV)
1978
1979=item sv_isa
1980
1981Returns a boolean indicating whether the SV is blessed into the specified
1982class. This does not know how to check for subtype, so it doesn't work in
1983an inheritance relationship.
1984
1985 int sv_isa _((SV* sv, char* name));
1986
1987=item SvIV
1988
1989Returns the integer which is in the SV.
1990
1991 int SvIV (SV* sv)
1992
1993=item sv_isobject
1994
1995Returns a boolean indicating whether the SV is an RV pointing to a blessed
1996object. If the SV is not an RV, or if the object is not blessed, then this
1997will return false.
1998
1999 int sv_isobject _((SV* sv));
2000
2001=item SvIVX
2002
2003Returns the integer which is stored in the SV.
2004
2005 int SvIVX (SV* sv);
2006
2007=item SvLEN
2008
2009Returns the size of the string buffer in the SV. See C<SvCUR>.
2010
2011 int SvLEN (SV* sv)
2012
5fb8527f
PP
2013=item sv_len
2014
2015Returns the length of the string in the SV. Use C<SvCUR>.
2016
2017 STRLEN sv_len _((SV* sv));
2018
2019=item sv_len
2020
2021Returns the length of the string in the SV. Use C<SvCUR>.
2022
2023 STRLEN sv_len _((SV* sv));
2024
cb1a09d0
AD
2025=item sv_magic
2026
2027Adds magic to an SV.
2028
2029 void sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
2030
2031=item sv_mortalcopy
2032
2033Creates a new SV which is a copy of the original SV. The new SV is marked
5f05dabc 2034as mortal.
cb1a09d0
AD
2035
2036 SV* sv_mortalcopy _((SV* oldsv));
2037
2038=item SvOK
2039
2040Returns a boolean indicating whether the value is an SV.
2041
2042 int SvOK (SV* sv)
2043
2044=item sv_newmortal
2045
5f05dabc 2046Creates a new SV which is mortal. The reference count of the SV is set to 1.
cb1a09d0
AD
2047
2048 SV* sv_newmortal _((void));
2049
2050=item sv_no
2051
2052This is the C<false> SV. See C<sv_yes>. Always refer to this as C<&sv_no>.
2053
2054=item SvNIOK
2055
2056Returns a boolean indicating whether the SV contains a number, integer or
2057double.
2058
2059 int SvNIOK (SV* SV)
2060
2061=item SvNIOK_off
2062
2063Unsets the NV/IV status of an SV.
2064
2065 SvNIOK_off (SV* sv)
2066
2067=item SvNIOKp
2068
2069Returns a boolean indicating whether the SV contains a number, integer or
2070double. Checks the B<private> setting. Use C<SvNIOK>.
2071
2072 int SvNIOKp (SV* SV)
2073
2074=item SvNOK
2075
2076Returns a boolean indicating whether the SV contains a double.
2077
2078 int SvNOK (SV* SV)
2079
2080=item SvNOK_off
2081
2082Unsets the NV status of an SV.
2083
2084 SvNOK_off (SV* sv)
2085
2086=item SvNOK_on
2087
2088Tells an SV that it is a double.
2089
2090 SvNOK_on (SV* sv)
2091
5fb8527f
PP
2092=item SvNOK_only
2093
2094Tells an SV that it is a double and disables all other OK bits.
2095
2096 SvNOK_on (SV* sv)
2097
2098=item SvNOK_only
2099
2100Tells an SV that it is a double and disables all other OK bits.
2101
2102 SvNOK_on (SV* sv)
2103
cb1a09d0
AD
2104=item SvNOKp
2105
2106Returns a boolean indicating whether the SV contains a double. Checks the
2107B<private> setting. Use C<SvNOK>.
2108
2109 int SvNOKp (SV* SV)
2110
2111=item SvNV
2112
2113Returns the double which is stored in the SV.
2114
2115 double SvNV (SV* sv);
2116
2117=item SvNVX
2118
2119Returns the double which is stored in the SV.
2120
2121 double SvNVX (SV* sv);
2122
2123=item SvPOK
2124
2125Returns a boolean indicating whether the SV contains a character string.
2126
2127 int SvPOK (SV* SV)
2128
2129=item SvPOK_off
2130
2131Unsets the PV status of an SV.
2132
2133 SvPOK_off (SV* sv)
2134
2135=item SvPOK_on
2136
2137Tells an SV that it is a string.
2138
2139 SvPOK_on (SV* sv)
2140
5fb8527f
PP
2141=item SvPOK_only
2142
2143Tells an SV that it is a string and disables all other OK bits.
2144
2145 SvPOK_on (SV* sv)
2146
2147=item SvPOK_only
2148
2149Tells an SV that it is a string and disables all other OK bits.
2150
2151 SvPOK_on (SV* sv)
2152
cb1a09d0
AD
2153=item SvPOKp
2154
2155Returns a boolean indicating whether the SV contains a character string.
2156Checks the B<private> setting. Use C<SvPOK>.
2157
2158 int SvPOKp (SV* SV)
2159
2160=item SvPV
2161
2162Returns a pointer to the string in the SV, or a stringified form of the SV
2163if the SV does not contain a string. If C<len> is C<na> then Perl will
2164handle the length on its own.
2165
2166 char * SvPV (SV* sv, int len )
2167
2168=item SvPVX
2169
2170Returns a pointer to the string in the SV. The SV must contain a string.
2171
2172 char * SvPVX (SV* sv)
2173
2174=item SvREFCNT
2175
5f05dabc 2176Returns the value of the object's reference count.
cb1a09d0
AD
2177
2178 int SvREFCNT (SV* sv);
2179
2180=item SvREFCNT_dec
2181
5f05dabc 2182Decrements the reference count of the given SV.
cb1a09d0
AD
2183
2184 void SvREFCNT_dec (SV* sv)
2185
2186=item SvREFCNT_inc
2187
5f05dabc 2188Increments the reference count of the given SV.
cb1a09d0
AD
2189
2190 void SvREFCNT_inc (SV* sv)
2191
2192=item SvROK
2193
2194Tests if the SV is an RV.
2195
2196 int SvROK (SV* sv)
2197
2198=item SvROK_off
2199
2200Unsets the RV status of an SV.
2201
2202 SvROK_off (SV* sv)
2203
2204=item SvROK_on
2205
2206Tells an SV that it is an RV.
2207
2208 SvROK_on (SV* sv)
2209
2210=item SvRV
2211
2212Dereferences an RV to return the SV.
2213
2214 SV* SvRV (SV* sv);
2215
2216=item sv_setiv
2217
2218Copies an integer into the given SV.
2219
2220 void sv_setiv _((SV* sv, IV num));
2221
2222=item sv_setnv
2223
2224Copies a double into the given SV.
2225
2226 void sv_setnv _((SV* sv, double num));
2227
2228=item sv_setpv
2229
2230Copies a string into an SV. The string must be null-terminated.
2231
2232 void sv_setpv _((SV* sv, char* ptr));
2233
2234=item sv_setpvn
2235
2236Copies a string into an SV. The C<len> parameter indicates the number of
2237bytes to be copied.
2238
2239 void sv_setpvn _((SV* sv, char* ptr, STRLEN len));
2240
2241=item sv_setref_iv
2242
5fb8527f
PP
2243Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2244argument will be upgraded to an RV. That RV will be modified to point to
2245the new SV. The C<classname> argument indicates the package for the
2246blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 2247will be returned and will have a reference count of 1.
cb1a09d0
AD
2248
2249 SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
2250
2251=item sv_setref_nv
2252
5fb8527f
PP
2253Copies a double into a new SV, optionally blessing the SV. The C<rv>
2254argument will be upgraded to an RV. That RV will be modified to point to
2255the new SV. The C<classname> argument indicates the package for the
2256blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 2257will be returned and will have a reference count of 1.
cb1a09d0
AD
2258
2259 SV* sv_setref_nv _((SV *rv, char *classname, double nv));
2260
2261=item sv_setref_pv
2262
5fb8527f
PP
2263Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2264argument will be upgraded to an RV. That RV will be modified to point to
2265the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
2266into the SV. The C<classname> argument indicates the package for the
2267blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
5f05dabc 2268will be returned and will have a reference count of 1.
cb1a09d0
AD
2269
2270 SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
2271
2272Do not use with integral Perl types such as HV, AV, SV, CV, because those
2273objects will become corrupted by the pointer copy process.
2274
2275Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2276
2277=item sv_setref_pvn
2278
5fb8527f
PP
2279Copies a string into a new SV, optionally blessing the SV. The length of the
2280string must be specified with C<n>. The C<rv> argument will be upgraded to
2281an RV. That RV will be modified to point to the new SV. The C<classname>
cb1a09d0
AD
2282argument indicates the package for the blessing. Set C<classname> to
2283C<Nullch> to avoid the blessing. The new SV will be returned and will have
5f05dabc 2284a reference count of 1.
cb1a09d0
AD
2285
2286 SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
2287
2288Note that C<sv_setref_pv> copies the pointer while this copies the string.
2289
2290=item sv_setsv
2291
2292Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
5f05dabc 2293The source SV may be destroyed if it is mortal.
cb1a09d0
AD
2294
2295 void sv_setsv _((SV* dsv, SV* ssv));
2296
2297=item SvSTASH
2298
2299Returns the stash of the SV.
2300
2301 HV * SvSTASH (SV* sv)
2302
2303=item SVt_IV
2304
2305Integer type flag for scalars. See C<svtype>.
2306
2307=item SVt_PV
2308
2309Pointer type flag for scalars. See C<svtype>.
2310
2311=item SVt_PVAV
2312
2313Type flag for arrays. See C<svtype>.
2314
2315=item SVt_PVCV
2316
2317Type flag for code refs. See C<svtype>.
2318
2319=item SVt_PVHV
2320
2321Type flag for hashes. See C<svtype>.
2322
2323=item SVt_PVMG
2324
2325Type flag for blessed scalars. See C<svtype>.
2326
2327=item SVt_NV
2328
2329Double type flag for scalars. See C<svtype>.
2330
2331=item SvTRUE
2332
2333Returns a boolean indicating whether Perl would evaluate the SV as true or
2334false, defined or undefined.
2335
2336 int SvTRUE (SV* sv)
2337
2338=item SvTYPE
2339
2340Returns the type of the SV. See C<svtype>.
2341
2342 svtype SvTYPE (SV* sv)
2343
2344=item svtype
2345
2346An enum of flags for Perl types. These are found in the file B<sv.h> in the
2347C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2348
2349=item SvUPGRADE
2350
5fb8527f
PP
2351Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
2352the upgrade if necessary. See C<svtype>.
2353
2354 bool SvUPGRADE _((SV* sv, svtype mt));
2355
2356=item sv_upgrade
2357
2358Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
cb1a09d0
AD
2359
2360=item sv_undef
2361
2362This is the C<undef> SV. Always refer to this as C<&sv_undef>.
2363
5fb8527f
PP
2364=item sv_unref
2365
5f05dabc 2366Unsets the RV status of the SV, and decrements the reference count of whatever was
5fb8527f
PP
2367being referenced by the RV. This can almost be thought of as a reversal of
2368C<newSVrv>. See C<SvROK_off>.
2369
2370 void sv_unref _((SV* sv));
2371
cb1a09d0
AD
2372=item sv_usepvn
2373
2374Tells an SV to use C<ptr> to find its string value. Normally the string is
5fb8527f
PP
2375stored inside the SV but sv_usepvn allows the SV to use an outside string.
2376The C<ptr> should point to memory that was allocated by C<malloc>. The
cb1a09d0
AD
2377string length, C<len>, must be supplied. This function will realloc the
2378memory pointed to by C<ptr>, so that pointer should not be freed or used by
2379the programmer after giving it to sv_usepvn.
2380
2381 void sv_usepvn _((SV* sv, char* ptr, STRLEN len));
2382
2383=item sv_yes
2384
2385This is the C<true> SV. See C<sv_no>. Always refer to this as C<&sv_yes>.
2386
2387=item THIS
2388
2389Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
2390This is always the proper type for the C++ object. See C<CLASS> and
5fb8527f 2391L<perlxs/"Using XS With C++">.
cb1a09d0
AD
2392
2393=item toLOWER
2394
2395Converts the specified character to lowercase.
2396
2397 int toLOWER (char c)
2398
2399=item toUPPER
2400
2401Converts the specified character to uppercase.
2402
2403 int toUPPER (char c)
2404
2405=item warn
2406
2407This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2408function the same way you use the C C<printf> function. See C<croak()>.
2409
2410=item XPUSHi
2411
2412Push an integer onto the stack, extending the stack if necessary. See
2413C<PUSHi>.
2414
2415 XPUSHi(int d)
2416
2417=item XPUSHn
2418
2419Push a double onto the stack, extending the stack if necessary. See
2420C<PUSHn>.
2421
2422 XPUSHn(double d)
2423
2424=item XPUSHp
2425
2426Push a string onto the stack, extending the stack if necessary. The C<len>
2427indicates the length of the string. See C<PUSHp>.
2428
2429 XPUSHp(char *c, int len)
2430
2431=item XPUSHs
2432
2433Push an SV onto the stack, extending the stack if necessary. See C<PUSHs>.
2434
2435 XPUSHs(sv)
2436
5fb8527f
PP
2437=item XS
2438
2439Macro to declare an XSUB and its C parameter list. This is handled by
2440C<xsubpp>.
2441
cb1a09d0
AD
2442=item XSRETURN
2443
2444Return from XSUB, indicating number of items on the stack. This is usually
2445handled by C<xsubpp>.
2446
5fb8527f 2447 XSRETURN(int x);
cb1a09d0
AD
2448
2449=item XSRETURN_EMPTY
2450
5fb8527f 2451Return an empty list from an XSUB immediately.
cb1a09d0
AD
2452
2453 XSRETURN_EMPTY;
2454
5fb8527f
PP
2455=item XSRETURN_IV
2456
2457Return an integer from an XSUB immediately. Uses C<XST_mIV>.
2458
2459 XSRETURN_IV(IV v);
2460
cb1a09d0
AD
2461=item XSRETURN_NO
2462
5fb8527f 2463Return C<&sv_no> from an XSUB immediately. Uses C<XST_mNO>.
cb1a09d0
AD
2464
2465 XSRETURN_NO;
2466
5fb8527f
PP
2467=item XSRETURN_NV
2468
2469Return an double from an XSUB immediately. Uses C<XST_mNV>.
2470
2471 XSRETURN_NV(NV v);
2472
2473=item XSRETURN_PV
2474
2475Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2476
2477 XSRETURN_PV(char *v);
2478
cb1a09d0
AD
2479=item XSRETURN_UNDEF
2480
5fb8527f 2481Return C<&sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
cb1a09d0
AD
2482
2483 XSRETURN_UNDEF;
2484
2485=item XSRETURN_YES
2486
5fb8527f 2487Return C<&sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
cb1a09d0
AD
2488
2489 XSRETURN_YES;
2490
5fb8527f
PP
2491=item XST_mIV
2492
2493Place an integer into the specified position C<i> on the stack. The value is
2494stored in a new mortal SV.
2495
2496 XST_mIV( int i, IV v );
2497
2498=item XST_mNV
2499
2500Place a double into the specified position C<i> on the stack. The value is
2501stored in a new mortal SV.
2502
2503 XST_mNV( int i, NV v );
2504
2505=item XST_mNO
2506
2507Place C<&sv_no> into the specified position C<i> on the stack.
2508
2509 XST_mNO( int i );
2510
2511=item XST_mPV
2512
2513Place a copy of a string into the specified position C<i> on the stack. The
2514value is stored in a new mortal SV.
2515
2516 XST_mPV( int i, char *v );
2517
2518=item XST_mUNDEF
2519
2520Place C<&sv_undef> into the specified position C<i> on the stack.
2521
2522 XST_mUNDEF( int i );
2523
2524=item XST_mYES
2525
2526Place C<&sv_yes> into the specified position C<i> on the stack.
2527
2528 XST_mYES( int i );
2529
2530=item XS_VERSION
2531
2532The version identifier for an XS module. This is usually handled
2533automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
2534
2535=item XS_VERSION_BOOTCHECK
2536
2537Macro to verify that a PM module's $VERSION variable matches the XS module's
2538C<XS_VERSION> variable. This is usually handled automatically by
2539C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
2540
cb1a09d0
AD
2541=item Zero
2542
2543The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
2544destination, C<n> is the number of items, and C<t> is the type.
2545
2546 (void) Zero( d, n, t );
2547
2548=back
2549
5f05dabc 2550=head1 EDITOR
cb1a09d0 2551
55497cff 2552Jeff Okamoto <okamoto@corp.hp.com>
cb1a09d0
AD
2553
2554With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2555Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
55497cff 2556Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer.
cb1a09d0 2557
55497cff 2558API Listing by Dean Roehrich <roehrich@cray.com>.
cb1a09d0
AD
2559
2560=head1 DATE
2561
5f05dabc 2562Version 25.2: 1996/12/16