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