NAME
       trace  -  Monitor  variable accesses, command usages and command execu-
       tions

SYNOPSIS
       trace option ?arg arg ...?


DESCRIPTION
       This command causes Tcl commands to be executed whenever certain opera-
       tions are invoked.  The legal option's (which may be abbreviated) are:

       trace add type name ops ?args?
              Where type is command, execution, or variable.

              trace add command name ops command
                     Arrange  for command to be executed whenever command name
                     is modified in one of the ways given  by  the  list  ops.
                     Name  will  be resolved using the usual namespace resolu-
                     tion rules used by procedures.  If the command  does  not
                     exist, an error will be thrown.

                     Ops  indicates which operations are of interest, and is a
                     list of one or more of the following items:

                     rename Invoke command whenever the  command  is  renamed.
                            Note  that renaming to the empty string is consid-
                            ered  deletion,  and  will  not  be  traced   with
                            'rename'.

                     delete Invoke  command when the command is deleted.  Com-
                            mands can  be  deleted  explicitly  by  using  the
                            rename  command  to rename the command to an empty
                            string.  Commands are also deleted when the inter-
                            preter  is deleted, but traces will not be invoked
                            because there is no interpreter in which  to  exe-
                            cute them.

                     When  the  trace  triggers,  depending  on the operations
                     being traced, a number of arguments are appended to  com-
                     mand so that the actual command is as follows:
                            command oldName newName op
                     OldName  and  newName  give  the traced command's current
                     (old) name, and the name to which  it  is  being  renamed
                     (the  empty  string if this is a 'delete' operation).  Op
                     indicates what operation is being performed on  the  com-
                     mand,  and  is  one of rename or delete as defined above.
                     The trace operation cannot be used to stop a command from
                     being  deleted.   Tcl will always remove the command once
                     the trace is complete.  Recursive  renaming  or  deleting
                     will  not  cause  further  traces  of the same type to be
                     evaluated, so a delete trace  which  itself  deletes  the
                     command,  or a rename trace which itself renames the com-
                     mand will not cause further trace evaluations  to  occur.
                     Both  oldName  and  newName  are fully qualified with any
                     namespace(s) in which they appear.

              trace add execution name ops command
                     Arrange for command to be executed whenever command  name
                     is  executed,  with  traces occurring at the points indi-
                     cated by the list ops.  Name will be resolved  using  the
                     usual  namespace resolution rules used by procedures.  If
                     the command does not exist, an error will be thrown.

                     Ops indicates which operations are of interest, and is  a
                     list of one or more of the following items:

                     enter  Invoke  command  whenever the command name is exe-
                            cuted, just  before  the  actual  execution  takes
                            place.

                     leave  Invoke  command  whenever the command name is exe-
                            cuted,  just  after  the  actual  execution  takes
                            place.

                     enterstep
                            Invoke command for every Tcl command which is exe-
                            cuted inside the procedure name, just  before  the
                            actual  execution  takes place.  For example if we
                            have 'proc foo {}  {  puts  "hello"  }',  then  an
                            enterstep  trace would be invoked just before puts
                            "hello" is executed.  Setting an  enterstep  trace
                            on  a  command  will not result in an error and is
                            simply ignored.

                     leavestep
                            Invoke command for every Tcl command which is exe-
                            cuted  inside  the  procedure name, just after the
                            actual execution takes place.  Setting a leavestep
                            trace on a command will not result in an error and
                            is simply ignored.

                     When the trace  triggers,  depending  on  the  operations
                     being  traced, a number of arguments are appended to com-
                     mand so that the actual command is as follows:

                     For enter and enterstep operations:
                            command command-string op
                     Command-string gives the complete current  command  being
                     executed  (the  traced  command for a enter operation, an
                     arbitrary command for a enterstep  operation),  including
                     all arguments in their fully expanded form.  Op indicates
                     what operation is being performed on the  command  execu-
                     tion,  and is one of enter or enterstep as defined above.
                     The trace operation can be used to stop the command  from
                     executing,  by  deleting  the  command  in  question.  Of
                     course when the  command  is  subsequently  executed,  an
                     'invalid command' error will occur.

                     For leave and leavestep operations:
                            command command-string code result op
                     Command-string  gives  the complete current command being
                     executed (the traced command for a  enter  operation,  an
                     arbitrary  command  for a enterstep operation), including
                     all arguments in their fully expanded form.   Code  gives
                     the  result code of that execution, and result the result
                     string.  Op indicates what operation is  being  performed
                     on  the  command  execution,  and  is  one  of  leave  or
                     leavestep as defined above.  Note that  the  creation  of
                     many  enterstep  or  leavestep traces can lead to unintu-
                     itive results, since the invoked commands from one  trace
                     can  themselves  lead  to further command invocations for
                     other traces.

                     Command executes in the same context  as  the  code  that
                     invoked  the  traced  operation:  thus  the  command,  if
                     invoked from a procedure, 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 nor-
                     mally does) then the procedure will have to use upvar  or
                     uplevel  commands  if it wishes to access the local vari-
                     ables of the code which invoked the trace operation.

                     While command is executing  during  an  execution  trace,
                     traces  on name are temporarily disabled. This allows the
                     command to execute name in its body without invoking  any
                     other  traces  again.  If an error occurs while executing
                     the command body, then the command name as a  whole  will
                     return that same error.

                     When  multiple traces are set on name, then for enter and
                     enterstep operations, the traced commands are invoked  in
                     the  reverse order of how the traces were originally cre-
                     ated; and for leave and leavestep operations, the  traced
                     commands are invoked in the original order of creation.

                     The  behavior  of execution traces is currently undefined
                     for a command name imported into another namespace.

              trace add variable name ops command
                     Arrange for command to be executed whenever variable name
                     is  accessed  in  one  of the ways given by the list 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 is a
                     list of one or more of the following items:

                     array  Invoke command whenever the variable  is  accessed
                            or  modified  via the array command, provided that
                            name is not a scalar variable at the time that the
                            array  command  is  invoked.   If name is a scalar
                            variable, the access via the  array  command  will
                            not trigger the trace.

                     read   Invoke command whenever the variable is read.

                     write  Invoke command whenever the variable is written.

                     unset  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 regis-
                     tered 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 read, write,  or
                     unset 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 con-
                     text 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 neces-
                     sarily 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  vari-
                     able  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  vari-
                     ables,  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 remove variable com-
                     mand 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 remove type name opList command
              Where type is either command, execution or variable.

              trace remove command name opList command
                     If  there  is a trace set on command name with the opera-
                     tions and command given by opList and command,  then  the
                     trace  is  removed,  so  that command will never again be
                     invoked.  Returns an  empty  string.    If  name  doesn't
                     exist, the command will throw an error.

              trace remove execution name opList command
                     If  there  is a trace set on command name with the opera-
                     tions and command given by opList and command,  then  the
                     trace  is  removed,  so  that command will never again be
                     invoked.  Returns an  empty  string.    If  name  doesn't
                     exist, the command will throw an error.

              trace remove variable name opList command
                     If  there is a trace set on variable name with the opera-
                     tions and command given by opList and command,  then  the
                     trace  is  removed,  so  that command will never again be
                     invoked.  Returns an empty string.

       trace info type name
              Where type is either command, execution or variable.

              trace info command name
                     Returns a list containing one element for each trace cur-
                     rently  set  on command name. Each element of the list is
                     itself a list containing  two  elements,  which  are  the
                     opList  and  command  associated with the trace.  If name
                     doesn't have any traces set, then the result of the  com-
                     mand will be an empty string.  If name doesn't exist, the
                     command will throw an error.

              trace info execution name
                     Returns a list containing one element for each trace cur-
                     rently  set  on command name. Each element of the list is
                     itself a list containing  two  elements,  which  are  the
                     opList  and  command  associated with the trace.  If name
                     doesn't have any traces set, then the result of the  com-
                     mand will be an empty string.  If name doesn't exist, the
                     command will throw an error.

              trace info variable name
                     Returns a list containing one element for each trace cur-
                     rently set on variable name.  Each element of the list is
                     itself a list containing  two  elements,  which  are  the
                     opList  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.

       For backwards compatibility, three other subcommands are available:

              trace variable name ops command
                     This  is  equivalent  to trace add variable name ops com-
                     mand.

              trace vdelete name ops command
                     This is equivalent to trace remove variable name ops com-
                     mand

              trace vinfo name
                     This is equivalent to trace info variable name

       These subcommands are deprecated and will likely be removed in a future
       version of Tcl.  They use an older syntax in which array, read,  write,
       unset  are replaced by a, r, w and u respectively, and the ops argument
       is not a list, but simply a string  concatenation  of  the  operations,
       such as rwua.

EXAMPLES
       Print a message whenever either of the global variables foo and bar are
       updated, even if they have a different local name at  the  time  (which
       can be done with the upvar command):
              proc tracer {varname args} {
                  upvar #0 $varname var
                  puts "$varname was updated to be \"$var\""
              }
              trace add variable foo write "tracer foo"
              trace add variable bar write "tracer bar"

       Ensure  that  the global variable foobar always contains the product of
       the global variables foo and bar:
              proc doMult args {
                  global foo bar foobar
                  set foobar [expr {$foo * $bar}]
              }
              trace add variable foo write doMult
              trace add variable bar write doMult


SEE ALSO
       set(n), unset(n)


KEYWORDS
