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,
string's length by using C<strlen>, which depends on the string terminating
with a NUL character.
-All SV's that will contain strings should, but need not, be terminated
+All SVs that will contain strings should, but need not, be terminated
with a NUL character. If it is not NUL-terminated there is a risk of
core dumps and corruptions from code which passes the string to C
functions or system calls which expect a NUL-terminated 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 might not be terminated by a NUL.
+NULs and might not be terminated by a NUL.
If you want to know if the scalar value is TRUE, you can use:
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 L<Reference Counts and Mortality>).
+call is not necessary (see L<Reference Counts and Mortality>).
=head2 What's Really Stored in an SV?
In general, though, it's best to 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 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.
+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*);
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);
The C<klen> parameter is the length of the key being passed in (Note that
you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
length of the key). The C<val> argument contains the SV pointer to the
-scalar being stored, and C<hash> is the pre-computed hash value (zero if
+scalar being stored, and C<hash> is the precomputed hash value (zero if
you want C<hv_store> to calculate it for you). The C<lval> parameter
indicates whether this fetch is actually a part of a store operation, in
which case a new undefined value will be added to the HV with the supplied
SV* sv_bless(SV* sv, HV* stash);
The C<sv> argument must be a reference. The C<stash> argument specifies
-which class the reference will belong to. See the section on
+which class the reference will belong to. See
L<Stashes and Globs> for information on converting class names into stashes.
/* Still under construction */
C<TRUE> argument to enable certain extra features. Those bits are:
GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
- "Indentifier <varname> used only once: possible typo" warning.
+ "Name <varname> used only once: possible typo" warning.
GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
the variable did not exist before the function was called.
=head2 Reference Counts and 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
+Perl uses an reference count-driven garbage collection mechanism. SVs,
+AVs, or HVs (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 it will be destroyed and its memory made available for reuse.
stopping any memory leak.
There are some convenience functions available that can help with the
-destruction of xV's. These functions introduce the concept of "mortality".
+destruction of xVs. 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 "a short time later". Generally the
term "short time later" means a single Perl statement, such as a call to
-an XSUB function. The actual determinant for when mortal xV's have their
+an XSUB function. The actual determinant for when mortal xVs have their
reference count decremented depends on two macros, SAVETMPS and FREETMPS.
See L<perlcall> and L<perlxs> for more details on these macros.
SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and 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
+The mortal routines are not just for SVs -- AVs and HVs can be
made mortal by passing their address (type-casted to C<SV*>) to the
C<sv_2mortal> or C<sv_mortalcopy> routines.
For more information on references and blessings, consult L<perlref>.
-=head2 Double-Typed SV's
+=head2 Double-Typed SVs
Scalar variables normally contain only one type of value, an integer,
double, pointer, or reference. Perl will automatically convert the
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
-the magic, typically the name of a variable. C<namlem> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
+The C<name> and C<namlen> arguments are used to associate a string with
+the magic, typically the name of a variable. C<namlen> is stored in the
+C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
copy of the name is stored in C<mg_ptr> field.
The sv_magic function uses C<how> to determine which, if any, predefined
This routine returns a pointer to the C<MAGIC> structure stored in the SV.
If the SV does not have that magical feature, C<NULL> is returned. Also,
-if the SV is not of type SVt_PVMG, Perl may core-dump.
+if the SV is not of type SVt_PVMG, Perl may core dump.
int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
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)
=head2 Scratchpads
-The question remains on when the SV's which are I<target>s for opcodes
+The question remains on when the SVs which are I<target>s for opcodes
are created. The answer is that they are created when the current unit --
a subroutine or a file (for opcodes for statements outside of
subroutines) -- is compiled. During this time a special anonymous Perl
array is created, which is called a scratchpad for the current
unit.
-A scratchpad keeps SV's which are lexicals for the current unit and are
+A scratchpad keeps SVs which are lexicals for the current unit and are
targets for opcodes. One can deduce that an SV lives on a scratchpad
by looking on its flags: lexicals have C<SVs_PADMY> set, and
I<target>s have C<SVs_PADTMP> set.
-The correspondence between OP's and I<target>s is not 1-to-1. Different
-OP's in the compile tree of the unit can use the same target, if this
+The correspondence between OPs and I<target>s is not 1-to-1. Different
+OPs in the compile tree of the unit can use the same target, if this
would not conflict with the expected life of the temporary.
=head2 Scratchpads and recursion
=item G_ARRAY
-Used to indicate array context. See C<GIMME> and L<perlcall>.
+Used to indicate array context. See C<GIMME_V>, C<GIMME> and L<perlcall>.
=item G_DISCARD
=item GIMME
-The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or
-C<G_ARRAY> for scalar or array context.
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+
+=item GIMME_V
+
+The XSUB-writer's equivalent to Perl's C<wantarray>. Returns
+C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
+context, respectively.
=item G_NOARGS
=item G_SCALAR
-Used to indicate scalar context. See C<GIMME> and L<perlcall>.
+Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>.
+
+=item G_VOID
+
+Used to indicate void context. See C<GIMME_V> and L<perlcall>.
=item gv_fetchmeth
=item gv_fetchmethod
+=item gv_fetchmethod_autoload
+
Returns the glob which contains the subroutine to call to invoke the
-method on the C<stash>. In fact in the presense of autoloading this may
-be the glob for "AUTOLOAD". In this case the corresponing variable
+method on the C<stash>. In fact in the presense of autoloading this may
+be the glob for "AUTOLOAD". In this case the corresponding variable
$AUTOLOAD is already setup.
-Note that if you want to keep this glob for a long time, you need to
-check for it being "AUTOLOAD", since at the later time the call
+The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
+lookup is performed if the given method is not present: non-zero means
+yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling
+C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
+non-zero C<autoload> parameter.
+
+These functions grant C<"SUPER"> token as a prefix of the method name.
+
+Note that if you want to keep the returned glob for a long time, you
+need to check for it being "AUTOLOAD", since at the later time the call
may load a different subroutine due to $AUTOLOAD changing its value.
Use the glob created via a side effect to do this.
-This function grants C<"SUPER"> token as a prefix of the method name.
-
-Has the same side-effects and as C<gv_fetchmeth> with C<level==0>.
-C<name> should be writable if contains C<':'> or C<'\''>.
+These functions have the same side-effects and as C<gv_fetchmeth> with
+C<level==0>. C<name> should be writable if contains C<':'> or C<'\''>.
The warning against passing the GV returned by C<gv_fetchmeth> to
-C<perl_call_sv> apply equally to C<gv_fetchmethod>.
+C<perl_call_sv> apply equally to these functions.
GV* gv_fetchmethod _((HV* stash, char* name));
+ GV* gv_fetchmethod_autoload _((HV* stash, char* name,
+ I32 autoload));
=item gv_stashpv
Deletes a key/value pair in the hash. The value SV is removed from the hash
and returned to the caller. The C<flags> value will normally be zero; if set
-to G_DISCARD then null will be returned. C<hash> can be a valid pre-computed
+to G_DISCARD then null will be returned. C<hash> can be a valid precomputed
hash value, or 0 to ask for it to be computed.
SV* hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash));
=item hv_exists_ent
Returns a boolean indicating whether the specified hash key exists. C<hash>
-can be a valid pre-computed hash value, or 0 to ask for it to be computed.
+can be a valid precomputed hash value, or 0 to ask for it to be computed.
bool hv_exists_ent _((HV* tb, SV* key, U32 hash));
=item hv_fetch_ent
Returns the hash entry which corresponds to the specified key in the hash.
-C<hash> must be a valid pre-computed hash number for the given C<key>, or
+C<hash> must be a valid precomputed hash number for the given C<key>, or
0 if you want the function to compute it. IF C<lval> is set then the
fetch will be part of a store. Make sure the return value is non-null
before accessing it. The return value when C<tb> is a tied hash
char* hv_iterkey _((HE* entry, I32* retlen));
=item hv_iterkeysv
-
+
Returns the key as an C<SV*> from the current position of the hash
iterator. The return value will always be a mortal copy of the
key. Also see C<hv_iterinit>.
=item hv_store
Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
-the length of the key. The C<hash> parameter is the pre-computed hash
+the length of the key. The C<hash> parameter is the precomputed hash
value; if it is zero then Perl will compute it. The return value will be
null if the operation failed, otherwise it can be dereferenced to get the
original C<SV*>.
=item hv_store_ent
Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
-parameter is the pre-computed hash value; if it is zero then Perl will
+parameter is the precomputed hash value; if it is zero then Perl will
compute it. The return value is the new hash entry so created. It will be
null if the operation failed or if the entry was stored in a tied hash.
Otherwise the contents of the return value can be accessed using the
I32 perl_eval_sv _((SV* sv, I32 flags));
+=item perl_eval_pv
+
+Tells Perl to C<eval> the given string and return an SV* result.
+
+ SV* perl_eval_pv _((char* p, I32 croak_on_error));
+
=item perl_free
Releases a Perl interpreter. See L<perlembed>.
=item SPAGAIN
-Re-fetch the stack pointer. Used after a callback. See L<perlcall>.
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
SPAGAIN;
=head1 DATE
-Version 31.3: 1997/3/14
+Version 31.6: 1997/4/14
projects / p5sagit/p5-mst-13.2.git / blobdiff