Amiga Magazin: Amiga-CD 1996 July/AMIGA_1996_7.BIN/ausgabe_7_96/pd-programmierung/perl5_002bin.lha/man/catp/perlguts.0

Text File | 1996-03-02 | 149KB | 2,707 lines

PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


NNNNAAAAMMMMEEEE
       perlguts - Perl's Internal Functions

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
       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.

DDDDaaaattttaaaattttyyyyppppeeeessss
       Perl has three typedefs that handle Perl's three main data
       types:

           SSSSVVVV  SSSSccccaaaallllaaaarrrr VVVVaaaalllluuuueeee
           AAAAVVVV  AAAArrrrrrrraaaayyyy VVVVaaaalllluuuueeee
           HHHHVVVV  HHHHaaaasssshhhh VVVVaaaalllluuuueeee

       Each typedef has specific routines that manipulate the
       various data types.

       WWWWhhhhaaaatttt iiiissss aaaannnn """"IIIIVVVV""""????

       Perl uses a special typedef IV which is large enough to
       hold either an integer or a pointer.

       Perl also uses two special typedefs, I32 and I16, which
       will always be at least 32-bits and 16-bits long,
       respectively.

       WWWWoooorrrrkkkkiiiinnnngggg wwwwiiiitttthhhh SSSSVVVV''''ssss

       An SV can be created and loaded with one command.  There
       are four types of values that can be loaded: an integer
       value (IV), a double (NV), a string, (PV), and another
       scalar (SV).

       The four routines are:

           SSSSVVVV****  nnnneeeewwwwSSSSVVVViiiivvvv((((IIIIVVVV))));;;;
           SSSSVVVV****  nnnneeeewwwwSSSSVVVVnnnnvvvv((((ddddoooouuuubbbblllleeee))));;;;
           SSSSVVVV****  nnnneeeewwwwSSSSVVVVppppvvvv((((cccchhhhaaaarrrr****,,,, iiiinnnntttt))));;;;
           SSSSVVVV****  nnnneeeewwwwSSSSVVVVssssvvvv((((SSSSVVVV****))));;;;

       To change the value of an *already-existing* SV, there are
       five routines:

           vvvvooooiiiidddd  ssssvvvv____sssseeeettttiiiivvvv((((SSSSVVVV****,,,, IIIIVVVV))));;;;
           vvvvooooiiiidddd  ssssvvvv____sssseeeettttnnnnvvvv((((SSSSVVVV****,,,, ddddoooouuuubbbblllleeee))));;;;
           vvvvooooiiiidddd  ssssvvvv____sssseeeettttppppvvvvnnnn((((SSSSVVVV****,,,, cccchhhhaaaarrrr****,,,, iiiinnnntttt))))
           vvvvooooiiiidddd  ssssvvvv____sssseeeettttppppvvvv((((SSSSVVVV****,,,, cccchhhhaaaarrrr****))));;;;
           vvvvooooiiiidddd  ssssvvvv____sssseeeettttssssvvvv((((SSSSVVVV****,,,, SSSSVVVV****))));;;;

       Notice that you can choose to specify the length of the
       string to be assigned by using ssssvvvv____sssseeeettttppppvvvvnnnn or nnnneeeewwwwSSSSVVVVppppvvvv, or



23/Jan/96                perl 5.002 with                        1





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       you may allow Perl to calculate the length by using
       ssssvvvv____sssseeeettttppppvvvv or by specifying 0 as the second argument to
       nnnneeeewwwwSSSSVVVVppppvvvv.  Be warned, though, that Perl will determine the
       string's length by using ssssttttrrrrlllleeeennnn, which depends on the
       string terminating with a NUL character.

       To access the actual value that an SV points to, you can
       use the macros:

           SSSSvvvvIIIIVVVV((((SSSSVVVV****))))
           SSSSvvvvNNNNVVVV((((SSSSVVVV****))))
           SSSSvvvvPPPPVVVV((((SSSSVVVV****,,,, SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))

       which will automatically coerce the actual scalar type
       into an IV, double, or string.

       In the SSSSvvvvPPPPVVVV macro, the length of the string returned is
       placed into the variable lllleeeennnn (this is a macro, so you do
       _n_o_t use &&&&lllleeeennnn).  If you do not care what the length of the
       data is, use the global variable nnnnaaaa.  Remember, however,
       that Perl allows arbitrary strings of data that may both
       contain NUL's and not be terminated by a NUL.

       If you simply want to know if the scalar value is TRUE,
       you can use:

           SSSSvvvvTTTTRRRRUUUUEEEE((((SSSSVVVV****))))

       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

           SSSSvvvvGGGGRRRROOOOWWWW((((SSSSVVVV****,,,, SSSSTTTTRRRRLLLLEEEENNNN nnnneeeewwwwlllleeeennnn))))

       which will determine if more memory needs to be allocated.
       If so, it will call the function ssssvvvv____ggggrrrroooowwww.  Note that
       SSSSvvvvGGGGRRRROOOOWWWW can only increase, not decrease, the allocated
       memory of an SV.

       If you have an SV and want to know what kind of data Perl
       thinks is stored in it, you can use the following macros
       to check the type of SV you have.

           SSSSvvvvIIIIOOOOKKKK((((SSSSVVVV****))))
           SSSSvvvvNNNNOOOOKKKK((((SSSSVVVV****))))
           SSSSvvvvPPPPOOOOKKKK((((SSSSVVVV****))))

       You can get and set the current length of the string
       stored in an SV with the following macros:

           SSSSvvvvCCCCUUUURRRR((((SSSSVVVV****))))
           SSSSvvvvCCCCUUUURRRR____sssseeeetttt((((SSSSVVVV****,,,, IIII33332222 vvvvaaaallll))))

       You can also get a pointer to the end of the string stored



23/Jan/96                perl 5.002 with                        2





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       in the SV with the macro:

           SSSSvvvvEEEENNNNDDDD((((SSSSVVVV****))))

       But note that these last three macros are valid only if
       SSSSvvvvPPPPOOOOKKKK(((()))) is true.

       If you want to append something to the end of string
       stored in an SSSSVVVV****, you can use the following functions:

           vvvvooooiiiidddd  ssssvvvv____ccccaaaattttppppvvvv((((SSSSVVVV****,,,, cccchhhhaaaarrrr****))));;;;
           vvvvooooiiiidddd  ssssvvvv____ccccaaaattttppppvvvvnnnn((((SSSSVVVV****,,,, cccchhhhaaaarrrr****,,,, iiiinnnntttt))));;;;
           vvvvooooiiiidddd  ssssvvvv____ccccaaaattttssssvvvv((((SSSSVVVV****,,,, SSSSVVVV****))));;;;

       The first function calculates the length of the string to
       be appended by using ssssttttrrrrlllleeeennnn.  In the second, you specify
       the length of the string yourself.  The third function
       extends the string stored in the first SV with the string
       stored in the second SV.  It also forces the second SV to
       be interpreted as a string.

       If you know the name of a scalar variable, you can get a
       pointer to its SV by using the following:

           SSSSVVVV****  ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, FFFFAAAALLLLSSSSEEEE))));;;;

       This returns NULL if the variable does not exist.

       If you want to know if this variable (or any other SV) is
       actually ddddeeeeffffiiiinnnneeeedddd, you can call:

           SSSSvvvvOOOOKKKK((((SSSSVVVV****))))

       The scalar uuuunnnnddddeeeeffff value is stored in an SV instance called
       ssssvvvv____uuuunnnnddddeeeeffff.  Its address can be used whenever an SSSSVVVV**** is
       needed.

       There are also the two values ssssvvvv____yyyyeeeessss and ssssvvvv____nnnnoooo, which
       contain Boolean TRUE and FALSE values, respectively.  Like
       ssssvvvv____uuuunnnnddddeeeeffff, their addresses can be used whenever an SSSSVVVV**** is
       needed.

       Do not be fooled into thinking that ((((SSSSVVVV ****)))) 0000 is the same
       as &&&&ssssvvvv____uuuunnnnddddeeeeffff.  Take this code:

           SSSSVVVV**** ssssvvvv ==== ((((SSSSVVVV****)))) 0000;;;;
           iiiiffff ((((IIII----aaaammmm----ttttoooo----rrrreeeettttuuuurrrrnnnn----aaaa----rrrreeeeaaaallll----vvvvaaaalllluuuueeee)))) {{{{
                   ssssvvvv ==== ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((44442222))))))));;;;
           }}}}
           ssssvvvv____sssseeeettttssssvvvv((((SSSSTTTT((((0000)))),,,, ssssvvvv))));;;;

       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,



23/Jan/96                perl 5.002 with                        3





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       somewhere down the line, will cause a segmentation
       violation, or just weird results.  Change the zero to
       &&&&ssssvvvv____uuuunnnnddddeeeeffff in the first line and all will be well.

       To free an SV that you've created, call SSSSvvvvRRRREEEEFFFFCCCCNNNNTTTT____ddddeeeecccc((((SSSSVVVV****)))).
       Normally this call is not necessary.  See the section on
       MMMMOOOORRRRTTTTAAAALLLLIIIITTTTYYYY.

       WWWWhhhhaaaatttt''''ssss RRRReeeeaaaallllllllyyyy SSSSttttoooorrrreeeedddd iiiinnnn aaaannnn SSSSVVVV????

       Recall that the usual method of determining the type of
       scalar you have is to use SSSSvvvv****OOOOKKKK macros.  Since a scalar
       can be both a number and a string, usually these macros
       will always return TRUE and calling the SSSSvvvv****VVVV macros will
       do the appropriate conversion of string to integer/double
       or integer/double to string.

       If you _r_e_a_l_l_y need to know if you have an integer, double,
       or string pointer in an SV, you can use the following
       three macros instead:

           SSSSvvvvIIIIOOOOKKKKpppp((((SSSSVVVV****))))
           SSSSvvvvNNNNOOOOKKKKpppp((((SSSSVVVV****))))
           SSSSvvvvPPPPOOOOKKKKpppp((((SSSSVVVV****))))

       These will tell you if you truly have an integer, double,
       or string pointer stored in your SV.  The "p" stands for
       private.

       In general, though, it's best to just use the SSSSvvvv****VVVV macros.

       WWWWoooorrrrkkkkiiiinnnngggg wwwwiiiitttthhhh AAAAVVVV''''ssss

       There are two ways to create and load an AV.  The first
       method just creates an empty AV:

           AAAAVVVV****  nnnneeeewwwwAAAAVVVV(((())));;;;

       The second method both creates the AV and initially
       populates it with SV's:

           AAAAVVVV****  aaaavvvv____mmmmaaaakkkkeeee((((IIII33332222 nnnnuuuummmm,,,, SSSSVVVV ********ppppttttrrrr))));;;;

       The second argument points to an array containing nnnnuuuummmm
       SSSSVVVV****'s.  Once the AV has been created, the SV's can be
       destroyed, if so desired.

       Once the AV has been created, the following operations are
       possible on AV's:

           vvvvooooiiiidddd  aaaavvvv____ppppuuuusssshhhh((((AAAAVVVV****,,,, SSSSVVVV****))));;;;
           SSSSVVVV****   aaaavvvv____ppppoooopppp((((AAAAVVVV****))));;;;
           SSSSVVVV****   aaaavvvv____sssshhhhiiiifffftttt((((AAAAVVVV****))));;;;
           vvvvooooiiiidddd  aaaavvvv____uuuunnnnsssshhhhiiiifffftttt((((AAAAVVVV****,,,, IIII33332222 nnnnuuuummmm))));;;;



23/Jan/96                perl 5.002 with                        4





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       These should be familiar operations, with the exception of
       aaaavvvv____uuuunnnnsssshhhhiiiifffftttt.  This routine adds nnnnuuuummmm elements at the front
       of the array with the uuuunnnnddddeeeeffff value.  You must then use
       aaaavvvv____ssssttttoooorrrreeee (described below) to assign values to these new
       elements.

       Here are some other functions:

           IIII33332222   aaaavvvv____lllleeeennnn((((AAAAVVVV****))));;;; ////**** RRRReeeettttuuuurrrrnnnnssss hhhhiiiigggghhhheeeesssstttt iiiinnnnddddeeeexxxx vvvvaaaalllluuuueeee iiiinnnn aaaarrrrrrrraaaayyyy ****////

           SSSSVVVV********  aaaavvvv____ffffeeeettttcccchhhh((((AAAAVVVV****,,,, IIII33332222 kkkkeeeeyyyy,,,, IIII33332222 llllvvvvaaaallll))));;;;
                   ////**** FFFFeeeettttcccchhhheeeessss vvvvaaaalllluuuueeee aaaatttt kkkkeeeeyyyy ooooffffffffsssseeeetttt,,,, bbbbuuuutttt iiiitttt ssssttttoooorrrreeeessss aaaannnn uuuunnnnddddeeeeffff vvvvaaaalllluuuueeee
                      aaaatttt tttthhhheeee ooooffffffffsssseeeetttt iiiiffff llllvvvvaaaallll iiiissss nnnnoooonnnn----zzzzeeeerrrroooo ****////
           SSSSVVVV********  aaaavvvv____ssssttttoooorrrreeee((((AAAAVVVV****,,,, IIII33332222 kkkkeeeeyyyy,,,, SSSSVVVV**** vvvvaaaallll))));;;;
                   ////**** SSSSttttoooorrrreeeessss vvvvaaaallll aaaatttt ooooffffffffsssseeeetttt kkkkeeeeyyyy ****////

       Take note that aaaavvvv____ffffeeeettttcccchhhh and aaaavvvv____ssssttttoooorrrreeee return SSSSVVVV********'s, not
       SSSSVVVV****'s.

           vvvvooooiiiidddd  aaaavvvv____cccclllleeeeaaaarrrr((((AAAAVVVV****))));;;;
                   ////**** CCCClllleeeeaaaarrrr oooouuuutttt aaaallllllll eeeelllleeeemmmmeeeennnnttttssss,,,, bbbbuuuutttt lllleeeeaaaavvvveeee tttthhhheeee aaaarrrrrrrraaaayyyy ****////
           vvvvooooiiiidddd  aaaavvvv____uuuunnnnddddeeeeffff((((AAAAVVVV****))));;;;
                   ////**** UUUUnnnnddddeeeeffffiiiinnnneeeessss tttthhhheeee aaaarrrrrrrraaaayyyy,,,, rrrreeeemmmmoooovvvviiiinnnngggg aaaallllllll eeeelllleeeemmmmeeeennnnttttssss ****////
           vvvvooooiiiidddd  aaaavvvv____eeeexxxxtttteeeennnndddd((((AAAAVVVV****,,,, IIII33332222 kkkkeeeeyyyy))));;;;
                   ////**** EEEExxxxtttteeeennnndddd tttthhhheeee aaaarrrrrrrraaaayyyy ttttoooo aaaa ttttoooottttaaaallll ooooffff kkkkeeeeyyyy eeeelllleeeemmmmeeeennnnttttssss ****////

       If you know the name of an array variable, you can get a
       pointer to its AV by using the following:

           AAAAVVVV****  ppppeeeerrrrllll____ggggeeeetttt____aaaavvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, FFFFAAAALLLLSSSSEEEE))));;;;

       This returns NULL if the variable does not exist.

       WWWWoooorrrrkkkkiiiinnnngggg wwwwiiiitttthhhh HHHHVVVV''''ssss

       To create an HV, you use the following routine:

           HHHHVVVV****  nnnneeeewwwwHHHHVVVV(((())));;;;

       Once the HV has been created, the following operations are
       possible on HV's:

           SSSSVVVV********  hhhhvvvv____ssssttttoooorrrreeee((((HHHHVVVV****,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, SSSSVVVV**** vvvvaaaallll,,,, UUUU33332222 hhhhaaaasssshhhh))));;;;
           SSSSVVVV********  hhhhvvvv____ffffeeeettttcccchhhh((((HHHHVVVV****,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, IIII33332222 llllvvvvaaaallll))));;;;

       The kkkklllleeeennnn parameter is the length of the key being passed
       in.  The vvvvaaaallll argument contains the SV pointer to the
       scalar being stored, and hhhhaaaasssshhhh is the pre-computed hash
       value (zero if you want hhhhvvvv____ssssttttoooorrrreeee to calculate it for you).
       The llllvvvvaaaallll parameter indicates whether this fetch is
       actually a part of a store operation.

       Remember that hhhhvvvv____ssssttttoooorrrreeee and hhhhvvvv____ffffeeeettttcccchhhh return SSSSVVVV********'s and not
       just SSSSVVVV****.  In order to access the scalar value, you must



23/Jan/96                perl 5.002 with                        5





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       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.

           bbbboooooooollll  hhhhvvvv____eeeexxxxiiiissssttttssss((((HHHHVVVV****,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn))));;;;
           SSSSVVVV****   hhhhvvvv____ddddeeeelllleeeetttteeee((((HHHHVVVV****,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, IIII33332222 ffffllllaaaaggggssss))));;;;

       And more miscellaneous functions:

           vvvvooooiiiidddd   hhhhvvvv____cccclllleeeeaaaarrrr((((HHHHVVVV****))));;;;
                   ////**** CCCClllleeeeaaaarrrrssss aaaallllllll eeeennnnttttrrrriiiieeeessss iiiinnnn hhhhaaaasssshhhh ttttaaaabbbblllleeee ****////
           vvvvooooiiiidddd   hhhhvvvv____uuuunnnnddddeeeeffff((((HHHHVVVV****))));;;;
                   ////**** UUUUnnnnddddeeeeffffiiiinnnneeeessss tttthhhheeee hhhhaaaasssshhhh ttttaaaabbbblllleeee ****////

       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 SSSSVVVV****.  However,
       once you have an HHHHEEEE****, to get the actual key and value, use
       the routines specified below.

           IIII33332222    hhhhvvvv____iiiitttteeeerrrriiiinnnniiiitttt((((HHHHVVVV****))));;;;
                   ////**** PPPPrrrreeeeppppaaaarrrreeeessss ssssttttaaaarrrrttttiiiinnnngggg ppppooooiiiinnnntttt ttttoooo ttttrrrraaaavvvveeeerrrrsssseeee hhhhaaaasssshhhh ttttaaaabbbblllleeee ****////
           HHHHEEEE****    hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxtttt((((HHHHVVVV****))));;;;
                   ////**** GGGGeeeetttt tttthhhheeee nnnneeeexxxxtttt eeeennnnttttrrrryyyy,,,, aaaannnndddd rrrreeeettttuuuurrrrnnnn aaaa ppppooooiiiinnnntttteeeerrrr ttttoooo aaaa
                      ssssttttrrrruuuuccccttttuuuurrrreeee tttthhhhaaaatttt hhhhaaaassss bbbbooootttthhhh tttthhhheeee kkkkeeeeyyyy aaaannnndddd vvvvaaaalllluuuueeee ****////
           cccchhhhaaaarrrr****  hhhhvvvv____iiiitttteeeerrrrkkkkeeeeyyyy((((HHHHEEEE**** eeeennnnttttrrrryyyy,,,, IIII33332222**** rrrreeeettttlllleeeennnn))));;;;
                   ////**** GGGGeeeetttt tttthhhheeee kkkkeeeeyyyy ffffrrrroooommmm aaaannnn HHHHEEEE ssssttttrrrruuuuccccttttuuuurrrreeee aaaannnndddd aaaallllssssoooo rrrreeeettttuuuurrrrnnnn
                      tttthhhheeee lllleeeennnnggggtttthhhh ooooffff tttthhhheeee kkkkeeeeyyyy ssssttttrrrriiiinnnngggg ****////
           SSSSVVVV****    hhhhvvvv____iiiitttteeeerrrrvvvvaaaallll((((HHHHVVVV****,,,, HHHHEEEE**** eeeennnnttttrrrryyyy))));;;;
                   ////**** RRRReeeettttuuuurrrrnnnn aaaa SSSSVVVV ppppooooiiiinnnntttteeeerrrr ttttoooo tttthhhheeee vvvvaaaalllluuuueeee ooooffff tttthhhheeee HHHHEEEE
                      ssssttttrrrruuuuccccttttuuuurrrreeee ****////
           SSSSVVVV****    hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxttttssssvvvv((((HHHHVVVV****,,,, cccchhhhaaaarrrr******** kkkkeeeeyyyy,,,, IIII33332222**** rrrreeeettttlllleeeennnn))));;;;
                   ////**** TTTThhhhiiiissss ccccoooonnnnvvvveeeennnniiiieeeennnncccceeee rrrroooouuuuttttiiiinnnneeee ccccoooommmmbbbbiiiinnnneeeessss hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxtttt,,,,
                      hhhhvvvv____iiiitttteeeerrrrkkkkeeeeyyyy,,,, aaaannnndddd hhhhvvvv____iiiitttteeeerrrrvvvvaaaallll....  TTTThhhheeee kkkkeeeeyyyy aaaannnndddd rrrreeeettttlllleeeennnn
                      aaaarrrrgggguuuummmmeeeennnnttttssss aaaarrrreeee rrrreeeettttuuuurrrrnnnn vvvvaaaalllluuuueeeessss ffffoooorrrr tttthhhheeee kkkkeeeeyyyy aaaannnndddd iiiittttssss
                      lllleeeennnnggggtttthhhh....  TTTThhhheeee vvvvaaaalllluuuueeee iiiissss rrrreeeettttuuuurrrrnnnneeeedddd iiiinnnn tttthhhheeee SSSSVVVV**** aaaarrrrgggguuuummmmeeeennnntttt ****////

       If you know the name of a hash variable, you can get a
       pointer to its HV by using the following:

           HHHHVVVV****  ppppeeeerrrrllll____ggggeeeetttt____hhhhvvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, FFFFAAAALLLLSSSSEEEE))));;;;

       This returns NULL if the variable does not exist.

       The hash algorithm, for those who are interested, is:








23/Jan/96                perl 5.002 with                        6





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


           iiii ==== kkkklllleeeennnn;;;;
           hhhhaaaasssshhhh ==== 0000;;;;
           ssss ==== kkkkeeeeyyyy;;;;
           wwwwhhhhiiiilllleeee ((((iiii--------))))
               hhhhaaaasssshhhh ==== hhhhaaaasssshhhh **** 33333333 ++++ ****ssss++++++++;;;;


       RRRReeeeffffeeeerrrreeeennnncccceeeessss

       References are a special type of scalar that point to
       other data types (including references).

       To create a reference, use the following command:

           SSSSVVVV**** nnnneeeewwwwRRRRVVVV((((((((SSSSVVVV****)))) tttthhhhiiiinnnngggg))));;;;

       The tttthhhhiiiinnnngggg argument can be any of an SSSSVVVV****, AAAAVVVV****, or HHHHVVVV****.
       Once you have a reference, you can use the following macro
       to dereference the reference:

           SSSSvvvvRRRRVVVV((((SSSSVVVV****))))

       then call the appropriate routines, casting the returned
       SSSSVVVV**** to either an AAAAVVVV**** or HHHHVVVV****, if required.

       To determine if an SV is a reference, you can use the
       following macro:

           SSSSvvvvRRRROOOOKKKK((((SSSSVVVV****))))

       To actually discover what the reference refers to, you
       must use the following macro and then check the value
       returned.

           SSSSvvvvTTTTYYYYPPPPEEEE((((SSSSvvvvRRRRVVVV((((SSSSVVVV****))))))))

       The most useful types that will be returned are:

           SSSSVVVVtttt____IIIIVVVV    SSSSccccaaaallllaaaarrrr
           SSSSVVVVtttt____NNNNVVVV    SSSSccccaaaallllaaaarrrr
           SSSSVVVVtttt____PPPPVVVV    SSSSccccaaaallllaaaarrrr
           SSSSVVVVtttt____PPPPVVVVAAAAVVVV  AAAArrrrrrrraaaayyyy
           SSSSVVVVtttt____PPPPVVVVHHHHVVVV  HHHHaaaasssshhhh
           SSSSVVVVtttt____PPPPVVVVCCCCVVVV  CCCCooooddddeeee
           SSSSVVVVtttt____PPPPVVVVMMMMGGGG  BBBBlllleeeesssssssseeeedddd SSSSccccaaaallllaaaarrrr


       BBBBlllleeeesssssssseeeedddd RRRReeeeffffeeeerrrreeeennnncccceeeessss aaaannnndddd CCCCllllaaaassssssss OOOObbbbjjjjeeeeccccttttssss

       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.



23/Jan/96                perl 5.002 with                        7





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       A reference can be blessed into a package with the
       following function:

           SSSSVVVV**** ssssvvvv____bbbblllleeeessssssss((((SSSSVVVV**** ssssvvvv,,,, HHHHVVVV**** ssssttttaaaasssshhhh))));;;;

       The ssssvvvv argument must be a reference.  The ssssttttaaaasssshhhh argument
       specifies which class the reference will belong to.  See
       the section on the _S_t_a_s_h_e_s manpage for information on
       converting class names into stashes.

       /* Still under construction */

       Upgrades rv to reference if not already one.  Creates new
       SV for rv to point to.  If classname is non-null, the SV
       is blessed into the specified class.  SV is returned.

               SSSSVVVV**** nnnneeeewwwwSSSSVVVVrrrrvvvv((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee))));;;;

       Copies integer or double into an SV whose reference is rv.
       SV is blessed if classname is non-null.

               SSSSVVVV**** ssssvvvv____sssseeeettttrrrreeeeffff____iiiivvvv((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee,,,, IIIIVVVV iiiivvvv))));;;;
               SSSSVVVV**** ssssvvvv____sssseeeettttrrrreeeeffff____nnnnvvvv((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee,,,, NNNNVVVV iiiivvvv))));;;;

       Copies pointer (_n_o_t _a _s_t_r_i_n_g_!) into an SV whose reference
       is rv.  SV is blessed if classname is non-null.

               SSSSVVVV**** ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvv((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee,,,, PPPPVVVV iiiivvvv))));;;;

       Copies string into an SV whose reference is rv.  Set
       length to 0 to let Perl calculate the string length.  SV
       is blessed if classname is non-null.

               SSSSVVVV**** ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvvnnnn((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee,,,, PPPPVVVV iiiivvvv,,,, iiiinnnntttt lllleeeennnnggggtttthhhh))));;;;

               iiiinnnntttt ssssvvvv____iiiissssaaaa((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** nnnnaaaammmmeeee))));;;;
               iiiinnnntttt ssssvvvv____iiiissssoooobbbbjjjjeeeecccctttt((((SSSSVVVV**** ssssvvvv))));;;;


CCCCrrrreeeeaaaattttiiiinnnngggg NNNNeeeewwww VVVVaaaarrrriiiiaaaabbbblllleeeessss
       To create a new Perl variable, which can be accessed from
       your Perl script, use the following routines, depending on
       the variable type.

           SSSSVVVV****  ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, TTTTRRRRUUUUEEEE))));;;;
           AAAAVVVV****  ppppeeeerrrrllll____ggggeeeetttt____aaaavvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, TTTTRRRRUUUUEEEE))));;;;
           HHHHVVVV****  ppppeeeerrrrllll____ggggeeeetttt____hhhhvvvv((((""""vvvvaaaarrrrnnnnaaaammmmeeee"""",,,, TTTTRRRRUUUUEEEE))));;;;

       Notice the use of TRUE as the second parameter.  The new
       variable can now be set, using the routines appropriate to
       the data type.

       There are additional bits that may be OR'ed with the TRUE
       argument to enable certain extra features.  Those bits



23/Jan/96                perl 5.002 with                        8





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       are:

           0000xxxx00002222  MMMMaaaarrrrkkkkssss tttthhhheeee vvvvaaaarrrriiiiaaaabbbblllleeee aaaassss mmmmuuuullllttttiiiippppllllyyyy ddddeeeeffffiiiinnnneeeedddd,,,, tttthhhhuuuussss pppprrrreeeevvvveeeennnnttttiiiinnnngggg tttthhhheeee
                 """"IIIInnnnddddeeeennnnttttiiiiffffiiiieeeerrrr <<<<vvvvaaaarrrrnnnnaaaammmmeeee>>>> uuuusssseeeedddd oooonnnnllllyyyy oooonnnncccceeee:::: ppppoooossssssssiiiibbbblllleeee ttttyyyyppppoooo"""" wwwwaaaarrrrnnnniiiinnnngggg....
           0000xxxx00004444  IIIIssssssssuuuueeeessss aaaa """"HHHHaaaadddd ttttoooo ccccrrrreeeeaaaatttteeee <<<<vvvvaaaarrrrnnnnaaaammmmeeee>>>> uuuunnnneeeexxxxppppeeeecccctttteeeeddddllllyyyy"""" wwwwaaaarrrrnnnniiiinnnngggg iiiiffff
                 tttthhhheeee vvvvaaaarrrriiiiaaaabbbblllleeee ddddiiiiddddnnnn''''tttt aaaaccccttttuuuuaaaallllllllyyyy eeeexxxxiiiisssstttt....  TTTThhhhiiiissss iiiissss uuuusssseeeeffffuuuullll iiiiffff
                 yyyyoooouuuu eeeexxxxppppeeeecccctttteeeedddd tttthhhheeee vvvvaaaarrrriiiiaaaabbbblllleeee ttttoooo aaaallllrrrreeeeaaaaddddyyyy eeeexxxxiiiisssstttt aaaannnndddd wwwwaaaannnntttt ttttoooo pppprrrrooooppppaaaaggggaaaatttteeee
                 tttthhhhiiiissss wwwwaaaarrrrnnnniiiinnnngggg bbbbaaaacccckkkk ttttoooo tttthhhheeee uuuusssseeeerrrr....

       If the vvvvaaaarrrrnnnnaaaammmmeeee argument does not contain a package
       specifier, it is created in the current package.

XXXXSSSSUUUUBBBB''''ssss aaaannnndddd tttthhhheeee AAAArrrrgggguuuummmmeeeennnntttt SSSSttttaaaacccckkkk
       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 SSSSTTTT((((nnnn))))
       macro, which returns the nnnn'th stack argument.  Argument 0
       is the first argument passed in the Perl subroutine call.
       These arguments are SSSSVVVV****, and can be used anywhere an SSSSVVVV****
       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 _t_z_n_a_m_e_(_) call, which takes no
       arguments, but returns two, the local timezone's standard
       and summer time abbreviations.

       To handle this situation, the PPCODE directive is used and
       the stack is extended using the macro:

           EEEEXXXXTTTTEEEENNNNDDDD((((sssspppp,,,, nnnnuuuummmm))));;;;

       where sssspppp is the stack pointer, and nnnnuuuummmm is the number of
       elements the stack should be extended by.

       Now that there is room on the stack, values can be pushed
       on it using the macros to push IV's, doubles, strings, and
       SV pointers respectively:

           PPPPUUUUSSSSHHHHiiii((((IIIIVVVV))))
           PPPPUUUUSSSSHHHHnnnn((((ddddoooouuuubbbblllleeee))))
           PPPPUUUUSSSSHHHHpppp((((cccchhhhaaaarrrr****,,,, IIII33332222))))
           PPPPUUUUSSSSHHHHssss((((SSSSVVVV****))))

       And now the Perl program calling ttttzzzznnnnaaaammmmeeee, the two values
       will be assigned as in:

           (((($$$$ssssttttaaaannnnddddaaaarrrrdddd____aaaabbbbbbbbrrrreeeevvvv,,,, $$$$ssssuuuummmmmmmmeeeerrrr____aaaabbbbbbbbrrrreeeevvvv)))) ==== PPPPOOOOSSSSIIIIXXXX::::::::ttttzzzznnnnaaaammmmeeee;;;;



23/Jan/96                perl 5.002 with                        9





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       An alternate (and possibly simpler) method to pushing
       values on the stack is to use the macros:

           XXXXPPPPUUUUSSSSHHHHiiii((((IIIIVVVV))))
           XXXXPPPPUUUUSSSSHHHHnnnn((((ddddoooouuuubbbblllleeee))))
           XXXXPPPPUUUUSSSSHHHHpppp((((cccchhhhaaaarrrr****,,,, IIII33332222))))
           XXXXPPPPUUUUSSSSHHHHssss((((SSSSVVVV****))))

       These macros automatically adjust the stack for you, if
       needed.

       For more information, consult the _p_e_r_l_x_s manpage.

MMMMoooorrrrttttaaaalllliiiittttyyyy
       In Perl, values are normally "immortal" -- that is, they
       are not freed unless explicitly done so (via the Perl
       uuuunnnnddddeeeeffff call or other routines in Perl itself).

       Add cruft about reference counts.       int SvREFCNT(SV*
       sv);      void SvREFCNT_inc(SV* sv);      void
       SvREFCNT_dec(SV* sv);

       In the above example with ttttzzzznnnnaaaammmmeeee, we needed to create two
       new SV's to push onto the argument stack, that being the
       two strings.  However, we don't want these new SV's to
       stick around forever because they will eventually be
       copied into the SV's that hold the two scalar variables.

       An SV (or AV or HV) that is "mortal" acts in all ways as a
       normal "immortal" SV, AV, or HV, but is only valid in the
       "current context".  When the Perl interpreter leaves the
       current context, the mortal SV, AV, or HV is automatically
       freed.  Generally the "current context" means a single
       Perl statement.

       To create a mortal variable, use the functions:

           SSSSVVVV****  ssssvvvv____nnnneeeewwwwmmmmoooorrrrttttaaaallll(((())))
           SSSSVVVV****  ssssvvvv____2222mmmmoooorrrrttttaaaallll((((SSSSVVVV****))))
           SSSSVVVV****  ssssvvvv____mmmmoooorrrrttttaaaallllccccooooppppyyyy((((SSSSVVVV****))))

       The first call creates a mortal SV, the second converts an
       existing SV to a mortal SV, the third creates a mortal
       copy of an existing SV.

       The mortal routines are not just for SV's -- AV's and HV's
       can be made mortal by passing their address (and casting
       them to SSSSVVVV****) to the ssssvvvv____2222mmmmoooorrrrttttaaaallll or ssssvvvv____mmmmoooorrrrttttaaaallllccccooooppppyyyy routines.

       >From Ilya: Beware that the _s_v___2_m_o_r_t_a_l_(_) call is
       eventually equivalent to _s_v_R_E_F_C_N_T___d_e_c_(_). A value can
       happily be mortal in two different contexts, and it will
       be _s_v_R_E_F_C_N_T___d_e_c_(_)ed twice, once on exit from these
       contexts. It can also be mortal twice in the same context.



23/Jan/96                perl 5.002 with                       10





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       This means that you should be very careful to make a value
       mortal exactly as many times as it is needed. The value
       that go to the Perl stack _s_h_o_u_l_d be mortal.

       You should be careful about creating mortal variables.  It
       is possible for strange things to happen should you make
       the same value mortal within multiple contexts.

SSSSttttaaaasssshhhheeeessss
       A stash is a hash table (associative array) that contains
       all of the different objects that are contained within a
       package.  Each key of the stash is a symbol name (shared
       by all the different types of objects that have the same
       name), and each value in the hash table is called a GV
       (for Glob Value).  This GV in turn contains references to
       the various objects of that name, including (but not
       limited to) the following:

           SSSSccccaaaallllaaaarrrr VVVVaaaalllluuuueeee
           AAAArrrrrrrraaaayyyy VVVVaaaalllluuuueeee
           HHHHaaaasssshhhh VVVVaaaalllluuuueeee
           FFFFiiiilllleeee HHHHaaaannnnddddlllleeee
           DDDDiiiirrrreeeeccccttttoooorrrryyyy HHHHaaaannnnddddlllleeee
           FFFFoooorrrrmmmmaaaatttt
           SSSSuuuubbbbrrrroooouuuuttttiiiinnnneeee

       Perl stores various stashes in a separate GV structure
       (for global variable) but represents them with an HV
       structure.  The keys in this larger GV are the various
       package names; the values are the GGGGVVVV****'s which are stashes.
       It may help to think of a stash purely as an HV, and that
       the term "GV" means the global variable hash.

       To get the stash pointer for a particular package, use the
       function:

           HHHHVVVV****  ggggvvvv____ssssttttaaaasssshhhhppppvvvv((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))
           HHHHVVVV****  ggggvvvv____ssssttttaaaasssshhhhssssvvvv((((SSSSVVVV****,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))

       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 HHHHVVVV****.  The ccccrrrreeeeaaaatttteeee
       flag will create a new package if it is set.

       The name that ggggvvvv____ssssttttaaaasssshhhh****vvvv wants is the name of the package
       whose symbol table you want.  The default package is
       called mmmmaaaaiiiinnnn.  If you have multiply nested packages, pass
       their names to ggggvvvv____ssssttttaaaasssshhhh****vvvv, separated by :::::::: as in the Perl
       language itself.

       Alternately, if you have an SV that is a blessed
       reference, you can find out the stash pointer by using:

           HHHHVVVV****  SSSSvvvvSSSSTTTTAAAASSSSHHHH((((SSSSvvvvRRRRVVVV((((SSSSVVVV****))))))));;;;



23/Jan/96                perl 5.002 with                       11





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       then use the following to get the package name itself:

           cccchhhhaaaarrrr****  HHHHvvvvNNNNAAAAMMMMEEEE((((HHHHVVVV**** ssssttttaaaasssshhhh))));;;;

       If you need to return a blessed value to your Perl script,
       you can use the following function:

           SSSSVVVV****  ssssvvvv____bbbblllleeeessssssss((((SSSSVVVV****,,,, HHHHVVVV**** ssssttttaaaasssshhhh))))

       where the first argument, an SSSSVVVV****, must be a reference, and
       the second argument is a stash.  The returned SSSSVVVV**** can now
       be used in the same way as any other SV.

       For more information on references and blessings, consult
       the _p_e_r_l_r_e_f manpage.

MMMMaaaaggggiiiicccc
       [This section still under construction.  Ignore everything
       here.  Post no bills.  Everything not permitted is
       forbidden.]

       # Version 6, 1995/1/27

       Any SV may be magical, that is, it has special features
       that a normal SV does not have.  These features are stored
       in the SV structure in a linked list of ssssttttrrrruuuucccctttt mmmmaaaaggggiiiicccc's,
       typedef'ed to MMMMAAAAGGGGIIIICCCC.

           ssssttttrrrruuuucccctttt mmmmaaaaggggiiiicccc {{{{
               MMMMAAAAGGGGIIIICCCC****      mmmmgggg____mmmmoooorrrreeeemmmmaaaaggggiiiicccc;;;;
               MMMMGGGGVVVVTTTTBBBBLLLL****     mmmmgggg____vvvviiiirrrrttttuuuuaaaallll;;;;
               UUUU11116666         mmmmgggg____pppprrrriiiivvvvaaaatttteeee;;;;
               cccchhhhaaaarrrr        mmmmgggg____ttttyyyyppppeeee;;;;
               UUUU8888          mmmmgggg____ffffllllaaaaggggssss;;;;
               SSSSVVVV****         mmmmgggg____oooobbbbjjjj;;;;
               cccchhhhaaaarrrr****       mmmmgggg____ppppttttrrrr;;;;
               IIII33332222         mmmmgggg____lllleeeennnn;;;;
           }}}};;;;

       Note this is current as of patchlevel 0, and could change
       at any time.

       AAAAssssssssiiiiggggnnnniiiinnnngggg MMMMaaaaggggiiiicccc

       Perl adds magic to an SV using the sv_magic function:

           vvvvooooiiiidddd ssssvvvv____mmmmaaaaggggiiiicccc((((SSSSVVVV**** ssssvvvv,,,, SSSSVVVV**** oooobbbbjjjj,,,, iiiinnnntttt hhhhoooowwww,,,, cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 nnnnaaaammmmlllleeeennnn))));;;;

       The ssssvvvv argument is a pointer to the SV that is to acquire
       a new magical feature.

       If ssssvvvv is not already magical, Perl uses the SSSSvvvvUUUUPPPPGGGGRRRRAAAADDDDEEEE
       macro to set the SSSSVVVVtttt____PPPPVVVVMMMMGGGG flag for the ssssvvvv.  Perl then
       continues by adding it to the beginning of the linked list



23/Jan/96                perl 5.002 with                       12





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       of magical features.  Any prior entry of the same type of
       magic is deleted.  Note that this can be overriden, and
       multiple instances of the same type of magic can be
       associated with an SV.

       The nnnnaaaammmmeeee and nnnnaaaammmmlllleeeemmmm arguments are used to associate a
       string with the magic, typically the name of a variable.
       nnnnaaaammmmlllleeeemmmm is stored in the mmmmgggg____lllleeeennnn field and if nnnnaaaammmmeeee is non-
       null and nnnnaaaammmmlllleeeemmmm >= 0 a malloc'd copy of the name is stored
       in mmmmgggg____ppppttttrrrr field.

       The sv_magic function uses hhhhoooowwww to determine which, if any,
       predefined "Magic Virtual Table" should be assigned to the
       mmmmgggg____vvvviiiirrrrttttuuuuaaaallll field.  See the "Magic Virtual Table" section
       below.  The hhhhoooowwww argument is also stored in the mmmmgggg____ttttyyyyppppeeee
       field.

       The oooobbbbjjjj argument is stored in the mmmmgggg____oooobbbbjjjj field of the
       MMMMAAAAGGGGIIIICCCC structure.  If it is not the same as the ssssvvvv
       argument, the reference count of the oooobbbbjjjj object is
       incremented.  If it is the same, or if the hhhhoooowwww argument is
       "#", or if it is a null pointer, then oooobbbbjjjj is merely
       stored, without the reference count being incremented.

       There is also a function to add magic to an HHHHVVVV:

           vvvvooooiiiidddd hhhhvvvv____mmmmaaaaggggiiiicccc((((HHHHVVVV ****hhhhvvvv,,,, GGGGVVVV ****ggggvvvv,,,, iiiinnnntttt hhhhoooowwww))));;;;

       This simply calls ssssvvvv____mmmmaaaaggggiiiicccc and coerces the ggggvvvv argument
       into an SSSSVVVV.

       To remove the magic from an SV, call the function
       sv_unmagic:

           vvvvooooiiiidddd ssssvvvv____uuuunnnnmmmmaaaaggggiiiicccc((((SSSSVVVV ****ssssvvvv,,,, iiiinnnntttt ttttyyyyppppeeee))));;;;

       The ttttyyyyppppeeee argument should be equal to the hhhhoooowwww value when
       the SSSSVVVV was initially made magical.

       MMMMaaaaggggiiiicccc VVVViiiirrrrttttuuuuaaaallll TTTTaaaabbbblllleeeessss

       The mmmmgggg____vvvviiiirrrrttttuuuuaaaallll field in the MMMMAAAAGGGGIIIICCCC structure is a pointer
       to a MMMMGGGGVVVVTTTTBBBBLLLL, 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 MMMMGGGGVVVVTTTTBBBBLLLL has five pointers to the following routine
       types:

           iiiinnnntttt  ((((****ssssvvvvtttt____ggggeeeetttt))))((((SSSSVVVV**** ssssvvvv,,,, MMMMAAAAGGGGIIIICCCC**** mmmmgggg))));;;;
           iiiinnnntttt  ((((****ssssvvvvtttt____sssseeeetttt))))((((SSSSVVVV**** ssssvvvv,,,, MMMMAAAAGGGGIIIICCCC**** mmmmgggg))));;;;
           UUUU33332222  ((((****ssssvvvvtttt____lllleeeennnn))))((((SSSSVVVV**** ssssvvvv,,,, MMMMAAAAGGGGIIIICCCC**** mmmmgggg))));;;;
           iiiinnnntttt  ((((****ssssvvvvtttt____cccclllleeeeaaaarrrr))))((((SSSSVVVV**** ssssvvvv,,,, MMMMAAAAGGGGIIIICCCC**** mmmmgggg))));;;;
           iiiinnnntttt  ((((****ssssvvvvtttt____ffffrrrreeeeeeee))))((((SSSSVVVV**** ssssvvvv,,,, MMMMAAAAGGGGIIIICCCC**** mmmmgggg))));;;;



23/Jan/96                perl 5.002 with                       13





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       This MGVTBL structure is set at compile-time in ppppeeeerrrrllll....hhhh 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.

           FFFFuuuunnnnccccttttiiiioooonnnn ppppooooiiiinnnntttteeeerrrr    AAAAccccttttiiiioooonnnn ttttaaaakkkkeeeennnn
           ----------------------------------------------------------------    ------------------------------------------------
           ssssvvvvtttt____ggggeeeetttt             DDDDoooo ssssoooommmmeeeetttthhhhiiiinnnngggg aaaafffftttteeeerrrr tttthhhheeee vvvvaaaalllluuuueeee ooooffff tttthhhheeee SSSSVVVV iiiissss rrrreeeettttrrrriiiieeeevvvveeeedddd....
           ssssvvvvtttt____sssseeeetttt             DDDDoooo ssssoooommmmeeeetttthhhhiiiinnnngggg aaaafffftttteeeerrrr tttthhhheeee SSSSVVVV iiiissss aaaassssssssiiiiggggnnnneeeedddd aaaa vvvvaaaalllluuuueeee....
           ssssvvvvtttt____lllleeeennnn             RRRReeeeppppoooorrrrtttt oooonnnn tttthhhheeee SSSSVVVV''''ssss lllleeeennnnggggtttthhhh....
           ssssvvvvtttt____cccclllleeeeaaaarrrr           CCCClllleeeeaaaarrrr ssssoooommmmeeeetttthhhhiiiinnnngggg tttthhhheeee SSSSVVVV rrrreeeepppprrrreeeesssseeeennnnttttssss....
           ssssvvvvtttt____ffffrrrreeeeeeee            FFFFrrrreeeeeeee aaaannnnyyyy eeeexxxxttttrrrraaaa ssssttttoooorrrraaaaggggeeee aaaassssssssoooocccciiiiaaaatttteeeedddd wwwwiiiitttthhhh tttthhhheeee SSSSVVVV....

       For instance, the MGVTBL structure called vvvvttttbbbbllll____ssssvvvv (which
       corresponds to an mmmmgggg____ttttyyyyppppeeee of '\0') contains:

           {{{{ mmmmaaaaggggiiiicccc____ggggeeeetttt,,,, mmmmaaaaggggiiiicccc____sssseeeetttt,,,, mmmmaaaaggggiiiicccc____lllleeeennnn,,,, 0000,,,, 0000 }}}}

       Thus, when an SV is determined to be magical and of type
       '\0', if a get operation is being performed, the routine
       mmmmaaaaggggiiiicccc____ggggeeeetttt is called.  All the various routines for the
       various magical types begin with mmmmaaaaggggiiiicccc____.

       The current kinds of Magic Virtual Tables are:

           mmmmgggg____ttttyyyyppppeeee  MMMMGGGGVVVVTTTTBBBBLLLL              TTTTyyyyppppeeee ooooffff mmmmaaaaggggiiiiccccaaaallllnnnneeeessssssss
           ----------------------------  ------------------------              ----------------------------------------------------------------------------
           \\\\0000       vvvvttttbbbbllll____ssssvvvv             RRRReeeeggggeeeexxxxpppp????????????
           AAAA        vvvvttttbbbbllll____aaaammmmaaaaggggiiiicccc         OOOOppppeeeerrrraaaattttoooorrrr OOOOvvvveeeerrrrllllooooaaaaddddiiiinnnngggg
           aaaa        vvvvttttbbbbllll____aaaammmmaaaaggggiiiicccceeeelllleeeemmmm     OOOOppppeeeerrrraaaattttoooorrrr OOOOvvvveeeerrrrllllooooaaaaddddiiiinnnngggg
           cccc        0000                   UUUUsssseeeedddd iiiinnnn OOOOppppeeeerrrraaaattttoooorrrr OOOOvvvveeeerrrrllllooooaaaaddddiiiinnnngggg
           BBBB        vvvvttttbbbbllll____bbbbmmmm             BBBBooooyyyyeeeerrrr----MMMMoooooooorrrreeee????????????
           EEEE        vvvvttttbbbbllll____eeeennnnvvvv            %%%%EEEENNNNVVVV hhhhaaaasssshhhh
           eeee        vvvvttttbbbbllll____eeeennnnvvvveeeelllleeeemmmm        %%%%EEEENNNNVVVV hhhhaaaasssshhhh eeeelllleeeemmmmeeeennnntttt
           gggg        vvvvttttbbbbllll____mmmmgggglllloooobbbb          RRRReeeeggggeeeexxxxpppp ////gggg ffffllllaaaagggg????????????
           IIII        vvvvttttbbbbllll____iiiissssaaaa            @@@@IIIISSSSAAAA aaaarrrrrrrraaaayyyy
           iiii        vvvvttttbbbbllll____iiiissssaaaaeeeelllleeeemmmm        @@@@IIIISSSSAAAA aaaarrrrrrrraaaayyyy eeeelllleeeemmmmeeeennnntttt
           LLLL        0000 ((((bbbbuuuutttt sssseeeettttssss RRRRMMMMAAAAGGGGIIIICCCCAAAALLLL))))     PPPPeeeerrrrllll MMMMoooodddduuuulllleeee////DDDDeeeebbbbuuuuggggggggeeeerrrr????????????
           llll        vvvvttttbbbbllll____ddddbbbblllliiiinnnneeee         DDDDeeeebbbbuuuuggggggggeeeerrrr????
           PPPP        vvvvttttbbbbllll____ppppaaaacccckkkk           TTTTiiiieeeedddd AAAArrrrrrrraaaayyyy oooorrrr HHHHaaaasssshhhh
           pppp        vvvvttttbbbbllll____ppppaaaacccckkkkeeeelllleeeemmmm       TTTTiiiieeeedddd AAAArrrrrrrraaaayyyy oooorrrr HHHHaaaasssshhhh eeeelllleeeemmmmeeeennnntttt
           qqqq        vvvvttttbbbbllll____ppppaaaacccckkkkeeeelllleeeemmmm       TTTTiiiieeeedddd SSSSccccaaaallllaaaarrrr oooorrrr HHHHaaaannnnddddlllleeee
           SSSS        vvvvttttbbbbllll____ssssiiiigggg            SSSSiiiiggggnnnnaaaallll HHHHaaaasssshhhh
           ssss        vvvvttttbbbbllll____ssssiiiiggggeeeelllleeeemmmm        SSSSiiiiggggnnnnaaaallll HHHHaaaasssshhhh eeeelllleeeemmmmeeeennnntttt
           tttt        vvvvttttbbbbllll____ttttaaaaiiiinnnntttt          TTTTaaaaiiiinnnntttteeeeddddnnnneeeessssssss
           UUUU        vvvvttttbbbbllll____uuuuvvvvaaaarrrr           ????????????
           vvvv        vvvvttttbbbbllll____vvvveeeecccc            VVVVeeeeccccttttoooorrrr
           xxxx        vvvvttttbbbbllll____ssssuuuubbbbssssttttrrrr         SSSSuuuubbbbssssttttrrrriiiinnnngggg????????????
           ****        vvvvttttbbbbllll____gggglllloooobbbb           GGGGVVVV????????????
           ####        vvvvttttbbbbllll____aaaarrrryyyylllleeeennnn         AAAArrrrrrrraaaayyyy LLLLeeeennnnggggtttthhhh
           ....        vvvvttttbbbbllll____ppppoooossss            $$$$.... ssssccccaaaallllaaaarrrr vvvvaaaarrrriiiiaaaabbbblllleeee
           ~~~~        RRRReeeesssseeeerrrrvvvveeeedddd ffffoooorrrr eeeexxxxtttteeeennnnssssiiiioooonnnnssss,,,, bbbbuuuutttt mmmmuuuullllttttiiiipppplllleeee eeeexxxxtttteeeennnnssssiiiioooonnnnssss mmmmaaaayyyy ccccllllaaaasssshhhh




23/Jan/96                perl 5.002 with                       14





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       When an upper-case and lower-case letter both exist in the
       table, then the upper-case letter is used to represent
       some kind of composite type (a list or a hash), and the
       lower-case letter is used to represent an element of that
       composite type.

       FFFFiiiinnnnddddiiiinnnngggg MMMMaaaaggggiiiicccc


           MMMMAAAAGGGGIIIICCCC**** mmmmgggg____ffffiiiinnnndddd((((SSSSVVVV****,,,, iiiinnnntttt ttttyyyyppppeeee))));;;; ////**** FFFFiiiinnnnddddssss tttthhhheeee mmmmaaaaggggiiiicccc ppppooooiiiinnnntttteeeerrrr ooooffff tttthhhhaaaatttt ttttyyyyppppeeee ****////

       This routine returns a pointer to the MMMMAAAAGGGGIIIICCCC structure
       stored in the SV.  If the SV does not have that magical
       feature, NNNNUUUULLLLLLLL is returned.  Also, if the SV is not of type
       SVt_PVMG, Perl may core-dump.

           iiiinnnntttt mmmmgggg____ccccooooppppyyyy((((SSSSVVVV**** ssssvvvv,,,, SSSSVVVV**** nnnnssssvvvv,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, SSSSTTTTRRRRLLLLEEEENNNN kkkklllleeeennnn))));;;;

       This routine checks to see what types of magic ssssvvvv has.  If
       the mg_type field is an upper-case letter, then the mg_obj
       is copied to nnnnssssvvvv, but the mg_type field is changed to be
       the lower-case letter.

DDDDoooouuuubbbblllleeee----TTTTyyyyppppeeeedddd SSSSVVVV''''ssss
       Scalar variables normally contain only one type of value,
       an integer, double, pointer, or reference.  Perl will
       automatically convert the actual scalar data from the
       stored type into the requested type.

       Some scalar variables contain more than one type of scalar
       data.  For example, the variable $$$$!!!! contains either the
       numeric value of eeeerrrrrrrrnnnnoooo or its string equivalent from
       either ssssttttrrrreeeerrrrrrrroooorrrr or ssssyyyyssss____eeeerrrrrrrrlllliiiisssstttt[[[[]]]].

       To force multiple data values into an SV, you must do two
       things: use the ssssvvvv____sssseeeetttt****vvvv 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:

               SSSSvvvvIIIIOOOOKKKK____oooonnnn
               SSSSvvvvNNNNOOOOKKKK____oooonnnn
               SSSSvvvvPPPPOOOOKKKK____oooonnnn
               SSSSvvvvRRRROOOOKKKK____oooonnnn

       The particular macro you must use depends on which
       ssssvvvv____sssseeeetttt****vvvv routine you called first.  This is because every
       ssssvvvv____sssseeeetttt****vvvv 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:




23/Jan/96                perl 5.002 with                       15





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


           eeeexxxxtttteeeerrrrnnnn iiiinnnntttt  ddddbbbbeeeerrrrrrrroooorrrr;;;;
           eeeexxxxtttteeeerrrrnnnn cccchhhhaaaarrrr ****ddddbbbbeeeerrrrrrrroooorrrr____lllliiiisssstttt;;;;

           SSSSVVVV**** ssssvvvv ==== ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""ddddbbbbeeeerrrrrrrroooorrrr"""",,,, TTTTRRRRUUUUEEEE))));;;;
           ssssvvvv____sssseeeettttiiiivvvv((((ssssvvvv,,,, ((((IIIIVVVV)))) ddddbbbbeeeerrrrrrrroooorrrr))));;;;
           ssssvvvv____sssseeeettttppppvvvv((((ssssvvvv,,,, ddddbbbbeeeerrrrrrrroooorrrr____lllliiiisssstttt[[[[ddddbbbbeeeerrrrrrrroooorrrr]]]]))));;;;
           SSSSvvvvIIIIOOOOKKKK____oooonnnn((((ssssvvvv))));;;;

       If the order of ssssvvvv____sssseeeettttiiiivvvv and ssssvvvv____sssseeeettttppppvvvv had been reversed,
       then the macro SSSSvvvvPPPPOOOOKKKK____oooonnnn would need to be called instead of
       SSSSvvvvIIIIOOOOKKKK____oooonnnn.

CCCCaaaalllllllliiiinnnngggg PPPPeeeerrrrllll RRRRoooouuuuttttiiiinnnneeeessss ffffrrrroooommmm wwwwiiiitttthhhhiiiinnnn CCCC PPPPrrrrooooggggrrrraaaammmmssss
       There are four routines that can be used to call a Perl
       subroutine from within a C program.  These four are:

           IIII33332222  ppppeeeerrrrllll____ccccaaaallllllll____ssssvvvv((((SSSSVVVV****,,,, IIII33332222))));;;;
           IIII33332222  ppppeeeerrrrllll____ccccaaaallllllll____ppppvvvv((((cccchhhhaaaarrrr****,,,, IIII33332222))));;;;
           IIII33332222  ppppeeeerrrrllll____ccccaaaallllllll____mmmmeeeetttthhhhoooodddd((((cccchhhhaaaarrrr****,,,, IIII33332222))));;;;
           IIII33332222  ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv((((cccchhhhaaaarrrr****,,,, IIII33332222,,,, rrrreeeeggggiiiisssstttteeeerrrr cccchhhhaaaarrrr********))));;;;

       The routine most often used is ppppeeeerrrrllll____ccccaaaallllllll____ssssvvvv.  The SSSSVVVV****
       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 ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv),
       the programmer must manipulate the Perl stack.  These
       include the following macros and functions:

           ddddSSSSPPPP
           PPPPUUUUSSSSHHHHMMMMAAAARRRRKKKK(((())))
           PPPPUUUUTTTTBBBBAAAACCCCKKKK
           SSSSPPPPAAAAGGGGAAAAIIIINNNN
           EEEENNNNTTTTEEEERRRR
           SSSSAAAAVVVVEEEETTTTMMMMPPPPSSSS
           FFFFRRRREEEEEEEETTTTMMMMPPPPSSSS
           LLLLEEEEAAAAVVVVEEEE
           XXXXPPPPUUUUSSSSHHHH****(((())))
           PPPPOOOOPPPP****(((())))

       For more information, consult the _p_e_r_l_c_a_l_l manpage.

MMMMeeeemmmmoooorrrryyyy AAAAllllllllooooccccaaaattttiiiioooonnnn
       It is strongly suggested that you use the version of
       malloc that is distributed with Perl.  It keeps pools of
       various sizes of unallocated memory in order to more
       quickly satisfy allocation requests.  However, on some



23/Jan/96                perl 5.002 with                       16





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       platforms, it may cause spurious malloc or free errors.

           NNNNeeeewwww((((xxxx,,,, ppppooooiiiinnnntttteeeerrrr,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;
           NNNNeeeewwwwcccc((((xxxx,,,, ppppooooiiiinnnntttteeeerrrr,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee,,,, ccccaaaasssstttt))));;;;
           NNNNeeeewwwwzzzz((((xxxx,,,, ppppooooiiiinnnntttteeeerrrr,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;

       These three macros are used to initially allocate memory.
       The first argument xxxx was a "magic cookie" that was used to
       keep track of who called the macro, to help when debugging
       memory problems.  However, the current code makes no use
       of this feature (Larry has switched to using a run-time
       memory checker), so this argument can be any number.

       The second argument ppppooooiiiinnnntttteeeerrrr will point to the newly
       allocated memory.  The third and fourth arguments nnnnuuuummmmbbbbeeeerrrr
       and ttttyyyyppppeeee specify how many of the specified type of data
       structure should be allocated.  The argument ttttyyyyppppeeee is
       passed to ssssiiiizzzzeeeeooooffff.  The final argument to NNNNeeeewwwwcccc, ccccaaaasssstttt,
       should be used if the ppppooooiiiinnnntttteeeerrrr argument is different from
       the ttttyyyyppppeeee argument.

       Unlike the NNNNeeeewwww and NNNNeeeewwwwcccc macros, the NNNNeeeewwwwzzzz macro calls
       mmmmeeeemmmmzzzzeeeerrrroooo to zero out all the newly allocated memory.

           RRRReeeennnneeeewwww((((ppppooooiiiinnnntttteeeerrrr,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;
           RRRReeeennnneeeewwwwcccc((((ppppooooiiiinnnntttteeeerrrr,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee,,,, ccccaaaasssstttt))));;;;
           SSSSaaaaffffeeeeffffrrrreeeeeeee((((ppppooooiiiinnnntttteeeerrrr))))

       These three macros are used to change a memory buffer size
       or to free a piece of memory no longer needed.  The
       arguments to RRRReeeennnneeeewwww and RRRReeeennnneeeewwwwcccc match those of NNNNeeeewwww and NNNNeeeewwwwcccc
       with the exception of not needing the "magic cookie"
       argument.

           MMMMoooovvvveeee((((ssssoooouuuurrrrcccceeee,,,, ddddeeeesssstttt,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;
           CCCCooooppppyyyy((((ssssoooouuuurrrrcccceeee,,,, ddddeeeesssstttt,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;
           ZZZZeeeerrrroooo((((ddddeeeesssstttt,,,, nnnnuuuummmmbbbbeeeerrrr,,,, ttttyyyyppppeeee))));;;;

       These three macros are used to move, copy, or zero out
       previously allocated memory.  The ssssoooouuuurrrrcccceeee and ddddeeeesssstttt
       arguments point to the source and destination starting
       points.  Perl will move, copy, or zero out nnnnuuuummmmbbbbeeeerrrr
       instances of the size of the ttttyyyyppppeeee data structure (using
       the ssssiiiizzzzeeeeooooffff function).

AAAAPPPPIIII LLLLIIIISSSSTTTTIIIINNNNGGGG
       This is a listing of functions, macros, flags, and
       variables that may be useful to extension writers or that
       may be found while reading other extensions.

       AvFILL  See aaaavvvv____lllleeeennnn.

       av_clear
               Clears an array, making it empty.



23/Jan/96                perl 5.002 with                       17





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       vvvvooooiiiidddd    aaaavvvv____cccclllleeeeaaaarrrr ____((((((((AAAAVVVV**** aaaarrrr))))))));;;;


       av_extend
               Pre-extend an array.  The kkkkeeeeyyyy is the index to
               which the array should be extended.

                       vvvvooooiiiidddd    aaaavvvv____eeeexxxxtttteeeennnndddd ____((((((((AAAAVVVV**** aaaarrrr,,,, IIII33332222 kkkkeeeeyyyy))))))));;;;


       av_fetch
               Returns the SV at the specified index in the
               array.  The kkkkeeeeyyyy is the index.  If llllvvvvaaaallll is set then
               the fetch will be part of a store.  Check that the
               return value is non-null before dereferencing it
               to a SSSSVVVV****.

                       SSSSVVVV********    aaaavvvv____ffffeeeettttcccchhhh ____((((((((AAAAVVVV**** aaaarrrr,,,, IIII33332222 kkkkeeeeyyyy,,,, IIII33332222 llllvvvvaaaallll))))))));;;;


       av_len  Returns the highest index in the array.  Returns
               -1 if the array is empty.

                       IIII33332222     aaaavvvv____lllleeeennnn ____((((((((AAAAVVVV**** aaaarrrr))))))));;;;


       av_make Creats a new AV and populates it with a list of
               SVs.  The SVs are copied into the array, so they
               may be freed after the call to av_make.

                       AAAAVVVV****     aaaavvvv____mmmmaaaakkkkeeee ____((((((((IIII33332222 ssssiiiizzzzeeee,,,, SSSSVVVV******** ssssvvvvpppp))))))));;;;


       av_pop  Pops an SV off the end of the array.  Returns
               &&&&ssssvvvv____uuuunnnnddddeeeeffff if the array is empty.

                       SSSSVVVV****     aaaavvvv____ppppoooopppp ____((((((((AAAAVVVV**** aaaarrrr))))))));;;;


       av_push Pushes an SV onto the end of the array.

                       vvvvooooiiiidddd    aaaavvvv____ppppuuuusssshhhh ____((((((((AAAAVVVV**** aaaarrrr,,,, SSSSVVVV**** vvvvaaaallll))))))));;;;


       av_shift
               Shifts an SV off the beginning of the array.

                       SSSSVVVV****     aaaavvvv____sssshhhhiiiifffftttt ____((((((((AAAAVVVV**** aaaarrrr))))))));;;;


       av_store
               Stores an SV in an array.  The array index is
               specified as kkkkeeeeyyyy.  The return value will be null
               if the operation failed, otherwise it can be



23/Jan/96                perl 5.002 with                       18





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               dereferenced to get the original SSSSVVVV****.

                       SSSSVVVV********    aaaavvvv____ssssttttoooorrrreeee ____((((((((AAAAVVVV**** aaaarrrr,,,, IIII33332222 kkkkeeeeyyyy,,,, SSSSVVVV**** vvvvaaaallll))))))));;;;


       av_undef
               Undefines the array.

                       vvvvooooiiiidddd    aaaavvvv____uuuunnnnddddeeeeffff ____((((((((AAAAVVVV**** aaaarrrr))))))));;;;


       av_unshift
               Unshift an SV onto the beginning of the array.

                       vvvvooooiiiidddd    aaaavvvv____uuuunnnnsssshhhhiiiifffftttt ____((((((((AAAAVVVV**** aaaarrrr,,,, IIII33332222 nnnnuuuummmm))))))));;;;


       CLASS   Variable which is setup by xxxxssssuuuubbbbpppppppp to indicate the
               class name for a C++ XS constructor.  This is
               always a cccchhhhaaaarrrr****.  See TTTTHHHHIIIISSSS and the _p_e_r_l_x_s manpage.

       Copy    The XSUB-writer's interface to the C mmmmeeeemmmmccccppppyyyy
               function.  The ssss is the source, dddd is the
               destination, nnnn is the number of items, and tttt is
               the type.

                       ((((vvvvooooiiiidddd)))) CCCCooooppppyyyy(((( ssss,,,, dddd,,,, nnnn,,,, tttt ))));;;;


       croak   This is the XSUB-writer's interface to Perl's ddddiiiieeee
               function.  Use this function the same way you use
               the C pppprrrriiiinnnnttttffff function.  See wwwwaaaarrrrnnnn.

       CvSTASH Returns the stash of the CV.

                       HHHHVVVV **** CCCCvvvvSSSSTTTTAAAASSSSHHHH(((( SSSSVVVV**** ssssvvvv ))))


       DBsingle
               When Perl is run in debugging mode, with the ----dddd
               switch, this SV is a boolean which indicates
               whether subs are being single-stepped.  Single-
               stepping is automatically turned on after every
               step.  See DDDDBBBBssssuuuubbbb.

       DBsub   When Perl is run in debugging mode, with the ----dddd
               switch, this GV contains the SV which holds the
               name of the sub being debugged.  See DDDDBBBBssssiiiinnnngggglllleeee.
               The sub name can be found by

                       SSSSvvvvPPPPVVVV(((( GGGGvvvvSSSSVVVV(((( DDDDBBBBssssuuuubbbb )))),,,, nnnnaaaa ))))






23/Jan/96                perl 5.002 with                       19





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       dMARK   Declare a stack marker for the XSUB.  See MMMMAAAARRRRKKKK and
               ddddOOOORRRRIIIIGGGGMMMMAAAARRRRKKKK.

       dORIGMARK
               Saves the original stack mark for the XSUB.  See
               OOOORRRRIIIIGGGGMMMMAAAARRRRKKKK.

       dSP     Declares a stack pointer for the XSUB.  See SSSSPPPP.

       dXSARGS Sets up stack and mark pointers for an XSUB,
               calling dSP and dMARK.  This is usually handled
               automatically by xxxxssssuuuubbbbpppppppp.  Declares the iiiitttteeeemmmmssss
               variable to indicate the number of items on the
               stack.

       ENTER   Opening bracket on a callback.  See LLLLEEEEAAAAVVVVEEEE and the
               _p_e_r_l_c_a_l_l manpage.

                       EEEENNNNTTTTEEEERRRR;;;;


       EXTEND  Used to extend the argument stack for an XSUB's
               return values.

                       EEEEXXXXTTTTEEEENNNNDDDD(((( sssspppp,,,, iiiinnnntttt xxxx ))));;;;


       FREETMPS
               Closing bracket for temporaries on a callback.
               See SSSSAAAAVVVVEEEETTTTMMMMPPPPSSSS and the _p_e_r_l_c_a_l_l manpage.

                       FFFFRRRREEEEEEEETTTTMMMMPPPPSSSS;;;;


       G_ARRAY Used to indicate array context.  See GGGGIIIIMMMMMMMMEEEE and the
               _p_e_r_l_c_a_l_l manpage.

       G_DISCARD
               Indicates that arguments returned from a callback
               should be discarded.  See the _p_e_r_l_c_a_l_l manpage.

       G_EVAL  Used to force a Perl eeeevvvvaaaallll wrapper around a
               callback.  See the _p_e_r_l_c_a_l_l manpage.

       GIMME   The XSUB-writer's equivalent to Perl's wwwwaaaannnnttttaaaarrrrrrrraaaayyyy.
               Returns GGGG____SSSSCCCCAAAALLLLAAAARRRR or GGGG____AAAARRRRRRRRAAAAYYYY for scalar or array
               context.

       G_NOARGS
               Indicates that no arguments are being sent to a
               callback.  See the _p_e_r_l_c_a_l_l manpage.

       G_SCALAR
               Used to indicate scalar context.  See GGGGIIIIMMMMMMMMEEEE and



23/Jan/96                perl 5.002 with                       20





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               the _p_e_r_l_c_a_l_l manpage.

       gv_stashpv
               Returns a pointer to the stash for a specified
               package.  If ccccrrrreeeeaaaatttteeee is set then the package will
               be created if it does not already exist.  If
               ccccrrrreeeeaaaatttteeee is not set and the package does not exist
               then NULL is returned.

                       HHHHVVVV****     ggggvvvv____ssssttttaaaasssshhhhppppvvvv ____((((((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       gv_stashsv
               Returns a pointer to the stash for a specified
               package.  See ggggvvvv____ssssttttaaaasssshhhhppppvvvv.

                       HHHHVVVV****     ggggvvvv____ssssttttaaaasssshhhhssssvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       GvSV    Return the SV from the GV.

       he_free Releases a hash entry from an iterator.  See
               hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxtttt.

       hv_clear
               Clears a hash, making it empty.

                       vvvvooooiiiidddd    hhhhvvvv____cccclllleeeeaaaarrrr ____((((((((HHHHVVVV**** ttttbbbb))))))));;;;


       hv_delete
               Deletes a key/value pair in the hash.  The value
               SV is removed from the hash and returned to the
               caller.  The llllkkkkeeeennnn is the length of the key.  The
               ffffllllaaaaggggssss value will normally be zero; if set to
               G_DISCARD then null will be returned.

                       SSSSVVVV****     hhhhvvvv____ddddeeeelllleeeetttteeee ____((((((((HHHHVVVV**** ttttbbbb,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, IIII33332222 ffffllllaaaaggggssss))))))));;;;


       hv_exists
               Returns a boolean indicating whether the specified
               hash key exists.  The llllkkkkeeeennnn is the length of the
               key.

                       bbbboooooooollll    hhhhvvvv____eeeexxxxiiiissssttttssss ____((((((((HHHHVVVV**** ttttbbbb,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn))))))));;;;


       hv_fetch
               Returns the SV which corresponds to the specified
               key in the hash.  The llllkkkkeeeennnn is the length of the
               key.  If llllvvvvaaaallll is set then the fetch will be part
               of a store.  Check that the return value is non-
               null before dereferencing it to a SSSSVVVV****.



23/Jan/96                perl 5.002 with                       21





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       SSSSVVVV********    hhhhvvvv____ffffeeeettttcccchhhh ____((((((((HHHHVVVV**** ttttbbbb,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, IIII33332222 llllvvvvaaaallll))))))));;;;


       hv_iterinit
               Prepares a starting point to traverse a hash
               table.

                       IIII33332222     hhhhvvvv____iiiitttteeeerrrriiiinnnniiiitttt ____((((((((HHHHVVVV**** ttttbbbb))))))));;;;


       hv_iterkey
               Returns the key from the current position of the
               hash iterator.  See hhhhvvvv____iiiitttteeeerrrriiiinnnniiiitttt.

                       cccchhhhaaaarrrr****   hhhhvvvv____iiiitttteeeerrrrkkkkeeeeyyyy ____((((((((HHHHEEEE**** eeeennnnttttrrrryyyy,,,, IIII33332222**** rrrreeeettttlllleeeennnn))))))));;;;


       hv_iternext
               Returns entries from a hash iterator.  See
               hhhhvvvv____iiiitttteeeerrrriiiinnnniiiitttt.

                       HHHHEEEE****     hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxtttt ____((((((((HHHHVVVV**** ttttbbbb))))))));;;;


       hv_iternextsv
               Performs an hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxtttt, hhhhvvvv____iiiitttteeeerrrrkkkkeeeeyyyy, and
               hhhhvvvv____iiiitttteeeerrrrvvvvaaaallll in one operation.

                       SSSSVVVV ****    hhhhvvvv____iiiitttteeeerrrrnnnneeeexxxxttttssssvvvv ____((((((((HHHHVVVV**** hhhhvvvv,,,, cccchhhhaaaarrrr******** kkkkeeeeyyyy,,,, IIII33332222**** rrrreeeettttlllleeeennnn))))))));;;;


       hv_iterval
               Returns the value from the current position of the
               hash iterator.  See hhhhvvvv____iiiitttteeeerrrrkkkkeeeeyyyy.

                       SSSSVVVV****     hhhhvvvv____iiiitttteeeerrrrvvvvaaaallll ____((((((((HHHHVVVV**** ttttbbbb,,,, HHHHEEEE**** eeeennnnttttrrrryyyy))))))));;;;


       hv_magic
               Adds magic to a hash.  See ssssvvvv____mmmmaaaaggggiiiicccc.

                       vvvvooooiiiidddd    hhhhvvvv____mmmmaaaaggggiiiicccc ____((((((((HHHHVVVV**** hhhhvvvv,,,, GGGGVVVV**** ggggvvvv,,,, iiiinnnntttt hhhhoooowwww))))))));;;;


       HvNAME  Returns the package name of a stash.  See SSSSvvvvSSSSTTTTAAAASSSSHHHH,
               CCCCvvvvSSSSTTTTAAAASSSSHHHH.

                       cccchhhhaaaarrrr ****HHHHvvvvNNNNAAAAMMMMEEEE ((((HHHHVVVV**** ssssttttaaaasssshhhh))))


       hv_store
               Stores an SV in a hash.  The hash key is specified
               as kkkkeeeeyyyy and kkkklllleeeennnn is the length of the key.  The
               hhhhaaaasssshhhh parameter is the pre-computed hash value; if



23/Jan/96                perl 5.002 with                       22





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               it is zero then Perl will compute it.  The return
               value will be null if the operation failed,
               otherwise it can be dereferenced to get the
               original SSSSVVVV****.

                       SSSSVVVV********    hhhhvvvv____ssssttttoooorrrreeee ____((((((((HHHHVVVV**** ttttbbbb,,,, cccchhhhaaaarrrr**** kkkkeeeeyyyy,,,, UUUU33332222 kkkklllleeeennnn,,,, SSSSVVVV**** vvvvaaaallll,,,, UUUU33332222 hhhhaaaasssshhhh))))))));;;;


       hv_undef
               Undefines the hash.

                       vvvvooooiiiidddd    hhhhvvvv____uuuunnnnddddeeeeffff ____((((((((HHHHVVVV**** ttttbbbb))))))));;;;


       isALNUM Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               an ascii alphanumeric character or digit.

                       iiiinnnntttt iiiissssAAAALLLLNNNNUUUUMMMM ((((cccchhhhaaaarrrr cccc))))


       isALPHA Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               an ascii alphanumeric character.

                       iiiinnnntttt iiiissssAAAALLLLPPPPHHHHAAAA ((((cccchhhhaaaarrrr cccc))))


       isDIGIT Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               an ascii digit.

                       iiiinnnntttt iiiissssDDDDIIIIGGGGIIIITTTT ((((cccchhhhaaaarrrr cccc))))


       isLOWER Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               a lowercase character.

                       iiiinnnntttt iiiissssLLLLOOOOWWWWEEEERRRR ((((cccchhhhaaaarrrr cccc))))


       isSPACE Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               whitespace.

                       iiiinnnntttt iiiissssSSSSPPPPAAAACCCCEEEE ((((cccchhhhaaaarrrr cccc))))


       isUPPER Returns a boolean indicating whether the C cccchhhhaaaarrrr is
               an uppercase character.

                       iiiinnnntttt iiiissssUUUUPPPPPPPPEEEERRRR ((((cccchhhhaaaarrrr cccc))))


       items   Variable which is setup by xxxxssssuuuubbbbpppppppp to indicate the
               number of items on the stack.  See the _p_e_r_l_x_s
               manpage.




23/Jan/96                perl 5.002 with                       23





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       LEAVE   Closing bracket on a callback.  See EEEENNNNTTTTEEEERRRR and the
               _p_e_r_l_c_a_l_l manpage.

                       LLLLEEEEAAAAVVVVEEEE;;;;


       MARK    Stack marker for the XSUB.  See ddddMMMMAAAARRRRKKKK.

       mg_clear
               Clear something magical that the SV represents.
               See ssssvvvv____mmmmaaaaggggiiiicccc.

                       iiiinnnntttt     mmmmgggg____cccclllleeeeaaaarrrr ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       mg_copy Copies the magic from one SV to another.  See
               ssssvvvv____mmmmaaaaggggiiiicccc.

                       iiiinnnntttt     mmmmgggg____ccccooooppppyyyy ____((((((((SSSSVVVV ****,,,, SSSSVVVV ****,,,, cccchhhhaaaarrrr ****,,,, SSSSTTTTRRRRLLLLEEEENNNN))))))));;;;


       mg_find Finds the magic pointer for type matching the SV.
               See ssssvvvv____mmmmaaaaggggiiiicccc.

                       MMMMAAAAGGGGIIIICCCC****  mmmmgggg____ffffiiiinnnndddd ____((((((((SSSSVVVV**** ssssvvvv,,,, iiiinnnntttt ttttyyyyppppeeee))))))));;;;


       mg_free Free any magic storage used by the SV.  See
               ssssvvvv____mmmmaaaaggggiiiicccc.

                       iiiinnnntttt     mmmmgggg____ffffrrrreeeeeeee ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       mg_get  Do magic after a value is retrieved from the SV.
               See ssssvvvv____mmmmaaaaggggiiiicccc.

                       iiiinnnntttt     mmmmgggg____ggggeeeetttt ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       mg_len  Report on the SV's length.  See ssssvvvv____mmmmaaaaggggiiiicccc.

                       UUUU33332222     mmmmgggg____lllleeeennnn ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       mg_magical
               Turns on the magical status of an SV.  See
               ssssvvvv____mmmmaaaaggggiiiicccc.

                       vvvvooooiiiidddd    mmmmgggg____mmmmaaaaggggiiiiccccaaaallll ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       mg_set  Do magic after a value is assigned to the SV.  See
               ssssvvvv____mmmmaaaaggggiiiicccc.




23/Jan/96                perl 5.002 with                       24





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       iiiinnnntttt     mmmmgggg____sssseeeetttt ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       Move    The XSUB-writer's interface to the C mmmmeeeemmmmmmmmoooovvvveeee
               function.  The ssss is the source, dddd is the
               destination, nnnn is the number of items, and tttt is
               the type.

                       ((((vvvvooooiiiidddd)))) MMMMoooovvvveeee(((( ssss,,,, dddd,,,, nnnn,,,, tttt ))));;;;


       na      A variable which may be used with SSSSvvvvPPPPVVVV to tell
               Perl to calculate the string length.

       New     The XSUB-writer's interface to the C mmmmaaaalllllllloooocccc
               function.

                       vvvvooooiiiidddd **** NNNNeeeewwww(((( xxxx,,,, vvvvooooiiiidddd ****ppppttttrrrr,,,, iiiinnnntttt ssssiiiizzzzeeee,,,, ttttyyyyppppeeee ))))


       Newc    The XSUB-writer's interface to the C mmmmaaaalllllllloooocccc
               function, with cast.

                       vvvvooooiiiidddd **** NNNNeeeewwwwcccc(((( xxxx,,,, vvvvooooiiiidddd ****ppppttttrrrr,,,, iiiinnnntttt ssssiiiizzzzeeee,,,, ttttyyyyppppeeee,,,, ccccaaaasssstttt ))))


       Newz    The XSUB-writer's interface to the C mmmmaaaalllllllloooocccc
               function.  The allocated memory is zeroed with
               mmmmeeeemmmmzzzzeeeerrrroooo.

                       vvvvooooiiiidddd **** NNNNeeeewwwwzzzz(((( xxxx,,,, vvvvooooiiiidddd ****ppppttttrrrr,,,, iiiinnnntttt ssssiiiizzzzeeee,,,, ttttyyyyppppeeee ))))


       newAV   Creates a new AV.  The refcount is set to 1.

                       AAAAVVVV****     nnnneeeewwwwAAAAVVVV ____((((((((vvvvooooiiiidddd))))))));;;;


       newHV   Creates a new HV.  The refcount is set to 1.

                       HHHHVVVV****     nnnneeeewwwwHHHHVVVV ____((((((((vvvvooooiiiidddd))))))));;;;


       newRV   Creates an RV wrapper for an SV.  The refcount for
               the original SV is incremented.

                       SSSSVVVV****     nnnneeeewwwwRRRRVVVV ____((((((((SSSSVVVV**** rrrreeeeffff))))))));;;;


       newSV   Creates a new SV.  The lllleeeennnn parameter indicates the
               number of bytes of pre-allocated string space the
               SV should have.  The refcount for the new SV is
               set to 1.




23/Jan/96                perl 5.002 with                       25





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       SSSSVVVV****     nnnneeeewwwwSSSSVVVV ____((((((((SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))))));;;;


       newSViv Creates a new SV and copies an integer into it.
               The refcount for the SV is set to 1.

                       SSSSVVVV****     nnnneeeewwwwSSSSVVVViiiivvvv ____((((((((IIIIVVVV iiii))))))));;;;


       newSVnv Creates a new SV and copies a double into it.  The
               refcount for the SV is set to 1.

                       SSSSVVVV****     nnnneeeewwwwSSSSVVVVnnnnvvvv ____((((((((NNNNVVVV iiii))))))));;;;


       newSVpv Creates a new SV and copies a string into it.  The
               refcount for the SV is set to 1.  If lllleeeennnn is zero
               then Perl will compute the length.

                       SSSSVVVV****     nnnneeeewwwwSSSSVVVVppppvvvv ____((((((((cccchhhhaaaarrrr**** ssss,,,, SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))))));;;;


       newSVrv Creates a new SV for the RV, rrrrvvvv, to point to.  If
               rrrrvvvv is not an RV then it will be upgraded one.  If
               ccccllllaaaassssssssnnnnaaaammmmeeee is non-null then the new SV will be
               blessed in the specified package.  The new SV is
               returned and its refcount is 1.

                       SSSSVVVV****     nnnneeeewwwwSSSSVVVVrrrrvvvv ____((((((((SSSSVVVV**** rrrrvvvv,,,, cccchhhhaaaarrrr**** ccccllllaaaassssssssnnnnaaaammmmeeee))))))));;;;


       newSVsv Creates a new SV which is an exact duplicate of
               the orignal SV.

                       SSSSVVVV****     nnnneeeewwwwSSSSVVVVssssvvvv ____((((((((SSSSVVVV**** oooolllldddd))))))));;;;


       newXS   Used by xxxxssssuuuubbbbpppppppp to hook up XSUBs as Perl subs.

       newXSproto
               Used by xxxxssssuuuubbbbpppppppp to hook up XSUBs as Perl subs.
               Adds Perl prototypes to the subs.

       Nullav  Null AV pointer.

       Nullch  Null character pointer.

       Nullcv  Null CV pointer.

       Nullhv  Null HV pointer.

       Nullsv  Null SV pointer.





23/Jan/96                perl 5.002 with                       26





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       ORIGMARK
               The original stack mark for the XSUB.  See
               ddddOOOORRRRIIIIGGGGMMMMAAAARRRRKKKK.

       perl_alloc
               Allocates a new Perl interpreter.  See the
               _p_e_r_l_e_m_b_e_d manpage.

       perl_call_argv
               Performs a callback to the specified Perl sub.
               See the _p_e_r_l_c_a_l_l manpage.

                       IIII33332222     ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv ____((((((((cccchhhhaaaarrrr**** ssssuuuubbbbnnnnaaaammmmeeee,,,, IIII33332222 ffffllllaaaaggggssss,,,, cccchhhhaaaarrrr******** aaaarrrrggggvvvv))))))));;;;


       perl_call_method
               Performs a callback to the specified Perl method.
               The blessed object must be on the stack.  See the
               _p_e_r_l_c_a_l_l manpage.

                       IIII33332222     ppppeeeerrrrllll____ccccaaaallllllll____mmmmeeeetttthhhhoooodddd ____((((((((cccchhhhaaaarrrr**** mmmmeeeetttthhhhnnnnaaaammmmeeee,,,, IIII33332222 ffffllllaaaaggggssss))))))));;;;


       perl_call_pv
               Performs a callback to the specified Perl sub.
               See the _p_e_r_l_c_a_l_l manpage.

                       IIII33332222     ppppeeeerrrrllll____ccccaaaallllllll____ppppvvvv ____((((((((cccchhhhaaaarrrr**** ssssuuuubbbbnnnnaaaammmmeeee,,,, IIII33332222 ffffllllaaaaggggssss))))))));;;;


       perl_call_sv
               Performs a callback to the Perl sub whose name is
               in the SV.  See the _p_e_r_l_c_a_l_l manpage.

                       IIII33332222     ppppeeeerrrrllll____ccccaaaallllllll____ssssvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, IIII33332222 ffffllllaaaaggggssss))))))));;;;


       perl_construct
               Initializes a new Perl interpreter.  See the
               _p_e_r_l_e_m_b_e_d manpage.

       perl_destruct
               Shuts down a Perl interpreter.  See the _p_e_r_l_e_m_b_e_d
               manpage.

       perl_eval_sv
               Tells Perl to eeeevvvvaaaallll the string in the SV.

                       IIII33332222     ppppeeeerrrrllll____eeeevvvvaaaallll____ssssvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, IIII33332222 ffffllllaaaaggggssss))))))));;;;


       perl_free
               Releases a Perl interpreter.  See the _p_e_r_l_e_m_b_e_d
               manpage.



23/Jan/96                perl 5.002 with                       27





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       perl_get_av
               Returns the AV of the specified Perl array.  If
               ccccrrrreeeeaaaatttteeee is set and the Perl variable does not exist
               then it will be created.  If ccccrrrreeeeaaaatttteeee is not set and
               the variable does not exist then null is returned.

                       AAAAVVVV****     ppppeeeerrrrllll____ggggeeeetttt____aaaavvvv ____((((((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       perl_get_cv
               Returns the CV of the specified Perl sub.  If
               ccccrrrreeeeaaaatttteeee is set and the Perl variable does not exist
               then it will be created.  If ccccrrrreeeeaaaatttteeee is not set and
               the variable does not exist then null is returned.

                       CCCCVVVV****     ppppeeeerrrrllll____ggggeeeetttt____ccccvvvv ____((((((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       perl_get_hv
               Returns the HV of the specified Perl hash.  If
               ccccrrrreeeeaaaatttteeee is set and the Perl variable does not exist
               then it will be created.  If ccccrrrreeeeaaaatttteeee is not set and
               the variable does not exist then null is returned.

                       HHHHVVVV****     ppppeeeerrrrllll____ggggeeeetttt____hhhhvvvv ____((((((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       perl_get_sv
               Returns the SV of the specified Perl scalar.  If
               ccccrrrreeeeaaaatttteeee is set and the Perl variable does not exist
               then it will be created.  If ccccrrrreeeeaaaatttteeee is not set and
               the variable does not exist then null is returned.

                       SSSSVVVV****     ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv ____((((((((cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 ccccrrrreeeeaaaatttteeee))))))));;;;


       perl_parse
               Tells a Perl interpreter to parse a Perl script.
               See the _p_e_r_l_e_m_b_e_d manpage.

       perl_require_pv
               Tells Perl to rrrreeeeqqqquuuuiiiirrrreeee a module.

                       vvvvooooiiiidddd    ppppeeeerrrrllll____rrrreeeeqqqquuuuiiiirrrreeee____ppppvvvv ____((((((((cccchhhhaaaarrrr**** ppppvvvv))))))));;;;


       perl_run
               Tells a Perl interpreter to run.  See the
               _p_e_r_l_e_m_b_e_d manpage.

       POPi    Pops an integer off the stack.

                       iiiinnnntttt PPPPOOOOPPPPiiii(((())));;;;




23/Jan/96                perl 5.002 with                       28





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       POPl    Pops a long off the stack.

                       lllloooonnnngggg PPPPOOOOPPPPllll(((())));;;;


       POPp    Pops a string off the stack.

                       cccchhhhaaaarrrr **** PPPPOOOOPPPPpppp(((())));;;;


       POPn    Pops a double off the stack.

                       ddddoooouuuubbbblllleeee PPPPOOOOPPPPnnnn(((())));;;;


       POPs    Pops an SV off the stack.

                       SSSSVVVV**** PPPPOOOOPPPPssss(((())));;;;


       PUSHMARK
               Opening bracket for arguments on a callback.  See
               PPPPUUUUTTTTBBBBAAAACCCCKKKK and the _p_e_r_l_c_a_l_l manpage.

                       PPPPUUUUSSSSHHHHMMMMAAAARRRRKKKK((((pppp))))


       PUSHi   Push an integer onto the stack.  The stack must
               have room for this element.  See XXXXPPPPUUUUSSSSHHHHiiii.

                       PPPPUUUUSSSSHHHHiiii((((iiiinnnntttt dddd))))


       PUSHn   Push a double onto the stack.  The stack must have
               room for this element.  See XXXXPPPPUUUUSSSSHHHHnnnn.

                       PPPPUUUUSSSSHHHHnnnn((((ddddoooouuuubbbblllleeee dddd))))


       PUSHp   Push a string onto the stack.  The stack must have
               room for this element.  The lllleeeennnn indicates the
               length of the string.  See XXXXPPPPUUUUSSSSHHHHpppp.

                       PPPPUUUUSSSSHHHHpppp((((cccchhhhaaaarrrr ****cccc,,,, iiiinnnntttt lllleeeennnn ))))


       PUSHs   Push an SV onto the stack.  The stack must have
               room for this element.  See XXXXPPPPUUUUSSSSHHHHssss.

                       PPPPUUUUSSSSHHHHssss((((ssssvvvv))))


       PUTBACK Closing bracket for XSUB arguments.  This is
               usually handled by xxxxssssuuuubbbbpppppppp.  See PPPPUUUUSSSSHHHHMMMMAAAARRRRKKKK and the



23/Jan/96                perl 5.002 with                       29





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               _p_e_r_l_c_a_l_l manpage for other uses.

                       PPPPUUUUTTTTBBBBAAAACCCCKKKK;;;;


       Renew   The XSUB-writer's interface to the C rrrreeeeaaaalllllllloooocccc
               function.

                       vvvvooooiiiidddd **** RRRReeeennnneeeewwww(((( vvvvooooiiiidddd ****ppppttttrrrr,,,, iiiinnnntttt ssssiiiizzzzeeee,,,, ttttyyyyppppeeee ))))


       Renewc  The XSUB-writer's interface to the C rrrreeeeaaaalllllllloooocccc
               function, with cast.

                       vvvvooooiiiidddd **** RRRReeeennnneeeewwwwcccc(((( vvvvooooiiiidddd ****ppppttttrrrr,,,, iiiinnnntttt ssssiiiizzzzeeee,,,, ttttyyyyppppeeee,,,, ccccaaaasssstttt ))))


       RETVAL  Variable which is setup by xxxxssssuuuubbbbpppppppp to hold the
               return value for an XSUB.  This is always the
               proper type for the XSUB.  See the _p_e_r_l_x_s manpage.

       safefree
               The XSUB-writer's interface to the C ffffrrrreeeeeeee
               function.

       safemalloc
               The XSUB-writer's interface to the C mmmmaaaalllllllloooocccc
               function.

       saferealloc
               The XSUB-writer's interface to the C rrrreeeeaaaalllllllloooocccc
               function.

       savepv  Copy a string to a safe spot.  This does not use
               an SV.

                       cccchhhhaaaarrrr****   ssssaaaavvvveeeeppppvvvv ____((((((((cccchhhhaaaarrrr**** ssssvvvv))))))));;;;


       savepvn Copy a string to a safe spot.  The lllleeeennnn indicates
               number of bytes to copy.  This does not use an SV.

                       cccchhhhaaaarrrr****   ssssaaaavvvveeeeppppvvvvnnnn ____((((((((cccchhhhaaaarrrr**** ssssvvvv,,,, IIII33332222 lllleeeennnn))))))));;;;


       SAVETMPS
               Opening bracket for temporaries on a callback.
               See FFFFRRRREEEEEEEETTTTMMMMPPPPSSSS and the _p_e_r_l_c_a_l_l manpage.

                       SSSSAAAAVVVVEEEETTTTMMMMPPPPSSSS;;;;


       SP      Stack pointer.  This is usually handled by xxxxssssuuuubbbbpppppppp.
               See ddddSSSSPPPP and SSSSPPPPAAAAGGGGAAAAIIIINNNN.



23/Jan/96                perl 5.002 with                       30





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       SPAGAIN Refetch the stack pointer.  Used after a callback.
               See the _p_e_r_l_c_a_l_l manpage.

                       SSSSPPPPAAAAGGGGAAAAIIIINNNN;;;;


       ST      Used to access elements on the XSUB's stack.

                       SSSSVVVV**** SSSSTTTT((((iiiinnnntttt xxxx))))


       strEQ   Test two strings to see if they are equal.
               Returns true or false.

                       iiiinnnntttt ssssttttrrrrEEEEQQQQ(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strGE   Test two strings to see if the first, ssss1111, is
               greater than or equal to the second, ssss2222.  Returns
               true or false.

                       iiiinnnntttt ssssttttrrrrGGGGEEEE(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strGT   Test two strings to see if the first, ssss1111, is
               greater than the second, ssss2222.  Returns true or
               false.

                       iiiinnnntttt ssssttttrrrrGGGGTTTT(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strLE   Test two strings to see if the first, ssss1111, is less
               than or equal to the second, ssss2222.  Returns true or
               false.

                       iiiinnnntttt ssssttttrrrrLLLLEEEE(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strLT   Test two strings to see if the first, ssss1111, is less
               than the second, ssss2222.  Returns true or false.

                       iiiinnnntttt ssssttttrrrrLLLLTTTT(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strNE   Test two strings to see if they are different.
               Returns true or false.

                       iiiinnnntttt ssssttttrrrrNNNNEEEE(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strnEQ  Test two strings to see if they are equal.  The
               lllleeeennnn parameter indicates the number of bytes to
               compare.  Returns true or false.




23/Jan/96                perl 5.002 with                       31





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       iiiinnnntttt ssssttttrrrrnnnnEEEEQQQQ(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222 ))))


       strnNE  Test two strings to see if they are different.
               The lllleeeennnn parameter indicates the number of bytes to
               compare.  Returns true or false.

                       iiiinnnntttt ssssttttrrrrnnnnNNNNEEEE(((( cccchhhhaaaarrrr ****ssss1111,,,, cccchhhhaaaarrrr ****ssss2222,,,, iiiinnnntttt lllleeeennnn ))))


       sv_2mortal
               Marks an SV as mortal.  The SV will be destroyed
               when the current context ends.

                       SSSSVVVV****     ssssvvvv____2222mmmmoooorrrrttttaaaallll ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       sv_bless
               Blesses an SV into a specified package.  The SV
               must be an RV.  The package must be designated by
               its stash (see ggggvvvv____ssssttttaaaasssshhhhppppvvvv(((())))).  The refcount of the
               SV is unaffected.

                       SSSSVVVV****     ssssvvvv____bbbblllleeeessssssss ____((((((((SSSSVVVV**** ssssvvvv,,,, HHHHVVVV**** ssssttttaaaasssshhhh))))))));;;;


       sv_catpv
               Concatenates the string onto the end of the string
               which is in the SV.

                       vvvvooooiiiidddd    ssssvvvv____ccccaaaattttppppvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** ppppttttrrrr))))))));;;;


       sv_catpvn
               Concatenates the string onto the end of the string
               which is in the SV.  The lllleeeennnn indicates number of
               bytes to copy.

                       vvvvooooiiiidddd    ssssvvvv____ccccaaaattttppppvvvvnnnn ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** ppppttttrrrr,,,, SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))))));;;;


       sv_catsv
               Concatentates the string from SV ssssssssvvvv onto the end
               of the string in SV ddddssssvvvv.

                       vvvvooooiiiidddd    ssssvvvv____ccccaaaattttssssvvvv ____((((((((SSSSVVVV**** ddddssssvvvv,,,, SSSSVVVV**** ssssssssvvvv))))))));;;;


       SvCUR   Returns the length of the string which is in the
               SV.  See SSSSvvvvLLLLEEEENNNN.

                       iiiinnnntttt SSSSvvvvCCCCUUUURRRR ((((SSSSVVVV**** ssssvvvv))))





23/Jan/96                perl 5.002 with                       32





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       SvCUR_set
               Set the length of the string which is in the SV.
               See SSSSvvvvCCCCUUUURRRR.

                       SSSSvvvvCCCCUUUURRRR____sssseeeetttt ((((SSSSVVVV**** ssssvvvv,,,, iiiinnnntttt vvvvaaaallll ))))


       SvEND   Returns a pointer to the last character in the
               string which is in the SV.  See SSSSvvvvCCCCUUUURRRR.  Access the
               character as

                       ****SSSSvvvvEEEENNNNDDDD((((ssssvvvv))))


       SvGROW  Expands the character buffer in the SV.

                       cccchhhhaaaarrrr **** SSSSvvvvGGGGRRRROOOOWWWW(((( SSSSVVVV**** ssssvvvv,,,, iiiinnnntttt lllleeeennnn ))))


       SvIOK   Returns a boolean indicating whether the SV
               contains an integer.

                       iiiinnnntttt SSSSvvvvIIIIOOOOKKKK ((((SSSSVVVV**** SSSSVVVV))))


       SvIOK_off
               Unsets the IV status of an SV.

                       SSSSvvvvIIIIOOOOKKKK____ooooffffffff ((((SSSSVVVV**** ssssvvvv))))


       SvIOK_on
               Tells an SV that it is an integer.

                       SSSSvvvvIIIIOOOOKKKK____oooonnnn ((((SSSSVVVV**** ssssvvvv))))


       SvIOKp  Returns a boolean indicating whether the SV
               contains an integer.  Checks the pppprrrriiiivvvvaaaatttteeee setting.
               Use SSSSvvvvIIIIOOOOKKKK.

                       iiiinnnntttt SSSSvvvvIIIIOOOOKKKKpppp ((((SSSSVVVV**** SSSSVVVV))))


       sv_isa  Returns a boolean indicating whether the SV is
               blessed into the specified class.  This does not
               know how to check for subtype, so it doesn't work
               in an inheritance relationship.

                       iiiinnnntttt     ssssvvvv____iiiissssaaaa ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** nnnnaaaammmmeeee))))))));;;;


       SvIV    Returns the integer which is in the SV.




23/Jan/96                perl 5.002 with                       33





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       iiiinnnntttt SSSSvvvvIIIIVVVV ((((SSSSVVVV**** ssssvvvv))))


       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.

                       iiiinnnntttt     ssssvvvv____iiiissssoooobbbbjjjjeeeecccctttt ____((((((((SSSSVVVV**** ssssvvvv))))))));;;;


       SvIVX   Returns the integer which is stored in the SV.

                       iiiinnnntttt  SSSSvvvvIIIIVVVVXXXX ((((SSSSVVVV**** ssssvvvv))));;;;


       SvLEN   Returns the size of the string buffer in the SV.
               See SSSSvvvvCCCCUUUURRRR.

                       iiiinnnntttt SSSSvvvvLLLLEEEENNNN ((((SSSSVVVV**** ssssvvvv))))


       sv_magic
               Adds magic to an SV.

                       vvvvooooiiiidddd    ssssvvvv____mmmmaaaaggggiiiicccc ____((((((((SSSSVVVV**** ssssvvvv,,,, SSSSVVVV**** oooobbbbjjjj,,,, iiiinnnntttt hhhhoooowwww,,,, cccchhhhaaaarrrr**** nnnnaaaammmmeeee,,,, IIII33332222 nnnnaaaammmmlllleeeennnn))))))));;;;


       sv_mortalcopy
               Creates a new SV which is a copy of the original
               SV.  The new SV is marked as mortal.

                       SSSSVVVV****     ssssvvvv____mmmmoooorrrrttttaaaallllccccooooppppyyyy ____((((((((SSSSVVVV**** oooollllddddssssvvvv))))))));;;;


       SvOK    Returns a boolean indicating whether the value is
               an SV.

                       iiiinnnntttt SSSSvvvvOOOOKKKK ((((SSSSVVVV**** ssssvvvv))))


       sv_newmortal
               Creates a new SV which is mortal.  The refcount of
               the SV is set to 1.

                       SSSSVVVV****     ssssvvvv____nnnneeeewwwwmmmmoooorrrrttttaaaallll ____((((((((vvvvooooiiiidddd))))))));;;;


       sv_no   This is the ffffaaaallllsssseeee SV.  See ssssvvvv____yyyyeeeessss.  Always refer
               to this as &&&&ssssvvvv____nnnnoooo.

       SvNIOK  Returns a boolean indicating whether the SV
               contains a number, integer or double.



23/Jan/96                perl 5.002 with                       34





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       iiiinnnntttt SSSSvvvvNNNNIIIIOOOOKKKK ((((SSSSVVVV**** SSSSVVVV))))


       SvNIOK_off
               Unsets the NV/IV status of an SV.

                       SSSSvvvvNNNNIIIIOOOOKKKK____ooooffffffff ((((SSSSVVVV**** ssssvvvv))))


       SvNIOKp Returns a boolean indicating whether the SV
               contains a number, integer or double.  Checks the
               pppprrrriiiivvvvaaaatttteeee setting.  Use SSSSvvvvNNNNIIIIOOOOKKKK.

                       iiiinnnntttt SSSSvvvvNNNNIIIIOOOOKKKKpppp ((((SSSSVVVV**** SSSSVVVV))))


       SvNOK   Returns a boolean indicating whether the SV
               contains a double.

                       iiiinnnntttt SSSSvvvvNNNNOOOOKKKK ((((SSSSVVVV**** SSSSVVVV))))


       SvNOK_off
               Unsets the NV status of an SV.

                       SSSSvvvvNNNNOOOOKKKK____ooooffffffff ((((SSSSVVVV**** ssssvvvv))))


       SvNOK_on
               Tells an SV that it is a double.

                       SSSSvvvvNNNNOOOOKKKK____oooonnnn ((((SSSSVVVV**** ssssvvvv))))


       SvNOKp  Returns a boolean indicating whether the SV
               contains a double.  Checks the pppprrrriiiivvvvaaaatttteeee setting.
               Use SSSSvvvvNNNNOOOOKKKK.

                       iiiinnnntttt SSSSvvvvNNNNOOOOKKKKpppp ((((SSSSVVVV**** SSSSVVVV))))


       SvNV    Returns the double which is stored in the SV.

                       ddddoooouuuubbbblllleeee SSSSvvvvNNNNVVVV ((((SSSSVVVV**** ssssvvvv))));;;;


       SvNVX   Returns the double which is stored in the SV.

                       ddddoooouuuubbbblllleeee SSSSvvvvNNNNVVVVXXXX ((((SSSSVVVV**** ssssvvvv))));;;;


       SvPOK   Returns a boolean indicating whether the SV
               contains a character string.




23/Jan/96                perl 5.002 with                       35





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


                       iiiinnnntttt SSSSvvvvPPPPOOOOKKKK ((((SSSSVVVV**** SSSSVVVV))))


       SvPOK_off
               Unsets the PV status of an SV.

                       SSSSvvvvPPPPOOOOKKKK____ooooffffffff ((((SSSSVVVV**** ssssvvvv))))


       SvPOK_on
               Tells an SV that it is a string.

                       SSSSvvvvPPPPOOOOKKKK____oooonnnn ((((SSSSVVVV**** ssssvvvv))))


       SvPOKp  Returns a boolean indicating whether the SV
               contains a character string.  Checks the pppprrrriiiivvvvaaaatttteeee
               setting.  Use SSSSvvvvPPPPOOOOKKKK.

                       iiiinnnntttt SSSSvvvvPPPPOOOOKKKKpppp ((((SSSSVVVV**** SSSSVVVV))))


       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 lllleeeennnn is nnnnaaaa then Perl will
               handle the length on its own.

                       cccchhhhaaaarrrr **** SSSSvvvvPPPPVVVV ((((SSSSVVVV**** ssssvvvv,,,, iiiinnnntttt lllleeeennnn ))))


       SvPVX   Returns a pointer to the string in the SV.  The SV
               must contain a string.

                       cccchhhhaaaarrrr **** SSSSvvvvPPPPVVVVXXXX ((((SSSSVVVV**** ssssvvvv))))


       SvREFCNT
               Returns the value of the object's refcount.

                       iiiinnnntttt SSSSvvvvRRRREEEEFFFFCCCCNNNNTTTT ((((SSSSVVVV**** ssssvvvv))));;;;


       SvREFCNT_dec
               Decrements the refcount of the given SV.

                       vvvvooooiiiidddd SSSSvvvvRRRREEEEFFFFCCCCNNNNTTTT____ddddeeeecccc ((((SSSSVVVV**** ssssvvvv))))


       SvREFCNT_inc
               Increments the refcount of the given SV.

                       vvvvooooiiiidddd SSSSvvvvRRRREEEEFFFFCCCCNNNNTTTT____iiiinnnncccc ((((SSSSVVVV**** ssssvvvv))))





23/Jan/96                perl 5.002 with                       36





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       SvROK   Tests if the SV is an RV.

                       iiiinnnntttt SSSSvvvvRRRROOOOKKKK ((((SSSSVVVV**** ssssvvvv))))


       SvROK_off
               Unsets the RV status of an SV.

                       SSSSvvvvRRRROOOOKKKK____ooooffffffff ((((SSSSVVVV**** ssssvvvv))))


       SvROK_on
               Tells an SV that it is an RV.

                       SSSSvvvvRRRROOOOKKKK____oooonnnn ((((SSSSVVVV**** ssssvvvv))))


       SvRV    Dereferences an RV to return the SV.

                       SSSSVVVV****     SSSSvvvvRRRRVVVV ((((SSSSVVVV**** ssssvvvv))));;;;


       sv_setiv
               Copies an integer into the given SV.

                       vvvvooooiiiidddd    ssssvvvv____sssseeeettttiiiivvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, IIIIVVVV nnnnuuuummmm))))))));;;;


       sv_setnv
               Copies a double into the given SV.

                       vvvvooooiiiidddd    ssssvvvv____sssseeeettttnnnnvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, ddddoooouuuubbbblllleeee nnnnuuuummmm))))))));;;;


       sv_setpv
               Copies a string into an SV.  The string must be
               null-terminated.

                       vvvvooooiiiidddd    ssssvvvv____sssseeeettttppppvvvv ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** ppppttttrrrr))))))));;;;


       sv_setpvn
               Copies a string into an SV.  The lllleeeennnn parameter
               indicates the number of bytes to be copied.

                       vvvvooooiiiidddd    ssssvvvv____sssseeeettttppppvvvvnnnn ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** ppppttttrrrr,,,, SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))))));;;;


       sv_setref_iv
               Copies an integer into an SV, optionally blessing
               the SV.  The SV must be an RV.  The ccccllllaaaassssssssnnnnaaaammmmeeee
               argument indicates the package for the blessing.
               Set ccccllllaaaassssssssnnnnaaaammmmeeee to NNNNuuuullllllllcccchhhh to avoid the blessing.
               The new SV will be returned and will have a



23/Jan/96                perl 5.002 with                       37





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               refcount of 1.

                       SSSSVVVV****     ssssvvvv____sssseeeettttrrrreeeeffff____iiiivvvv ____((((((((SSSSVVVV ****rrrrvvvv,,,, cccchhhhaaaarrrr ****ccccllllaaaassssssssnnnnaaaammmmeeee,,,, IIIIVVVV iiiivvvv))))))));;;;


       sv_setref_nv
               Copies a double into an SV, optionally blessing
               the SV.  The SV must be an RV.  The ccccllllaaaassssssssnnnnaaaammmmeeee
               argument indicates the package for the blessing.
               Set ccccllllaaaassssssssnnnnaaaammmmeeee to NNNNuuuullllllllcccchhhh to avoid the blessing.
               The new SV will be returned and will have a
               refcount of 1.

                       SSSSVVVV****     ssssvvvv____sssseeeettttrrrreeeeffff____nnnnvvvv ____((((((((SSSSVVVV ****rrrrvvvv,,,, cccchhhhaaaarrrr ****ccccllllaaaassssssssnnnnaaaammmmeeee,,,, ddddoooouuuubbbblllleeee nnnnvvvv))))))));;;;


       sv_setref_pv
               Copies a pointer into an SV, optionally blessing
               the SV.  The SV must be an RV.  If the ppppvvvv argument
               is NULL then ssssvvvv____uuuunnnnddddeeeeffff will be placed into the SV.
               The ccccllllaaaassssssssnnnnaaaammmmeeee argument indicates the package for
               the blessing.  Set ccccllllaaaassssssssnnnnaaaammmmeeee to NNNNuuuullllllllcccchhhh to avoid
               the blessing.  The new SV will be returned and
               will have a refcount of 1.

                       SSSSVVVV****     ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvv ____((((((((SSSSVVVV ****rrrrvvvv,,,, cccchhhhaaaarrrr ****ccccllllaaaassssssssnnnnaaaammmmeeee,,,, vvvvooooiiiidddd**** ppppvvvv))))))));;;;

               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 ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvvnnnn copies the string while
               this copies the pointer.

       sv_setref_pvn
               Copies a string into an SV, optionally blessing
               the SV.  The lenth of the string must be specified
               with nnnn.  The SV must be an RV.  The ccccllllaaaassssssssnnnnaaaammmmeeee
               argument indicates the package for the blessing.
               Set ccccllllaaaassssssssnnnnaaaammmmeeee to NNNNuuuullllllllcccchhhh to avoid the blessing.
               The new SV will be returned and will have a
               refcount of 1.

                       SSSSVVVV****     ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvvnnnn ____((((((((SSSSVVVV ****rrrrvvvv,,,, cccchhhhaaaarrrr ****ccccllllaaaassssssssnnnnaaaammmmeeee,,,, cccchhhhaaaarrrr**** ppppvvvv,,,, IIII33332222 nnnn))))))));;;;

               Note that ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvv copies the pointer while
               this copies the string.

       sv_setsv
               Copies the contents of the source SV ssssssssvvvv into the
               destination SV ddddssssvvvv.

                       vvvvooooiiiidddd    ssssvvvv____sssseeeettttssssvvvv ____((((((((SSSSVVVV**** ddddssssvvvv,,,, SSSSVVVV**** ssssssssvvvv))))))));;;;




23/Jan/96                perl 5.002 with                       38





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


       SvSTASH Returns the stash of the SV.

                       HHHHVVVV **** SSSSvvvvSSSSTTTTAAAASSSSHHHH ((((SSSSVVVV**** ssssvvvv))))


       SVt_IV  Integer type flag for scalars.  See ssssvvvvttttyyyyppppeeee.

       SVt_PV  Pointer type flag for scalars.  See ssssvvvvttttyyyyppppeeee.

       SVt_PVAV
               Type flag for arrays.  See ssssvvvvttttyyyyppppeeee.

       SVt_PVCV
               Type flag for code refs.  See ssssvvvvttttyyyyppppeeee.

       SVt_PVHV
               Type flag for hashes.  See ssssvvvvttttyyyyppppeeee.

       SVt_PVMG
               Type flag for blessed scalars.  See ssssvvvvttttyyyyppppeeee.

       SVt_NV  Double type flag for scalars.  See ssssvvvvttttyyyyppppeeee.

       SvTRUE  Returns a boolean indicating whether Perl would
               evaluate the SV as true or false, defined or
               undefined.

                       iiiinnnntttt SSSSvvvvTTTTRRRRUUUUEEEE ((((SSSSVVVV**** ssssvvvv))))


       SvTYPE  Returns the type of the SV.  See ssssvvvvttttyyyyppppeeee.

                       ssssvvvvttttyyyyppppeeee  SSSSvvvvTTTTYYYYPPPPEEEE ((((SSSSVVVV**** ssssvvvv))))


       svtype  An enum of flags for Perl types.  These are found
               in the file ssssvvvv....hhhh in the ssssvvvvttttyyyyppppeeee enum.  Test these
               flags with the SSSSvvvvTTTTYYYYPPPPEEEE macro.

       SvUPGRADE
               Used to upgrade an SV to a more complex form.  See
               ssssvvvvttttyyyyppppeeee.

       sv_undef
               This is the uuuunnnnddddeeeeffff SV.  Always refer to this as
               &&&&ssssvvvv____uuuunnnnddddeeeeffff.

       sv_usepvn
               Tells an SV to use ppppttttrrrr to find its string value.
               Normally the string is stored inside the SV; this
               allows the SV to use an outside string.  The
               string length, lllleeeennnn, must be supplied.  This
               function will realloc the memory pointed to by
               ppppttttrrrr, so that pointer should not be freed or used



23/Jan/96                perl 5.002 with                       39





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               by the programmer after giving it to sv_usepvn.

                       vvvvooooiiiidddd    ssssvvvv____uuuusssseeeeppppvvvvnnnn ____((((((((SSSSVVVV**** ssssvvvv,,,, cccchhhhaaaarrrr**** ppppttttrrrr,,,, SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnn))))))));;;;


       sv_yes  This is the ttttrrrruuuueeee SV.  See ssssvvvv____nnnnoooo.  Always refer to
               this as &&&&ssssvvvv____yyyyeeeessss.

       THIS    Variable which is setup by xxxxssssuuuubbbbpppppppp to designate the
               object in a C++ XSUB.  This is always the proper
               type for the C++ object.  See CCCCLLLLAAAASSSSSSSS and the _p_e_r_l_x_s
               manpage.

       toLOWER Converts the specified character to lowercase.

                       iiiinnnntttt ttttooooLLLLOOOOWWWWEEEERRRR ((((cccchhhhaaaarrrr cccc))))


       toUPPER Converts the specified character to uppercase.

                       iiiinnnntttt ttttooooUUUUPPPPPPPPEEEERRRR ((((cccchhhhaaaarrrr cccc))))


       warn    This is the XSUB-writer's interface to Perl's wwwwaaaarrrrnnnn
               function.  Use this function the same way you use
               the C pppprrrriiiinnnnttttffff function.  See ccccrrrrooooaaaakkkk(((()))).

       XPUSHi  Push an integer onto the stack, extending the
               stack if necessary.  See PPPPUUUUSSSSHHHHiiii.

                       XXXXPPPPUUUUSSSSHHHHiiii((((iiiinnnntttt dddd))))


       XPUSHn  Push a double onto the stack, extending the stack
               if necessary.  See PPPPUUUUSSSSHHHHnnnn.

                       XXXXPPPPUUUUSSSSHHHHnnnn((((ddddoooouuuubbbblllleeee dddd))))


       XPUSHp  Push a string onto the stack, extending the stack
               if necessary.  The lllleeeennnn indicates the length of the
               string.  See PPPPUUUUSSSSHHHHpppp.

                       XXXXPPPPUUUUSSSSHHHHpppp((((cccchhhhaaaarrrr ****cccc,,,, iiiinnnntttt lllleeeennnn))))


       XPUSHs  Push an SV onto the stack, extending the stack if
               necessary.  See PPPPUUUUSSSSHHHHssss.

                       XXXXPPPPUUUUSSSSHHHHssss((((ssssvvvv))))


       XSRETURN
               Return from XSUB, indicating number of items on



23/Jan/96                perl 5.002 with                       40





PERLGUTS(1)    User Contributed Perl Documentation    PERLGUTS(1)


               the stack.  This is usually handled by xxxxssssuuuubbbbpppppppp.

                       XXXXSSSSRRRREEEETTTTUUUURRRRNNNN((((xxxx))));;;;


       XSRETURN_EMPTY
               Return from an XSUB immediately.

                       XXXXSSSSRRRREEEETTTTUUUURRRRNNNN____EEEEMMMMPPPPTTTTYYYY;;;;


       XSRETURN_NO
               Return ffffaaaallllsssseeee from an XSUB immediately.

                       XXXXSSSSRRRREEEETTTTUUUURRRRNNNN____NNNNOOOO;;;;


       XSRETURN_UNDEF
               Return uuuunnnnddddeeeeffff from an XSUB immediately.

                       XXXXSSSSRRRREEEETTTTUUUURRRRNNNN____UUUUNNNNDDDDEEEEFFFF;;;;


       XSRETURN_YES
               Return ttttrrrruuuueeee from an XSUB immediately.

                       XXXXSSSSRRRREEEETTTTUUUURRRRNNNN____YYYYEEEESSSS;;;;


       Zero    The XSUB-writer's interface to the C mmmmeeeemmmmzzzzeeeerrrroooo
               function.  The dddd is the destination, nnnn is the
               number of items, and tttt is the type.

                       ((((vvvvooooiiiidddd)))) ZZZZeeeerrrroooo(((( dddd,,,, nnnn,,,, tttt ))));;;;


AAAAUUUUTTTTHHHHOOOORRRR
       Jeff Okamoto <[e-mail]>

       With lots of help and suggestions from Dean Roehrich,
       Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya
       Zakharevich, Paul Marquess, Neil Bowers, Matthew Green,
       Tim Bunce, and Spider Boardman.

       API Listing by Dean Roehrich <[e-mail]>.

DDDDAAAATTTTEEEE
       Version 20: 1995/12/14









23/Jan/96                perl 5.002 with                       41