Initial import of Perl5. The king is dead; long live the king!vendor/perl5/5.005.02

1 files changed, 3557 insertions, 0 deletions

diff --git a/contrib/perl5/pod/perlguts.pod b/contrib/perl5/pod/perlguts.pod
new file mode 100644
index 000000000000..20a07d38540d
--- /dev/null
+++ b/contrib/perl5/pod/perlguts.pod
@@ -0,0 +1,3557 @@
+=head1 NAME
+
+perlguts - Perl's Internal Functions
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 Variables
+
+=head2 Datatypes
+
+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.
+
+=head2 What is an "IV"?
+
+Perl uses a special typedef IV which is a simple integer type that is
+guaranteed to be large enough to hold a pointer (as well as an integer).
+
+Perl also uses two special typedefs, I32 and I16, which will always be at
+least 32-bits and 16-bits long, respectively.
+
+=head2 Working with 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).
+
+The six routines are:
+
+    SV*  newSViv(IV);
+    SV*  newSVnv(double);
+    SV*  newSVpv(char*, int);
+    SV*  newSVpvn(char*, int);
+    SV*  newSVpvf(const char*, ...);
+    SV*  newSVsv(SV*);
+
+To change the value of an *already-existing* SV, there are seven routines:
+
+    void  sv_setiv(SV*, IV);
+    void  sv_setuv(SV*, UV);
+    void  sv_setnv(SV*, double);
+    void  sv_setpv(SV*, char*);
+    void  sv_setpvn(SV*, char*, int)
+    void  sv_setpvf(SV*, const char*, ...);
+    void  sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+    void  sv_setsv(SV*, SV*);
+
+Notice that you can choose to specify the length of the string to be
+assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
+allow Perl to calculate the length by using C<sv_setpv> or by specifying
+0 as the second argument to C<newSVpv>.  Be warned, though, that Perl will
+determine the string's length by using C<strlen>, which depends on the
+string terminating with a NUL character.
+
+The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
+formatted output becomes the value.
+
+C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify
+either a pointer to a variable argument list or the address and length of
+an array of SVs.  The last argument points to a boolean; on return, if that
+boolean is true, then locale-specific information has been used to format
+the string, and the string's contents are therefore untrustworty (see
+L<perlsec>).  This pointer may be NULL if that information is not
+important.  Note that this function requires you to specify the length of
+the format.
+
+The C<sv_set*()> functions are not generic enough to operate on values
+that have "magic".  See L<Magic Virtual Tables> later in this document.
+
+All SVs that contain strings should be terminated with a NUL character.
+If it is not NUL-terminated there is a risk of
+core dumps and corruptions from code which passes the string to C
+functions or system calls which expect a NUL-terminated string.
+Perl's own functions typically add a trailing NUL for this reason.
+Nevertheless, you should be very careful when you pass a string stored
+in an SV to a C function or system call.
+
+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 C<SvPV> macro, the length of the string returned is placed into the
+variable C<len> (this is a macro, so you do I<not> use C<&len>).  If you do not
+care what the length of the data is, use the global variable C<PL_na>.  Remember,
+however, that Perl allows arbitrary strings of data that may both contain
+NULs and might not be terminated by a NUL.
+
+If you 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 C<sv_grow>.  Note that C<SvGROW> can only increase, not
+decrease, the allocated memory of an SV and that it does not automatically
+add a byte for the a trailing NUL (perl's own string functions typically do
+C<SvGROW(sv, len + 1)>).
+
+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 C<SvPOK()> is true.
+
+If you want to append something to the end of string stored in an C<SV*>,
+you can use the following functions:
+
+    void  sv_catpv(SV*, char*);
+    void  sv_catpvn(SV*, char*, int);
+    void  sv_catpvf(SV*, const char*, ...);
+    void  sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+    void  sv_catsv(SV*, SV*);
+
+The first function calculates the length of the string to be appended by
+using C<strlen>.  In the second, you specify the length of the string
+yourself.  The third function processes its arguments like C<sprintf> and
+appends the formatted output.  The fourth function works like C<vsprintf>.
+You can specify the address and length of an array of SVs instead of the
+va_list argument. The fifth 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.
+
+The C<sv_cat*()> functions are not generic enough to operate on values that
+have "magic".  See L<Magic Virtual Tables> later in this document.
+
+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("package::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 C<defined>,
+you can call:
+
+    SvOK(SV*)
+
+The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.  Its
+address can be used whenever an C<SV*> is needed.
+
+There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
+TRUE and FALSE values, respectively.  Like C<PL_sv_undef>, their addresses can
+be used whenever an C<SV*> is needed.
+
+Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_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,
+bus error, or just weird results.  Change the zero to C<&PL_sv_undef> in the first
+line and all will be well.
+
+To free an SV that you've created, call C<SvREFCNT_dec(SV*)>.  Normally this
+call is not necessary (see L<Reference Counts and Mortality>).
+
+=head2 What's Really Stored in an SV?
+
+Recall that the usual method of determining the type of scalar you have is
+to use C<Sv*OK> macros.  Because a scalar can be both a number and a string,
+usually these macros will always return TRUE and calling the C<Sv*V>
+macros will do the appropriate conversion of string to integer/double or
+integer/double to string.
+
+If you I<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 use the C<Sv*V> macros.
+
+=head2 Working with AVs
+
+There are two ways to create and load an AV.  The first method creates an
+empty AV:
+
+    AV*  newAV();
+
+The second method both creates the AV and initially populates it with SVs:
+
+    AV*  av_make(I32 num, SV **ptr);
+
+The second argument points to an array containing C<num> C<SV*>'s.  Once the
+AV has been created, the SVs can be destroyed, if so desired.
+
+Once the AV has been created, the following operations are possible on AVs:
+
+    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 C<av_unshift>.
+This routine adds C<num> elements at the front of the array with the C<undef>
+value.  You must then use C<av_store> (described below) to assign values
+to these new elements.
+
+Here are some other functions:
+
+    I32   av_len(AV*);
+    SV**  av_fetch(AV*, I32 key, I32 lval);
+    SV**  av_store(AV*, I32 key, SV* val);
+
+The C<av_len> function returns the highest index value in array (just
+like $#array in Perl).  If the array is empty, -1 is returned.  The
+C<av_fetch> function returns the value at index C<key>, but if C<lval>
+is non-zero, then C<av_fetch> will store an undef value at that index.
+The C<av_store> function stores the value C<val> at index C<key>, and does
+not increment the reference count of C<val>.  Thus the caller is responsible
+for taking care of that, and if C<av_store> returns NULL, the caller will
+have to decrement the reference count to avoid a memory leak.  Note that
+C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
+return value.
+
+    void  av_clear(AV*);
+    void  av_undef(AV*);
+    void  av_extend(AV*, I32 key);
+
+The C<av_clear> function deletes all the elements in the AV* array, but
+does not actually delete the array itself.  The C<av_undef> function will
+delete all the elements in the array plus the array itself.  The
+C<av_extend> function extends the array so that it contains C<key>
+elements.  If C<key> is less than the current length of the array, then
+nothing is done.
+
+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("package::varname", FALSE);
+
+This returns NULL if the variable does not exist.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use the array access functions on tied arrays.
+
+=head2 Working with HVs
+
+To create an HV, you use the following routine:
+
+    HV*  newHV();
+
+Once the HV has been created, the following operations are possible on HVs:
+
+    SV**  hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
+    SV**  hv_fetch(HV*, char* key, U32 klen, I32 lval);
+
+The C<klen> parameter is the length of the key being passed in (Note that
+you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
+length of the key).  The C<val> argument contains the SV pointer to the
+scalar being stored, and C<hash> is the precomputed hash value (zero if
+you want C<hv_store> to calculate it for you).  The C<lval> parameter
+indicates whether this fetch is actually a part of a store operation, in
+which case a new undefined value will be added to the HV with the supplied
+key and C<hv_fetch> will return as if the value had already existed.
+
+Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
+C<SV*>.  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);
+
+If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
+create and return a mortal copy of the deleted value.
+
+And more miscellaneous functions:
+
+    void   hv_clear(HV*);
+    void   hv_undef(HV*);
+
+Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
+table but does not actually delete the hash table.  The C<hv_undef> deletes
+both the entries and the hash table itself.
+
+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 C<SV*>.  However,
+once you have an C<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("package::varname", FALSE);
+
+This returns NULL if the variable does not exist.
+
+The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
+
+    i = klen;
+    hash = 0;
+    s = key;
+    while (i--)
+	hash = hash * 33 + *s++;
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use the hash access functions on tied hashes.
+
+=head2 Hash API Extensions
+
+Beginning with version 5.004, the following functions are also supported:
+
+    HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
+    HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
+    
+    bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
+    SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
+    
+    SV*     hv_iterkeysv  (HE* entry);
+
+Note that these functions take C<SV*> keys, which simplifies writing
+of extension code that deals with hash structures.  These functions
+also allow passing of C<SV*> keys to C<tie> functions without forcing
+you to stringify the keys (unlike the previous set of functions).
+
+They also return and accept whole hash entries (C<HE*>), making their
+use more efficient (since the hash number for a particular string
+doesn't have to be recomputed every time).  See L<API LISTING> later in
+this document for detailed descriptions.
+
+The following macros must always be used to access the contents of hash
+entries.  Note that the arguments to these macros must be simple
+variables, since they may get evaluated more than once.  See
+L<API LISTING> later in this document for detailed descriptions of these
+macros.
+
+    HePV(HE* he, STRLEN len)
+    HeVAL(HE* he)
+    HeHASH(HE* he)
+    HeSVKEY(HE* he)
+    HeSVKEY_force(HE* he)
+    HeSVKEY_set(HE* he, SV* sv)
+
+These two lower level macros are defined, but must only be used when
+dealing with keys that are not C<SV*>s:
+
+    HeKEY(HE* he)
+    HeKLEN(HE* he)
+
+Note that both C<hv_store> and C<hv_store_ent> do not increment the
+reference count of the stored C<val>, which is the caller's responsibility.
+If these functions return a NULL value, the caller will usually have to
+decrement the reference count of C<val> to avoid a memory leak.
+
+=head2 References
+
+References are a special type of scalar that point to other data types
+(including references).
+
+To create a reference, use either of the following functions:
+
+    SV* newRV_inc((SV*) thing);
+    SV* newRV_noinc((SV*) thing);
+
+The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>.  The
+functions are identical except that C<newRV_inc> increments the reference
+count of the C<thing>, while C<newRV_noinc> does not.  For historical
+reasons, C<newRV> is a synonym for C<newRV_inc>.
+
+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 C<SV*> to either an
+C<AV*> or C<HV*>, if required.
+
+To determine if an SV is a reference, you can use the following macro:
+
+    SvROK(SV*)
+
+To discover what type of value the reference refers to, use the following
+macro and then check the return value.
+
+    SvTYPE(SvRV(SV*))
+
+The most useful types that will be returned are:
+
+    SVt_IV    Scalar
+    SVt_NV    Scalar
+    SVt_PV    Scalar
+    SVt_RV    Scalar
+    SVt_PVAV  Array
+    SVt_PVHV  Hash
+    SVt_PVCV  Code
+    SVt_PVGV  Glob (possible a file handle)
+    SVt_PVMG  Blessed or Magical Scalar
+
+    See the sv.h header file for more details.
+
+=head2 Blessed References and Class Objects
+
+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 C<sv> argument must be a reference.  The C<stash> argument specifies
+which class the reference will belong to.  See
+L<Stashes and Globs> 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 C<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 C<rv>.  SV is blessed
+if C<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 the pointer value (I<the address, not the string!>) into an SV whose
+reference is rv.  SV is blessed if C<classname> is non-null.
+
+	SV* sv_setref_pv(SV* rv, char* classname, PV iv);
+
+Copies string into an SV whose reference is C<rv>.  Set length to 0 to let
+Perl calculate the string length.  SV is blessed if C<classname> is non-null.
+
+	SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
+
+Tests whether the SV is blessed into the specified class.  It does not
+check inheritance relationships.
+
+	int  sv_isa(SV* sv, char* name);
+
+Tests whether the SV is a reference to a blessed object.
+
+	int  sv_isobject(SV* sv);
+
+Tests whether the SV is derived from the specified class. SV can be either
+a reference to a blessed object or a string containing a class name. This
+is the function implementing the C<UNIVERSAL::isa> functionality.
+
+	bool sv_derived_from(SV* sv, char* name);
+
+To check if you've got an object derived from a specific class you have 
+to write:
+
+	if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
+
+=head2 Creating New Variables
+
+To create a new Perl variable with an undef value which can be accessed from
+your Perl script, use the following routines, depending on the variable type.
+
+    SV*  perl_get_sv("package::varname", TRUE);
+    AV*  perl_get_av("package::varname", TRUE);
+    HV*  perl_get_hv("package::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 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.
+
+If you do not specify a package name, the variable is created in the current
+package.
+
+=head2 Reference Counts and Mortality
+
+Perl uses an reference count-driven garbage collection mechanism. SVs,
+AVs, or HVs (xV for short in the following) start their life with a
+reference count of 1.  If the reference count of an xV ever drops to 0,
+then it will be destroyed and its memory made available for reuse.
+
+This normally doesn't happen at the Perl level unless a variable is
+undef'ed or the last variable holding a reference to it is changed or
+overwritten.  At the internal level, however, reference counts can be
+manipulated with the following macros:
+
+    int SvREFCNT(SV* sv);
+    SV* SvREFCNT_inc(SV* sv);
+    void SvREFCNT_dec(SV* sv);
+
+However, there is one other function which manipulates the reference
+count of its argument.  The C<newRV_inc> function, you will recall,
+creates a reference to the specified argument.  As a side effect,
+it increments the argument's reference count.  If this is not what
+you want, use C<newRV_noinc> instead.
+
+For example, imagine you want to return a reference from an XSUB function.
+Inside the XSUB routine, you create an SV which initially has a reference
+count of one.  Then you call C<newRV_inc>, passing it the just-created SV.
+This returns the reference as a new SV, but the reference count of the
+SV you passed to C<newRV_inc> has been incremented to two.  Now you
+return the reference from the XSUB routine and forget about the SV.
+But Perl hasn't!  Whenever the returned reference is destroyed, the
+reference count of the original SV is decreased to one and nothing happens.
+The SV will hang around without any way to access it until Perl itself
+terminates.  This is a memory leak.
+
+The correct procedure, then, is to use C<newRV_noinc> instead of
+C<newRV_inc>.  Then, if and when the last reference is destroyed,
+the reference count of the SV will go to zero and it will be destroyed,
+stopping any memory leak.
+
+There are some convenience functions available that can help with the
+destruction of xVs.  These functions introduce the concept of "mortality".
+An xV that is mortal has had its reference count marked to be decremented,
+but not actually decremented, until "a short time later".  Generally the
+term "short time later" means a single Perl statement, such as a call to
+an XSUB function.  The actual determinant for when mortal xVs have their
+reference count decremented depends on two macros, SAVETMPS and FREETMPS.
+See L<perlcall> and L<perlxs> for more details on these macros.
+
+"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
+However, if you mortalize a variable twice, the reference count will
+later be decremented twice.
+
+You should be careful about creating mortal variables.  Strange things
+can happen if you make the same value mortal within multiple contexts,
+or if you make a variable mortal multiple times.
+
+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 (and thus defers a call to C<SvREFCNT_dec>), and the
+third creates a mortal copy of an existing SV.
+
+The mortal routines are not just for SVs -- AVs and HVs can be
+made mortal by passing their address (type-casted to C<SV*>) to the
+C<sv_2mortal> or C<sv_mortalcopy> routines.
+
+=head2 Stashes and Globs
+
+A "stash" is a hash 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 a GV (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
+    I/O Handle
+    Format
+    Subroutine
+
+There is a single stash called "PL_defstash" that holds the items that exist
+in the "main" package.  To get at the items in other packages, append the
+string "::" to the package name.  The items in the "Foo" package are in
+the stash "Foo::" in PL_defstash.  The items in the "Bar::Baz" package are
+in the stash "Baz::" in "Bar::"'s stash.
+
+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
+C<HV*>.  The C<create> flag will create a new package if it is set.
+
+The name that C<gv_stash*v> wants is the name of the package whose symbol table
+you want.  The default package is called C<main>.  If you have multiply nested
+packages, pass their names to C<gv_stash*v>, separated by C<::> 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 bless or re-bless an object you can use the following
+function:
+
+    SV*  sv_bless(SV*, HV* stash)
+
+where the first argument, an C<SV*>, must be a reference, and the second
+argument is a stash.  The returned C<SV*> can now be used in the same way
+as any other SV.
+
+For more information on references and blessings, consult L<perlref>.
+
+=head2 Double-Typed SVs
+
+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 C<$!> contains either the numeric value of C<errno>
+or its string equivalent from either C<strerror> or C<sys_errlist[]>.
+
+To force multiple data values into an SV, you must do two things: use the
+C<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 C<sv_set*v> routine
+you called first.  This is because every C<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 C<sv_setiv> and C<sv_setpv> had been reversed, then the
+macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+
+=head2 Magic Variables
+
+[This section still under construction.  Ignore everything here.  Post no
+bills.  Everything not permitted is forbidden.]
+
+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 C<struct magic>'s, typedef'ed to C<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.
+
+=head2 Assigning Magic
+
+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 C<sv> argument is a pointer to the SV that is to acquire a new magical
+feature.
+
+If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
+set the C<SVt_PVMG> flag for the C<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
+overridden, and multiple instances of the same type of magic can be
+associated with an SV.
+
+The C<name> and C<namlen> arguments are used to associate a string with
+the magic, typically the name of a variable. C<namlen> is stored in the
+C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
+copy of the name is stored in C<mg_ptr> field.
+
+The sv_magic function uses C<how> to determine which, if any, predefined
+"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
+See the "Magic Virtual Table" section below.  The C<how> argument is also
+stored in the C<mg_type> field.
+
+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
+count of the C<obj> object is incremented.  If it is the same, or if
+the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
+merely stored, without the reference count being incremented.
+
+There is also a function to add magic to an C<HV>:
+
+    void hv_magic(HV *hv, GV *gv, int how);
+
+This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
+
+To remove the magic from an SV, call the function sv_unmagic:
+
+    void sv_unmagic(SV *sv, int type);
+
+The C<type> argument should be equal to the C<how> value when the C<SV>
+was initially made magical.
+
+=head2 Magic Virtual Tables
+
+The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
+C<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 C<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 C<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 C<vtbl_sv> (which corresponds
+to an C<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 C<magic_get> is called.  All
+the various routines for the various magical types begin with C<magic_>.
+
+The current kinds of Magic Virtual Tables are:
+
+    mg_type  MGVTBL              Type of magic
+    -------  ------              ----------------------------
+    \0       vtbl_sv             Special scalar variable
+    A        vtbl_amagic         %OVERLOAD hash
+    a        vtbl_amagicelem     %OVERLOAD hash element
+    c        (none)              Holds overload table (AMT) on stash
+    B        vtbl_bm             Boyer-Moore (fast string search)
+    E        vtbl_env            %ENV hash
+    e        vtbl_envelem        %ENV hash element
+    f        vtbl_fm             Formline ('compiled' format)
+    g        vtbl_mglob          m//g target / study()ed string
+    I        vtbl_isa            @ISA array
+    i        vtbl_isaelem        @ISA array element
+    k        vtbl_nkeys          scalar(keys()) lvalue
+    L        (none)              Debugger %_<filename 
+    l        vtbl_dbline         Debugger %_<filename element
+    o        vtbl_collxfrm       Locale transformation
+    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            %SIG hash
+    s        vtbl_sigelem        %SIG hash element
+    t        vtbl_taint          Taintedness
+    U        vtbl_uvar           Available for use by extensions
+    v        vtbl_vec            vec() lvalue
+    x        vtbl_substr         substr() lvalue
+    y        vtbl_defelem        Shadow "foreach" iterator variable /
+                                  smart parameter vivification
+    *        vtbl_glob           GV (typeglob)
+    #        vtbl_arylen         Array length ($#ary)
+    .        vtbl_pos            pos() lvalue
+    ~        (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.
+
+The '~' and 'U' magic types are defined specifically for use by
+extensions and will not be used by perl itself.  Extensions can use
+'~' magic to 'attach' private information to variables (typically
+objects).  This is especially useful because there is no way for
+normal perl code to corrupt this private information (unlike using
+extra elements of a hash object).
+
+Similarly, 'U' magic can be used much like tie() to call a C function
+any time a scalar's value is used or changed.  The C<MAGIC>'s
+C<mg_ptr> field points to a C<ufuncs> structure:
+
+    struct ufuncs {
+        I32 (*uf_val)(IV, SV*);
+        I32 (*uf_set)(IV, SV*);
+        IV uf_index;
+    };
+
+When the SV is read from or written to, the C<uf_val> or C<uf_set>
+function will be called with C<uf_index> as the first arg and a
+pointer to the SV as the second.
+
+Note that because multiple extensions may be using '~' or 'U' magic,
+it is important for extensions to take extra care to avoid conflict.
+Typically only using the magic on objects blessed into the same class
+as the extension is sufficient.  For '~' magic, it may also be
+appropriate to add an I32 'signature' at the top of the private data
+area and check that.
+
+Also note that the C<sv_set*()> and C<sv_cat*()> functions described
+earlier do B<not> invoke 'set' magic on their targets.  This must
+be done by the user either by calling the C<SvSETMAGIC()> macro after
+calling these functions, or by using one of the C<sv_set*_mg()> or
+C<sv_cat*_mg()> functions.  Similarly, generic C code must call the
+C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
+obtained from external sources in functions that don't handle magic.
+L<API LISTING> later in this document identifies such functions.
+For example, calls to the C<sv_cat*()> functions typically need to be
+followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
+since their implementation handles 'get' magic.
+
+=head2 Finding Magic
+
+    MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
+
+This routine returns a pointer to the C<MAGIC> structure stored in the SV.
+If the SV does not have that magical feature, C<NULL> is returned.  Also,
+if the SV is not of type SVt_PVMG, Perl may core dump.
+
+    int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
+
+This routine checks to see what types of magic C<sv> has.  If the mg_type
+field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
+the mg_type field is changed to be the lowercase letter.
+
+=head2 Understanding the Magic of Tied Hashes and Arrays
+
+Tied hashes and arrays are magical beasts of the 'P' magic type.
+
+WARNING: As of the 5.004 release, proper usage of the array and hash
+access functions requires understanding a few caveats.  Some
+of these caveats are actually considered bugs in the API, to be fixed
+in later releases, and are bracketed with [MAYCHANGE] below. If
+you find yourself actually applying such information in this section, be
+aware that the behavior may change in the future, umm, without warning.
+
+The C<av_store> function, when given a tied array argument, merely
+copies the magic of the array onto the value to be "stored", using
+C<mg_copy>.  It may also return NULL, indicating that the value did not
+actually need to be stored in the array.  [MAYCHANGE] After a call to
+C<av_store> on a tied array, the caller will usually need to call
+C<mg_set(val)> to actually invoke the perl level "STORE" method on the
+TIEARRAY object.  If C<av_store> did return NULL, a call to
+C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
+leak. [/MAYCHANGE]
+
+The previous paragraph is applicable verbatim to tied hash access using the
+C<hv_store> and C<hv_store_ent> functions as well.
+
+C<av_fetch> and the corresponding hash functions C<hv_fetch> and
+C<hv_fetch_ent> actually return an undefined mortal value whose magic
+has been initialized using C<mg_copy>.  Note the value so returned does not
+need to be deallocated, as it is already mortal.  [MAYCHANGE] But you will
+need to call C<mg_get()> on the returned value in order to actually invoke
+the perl level "FETCH" method on the underlying TIE object.  Similarly,
+you may also call C<mg_set()> on the return value after possibly assigning
+a suitable value to it using C<sv_setsv>,  which will invoke the "STORE"
+method on the TIE object. [/MAYCHANGE]
+
+[MAYCHANGE]
+In other words, the array or hash fetch/store functions don't really
+fetch and store actual values in the case of tied arrays and hashes.  They
+merely call C<mg_copy> to attach magic to the values that were meant to be
+"stored" or "fetched".  Later calls to C<mg_get> and C<mg_set> actually
+do the job of invoking the TIE methods on the underlying objects.  Thus
+the magic mechanism currently implements a kind of lazy access to arrays
+and hashes.
+
+Currently (as of perl version 5.004), use of the hash and array access
+functions requires the user to be aware of whether they are operating on
+"normal" hashes and arrays, or on their tied variants.  The API may be
+changed to provide more transparent access to both tied and normal data
+types in future versions.
+[/MAYCHANGE]
+
+You would do well to understand that the TIEARRAY and TIEHASH interfaces
+are mere sugar to invoke some perl method calls while using the uniform hash
+and array syntax.  The use of this sugar imposes some overhead (typically
+about two to four extra opcodes per FETCH/STORE operation, in addition to
+the creation of all the mortal variables required to invoke the methods).
+This overhead will be comparatively small if the TIE methods are themselves
+substantial, but if they are only a few statements long, the overhead
+will not be insignificant.
+
+=head2 Localizing changes
+
+Perl has a very handy construction
+
+  {
+    local $var = 2;
+    ...
+  }
+
+This construction is I<approximately> equivalent to
+
+  {
+    my $oldvar = $var;
+    $var = 2;
+    ...
+    $var = $oldvar;
+  }
+
+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
+more efficient as well.
+
+There is a way to achieve a similar task from C via Perl API: create a
+I<pseudo-block>, and arrange for some changes to be automatically
+undone at the end of it, either explicit, or via a non-local exit (via
+die()). A I<block>-like construct is created by a pair of
+C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a
+Scalar">).  Such a construct may be created specially for some
+important localized task, or an existing one (like boundaries of
+enclosing Perl subroutine/block, or an existing pair for freeing TMPs)
+may be used. (In the second case the overhead of additional
+localization must be almost negligible.) Note that any XSUB is
+automatically enclosed in an C<ENTER>/C<LEAVE> pair.
+
+Inside such a I<pseudo-block> the following service is available:
+
+=over
+
+=item C<SAVEINT(int i)>
+
+=item C<SAVEIV(IV i)>
+
+=item C<SAVEI32(I32 i)>
+
+=item C<SAVELONG(long i)>
+
+These macros arrange things to restore the value of integer variable
+C<i> at the end of enclosing I<pseudo-block>.
+
+=item C<SAVESPTR(s)>
+
+=item C<SAVEPPTR(p)>
+
+These macros arrange things to restore the value of pointers C<s> and
+C<p>. C<s> must be a pointer of a type which survives conversion to
+C<SV*> and back, C<p> should be able to survive conversion to C<char*>
+and back.
+
+=item C<SAVEFREESV(SV *sv)>
+
+The refcount of C<sv> would be decremented at the end of
+I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
+used instead.
+
+=item C<SAVEFREEOP(OP *op)>
+
+The C<OP *> is op_free()ed at the end of I<pseudo-block>.
+
+=item C<SAVEFREEPV(p)>
+
+The chunk of memory which is pointed to by C<p> is Safefree()ed at the
+end of I<pseudo-block>.
+
+=item C<SAVECLEARSV(SV *sv)>
+
+Clears a slot in the current scratchpad which corresponds to C<sv> at
+the end of I<pseudo-block>.
+
+=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
+
+The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
+string pointed to by C<key> is Safefree()ed.  If one has a I<key> in
+short-lived storage, the corresponding string may be reallocated like
+this:
+
+  SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
+
+=item C<SAVEDESTRUCTOR(f,p)>
+
+At the end of I<pseudo-block> the function C<f> is called with the
+only argument (of type C<void*>) C<p>.
+
+=item C<SAVESTACK_POS()>
+
+The current offset on the Perl internal stack (cf. C<SP>) is restored
+at the end of I<pseudo-block>.
+
+=back
+
+The following API list contains functions, thus one needs to
+provide pointers to the modifiable data explicitly (either C pointers,
+or Perlish C<GV *>s).  Where the above macros take C<int>, a similar 
+function takes C<int *>.
+
+=over
+
+=item C<SV* save_scalar(GV *gv)>
+
+Equivalent to Perl code C<local $gv>.
+
+=item C<AV* save_ary(GV *gv)>
+
+=item C<HV* save_hash(GV *gv)>
+
+Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
+
+=item C<void save_item(SV *item)>
+
+Duplicates the current value of C<SV>, on the exit from the current
+C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
+using the stored value.
+
+=item C<void save_list(SV **sarg, I32 maxsarg)>
+
+A variant of C<save_item> which takes multiple arguments via an array
+C<sarg> of C<SV*> of length C<maxsarg>.
+
+=item C<SV* save_svref(SV **sptr)>
+
+Similar to C<save_scalar>, but will reinstate a C<SV *>.
+
+=item C<void save_aptr(AV **aptr)>
+
+=item C<void save_hptr(HV **hptr)>
+
+Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
+
+=back
+
+The C<Alias> module implements localization of the basic types within the
+I<caller's scope>.  People who are interested in how to localize things in
+the containing scope should take a look there too.
+
+=head1 Subroutines
+
+=head2 XSUBs and the Argument Stack
+
+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 C<ST(n)> macro, which returns
+the C<n>'th stack argument.  Argument 0 is the first argument passed in the
+Perl subroutine call.  These arguments are C<SV*>, and can be used anywhere
+an C<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 time zone'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 C<SP> is the macro that represents the local copy of the stack pointer,
+and C<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 IVs, doubles, strings, and SV pointers respectively:
+
+    PUSHi(IV)
+    PUSHn(double)
+    PUSHp(char*, I32)
+    PUSHs(SV*)
+
+And now the Perl program calling C<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.  Thus, you
+do not need to call C<EXTEND> to extend the stack.
+
+For more information, consult L<perlxs> and L<perlxstut>.
+
+=head2 Calling Perl Routines from within C Programs
+
+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 C<perl_call_sv>.  The C<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 C<perl_call_argv>), the programmer
+must manipulate the Perl stack.  These include the following macros and
+functions:
+
+    dSP
+    SP
+    PUSHMARK()
+    PUTBACK
+    SPAGAIN
+    ENTER
+    SAVETMPS
+    FREETMPS
+    LEAVE
+    XPUSH*()
+    POP*()
+
+For a detailed description of calling conventions from C to Perl,
+consult L<perlcall>.
+
+=head2 Memory Allocation
+
+It is 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 satisfy allocation requests more quickly.  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 C<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 (most Perl developers now
+use run-time memory checkers), so this argument can be any number.
+
+The second argument C<pointer> should be the name of a variable that will
+point to the newly allocated memory.
+
+The third and fourth arguments C<number> and C<type> specify how many of
+the specified type of data structure should be allocated.  The argument
+C<type> is passed to C<sizeof>.  The final argument to C<Newc>, C<cast>,
+should be used if the C<pointer> argument is different from the C<type>
+argument.
+
+Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<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 C<Renew> and C<Renewc>
+match those of C<New> and C<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 C<source> and C<dest> arguments point to the source and
+destination starting points.  Perl will move, copy, or zero out C<number>
+instances of the size of the C<type> data structure (using the C<sizeof>
+function).
+
+=head2 PerlIO
+
+The most recent development releases of Perl has been experimenting with
+removing Perl's dependency on the "normal" standard I/O suite and allowing
+other stdio implementations to be used.  This involves creating a new
+abstraction layer that then calls whichever implementation of stdio Perl
+was compiled with.  All XSUBs should now use the functions in the PerlIO
+abstraction layer and not make any assumptions about what kind of stdio
+is being used.
+
+For a complete description of the PerlIO abstraction, consult L<perlapio>.
+
+=head2 Putting a C value on Perl stack
+
+A lot of opcodes (this is an elementary operation in the internal perl
+stack machine) put an SV* on the stack. However, as an optimization
+the corresponding SV is (usually) not recreated each time. The opcodes
+reuse specially assigned SVs (I<target>s) which are (as a corollary)
+not constantly freed/created.
+
+Each of the targets is created only once (but see
+L<Scratchpads and recursion> below), and when an opcode needs to put
+an integer, a double, or a string on stack, it just sets the
+corresponding parts of its I<target> and puts the I<target> on stack.
+
+The macro to put this target on stack is C<PUSHTARG>, and it is
+directly used in some opcodes, as well as indirectly in zillions of
+others, which use it via C<(X)PUSH[pni]>.
+
+=head2 Scratchpads
+
+The question remains on when the SVs which are I<target>s for opcodes
+are created. The answer is that they are created when the current unit --
+a subroutine or a file (for opcodes for statements outside of
+subroutines) -- is compiled. During this time a special anonymous Perl
+array is created, which is called a scratchpad for the current
+unit.
+
+A scratchpad keeps SVs which are lexicals for the current unit and are
+targets for opcodes. One can deduce that an SV lives on a scratchpad
+by looking on its flags: lexicals have C<SVs_PADMY> set, and
+I<target>s have C<SVs_PADTMP> set.
+
+The correspondence between OPs and I<target>s is not 1-to-1. Different
+OPs in the compile tree of the unit can use the same target, if this
+would not conflict with the expected life of the temporary.
+
+=head2 Scratchpads and recursion
+
+In fact it is not 100% true that a compiled unit contains a pointer to
+the scratchpad AV. In fact it contains a pointer to an AV of
+(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
+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
+child), the parent and the child should have different
+scratchpads. (I<And> the lexicals should be separate anyway!)
+
+So each subroutine is born with an array of scratchpads (of length 1).
+On each entry to the subroutine it is checked that the current
+depth of the recursion is not more than the length of this array, and
+if it is, new scratchpad is created and pushed into the array.
+
+The I<target>s on this scratchpad are C<undef>s, but they are already
+marked with correct flags.
+
+=head1 Compiled code
+
+=head2 Code tree
+
+Here we describe the internal form your code is converted to by
+Perl. Start with a simple example:
+
+  $a = $b + $c;
+
+This is converted to a tree similar to this one:
+
+             assign-to
+           /           \
+          +             $a
+        /   \
+      $b     $c
+
+(but slightly more complicated).  This tree reflects the way Perl
+parsed your code, but has nothing to do with the execution order.
+There is an additional "thread" going through the nodes of the tree
+which shows the order of execution of the nodes.  In our simplified
+example above it looks like:
+
+     $b ---> $c ---> + ---> $a ---> assign-to
+
+But with the actual compile tree for C<$a = $b + $c> it is different:
+some nodes I<optimized away>.  As a corollary, though the actual tree
+contains more nodes than our simplified example, the execution order
+is the same as in our example.
+
+=head2 Examining the tree
+
+If you have your perl compiled for debugging (usually done with C<-D
+optimize=-g> on C<Configure> command line), you may examine the
+compiled tree by specifying C<-Dx> on the Perl command line.  The
+output takes several lines per node, and for C<$b+$c> it looks like
+this:
+
+    5           TYPE = add  ===> 6
+                TARG = 1
+                FLAGS = (SCALAR,KIDS)
+                {
+                    TYPE = null  ===> (4)
+                      (was rv2sv)
+                    FLAGS = (SCALAR,KIDS)
+                    {
+    3                   TYPE = gvsv  ===> 4
+                        FLAGS = (SCALAR)
+                        GV = main::b
+                    }
+                }
+                {
+                    TYPE = null  ===> (5)
+                      (was rv2sv)
+                    FLAGS = (SCALAR,KIDS)
+                    {
+    4                   TYPE = gvsv  ===> 5
+                        FLAGS = (SCALAR)
+                        GV = main::c
+                    }
+                }
+
+This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
+not optimized away (one per number in the left column).  The immediate
+children of the given node correspond to C<{}> pairs on the same level
+of indentation, thus this listing corresponds to the tree:
+
+                   add
+                 /     \
+               null    null
+                |       |
+               gvsv    gvsv
+
+The execution order is indicated by C<===E<gt>> marks, thus it is C<3
+4 5 6> (node C<6> is not included into above listing), i.e.,
+C<gvsv gvsv add whatever>.
+
+=head2 Compile pass 1: check routines
+
+The tree is created by the I<pseudo-compiler> while yacc code feeds it
+the constructions it recognizes. Since yacc works bottom-up, so does
+the first pass of perl compilation.
+
+What makes this pass interesting for perl developers is that some
+optimization may be performed on this pass.  This is optimization by
+so-called I<check routines>.  The correspondence between node names
+and corresponding check routines is described in F<opcode.pl> (do not
+forget to run C<make regen_headers> if you modify this file).
+
+A check routine is called when the node is fully constructed except
+for the execution-order thread.  Since at this time there are no
+back-links to the currently constructed node, one can do most any
+operation to the top-level node, including freeing it and/or creating
+new nodes above/below it.
+
+The check routine returns the node which should be inserted into the
+tree (if the top-level node was not modified, check routine returns
+its argument).
+
+By convention, check routines have names C<ck_*>. They are usually
+called from C<new*OP> subroutines (or C<convert>) (which in turn are
+called from F<perly.y>).
+
+=head2 Compile pass 1a: constant folding
+
+Immediately after the check routine is called the returned node is
+checked for being compile-time executable.  If it is (the value is
+judged to be constant) it is immediately executed, and a I<constant>
+node with the "return value" of the corresponding subtree is
+substituted instead.  The subtree is deleted.
+
+If constant folding was not performed, the execution-order thread is
+created.
+
+=head2 Compile pass 2: context propagation
+
+When a context for a part of compile tree is known, it is propagated
+down through the tree.  At this time the context can have 5 values
+(instead of 2 for runtime context): void, boolean, scalar, list, and
+lvalue.  In contrast with the pass 1 this pass is processed from top
+to bottom: a node's context determines the context for its children.
+
+Additional context-dependent optimizations are performed at this time.
+Since at this moment the compile tree contains back-references (via
+"thread" pointers), nodes cannot be free()d now.  To allow
+optimized-away nodes at this stage, such nodes are null()ified instead
+of free()ing (i.e. their type is changed to OP_NULL).
+
+=head2 Compile pass 3: peephole optimization
+
+After the compile tree for a subroutine (or for an C<eval> or a file)
+is created, an additional pass over the code is performed. This pass
+is neither top-down or bottom-up, but in the execution order (with
+additional complications for conditionals).  These optimizations are
+done in the subroutine peep().  Optimizations performed at this stage
+are subject to the same restrictions as in the pass 2.
+
+=head1 API LISTING
+
+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.
+
+Note that all Perl API global variables must be referenced with the C<PL_>
+prefix.  Some macros are provided for compatibility with the older,
+unadorned names, but this support will be removed in a future release.
+
+It is strongly recommended that all Perl API functions that don't begin
+with C<perl> be referenced with an explicit C<Perl_> prefix.
+
+The sort order of the listing is case insensitive, with any
+occurrences of '_' ignored for the the purpose of sorting.
+
+=over 8
+
+=item av_clear
+
+Clears an array, making it empty.  Does not free the memory used by the
+array itself.
+
+	void	av_clear (AV* ar)
+
+=item av_extend
+
+Pre-extend an array.  The C<key> is the index to which the array should be
+extended.
+
+	void	av_extend (AV* ar, I32 key)
+
+=item av_fetch
+
+Returns the SV at the specified index in the array.  The C<key> is the
+index.  If C<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 C<SV*>.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied arrays.
+
+	SV**	av_fetch (AV* ar, I32 key, I32 lval)
+
+=item AvFILL
+
+Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
+
+=item av_len
+
+Returns the highest index in the array.  Returns -1 if the array is empty.
+
+	I32	av_len (AV* ar)
+
+=item av_make
+
+Creates 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.  The new AV
+will have a reference count of 1.
+
+	AV*	av_make (I32 size, SV** svp)
+
+=item av_pop
+
+Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array is
+empty.
+
+	SV*	av_pop (AV* ar)
+
+=item av_push
+
+Pushes an SV onto the end of the array.  The array will grow automatically
+to accommodate the addition.
+
+	void	av_push (AV* ar, SV* val)
+
+=item av_shift
+
+Shifts an SV off the beginning of the array.
+
+	SV*	av_shift (AV* ar)
+
+=item av_store
+
+Stores an SV in an array.  The array index is specified as C<key>.  The
+return value will be NULL if the operation failed or if the value did not
+need to be actually stored within the array (as in the case of tied arrays).
+Otherwise it can be dereferenced to get the original C<SV*>.  Note that the
+caller is responsible for suitably incrementing the reference count of C<val>
+before the call, and decrementing it if the function returned NULL.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied arrays.
+
+	SV**	av_store (AV* ar, I32 key, SV* val)
+
+=item av_undef
+
+Undefines the array.  Frees the memory used by the array itself.
+
+	void	av_undef (AV* ar)
+
+=item av_unshift
+
+Unshift the given number of C<undef> values onto the beginning of the
+array.  The array will grow automatically to accommodate the addition.
+You must then use C<av_store> to assign values to these new elements.
+
+	void	av_unshift (AV* ar, I32 num)
+
+=item CLASS
+
+Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
+constructor.  This is always a C<char*>.  See C<THIS> and
+L<perlxs/"Using XS With C++">.
+
+=item Copy
+
+The XSUB-writer's interface to the C C<memcpy> function.  The C<s> is the
+source, C<d> is the destination, C<n> is the number of items, and C<t> is
+the type.  May fail on overlapping copies.  See also C<Move>.
+
+	void	Copy( s, d, n, t )
+
+=item croak
+
+This is the XSUB-writer's interface to Perl's C<die> function.  Use this
+function the same way you use the C C<printf> function.  See C<warn>.
+
+=item CvSTASH
+
+Returns the stash of the CV.
+
+	HV*	CvSTASH( SV* sv )
+
+=item PL_DBsingle
+
+When Perl is run in debugging mode, with the B<-d> switch, this SV is a
+boolean which indicates whether subs are being single-stepped.
+Single-stepping is automatically turned on after every step.  This is the C
+variable which corresponds to Perl's $DB::single variable.  See C<PL_DBsub>.
+
+=item PL_DBsub
+
+When Perl is run in debugging mode, with the B<-d> switch, this GV contains
+the SV which holds the name of the sub being debugged.  This is the C
+variable which corresponds to Perl's $DB::sub variable.  See C<PL_DBsingle>.
+The sub name can be found by
+
+	SvPV( GvSV( PL_DBsub ), PL_na )
+
+=item PL_DBtrace
+
+Trace variable used when Perl is run in debugging mode, with the B<-d>
+switch.  This is the C variable which corresponds to Perl's $DB::trace
+variable.  See C<PL_DBsingle>.
+
+=item dMARK
+
+Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
+C<dORIGMARK>.
+
+=item dORIGMARK
+
+Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
+
+=item PL_dowarn
+
+The C variable which corresponds to Perl's $^W warning variable.
+
+=item dSP
+
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro.  See C<SP>.
+
+=item dXSARGS
+
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This is
+usually handled automatically by C<xsubpp>.  Declares the C<items> variable
+to indicate the number of items on the stack.
+
+=item dXSI32
+
+Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
+handled automatically by C<xsubpp>.
+
+=item do_binmode
+
+Switches filehandle to binmode.  C<iotype> is what C<IoTYPE(io)> would
+contain.
+
+	do_binmode(fp, iotype, TRUE);
+
+=item ENTER
+
+Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
+
+	ENTER;
+
+=item EXTEND
+
+Used to extend the argument stack for an XSUB's return values.
+
+	EXTEND( sp, int x )
+
+=item fbm_compile
+
+Analyses the string in order to make fast searches on it using fbm_instr() --
+the Boyer-Moore algorithm.
+
+	void	fbm_compile(SV* sv, U32 flags)
+
+=item fbm_instr
+
+Returns the location of the SV in the string delimited by C<str> and
+C<strend>.  It returns C<Nullch> if the string can't be found.  The
+C<sv> does not have to be fbm_compiled, but the search will not be as
+fast then.
+
+	char*	fbm_instr(char *str, char *strend, SV *sv, U32 flags)
+
+=item FREETMPS
+
+Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
+L<perlcall>.
+
+	FREETMPS;
+
+=item G_ARRAY
+
+Used to indicate array context.  See C<GIMME_V>, C<GIMME> and L<perlcall>.
+
+=item G_DISCARD
+
+Indicates that arguments returned from a callback should be discarded.  See
+L<perlcall>.
+
+=item G_EVAL
+
+Used to force a Perl C<eval> wrapper around a callback.  See L<perlcall>.
+
+=item GIMME
+
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+
+=item GIMME_V
+
+The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns
+C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array
+context, respectively.
+
+=item G_NOARGS
+
+Indicates that no arguments are being sent to a callback.  See L<perlcall>.
+
+=item G_SCALAR
+
+Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and L<perlcall>.
+
+=item gv_fetchmeth
+
+Returns the glob with the given C<name> and a defined subroutine or
+C<NULL>.  The glob lives in the given C<stash>, or in the stashes
+accessible via @ISA and @UNIVERSAL.
+
+The argument C<level> should be either 0 or -1.  If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given
+C<stash> which in the case of success contains an alias for the
+subroutine, and sets up caching info for this glob.  Similarly for all
+the searched stashes.
+
+This function grants C<"SUPER"> token as a postfix of the stash name.
+
+The GV returned from C<gv_fetchmeth> may be a method cache entry,
+which is not visible to Perl code.  So when calling C<perl_call_sv>,
+you should not use the GV directly; instead, you should use the
+method's CV, which can be obtained from the GV with the C<GvCV> macro.
+
+        GV*     gv_fetchmeth (HV* stash, char* name, STRLEN len, I32 level)
+
+=item gv_fetchmethod
+
+=item gv_fetchmethod_autoload
+
+Returns the glob which contains the subroutine to call to invoke the
+method on the C<stash>.  In fact in the presense of autoloading this may
+be the glob for "AUTOLOAD".  In this case the corresponding variable
+$AUTOLOAD is already setup.
+
+The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD
+lookup is performed if the given method is not present: non-zero means
+yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.  Calling
+C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> with a
+non-zero C<autoload> parameter.
+
+These functions grant C<"SUPER"> token as a prefix of the method name.
+
+Note that if you want to keep the returned glob for a long time, you
+need to check for it being "AUTOLOAD", since at the later time the call
+may load a different subroutine due to $AUTOLOAD changing its value.
+Use the glob created via a side effect to do this.
+
+These functions have the same side-effects and as C<gv_fetchmeth> with
+C<level==0>.  C<name> should be writable if contains C<':'> or C<'\''>.
+The warning against passing the GV returned by C<gv_fetchmeth> to
+C<perl_call_sv> apply equally to these functions.
+
+        GV*     gv_fetchmethod (HV* stash, char* name)
+        GV*     gv_fetchmethod_autoload (HV* stash, char* name, I32 autoload)
+
+=item G_VOID
+
+Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
+
+=item gv_stashpv
+
+Returns a pointer to the stash for a specified package.  If C<create> is set
+then the package will be created if it does not already exist.  If C<create>
+is not set and the package does not exist then NULL is returned.
+
+	HV*	gv_stashpv (char* name, I32 create)
+
+=item gv_stashsv
+
+Returns a pointer to the stash for a specified package.  See C<gv_stashpv>.
+
+	HV*	gv_stashsv (SV* sv, I32 create)
+
+=item GvSV
+
+Return the SV from the GV.
+
+=item HEf_SVKEY
+
+This flag, used in the length slot of hash entries and magic
+structures, specifies the structure contains a C<SV*> pointer where a
+C<char*> pointer is to be expected. (For information only--not to be used).
+
+=item HeHASH
+
+Returns the computed hash stored in the hash entry.
+
+	U32	HeHASH(HE* he)
+
+=item HeKEY
+
+Returns the actual pointer stored in the key slot of the hash entry.
+The pointer may be either C<char*> or C<SV*>, depending on the value of
+C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros
+are usually preferable for finding the value of a key.
+
+	char*	HeKEY(HE* he)
+
+=item HeKLEN
+
+If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
+holds an C<SV*> key.  Otherwise, holds the actual length of the key.
+Can be assigned to. The C<HePV()> macro is usually preferable for finding
+key lengths.
+
+	int	HeKLEN(HE* he)
+
+=item HePV
+
+Returns the key slot of the hash entry as a C<char*> value, doing any
+necessary dereferencing of possibly C<SV*> keys.  The length of
+the string is placed in C<len> (this is a macro, so do I<not> use
+C<&len>).  If you do not care about what the length of the key is,
+you may use the global variable C<PL_na>.  Remember though, that hash
+keys in perl are free to contain embedded nulls, so using C<strlen()>
+or similar is not a good way to find the length of hash keys.
+This is very similar to the C<SvPV()> macro described elsewhere in
+this document.
+
+	char*	HePV(HE* he, STRLEN len)
+
+=item HeSVKEY
+
+Returns the key as an C<SV*>, or C<Nullsv> if the hash entry
+does not contain an C<SV*> key.
+
+	HeSVKEY(HE* he)
+
+=item HeSVKEY_force
+
+Returns the key as an C<SV*>.  Will create and return a temporary
+mortal C<SV*> if the hash entry contains only a C<char*> key.
+
+	HeSVKEY_force(HE* he)
+
+=item HeSVKEY_set
+
+Sets the key to a given C<SV*>, taking care to set the appropriate flags
+to indicate the presence of an C<SV*> key, and returns the same C<SV*>.
+
+	HeSVKEY_set(HE* he, SV* sv)
+
+=item HeVAL
+
+Returns the value slot (type C<SV*>) stored in the hash entry.
+
+	HeVAL(HE* he)
+
+=item hv_clear
+
+Clears a hash, making it empty.
+
+	void	hv_clear (HV* tb)
+
+=item hv_delayfree_ent
+
+Releases a hash entry, such as while iterating though the hash, but
+delays actual freeing of key and value until the end of the current
+statement (or thereabouts) with C<sv_2mortal>.  See C<hv_iternext>
+and C<hv_free_ent>.
+
+	void    hv_delayfree_ent (HV* hv, HE* entry)
+
+=item hv_delete
+
+Deletes a key/value pair in the hash.  The value SV is removed from the hash
+and returned to the caller.  The C<klen> is the length of the key.  The
+C<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)
+
+=item hv_delete_ent
+
+Deletes a key/value pair in the hash.  The value SV is removed from the hash
+and returned to the caller.  The C<flags> value will normally be zero; if set
+to G_DISCARD then NULL will be returned.  C<hash> can be a valid precomputed
+hash value, or 0 to ask for it to be computed.
+
+	SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash)
+
+=item hv_exists
+
+Returns a boolean indicating whether the specified hash key exists.  The
+C<klen> is the length of the key.
+
+	bool	hv_exists (HV* tb, char* key, U32 klen)
+
+=item hv_exists_ent
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid precomputed hash value, or 0 to ask for it to be computed.
+
+	bool    hv_exists_ent (HV* tb, SV* key, U32 hash)
+
+=item hv_fetch
+
+Returns the SV which corresponds to the specified key in the hash.  The
+C<klen> is the length of the key.  If C<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 C<SV*>.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
+	SV**	hv_fetch (HV* tb, char* key, U32 klen, I32 lval)
+
+=item hv_fetch_ent
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid precomputed hash number for the given C<key>, or
+0 if you want the function to compute it.  IF C<lval> is set then the
+fetch will be part of a store.  Make sure the return value is non-null
+before accessing it.  The return value when C<tb> is a tied hash
+is a pointer to a static location, so be sure to make a copy of the
+structure if you need to store it somewhere.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
+	HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash)
+
+=item hv_free_ent
+
+Releases a hash entry, such as while iterating though the hash.  See
+C<hv_iternext> and C<hv_delayfree_ent>.
+
+	void    hv_free_ent (HV* hv, HE* entry)
+
+=item hv_iterinit
+
+Prepares a starting point to traverse a hash table.
+
+	I32	hv_iterinit (HV* tb)
+
+Returns the number of keys in the hash (i.e. the same as C<HvKEYS(tb)>).
+The return value is currently only meaningful for hashes without tie
+magic.
+
+NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number
+of hash buckets that happen to be in use.  If you still need that
+esoteric value, you can get it through the macro C<HvFILL(tb)>.
+
+=item hv_iterkey
+
+Returns the key from the current position of the hash iterator.  See
+C<hv_iterinit>.
+
+	char*	hv_iterkey (HE* entry, I32* retlen)
+
+=item hv_iterkeysv
+
+Returns the key as an C<SV*> from the current position of the hash
+iterator.  The return value will always be a mortal copy of the
+key.  Also see C<hv_iterinit>.
+
+	SV*     hv_iterkeysv  (HE* entry)
+
+=item hv_iternext
+
+Returns entries from a hash iterator.  See C<hv_iterinit>.
+
+	HE*	hv_iternext (HV* tb)
+
+=item hv_iternextsv
+
+Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
+operation.
+
+	SV*	hv_iternextsv (HV* hv, char** key, I32* retlen)
+
+=item hv_iterval
+
+Returns the value from the current position of the hash iterator.  See
+C<hv_iterkey>.
+
+	SV*	hv_iterval (HV* tb, HE* entry)
+
+=item hv_magic
+
+Adds magic to a hash.  See C<sv_magic>.
+
+	void	hv_magic (HV* hv, GV* gv, int how)
+
+=item HvNAME
+
+Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
+
+	char*	HvNAME (HV* stash)
+
+=item hv_store
+
+Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
+the length of the key.  The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it.  The return value will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes).  Otherwise it can
+be dereferenced to get the original C<SV*>.  Note that the caller is
+responsible for suitably incrementing the reference count of C<val>
+before the call, and decrementing it if the function returned NULL.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
+	SV**	hv_store (HV* tb, char* key, U32 klen, SV* val, U32 hash)
+
+=item hv_store_ent
+
+Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it.  The return value is the new hash entry so created.  It will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes).  Otherwise the
+contents of the return value can be accessed using the C<He???> macros
+described here.  Note that the caller is responsible for suitably
+incrementing the reference count of C<val> before the call, and decrementing
+it if the function returned NULL.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
+	HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash)
+
+=item hv_undef
+
+Undefines the hash.
+
+	void	hv_undef (HV* tb)
+
+=item isALNUM
+
+Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
+character or digit.
+
+	int	isALNUM (char c)
+
+=item isALPHA
+
+Returns a boolean indicating whether the C C<char> is an ascii alphabetic
+character.
+
+	int	isALPHA (char c)
+
+=item isDIGIT
+
+Returns a boolean indicating whether the C C<char> is an ascii digit.
+
+	int	isDIGIT (char c)
+
+=item isLOWER
+
+Returns a boolean indicating whether the C C<char> is a lowercase character.
+
+	int	isLOWER (char c)
+
+=item isSPACE
+
+Returns a boolean indicating whether the C C<char> is whitespace.
+
+	int	isSPACE (char c)
+
+=item isUPPER
+
+Returns a boolean indicating whether the C C<char> is an uppercase character.
+
+	int	isUPPER (char c)
+
+=item items
+
+Variable which is setup by C<xsubpp> to indicate the number of items on the
+stack.  See L<perlxs/"Variable-length Parameter Lists">.
+
+=item ix
+
+Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
+was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
+
+=item LEAVE
+
+Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
+
+	LEAVE;
+
+=item looks_like_number
+
+Test if an the content of an SV looks like a number (or is a number).
+
+	int	looks_like_number(SV*)
+
+
+=item MARK
+
+Stack marker variable for the XSUB.  See C<dMARK>.
+
+=item mg_clear
+
+Clear something magical that the SV represents.  See C<sv_magic>.
+
+	int	mg_clear (SV* sv)
+
+=item mg_copy
+
+Copies the magic from one SV to another.  See C<sv_magic>.
+
+	int	mg_copy (SV *, SV *, char *, STRLEN)
+
+=item mg_find
+
+Finds the magic pointer for type matching the SV.  See C<sv_magic>.
+
+	MAGIC*	mg_find (SV* sv, int type)
+
+=item mg_free
+
+Free any magic storage used by the SV.  See C<sv_magic>.
+
+	int	mg_free (SV* sv)
+
+=item mg_get
+
+Do magic after a value is retrieved from the SV.  See C<sv_magic>.
+
+	int	mg_get (SV* sv)
+
+=item mg_len
+
+Report on the SV's length.  See C<sv_magic>.
+
+	U32	mg_len (SV* sv)
+
+=item mg_magical
+
+Turns on the magical status of an SV.  See C<sv_magic>.
+
+	void	mg_magical (SV* sv)
+
+=item mg_set
+
+Do magic after a value is assigned to the SV.  See C<sv_magic>.
+
+	int	mg_set (SV* sv)
+
+=item Move
+
+The XSUB-writer's interface to the C C<memmove> function.  The C<s> is the
+source, C<d> is the destination, C<n> is the number of items, and C<t> is
+the type.  Can do overlapping moves.  See also C<Copy>.
+
+	void	Move( s, d, n, t )
+
+=item PL_na
+
+A variable which may be used with C<SvPV> to tell Perl to calculate the
+string length.
+
+=item New
+
+The XSUB-writer's interface to the C C<malloc> function.
+
+	void*	New( x, void *ptr, int size, type )
+
+=item newAV
+
+Creates a new AV.  The reference count is set to 1.
+
+	AV*	newAV (void)
+
+=item Newc
+
+The XSUB-writer's interface to the C C<malloc> function, with cast.
+
+	void*	Newc( x, void *ptr, int size, type, cast )
+
+=item newCONSTSUB
+
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }>
+which is eligible for inlining at compile-time.
+
+	void	newCONSTSUB(HV* stash, char* name, SV* sv)
+
+=item newHV
+
+Creates a new HV.  The reference count is set to 1.
+
+	HV*	newHV (void)
+
+=item newRV_inc
+
+Creates an RV wrapper for an SV.  The reference count for the original SV is
+incremented.
+
+	SV*	newRV_inc (SV* ref)
+
+For historical reasons, "newRV" is a synonym for "newRV_inc".
+
+=item newRV_noinc
+
+Creates an RV wrapper for an SV.  The reference count for the original
+SV is B<not> incremented.
+
+	SV*     newRV_noinc (SV* ref)
+
+=item NEWSV
+
+Creates a new SV.  A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have.  An extra byte
+for a tailing NUL is also reserved.  (SvPOK is not set for the SV even
+if string space is allocated.)  The reference count for the new SV is
+set to 1.  C<id> is an integer id between 0 and 1299 (used to identify
+leaks).
+
+	SV*	NEWSV (int id, STRLEN len)
+
+=item newSViv
+
+Creates a new SV and copies an integer into it.  The reference count for the
+SV is set to 1.
+
+	SV*	newSViv (IV i)
+
+=item newSVnv
+
+Creates a new SV and copies a double into it.  The reference count for the
+SV is set to 1.
+
+	SV*	newSVnv (NV i)
+
+=item newSVpv
+
+Creates a new SV and copies a string into it.  The reference count for the
+SV is set to 1.  If C<len> is zero then Perl will compute the length.
+
+	SV*	newSVpv (char* s, STRLEN len)
+
+=item newSVpvf
+
+Creates a new SV an initialize it with the string formatted like
+C<sprintf>.
+
+	SV*     newSVpvf(const char* pat, ...);
+
+=item newSVpvn
+
+Creates a new SV and copies a string into it.  The reference count for the
+SV is set to 1.  If C<len> is zero then Perl will create a zero length 
+string.
+
+	SV*	newSVpvn (char* s, STRLEN len)
+
+=item newSVrv
+
+Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
+it will be upgraded to one.  If C<classname> is non-null then the new SV will
+be blessed in the specified package.  The new SV is returned and its
+reference count is 1.
+
+	SV*	newSVrv (SV* rv, char* classname)
+
+=item newSVsv
+
+Creates a new SV which is an exact duplicate of the original SV.
+
+	SV*	newSVsv (SV* old)
+
+=item newXS
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs.
+
+=item newXSproto
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
+the subs.
+
+=item Newz
+
+The XSUB-writer's interface to the C C<malloc> function.  The allocated
+memory is zeroed with C<memzero>.
+
+	void*	Newz( x, void *ptr, int size, type )
+
+=item Nullav
+
+Null AV pointer.
+
+=item Nullch
+
+Null character pointer.
+
+=item Nullcv
+
+Null CV pointer.
+
+=item Nullhv
+
+Null HV pointer.
+
+=item Nullsv
+
+Null SV pointer.
+
+=item ORIGMARK
+
+The original stack mark for the XSUB.  See C<dORIGMARK>.
+
+=item perl_alloc
+
+Allocates a new Perl interpreter.  See L<perlembed>.
+
+=item perl_call_argv
+
+Performs a callback to the specified Perl sub.  See L<perlcall>.
+
+	I32	perl_call_argv (char* subname, I32 flags, char** argv)
+
+=item perl_call_method
+
+Performs a callback to the specified Perl method.  The blessed object must
+be on the stack.  See L<perlcall>.
+
+	I32	perl_call_method (char* methname, I32 flags)
+
+=item perl_call_pv
+
+Performs a callback to the specified Perl sub.  See L<perlcall>.
+
+	I32	perl_call_pv (char* subname, I32 flags)
+
+=item perl_call_sv
+
+Performs a callback to the Perl sub whose name is in the SV.  See
+L<perlcall>.
+
+	I32	perl_call_sv (SV* sv, I32 flags)
+
+=item perl_construct
+
+Initializes a new Perl interpreter.  See L<perlembed>.
+
+=item perl_destruct
+
+Shuts down a Perl interpreter.  See L<perlembed>.
+
+=item perl_eval_sv
+
+Tells Perl to C<eval> the string in the SV.
+
+	I32	perl_eval_sv (SV* sv, I32 flags)
+
+=item perl_eval_pv
+
+Tells Perl to C<eval> the given string and return an SV* result.
+
+	SV*	perl_eval_pv (char* p, I32 croak_on_error)
+
+=item perl_free
+
+Releases a Perl interpreter.  See L<perlembed>.
+
+=item perl_get_av
+
+Returns the AV of the specified Perl array.  If C<create> is set and the
+Perl variable does not exist then it will be created.  If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+	AV*	perl_get_av (char* name, I32 create)
+
+=item perl_get_cv
+
+Returns the CV of the specified Perl sub.  If C<create> is set and the Perl
+variable does not exist then it will be created.  If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+	CV*	perl_get_cv (char* name, I32 create)
+
+=item perl_get_hv
+
+Returns the HV of the specified Perl hash.  If C<create> is set and the Perl
+variable does not exist then it will be created.  If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+	HV*	perl_get_hv (char* name, I32 create)
+
+=item perl_get_sv
+
+Returns the SV of the specified Perl scalar.  If C<create> is set and the
+Perl variable does not exist then it will be created.  If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+	SV*	perl_get_sv (char* name, I32 create)
+
+=item perl_parse
+
+Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
+
+=item perl_require_pv
+
+Tells Perl to C<require> a module.
+
+	void	perl_require_pv (char* pv)
+
+=item perl_run
+
+Tells a Perl interpreter to run.  See L<perlembed>.
+
+=item POPi
+
+Pops an integer off the stack.
+
+	int	POPi()
+
+=item POPl
+
+Pops a long off the stack.
+
+	long	POPl()
+
+=item POPp
+
+Pops a string off the stack.
+
+	char*	POPp()
+
+=item POPn
+
+Pops a double off the stack.
+
+	double	POPn()
+
+=item POPs
+
+Pops an SV off the stack.
+
+	SV*	POPs()
+
+=item PUSHMARK
+
+Opening bracket for arguments on a callback.  See C<PUTBACK> and L<perlcall>.
+
+	PUSHMARK(p)
+
+=item PUSHi
+
+Push an integer onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  See C<XPUSHi>.
+
+	void	PUSHi(int d)
+
+=item PUSHn
+
+Push a double onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  See C<XPUSHn>.
+
+	void	PUSHn(double d)
+
+=item PUSHp
+
+Push a string onto the stack.  The stack must have room for this element.
+The C<len> indicates the length of the string.  Handles 'set' magic.  See
+C<XPUSHp>.
+
+	void	PUSHp(char *c, int len )
+
+=item PUSHs
+
+Push an SV onto the stack.  The stack must have room for this element.  Does
+not handle 'set' magic.  See C<XPUSHs>.
+
+	void	PUSHs(sv)
+
+=item PUSHu
+
+Push an unsigned integer onto the stack.  The stack must have room for
+this element.  See C<XPUSHu>.
+
+	void	PUSHu(unsigned int d)
+
+
+=item PUTBACK
+
+Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
+
+	PUTBACK;
+
+=item Renew
+
+The XSUB-writer's interface to the C C<realloc> function.
+
+	void*	Renew( void *ptr, int size, type )
+
+=item Renewc
+
+The XSUB-writer's interface to the C C<realloc> function, with cast.
+
+	void*	Renewc( void *ptr, int size, type, cast )
+
+=item RETVAL
+
+Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
+This is always the proper type for the XSUB.
+See L<perlxs/"The RETVAL Variable">.
+
+=item safefree
+
+The XSUB-writer's interface to the C C<free> function.
+
+=item safemalloc
+
+The XSUB-writer's interface to the C C<malloc> function.
+
+=item saferealloc
+
+The XSUB-writer's interface to the C C<realloc> function.
+
+=item savepv
+
+Copy a string to a safe spot.  This does not use an SV.
+
+	char*	savepv (char* sv)
+
+=item savepvn
+
+Copy a string to a safe spot.  The C<len> indicates number of bytes to
+copy.  This does not use an SV.
+
+	char*	savepvn (char* sv, I32 len)
+
+=item SAVETMPS
+
+Opening bracket for temporaries on a callback.  See C<FREETMPS> and
+L<perlcall>.
+
+	SAVETMPS;
+
+=item SP
+
+Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
+C<SPAGAIN>.
+
+=item SPAGAIN
+
+Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
+
+	SPAGAIN;
+
+=item ST
+
+Used to access elements on the XSUB's stack.
+
+	SV*	ST(int x)
+
+=item strEQ
+
+Test two strings to see if they are equal.  Returns true or false.
+
+	int	strEQ( char *s1, char *s2 )
+
+=item strGE
+
+Test two strings to see if the first, C<s1>, is greater than or equal to the
+second, C<s2>.  Returns true or false.
+
+	int	strGE( char *s1, char *s2 )
+
+=item strGT
+
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>.  Returns true or false.
+
+	int	strGT( char *s1, char *s2 )
+
+=item strLE
+
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>.  Returns true or false.
+
+	int	strLE( char *s1, char *s2 )
+
+=item strLT
+
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>.  Returns true or false.
+
+	int	strLT( char *s1, char *s2 )
+
+=item strNE
+
+Test two strings to see if they are different.  Returns true or false.
+
+	int	strNE( char *s1, char *s2 )
+
+=item strnEQ
+
+Test two strings to see if they are equal.  The C<len> parameter indicates
+the number of bytes to compare.  Returns true or false.
+
+	int	strnEQ( char *s1, char *s2 )
+
+=item strnNE
+
+Test two strings to see if they are different.  The C<len> parameter
+indicates the number of bytes to compare.  Returns true or false.
+
+	int	strnNE( char *s1, char *s2, int len )
+
+=item sv_2mortal
+
+Marks an SV as mortal.  The SV will be destroyed when the current context
+ends.
+
+	SV*	sv_2mortal (SV* sv)
+
+=item sv_bless
+
+Blesses an SV into a specified package.  The SV must be an RV.  The package
+must be designated by its stash (see C<gv_stashpv()>).  The reference count
+of the SV is unaffected.
+
+	SV*	sv_bless (SV* sv, HV* stash)
+
+=item sv_catpv
+
+Concatenates the string onto the end of the string which is in the SV.
+Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
+
+	void	sv_catpv (SV* sv, char* ptr)
+
+=item sv_catpv_mg
+
+Like C<sv_catpv>, but also handles 'set' magic.
+
+	void	sv_catpvn (SV* sv, char* ptr)
+
+=item sv_catpvn
+
+Concatenates the string onto the end of the string which is in the SV.  The
+C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
+'set' magic.  See C<sv_catpvn_mg>.
+
+	void	sv_catpvn (SV* sv, char* ptr, STRLEN len)
+
+=item sv_catpvn_mg
+
+Like C<sv_catpvn>, but also handles 'set' magic.
+
+	void	sv_catpvn_mg (SV* sv, char* ptr, STRLEN len)
+
+=item sv_catpvf
+
+Processes its arguments like C<sprintf> and appends the formatted output
+to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
+typically be called after calling this function to handle 'set' magic.
+
+	void	sv_catpvf (SV* sv, const char* pat, ...)
+
+=item sv_catpvf_mg
+
+Like C<sv_catpvf>, but also handles 'set' magic.
+
+	void	sv_catpvf_mg (SV* sv, const char* pat, ...)
+
+=item sv_catsv
+
+Concatenates the string from SV C<ssv> onto the end of the string in SV
+C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
+
+	void	sv_catsv (SV* dsv, SV* ssv)
+
+=item sv_catsv_mg
+
+Like C<sv_catsv>, but also handles 'set' magic.
+
+	void	sv_catsv_mg (SV* dsv, SV* ssv)
+
+=item sv_chop
+
+Efficient removal of characters from the beginning of the string
+buffer.  SvPOK(sv) must be true and the C<ptr> must be a pointer to
+somewhere inside the string buffer.  The C<ptr> becomes the first
+character of the adjusted string.
+
+	void    sv_chop(SV* sv, char *ptr)
+
+
+=item sv_cmp
+
+Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
+string in C<sv1> is less than, equal to, or greater than the string in
+C<sv2>.
+
+	I32	sv_cmp (SV* sv1, SV* sv2)
+
+=item SvCUR
+
+Returns the length of the string which is in the SV.  See C<SvLEN>.
+
+	int	SvCUR (SV* sv)
+
+=item SvCUR_set
+
+Set the length of the string which is in the SV.  See C<SvCUR>.
+
+	void	SvCUR_set (SV* sv, int val )
+
+=item sv_dec
+
+Auto-decrement of the value in the SV.
+
+	void	sv_dec (SV* sv)
+
+=item sv_derived_from
+
+Returns a boolean indicating whether the SV is a subclass of the
+specified class.
+
+	int     sv_derived_from(SV* sv, char* class)
+
+=item sv_derived_from
+
+Returns a boolean indicating whether the SV is derived from the specified
+class.  This is the function that implements C<UNIVERSAL::isa>.  It works
+for class names as well as for objects.
+
+	bool	sv_derived_from _((SV* sv, char* name));
+
+=item SvEND
+
+Returns a pointer to the last character in the string which is in the SV.
+See C<SvCUR>.  Access the character as
+
+	char*	SvEND(sv)
+
+=item sv_eq
+
+Returns a boolean indicating whether the strings in the two SVs are
+identical.
+
+	I32	sv_eq (SV* sv1, SV* sv2)
+
+=item SvGETMAGIC
+
+Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates
+its argument more than once.
+
+	void	SvGETMAGIC( SV *sv )
+
+=item SvGROW
+
+Expands the character buffer in the SV so that it has room for the
+indicated number of bytes (remember to reserve space for an extra
+trailing NUL character).  Calls C<sv_grow> to perform the expansion if
+necessary.  Returns a pointer to the character buffer.
+
+	char*	SvGROW( SV* sv, int len )
+
+=item sv_grow
+
+Expands the character buffer in the SV.  This will use C<sv_unref> and will
+upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
+Use C<SvGROW>.
+
+=item sv_inc
+
+Auto-increment of the value in the SV.
+
+	void	sv_inc (SV* sv)
+
+=item sv_insert
+
+Inserts a string at the specified offset/length within the SV.
+Similar to the Perl substr() function.
+
+	void	sv_insert(SV *sv, STRLEN offset, STRLEN len,
+			  char *str, STRLEN strlen)
+
+=item SvIOK
+
+Returns a boolean indicating whether the SV contains an integer.
+
+	int	SvIOK (SV* SV)
+
+=item SvIOK_off
+
+Unsets the IV status of an SV.
+
+	void	SvIOK_off (SV* sv)
+
+=item SvIOK_on
+
+Tells an SV that it is an integer.
+
+	void	SvIOK_on (SV* sv)
+
+=item SvIOK_only
+
+Tells an SV that it is an integer and disables all other OK bits.
+
+	void	SvIOK_only (SV* sv)
+
+=item SvIOKp
+
+Returns a boolean indicating whether the SV contains an integer.  Checks the
+B<private> setting.  Use C<SvIOK>.
+
+	int	SvIOKp (SV* SV)
+
+=item sv_isa
+
+Returns a boolean indicating whether the SV is blessed into the specified
+class.  This does not check for subtypes; use C<sv_derived_from> to verify
+an inheritance relationship.
+
+	int	sv_isa (SV* sv, char* name)
+
+=item 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)
+
+=item SvIV
+
+Returns the integer which is in the SV.
+
+	int SvIV (SV* sv)
+
+=item SvIVX
+
+Returns the integer which is stored in the SV.
+
+	int	SvIVX (SV* sv)
+
+=item SvLEN
+
+Returns the size of the string buffer in the SV.  See C<SvCUR>.
+
+	int	SvLEN (SV* sv)
+
+=item sv_len
+
+Returns the length of the string in the SV.  Use C<SvCUR>.
+
+	STRLEN	sv_len (SV* sv)
+
+=item sv_magic
+
+Adds magic to an SV.
+
+	void	sv_magic (SV* sv, SV* obj, int how, char* name, I32 namlen)
+
+=item 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)
+
+=item sv_newmortal
+
+Creates a new SV which is mortal.  The reference count of the SV is set to 1.
+
+	SV*	sv_newmortal (void)
+
+=item SvNIOK
+
+Returns a boolean indicating whether the SV contains a number, integer or
+double.
+
+	int	SvNIOK (SV* SV)
+
+=item SvNIOK_off
+
+Unsets the NV/IV status of an SV.
+
+	void	SvNIOK_off (SV* sv)
+
+=item SvNIOKp
+
+Returns a boolean indicating whether the SV contains a number, integer or
+double.  Checks the B<private> setting.  Use C<SvNIOK>.
+
+	int	SvNIOKp (SV* SV)
+
+=item PL_sv_no
+
+This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as C<&PL_sv_no>.
+
+=item SvNOK
+
+Returns a boolean indicating whether the SV contains a double.
+
+	int	SvNOK (SV* SV)
+
+=item SvNOK_off
+
+Unsets the NV status of an SV.
+
+	void	SvNOK_off (SV* sv)
+
+=item SvNOK_on
+
+Tells an SV that it is a double.
+
+	void	SvNOK_on (SV* sv)
+
+=item SvNOK_only
+
+Tells an SV that it is a double and disables all other OK bits.
+
+	void	SvNOK_only (SV* sv)
+
+=item SvNOKp
+
+Returns a boolean indicating whether the SV contains a double.  Checks the
+B<private> setting.  Use C<SvNOK>.
+
+	int	SvNOKp (SV* SV)
+
+=item SvNV
+
+Returns the double which is stored in the SV.
+
+	double	SvNV (SV* sv)
+
+=item SvNVX
+
+Returns the double which is stored in the SV.
+
+	double	SvNVX (SV* sv)
+
+=item SvOK
+
+Returns a boolean indicating whether the value is an SV.
+
+	int	SvOK (SV* sv)
+
+=item SvOOK
+
+Returns a boolean indicating whether the SvIVX is a valid offset value
+for the SvPVX.  This hack is used internally to speed up removal of
+characters from the beginning of a SvPV.  When SvOOK is true, then the
+start of the allocated string buffer is really (SvPVX - SvIVX).
+
+	int     SvOOK(SV* sv)
+
+=item SvPOK
+
+Returns a boolean indicating whether the SV contains a character string.
+
+	int	SvPOK (SV* SV)
+
+=item SvPOK_off
+
+Unsets the PV status of an SV.
+
+	void	SvPOK_off (SV* sv)
+
+=item SvPOK_on
+
+Tells an SV that it is a string.
+
+	void	SvPOK_on (SV* sv)
+
+=item SvPOK_only
+
+Tells an SV that it is a string and disables all other OK bits.
+
+	void	SvPOK_only (SV* sv)
+
+=item SvPOKp
+
+Returns a boolean indicating whether the SV contains a character string.
+Checks the B<private> setting.  Use C<SvPOK>.
+
+	int	SvPOKp (SV* SV)
+
+=item 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 C<len> is C<PL_na> then Perl will
+handle the length on its own.  Handles 'get' magic.
+
+	char*	SvPV (SV* sv, int len )
+
+=item SvPV_force
+
+Like <SvPV> but will force the SV into becoming a string (SvPOK).  You
+want force if you are going to update the SvPVX directly.
+
+	char*	SvPV_force(SV* sv, int len)
+
+
+=item SvPVX
+
+Returns a pointer to the string in the SV.  The SV must contain a string.
+
+	char*	SvPVX (SV* sv)
+
+=item SvREFCNT
+
+Returns the value of the object's reference count.
+
+	int	SvREFCNT (SV* sv)
+
+=item SvREFCNT_dec
+
+Decrements the reference count of the given SV.
+
+	void	SvREFCNT_dec (SV* sv)
+
+=item SvREFCNT_inc
+
+Increments the reference count of the given SV.
+
+	void	SvREFCNT_inc (SV* sv)
+
+=item SvROK
+
+Tests if the SV is an RV.
+
+	int	SvROK (SV* sv)
+
+=item SvROK_off
+
+Unsets the RV status of an SV.
+
+	void	SvROK_off (SV* sv)
+
+=item SvROK_on
+
+Tells an SV that it is an RV.
+
+	void	SvROK_on (SV* sv)
+
+=item SvRV
+
+Dereferences an RV to return the SV.
+
+	SV*	SvRV (SV* sv)
+
+=item SvSETMAGIC
+
+Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates
+its argument more than once.
+
+	void	SvSETMAGIC( SV *sv )
+
+=item sv_setiv
+
+Copies an integer into the given SV.  Does not handle 'set' magic.
+See C<sv_setiv_mg>.
+
+	void	sv_setiv (SV* sv, IV num)
+
+=item sv_setiv_mg
+
+Like C<sv_setiv>, but also handles 'set' magic.
+
+	void	sv_setiv_mg (SV* sv, IV num)
+
+=item sv_setnv
+
+Copies a double into the given SV.  Does not handle 'set' magic.
+See C<sv_setnv_mg>.
+
+	void	sv_setnv (SV* sv, double num)
+
+=item sv_setnv_mg
+
+Like C<sv_setnv>, but also handles 'set' magic.
+
+	void	sv_setnv_mg (SV* sv, double num)
+
+=item sv_setpv
+
+Copies a string into an SV.  The string must be null-terminated.
+Does not handle 'set' magic.  See C<sv_setpv_mg>.
+
+	void	sv_setpv (SV* sv, char* ptr)
+
+=item sv_setpv_mg
+
+Like C<sv_setpv>, but also handles 'set' magic.
+
+	void	sv_setpv_mg (SV* sv, char* ptr)
+
+=item sv_setpviv
+
+Copies an integer into the given SV, also updating its string value.
+Does not handle 'set' magic.  See C<sv_setpviv_mg>.
+
+	void	sv_setpviv (SV* sv, IV num)
+
+=item sv_setpviv_mg
+
+Like C<sv_setpviv>, but also handles 'set' magic.
+
+	void	sv_setpviv_mg (SV* sv, IV num)
+
+=item sv_setpvn
+
+Copies a string into an SV.  The C<len> parameter indicates the number of
+bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
+
+	void	sv_setpvn (SV* sv, char* ptr, STRLEN len)
+
+=item sv_setpvn_mg
+
+Like C<sv_setpvn>, but also handles 'set' magic.
+
+	void	sv_setpvn_mg (SV* sv, char* ptr, STRLEN len)
+
+=item sv_setpvf
+
+Processes its arguments like C<sprintf> and sets an SV to the formatted
+output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
+
+	void	sv_setpvf (SV* sv, const char* pat, ...)
+
+=item sv_setpvf_mg
+
+Like C<sv_setpvf>, but also handles 'set' magic.
+
+	void	sv_setpvf_mg (SV* sv, const char* pat, ...)
+
+=item sv_setref_iv
+
+Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  The C<classname> argument indicates the package for the
+blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
+will be returned and will have a reference count of 1.
+
+	SV*	sv_setref_iv (SV *rv, char *classname, IV iv)
+
+=item sv_setref_nv
+
+Copies a double into a new SV, optionally blessing the SV.  The C<rv>
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  The C<classname> argument indicates the package for the
+blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
+will be returned and will have a reference count of 1.
+
+	SV*	sv_setref_nv (SV *rv, char *classname, double nv)
+
+=item sv_setref_pv
+
+Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
+argument will be upgraded to an RV.  That RV will be modified to point to
+the new SV.  If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
+into the SV.  The C<classname> argument indicates the package for the
+blessing.  Set C<classname> to C<Nullch> to avoid the blessing.  The new SV
+will be returned and will have a reference count 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 C<sv_setref_pvn> copies the string while this copies the pointer.
+
+=item sv_setref_pvn
+
+Copies a string into a new SV, optionally blessing the SV.  The length of the
+string must be specified with C<n>.  The C<rv> argument will be upgraded to
+an RV.  That RV will be modified to point to the new SV.  The C<classname>
+argument indicates the package for the blessing.  Set C<classname> to
+C<Nullch> to avoid the blessing.  The new SV will be returned and will have
+a reference count of 1.
+
+	SV*	sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n)
+
+Note that C<sv_setref_pv> copies the pointer while this copies the string.
+
+=item SvSetSV
+
+Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
+more than once.
+
+	void	SvSetSV (SV* dsv, SV* ssv)
+
+=item SvSetSV_nosteal
+
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as ssv.
+May evaluate arguments more than once.
+
+	void	SvSetSV_nosteal (SV* dsv, SV* ssv)
+
+=item sv_setsv
+
+Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
+The source SV may be destroyed if it is mortal.  Does not handle 'set' magic.
+See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and C<sv_setsv_mg>.
+
+	void	sv_setsv (SV* dsv, SV* ssv)
+
+=item sv_setsv_mg
+
+Like C<sv_setsv>, but also handles 'set' magic.
+
+	void	sv_setsv_mg (SV* dsv, SV* ssv)
+
+=item sv_setuv
+
+Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
+See C<sv_setuv_mg>.
+
+	void	sv_setuv (SV* sv, UV num)
+
+=item sv_setuv_mg
+
+Like C<sv_setuv>, but also handles 'set' magic.
+
+	void	sv_setuv_mg (SV* sv, UV num)
+
+=item SvSTASH
+
+Returns the stash of the SV.
+
+	HV*	SvSTASH (SV* sv)
+
+=item SvTAINT
+
+Taints an SV if tainting is enabled
+
+	void	SvTAINT (SV* sv)
+
+=item SvTAINTED
+
+Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.
+
+	int	SvTAINTED (SV* sv)
+
+=item SvTAINTED_off
+
+Untaints an SV. Be I<very> careful with this routine, as it short-circuits
+some of Perl's fundamental security features. XS module authors should
+not use this function unless they fully understand all the implications
+of unconditionally untainting the value. Untainting should be done in
+the standard perl fashion, via a carefully crafted regexp, rather than
+directly untainting variables.
+
+	void	SvTAINTED_off (SV* sv)
+
+=item SvTAINTED_on
+
+Marks an SV as tainted.
+
+	void	SvTAINTED_on (SV* sv)
+
+=item SVt_IV
+
+Integer type flag for scalars.  See C<svtype>.
+
+=item SVt_PV
+
+Pointer type flag for scalars.  See C<svtype>.
+
+=item SVt_PVAV
+
+Type flag for arrays.  See C<svtype>.
+
+=item SVt_PVCV
+
+Type flag for code refs.  See C<svtype>.
+
+=item SVt_PVHV
+
+Type flag for hashes.  See C<svtype>.
+
+=item SVt_PVMG
+
+Type flag for blessed scalars.  See C<svtype>.
+
+=item SVt_NV
+
+Double type flag for scalars.  See C<svtype>.
+
+=item SvTRUE
+
+Returns a boolean indicating whether Perl would evaluate the SV as true or
+false, defined or undefined.  Does not handle 'get' magic.
+
+	int	SvTRUE (SV* sv)
+
+=item SvTYPE
+
+Returns the type of the SV.  See C<svtype>.
+
+	svtype	SvTYPE (SV* sv)
+
+=item svtype
+
+An enum of flags for Perl types.  These are found in the file B<sv.h> in the
+C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
+
+=item PL_sv_undef
+
+This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
+
+=item sv_unref
+
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV.  This can almost be thought of
+as a reversal of C<newSVrv>.  See C<SvROK_off>.
+
+	void    sv_unref (SV* sv)
+
+=item SvUPGRADE
+
+Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to perform
+the upgrade if necessary.  See C<svtype>.
+
+	bool    SvUPGRADE (SV* sv, svtype mt)
+
+=item sv_upgrade
+
+Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See C<svtype>.
+
+=item sv_usepvn
+
+Tells an SV to use C<ptr> to find its string value.  Normally the string is
+stored inside the SV but sv_usepvn allows the SV to use an outside string.
+The C<ptr> should point to memory that was allocated by C<malloc>.  The
+string length, C<len>, must be supplied.  This function will realloc the
+memory pointed to by C<ptr>, so that pointer should not be freed or used by
+the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
+See C<sv_usepvn_mg>.
+
+	void	sv_usepvn (SV* sv, char* ptr, STRLEN len)
+
+=item sv_usepvn_mg
+
+Like C<sv_usepvn>, but also handles 'set' magic.
+
+	void	sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
+
+=item sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV.  Uses an array of SVs if the C style variable argument list is
+missing (NULL).  Indicates if locale information has been used for formatting.
+
+	void	sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen,
+			      va_list *args, SV **svargs, I32 svmax,
+			      bool *used_locale));
+
+=item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
+
+Works like C<vcatpvfn> but copies the text into the SV instead of
+appending it.
+
+	void	sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen,
+			      va_list *args, SV **svargs, I32 svmax,
+			      bool *used_locale));
+
+=item SvUV
+
+Returns the unsigned integer which is in the SV.
+
+	UV      SvUV(SV* sv)
+
+=item SvUVX
+
+Returns the unsigned integer which is stored in the SV.
+
+	UV      SvUVX(SV* sv)
+
+=item PL_sv_yes
+
+This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as C<&PL_sv_yes>.
+
+=item THIS
+
+Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
+This is always the proper type for the C++ object.  See C<CLASS> and
+L<perlxs/"Using XS With C++">.
+
+=item toLOWER
+
+Converts the specified character to lowercase.
+
+	int	toLOWER (char c)
+
+=item toUPPER
+
+Converts the specified character to uppercase.
+
+	int	toUPPER (char c)
+
+=item warn
+
+This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
+function the same way you use the C C<printf> function.  See C<croak()>.
+
+=item XPUSHi
+
+Push an integer onto the stack, extending the stack if necessary.  Handles
+'set' magic. See C<PUSHi>.
+
+	XPUSHi(int d)
+
+=item XPUSHn
+
+Push a double onto the stack, extending the stack if necessary.  Handles 'set'
+magic.  See C<PUSHn>.
+
+	XPUSHn(double d)
+
+=item XPUSHp
+
+Push a string onto the stack, extending the stack if necessary.  The C<len>
+indicates the length of the string.  Handles 'set' magic.  See C<PUSHp>.
+
+	XPUSHp(char *c, int len)
+
+=item XPUSHs
+
+Push an SV onto the stack, extending the stack if necessary.  Does not
+handle 'set' magic.  See C<PUSHs>.
+
+	XPUSHs(sv)
+
+=item XPUSHu
+
+Push an unsigned integer onto the stack, extending the stack if
+necessary.  See C<PUSHu>.
+
+=item XS
+
+Macro to declare an XSUB and its C parameter list.  This is handled by
+C<xsubpp>.
+
+=item XSRETURN
+
+Return from XSUB, indicating number of items on the stack.  This is usually
+handled by C<xsubpp>.
+
+	XSRETURN(int x)
+
+=item XSRETURN_EMPTY
+
+Return an empty list from an XSUB immediately.
+
+	XSRETURN_EMPTY;
+
+=item XSRETURN_IV
+
+Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
+
+	XSRETURN_IV(IV v)
+
+=item XSRETURN_NO
+
+Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
+
+	XSRETURN_NO;
+
+=item XSRETURN_NV
+
+Return an double from an XSUB immediately.  Uses C<XST_mNV>.
+
+	XSRETURN_NV(NV v)
+
+=item XSRETURN_PV
+
+Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
+
+	XSRETURN_PV(char *v)
+
+=item XSRETURN_UNDEF
+
+Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
+
+	XSRETURN_UNDEF;
+
+=item XSRETURN_YES
+
+Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
+
+	XSRETURN_YES;
+
+=item XST_mIV
+
+Place an integer into the specified position C<i> on the stack.  The value is
+stored in a new mortal SV.
+
+	XST_mIV( int i, IV v )
+
+=item XST_mNV
+
+Place a double into the specified position C<i> on the stack.  The value is
+stored in a new mortal SV.
+
+	XST_mNV( int i, NV v )
+
+=item XST_mNO
+
+Place C<&PL_sv_no> into the specified position C<i> on the stack.
+
+	XST_mNO( int i )
+
+=item XST_mPV
+
+Place a copy of a string into the specified position C<i> on the stack.  The
+value is stored in a new mortal SV.
+
+	XST_mPV( int i, char *v )
+
+=item XST_mUNDEF
+
+Place C<&PL_sv_undef> into the specified position C<i> on the stack.
+
+	XST_mUNDEF( int i )
+
+=item XST_mYES
+
+Place C<&PL_sv_yes> into the specified position C<i> on the stack.
+
+	XST_mYES( int i )
+
+=item XS_VERSION
+
+The version identifier for an XS module.  This is usually handled
+automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
+
+=item XS_VERSION_BOOTCHECK
+
+Macro to verify that a PM module's $VERSION variable matches the XS module's
+C<XS_VERSION> variable.  This is usually handled automatically by
+C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
+
+=item Zero
+
+The XSUB-writer's interface to the C C<memzero> function.  The C<d> is the
+destination, C<n> is the number of items, and C<t> is the type.
+
+	void	Zero( d, n, t )
+
+=back
+
+=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.
+
+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>.