NAME
       trace - Monitor variable accesses, command usages and com-
       mand executions

SYNOPSIS
       trace option ?arg arg ...?


DESCRIPTION
       This command causes Tcl commands to be  executed  whenever
       certain operations 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  com-
                     mand  does  not  exist,  an  error  will  be
                     thrown.

                     Ops indicates which operations are of inter-
                     est,  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 considered dele-
                             tion,  and  will  not be traced with
                             'rename'.

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

                     When the trace triggers,  depending  on  the
                     operations  being  traced, a number of argu-
                     ments are appended to command  so  that  the
                     actual command is as follows:
                             command oldName newName op
                     OldName  and  newName  give  the traced com-
                     mand's current (old) name, and the  name  to
                     which  it is being renamed (the empty string
                     if this is a 'delete' operation).  Op  indi-
                     cates  what  operation is being performed on
                     the command, and is one of rename or  delete
                     as  defined above.  The trace operation can-
                     not 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 com-
                     mand, or a rename trace which itself renames
                     the  command  will  not  cause further trace
                     evaluations to occur.

              trace add execution 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  com-
                     mand  does  not  exist,  an  error  will  be
                     thrown.

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

                      enter  Invoke command whenever the  command
                             name  is  executed,  just before the
                             actual execution takes place.

                      leave  Invoke command whenever the  command
                             name  is  executed,  just  after the
                             actual execution takes place.

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

                     leavestep
                             Invoke command for every tcl command
                             which  is executed inside the proce-
                             dure 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 argu-
                     ments are appended to command  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  execution,  and  is one of
                     enter or enterstep as  defined  above.   The
                     trace operation can be used to stop the com-
                     mand 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  execu-
                     tion,  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  unintuitive
                     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 pro-
                     cedure (which it  normally  does)  then  the
                     procedure  will have to use upvar or uplevel
                     commands if it wishes to  access  the  local
                     variables  of  the  code  which  invoked the
                     trace operation.

                     While command is executing during an  execu-
                     tion  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 exe-
                     cuting  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 opera-
                     tions, the traced commands  are  invoked  in
                     the original order of creation.

                     The  behavior  of  execution  traces is cur-
                     rently 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 parenthe-
                     sized  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 inter-
                     est, 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  com-
                     mand 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 ref-
                     erence  a  variable  under a different name.
                     Op indicates what operation  is  being  per-
                     formed  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 pro-
                     cedure.   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 mod-
                     ify 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 tem-
                     porarily  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 dis-
                     abled 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 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  remove  variable  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 remove type name opList command
              Where  type  is  either command, execution or vari-
              able.

              trace remove command name opList command
                     If there is a trace set on command name with
                     the  operations  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 operations 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  operations  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  vari-
              able.

              trace info command name
                     Returns  a  list  containing one element for
                     each trace currently 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 command 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 currently 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 command 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 currently 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 command.

              trace vdelete name ops command
                     This is equivalent to trace remove  variable
                     name ops command

              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.


SEE ALSO
       set(n), unset(n)


KEYWORDS
