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