Perl also uses two special typedefs, I32 and I16, which will always be at
least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16,
-as well.)
+as well.) They will usually be exactly 32 and 16 bits long, but on Crays
+they will both be 64 bits.
=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 (PV), and another scalar (SV).
+An SV can be created and loaded with one command. There are five types of
+values that can be loaded: an integer value (IV), an unsigned integer
+value (UV), a double (NV), a string (PV), and another scalar (SV).
-The six routines are:
+The seven routines are:
SV* newSViv(IV);
+ SV* newSVuv(UV);
SV* newSVnv(double);
SV* newSVpv(const char*, int);
SV* newSVpvn(const char*, int);
SV* newSVpvf(const char*, ...);
SV* newSVsv(SV*);
-To change the value of an *already-existing* SV, there are seven routines:
+If you require more complex initialisation you can create an empty SV with
+newSV(len). If C<len> is 0 an empty SV of type NULL is returned, else an
+SV of type PV is returned with len + 1 (for the NUL) bytes of storage
+allocated, accessible via SvPVX. In both cases the SV has value undef.
+
+ SV* newSV(0); /* no storage allocated */
+ SV* newSV(10); /* 10 (+1) bytes of uninitialised storage allocated */
+
+To change the value of an *already-existing* SV, there are eight routines:
void sv_setiv(SV*, IV);
void sv_setuv(SV*, UV);
There are additional macros whose values may be bitwise OR'ed with the
C<TRUE> argument to enable certain extra features. Those bits are:
- GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
- "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.
+=over
+
+=item GV_ADDMULTI
+
+Marks the variable as multiply defined, thus preventing the:
+
+ Name <varname> used only once: possible typo
+
+warning.
+
+=item GV_ADDWARN
+
+Issues the warning:
+
+ Had to create <varname> unexpectedly
+
+if the variable did not exist before the function was called.
+
+=back
If you do not specify a package name, the variable is created in the current
package.
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.
Because C<sv_newmortal> gives the new SV no value,it must normally be given one
-via C<sv_setpv>, C<sv_setiv> etc. :
+via C<sv_setpv>, C<sv_setiv>, etc. :
SV *tmp = sv_newmortal();
sv_setiv(tmp, an_integer);
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
+C<mg_len> field and if C<name> is non-null and C<namlen> E<gt>= 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
from the set of macros C<PERL_MAGIC_foo> found perl.h. Note that before
these macros were added, Perl internals used to directly use character
literals, so you may occasionally come across old code or documentation
-referrring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
+referring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
structure. If it is not the same as the C<sv> argument, the reference
Function pointer Action taken
---------------- ------------
- svt_get Do something after the value of the SV is retrieved.
+ svt_get Do something before the value of the SV is retrieved.
svt_set Do something after the SV is assigned a value.
svt_len Report on the SV's length.
svt_clear Clear something the SV represents.
t PERL_MAGIC_taint vtbl_taint Taintedness
U PERL_MAGIC_uvar vtbl_uvar Available for use by extensions
v PERL_MAGIC_vec vtbl_vec vec() lvalue
+ V PERL_MAGIC_vstring (none) v-string scalars
x PERL_MAGIC_substr vtbl_substr substr() lvalue
y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
variable / smart parameter
~ PERL_MAGIC_ext (none) Available for use by extensions
When an uppercase and lowercase letter both exist in the table, then the
-uppercase letter is used to represent some kind of composite type (a list
-or a hash), and the lowercase letter is used to represent an element of
-that composite type. Some internals code makes use of this case
-relationship.
+uppercase letter is typically used to represent some kind of composite type
+(a list or a hash), and the lowercase letter is used to represent an element
+of that composite type. Some internals code makes use of this case
+relationship. However, 'v' and 'V' (vec and v-string) are in no way related.
The C<PERL_MAGIC_ext> and C<PERL_MAGIC_uvar> magic types are defined
specifically for use by extensions and will not be used by perl itself.
aware that the behavior may change in the future, umm, without warning.
The perl tie function associates a variable with an object that implements
-the various GET, SET etc methods. To perform the equivalent of the perl
+the various GET, SET, etc methods. To perform the equivalent of the perl
tie function from an XSUB, you must mimic this behaviour. The code below
carries out the necessary steps - firstly it creates a new hash, and then
creates a second hash which it blesses into the class which will implement
The biggest difference is that the first construction 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
+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
All four routines return the number of arguments that the subroutine returned
on the Perl stack.
-These routines used to be called C<perl_call_sv> etc., before Perl v5.6.0,
+These routines used to be called C<perl_call_sv>, etc., before Perl v5.6.0,
but those names are now deprecated; macros of the same name are provided for
compatibility.
(initially) one element, and this element is the scratchpad AV. Why do
we need an extra level of indirection?
-The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
+The answer is B<recursion>, and maybe B<threads>. Both
these can create several execution pointers going into the same
subroutine. For the subroutine-child not write over the temporaries
for the subroutine-parent (lifespan of which covers the call to the
or inside a thread-specific structure. These structures contain all
the context, the state of that interpreter.
-Three macros control the major Perl build flavors: MULTIPLICITY, and
+Two macros control the major Perl build flavors: MULTIPLICITY and
USE_5005THREADS. The MULTIPLICITY build has a C structure
that packages all the interpreter state, and there is a similar thread-specific
data structure under USE_5005THREADS. In both cases,
=head1 Custom Operators
-Custom operator support is a new experimental feature that allows you do
+Custom operator support is a new experimental feature that allows you to
define your own ops. This is primarily to allow the building of
interpreters for other languages in the Perl core, but it also allows
optimizations through the creation of "macro-ops" (ops which perform the
=head1 AUTHORS
Until May 1997, this document was maintained by Jeff Okamoto
-<okamoto@corp.hp.com>. It is now maintained as part of Perl itself
-by the Perl 5 Porters <perl5-porters@perl.org>.
+E<lt>okamoto@corp.hp.comE<gt>. It is now maintained as part of Perl
+itself by the Perl 5 Porters E<lt>perl5-porters@perl.orgE<gt>.
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, Spider Boardman, Ulrich Pfeifer,
Stephen McCamant, and Gurusamy Sarathy.
-API Listing originally by Dean Roehrich <roehrich@cray.com>.
+API Listing originally by Dean Roehrich E<lt>roehrich@cray.comE<gt>.
Modifications to autogenerate the API listing (L<perlapi>) by Benjamin
Stuhl.