*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> perlguts (1)              


PERLGUTS(1)							   PERLGUTS(1)

NAME    [Toc]    [Back]

     perlguts -	Perl's Internal	Functions

DESCRIPTION    [Toc]    [Back]

     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.

Variables    [Toc]    [Back]


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

	 SV  Scalar Value
	 AV  Array Value
	 HV  Hash Value

     Each typedef has specific routines	that manipulate	the various data

     What is an	"IV"?

     Perl uses a special typedef IV which is a simple integer type that	is
     guaranteed	to be large enough to hold a pointer (as well as an integer).

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

     Working with SVs    [Toc]    [Back]

     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 five routines are:

	 SV*  newSViv(IV);
	 SV*  newSVnv(double);
	 SV*  newSVpv(char*, int);
	 SV*  newSVpvf(const char*, ...);
	 SV*  newSVsv(SV*);

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

	 void  sv_setiv(SV*, IV);
	 void  sv_setnv(SV*, double);
	 void  sv_setpv(SV*, char*);
	 void  sv_setpvn(SV*, char*, int)
	 void  sv_setpvf(SV*, const char*, ...);
	 void  sv_setsv(SV*, SV*);

     Notice that you can choose	to specify the length of the string to be

									Page 1

PERLGUTS(1)							   PERLGUTS(1)

     assigned by using sv_setpvn or newSVpv, or	you may	allow Perl to
     calculate the length by using sv_setpv or by specifying 0 as the second
     argument to newSVpv.  Be warned, though, that Perl	will determine the
     string's length by	using strlen, which depends on the string terminating
     with a NUL	character.  The	arguments of sv_setpvf are processed like
     sprintf, and the formatted	output becomes the value.

     All SVs that will contain strings should, but need	not, be	terminated
     with a NUL	character.  If it is not NUL-terminated	there is a risk	of
     core dumps	and corruptions	from code which	passes the string to C
     functions or system calls which expect a NUL-terminated string.  Perl's
     own functions typically add a trailing NUL	for this reason.
     Nevertheless, you should be very careful when you pass a string stored in
     an	SV to a	C function or system call.

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

	 SvPV(SV*, STRLEN len)

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

     In	the SvPV macro,	the length of the string returned is placed into the
     variable len (this	is a macro, so you do not use &len).  If you do	not
     care what the length of the data is, use the global variable na.
     Remember, however,	that Perl allows arbitrary strings of data that	may
     both contain NULs and might not be	terminated by a	NUL.

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


     Although Perl will	automatically grow strings for you, if you need	to
     force Perl	to allocate more memory	for your SV, you can use the macro

	 SvGROW(SV*, STRLEN newlen)

     which will	determine if more memory needs to be allocated.	 If so,	it
     will call the function sv_grow.  Note that	SvGROW can only	increase, not
     decrease, the allocated memory of an SV and that it does not
     automatically add a byte for the a	trailing NUL (perl's own string
     functions typically do SvGROW(sv, len + 1)).

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


									Page 2

PERLGUTS(1)							   PERLGUTS(1)

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

	 SvCUR_set(SV*,	I32 val)

     You can also get a	pointer	to the end of the string stored	in the SV with
     the macro:


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

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

	 void  sv_catpv(SV*, char*);
	 void  sv_catpvn(SV*, char*, int);
	 void  sv_catpvf(SV*, const char*, ...);
	 void  sv_catsv(SV*, SV*);

     The first function	calculates the length of the string to be appended by
     using strlen.  In the second, you specify the length of the string
     yourself.	The third function processes its arguments like	sprintf	and
     appends the formatted output.  The	fourth function	extends	the string
     stored in the first SV with the string stored in the second SV.  It also
     forces the	second SV to be	interpreted as a string.

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

	 SV*  perl_get_sv("package::varname", FALSE);

     This returns NULL if the variable does not	exist.

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


     The scalar	undef value is stored in an SV instance	called sv_undef.  Its
     address can be used whenever an SV* is needed.

     There are also the	two values sv_yes and sv_no, which contain Boolean
     TRUE and FALSE values, respectively.  Like	sv_undef, their	addresses can
     be	used whenever an SV* is	needed.

     Do	not be fooled into thinking that (SV *)	0 is the same as &sv_undef.
     Take this code:

									Page 3

PERLGUTS(1)							   PERLGUTS(1)

	 SV* sv	= (SV*)	0;
	 if (I-am-to-return-a-real-value) {
		 sv = sv_2mortal(newSViv(42));
	 sv_setsv(ST(0), sv);

     This code tries to	return a new SV	(which contains	the value 42) if it
     should return a real value, or undef otherwise.  Instead it has returned
     a NULL pointer which, somewhere down the line, will cause a segmentation
     violation,	bus error, or just weird results.  Change the zero to
     &sv_undef in the first line and all will be well.

     To	free an	SV that	you've created,	call SvREFCNT_dec(SV*).	 Normally this
     call is not necessary (see	the section on Reference Counts	and

     What's Really Stored in an	SV?

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

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


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

     In	general, though, it's best to use the Sv*V macros.

     Working with AVs    [Toc]    [Back]

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

	 AV*  newAV();

     The second	method both creates the	AV and initially populates it with

	 AV*  av_make(I32 num, SV **ptr);

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

									Page 4

PERLGUTS(1)							   PERLGUTS(1)

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

	 void  av_push(AV*, SV*);
	 SV*   av_pop(AV*);
	 SV*   av_shift(AV*);
	 void  av_unshift(AV*, I32 num);

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

     Here are some other functions:

	 I32   av_len(AV*);
	 SV**  av_fetch(AV*, I32 key, I32 lval);
	 SV**  av_store(AV*, I32 key, SV* val);

     The av_len	function returns the highest index value in array (just	like
     $#array in	Perl).	If the array is	empty, -1 is returned.	The av_fetch
     function returns the value	at index key, but if lval is non-zero, then
     av_fetch will store an undef value	at that	index.	The av_store function
     stores the	value val at index key,	and does not increment the reference
     count of val.  Thus the caller is responsible for taking care of that,
     and if av_store returns NULL, the caller will have	to decrement the
     reference count to	avoid a	memory leak.  Note that	av_fetch and av_store
     both return SV**'s, not SV*'s as their return value.

	 void  av_clear(AV*);
	 void  av_undef(AV*);
	 void  av_extend(AV*, I32 key);

     The av_clear function deletes all the elements in the AV* array, but does
     not actually delete the array itself.  The	av_undef function will delete
     all the elements in the array plus	the array itself.  The av_extend
     function extends the array	so that	it contains key	elements.  If key is
     less than the current length of the array,	then nothing is	done.

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

	 AV*  perl_get_av("package::varname", FALSE);

     This returns NULL if the variable does not	exist.

     See the section on	Understanding the Magic	of Tied	Hashes and Arrays for
     more information on how to	use the	array access functions on tied arrays.

									Page 5

PERLGUTS(1)							   PERLGUTS(1)

     Working with HVs    [Toc]    [Back]

     To	create an HV, you use the following routine:

	 HV*  newHV();

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

	 SV**  hv_store(HV*, char* key,	U32 klen, SV* val, U32 hash);
	 SV**  hv_fetch(HV*, char* key,	U32 klen, I32 lval);

     The klen parameter	is the length of the key being passed in (Note that
     you cannot	pass 0 in as a value of	klen to	tell Perl to measure the
     length of the key).  The val argument contains the	SV pointer to the
     scalar being stored, and hash is the precomputed hash value (zero if you
     want hv_store to calculate	it for you).  The lval parameter indicates
     whether this fetch	is actually a part of a	store operation, in which case
     a new undefined value will	be added to the	HV with	the supplied key and
     hv_fetch will return as if	the value had already existed.

     Remember that hv_store and	hv_fetch return	SV**'s and not just SV*.  To
     access the	scalar value, you must first dereference the return value.
     However, you should check to make sure that the return value is not NULL
     before dereferencing it.

     These two functions check if a hash table entry exists, and deletes it.

	 bool  hv_exists(HV*, char* key, U32 klen);
	 SV*   hv_delete(HV*, char* key, U32 klen, I32 flags);

     If	flags does not include the G_DISCARD flag then hv_delete will create
     and return	a mortal copy of the deleted value.

     And more miscellaneous functions:

	 void	hv_clear(HV*);
	 void	hv_undef(HV*);

     Like their	AV counterparts, hv_clear deletes all the entries in the hash
     table but does not	actually delete	the hash table.	 The hv_undef deletes
     both the entries and the hash table itself.

     Perl keeps	the actual data	in linked list of structures with a typedef of
     HE.  These	contain	the actual key and value pointers (plus	extra
     administrative overhead).	The key	is a string pointer; the value is an
     SV*.  However, once you have an HE*, to get the actual key	and value, use
     the routines specified below.

									Page 6

PERLGUTS(1)							   PERLGUTS(1)

	 I32	hv_iterinit(HV*);
		 /* Prepares starting point to traverse	hash table */
	 HE*	hv_iternext(HV*);
		 /* Get	the next entry,	and return a pointer to	a
		    structure that has both the	key and	value */
	 char*	hv_iterkey(HE* entry, I32* retlen);
		 /* Get	the key	from an	HE structure and also return
		    the	length of the key string */
	 SV*	hv_iterval(HV*,	HE* entry);
		 /* Return a SV	pointer	to the value of	the HE
		    structure */
	 SV*	hv_iternextsv(HV*, char** key, I32* retlen);
		 /* This convenience routine combines hv_iternext,
		    hv_iterkey,	and hv_iterval.	 The key and retlen
		    arguments are return values	for the	key and	its
		    length.  The value is returned in the SV* argument */

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

	 HV*  perl_get_hv("package::varname", FALSE);

     This returns NULL if the variable does not	exist.

     The hash algorithm	is defined in the PERL_HASH(hash, key, klen) macro:

	 i = klen;
	 hash =	0;
	 s = key;
	 while (i--)
	     hash = hash * 33 +	*s++;

     See the section on	Understanding the Magic	of Tied	Hashes and Arrays for
     more information on how to	use the	hash access functions on tied hashes.

     Hash API Extensions    [Toc]    [Back]

     Beginning with version 5.004, the following functions are also supported:

	 HE*	 hv_fetch_ent  (HV* tb,	SV* key, I32 lval, U32 hash);
	 HE*	 hv_store_ent  (HV* tb,	SV* key, SV* val, U32 hash);

	 bool	 hv_exists_ent (HV* tb,	SV* key, U32 hash);
	 SV*	 hv_delete_ent (HV* tb,	SV* key, I32 flags, U32	hash);

	 SV*	 hv_iterkeysv  (HE* entry);

     Note that these functions take SV*	keys, which simplifies writing of
     extension code that deals with hash structures.  These functions also
     allow passing of SV* keys to tie functions	without	forcing	you to
     stringify the keys	(unlike	the previous set of functions).

									Page 7

PERLGUTS(1)							   PERLGUTS(1)

     They also return and accept whole hash entries (HE*), making their	use
     more efficient (since the hash number for a particular string doesn't
     have to be	recomputed every time).	 See the section on API	LISTING	later
     in	this document for detailed descriptions.

     The following macros must always be used to access	the contents of	hash
     entries.  Note that the arguments to these	macros must be simple
     variables,	since they may get evaluated more than once.  See the section
     on	API LISTING later in this document for detailed	descriptions of	these

	 HePV(HE* he, STRLEN len)
	 HeVAL(HE* he)
	 HeHASH(HE* he)
	 HeSVKEY(HE* he)
	 HeSVKEY_force(HE* he)
	 HeSVKEY_set(HE* he, SV* sv)

     These two lower level macros are defined, but must	only be	used when
     dealing with keys that are	not SV*s:

	 HeKEY(HE* he)
	 HeKLEN(HE* he)

     Note that both hv_store and hv_store_ent do not increment the reference
     count of the stored val, which is the caller's responsibility.  If	these
     functions return a	NULL value, the	caller will usually have to decrement
     the reference count of val	to avoid a memory leak.

     References    [Toc]    [Back]

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

     To	create a reference, use	either of the following	functions:

	 SV* newRV_inc((SV*) thing);
	 SV* newRV_noinc((SV*) thing);

     The thing argument	can be any of an SV*, AV*, or HV*.  The	functions are
     identical except that newRV_inc increments	the reference count of the
     thing, while newRV_noinc does not.	 For historical	reasons, newRV is a
     synonym for newRV_inc.

     Once you have a reference,	you can	use the	following macro	to dereference
     the reference:


     then call the appropriate routines, casting the returned SV* to either an
     AV* or HV*, if required.

									Page 8

PERLGUTS(1)							   PERLGUTS(1)

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


     To	discover what type of value the	reference refers to, use the following
     macro and then check the return value.


     The most useful types that	will be	returned are:

	 SVt_IV	   Scalar
	 SVt_NV	   Scalar
	 SVt_PV	   Scalar
	 SVt_RV	   Scalar
	 SVt_PVAV  Array
	 SVt_PVHV  Hash
	 SVt_PVCV  Code
	 SVt_PVGV  Glob	(possible a file handle)
	 SVt_PVMG  Blessed or Magical Scalar

	 See the sv.h header file for more details.

     Blessed References	and Class Objects

     References	are also used to support object-oriented programming.  In the
     OO	lexicon, an object is simply a reference that has been blessed into a
     package (or class).  Once blessed,	the programmer may now use the
     reference to access the various methods in	the class.

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

	 SV* sv_bless(SV* sv, HV* stash);

     The sv argument must be a reference.  The stash argument specifies	which
     class the reference will belong to.  See the section on Stashes and Globs
     for information on	converting class names into stashes.

     /*	Still under construction */

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

	     SV* newSVrv(SV* rv, char* classname);

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

									Page 9

PERLGUTS(1)							   PERLGUTS(1)

	     SV* sv_setref_iv(SV* rv, char* classname, IV iv);
	     SV* sv_setref_nv(SV* rv, char* classname, NV iv);

     Copies the	pointer	value (the address, not	the string!) into an SV	whose
     reference is rv.  SV is blessed if	classname is non-null.

	     SV* sv_setref_pv(SV* rv, char* classname, PV iv);

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

	     SV* sv_setref_pvn(SV* rv, char* classname,	PV iv, int length);

	     int sv_isa(SV* sv,	char* name);
	     int sv_isobject(SV* sv);

     Creating New Variables    [Toc]    [Back]

     To	create a new Perl variable with	an undef value which can be accessed
     from your Perl script, use	the following routines,	depending on the
     variable type.

	 SV*  perl_get_sv("package::varname", TRUE);
	 AV*  perl_get_av("package::varname", TRUE);
	 HV*  perl_get_hv("package::varname", TRUE);

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

     There are additional macros whose values may be bitwise OR'ed with	the
     TRUE argument to enable certain extra features.  Those bits are:

	 GV_ADDMULTI Marks the variable	as multiply defined, thus preventing the
		     "Name <varname> used only once: possible typo" warning.
	 GV_ADDWARN  Issues the	warning	"Had to	create <varname> unexpectedly" if
		     the variable did not exist	before the function was	called.

     If	you do not specify a package name, the variable	is created in the
     current package.

     Reference Counts and Mortality    [Toc]    [Back]

     Perl uses an reference count-driven garbage collection mechanism. SVs,
     AVs, or HVs (xV for short in the following) start their life with a
     reference count of	1.  If the reference count of an xV ever drops to 0,
     then it will be destroyed and its memory made available for reuse.

     This normally doesn't happen at the Perl level unless a variable is
     undef'ed or the last variable holding a reference to it is	changed	or
     overwritten.  At the internal level, however, reference counts can	be

								       Page 10

PERLGUTS(1)							   PERLGUTS(1)

     manipulated with the following macros:

	 int SvREFCNT(SV* sv);
	 SV* SvREFCNT_inc(SV* sv);
	 void SvREFCNT_dec(SV* sv);

     However, there is one other function which	manipulates the	reference
     count of its argument.  The newRV_inc function, you will recall, creates
     a reference to the	specified argument.  As	a side effect, it increments
     the argument's reference count.  If this is not what you want, use
     newRV_noinc instead.

     For example, imagine you want to return a reference from an XSUB
     function.	Inside the XSUB	routine, you create an SV which	initially has
     a reference count of one.	Then you call newRV_inc, passing it the	justcreated
 SV.  This returns the reference as	a new SV, but the reference
     count of the SV you passed	to newRV_inc has been incremented to two.  Now
     you return	the reference from the XSUB routine and	forget about the SV.
     But Perl hasn't!  Whenever	the returned reference is destroyed, the
     reference count of	the original SV	is decreased to	one and	nothing
     happens.  The SV will hang	around without any way to access it until Perl
     itself terminates.	 This is a memory leak.

     The correct procedure, then, is to	use newRV_noinc	instead	of newRV_inc.
     Then, if and when the last	reference is destroyed,	the reference count of
     the SV will go to zero and	it will	be destroyed, stopping any memory

     There are some convenience	functions available that can help with the
     destruction of xVs.  These	functions introduce the	concept	of
     "mortality".  An xV that is mortal	has had	its reference count marked to
     be	decremented, but not actually decremented, until "a short time later".
     Generally the term	"short time later" means a single Perl statement, such
     as	a call to an XSUB function.  The actual	determinant for	when mortal
     xVs have their reference count decremented	depends	on two macros,
     SAVETMPS and FREETMPS.  See the perlcall manpage and the perlxs manpage
     for more details on these macros.

     "Mortalization" then is at	its simplest a deferred	SvREFCNT_dec.
     However, if you mortalize a variable twice, the reference count will
     later be decremented twice.

     You should	be careful about creating mortal variables.  Strange things
     can happen	if you make the	same value mortal within multiple contexts, or
     if	you make a variable mortal multiple times.

     To	create a mortal	variable, use the functions:

	 SV*  sv_newmortal()
	 SV*  sv_2mortal(SV*)
	 SV*  sv_mortalcopy(SV*)

								       Page 11

PERLGUTS(1)							   PERLGUTS(1)

     The first call creates a mortal SV, the second converts an	existing SV to
     a mortal SV (and thus defers a call to SvREFCNT_dec), and the third
     creates a mortal copy of an existing SV.

     The mortal	routines are not just for SVs -- AVs and HVs can be made
     mortal by passing their address (type-casted to SV*) to the sv_2mortal or
     sv_mortalcopy routines.

     Stashes and Globs    [Toc]    [Back]

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

	 Scalar	Value
	 Array Value
	 Hash Value
	 File Handle
	 Directory Handle

     There is a	single stash called "defstash" that holds the items that exist
     in	the "main" package.  To	get at the items in other packages, append the
     string "::" to the	package	name.  The items in the	"Foo" package are in
     the stash "Foo::" in defstash.  The items in the "Bar::Baz" package are
     in	the stash "Baz::" in "Bar::"'s stash.

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

	 HV*  gv_stashpv(char* name, I32 create)
	 HV*  gv_stashsv(SV*, I32 create)

     The first function	takes a	literal	string,	the second uses	the string
     stored in the SV.	Remember that a	stash is just a	hash table, so you get
     back an HV*.  The create flag will	create a new package if	it is set.

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

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

	 HV*  SvSTASH(SvRV(SV*));

     then use the following to get the package name itself:

								       Page 12

PERLGUTS(1)							   PERLGUTS(1)

	 char*	HvNAME(HV* stash);

     If	you need to bless or re-bless an object	you can	use the	following

	 SV*  sv_bless(SV*, HV*	stash)

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

     For more information on references	and blessings, consult the perlref

     Double-Typed SVs    [Toc]    [Back]

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

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

     To	force multiple data values into	an SV, you must	do two things: use the
     sv_set*v routines to add the additional scalar type, then set a flag so
     that Perl will believe it contains	more than one type of data.  The four
     macros to set the flags are:


     The particular macro you must use depends on which	sv_set*v routine you
     called first.  This is because every sv_set*v routine turns on only the
     bit for the particular type of data being set, and	turns off all the

     For example, to create a new Perl variable	called "dberror" that contains
     both the numeric and descriptive string error values, you could use the
     following code:

	 extern	int  dberror;
	 extern	char *dberror_list;

	 SV* sv	= perl_get_sv("dberror", TRUE);
	 sv_setiv(sv, (IV) dberror);
	 sv_setpv(sv, dberror_list[dberror]);

     If	the order of sv_setiv and sv_setpv had been reversed, then the macro

								       Page 13

PERLGUTS(1)							   PERLGUTS(1)

     SvPOK_on would need to be called instead of SvIOK_on.

     Magic Variables    [Toc]    [Back]

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

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

	 struct	magic {
	     MAGIC*	 mg_moremagic;
	     MGVTBL*	 mg_virtual;
	     U16	 mg_private;
	     char	 mg_type;
	     U8		 mg_flags;
	     SV*	 mg_obj;
	     char*	 mg_ptr;
	     I32	 mg_len;

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

     Assigning Magic    [Toc]    [Back]

     Perl adds magic to	an SV using the	sv_magic function:

	 void sv_magic(SV* sv, SV* obj,	int how, char* name, I32 namlen);

     The sv argument is	a pointer to the SV that is to acquire a new magical

     If	sv is not already magical, Perl	uses the SvUPGRADE macro to set	the
     SVt_PVMG flag for the sv.	Perl then continues by adding it to the
     beginning of the linked list of magical features.	Any prior entry	of the
     same type of magic	is deleted.  Note that this can	be overridden, and
     multiple instances	of the same type of magic can be associated with an

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

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

								       Page 14

PERLGUTS(1)							   PERLGUTS(1)

     The obj argument is stored	in the mg_obj field of the MAGIC structure.
     If	it is not the same as the sv argument, the reference count of the obj
     object is incremented.  If	it is the same,	or if the how argument is "#",
     or	if it is a NULL	pointer, then obj is merely stored, without the
     reference count being incremented.

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

	 void hv_magic(HV *hv, GV *gv, int how);

     This simply calls sv_magic	and coerces the	gv argument into an SV.

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

	 void sv_unmagic(SV *sv, int type);

     The type argument should be equal to the how value	when the SV was
     initially made magical.

     Magic Virtual Tables    [Toc]    [Back]

     The mg_virtual field in the MAGIC structure is a pointer to a MGVTBL,
     which is a	structure of function pointers and stands for "Magic Virtual
     Table" to handle the various operations that might	be applied to that

     The MGVTBL	has five pointers to the following routine types:

	 int  (*svt_get)(SV* sv, MAGIC*	mg);
	 int  (*svt_set)(SV* sv, MAGIC*	mg);
	 U32  (*svt_len)(SV* sv, MAGIC*	mg);
	 int  (*svt_clear)(SV* sv, MAGIC* mg);
	 int  (*svt_free)(SV* sv, MAGIC* mg);

     This MGVTBL structure is set at compile-time in perl.h and	there are
     currently 19 types	(or 21 with overloading	turned on).  These different
     structures	contain	pointers to various routines that perform additional
     actions depending on which	function is being called.

	 Function pointer    Action taken
	 ----------------    ------------
	 svt_get	     Do	something after	the value of the SV is retrieved.
	 svt_set	     Do	something after	the SV is assigned a value.
	 svt_len	     Report on the SV's	length.
	 svt_clear	     Clear something the SV represents.
	 svt_free	     Free any extra storage associated with the	SV.

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

								       Page 15

PERLGUTS(1)							   PERLGUTS(1)

	 { magic_get, magic_set, magic_len, 0, 0 }

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

     The current kinds of Magic	Virtual	Tables are:

	 mg_type  MGVTBL	      Type of magic
	 -------  ------	      ----------------------------
	 \0	  vtbl_sv	      Special scalar variable
	 A	  vtbl_amagic	      %OVERLOAD	hash
	 a	  vtbl_amagicelem     %OVERLOAD	hash element
	 c	  (none)	      Holds overload table (AMT) on stash
	 B	  vtbl_bm	      Boyer-Moore (fast	string search)
	 E	  vtbl_env	      %ENV hash
	 e	  vtbl_envelem	      %ENV hash	element
	 f	  vtbl_fm	      Formline ('compiled' format)
	 g	  vtbl_mglob	      m//g target / study()ed string
	 I	  vtbl_isa	      @ISA array
	 i	  vtbl_isaelem	      @ISA array element
	 k	  vtbl_nkeys	      scalar(keys()) lvalue
	 L	  (none)	      Debugger %_<filename
	 l	  vtbl_dbline	      Debugger %_<filename element
	 o	  vtbl_collxfrm	      Locale transformation
	 P	  vtbl_pack	      Tied array or hash
	 p	  vtbl_packelem	      Tied array or hash element
	 q	  vtbl_packelem	      Tied scalar or handle
	 S	  vtbl_sig	      %SIG hash
	 s	  vtbl_sigelem	      %SIG hash	element
	 t	  vtbl_taint	      Taintedness
	 U	  vtbl_uvar	      Available	for use	by extensions
	 v	  vtbl_vec	      vec() lvalue
	 x	  vtbl_substr	      substr() lvalue
	 y	  vtbl_defelem	      Shadow "foreach" iterator	variable /
				       smart parameter vivification
	 *	  vtbl_glob	      GV (typeglob)
	 #	  vtbl_arylen	      Array length ($#ary)
	 .	  vtbl_pos	      pos() lvalue
	 ~	  (none)	      Available	for use	by extensions

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

     The '~' and 'U' magic types are defined specifically for use by
     extensions	and will not be	used by	perl itself.  Extensions can use '~'
     magic to 'attach' private information to variables	(typically objects).
     This is especially	useful because there is	no way for normal perl code to
     corrupt this private information (unlike using extra elements of a	hash

								       Page 16

PERLGUTS(1)							   PERLGUTS(1)

     Similarly,	'U' magic can be used much like	tie() to call a	C function any
     time a scalar's value is used or changed.	The MAGIC's mg_ptr field
     points to a ufuncs	structure:

	 struct	ufuncs {
	     I32 (*uf_val)(IV, SV*);
	     I32 (*uf_set)(IV, SV*);
	     IV	uf_index;

     When the SV is read from or written to, the uf_val	or uf_set function
     will be called with uf_index as the first arg and a pointer to the	SV as
     the second.

     Note that because multiple	extensions may be using	'~' or 'U' magic, it
     is	important for extensions to take extra care to avoid conflict.
     Typically only using the magic on objects blessed into the	same class as
     the extension is sufficient.  For '~' magic, it may also be appropriate
     to	add an I32 'signature' at the top of the private data area and check

     Finding Magic    [Toc]    [Back]

	 MAGIC*	mg_find(SV*, int type);	/* Finds the magic pointer of that type	*/

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

	 int mg_copy(SV* sv, SV* nsv, char* key, STRLEN	klen);

     This routine checks to see	what types of magic sv has.  If	the mg_type
     field is an uppercase letter, then	the mg_obj is copied to	nsv, but the
     mg_type field is changed to be the	lowercase letter.

     Understanding the Magic of	Tied Hashes and	Arrays

     Tied hashes and arrays are	magical	beasts of the 'P' magic	type.

     WARNING: As of the	5.004 release, proper usage of the array and hash
     access functions requires understanding a few caveats.  Some of these
     caveats are actually considered bugs in the API, to be fixed in later
     releases, and are bracketed with [MAYCHANGE] below. If you	find yourself
     actually applying such information	in this	section, be aware that the
     behavior may change in the	future,	umm, without warning.

     The av_store function, when given a tied array argument, merely copies
     the magic of the array onto the value to be "stored", using mg_copy.  It
     may also return NULL, indicating that the value did not actually need to
     be	stored in the array.  [MAYCHANGE] After	a call to av_store on a	tied
     array, the	caller will usually need to call mg_set(val) to	actually
     invoke the	perl level "STORE" method on the TIEARRAY object.  If av_store

								       Page 17

PERLGUTS(1)							   PERLGUTS(1)

     did return	NULL, a	call to	SvREFCNT_dec(val) will also be usually
     necessary to avoid	a memory leak. [/MAYCHANGE]

     The previous paragraph is applicable verbatim to tied hash	access using
     the hv_store and hv_store_ent functions as	well.

     av_fetch and the corresponding hash functions hv_fetch and	hv_fetch_ent
     actually return an	undefined mortal value whose magic has been
     initialized using mg_copy.	 Note the value	so returned does not need to
     be	deallocated, as	it is already mortal.  [MAYCHANGE] But you will	need
     to	call mg_get() on the returned value in order to	actually invoke	the
     perl level	"FETCH"	method on the underlying TIE object.  Similarly, you
     may also call mg_set() on the return value	after possibly assigning a
     suitable value to it using	sv_setsv,  which will invoke the "STORE"
     method on the TIE object. [/MAYCHANGE]

     [MAYCHANGE] In other words, the array or hash fetch/store functions don't
     really fetch and store actual values in the case of tied arrays and
     hashes.  They merely call mg_copy to attach magic to the values that were
     meant to be "stored" or "fetched".	 Later calls to	mg_get and mg_set
     actually do the job of invoking the TIE methods on	the underlying
     objects.  Thus the	magic mechanism	currently implements a kind of lazy
     access to arrays and hashes.

     Currently (as of perl version 5.004), use of the hash and array access
     functions requires	the user to be aware of	whether	they are operating on
     "normal" hashes and arrays, or on their tied variants.  The API may be
     changed to	provide	more transparent access	to both	tied and normal	data
     types in future versions.	[/MAYCHANGE]

     You would do well to understand that the TIEARRAY and TIEHASH interfaces
     are mere sugar to invoke some perl	method calls while using the uniform
     hash and array syntax.  The use of	this sugar imposes some	overhead
     (typically	about two to four extra	opcodes	per FETCH/STORE	operation, in
     addition to the creation of all the mortal	variables required to invoke
     the methods).  This overhead will be comparatively	small if the TIE
     methods are themselves substantial, but if	they are only a	few statements
     long, the overhead	will not be insignificant.

     Localizing	changes

     Perl has a	very handy construction

	 local $var = 2;

     This construction is approximately	equivalent to

								       Page 18

PERLGUTS(1)							   PERLGUTS(1)

	 my $oldvar = $var;
	 $var =	2;
	 $var =	$oldvar;

     The biggest difference is that the	first construction would reinstate the
     initial value of $var, irrespective of how	control	exits the block: goto,
     return, die/eval etc. It is a little bit more efficient as	well.

     There is a	way to achieve a similar task from C via Perl API: create a
     pseudo-block, and arrange for some	changes	to be automatically undone at
     the end of	it, either explicit, or	via a non-local	exit (via die()). A
     block-like	construct is created by	a pair of ENTER/LEAVE macros (see the
     section on	EXAMPLE/"Returning a Scalar in the perlcall manpage).  Such a
     construct may be created specially	for some important localized task, or
     an	existing one (like boundaries of enclosing Perl	subroutine/block, or
     an	existing pair for freeing TMPs)	may be used. (In the second case the
     overhead of additional localization must be almost	negligible.) Note that
     any XSUB is automatically enclosed	in an ENTER/LEAVE pair.

     Inside such a pseudo-block	the following service is available:

     SAVEINT(int i)

     SAVEIV(IV i)

     SAVEI32(I32 i)

     SAVELONG(long i)
	  These	macros arrange things to restore the value of integer variable
	  i at the end of enclosing pseudo-block.


	  These	macros arrange things to restore the value of pointers s and
	  p. s must be a pointer of a type which survives conversion to	SV*
	  and back, p should be	able to	survive	conversion to char* and	back.

	  The refcount of sv would be decremented at the end of	pseudo-block.
	  This is similar to sv_2mortal, which should (?) be used instead.

	  The OP * is op_free()ed at the end of	pseudo-block.

	  The chunk of memory which is pointed to by p is Safefree()ed at the
	  end of pseudo-block.

								       Page 19

PERLGUTS(1)							   PERLGUTS(1)

	  Clears a slot	in the current scratchpad which	corresponds to sv at
	  the end of pseudo-block.

     SAVEDELETE(HV *hv,	char *key, I32 length)
	  The key key of hv is deleted at the end of pseudo-block. The string
	  pointed to by	key is Safefree()ed.  If one has a key in short-lived
	  storage, the corresponding string may	be reallocated like this:

	    SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf));

	  At the end of	pseudo-block the function f is called with the only
	  argument (of type void*) p.

	  The current offset on	the Perl internal stack	(cf. SP) is restored
	  at the end of	pseudo-block.

     The following API list contains functions,	thus one needs to provide
     pointers to the modifiable	data explicitly	(either	C pointers, or Perlish
     GV	*s).  Where the	above macros take int, a similar function takes	int *.

     SV* save_scalar(GV	*gv)
	  Equivalent to	Perl code local	$gv.

     AV* save_ary(GV *gv)

     HV* save_hash(GV *gv)
	  Similar to save_scalar, but localize @gv and %gv.

     void save_item(SV *item)
	  Duplicates the current value of SV, on the exit from the current
	  ENTER/LEAVE pseudo-block will	restore	the value of SV	using the
	  stored value.

     void save_list(SV **sarg, I32 maxsarg)
	  A variant of save_item which takes multiple arguments	via an array
	  sarg of SV* of length	maxsarg.

     SV* save_svref(SV **sptr)
	  Similar to save_scalar, but will reinstate a SV *.

     void save_aptr(AV **aptr)

     void save_hptr(HV **hptr)
	  Similar to save_svref, but localize AV * and HV *.

     The Alias module implements localization of the basic types within	the
     caller's scope.  People who are interested	in how to localize things in
     the containing scope should take a	look there too.

								       Page 20

PERLGUTS(1)							   PERLGUTS(1)

Subroutines    [Toc]    [Back]

     XSUBs and the Argument Stack

     The XSUB mechanism	is a simple way	for Perl programs to access C
     subroutines.  An XSUB routine will	have a stack that contains the
     arguments from the	Perl program, and a way	to map from the	Perl data
     structures	to a C equivalent.

     The stack arguments are accessible	through	the ST(n) macro, which returns
     the n'th stack argument.  Argument	0 is the first argument	passed in the
     Perl subroutine call.  These arguments are	SV*, and can be	used anywhere
     an	SV* is used.

     Most of the time, output from the C routine can be	handled	through	use of
     the RETVAL	and OUTPUT directives.	However, there are some	cases where
     the argument stack	is not already long enough to handle all the return
     values.  An example is the	POSIX tzname() call, which takes no arguments,
     but returns two, the local	time zone's standard and summer	time

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

	 EXTEND(sp, num);

     where sp is the stack pointer, and	num is the number of elements the
     stack should be extended by.

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

	 PUSHp(char*, I32)

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

	 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;

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

	 XPUSHp(char*, I32)

     These macros automatically	adjust the stack for you, if needed.  Thus,
     you do not	need to	call EXTEND to extend the stack.

								       Page 21

PERLGUTS(1)							   PERLGUTS(1)

     For more information, consult the perlxs manpage and the perlxstut

     Calling Perl Routines from	within C Programs

     There are four routines that can be used to call a	Perl subroutine	from
     within a C	program.  These	four are:

	 I32  perl_call_sv(SV*,	I32);
	 I32  perl_call_pv(char*, I32);
	 I32  perl_call_method(char*, I32);
	 I32  perl_call_argv(char*, I32, register char**);

     The routine most often used is perl_call_sv.  The SV* argument contains
     either the	name of	the Perl subroutine to be called, or a reference to
     the subroutine.  The second argument consists of flags that control the
     context in	which the subroutine is	called,	whether	or not the subroutine
     is	being passed arguments,	how errors should be trapped, and how to treat
     return values.

     All four routines return the number of arguments that the subroutine
     returned on the Perl stack.

     When using	any of these routines (except perl_call_argv), the programmer
     must manipulate the Perl stack.  These include the	following macros and


     For a detailed description	of calling conventions from C to Perl, consult
     the perlcall manpage.

     Memory Allocation    [Toc]    [Back]

     It	is suggested that you use the version of malloc	that is	distributed
     with Perl.	 It keeps pools	of various sizes of unallocated	memory in
     order to satisfy allocation requests more quickly.	 However, on some
     platforms,	it may cause spurious malloc or	free errors.

	 New(x,	pointer, number, type);
	 Newc(x, pointer, number, type,	cast);
	 Newz(x, pointer, number, type);

								       Page 22

PERLGUTS(1)							   PERLGUTS(1)

     These three macros	are used to initially allocate memory.

     The first argument	x was a	"magic cookie" that was	used to	keep track of
     who called	the macro, to help when	debugging memory problems.  However,
     the current code makes no use of this feature (most Perl developers now
     use run-time memory checkers), so this argument can be any	number.

     The second	argument pointer should	be the name of a variable that will
     point to the newly	allocated memory.

     The third and fourth arguments number and type specify how	many of	the
     specified type of data structure should be	allocated.  The	argument type
     is	passed to sizeof.  The final argument to Newc, cast, should be used if
     the pointer argument is different from the	type argument.

     Unlike the	New and	Newc macros, the Newz macro calls memzero to zero out
     all the newly allocated memory.

	 Renew(pointer,	number,	type);
	 Renewc(pointer, number, type, cast);

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

	 Move(source, dest, number, type);
	 Copy(source, dest, number, type);
	 Zero(dest, number, type);

     These three macros	are used to move, copy,	or zero	out previously
     allocated memory.	The source and dest arguments point to the source and
     destination starting points.  Perl	will move, copy, or zero out number
     instances of the size of the type data structure (using the sizeof

     PerlIO    [Toc]    [Back]

     The most recent development releases of Perl has been experimenting with
     removing Perl's dependency	on the "normal"	standard I/O suite and
     allowing other stdio implementations to be	used.  This involves creating
     a new abstraction layer that then calls whichever implementation of stdio
     Perl was compiled with.  All XSUBs	should now use the functions in	the
     PerlIO abstraction	layer and not make any assumptions about what kind of
     stdio is being used.

     For a complete description	of the PerlIO abstraction, consult the
     perlapio manpage.

								       Page 23

PERLGUTS(1)							   PERLGUTS(1)

     Putting a C value on Perl stack    [Toc]    [Back]

     A lot of opcodes (this is an elementary operation in the internal perl
     stack machine) put	an SV* on the stack. However, as an optimization the
     corresponding SV is (usually) not recreated each time. The	opcodes	reuse
     specially assigned	SVs (targets) which are	(as a corollary) not
     constantly	freed/created.

     Each of the targets is created only once (but see the section on
     Scratchpads and recursion below), and when	an opcode needs	to put an
     integer, a	double,	or a string on stack, it just sets the corresponding
     parts of its target and puts the target on	stack.

     The macro to put this target on stack is PUSHTARG,	and it is directly
     used in some opcodes, as well as indirectly in zillions of	others,	which
     use it via	(X)PUSH[pni].

     Scratchpads    [Toc]    [Back]

     The question remains on when the SVs which	are targets for	opcodes	are
     created. The answer is that they are created when the current unit	-- a
     subroutine	or a file (for opcodes for statements outside of subroutines)
     --	is compiled. During this time a	special	anonymous Perl array is
     created, which is called a	scratchpad for the current unit.

     A scratchpad keeps	SVs which are lexicals for the current unit and	are
     targets for opcodes. One can deduce that an SV lives on a scratchpad by
     looking on	its flags: lexicals have SVs_PADMY set,	and targets have
     SVs_PADTMP	set.

     The correspondence	between	OPs and	targets	is not 1-to-1. Different OPs
     in	the compile tree of the	unit can use the same target, if this would
     not conflict with the expected life of the	temporary.

     Scratchpads and recursion    [Toc]    [Back]

     In	fact it	is not 100% true that a	compiled unit contains a pointer to
     the scratchpad AV.	In fact	it contains a pointer to an AV of (initially)
     one element, and this element is the scratchpad AV. Why do	we need	an
     extra level of indirection?

     The answer	is recursion, and maybe	(sometime soon)	threads. Both these
     can create	several	execution pointers going into the same subroutine. For
     the subroutine-child not write over the temporaries for the subroutineparent
 (lifespan of which covers the call to the child), the parent and
     the child should have different scratchpads. (And the lexicals should be
     separate anyway!)

     So	each subroutine	is born	with an	array of scratchpads (of length	1).
     On	each entry to the subroutine it	is checked that	the current depth of
     the recursion is not more than the	length of this array, and if it	is,
     new scratchpad is created and pushed into the array.

								       Page 24

PERLGUTS(1)							   PERLGUTS(1)

     The targets on this scratchpad are	undefs,	but they are already marked
     with correct flags.

Compiled code    [Toc]    [Back]

     Code tree

     Here we describe the internal form	your code is converted to by Perl.
     Start with	a simple example:

       $a = $b + $c;

     This is converted to a tree similar to this one:

		/	    \
	       +	     $a
	     /	 \
	   $b	  $c

     (but slightly more	complicated).  This tree reflect the way Perl parsed
     your code,	but has	nothing	to do with the execution order.	 There is an
     additional	"thread" going through the nodes of the	tree which shows the
     order of execution	of the nodes.  In our simplified example above it
     looks like:

	  $b ---> $c ---> + ---> $a ---> assign-to

     But with the actual compile tree for $a = $b + $c it is different:	 some
     nodes optimized away.  As a corollary, though the actual tree contains
     more nodes	than our simplified example, the execution order is the	same
     as	in our example.

     Examining the tree    [Toc]    [Back]

     If	you have your perl compiled for	debugging (usually done	with -D
     optimize=-g on Configure command line), you may examine the compiled tree
     by	specifying -Dx on the Perl command line.  The output takes several
     lines per node, and for $b+$c it looks like this:

								       Page 25

PERLGUTS(1)							   PERLGUTS(1)

	 5	     TYPE = add	 ===> 6
		     TARG = 1
			 TYPE =	null  ===> (4)
			   (was	rv2sv)
	 3		     TYPE = gvsv  ===> 4
			     FLAGS = (SCALAR)
			     GV	= main::b
			 TYPE =	null  ===> (5)
			   (was	rv2sv)
	 4		     TYPE = gvsv  ===> 5
			     FLAGS = (SCALAR)
			     GV	= main::c

     This tree has 5 nodes (one	per TYPE specifier), only 3 of them are	not
     optimized away (one per number in the left	column).  The immediate
     children of the given node	correspond to {} pairs on the same level of
     indentation, thus this listing corresponds	to the tree:

		      /	    \
		    null    null
		     |	     |
		    gvsv    gvsv

     The execution order is indicated by ===> marks, thus it is	3 4 5 6	(node
     6 is not included into above listing), i.e., gvsv gvsv add	whatever.

     Compile pass 1: check routines

     The tree is created by the	pseudo-compiler	while yacc code	feeds it the
     constructions it recognizes. Since	yacc works bottom-up, so does the
     first pass	of perl	compilation.

     What makes	this pass interesting for perl developers is that some
     optimization may be performed on this pass.  This is optimization by socalled
 check routines.  The correspondence	between	node names and
     corresponding check routines is described in opcode.pl (do	not forget to
     run make regen_headers if you modify this file).

								       Page 26

PERLGUTS(1)							   PERLGUTS(1)

     A check routine is	called when the	node is	fully constructed except for
     the execution-order thread.  Since	at this	time there is no back-links to
     the currently constructed node, one can do	most any operation to the
     top-level node, including freeing it and/or creating new nodes
     above/below it.

     The check routine returns the node	which should be	inserted into the tree
     (if the top-level node was	not modified, check routine returns its

     By	convention, check routines have	names ck_*. They are usually called
     from new*OP subroutines (or convert) (which in turn are called from

     Compile pass 1a: constant folding

     Immediately after the check routine is called the returned	node is
     checked for being compile-time executable.	 If it is (the value is	judged
     to	be constant) it	is immediately executed, and a constant	node with the
     "return value" of the corresponding subtree is substituted	instead.  The
     subtree is	deleted.

     If	constant folding was not performed, the	execution-order	thread is

     Compile pass 2: context propagation

     When a context for	a part of compile tree is known, it is propagated down
     through the tree.	Aat this time the context can have 5 values (instead
     of	2 for runtime context):	void, boolean, scalar, list, and lvalue.  In
     contrast with the pass 1 this pass	is processed from top to bottom: a
     node's context determines the context for its children.

     Additional	context-dependent optimizations	are performed at this time.
     Since at this moment the compile tree contains back-references (via
     "thread" pointers), nodes cannot be free()d now.  To allow	optimized-away
     nodes at this stage, such nodes are null()ified instead of	free()ing
     (i.e. their type is changed to OP_NULL).

     Compile pass 3: peephole optimization

     After the compile tree for	a subroutine (or for an	eval or	a file)	is
     created, an additional pass over the code is p

 Similar pages
Name OS Title
perljp OpenBSD AEuEU,i Perl Y~YxYE `A^a`I`A Perl xIAx3|xOxex|x3x1/2! Perl 5.8.0 xexeicUni- _ codeYuYYi1/4YEx~AcEyxE...
gss_canonicalize_name HP-UX convert an internal name to an internal mechanism name (MN) representation of an opaque internal name
perlfunc OpenBSD Perl builtin functions
perlfunc IRIX Perl builtin functions
bn_sqr_comba8 Tru64 BIGNUM library internal functions
bn_sqr_words Tru64 BIGNUM library internal functions
bn_sqr_normal Tru64 BIGNUM library internal functions
bn_sqr_recursive Tru64 BIGNUM library internal functions
bn_sub_words Tru64 BIGNUM library internal functions
bn_wexpand Tru64 BIGNUM library internal functions
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service