1mNAME0m
       trace  -  Monitor  variable accesses, command usages and command execu-
       tions

1mSYNOPSIS0m
       1mtrace 4m22moption24m ?4marg24m 4marg24m 4m...24m?


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

       1mtrace add 4m22mtype24m 4mname24m 4mops24m 4m?args?0m
              Where 4mtype24m is 1mcommand22m, 1mexecution22m, or 1mvariable22m.

              1mtrace add command 4m22mname24m 4mops24m 4mcommand0m
                     Arrange  for 4mcommand24m to be executed whenever command 4mname0m
                     is modified in one of the ways given  by  the  list  4mops24m.
                     4mName24m  will  be resolved using the usual namespace resolu-
                     tion rules used by procedures.  If the command  does  not
                     exist, an error will be thrown.

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

                     1mrename 22mInvoke 4mcommand24m whenever the  command  is  renamed.
                            Note  that renaming to the empty string is consid-
                            ered  deletion,  and  will  not  be  traced   with
                            '1mrename22m'.

                     1mdelete 22mInvoke  4mcommand24m when the command is deleted.  Com-
                            mands can  be  deleted  explicitly  by  using  the
                            1mrename  22mcommand  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  4mcom-0m
                     4mmand24m so that the actual command is as follows:
                            4mcommand24m 4moldName24m 4mnewName24m 4mop0m
                     4mOldName24m  and  4mnewName24m  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).  4mOp0m
                     indicates what operation is being performed on  the  com-
                     mand,  and  is  one of 1mrename 22mor 1mdelete 22mas 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  4moldName24m  and  4mnewName24m  are fully qualified with any
                     namespace(s) in which they appear.

              1mtrace add execution 4m22mname24m 4mops24m 4mcommand0m
                     Arrange for 4mcommand24m to be executed whenever command  4mname0m
                     is  executed,  with  traces occurring at the points indi-
                     cated by the list 4mops24m.  4mName24m will be resolved  using  the
                     usual  namespace resolution rules used by procedures.  If
                     the command does not exist, an error will be thrown.

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

                     1menter  22mInvoke  4mcommand24m  whenever the command 4mname24m is exe-
                            cuted, just  before  the  actual  execution  takes
                            place.

                     1mleave  22mInvoke  4mcommand24m  whenever the command 4mname24m is exe-
                            cuted,  just  after  the  actual  execution  takes
                            place.

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

                     1mleavestep0m
                            Invoke 4mcommand24m for every Tcl command which is exe-
                            cuted  inside  the  procedure 4mname24m, just after the
                            actual execution takes place.  Setting a 4mleavestep0m
                            trace on a 4mcommand24m 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 4mcom-0m
                     4mmand24m so that the actual command is as follows:

                     For 1menter 22mand 1menterstep 22moperations:
                            4mcommand24m 4mcommand-string24m 4mop0m
                     4mCommand-string24m gives the complete current  command  being
                     executed  (the  traced  command for a 1menter 22moperation, an
                     arbitrary command for a 1menterstep  22moperation),  including
                     all arguments in their fully expanded form.  4mOp24m indicates
                     what operation is being performed on the  command  execu-
                     tion,  and is one of 1menter 22mor 1menterstep 22mas 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 1mleave 22mand 1mleavestep 22moperations:
                            4mcommand24m 4mcommand-string24m 4mcode24m 4mresult24m 4mop0m
                     4mCommand-string24m  gives  the complete current command being
                     executed (the traced command for a  1menter  22moperation,  an
                     arbitrary  command  for a 1menterstep 22moperation), including
                     all arguments in their fully expanded form.   4mCode24m  gives
                     the  result code of that execution, and 4mresult24m the result
                     string.  4mOp24m indicates what operation is  being  performed
                     on  the  command  execution,  and  is  one  of  1mleave  22mor
                     1mleavestep 22mas defined above.  Note that  the  creation  of
                     many  1menterstep  22mor  1mleavestep 22mtraces can lead to unintu-
                     itive results, since the invoked commands from one  trace
                     can  themselves  lead  to further command invocations for
                     other traces.

                     4mCommand24m executes in the same context  as  the  code  that
                     invoked  the  traced  operation:  thus  the  4mcommand24m,  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  4mcommand24m  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 4mcommand24m is executing  during  an  execution  trace,
                     traces  on 4mname24m are temporarily disabled. This allows the
                     4mcommand24m to execute 4mname24m in its body without invoking  any
                     other  traces  again.  If an error occurs while executing
                     the 4mcommand24m body, then the command 4mname24m as a  whole  will
                     return that same error.

                     When  multiple traces are set on 4mname24m, then for 4menter24m and
                     4menterstep24m operations, the traced commands are invoked  in
                     the  reverse order of how the traces were originally cre-
                     ated; and for 4mleave24m and 4mleavestep24m operations, the  traced
                     commands are invoked in the original order of creation.

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

              1mtrace add variable 4m22mname24m 4mops24m 4mcommand0m
                     Arrange for 4mcommand24m to be executed whenever variable 4mname0m
                     is  accessed  in  one  of the ways given by the list 4mops24m.
                     4mName24m may refer to a normal variable,  an  element  of  an
                     array,  or  to an array as a whole (i.e. 4mname24m may be just
                     the name of an array, with no parenthesized  index).   If
                     4mname24m  refers  to  a  whole array, then 4mcommand24m 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  1mnamespace0m
                     1mwhich 22mqueries, but not to 1minfo exists 22mqueries.

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

                     1marray  22mInvoke 4mcommand24m whenever the variable  is  accessed
                            or  modified  via the 1marray 22mcommand, provided that
                            4mname24m is not a scalar variable at the time that the
                            1marray  22mcommand  is  invoked.   If 4mname24m is a scalar
                            variable, the access via the  1marray  22mcommand  will
                            not trigger the trace.

                     1mread   22mInvoke 4mcommand24m whenever the variable is read.

                     1mwrite  22mInvoke 4mcommand24m whenever the variable is written.

                     1munset  22mInvoke  4mcommand24m  whenever  the  variable is unset.
                            Variables can be unset explicitly with  the  1munset0m
                            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
                     4mcommand24m so that the actual command is as follows:
                            4mcommand24m 4mname124m 4mname224m 4mop0m
                     4mName124m and 4mname224m give the name(s) for the  variable  being
                     accessed:   if  the variable is a scalar then 4mname124m gives
                     the variable's name and 4mname224m is an empty string; if  the
                     variable is an array element then 4mname124m 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  4mname124m  gives  the  array name and 4mname224m is an empty
                     string.  4mName124m and 4mname224m are not necessarily the same  as
                     the  name  used in the 1mtrace variable 22mcommand:  the 1mupvar0m
                     command allows a procedure to reference a variable  under
                     a  different  name.  4mOp24m indicates what operation is being
                     performed on the variable, and is one of 1mread22m, 1mwrite22m,  or
                     1munset 22mas defined above.

                     4mCommand24m  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 4mcommand24m 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 4mcommand24m invokes a
                     procedure  (which  it  normally  does) then the procedure
                     will have to use 1mupvar 22mor 1muplevel 22mif it wishes to  access
                     the traced variable.  Note also that 4mname124m 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 1mupvar 22mcommand.

                     For read and write traces, 4mcommand24m can modify  the  vari-
                     able  to  affect  the result of the traced operation.  If
                     4mcommand24m 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
                     4mcommand24m  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,  4mcommand24m  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,  4mcommand24m  will  have  to
                     restore the old value of the variable.

                     While 4mcommand24m is executing during a read or write  trace,
                     traces  on  the  variable are temporarily disabled.  This
                     means that reads and writes invoked by 4mcommand24m will occur
                     directly,  without invoking 4mcommand24m (or any other traces)
                     again.  However, if  4mcommand24m  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 1mtrace remove variable 22mcom-
                     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.

       1mtrace remove 4m22mtype24m 4mname24m 4mopList24m 4mcommand0m
              Where 4mtype24m is either 1mcommand22m, 1mexecution 22mor 1mvariable22m.

              1mtrace remove command 4m22mname24m 4mopList24m 4mcommand0m
                     If  there  is a trace set on command 4mname24m with the opera-
                     tions and command given by 4mopList24m and 4mcommand24m,  then  the
                     trace  is  removed,  so  that 4mcommand24m will never again be
                     invoked.  Returns an  empty  string.    If  4mname24m  doesn't
                     exist, the command will throw an error.

              1mtrace remove execution 4m22mname24m 4mopList24m 4mcommand0m
                     If  there  is a trace set on command 4mname24m with the opera-
                     tions and command given by 4mopList24m and 4mcommand24m,  then  the
                     trace  is  removed,  so  that 4mcommand24m will never again be
                     invoked.  Returns an  empty  string.    If  4mname24m  doesn't
                     exist, the command will throw an error.

              1mtrace remove variable 4m22mname24m 4mopList24m 4mcommand0m
                     If  there is a trace set on variable 4mname24m with the opera-
                     tions and command given by 4mopList24m and 4mcommand24m,  then  the
                     trace  is  removed,  so  that 4mcommand24m will never again be
                     invoked.  Returns an empty string.

       1mtrace info 4m22mtype24m 4mname0m
              Where 4mtype24m is either 1mcommand22m, 1mexecution 22mor 1mvariable22m.

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

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

              1mtrace info variable 4m22mname0m
                     Returns a list containing one element for each trace cur-
                     rently set on variable 4mname24m.  Each element of the list is
                     itself a list containing  two  elements,  which  are  the
                     4mopList24m  and  4mcommand24m  associated with the trace.  If 4mname0m
                     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:

              1mtrace variable 4m22mname24m 4mops24m 4mcommand0m
                     This  is  equivalent  to 1mtrace add variable 4m22mname24m 4mops24m 4mcom-0m
                     4mmand24m.

              1mtrace vdelete 4m22mname24m 4mops24m 4mcommand0m
                     This is equivalent to 1mtrace remove variable 4m22mname24m 4mops24m 4mcom-0m
                     4mmand0m

              1mtrace vinfo 4m22mname0m
                     This is equivalent to 1mtrace info variable 4m22mname0m

       These subcommands are deprecated and will likely be removed in a future
       version of Tcl.  They use an older syntax in which 1marray22m, 1mread22m,  1mwrite22m,
       1munset  22mare replaced by 1ma22m, 1mr22m, 1mw 22mand 1mu 22mrespectively, and the 4mops24m argument
       is not a list, but simply a string  concatenation  of  the  operations,
       such as 1mrwua22m.

1mEXAMPLES0m
       Print a message whenever either of the global variables 1mfoo 22mand 1mbar 22mare
       updated, even if they have a different local name at  the  time  (which
       can be done with the 1mupvar 22mcommand):
              proc tracer {varname args} {
                  upvar #0 $varname var
                  puts "$varname was updated to be \"$var\""
              }
              1mtrace add 22mvariable foo write "tracer foo"
              1mtrace add 22mvariable bar write "tracer bar"

       Ensure  that  the global variable 1mfoobar 22malways contains the product of
       the global variables 1mfoo 22mand 1mbar22m:
              proc doMult args {
                  global foo bar foobar
                  set foobar [expr {$foo * $bar}]
              }
              1mtrace add 22mvariable foo write doMult
              1mtrace add 22mvariable bar write doMult


1mSEE ALSO0m
       set(n), unset(n)


1mKEYWORDS0m
