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 vari-
able name is accessed in one of the ways given by
ops. Name may refer to a normal variable, an ele-
ment 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 vari-
ables 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 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 com-
mand will have access to the same local variables
as code in the procedure. This context may be dif-
ferent than the context in which the trace was cre-
ated. 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 opera-
tion. 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 opera-
tion. 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 dis-
abled. This means that reads and writes invoked by
command will occur directly, without invoking com-
mand (or any other traces) again. However, if com-
mand 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 return-
ing 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 vari-
able, 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 over-
all 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. Unset-
ting 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 ele-
ments, 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