Perl also uses two special typedefs, I32 and I16, which will always be at
least 32-bits and 16-bits long, respectively.
-=head2 Working with SV's
+=head2 Working with SVs
An SV can be created and loaded with one command. There are four types of
values that can be loaded: an integer value (IV), a double (NV), a string,
variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
care what the length of the data is, use the global variable C<na>. Remember,
however, that Perl allows arbitrary strings of data that may both contain
-NUL's and not be terminated by a NUL.
+NULs and not be terminated by a NUL.
If you simply want to know if the scalar value is TRUE, you can use:
This code tries to return a new SV (which contains the value 42) if it should
return a real value, or undef otherwise. Instead it has returned a null
pointer which, somewhere down the line, will cause a segmentation violation,
-or just weird results. Change the zero to C<&sv_undef> in the first line and
-all will be well.
+bus error, or just plain weird results. Change the zero to C<&sv_undef> in
+the first line and all will be well.
To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
-call is not necessary. See the section on B<MORTALITY>.
+call is not necessary. See the section on L<Mortality>.
=head2 What's Really Stored in an SV?
In general, though, it's best to just use the C<Sv*V> macros.
-=head2 Working with AV's
+=head2 Working with AVs
There are two ways to create and load an AV. The first method just creates
an empty AV:
AV* newAV();
-The second method both creates the AV and initially populates it with SV's:
+The second method both creates the AV and initially populates it with SVs:
AV* av_make(I32 num, SV **ptr);
-The second argument points to an array containing C<num> C<SV*>'s. Once the
-AV has been created, the SV's can be destroyed, if so desired.
+The second argument points to an array containing C<num> C<SV*>s. Once the
+AV has been created, the SVs can be destroyed, if so desired.
-Once the AV has been created, the following operations are possible on AV's:
+Once the AV has been created, the following operations are possible on AVs:
void av_push(AV*, SV*);
SV* av_pop(AV*);
SV** av_store(AV*, I32 key, SV* val);
/* Stores val at offset key */
-Take note that C<av_fetch> and C<av_store> return C<SV**>'s, not C<SV*>'s.
+Take note that C<av_fetch> and C<av_store> return C<SV**>s, not C<SV*>s.
void av_clear(AV*);
/* Clear out all elements, but leave the array */
This returns NULL if the variable does not exist.
-=head2 Working with HV's
+=head2 Working with HVs
To create an HV, you use the following routine:
HV* newHV();
-Once the HV has been created, the following operations are possible on HV's:
+Once the HV has been created, the following operations are possible on HVs:
SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
for you). The C<lval> parameter indicates whether this fetch is actually a
part of a store operation.
-Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
+Remember that C<hv_store> and C<hv_fetch> return C<SV**>s and not just
C<SV*>. In order to access the scalar value, you must first dereference
the return value. However, you should check to make sure that the return
value is not NULL before dereferencing it.
certain extra features. Those bits are:
0x02 Marks the variable as multiply defined, thus preventing the
- "Indentifier <varname> used only once: possible typo" warning.
+ "Identifier <varname> used only once: possible typo" warning.
0x04 Issues a "Had to create <varname> unexpectedly" warning if
the variable didn't actually exist. This is useful if
you expected the variable to already exist and want to propagate
If the C<varname> argument does not contain a package specifier, it is
created in the current package.
-=head1 XSUB's and the Argument Stack
+=head1 XSUBs and the Argument Stack
The XSUB mechanism is a simple way for Perl programs to access C subroutines.
An XSUB routine will have a stack that contains the arguments from the Perl
stack should be extended by.
Now that there is room on the stack, values can be pushed on it using the
-macros to push IV's, doubles, strings, and SV pointers respectively:
+macros to push IVs, doubles, strings, and SV pointers respectively:
PUSHi(IV)
PUSHn(double)
XPUSHp(char*, I32)
XPUSHs(SV*)
-These macros automatically adjust the stack for you, if needed.
+These macros automatically adjust the stack for you, if needed. Thus, you
+do not need to call C<EXTEND> to extend the stack.
For more information, consult L<perlxs>.
-=head1 Mortality
+=head1 Localizing Changes
+
+Perl has a very handy construction
+
+ {
+ local $var = 2;
+ ...
+ }
+
+This construction is I<approximately> equivalent to
+
+ {
+ my $oldvar = $var;
+ $var = 2;
+ ...
+ $var = $oldvar;
+ }
+
+The biggest difference is that the first construction would would
+reinstate the initial value of $var, irrespective of how control exits
+the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
+more efficient as well.
+
+There is a way to achieve a similar task from C via Perl API: create a
+I<pseudo-block>, and arrange for some changes to be automatically
+undone at the end of it, either explicit, or via a non-local exit (via
+die()). A I<block>-like construct is created by a pair of
+C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a
+Scalar">). Such a construct may be created specially for some
+important localized task, or an existing one (like boundaries of
+enclosing Perl subroutine/block, or an existing pair for freeing TMPs)
+may be used. (In the second case the overhead of additional
+localization must be almost negligible.) Note that any XSUB is
+automatically enclosed in an C<ENTER>/C<LEAVE> pair.
+
+Inside such a I<pseudo-block> the following service is available:
+
+=over
+
+=item C<SAVEINT(int i)>
+
+=item C<SAVEIV(IV i)>
+
+=item C<SAVEI16(I16 i)>
+
+=item C<SAVEI32(I32 i)>
+
+=item C<SAVELONG(long i)>
+
+These macros arrange things to restore the value of integer variable
+C<i> at the end of enclosing I<pseudo-block>.
+
+=item C<SAVESPTR(p)>
+
+=item C<SAVEPPTR(s)>
+
+These macros arrange things to restore the value of pointers C<s> and
+C<p>. C<p> must be a pointer of a type which survives conversion to
+C<SV*> and back, C<s> should be able to survive conversion to C<char*>
+and back.
+
+=item C<SAVEFREESV(SV *sv)>
+
+The refcount of C<sv> would be decremented at the end of
+I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
+used instead.
+
+=item C<SAVEFREEOP(OP *op)>
+
+The C<OP *> is op_free()ed at the end of I<pseudo-block>.
+
+=item C<SAVEFREEPV(p)>
+
+The chunk of memory which is pointed to by C<p> is Safefree()ed at the
+end of I<pseudo-block>.
+
+=item C<SAVECLEARSV(SV *sv)>
+
+Clears a slot in the current scratchpad which corresponds to C<sv> at
+the end of I<pseudo-block>.
+
+=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
+
+The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
+string pointed to by C<key> is Safefree()ed. If one has a I<key> in
+short-lived storage, the corresponding string may be reallocated like
+this:
+
+ SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf));
+
+=item C<SAVEDESTRUCTOR(f,p)>
+
+At the end of I<pseudo-block> the function C<f> is called with the
+only argument (of type C<void*>) C<p>.
+
+=item C<SAVESTACK_POS()>
+
+The current offset on the Perl internal stack (cf. C<SP>) is restored
+at the end of I<pseudo-block>.
+
+=back
+
+The following API list contains functions, thus one needs to
+provide pointers to the modifiable data explicitly (either C pointers,
+or Perlish C<GV *>s):
+
+=over
+
+=item C<SV* save_scalar(GV *gv)>
+
+Equivalent to Perl code C<local $gv>.
+
+=item C<AV* save_ary(GV *gv)>
-In Perl, values are normally "immortal" -- that is, they are not freed unless
-explicitly done so (via the Perl C<undef> call or other routines in Perl
-itself).
+=item C<HV* save_hash(GV *gv)>
-Add cruft about reference counts.
- int SvREFCNT(SV* sv);
- void SvREFCNT_inc(SV* sv);
- void SvREFCNT_dec(SV* sv);
+Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
-In the above example with C<tzname>, we needed to create two new SV's to push
-onto the argument stack, that being the two strings. However, we don't want
-these new SV's to stick around forever because they will eventually be
-copied into the SV's that hold the two scalar variables.
+=item C<void save_item(SV *item)>
-An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal"
-SV, AV, or HV, but is only valid in the "current context". When the Perl
-interpreter leaves the current context, the mortal SV, AV, or HV is
-automatically freed. Generally the "current context" means a single
-Perl statement.
+Duplicates the current value of C<SV>, on the exit from the current
+C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
+using the stored value.
+
+=item C<void save_list(SV **sarg, I32 maxsarg)>
+
+A variant of C<save_item> which takes multiple arguments via an array
+C<sarg> of C<SV*> of length C<maxsarg>.
+
+=item C<SV* save_svref(SV **sptr)>
+
+Similar to C<save_scalar>, but will reinstate a C<SV *>.
+
+=item C<void save_aptr(AV **aptr)>
+
+=item C<void save_hptr(HV **hptr)>
+
+Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
+
+=item C<void save_nogv(GV *gv)>
+
+Will postpone destruction of a I<stub> glob.
+
+=back
+
+=head1 Mortality
+
+Perl uses an reference count-driven garbage collection mechanism. SV's,
+AV's, or HV's (xV for short in the following) start their life with a
+reference count of 1. If the reference count of an xV ever drops to 0,
+then they will be destroyed and their memory made available for reuse.
+
+This normally doesn't happen at the Perl level unless a variable is
+undef'ed. At the internal level, however, reference counts can be
+manipulated with the following macros:
+
+ int SvREFCNT(SV* sv);
+ void SvREFCNT_inc(SV* sv);
+ void SvREFCNT_dec(SV* sv);
+
+However, there is one other function which manipulates the reference
+count of its argument. The C<newRV> function, as you should recall,
+creates a reference to the specified argument. As a side effect, it
+increments the argument's reference count, which is ok in most
+circumstances. But imagine you want to return a reference from an XS
+function. You create a new SV which initially has a reference count
+of 1. Then you call C<newRV>, passing the just-created SV. This returns
+the reference as a new SV, but the reference count of the SV you passed
+to C<newRV> has been incremented to 2. Now you return the reference and
+forget about the SV. But Perl hasn't! Whenever the returned reference
+is destroyed, the reference count of the original SV is decreased to 1
+and nothing happens. The SV will hang around without any way to access
+it until Perl itself terminates. This is a memory leak.
+
+The correct procedure, then, is to call C<SvREFCNT_dec> on the SV after
+C<newRV> has returned. Then, if and when the reference is destroyed,
+the reference count of the SV will go to 0 and also be destroyed, stopping
+any memory leak.
+
+There are some convenience functions available that can help with this
+process. These functions introduce the concept of "mortality". An xV
+that is mortal has had its reference count marked to be decremented,
+but not actually decremented, until the "current context" is left.
+Generally the "current context" means a single Perl statement, such as
+a call to an XSUB function.
+
+"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
+However, if you mortalize a variable twice, the reference count will
+later be decremented twice.
+
+You should be careful about creating mortal variables. Strange things
+can happen if you make the same value mortal within multiple contexts,
+or if you make a variable mortal multiple times. Doing the latter can
+cause a variable to become invalid prematurely.
To create a mortal variable, use the functions:
The first call creates a mortal SV, the second converts an existing SV to
a mortal SV, the third creates a mortal copy of an existing SV.
-The mortal routines are not just for SV's -- AV's and HV's can be made mortal
+The mortal routines are not just for SVs -- AVs and HVs can be made mortal
by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
C<sv_mortalcopy> routines.
->From Ilya:
+I<From Ilya:>
Beware that the sv_2mortal() call is eventually equivalent to
svREFCNT_dec(). A value can happily be mortal in two different contexts,
and it will be svREFCNT_dec()ed twice, once on exit from these
times as it is needed. The value that go to the Perl stack I<should>
be mortal.
-You should be careful about creating mortal variables. It is possible for
-strange things to happen should you make the same value mortal within
-multiple contexts.
=head1 Stashes
Perl stores various stashes in a separate GV structure (for global
variable) but represents them with an HV structure. The keys in this
-larger GV are the various package names; the values are the C<GV*>'s
+larger GV are the various package names; the values are the C<GV*>s
which are stashes. It may help to think of a stash purely as an HV,
and that the term "GV" means the global variable hash.
[This section still under construction. Ignore everything here. Post no
bills. Everything not permitted is forbidden.]
-# Version 6, 1995/1/27
-
Any SV may be magical, that is, it has special features that a normal
SV does not have. These features are stored in the SV structure in a
-linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
+linked list of C<struct magic>s, typedef'ed to C<MAGIC>.
struct magic {
MAGIC* mg_moremagic;
set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
it to the beginning of the linked list of magical features. Any prior
entry of the same type of magic is deleted. Note that this can be
-overriden, and multiple instances of the same type of magic can be
+overridden, and multiple instances of the same type of magic can be
associated with an SV.
The C<name> and C<namlem> arguments are used to associate a string with
field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
the mg_type field is changed to be the lower-case letter.
-=head1 Double-Typed SV's
+=head1 Double-Typed SVs
Scalar variables normally contain only one type of value, an integer,
double, pointer, or reference. Perl will automatically convert the
=item av_make
-Creats a new AV and populates it with a list of SVs. The SVs are copied
-into the array, so they may be freed after the call to av_make.
+Creates a new AV and populates it with a list of SVs. The SVs are copied
+into the array, so they may be freed after the call to av_make. The new AV
+will have a refcount of 1.
AV* av_make _((I32 size, SV** svp));
=item av_push
-Pushes an SV onto the end of the array.
+Pushes an SV onto the end of the array. The array will grow automatically
+to accommodate the addition.
void av_push _((AV* ar, SV* val));
=item av_unshift
-Unshift an SV onto the beginning of the array.
+Unshift an SV onto the beginning of the array. The array will grow
+automatically to accommodate the addition.
void av_unshift _((AV* ar, I32 num));
=item CLASS
Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
-constructor. This is always a C<char*>. See C<THIS> and L<perlxs>.
+constructor. This is always a C<char*>. See C<THIS> and
+L<perlxs/"Using XS With C++">.
=item Copy
When Perl is run in debugging mode, with the B<-d> switch, this SV is a
boolean which indicates whether subs are being single-stepped.
-Single-stepping is automatically turned on after every step. See C<DBsub>.
+Single-stepping is automatically turned on after every step. This is the C
+variable which corresponds to Perl's $DB::single variable. See C<DBsub>.
=item DBsub
When Perl is run in debugging mode, with the B<-d> switch, this GV contains
-the SV which holds the name of the sub being debugged. See C<DBsingle>.
+the SV which holds the name of the sub being debugged. This is the C
+variable which corresponds to Perl's $DB::sub variable. See C<DBsingle>.
The sub name can be found by
SvPV( GvSV( DBsub ), na )
+=item DBtrace
+
+Trace variable used when Perl is run in debugging mode, with the B<-d>
+switch. This is the C variable which corresponds to Perl's $DB::trace
+variable. See C<DBsingle>.
+
=item dMARK
-Declare a stack marker for the XSUB. See C<MARK> and C<dORIGMARK>.
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
=item dORIGMARK
Saves the original stack mark for the XSUB. See C<ORIGMARK>.
+=item dowarn
+
+The C variable which corresponds to Perl's $^W warning variable.
+
=item dSP
-Declares a stack pointer for the XSUB. See C<SP>.
+Declares a stack pointer variable, C<sp>, for the XSUB. See C<SP>.
=item dXSARGS
usually handled automatically by C<xsubpp>. Declares the C<items> variable
to indicate the number of items on the stack.
+=item dXSI32
+
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
+
+=item dXSI32
+
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
+
=item ENTER
Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
=item hv_delete
Deletes a key/value pair in the hash. The value SV is removed from the hash
-and returned to the caller. The C<lken> is the length of the key. The
+and returned to the caller. The C<klen> is the length of the key. The
C<flags> value will normally be zero; if set to G_DISCARD then null will be
returned.
=item hv_exists
Returns a boolean indicating whether the specified hash key exists. The
-C<lken> is the length of the key.
+C<klen> is the length of the key.
bool hv_exists _((HV* tb, char* key, U32 klen));
=item hv_fetch
Returns the SV which corresponds to the specified key in the hash. The
-C<lken> is the length of the key. If C<lval> is set then the fetch will be
+C<klen> is the length of the key. If C<lval> is set then the fetch will be
part of a store. Check that the return value is non-null before
dereferencing it to a C<SV*>.
=item isALNUM
Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
-character or digit.
+character.
int isALNUM (char c)
=item isALPHA
-Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
+Returns a boolean indicating whether the C C<char> is an ascii alphabetic
character.
int isALPHA (char c)
=item items
Variable which is setup by C<xsubpp> to indicate the number of items on the
-stack. See L<perlxs>.
+stack. See L<perlxs/"Variable-length Parameter Lists">.
+
+=item ix
+
+Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
+was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
=item LEAVE
=item MARK
-Stack marker for the XSUB. See C<dMARK>.
+Stack marker variable for the XSUB. See C<dMARK>.
=item mg_clear
=item newSVrv
Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
-it will be upgraded one. If C<classname> is non-null then the new SV will
+it will be upgraded to one. If C<classname> is non-null then the new SV will
be blessed in the specified package. The new SV is returned and its
refcount is 1.
=item newSVsv
-Creates a new SV which is an exact duplicate of the orignal SV.
+Creates a new SV which is an exact duplicate of the original SV.
SV* newSVsv _((SV* old));
=item RETVAL
Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
-This is always the proper type for the XSUB. See L<perlxs>.
+This is always the proper type for the XSUB.
+See L<perlxs/"The RETVAL Variable">.
=item safefree
=item sv_catsv
-Concatentates the string from SV C<ssv> onto the end of the string in SV
+Concatenates the string from SV C<ssv> onto the end of the string in SV
C<dsv>.
void sv_catsv _((SV* dsv, SV* ssv));
+=item sv_cmp
+
+Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
+string in C<sv1> is less than, equal to, or greater than the string in
+C<sv2>.
+
+ I32 sv_cmp _((SV* sv1, SV* sv2));
+
+=item sv_cmp
+
+Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
+string in C<sv1> is less than, equal to, or greater than the string in
+C<sv2>.
+
+ I32 sv_cmp _((SV* sv1, SV* sv2));
+
=item SvCUR
Returns the length of the string which is in the SV. See C<SvLEN>.
SvCUR_set (SV* sv, int val )
+=item sv_dec
+
+Autodecrement of the value in the SV.
+
+ void sv_dec _((SV* sv));
+
+=item sv_dec
+
+Autodecrement of the value in the SV.
+
+ void sv_dec _((SV* sv));
+
=item SvEND
Returns a pointer to the last character in the string which is in the SV.
*SvEND(sv)
+=item sv_eq
+
+Returns a boolean indicating whether the strings in the two SVs are
+identical.
+
+ I32 sv_eq _((SV* sv1, SV* sv2));
+
=item SvGROW
-Expands the character buffer in the SV.
+Expands the character buffer in the SV. Calls C<sv_grow> to perform the
+expansion if necessary. Returns a pointer to the character buffer.
char * SvGROW( SV* sv, int len )
+=item sv_grow
+
+Expands the character buffer in the SV. This will use C<sv_unref> and will
+upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
+Use C<SvGROW>.
+
+=item sv_inc
+
+Autoincrement of the value in the SV.
+
+ void sv_inc _((SV* sv));
+
=item SvIOK
Returns a boolean indicating whether the SV contains an integer.
SvIOK_on (SV* sv)
+=item SvIOK_only
+
+Tells an SV that it is an integer and disables all other OK bits.
+
+ SvIOK_on (SV* sv)
+
+=item SvIOK_only
+
+Tells an SV that it is an integer and disables all other OK bits.
+
+ SvIOK_on (SV* sv)
+
=item SvIOKp
Returns a boolean indicating whether the SV contains an integer. Checks the
int SvLEN (SV* sv)
+=item sv_len
+
+Returns the length of the string in the SV. Use C<SvCUR>.
+
+ STRLEN sv_len _((SV* sv));
+
+=item sv_len
+
+Returns the length of the string in the SV. Use C<SvCUR>.
+
+ STRLEN sv_len _((SV* sv));
+
=item sv_magic
Adds magic to an SV.
SvNOK_on (SV* sv)
+=item SvNOK_only
+
+Tells an SV that it is a double and disables all other OK bits.
+
+ SvNOK_on (SV* sv)
+
+=item SvNOK_only
+
+Tells an SV that it is a double and disables all other OK bits.
+
+ SvNOK_on (SV* sv)
+
=item SvNOKp
Returns a boolean indicating whether the SV contains a double. Checks the
SvPOK_on (SV* sv)
+=item SvPOK_only
+
+Tells an SV that it is a string and disables all other OK bits.
+
+ SvPOK_on (SV* sv)
+
+=item SvPOK_only
+
+Tells an SV that it is a string and disables all other OK bits.
+
+ SvPOK_on (SV* sv)
+
=item SvPOKp
Returns a boolean indicating whether the SV contains a character string.
=item sv_setref_iv
-Copies an integer into an SV, optionally blessing the SV. The SV must be an
-RV. The C<classname> argument indicates the package for the blessing. Set
-C<classname> to C<Nullch> to avoid the blessing. The new SV will be
-returned and will have a refcount of 1.
+Copies an integer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a refcount of 1.
SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
=item sv_setref_nv
-Copies a double into an SV, optionally blessing the SV. The SV must be an
-RV. The C<classname> argument indicates the package for the blessing. Set
-C<classname> to C<Nullch> to avoid the blessing. The new SV will be
-returned and will have a refcount of 1.
+Copies a double into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a refcount of 1.
SV* sv_setref_nv _((SV *rv, char *classname, double nv));
=item sv_setref_pv
-Copies a pointer into an SV, optionally blessing the SV. The SV must be an
-RV. If the C<pv> argument is NULL then C<sv_undef> will be placed into the
-SV. The C<classname> argument indicates the package for the blessing. Set
-C<classname> to C<Nullch> to avoid the blessing. The new SV will be
-returned and will have a refcount of 1.
+Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
+into the SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a refcount of 1.
SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
=item sv_setref_pvn
-Copies a string into an SV, optionally blessing the SV. The lenth of the
-string must be specified with C<n>. The SV must be an RV. The C<classname>
+Copies a string into a new SV, optionally blessing the SV. The length of the
+string must be specified with C<n>. The C<rv> argument will be upgraded to
+an RV. That RV will be modified to point to the new SV. The C<classname>
argument indicates the package for the blessing. Set C<classname> to
C<Nullch> to avoid the blessing. The new SV will be returned and will have
a refcount of 1.
=item sv_setsv
Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
-(B<NOTE:> If C<ssv> has the C<SVs_TEMP> bit set, C<sv_setsv> may simply steal
-the string from C<ssv> and give it to C<dsv>, leaving C<ssv> empty.
-Caveat caller.)
+The source SV may be destroyed if it is mortal.
void sv_setsv _((SV* dsv, SV* ssv));
=item SvUPGRADE
-Used to upgrade an SV to a more complex form. See C<svtype>.
+Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
+the upgrade if necessary. See C<svtype>.
+
+ bool SvUPGRADE _((SV* sv, svtype mt));
+
+=item sv_upgrade
+
+Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
=item sv_undef
This is the C<undef> SV. Always refer to this as C<&sv_undef>.
+=item sv_unref
+
+Unsets the RV status of the SV, and decrements the refcount of whatever was
+being referenced by the RV. This can almost be thought of as a reversal of
+C<newSVrv>. See C<SvROK_off>.
+
+ void sv_unref _((SV* sv));
+
=item sv_usepvn
Tells an SV to use C<ptr> to find its string value. Normally the string is
-stored inside the SV; this allows the SV to use an outside string. The
+stored inside the SV but sv_usepvn allows the SV to use an outside string.
+The C<ptr> should point to memory that was allocated by C<malloc>. The
string length, C<len>, must be supplied. This function will realloc the
memory pointed to by C<ptr>, so that pointer should not be freed or used by
the programmer after giving it to sv_usepvn.
Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
This is always the proper type for the C++ object. See C<CLASS> and
-L<perlxs>.
+L<perlxs/"Using XS With C++">.
=item toLOWER
XPUSHs(sv)
+=item XS
+
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
+
=item XSRETURN
Return from XSUB, indicating number of items on the stack. This is usually
handled by C<xsubpp>.
- XSRETURN(x);
+ XSRETURN(int x);
=item XSRETURN_EMPTY
-Return from an XSUB immediately.
+Return an empty list from an XSUB immediately.
XSRETURN_EMPTY;
+=item XSRETURN_IV
+
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
+
+ XSRETURN_IV(IV v);
+
=item XSRETURN_NO
-Return C<false> from an XSUB immediately.
+Return C<&sv_no> from an XSUB immediately. Uses C<XST_mNO>.
XSRETURN_NO;
+=item XSRETURN_NV
+
+Return an double from an XSUB immediately. Uses C<XST_mNV>.
+
+ XSRETURN_NV(NV v);
+
+=item XSRETURN_PV
+
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
+
+ XSRETURN_PV(char *v);
+
=item XSRETURN_UNDEF
-Return C<undef> from an XSUB immediately.
+Return C<&sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
XSRETURN_UNDEF;
=item XSRETURN_YES
-Return C<true> from an XSUB immediately.
+Return C<&sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
XSRETURN_YES;
+=item XST_mIV
+
+Place an integer into the specified position C<i> on the stack. The value is
+stored in a new mortal SV.
+
+ XST_mIV( int i, IV v );
+
+=item XST_mNV
+
+Place a double into the specified position C<i> on the stack. The value is
+stored in a new mortal SV.
+
+ XST_mNV( int i, NV v );
+
+=item XST_mNO
+
+Place C<&sv_no> into the specified position C<i> on the stack.
+
+ XST_mNO( int i );
+
+=item XST_mPV
+
+Place a copy of a string into the specified position C<i> on the stack. The
+value is stored in a new mortal SV.
+
+ XST_mPV( int i, char *v );
+
+=item XST_mUNDEF
+
+Place C<&sv_undef> into the specified position C<i> on the stack.
+
+ XST_mUNDEF( int i );
+
+=item XST_mYES
+
+Place C<&sv_yes> into the specified position C<i> on the stack.
+
+ XST_mYES( int i );
+
+=item XS_VERSION
+
+The version identifier for an XS module. This is usually handled
+automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
+
+=item XS_VERSION_BOOTCHECK
+
+Macro to verify that a PM module's $VERSION variable matches the XS module's
+C<XS_VERSION> variable. This is usually handled automatically by
+C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
+
=item Zero
The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
-Bowers, Matthew Green, Tim Bunce, and Spider Boardman.
+Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer.
API Listing by Dean Roehrich <roehrich@cray.com>.
=head1 DATE
-Version 20: 1995/12/14
-
+Version 23.1: 1996/10/19
https://perl5.git.perl.org / perl5.git / blobdiff