Each typedef has specific routines that manipulate the various data types.
Perl also uses two special typedefs, I32 and I16, which will always be at least 32-bits and 16-bits long, respectively.
The four routines are:
To change the value of an *already-existing* scalar, there are five routines:
Notice that you can choose to specify the length of the string to be
assigned by using
newSVpv, or you may allow Perl to
calculate the length by using
sv_setpv or specifying 0 as the second
newSVpv. Be warned, though, that Perl will determine the
string's length by using
strlen, which depends on the string terminating
with a NUL character.
To access the actual value that an SV points to, you can use the macros:
which will automatically coerce the actual scalar type into an IV, double, or string.
SvPV macro, the length of the string returned is placed into the
len (this is a macro, so you do not use
&len). If you do not
care what the length of the data is, use the global variable
however, that Perl allows arbitrary strings of data that may both contain
NUL's and not be terminated by a NUL.
If you simply want to know if the scalar value is TRUE, you can use:
Although Perl will automatically grow strings for you, if you need to force Perl to allocate more memory for your SV, you can use the macro
which will determine if more memory needs to be allocated. If so, it will
call the function
sv_grow. Note that
SvGROW can only increase, not
decrease, the allocated memory of an SV.
If you have an SV and want to know what kind of data Perl thinks is stored in it, you can use the following macros to check the type of SV you have.
You can get and set the current length of the string stored in an SV with the following macros:
But note that these are valid only if
SvPOK() is true.
If you want to append something to the end of string stored in an
you can use the following functions:
The first function calculates the length of the string to be appended by
strlen. In the second, you specify the length of the string
yourself. The third function extends the string stored in the first SV
with the string stored in the second SV. It also forces the second SV to
be interpreted as a string.
If you know the name of a scalar variable, you can get a pointer to its SV by using the following:
This returns NULL if the variable does not exist.
If you want to know if this variable (or any other SV) is actually defined , you can call:
value is stored in an SV instance called
address can be used whenever an
SV* is needed.
There are also the two values
sv_no, which contain Boolean
TRUE and FALSE values, respectively. Like
sv_undef, their addresses can
be used whenever an
SV* is needed.
Do not be fooled into thinking that
(SV *) 0 is the same as
Take this code:
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
&sv_undef in the first line and
all will be well.
To free an SV that you've created, call
SvREFCNT_dec(SV*). Normally this
call is not necessary. See the section on MORTALITY.
Sv*OKmacros. Since a scalar can be both a number and a string, usually these macros will always return TRUE and calling the
Sv*Vmacros will do the appropriate conversion of string to integer/double or integer/double to string.
If you really need to know if you have an integer, double, or string pointer in an SV, you can use the following three macros instead:
These will tell you if you truly have an integer, double, or string pointer stored in your SV. The "p" stands for private.
In general, though, it's best to just use the
The second method both creates the AV and initially populates it with SV's:
The second argument points to an array containing
SV*'s. Once the
AV has been created, the SV's can be destroyed, if so desired.
Once the AV has been created, the following operations are possible on AV's:
These should be familiar operations, with the exception of
This routine adds
num elements at the front of the array with the
value. You must then use
av_store (described below) to assign values
to these new elements.
Here are some other functions:
Take note that these two functions return
If you know the name of an array variable, you can get a pointer to its AV by using the following:
This returns NULL if the variable does not exist.
Once the HV has been created, the following operations are possible on HV's:
klen parameter is the length of the key being passed in. The
argument contains the SV pointer to the scalar being stored, and
the pre-computed hash value (zero if you want
hv_store to calculate it
for you). The
lval parameter indicates whether this fetch is actually a
part of a store operation.
SV**'s and not just
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.
These two functions check if a hash table entry exists, and deletes it.
And more miscellaneous functions:
Perl keeps the actual data in linked list of structures with a typedef of HE.
These contain the actual key and value pointers (plus extra administrative
overhead). The key is a string pointer; the value is an
once you have an
HE*, to get the actual key and value, use the routines
If you know the name of a hash variable, you can get a pointer to its HV by using the following:
This returns NULL if the variable does not exist.
The hash algorithm, for those who are interested, is:
Notice the use of TRUE as the second parameter. The new variable can now be set, using the routines appropriate to the data type.
There are additional bits that may be OR'ed with the TRUE argument to enable certain extra features. Those bits are:
To create a reference, use the following command:
thing argument can be any of an
you have a reference, you can use the following macro to dereference the
then call the appropriate routines, casting the returned
SV* to either an
HV*, if required.
To determine if an SV is a reference, you can use the following macro:
To actually discover what the reference refers to, you must use the following macro and then check the value returned.
The most useful types that will be returned are:
The stack arguments are accessible through the
ST(n) macro, which returns
n'th stack argument. Argument 0 is the first argument passed in the
Perl subroutine call. These arguments are
SV*, and can be used anywhere
SV* is used.
Most of the time, output from the C routine can be handled through use of the RETVAL and OUTPUT directives. However, there are some cases where the argument stack is not already long enough to handle all the return values. An example is the POSIX tzname() call, which takes no arguments, but returns two, the local timezone's standard and summer time abbreviations.
To handle this situation, the PPCODE directive is used and the stack is extended using the macro:
sp is the stack pointer, and
num is the number of elements the
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:
And now the Perl program calling
tzname, the two values will be assigned
An alternate (and possibly simpler) method to pushing values on the stack is to use the macros:
These macros automatically adjust the stack for you, if needed.
For more information, consult the perlapi manpage .
Add cruft about reference counts.
In the above example with
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.
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.
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
by passing their address (and casting them to
SV*) to the
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 contexts. It can also be mortal twice in the same context. This means that you should be very careful to make a value mortal exactly as many times as it is needed. The value that go to the Perl stack 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.
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
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.
To get the stash pointer for a particular package, use the function:
The first function takes a literal string, the second uses the string stored
in the SV. Remember that a stash is just a hash table, so you get back an
The name that
gv_stash*v wants is the name of the package whose symbol table
you want. The default package is called
main. If you have multiply nested
packages, pass their names to
gv_stash*v, separated by
:: as in the Perl
Alternately, if you have an SV that is a blessed reference, you can find out the stash pointer by using:
then use the following to get the package name itself:
If you need to return a blessed value to your Perl script, you can use the following function:
where the first argument, an
SV*, must be a reference, and the second
argument is a stash. The returned
SV* can now be used in the same way
as any other SV.
For more information on references and blessings, consult the perlref manpage .
# 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
struct magic's, typedef'ed to
Note this is current as of patchlevel 0, and could change at any time.
sv argument is a pointer to the SV that is to acquire a new magical
sv is not already magical, Perl uses the
SvUPGRADE macro to
SVt_PVMG flag for the
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
associated with an SV.
namlem arguments are used to associate a string with
the magic, typically the name of a variable.
namlem is stored in the
mg_len field and if
name is non-null and
namlem >= 0 a malloc'd
copy of the name is stored in
The sv_magic function uses
how to determine which, if any, predefined
"Magic Virtual Table" should be assigned to the
See the "Magic Virtual Table" section below.
obj argument is stored in the
mg_obj field of the
structure. If it is not the same as the
sv argument, the reference
count of the
obj object is incremented. If it is the same, or if
how argument is "#", or if it is a null pointer, then
merely stored, without the reference count being incremented.
mg_virtualfield in the
MAGICstructure is a pointer to a
MGVTBL, which is a structure of function pointers and stands for "Magic Virtual Table" to handle the various operations that might be applied to that variable.
MGVTBL has five pointers to the following routine types:
This MGVTBL structure is set at compile-time in
perl.h and there are
currently 19 types (or 21 with overloading turned on). These different
structures contain pointers to various routines that perform additional
actions depending on which function is being called.
For instance, the MGVTBL structure called
vtbl_sv (which corresponds
mg_type of '\0') contains:
Thus, when an SV is determined to be magical and of type '\0', if a get
operation is being performed, the routine
magic_get is called. All
the various routines for the various magical types begin with
The current kinds of Magic Virtual Tables are:
When an upper-case and lower-case letter both exist in the table, then the upper-case letter is used to represent some kind of composite type (a list or a hash), and the lower-case letter is used to represent an element of that composite type.
This routine returns a pointer to the
MAGIC structure stored in the SV.
If the SV does not have that magical feature,
NULL is returned. Also,
if the SV is not of type SVt_PVMG, Perl may core-dump.
This routine checks to see what types of magic
sv has. If the mg_type
field is an upper-case letter, then the mg_obj is copied to
the mg_type field is changed to be the lower-case letter.
Some scalar variables contain more than one type of scalar data. For
example, the variable
contains either the numeric value of
or its string equivalent from either
To force multiple data values into an SV, you must do two things: use the
sv_set*v routines to add the additional scalar type, then set a flag
so that Perl will believe it contains more than one type of data. The
four macros to set the flags are:
The particular macro you must use depends on which
you called first. This is because every
sv_set*v routine turns on
only the bit for the particular type of data being set, and turns off
all the rest.
For example, to create a new Perl variable called "dberror" that contains both the numeric and descriptive string error values, you could use the following code:
If the order of
sv_setpv had been reversed, then the
SvPOK_on would need to be called instead of
The routine most often used is
contains either the name of the Perl subroutine to be called, or a
reference to the subroutine. The second argument consists of flags
that control the context in which the subroutine is called, whether
or not the subroutine is being passed arguments, how errors should be
trapped, and how to treat return values.
All four routines return the number of arguments that the subroutine returned on the Perl stack.
When using any of these routines (except
perl_call_argv), the programmer
must manipulate the Perl stack. These include the following macros and
For more information, consult the perlcall manpage .
These three macros are used to initially allocate memory. The first argument
x was a "magic cookie" that was used to keep track of who called the macro,
to help when debugging memory problems. However, the current code makes no
use of this feature (Larry has switched to using a run-time memory checker),
so this argument can be any number.
The second argument
pointer will point to the newly allocated memory.
The third and fourth arguments
type specify how many of
the specified type of data structure should be allocated. The argument
type is passed to
sizeof. The final argument to
should be used if the
pointer argument is different from the
Newc macros, the
Newz macro calls
to zero out all the newly allocated memory.
These three macros are used to change a memory buffer size or to free a
piece of memory no longer needed. The arguments to
match those of
Newc with the exception of not needing the
"magic cookie" argument.
These three macros are used to move, copy, or zero out previously allocated
dest arguments point to the source and
destination starting points. Perl will move, copy, or zero out
instances of the size of the
type data structure (using 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.