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  unde-
              fined  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
