166 lines
8.0 KiB
HTML
166 lines
8.0 KiB
HTML
<HTML><HEAD><TITLE>Built-In Commands - trace manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="trace.htm#M2" NAME="L1316">NAME</A>
|
|
<DL><DD>trace - Monitor variable accesses</DL>
|
|
<DD><A HREF="trace.htm#M3" NAME="L1317">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>trace </B><I>option</I> ?<I>arg arg ...</I>?
|
|
</DL>
|
|
<DD><A HREF="trace.htm#M4" NAME="L1318">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="trace.htm#M5" NAME="L1319"><B>trace variable </B><I>name ops command</I></A>
|
|
<DL>
|
|
<DD><A HREF="trace.htm#M6" NAME="L1320"><B>r</B></A>
|
|
<DD><A HREF="trace.htm#M7" NAME="L1321"><B>w</B></A>
|
|
<DD><A HREF="trace.htm#M8" NAME="L1322"><B>u</B></A>
|
|
</DL>
|
|
<DD><A HREF="trace.htm#M9" NAME="L1323"><B>trace vdelete </B><I>name ops command</I></A>
|
|
<DD><A HREF="trace.htm#M10" NAME="L1324"><B>trace vinfo </B><I>name</I></A>
|
|
</DL>
|
|
<DD><A HREF="trace.htm#M11" NAME="L1325">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
trace - Monitor variable accesses
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>trace </B><I>option</I> ?<I>arg arg ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command causes Tcl commands to be executed whenever certain operations are
|
|
invoked. At present, only variable tracing is implemented. The
|
|
legal <I>option</I>'s (which may be abbreviated) are:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>trace variable </B><I>name ops command</I></A><DD>
|
|
Arrange for <I>command</I> to be executed whenever variable <I>name</I>
|
|
is accessed in one of the ways given by <I>ops</I>. <I>Name</I> may
|
|
refer to a normal variable, an element of an array, or to an array
|
|
as a whole (i.e. <I>name</I> may be just the name of an array, with no
|
|
parenthesized index). If <I>name</I> refers to a whole array, then
|
|
<I>command</I> is invoked whenever any element of the array is
|
|
manipulated. If the variable does not exist, it will be created but
|
|
will not be given a value, so it will be visible to <B>namespace which</B>
|
|
queries, but not to <B><A HREF="../TkCmd/info.htm">info exists</A></B> queries.
|
|
<P>
|
|
<I>Ops</I> indicates which operations are of interest, and consists of
|
|
one or more of the following letters:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>r</B></A><DD>
|
|
Invoke <I>command</I> whenever the variable is read.
|
|
<P><DT><A NAME="M7"><B>w</B></A><DD>
|
|
Invoke <I>command</I> whenever the variable is written.
|
|
<P><DT><A NAME="M8"><B>u</B></A><DD>
|
|
Invoke <I>command</I> whenever the variable is unset. Variables
|
|
can be unset explicitly with the <B><A HREF="../TkCmd/unset.htm">unset</A></B> command, or
|
|
implicitly when procedures return (all of their local variables
|
|
are unset). Variables are also unset when interpreters are
|
|
deleted, but traces will not be invoked because there is no
|
|
interpreter in which to execute them.
|
|
<P></DL>
|
|
<P>
|
|
When the trace triggers, three arguments are appended to
|
|
<I>command</I> so that the actual command is as follows:
|
|
<PRE><I>command name1 name2 op</I></PRE>
|
|
<I>Name1</I> and <I>name2</I> give the name(s) for the variable
|
|
being accessed: if the variable is a scalar then <I>name1</I>
|
|
gives the variable's name and <I>name2</I> is an empty string;
|
|
if the variable is an array element then <I>name1</I> gives the
|
|
name of the array and name2 gives the index into the array;
|
|
if an entire array is being deleted and the trace was registered
|
|
on the overall array, rather than a single element, then <I>name1</I>
|
|
gives the array name and <I>name2</I> is an empty string.
|
|
<I>Name1</I> and <I>name2</I> are not necessarily the same as the
|
|
name used in the <B>trace variable</B> command: the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
|
command allows a procedure to reference a variable under a
|
|
different name.
|
|
<I>Op</I> indicates what operation is being performed on the
|
|
variable, and is one of <B>r</B>, <B>w</B>, or <B>u</B> as
|
|
defined above.
|
|
<P>
|
|
<I>Command</I> executes in the same context as the code that invoked
|
|
the traced operation: if the variable was accessed as part of a
|
|
Tcl procedure, then <I>command</I> will have access to the same
|
|
local variables as code in the procedure. This context may be
|
|
different than the context in which the trace was created.
|
|
If <I>command</I> invokes a procedure (which it normally does) then
|
|
the procedure will have to use <B><A HREF="../TkCmd/upvar.htm">upvar</A></B> or <B><A HREF="../TkCmd/uplevel.htm">uplevel</A></B> if it
|
|
wishes to access the traced variable.
|
|
Note also that <I>name1</I> may not necessarily be the same as the name
|
|
used to set the trace on the variable; differences can occur if
|
|
the access is made through a variable defined with the <B><A HREF="../TkCmd/upvar.htm">upvar</A></B>
|
|
command.
|
|
<P>
|
|
For read and write traces, <I>command</I> can modify
|
|
the variable to affect the result of the traced operation.
|
|
If <I>command</I> modifies the value of a variable during a
|
|
read or write trace, then the new value will be returned as the
|
|
result of the traced operation.
|
|
The return value from <I>command</I> is ignored except that
|
|
if it returns an error of any sort then the traced operation
|
|
also returns an error with
|
|
the same error message returned by the trace command
|
|
(this mechanism can be used to implement read-only variables, for
|
|
example).
|
|
For write traces, <I>command</I> is invoked after the variable's
|
|
value has been changed; it can write a new value into the variable
|
|
to override the original value specified in the write operation.
|
|
To implement read-only variables, <I>command</I> will have to restore
|
|
the old value of the variable.
|
|
<P>
|
|
While <I>command</I> is executing during a read or write trace, traces
|
|
on the variable are temporarily disabled.
|
|
This means that reads and writes invoked by
|
|
<I>command</I> will occur directly, without invoking <I>command</I>
|
|
(or any other traces) again.
|
|
However, if <I>command</I> unsets the variable then unset traces
|
|
will be invoked.
|
|
<P>
|
|
When an unset trace is invoked, the variable has already been
|
|
deleted: it will appear to be undefined with no traces.
|
|
If an unset occurs because of a procedure return, then the
|
|
trace will be invoked in the variable context of the procedure
|
|
being returned to: the stack frame of the returning procedure
|
|
will no longer exist.
|
|
Traces are not disabled during unset traces, so if an unset trace
|
|
command creates a new trace and accesses the variable, the
|
|
trace will be invoked.
|
|
Any errors in unset traces are ignored.
|
|
<P>
|
|
If there are multiple traces on a variable they are invoked
|
|
in order of creation, most-recent first.
|
|
If one trace returns an error, then no further traces are
|
|
invoked for the variable.
|
|
If an array element has a trace set, and there is also a trace
|
|
set on the array as a whole, the trace on the overall array
|
|
is invoked before the one on the element.
|
|
<P>
|
|
Once created, the trace remains in effect either until the
|
|
trace is removed with the <B>trace vdelete</B> command described
|
|
below, until the variable is unset, or until the interpreter
|
|
is deleted.
|
|
Unsetting an element of array will remove any traces on that
|
|
element, but will not remove traces on the overall array.
|
|
<P>This command returns an empty string.
|
|
<P><DT><A NAME="M9"><B>trace vdelete </B><I>name ops command</I></A><DD>
|
|
If there is a trace set on variable <I>name</I> with the
|
|
operations and command given by <I>ops</I> and <I>command</I>,
|
|
then the trace is removed, so that <I>command</I> will never
|
|
again be invoked.
|
|
Returns an empty string.
|
|
<P><DT><A NAME="M10"><B>trace vinfo </B><I>name</I></A><DD>
|
|
Returns a list containing one element for each trace
|
|
currently set on variable <I>name</I>.
|
|
Each element of the list is itself a list containing two
|
|
elements, which are the <I>ops</I> and <I>command</I> associated
|
|
with the trace.
|
|
If <I>name</I> doesn't exist or doesn't have any traces set, then
|
|
the result of the command will be an empty string.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M11">KEYWORDS</A></H3>
|
|
<A href="../Keywords/R.htm#read">read</A>, <A href="../Keywords/V.htm#variable">variable</A>, <A href="../Keywords/W.htm#write">write</A>, <A href="../Keywords/T.htm#trace">trace</A>, <A href="../Keywords/U.htm#unset">unset</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|