home *** CD-ROM | disk | FTP | other *** search
- <!-- $RCSfile$$Revision$$Date$ -->
- <!-- $Log$ -->
- <HTML>
- <TITLE> PERLGUTS </TITLE>
- <h2>NAME</h2>
- perlguts - Perl's Internal Functions
- <p><h2>DESCRIPTION</h2>
- 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.
- <p><h2>Datatypes</h2>
- Perl has three typedefs that handle Perl's three main data types:
- <p><pre>
- SV Scalar Value
- AV Array Value
- HV Hash Value
- </pre>
- Each typedef has specific routines that manipulate the various data type.
- <p><h3>What is an "IV"?</h3>
- Perl uses a special typedef IV which is large enough to hold either an
- integer or a pointer.
- <p>Perl also uses a special typedef I32 which will always be a 32-bit integer.
- <p><h3>Working with SV's</h3>
- 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).
- <p>The four routines are:
- <p><pre>
- SV* newSViv(IV);
- SV* newSVnv(double);
- SV* newSVpv(char*, int);
- SV* newSVsv(SV*);
- </pre>
- To change the value of an *already-existing* scalar, there are five routines:
- <p><pre>
- 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*);
- </pre>
- Notice that you can choose to specify the length of the string to be
- assigned by using <B>sv_setpvn</B>, or allow Perl to calculate the length by
- using <B>sv_setpv</B>. Be warned, though, that <B>sv_setpv</B> determines the
- string's length by using <B>strlen</B>, which depends on the string terminating
- with a NUL character.
- <p>To access the actual value that an SV points to, you can use the macros:
- <p><pre>
- SvIV(SV*)
- SvNV(SV*)
- SvPV(SV*, STRLEN len)
- </pre>
- which will automatically coerce the actual scalar type into an IV, double,
- or string.
- <p>In the <B>SvPV</B> macro, the length of the string returned is placed into the
- variable <B>len</B> (this is a macro, so you do <I>not</I> use <B>&len</B>). If you do not
- care what the length of the data is, use the global variable <B>na</B>. Remember,
- however, that Perl allows arbitrary strings of data that may both contain
- NUL's and not be terminated by a NUL.
- <p>If you simply want to know if the scalar value is TRUE, you can use:
- <p><pre>
- SvTRUE(SV*)
- </pre>
- 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
- <p><pre>
- SvGROW(SV*, STRLEN newlen)
- </pre>
- which will determine if more memory needs to be allocated. If so, it will
- call the function <B>sv_grow</B>. Note that <B>SvGROW</B> can only increase, not
- decrease, the allocated memory of an SV.
- <p>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.
- <p><pre>
- SvIOK(SV*)
- SvNOK(SV*)
- SvPOK(SV*)
- </pre>
- You can get and set the current length of the string stored in an SV with
- the following macros:
- <p><pre>
- SvCUR(SV*)
- SvCUR_set(SV*, I32 val)
- </pre>
- But note that these are valid only if <B>SvPOK()</B> is true.
- <p>If you know the name of a scalar variable, you can get a pointer to its SV
- by using the following:
- <p><pre>
- SV* perl_get_sv("varname", FALSE);
- </pre>
- This returns NULL if the variable does not exist.
- <p>If you want to know if this variable (or any other SV) is actually defined,
- you can call:
- <p><pre>
- SvOK(SV*)
- </pre>
- The scalar
- <A HREF="perlfunc.html#perlfunc_258">undef</A>
- value is stored in an SV instance called <B>sv_undef</B>. Its
- address can be used whenever an <B>SV*</B> is needed.
- <p>There are also the two values <B>sv_yes</B> and <B>sv_no</B>, which contain Boolean
- TRUE and FALSE values, respectively. Like <B>sv_undef</B>, their addresses can
- be used whenever an <B>SV*</B> is needed.
- <p>Do not be fooled into thinking that <B>(SV *) 0</B> is the same as <B>&sv_undef</B>.
- Take this code:
- <p><pre>
- SV* sv = (SV*) 0;
- if (I-am-to-return-a-real-value) {
- sv = sv_2mortal(newSViv(42));
- }
- sv_setsv(ST(0), sv);
- </pre>
- 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 <B>&sv_undef</B> in the first line and
- all will be well.
- <p>To free an SV that you've created, call <B>SvREFCNT_dec(SV*)</B>. Normally this
- call is not necessary. See the section on <B>MORTALITY</B>.
- <p><h3>Private and Public Values</h3>
- Recall that the usual method of determining the type of scalar you have is
- to use <B>Sv[INP]OK</B> macros. Since a scalar can be both a number and a string,
- usually these macros will always return TRUE and calling the <B>Sv[INP]V</B>
- macros will do the appropriate conversion of string to integer/double or
- integer/double to string.
- <p>If you <I>really</I> need to know if you have an integer, double, or string
- pointer in an SV, you can use the following three macros instead:
- <p><pre>
- SvIOKp(SV*)
- SvNOKp(SV*)
- SvPOKp(SV*)
- </pre>
- These will tell you if you truly have an integer, double, or string pointer
- stored in your SV.
- <p>In general, though, it's best to just use the <B>Sv[INP]V</B> macros.
- <p><h3>Working with AV's</h3>
- There are two ways to create and load an AV. The first method just creates
- an empty AV:
- <p><pre>
- AV* newAV();
- </pre>
- The second method both creates the AV and initially populates it with SV's:
- <p><pre>
- AV* av_make(I32 num, SV **ptr);
- </pre>
- The second argument points to an array containing <B>num</B> <B>SV*</B>'s.
- <p>Once the AV has been created, the following operations are possible on AV's:
- <p><pre>
- void av_push(AV*, SV*);
- SV* av_pop(AV*);
- SV* av_shift(AV*);
- void av_unshift(AV*, I32 num);
- </pre>
- These should be familiar operations, with the exception of <B>av_unshift</B>.
- This routine adds <B>num</B> elements at the front of the array with the
- <A HREF="perlfunc.html#perlfunc_258">undef</A>
-
- value. You must then use <B>av_store</B> (described below) to assign values
- to these new elements.
- <p>Here are some other functions:
- <p><pre>
- I32 av_len(AV*); /* Returns length of array */
- </pre>
- <pre>
- SV** av_fetch(AV*, I32 key, I32 lval);
- /* Fetches value at key offset, but it seems to
- set the value to lval if lval is non-zero */
- SV** av_store(AV*, I32 key, SV* val);
- /* Stores val at offset key */
- </pre>
- <pre>
- void av_clear(AV*);
- /* Clear out all elements, but leave the array */
- void av_undef(AV*);
- /* Undefines the array, removing all elements */
- </pre>
- If you know the name of an array variable, you can get a pointer to its AV
- by using the following:
- <p><pre>
- AV* perl_get_av("varname", FALSE);
- </pre>
- This returns NULL if the variable does not exist.
- <p><h3>Working with HV's</h3>
- To create an HV, you use the following routine:
- <p><pre>
- HV* newHV();
- </pre>
- Once the HV has been created, the following operations are possible on HV's:
- <p><pre>
- SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
- SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
- </pre>
- The <B>klen</B> parameter is the length of the key being passed in. The <B>val</B>
- argument contains the SV pointer to the scalar being stored, and <B>hash</B> is
- the pre-computed hash value (zero if you want <B>hv_store</B> to calculate it
- for you). The <B>lval</B> parameter indicates whether this fetch is actually a
- part of a store operation.
- <p>Remember that <B>hv_store</B> and <B>hv_fetch</B> return <B>SV**</B>'s and not just
- <B>SV*</B>. 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.
- <p>These two functions check if a hash table entry exists, and deletes it.
- <p><pre>
- bool hv_exists(HV*, char* key, U32 klen);
- SV* hv_delete(HV*, char* key, U32 klen);
- </pre>
- And more miscellaneous functions:
- <p><pre>
- void hv_clear(HV*);
- /* Clears all entries in hash table */
- void hv_undef(HV*);
- /* Undefines the hash table */
- </pre>
- <pre>
- 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 */
- </pre>
- If you know the name of a hash variable, you can get a pointer to its HV
- by using the following:
- <p><pre>
- HV* perl_get_hv("varname", FALSE);
- </pre>
- This returns NULL if the variable does not exist.
- <p>The hash algorithm, for those who are interested, is:
- <p><pre>
- i = klen;
- hash = 0;
- s = key;
- while (i--)
- hash = hash * 33 + *s++;
- </pre>
- <h3>References</h3>
- References are a special type of scalar that point to other scalar types
- (including references). To treat an AV or HV as a scalar, it is simply
- a matter of casting an AV or HV to an SV.
- <p>To create a reference, use the following command:
- <p><pre>
- SV* newRV((SV*) pointer);
- </pre>
- Once you have a reference, you can use the following macro with a cast to
- the appropriate typedef (SV, AV, HV):
- <p><pre>
- SvRV(SV*)
- </pre>
- then call the appropriate routines, casting the returned <B>SV*</B> to either an
- <B>AV*</B> or <B>HV*</B>.
- <p>To determine, after dereferencing a reference, if you still have a reference,
- you can use the following macro:
- <p><pre>
- SvROK(SV*)
- </pre>
- <h2>XSUB'S and the Argument Stack</h2>
- 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.
- <p>The stack arguments are accessible through the <B>ST(n)</B> macro, which returns
- the <B>n</B>'th stack argument. Argument 0 is the first argument passed in the
- Perl subroutine call. These arguments are <B>SV*</B>, and can be used anywhere
- an <B>SV*</B> is used.
- <p>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.
- <p>To handle this situation, the PPCODE directive is used and the stack is
- extended using the macro:
- <p><pre>
- EXTEND(sp, num);
- </pre>
- where <B>sp</B> is the stack pointer, and <B>num</B> is the number of elements the
- stack should be extended by.
- <p>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:
- <p><pre>
- PUSHi(IV)
- PUSHn(double)
- PUSHp(char*, I32)
- PUSHs(SV*)
- </pre>
- And now the Perl program calling <B>tzname</B>, the two values will be assigned
- as in:
- <p><pre>
- ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
- </pre>
- An alternate (and possibly simpler) method to pushing values on the stack is
- to use the macros:
- <p><pre>
- XPUSHi(IV)
- XPUSHn(double)
- XPUSHp(char*, I32)
- XPUSHs(SV*)
- </pre>
- These macros automatically adjust the stack for you, if needed.
- <p><h2>Mortality</h2>
- In Perl, values are normally "immortal" -- that is, they are not freed unless
- explicitly done so (via the Perl
- <A HREF="perlfunc.html#perlfunc_258">undef</A>
- call or other routines in Perl
- itself).
- <p>In the above example with <B>tzname</B>, 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.
- <p>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.
- <p>To create a mortal variable, use the functions:
- <p><pre>
- SV* sv_newmortal()
- SV* sv_2mortal(SV*)
- SV* sv_mortalcopy(SV*)
- </pre>
- 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.
- <p>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 <B>SV*</B>) to the <B>sv_2mortal</B> or
- <B>sv_mortalcopy</B> routines.
- <p><h2>Creating New Variables</h2>
- To create a new Perl variable, which can be accessed from your Perl script,
- use the following routines, depending on the variable type.
- <p><pre>
- SV* perl_get_sv("varname", TRUE);
- AV* perl_get_av("varname", TRUE);
- HV* perl_get_hv("varname", TRUE);
- </pre>
- Notice the use of TRUE as the second parameter. The new variable can now
- be set, using the routines appropriate to the data type.
- <p><h2>Stashes and Objects</h2>
- 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
- hash table 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). The 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
- <p>Perl stores various stashes in a GV structure (for global variable) but
- represents them with an HV structure.
- <p>To get the HV pointer for a particular package, use the function:
- <p><pre>
- HV* gv_stashpv(char* name, I32 create)
- HV* gv_stashsv(SV*, I32 create)
- </pre>
- The first function takes a literal string, the second uses the string stored
- in the SV.
- <p>The name that <B>gv_stash*v</B> wants is the name of the package whose symbol table
- you want. The default package is called <B>main</B>. If you have multiply nested
- packages, it is legal to pass their names to <B>gv_stash*v</B>, separated by
- <B>::</B> as in the Perl language itself.
- <p>Alternately, if you have an SV that is a blessed reference, you can find
- out the stash pointer by using:
- <p><pre>
- HV* SvSTASH(SvRV(SV*));
- </pre>
- then use the following to get the package name itself:
- <p><pre>
- char* HvNAME(HV* stash);
- </pre>
- If you need to return a blessed value to your Perl script, you can use the
- following function:
- <p><pre>
- SV* sv_bless(SV*, HV* stash)
- </pre>
- where the first argument, an <B>SV*</B>, must be a reference, and the second
- argument is a stash. The returned <B>SV*</B> can now be used in the same way
- as any other SV.
- <p><h2>Magic</h2>
- [This section under construction]
- <p><h2>Double-Typed SV's</h2>
- 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.
- <p>Some scalar variables contain more than one type of scalar data. For
- example, the variable
- <A HREF="perlvar.html#perlvar_436">$!</A>
- contains either the numeric value of <B>errno</B>
- or its string equivalent from <B>sys_errlist[]</B>.
- <p>To force multiple data values into an SV, you must do two things: use the
- <B>sv_set*v</B> 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:
- <p><pre>
- SvIOK_on
- SvNOK_on
- SvPOK_on
- SvROK_on
- </pre>
- The particular macro you must use depends on which <B>sv_set*v</B> routine
- you called first. This is because every <B>sv_set*v</B> routine turns on
- only the bit for the particular type of data being set, and turns off
- all the rest.
- <p>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:
- <p><pre>
- extern int dberror;
- extern char *dberror_list;
- </pre>
- <pre>
- SV* sv = perl_get_sv("dberror", TRUE);
- sv_setiv(sv, (IV) dberror);
- sv_setpv(sv, dberror_list[dberror]);
- SvIOK_on(sv);
- </pre>
- If the order of <B>sv_setiv</B> and <B>sv_setpv</B> had been reversed, then the
- macro <B>SvPOK_on</B> would need to be called instead of <B>SvIOK_on</B>.
- <p><h2>Calling Perl Routines from within C Programs</h2>
- There are four routines that can be used to call a Perl subroutine from
- within a C program. These four are:
- <p><pre>
- 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**);
- </pre>
- The routine most often used should be <B>perl_call_sv</B>. The <B>SV*</B> argument
- contains either the name of the Perl subroutine to be called, or a reference
- to the subroutine. The second argument tells the appropriate routine what,
- if any, variables are being returned by the Perl subroutine.
- <p>All four routines return the number of arguments that the subroutine returned
- on the Perl stack.
- <p>When using these four routines, the programmer must manipulate the Perl stack.
- These include the following macros and functions:
- <p><pre>
- dSP
- PUSHMARK()
- PUTBACK
- SPAGAIN
- ENTER
- SAVETMPS
- FREETMPS
- LEAVE
- XPUSH*()
- </pre>
- For more information, consult
- <A HREF="perlcall.html">
- the perlcall manpage</A>
- .
- <p><h2>Memory Allocation</h2>
- [This section under construction]
- <p><h2>AUTHOR</h2>
- Jeff Okamoto <okamoto@corp.hp.com>
- <p>With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
- Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, and Neil
- Bowers.
- <p><h2>DATE</h2>
- Version 12: 1994/10/16
- <p>