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