perlguts
perlguts - Perl's Internal Functions
This document attempts to describe some of the internal functions of the
Perl executable. It is far from complete and probably contains many errors.
Please refer any questions or comments to the author below.
Perl has three typedefs that handle Perl's three main data types:
SV Scalar Value
AV Array Value
HV Hash Value
Each typedef has specific routines that manipulate the various data types.
What is an ``IV''?
Perl uses a special typedef IV which is large enough to hold either an
integer or a pointer.
Perl also uses two special typedefs, I32 and I16, which will always be at
least 32-bits and 16-bits long, respectively.
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).
The four routines are:
SV* newSViv(IV);
SV* newSVnv(double);
SV* newSVpv(char*, int);
SV* newSVsv(SV*);
To change the value of an *already-existing* SV, there are five routines:
void sv_setiv(SV*, IV);
void sv_setnv(SV*, double);
void sv_setpvn(SV*, char*, int)
void sv_setpv(SV*, char*);
void sv_setsv(SV*, SV*);
Notice that you can choose to specify the length of the string to be
assigned by using
sv_setpvn
or
newSVpv
, or you may allow Perl to
calculate the length by using
sv_setpv
or by specifying 0 as the second
argument to
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:
SvIV(SV*)
SvNV(SV*)
SvPV(SV*, STRLEN len)
which will automatically coerce the actual scalar type into an IV, double,
or string.
In the
SvPV
macro, the length of the string returned is placed into the
variable 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
na
. Remember,
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:
SvTRUE(SV*)
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
SvGROW(SV*, STRLEN newlen)
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.
SvIOK(SV*)
SvNOK(SV*)
SvPOK(SV*)
You can get and set the current length of the string stored in an SV with
the following macros:
SvCUR(SV*)
SvCUR_set(SV*, I32 val)
You can also get a pointer to the end of the string stored in the SV
with the macro:
SvEND(SV*)
But note that these last three macros are valid only if
SvPOK()
is true.
If you want to append something to the end of string stored in an SV*
,
you can use the following functions:
void sv_catpv(SV*, char*);
void sv_catpvn(SV*, char*, int);
void sv_catsv(SV*, SV*);
The first function calculates the length of the string to be appended by
using 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:
SV* perl_get_sv("varname", FALSE);
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:
SvOK(SV*)
The scalar
undef
value is stored in an SV instance called
sv_undef
. Its
address can be used whenever an SV*
is needed.
There are also the two values
sv_yes
and
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 &sv_undef
.
Take this code:
SV* sv = (SV*) 0;
if (I-am-to-return-a-real-value) {
sv = sv_2mortal(newSViv(42));
}
sv_setsv(ST(0), sv);
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.
Recall that the usual method of determining the type of scalar you have is
to use Sv*OK
macros. Since a scalar can be both a number and a string,
usually these macros will always return TRUE and calling the Sv*V
macros 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:
SvIOKp(SV*)
SvNOKp(SV*)
SvPOKp(SV*)
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 Sv*V
macros.
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:
AV* av_make(I32 num, SV **ptr);
The second argument points to an array containing num
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:
void av_push(AV*, SV*);
SV* av_pop(AV*);
SV* av_shift(AV*);
void av_unshift(AV*, I32 num);
These should be familiar operations, with the exception of
av_unshift
.
This routine adds num
elements at the front of the array with the
undef
value. You must then use
av_store
(described below) to assign values
to these new elements.
Here are some other functions:
I32 av_len(AV*); /* Returns highest index value in array */
SV** av_fetch(AV*, I32 key, I32 lval);
/* Fetches value at key offset, but it stores an undef value
at the offset if lval is non-zero */
SV** av_store(AV*, I32 key, SV* val);
/* Stores val at offset key */
Take note that
av_fetch
and
av_store
return SV**
's, not SV*
's.
void av_clear(AV*);
/* Clear out all elements, but leave the array */
void av_undef(AV*);
/* Undefines the array, removing all elements */
void av_extend(AV*, I32 key);
/* Extend the array to a total of key elements */
If you know the name of an array variable, you can get a pointer to its AV
by using the following:
AV* perl_get_av("varname", FALSE);
This returns NULL if the variable does not exist.
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:
SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
The klen
parameter is the length of the key being passed in. The val
argument contains the SV pointer to the scalar being stored, and hash
is
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.
Remember that
hv_store
and
hv_fetch
return 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.
bool hv_exists(HV*, char* key, U32 klen);
SV* hv_delete(HV*, char* key, U32 klen, I32 flags);
And more miscellaneous functions:
void hv_clear(HV*);
/* Clears all entries in hash table */
void hv_undef(HV*);
/* Undefines the hash table */
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 SV*
. However,
once you have an HE*
, to get the actual key and value, use the routines
specified below.
I32 hv_iterinit(HV*);
/* Prepares starting point to traverse hash table */
HE* hv_iternext(HV*);
/* Get the next entry, and return a pointer to a
structure that has both the key and value */
char* hv_iterkey(HE* entry, I32* retlen);
/* Get the key from an HE structure and also return
the length of the key string */
SV* hv_iterval(HV*, HE* entry);
/* Return a SV pointer to the value of the HE
structure */
SV* hv_iternextsv(HV*, char** key, I32* retlen);
/* This convenience routine combines hv_iternext,
hv_iterkey, and hv_iterval. The key and retlen
arguments are return values for the key and its
length. The value is returned in the SV* argument */
If you know the name of a hash variable, you can get a pointer to its HV
by using the following:
HV* perl_get_hv("varname", FALSE);
This returns NULL if the variable does not exist.
The hash algorithm, for those who are interested, is:
i = klen;
hash = 0;
s = key;
while (i--)
hash = hash * 33 + *s++;
References are a special type of scalar that point to other data types
(including references).
To create a reference, use the following command:
SV* newRV((SV*) thing);
The thing
argument can be any of an SV*
, AV*
, or HV*
. Once
you have a reference, you can use the following macro to dereference the
reference:
SvRV(SV*)
then call the appropriate routines, casting the returned SV*
to either an
AV*
or HV*
, if required.
To determine if an SV is a reference, you can use the following macro:
SvROK(SV*)
To actually discover what the reference refers to, you must use the following
macro and then check the value returned.
SvTYPE(SvRV(SV*))
The most useful types that will be returned are:
SVt_IV Scalar
SVt_NV Scalar
SVt_PV Scalar
SVt_PVAV Array
SVt_PVHV Hash
SVt_PVCV Code
SVt_PVMG Blessed Scalar
References are also used to support object-oriented programming. In the
OO lexicon, an object is simply a reference that has been blessed into a
package (or class). Once blessed, the programmer may now use the reference
to access the various methods in the class.
A reference can be blessed into a package with the following function:
SV* sv_bless(SV* sv, HV* stash);
The sv
argument must be a reference. The stash
argument specifies
which class the reference will belong to. See the section on Stashes
for information on converting class names into stashes.
/* Still under construction */
Upgrades rv to reference if not already one. Creates new SV for rv to
point to.
If classname is non-null, the SV is blessed into the specified class.
SV is returned.
SV* newSVrv(SV* rv, char* classname);
Copies integer or double into an SV whose reference is rv. SV is blessed
if classname is non-null.
SV* sv_setref_iv(SV* rv, char* classname, IV iv);
SV* sv_setref_nv(SV* rv, char* classname, NV iv);
Copies pointer (not a string!) into an SV whose reference is rv.
SV is blessed if classname is non-null.
SV* sv_setref_pv(SV* rv, char* classname, PV iv);
Copies string into an SV whose reference is rv.
Set length to 0 to let Perl calculate the string length.
SV is blessed if classname is non-null.
SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
int sv_isa(SV* sv, char* name);
int sv_isobject(SV* sv);
To create a new Perl variable, which can be accessed from your Perl script,
use the following routines, depending on the variable type.
SV* perl_get_sv("varname", TRUE);
AV* perl_get_av("varname", TRUE);
HV* perl_get_hv("varname", TRUE);
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:
0x02 Marks the variable as multiply defined, thus preventing the
"Indentifier used only once: possible typo" warning.
0x04 Issues a "Had to create unexpectedly" warning if
the variable didn't actually exist. This is useful if
you expected the variable to already exist and want to propagate
this warning back to the user.
If the varname
argument does not contain a package specifier, it is
created in the current package.
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
program, and a way to map from the Perl data structures to a C equivalent.
The stack arguments are accessible through the
ST(n)
macro, which returns
the 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
an 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:
EXTEND(sp, num);
where 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:
PUSHi(IV)
PUSHn(double)
PUSHp(char*, I32)
PUSHs(SV*)
And now the Perl program calling tzname
, the two values will be assigned
as in:
($standard_abbrev, $summer_abbrev) = POSIX::tzname;
An alternate (and possibly simpler) method to pushing values on the stack is
to use the macros:
XPUSHi(IV)
XPUSHn(double)
XPUSHp(char*, I32)
XPUSHs(SV*)
These macros automatically adjust the stack for you, if needed.
For more information, consult
the perlxs manpage
.
In Perl, values are normally ``immortal'' -- that is, they are not freed unless
explicitly done so (via the Perl
undef
call or other routines in Perl
itself).
Add cruft about reference counts.
int SvREFCNT(SV* sv);
void SvREFCNT_inc(SV* sv);
void SvREFCNT_dec(SV* sv);
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:
SV* sv_newmortal()
SV* sv_2mortal(SV*)
SV* sv_mortalcopy(SV*)
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
sv_2mortal
or
sv_mortalcopy
routines.
>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.
A stash is a hash table (associative array) that contains all of the
different objects that are contained within a package. Each key of the
stash is a symbol name (shared by all the different types of objects
that have the same name), and each value in the hash table is called a
GV (for Glob Value). This GV in turn contains references to the various
objects of that name, including (but not limited to) the following:
Scalar Value
Array Value
Hash Value
File Handle
Directory Handle
Format
Subroutine
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 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.
To get the stash pointer for a particular package, use the function:
HV* gv_stashpv(char* name, I32 create)
HV* gv_stashsv(SV*, I32 create)
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
HV*
. The create
flag will create a new package if it is set.
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
language itself.
Alternately, if you have an SV that is a blessed reference, you can find
out the stash pointer by using:
HV* SvSTASH(SvRV(SV*));
then use the following to get the package name itself:
char* HvNAME(HV* stash);
If you need to return a blessed value to your Perl script, you can use the
following function:
SV* sv_bless(SV*, HV* stash)
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
.
[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 struct magic
's, typedef'ed to MAGIC
.
struct magic {
MAGIC* mg_moremagic;
MGVTBL* mg_virtual;
U16 mg_private;
char mg_type;
U8 mg_flags;
SV* mg_obj;
char* mg_ptr;
I32 mg_len;
};
Note this is current as of patchlevel 0, and could change at any time.
Perl adds magic to an SV using the sv_magic function:
void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
The sv
argument is a pointer to the SV that is to acquire a new magical
feature.
If sv
is not already magical, Perl uses the
SvUPGRADE
macro to
set the
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.
The name
and 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 mg_ptr
field.
The sv_magic function uses how
to determine which, if any, predefined
``Magic Virtual Table'' should be assigned to the mg_virtual
field.
See the ``Magic Virtual Table'' section below. The how
argument is also
stored in the mg_type
field.
The obj
argument is stored in the mg_obj
field of the MAGIC
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
the how
argument is ``#'', or if it is a null pointer, then obj
is
merely stored, without the reference count being incremented.
There is also a function to add magic to an HV
:
void hv_magic(HV *hv, GV *gv, int how);
This simply calls
sv_magic
and coerces the gv
argument into an SV
.
To remove the magic from an SV, call the function sv_unmagic:
void sv_unmagic(SV *sv, int type);
The type
argument should be equal to the how
value when the SV
was initially made magical.
The mg_virtual
field in the MAGIC
structure 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.
The MGVTBL
has five pointers to the following routine types:
int (*svt_get)(SV* sv, MAGIC* mg);
int (*svt_set)(SV* sv, MAGIC* mg);
U32 (*svt_len)(SV* sv, MAGIC* mg);
int (*svt_clear)(SV* sv, MAGIC* mg);
int (*svt_free)(SV* sv, MAGIC* mg);
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.
Function pointer Action taken
---------------- ------------
svt_get Do something after 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.
svt_free Free any extra storage associated with the SV.
For instance, the MGVTBL structure called vtbl_sv
(which corresponds
to an mg_type
of '\0') contains:
{ magic_get, magic_set, magic_len, 0, 0 }
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 magic_
.
The current kinds of Magic Virtual Tables are:
mg_type MGVTBL Type of magicalness
------- ------ -------------------
\0 vtbl_sv Regexp???
A vtbl_amagic Operator Overloading
a vtbl_amagicelem Operator Overloading
c 0 Used in Operator Overloading
B vtbl_bm Boyer-Moore???
E vtbl_env %ENV hash
e vtbl_envelem %ENV hash element
g vtbl_mglob Regexp /g flag???
I vtbl_isa @ISA array
i vtbl_isaelem @ISA array element
L 0 (but sets RMAGICAL) Perl Module/Debugger???
l vtbl_dbline Debugger?
P vtbl_pack Tied Array or Hash
p vtbl_packelem Tied Array or Hash element
q vtbl_packelem Tied Scalar or Handle
S vtbl_sig Signal Hash
s vtbl_sigelem Signal Hash element
t vtbl_taint Taintedness
U vtbl_uvar ???
v vtbl_vec Vector
x vtbl_substr Substring???
* vtbl_glob GV???
# vtbl_arylen Array Length
. vtbl_pos $. scalar variable
~ Reserved for extensions, but multiple extensions may clash
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.
MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that 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.
int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
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 nsv
, but
the mg_type field is changed to be the lower-case letter.
Scalar variables normally contain only one type of value, an integer,
double, pointer, or reference. Perl will automatically convert the
actual scalar data from the stored type into the requested type.
Some scalar variables contain more than one type of scalar data. For
example, the variable
$!
contains either the numeric value of errno
or its string equivalent from either strerror
or sys_errlist[]
.
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:
SvIOK_on
SvNOK_on
SvPOK_on
SvROK_on
The particular macro you must use depends on which sv_set*v
routine
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:
extern int dberror;
extern char *dberror_list;
SV* sv = perl_get_sv("dberror", TRUE);
sv_setiv(sv, (IV) dberror);
sv_setpv(sv, dberror_list[dberror]);
SvIOK_on(sv);
If the order of
sv_setiv
and
sv_setpv
had been reversed, then the
macro
SvPOK_on
would need to be called instead of
SvIOK_on
.
There are four routines that can be used to call a Perl subroutine from
within a C program. These four are:
I32 perl_call_sv(SV*, I32);
I32 perl_call_pv(char*, I32);
I32 perl_call_method(char*, I32);
I32 perl_call_argv(char*, I32, register char**);
The routine most often used is
perl_call_sv
. The SV*
argument
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
functions:
dSP
PUSHMARK()
PUTBACK
SPAGAIN
ENTER
SAVETMPS
FREETMPS
LEAVE
XPUSH*()
POP*()
For more information, consult
the perlcall manpage
.
It is strongly suggested that you use the version of malloc that is distributed
with Perl. It keeps pools of various sizes of unallocated memory in order to
more quickly satisfy allocation requests.
However, on some platforms, it may cause spurious malloc or free errors.
New(x, pointer, number, type);
Newc(x, pointer, number, type, cast);
Newz(x, pointer, number, type);
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 number
and 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
Newc
, cast
,
should be used if the pointer
argument is different from the type
argument.
Unlike the
New
and
Newc
macros, the
Newz
macro calls memzero
to zero out all the newly allocated memory.
Renew(pointer, number, type);
Renewc(pointer, number, type, cast);
Safefree(pointer)
These three macros are used to change a memory buffer size or to free a
piece of memory no longer needed. The arguments to
Renew
and
Renewc
match those of
New
and
Newc
with the exception of not needing the
``magic cookie'' argument.
Move(source, dest, number, type);
Copy(source, dest, number, type);
Zero(dest, number, type);
These three macros are used to move, copy, or zero out previously allocated
memory. The source
and dest
arguments point to the source and
destination starting points. Perl will move, copy, or zero out number
instances of the size of the type
data structure (using the sizeof
function).
This is a listing of functions, macros, flags, and variables that may be
useful to extension writers or that may be found while reading other
extensions.
-
AvFILL
-
See
av_len
.
-
av_clear
-
Clears an array, making it empty.
- void av_clear _((AV* ar));
-
av_extend
-
Pre-extend an array. The
key
is the index to which the array should be
extended.
- void av_extend _((AV* ar, I32 key));
-
av_fetch
-
Returns the SV at the specified index in the array. The
key
is the
index. If 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 SV*
.
SV** av_fetch _((AV* ar, I32 key, I32 lval));
-
av_len
-
Returns the highest index in the array. Returns -1 if the array is empty.
-
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.
AV* av_make _((I32 size, SV** svp));
-
av_pop
-
Pops an SV off the end of the array. Returns
&sv_undef
if the array is
empty.
SV* av_pop _((AV* ar));
-
av_push
-
Pushes an SV onto the end of the array.
- void av_push _((AV* ar, SV* val));
-
av_shift
-
Shifts an SV off the beginning of the array.
SV* av_shift _((AV* ar));
-
av_store
-
Stores an SV in an array. The array index is specified as
key
. The
return value will be null if the operation failed, otherwise it can be
dereferenced to get the original SV*
.
SV** av_store _((AV* ar, I32 key, SV* val));
-
av_undef
-
Undefines the array.
- void av_undef _((AV* ar));
-
av_unshift
-
Unshift an SV onto the beginning of the array.
- void av_unshift _((AV* ar, I32 num));
-
CLASS
-
Variable which is setup by
xsubpp
to indicate the class name for a C++ XS
constructor. This is always a char*
. See
THIS
and
the perlxs manpage
.
-
Copy
-
The XSUB-writer's interface to the C
memcpy
function. The s
is the
source, d
is the destination, n
is the number of items, and t
is
the type.
(void) Copy( s, d, n, t );
-
croak
-
This is the XSUB-writer's interface to Perl's
die
function. Use this
function the same way you use the C
printf
function. See
warn
.
-
CvSTASH
-
Returns the stash of the CV.
HV * CvSTASH( SV* sv )
-
DBsingle
-
When Perl is run in debugging mode, with the
-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
DBsub
.
-
DBsub
-
When Perl is run in debugging mode, with the
-d
switch, this GV contains
the SV which holds the name of the sub being debugged. See
DBsingle
.
The sub name can be found by
SvPV( GvSV( DBsub ), na )
-
dMARK
-
Declare a stack marker for the XSUB. See
MARK
and
dORIGMARK
.
-
dORIGMARK
-
Saves the original stack mark for the XSUB. See
ORIGMARK
.
-
dSP
-
Declares a stack pointer for the XSUB. See
SP
.
-
dXSARGS
-
Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
usually handled automatically by
xsubpp
. Declares the
items
variable
to indicate the number of items on the stack.
-
ENTER
-
Opening bracket on a callback. See
LEAVE
and
the perlcall manpage
.
ENTER;
-
EXTEND
-
Used to extend the argument stack for an XSUB's return values.
EXTEND( sp, int x );
-
FREETMPS
-
Closing bracket for temporaries on a callback. See
SAVETMPS
and
the perlcall manpage
.
FREETMPS;
-
G_ARRAY
-
Used to indicate array context. See
GIMME
and
the perlcall manpage
.
-
G_DISCARD
-
Indicates that arguments returned from a callback should be discarded. See
the perlcall manpage
.
-
G_EVAL
-
Used to force a Perl
eval
wrapper around a callback. See
the perlcall manpage
.
-
GIMME
-
The XSUB-writer's equivalent to Perl's
wantarray
. Returns
G_SCALAR
or
G_ARRAY
for scalar or array context.
-
G_NOARGS
-
Indicates that no arguments are being sent to a callback. See
the perlcall manpage
.
-
G_SCALAR
-
Used to indicate scalar context. See
GIMME
and
the perlcall manpage
.
-
gv_stashpv
-
Returns a pointer to the stash for a specified package. If
create
is set
then the package will be created if it does not already exist. If create
is not set and the package does not exist then NULL is returned.
HV* gv_stashpv _((char* name, I32 create));
-
gv_stashsv
-
Returns a pointer to the stash for a specified package. See
gv_stashpv
.
HV* gv_stashsv _((SV* sv, I32 create));
-
GvSV
-
Return the SV from the GV.
-
he_free
-
Releases a hash entry from an iterator. See
hv_iternext
.
-
hv_clear
-
Clears a hash, making it empty.
- void hv_clear _((HV* tb));
-
hv_delete
-
Deletes a key/value pair in the hash. The value SV is removed from the hash
and returned to the caller. The
lken
is the length of the key. The
flags
value will normally be zero; if set to G_DISCARD then null will be
returned.
SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
-
hv_exists
-
Returns a boolean indicating whether the specified hash key exists. The
lken
is the length of the key.
- bool hv_exists _((HV* tb, char* key, U32 klen));
-
hv_fetch
-
Returns the SV which corresponds to the specified key in the hash. The
lken
is the length of the key. If 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 SV*
.
SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
-
hv_iterinit
-
Prepares a starting point to traverse a hash table.
- I32 hv_iterinit _((HV* tb));
-
hv_iterkey
-
Returns the key from the current position of the hash iterator. See
hv_iterinit
.
char* hv_iterkey _((HE* entry, I32* retlen));
-
hv_iternext
-
Returns entries from a hash iterator. See
hv_iterinit
.
HE* hv_iternext _((HV* tb));
-
hv_iternextsv
-
Performs an
hv_iternext
,
hv_iterkey
, and
hv_iterval
in one
operation.
SV * hv_iternextsv _((HV* hv, char** key, I32* retlen));
-
hv_iterval
-
Returns the value from the current position of the hash iterator. See
hv_iterkey
.
SV* hv_iterval _((HV* tb, HE* entry));
-
hv_magic
-
Adds magic to a hash. See
sv_magic
.
- void hv_magic _((HV* hv, GV* gv, int how));
-
HvNAME
-
Returns the package name of a stash. See
SvSTASH
,
CvSTASH
.
char *HvNAME (HV* stash)
-
hv_store
-
Stores an SV in a hash. The hash key is specified as
key
and klen
is
the length of the key. The hash
parameter is the pre-computed 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 SV*
.
SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
-
hv_undef
-
Undefines the hash.
- void hv_undef _((HV* tb));
-
isALNUM
-
Returns a boolean indicating whether the C
char
is an ascii alphanumeric
character or digit.
int isALNUM (char c)
-
isALPHA
-
Returns a boolean indicating whether the C
char
is an ascii alphanumeric
character.
int isALPHA (char c)
-
isDIGIT
-
Returns a boolean indicating whether the C
char
is an ascii digit.
int isDIGIT (char c)
-
isLOWER
-
Returns a boolean indicating whether the C
char
is a lowercase character.
int isLOWER (char c)
-
isSPACE
-
Returns a boolean indicating whether the C
char
is whitespace.
int isSPACE (char c)
-
isUPPER
-
Returns a boolean indicating whether the C
char
is an uppercase character.
int isUPPER (char c)
-
items
-
Variable which is setup by
xsubpp
to indicate the number of items on the
stack. See
the perlxs manpage
.
-
LEAVE
-
Closing bracket on a callback. See
ENTER
and
the perlcall manpage
.
LEAVE;
-
MARK
-
Stack marker for the XSUB. See
dMARK
.
-
mg_clear
-
Clear something magical that the SV represents. See
sv_magic
.
- int mg_clear _((SV* sv));
-
mg_copy
-
Copies the magic from one SV to another. See
sv_magic
.
- int mg_copy _((SV *, SV *, char *, STRLEN));
-
mg_find
-
Finds the magic pointer for type matching the SV. See
sv_magic
.
MAGIC* mg_find _((SV* sv, int type));
-
mg_free
-
Free any magic storage used by the SV. See
sv_magic
.
-
mg_get
-
Do magic after a value is retrieved from the SV. See
sv_magic
.
-
mg_len
-
Report on the SV's length. See
sv_magic
.
-
mg_magical
-
Turns on the magical status of an SV. See
sv_magic
.
- void mg_magical _((SV* sv));
-
mg_set
-
Do magic after a value is assigned to the SV. See
sv_magic
.
-
Move
-
The XSUB-writer's interface to the C
memmove
function. The s
is the
source, d
is the destination, n
is the number of items, and t
is
the type.
(void) Move( s, d, n, t );
-
na
-
A variable which may be used with
SvPV
to tell Perl to calculate the
string length.
-
New
-
The XSUB-writer's interface to the C
malloc
function.
void * New( x, void *ptr, int size, type )
-
Newc
-
The XSUB-writer's interface to the C
malloc
function, with cast.
void * Newc( x, void *ptr, int size, type, cast )
-
Newz
-
The XSUB-writer's interface to the C
malloc
function. The allocated
memory is zeroed with memzero
.
void * Newz( x, void *ptr, int size, type )
-
newAV
-
Creates a new AV. The refcount is set to 1.
AV* newAV _((void));
-
newHV
-
Creates a new HV. The refcount is set to 1.
HV* newHV _((void));
-
newRV
-
Creates an RV wrapper for an SV. The refcount for the original SV is
incremented.
SV* newRV _((SV* ref));
-
newSV
-
Creates a new SV. The
len
parameter indicates the number of bytes of
pre-allocated string space the SV should have. The refcount for the new SV
is set to 1.
SV* newSV _((STRLEN len));
-
newSViv
-
Creates a new SV and copies an integer into it. The refcount for the SV is
set to 1.
SV* newSViv _((IV i));
-
newSVnv
-
Creates a new SV and copies a double into it. The refcount for the SV is
set to 1.
SV* newSVnv _((NV i));
-
newSVpv
-
Creates a new SV and copies a string into it. The refcount for the SV is
set to 1. If
len
is zero then Perl will compute the length.
SV* newSVpv _((char* s, STRLEN len));
-
newSVrv
-
Creates a new SV for the RV,
rv
, to point to. If rv
is not an RV then
it will be upgraded one. If 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.
SV* newSVrv _((SV* rv, char* classname));
-
newSVsv
-
Creates a new SV which is an exact duplicate of the orignal SV.
SV* newSVsv _((SV* old));
-
newXS
-
Used by
xsubpp
to hook up XSUBs as Perl subs.
-
newXSproto
-
Used by
xsubpp
to hook up XSUBs as Perl subs. Adds Perl prototypes to
the subs.
-
Nullav
-
Null AV pointer.
-
Nullch
-
Null character pointer.
-
Nullcv
-
Null CV pointer.
-
Nullhv
-
Null HV pointer.
-
Nullsv
-
Null SV pointer.
-
ORIGMARK
-
The original stack mark for the XSUB. See
dORIGMARK
.
-
perl_alloc
-
Allocates a new Perl interpreter. See
the perlembed manpage
.
-
perl_call_argv
-
Performs a callback to the specified Perl sub. See
the perlcall manpage
.
- I32 perl_call_argv _((char* subname, I32 flags, char** argv));
-
perl_call_method
-
Performs a callback to the specified Perl method. The blessed object must
be on the stack. See
the perlcall manpage
.
- I32 perl_call_method _((char* methname, I32 flags));
-
perl_call_pv
-
Performs a callback to the specified Perl sub. See
the perlcall manpage
.
- I32 perl_call_pv _((char* subname, I32 flags));
-
perl_call_sv
-
Performs a callback to the Perl sub whose name is in the SV. See
the perlcall manpage
.
- I32 perl_call_sv _((SV* sv, I32 flags));
-
perl_construct
-
Initializes a new Perl interpreter. See
the perlembed manpage
.
-
perl_destruct
-
Shuts down a Perl interpreter. See
the perlembed manpage
.
-
perl_eval_sv
-
Tells Perl to
eval
the string in the SV.
- I32 perl_eval_sv _((SV* sv, I32 flags));
-
perl_free
-
Releases a Perl interpreter. See
the perlembed manpage
.
-
perl_get_av
-
Returns the AV of the specified Perl array. If
create
is set and the
Perl variable does not exist then it will be created. If create
is not
set and the variable does not exist then null is returned.
AV* perl_get_av _((char* name, I32 create));
-
perl_get_cv
-
Returns the CV of the specified Perl sub. If
create
is set and the Perl
variable does not exist then it will be created. If create
is not
set and the variable does not exist then null is returned.
CV* perl_get_cv _((char* name, I32 create));
-
perl_get_hv
-
Returns the HV of the specified Perl hash. If
create
is set and the Perl
variable does not exist then it will be created. If create
is not
set and the variable does not exist then null is returned.
HV* perl_get_hv _((char* name, I32 create));
-
perl_get_sv
-
Returns the SV of the specified Perl scalar. If
create
is set and the
Perl variable does not exist then it will be created. If create
is not
set and the variable does not exist then null is returned.
SV* perl_get_sv _((char* name, I32 create));
-
perl_parse
-
Tells a Perl interpreter to parse a Perl script. See
the perlembed manpage
.
-
perl_require_pv
-
Tells Perl to
require
a module.
- void perl_require_pv _((char* pv));
-
perl_run
-
Tells a Perl interpreter to run. See
the perlembed manpage
.
-
POPi
-
Pops an integer off the stack.
int POPi();
-
POPl
-
Pops a long off the stack.
long POPl();
-
POPp
-
Pops a string off the stack.
char * POPp();
-
POPn
-
Pops a double off the stack.
double POPn();
-
POPs
-
Pops an SV off the stack.
SV* POPs();
-
PUSHMARK
-
Opening bracket for arguments on a callback. See
PUTBACK
and
the perlcall manpage
.
PUSHMARK(p)
-
PUSHi
-
Push an integer onto the stack. The stack must have room for this element.
See
XPUSHi
.
PUSHi(int d)
-
PUSHn
-
Push a double onto the stack. The stack must have room for this element.
See
XPUSHn
.
PUSHn(double d)
-
PUSHp
-
Push a string onto the stack. The stack must have room for this element.
The
len
indicates the length of the string. See
XPUSHp
.
PUSHp(char *c, int len )
-
PUSHs
-
Push an SV onto the stack. The stack must have room for this element. See
XPUSHs
.
PUSHs(sv)
-
PUTBACK
-
Closing bracket for XSUB arguments. This is usually handled by
xsubpp
.
See
PUSHMARK
and
the perlcall manpage
for other uses.
PUTBACK;
-
Renew
-
The XSUB-writer's interface to the C
realloc
function.
void * Renew( void *ptr, int size, type )
-
Renewc
-
The XSUB-writer's interface to the C
realloc
function, with cast.
void * Renewc( void *ptr, int size, type, cast )
-
RETVAL
-
Variable which is setup by
xsubpp
to hold the return value for an XSUB.
This is always the proper type for the XSUB. See
the perlxs manpage
.
-
safefree
-
The XSUB-writer's interface to the C
free
function.
-
safemalloc
-
The XSUB-writer's interface to the C
malloc
function.
-
saferealloc
-
The XSUB-writer's interface to the C
realloc
function.
-
savepv
-
Copy a string to a safe spot. This does not use an SV.
char* savepv _((char* sv));
-
savepvn
-
Copy a string to a safe spot. The
len
indicates number of bytes to
copy. This does not use an SV.
char* savepvn _((char* sv, I32 len));
-
SAVETMPS
-
Opening bracket for temporaries on a callback. See
FREETMPS
and
the perlcall manpage
.
SAVETMPS;
-
SP
-
Stack pointer. This is usually handled by
xsubpp
. See
dSP
and
SPAGAIN
.
-
SPAGAIN
-
Refetch the stack pointer. Used after a callback. See
the perlcall manpage
.
SPAGAIN;
-
ST
-
Used to access elements on the XSUB's stack.
SV* ST(int x)
-
strEQ
-
Test two strings to see if they are equal. Returns true or false.
int strEQ( char *s1, char *s2 )
-
strGE
-
Test two strings to see if the first,
s1
, is greater than or equal to the
second, s2
. Returns true or false.
int strGE( char *s1, char *s2 )
-
strGT
-
Test two strings to see if the first,
s1
, is greater than the second,
s2
. Returns true or false.
int strGT( char *s1, char *s2 )
-
strLE
-
Test two strings to see if the first,
s1
, is less than or equal to the
second, s2
. Returns true or false.
int strLE( char *s1, char *s2 )
-
strLT
-
Test two strings to see if the first,
s1
, is less than the second,
s2
. Returns true or false.
int strLT( char *s1, char *s2 )
-
strNE
-
Test two strings to see if they are different. Returns true or false.
int strNE( char *s1, char *s2 )
-
strnEQ
-
Test two strings to see if they are equal. The
len
parameter indicates
the number of bytes to compare. Returns true or false.
int strnEQ( char *s1, char *s2 )
-
strnNE
-
Test two strings to see if they are different. The
len
parameter
indicates the number of bytes to compare. Returns true or false.
int strnNE( char *s1, char *s2, int len )
-
sv_2mortal
-
Marks an SV as mortal. The SV will be destroyed when the current context
ends.
SV* sv_2mortal _((SV* sv));
-
sv_bless
-
Blesses an SV into a specified package. The SV must be an RV. The package
must be designated by its stash (see
gv_stashpv()
). The refcount of the
SV is unaffected.
SV* sv_bless _((SV* sv, HV* stash));
-
sv_catpv
-
Concatenates the string onto the end of the string which is in the SV.
- void sv_catpv _((SV* sv, char* ptr));
-
sv_catpvn
-
Concatenates the string onto the end of the string which is in the SV. The
len
indicates number of bytes to copy.
- void sv_catpvn _((SV* sv, char* ptr, STRLEN len));
-
sv_catsv
-
Concatentates the string from SV
ssv
onto the end of the string in SV
dsv
.
- void sv_catsv _((SV* dsv, SV* ssv));
-
SvCUR
-
Returns the length of the string which is in the SV. See
SvLEN
.
int SvCUR (SV* sv)
-
SvCUR_set
-
Set the length of the string which is in the SV. See
SvCUR
.
SvCUR_set (SV* sv, int val )
-
SvEND
-
Returns a pointer to the last character in the string which is in the SV.
See
SvCUR
. Access the character as
*SvEND(sv)
-
SvGROW
-
Expands the character buffer in the SV.
char * SvGROW( SV* sv, int len )
-
SvIOK
-
Returns a boolean indicating whether the SV contains an integer.
int SvIOK (SV* SV)
-
SvIOK_off
-
Unsets the IV status of an SV.
SvIOK_off (SV* sv)
-
SvIOK_on
-
Tells an SV that it is an integer.
SvIOK_on (SV* sv)
-
SvIOKp
-
Returns a boolean indicating whether the SV contains an integer. Checks the
private setting. Use
SvIOK
.
int SvIOKp (SV* SV)
-
sv_isa
-
Returns a boolean indicating whether the SV is blessed into the specified
class. This does not know how to check for subtype, so it doesn't work in
an inheritance relationship.
- int sv_isa _((SV* sv, char* name));
-
SvIV
-
Returns the integer which is in the SV.
int SvIV (SV* sv)
-
sv_isobject
-
Returns a boolean indicating whether the SV is an RV pointing to a blessed
object. If the SV is not an RV, or if the object is not blessed, then this
will return false.
- int sv_isobject _((SV* sv));
-
SvIVX
-
Returns the integer which is stored in the SV.
int SvIVX (SV* sv);
-
SvLEN
-
Returns the size of the string buffer in the SV. See
SvCUR
.
int SvLEN (SV* sv)
-
sv_magic
-
Adds magic to an SV.
- void sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
-
sv_mortalcopy
-
Creates a new SV which is a copy of the original SV. The new SV is marked
as mortal.
SV* sv_mortalcopy _((SV* oldsv));
-
SvOK
-
Returns a boolean indicating whether the value is an SV.
int SvOK (SV* sv)
-
sv_newmortal
-
Creates a new SV which is mortal. The refcount of the SV is set to 1.
SV* sv_newmortal _((void));
-
sv_no
-
This is the
false
SV. See
sv_yes
. Always refer to this as &sv_no
.
-
SvNIOK
-
Returns a boolean indicating whether the SV contains a number, integer or
double.
int SvNIOK (SV* SV)
-
SvNIOK_off
-
Unsets the NV/IV status of an SV.
SvNIOK_off (SV* sv)
-
SvNIOKp
-
Returns a boolean indicating whether the SV contains a number, integer or
double. Checks the private setting. Use
SvNIOK
.
int SvNIOKp (SV* SV)
-
SvNOK
-
Returns a boolean indicating whether the SV contains a double.
int SvNOK (SV* SV)
-
SvNOK_off
-
Unsets the NV status of an SV.
SvNOK_off (SV* sv)
-
SvNOK_on
-
Tells an SV that it is a double.
SvNOK_on (SV* sv)
-
SvNOKp
-
Returns a boolean indicating whether the SV contains a double. Checks the
private setting. Use
SvNOK
.
int SvNOKp (SV* SV)
-
SvNV
-
Returns the double which is stored in the SV.
double SvNV (SV* sv);
-
SvNVX
-
Returns the double which is stored in the SV.
double SvNVX (SV* sv);
-
SvPOK
-
Returns a boolean indicating whether the SV contains a character string.
int SvPOK (SV* SV)
-
SvPOK_off
-
Unsets the PV status of an SV.
SvPOK_off (SV* sv)
-
SvPOK_on
-
Tells an SV that it is a string.
SvPOK_on (SV* sv)
-
SvPOKp
-
Returns a boolean indicating whether the SV contains a character string.
Checks the private setting. Use
SvPOK
.
int SvPOKp (SV* SV)
-
SvPV
-
Returns a pointer to the string in the SV, or a stringified form of the SV
if the SV does not contain a string. If
len
is
na
then Perl will
handle the length on its own.
char * SvPV (SV* sv, int len )
-
SvPVX
-
Returns a pointer to the string in the SV. The SV must contain a string.
char * SvPVX (SV* sv)
-
SvREFCNT
-
Returns the value of the object's refcount.
int SvREFCNT (SV* sv);
-
SvREFCNT_dec
-
Decrements the refcount of the given SV.
void SvREFCNT_dec (SV* sv)
-
SvREFCNT_inc
-
Increments the refcount of the given SV.
void SvREFCNT_inc (SV* sv)
-
SvROK
-
Tests if the SV is an RV.
int SvROK (SV* sv)
-
SvROK_off
-
Unsets the RV status of an SV.
SvROK_off (SV* sv)
-
SvROK_on
-
Tells an SV that it is an RV.
SvROK_on (SV* sv)
-
SvRV
-
Dereferences an RV to return the SV.
SV* SvRV (SV* sv);
-
sv_setiv
-
Copies an integer into the given SV.
- void sv_setiv _((SV* sv, IV num));
-
sv_setnv
-
Copies a double into the given SV.
- void sv_setnv _((SV* sv, double num));
-
sv_setpv
-
Copies a string into an SV. The string must be null-terminated.
- void sv_setpv _((SV* sv, char* ptr));
-
sv_setpvn
-
Copies a string into an SV. The
len
parameter indicates the number of
bytes to be copied.
- void sv_setpvn _((SV* sv, char* ptr, STRLEN len));
-
sv_setref_iv
-
Copies an integer into an SV, optionally blessing the SV. The SV must be an
RV. The
classname
argument indicates the package for the blessing. Set
classname
to
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));
-
sv_setref_nv
-
Copies a double into an SV, optionally blessing the SV. The SV must be an
RV. The
classname
argument indicates the package for the blessing. Set
classname
to
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));
-
sv_setref_pv
-
Copies a pointer into an SV, optionally blessing the SV. The SV must be an
RV. If the
pv
argument is NULL then
sv_undef
will be placed into the
SV. The classname
argument indicates the package for the blessing. Set
classname
to
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));
Do not use with integral Perl types such as HV, AV, SV, CV, because those
objects will become corrupted by the pointer copy process.
Note that
sv_setref_pvn
copies the string while this copies the pointer.
-
sv_setref_pvn
-
Copies a string into an SV, optionally blessing the SV. The lenth of the
string must be specified with
n
. The SV must be an RV. The classname
argument indicates the package for the blessing. Set classname
to
Nullch
to avoid the blessing. The new SV will be returned and will have
a refcount of 1.
SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
Note that
sv_setref_pv
copies the pointer while this copies the string.
-
sv_setsv
-
Copies the contents of the source SV
ssv
into the destination SV dsv
.
- void sv_setsv _((SV* dsv, SV* ssv));
-
SvSTASH
-
Returns the stash of the SV.
HV * SvSTASH (SV* sv)
-
SVt_IV
-
Integer type flag for scalars. See
svtype
.
-
SVt_PV
-
Pointer type flag for scalars. See
svtype
.
-
SVt_PVAV
-
Type flag for arrays. See
svtype
.
-
SVt_PVCV
-
Type flag for code refs. See
svtype
.
-
SVt_PVHV
-
Type flag for hashes. See
svtype
.
-
SVt_PVMG
-
Type flag for blessed scalars. See
svtype
.
-
SVt_NV
-
Double type flag for scalars. See
svtype
.
-
SvTRUE
-
Returns a boolean indicating whether Perl would evaluate the SV as true or
false, defined or undefined.
int SvTRUE (SV* sv)
-
SvTYPE
-
Returns the type of the SV. See
svtype
.
-
svtype
-
An enum of flags for Perl types. These are found in the file sv.h in the
svtype
enum. Test these flags with the
SvTYPE
macro.
-
SvUPGRADE
-
Used to upgrade an SV to a more complex form. See
svtype
.
-
sv_undef
-
This is the
undef
SV. Always refer to this as
&sv_undef
.
-
sv_usepvn
-
Tells an SV to use
ptr
to find its string value. Normally the string is
stored inside the SV; this allows the SV to use an outside string. The
string length, len
, must be supplied. This function will realloc the
memory pointed to by ptr
, so that pointer should not be freed or used by
the programmer after giving it to sv_usepvn.
- void sv_usepvn _((SV* sv, char* ptr, STRLEN len));
-
sv_yes
-
This is the
true
SV. See
sv_no
. Always refer to this as &sv_yes
.
-
THIS
-
Variable which is setup by
xsubpp
to designate the object in a C++ XSUB.
This is always the proper type for the C++ object. See
CLASS
and
the perlxs manpage
.
-
toLOWER
-
Converts the specified character to lowercase.
int toLOWER (char c)
-
toUPPER
-
Converts the specified character to uppercase.
int toUPPER (char c)
-
warn
-
This is the XSUB-writer's interface to Perl's
warn
function. Use this
function the same way you use the C
printf
function. See
croak()
.
-
XPUSHi
-
Push an integer onto the stack, extending the stack if necessary. See
PUSHi
.
XPUSHi(int d)
-
XPUSHn
-
Push a double onto the stack, extending the stack if necessary. See
PUSHn
.
XPUSHn(double d)
-
XPUSHp
-
Push a string onto the stack, extending the stack if necessary. The
len
indicates the length of the string. See
PUSHp
.
XPUSHp(char *c, int len)
-
XPUSHs
-
Push an SV onto the stack, extending the stack if necessary. See
PUSHs
.
XPUSHs(sv)
-
XSRETURN
-
Return from XSUB, indicating number of items on the stack. This is usually
handled by
xsubpp
.
XSRETURN(x);
-
XSRETURN_EMPTY
-
Return from an XSUB immediately.
XSRETURN_EMPTY;
-
XSRETURN_NO
-
Return
false
from an XSUB immediately.
XSRETURN_NO;
-
XSRETURN_UNDEF
-
Return
undef
from an XSUB immediately.
XSRETURN_UNDEF;
-
XSRETURN_YES
-
Return
true
from an XSUB immediately.
XSRETURN_YES;
-
Zero
-
The XSUB-writer's interface to the C
memzero
function. The d
is the
destination, n
is the number of items, and t
is the type.
(void) Zero( d, n, t );
Jeff Okamoto <okamoto@corp.hp.com>
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.
API Listing by Dean Roehrich <roehrich@cray.com>.
Version 20: 1995/12/14