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.  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
                     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 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  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
