Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

trace (1t)

Name

trace - tions

Synopsis

trace option ?arg arg ...?

Description

trace(1t)                    Tcl Built-In Commands                   trace(1t)



______________________________________________________________________________

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 options (which may be abbreviated) are:

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

              trace add command name ops commandPrefix
                     Arrange for commandPrefix to be executed (with additional
                     arguments) whenever command name is modified  in  one  of
                     the  ways  given  by  the list ops. Name will be resolved
                     using the usual namespace resolution rules used  by  com-
                     mands.  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  commandPrefix  whenever the traced command
                            is renamed.   Note  that  renaming  to  the  empty
                            string  is  considered  deletion,  and will not be
                            traced with "rename".

                     delete Invoke commandPrefix when the  traced  command  is
                            deleted.  Commands  can  be  deleted explicitly by
                            using the rename command 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 interpreter in which
                            to execute them.

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

                            commandPrefix 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 commandPrefix
                     Arrange for commandPrefix to be executed (with additional
                     arguments) whenever command name is executed, with traces
                     occurring  at the points indicated by the list ops.  Name
                     will be resolved using  the  usual  namespace  resolution
                     rules  used  by commands.  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  commandPrefix whenever the command name is
                            executed, just before the actual  execution  takes
                            place.

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

                     enterstep
                            Invoke  commandPrefix  for every Tcl command which
                            is executed from the start of the execution of the
                            procedure name until that procedure finishes. Com-
                            mandPrefix is invoked just before the actual  exe-
                            cution  of  the  Tcl  command being reported 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 name that
                            does not refer to a procedure will not  result  in
                            an error and is simply ignored.

                     leavestep
                            Invoke  commandPrefix  for every Tcl command which
                            is executed from the start of the execution of the
                            procedure name until that procedure finishes. Com-
                            mandPrefix is invoked just after the actual execu-
                            tion  of  the  Tcl  command  being  reported takes
                            place.  Setting a leavestep  trace  on  a  command
                            name  that  does not refer to a procedure 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-
                     mandPrefix so that the actual command is as follows:

                     For enter and enterstep operations:

                            commandPrefix 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:

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

                     CommandPrefix executes in the same context  as  the  code
                     that  invoked  the traced operation: thus the commandPre-
                     fix, if invoked from a procedure, will have access to the
                     same  local variables as code in the procedure. This con-
                     text may be different than the context in which the trace
                     was  created. If commandPrefix invokes a procedure (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 oper-
                     ation.

                     While  commandPrefix  is  executing  during  an execution
                     trace, traces on  name  are  temporarily  disabled.  This
                     allows  the  commandPrefix  to  execute  name in its body
                     without invoking any other traces  again.   If  an  error
                     occurs  while  executing the commandPrefix, then the com-
                     mand 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 commandPrefix
                     Arrange  for  commandPrefix to be executed whenever vari-
                     able name is accessed in one of the  ways  given  by  the
                     list  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-
                     Prefix  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 vis-
                     ible 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  commandPrefix  whenever  the  variable  is
                            accessed  or  modified via the array command, pro-
                            vided 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  commandPrefix  whenever  the  variable  is
                            read.

                     write  Invoke  commandPrefix  whenever  the  variable  is
                            written.

                     unset  Invoke  commandPrefix  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
                     commandPrefix so that the actual command is as follows:

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

                     CommandPrefix  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 commandPrefix
                     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  commandPrefix
                     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, commandPrefix can modify the
                     variable to affect the result of  the  traced  operation.
                     If  commandPrefix 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  commandPrefix is ignored  except  that
                     if it returns an error of any sort then the traced opera-
                     tion 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,  commandPrefix  is invoked after the vari-
                     able's value has been changed; it can write a  new  value
                     into  the  variable to override the original value speci-
                     fied in the  write  operation.   To  implement  read-only
                     variables,  commandPrefix  will  have  to restore the old
                     value of the variable.

                     While commandPrefix is executing during a read  or  write
                     trace,  traces  on the variable are temporarily disabled.
                     This means that reads and writes invoked by commandPrefix
                     will  occur  directly, without invoking commandPrefix (or
                     any  other  traces)  again.   However,  if  commandPrefix
                     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 commandPrefix
              Where type is either command, execution or variable.

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

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

              trace remove variable name opList commandPrefix
                     If  there is a trace set on variable name with the opera-
                     tions and command given by opList and commandPrefix, then
                     the  trace  is  removed, so that commandPrefix 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  commandPrefix associated with the trace.  If
                     name does not have any traces set, then the result of the
                     command will be an empty string.  If name does not 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  commandPrefix associated with the trace.  If
                     name does not have any traces set, then the result of the
                     command will be an empty string.  If name does not 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  commandPrefix associated with the trace.  If
                     name does not exist or does not 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

       Print a trace of what commands are executed during the processing of  a
       Tcl procedure:

              proc x {} { y }
              proc y {} { z }
              proc z {} { puts hello }
              proc report args {puts [info level 0]}
              trace add execution x enterstep report
              x
                -> report y enterstep
                  report z enterstep
                  report {puts hello} enterstep
                  hello


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tcl-8    |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       set(n), unset(n)

KEYWORDS
       read, command, rename, variable, write, trace, unset



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-
       core8.6.7-src.tar.gz

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tcl                                   8.4                            trace(1t)