trace(n) Tcl trace(n)
_________________________________________________________________
NAME
trace - Monitor variable accesses
SYNOPSIS
trace option ?arg arg ...?
_________________________________________________________________
DESCRIPTION
This command causes Tcl commands to be executed whenever
certain operations are invoked. At present, only variable
tracing is implemented. The legal option's (which may be
abbreviated) are:
trace variable name ops command
Arrange for command to be executed whenever variable
name is accessed in one of the ways given by ops. Name
may refer to a normal variable, an element of an array,
or to an array as a whole (i.e. name may be just the
name of an array, with no parenthesized index). If
name refers to a whole array, then command is invoked
whenever any element of the array is manipulated.
Ops indicates which operations are of interest, and
consists of one or more of the following letters:
r Invoke command whenever the variable is read.
w Invoke command whenever the variable is written.
u Invoke command whenever the variable is unset.
Variables can be unset explicitly with the unset
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.
When the trace triggers, three arguments are appended
to command so that the actual command is as follows:
command name1 name2 op
Name1 and name2 give the name(s) for the variable being
accessed: if the variable is a scalar then name1 gives
the variable's name and name2 is an empty string; if
the variable is an array element then name1 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 name1 gives the array name and
name2 is an empty string. Name1 and name2 are not
Page 1 (printed 2/19/99)
trace(n) Tcl trace(n)
necessarily the same as the name used in the trace
variable command: the upvar command allows a procedure
to reference a variable under a different name. Op
indicates what operation is being performed on the
variable, and is one of r, w, or u as defined above.
Command 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 command 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 command
invokes a procedure (which it normally does) then the
procedure will have to use upvar or uplevel if it
wishes to access the traced variable. Note also that
name1 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 upvar command.
For read and write traces, command can modify the
variable to affect the result of the traced operation.
If command 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 command 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, command 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, command will have to restore the old
value of the variable.
While command is executing during a read or write
trace, traces on the variable are temporarily disabled.
This means that reads and writes invoked by command
will occur directly, without invoking command (or any
other traces) again. However, if command unsets the
variable then unset traces will be invoked.
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
Page 2 (printed 2/19/99)
trace(n) Tcl trace(n)trace and accesses the variable, the trace will be
invoked. Any errors in unset traces are ignored.
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.
Once created, the trace remains in effect either until
the trace is removed with the trace vdelete 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.
This command returns an empty string.
trace vdelete name ops command
If there is a trace set on variable name with the
operations and command given by ops and command, then
the trace is removed, so that command will never again
be invoked. Returns an empty string.
trace vinfo name
Returns a list containing one element for each trace
currently set on variable name. Each element of the
list is itself a list containing two elements, which
are the ops and command associated with the trace. If
name doesn't exist or doesn't have any traces set, then
the result of the command will be an empty string.
KEYWORDS
read, variable, write, trace, unset
Page 3 (printed 2/19/99)
