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.  If the variable does
              not exist, it will be created but will not be given
              a  value,  so it will be visible to namespace which
              queries, but not to info exists queries.

              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
