Scroll to navigation

trace(3tcl) Tcl Built-In Commands trace(3tcl) 





NAME


trace - Monitor variable accesses, command usages and command
    executions






SYNOPSIS


trace option ?arg arg ...?








DESCRIPTION


This command causes Tcl commands to be executed whenever certain
    operations are invoked. The legal options (which may be abbreviated)
    are:



  

  
Where type is command, execution, or
    variable.







  

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



  

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

  

  
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 commandPrefix 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 command, 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
    command will not cause further trace evaluations to occur. Both
    oldName and newName are fully qualified with any namespace(s)
    in which they appear.





  

  
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:



  

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

  

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

  

  
Invoke commandPrefix for every Tcl command which is executed from
      the start of the execution of the procedure name until that
      procedure finishes. CommandPrefix is invoked just before the actual
      execution 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.

  

  
Invoke commandPrefix for every Tcl command which is executed from
      the start of the execution of the procedure name until that
      procedure finishes. CommandPrefix is invoked just after the actual
      execution 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 commandPrefix 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 execution, 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 unintuitive 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 commandPrefix, 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 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 operation.


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





  

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



  

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

  

  
Invoke commandPrefix whenever the variable is read.

  

  
Invoke commandPrefix whenever the variable is written.

  

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







  

  
Where type is either command, execution or
      variable.







  

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

  

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

  

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







  

  
Where type is either command, execution or
      variable.







  

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

  

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

  

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





  

  
This is equivalent to trace add variable name ops
    command.

  

  
This is equivalent to trace remove variable name ops
    command

  

  
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








SEE ALSO


set(3tcl), unset(3tcl)






KEYWORDS


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







  

    8.4
    Tcl