int Tcl_TraceVar(interp, varName, flags, proc, clientData)
int Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)
Tcl_UntraceVar(interp, varName, flags, proc, clientData)
Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)
ClientData Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)
ClientData Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)
- Tcl_Interp *interp (in)
Interpreter containing variable.
- char *varName (in)
Name of variable. May refer to a scalar variable, to an array variable with no index, or to an array variable with a parenthesized index. If the name references an element of an array, then it must be in writable memory: Tcl will make temporary modifications to it while looking up the name.
- int flags (in)
OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, and TCL_GLOBAL_ONLY. Not all flags are used by all procedures. See below for more information.
- Tcl_VarTraceProc *proc (in)
Procedure to invoke whenever one of the traced operations occurs.
- ClientData clientData (in)
Arbitrary one-word value to pass to proc.
- char *name1 (in)
Name of scalar or array variable (without array index).
- char *name2 (in)
For a trace on an element of an array, gives the index of the element. For traces on scalar variables or on whole arrays, is NULL.
- ClientData prevClientData (in)
If non-NULL, gives last value returned by
Tcl_VarTraceInfo()or Tcl_VarTraceInfo2(), so this call will return information about next trace. If NULL, this call will return information about first trace.
The flags argument to
Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up at global level, ignoring any active procedures.
Invoke proc whenever an attempt is made to read the variable.
Invoke proc whenever an attempt is made to modify the variable.
Invoke proc whenever the variable is unset. A variable may be unset either explicitly by an unset command, or implicitly when a procedure returns (its local variables are automatically unset) or when the interpreter is deleted (all variables are automatically unset).
Invoke proc whenever the array command is invoked. This gives the trace procedure a chance to update the array before array names or array get is called. Note that this is called before an array set, but that will trigger write traces.
Whenever one of the specified operations occurs on the variable, proc will be invoked. It should have arguments and result that match the type Tcl_VarTraceProc:
typedef char *Tcl_VarTraceProc( ClientData clientData, Tcl_Interp *interp, char *name1, char *name2, int flags);
The clientData and interp parameters will
have the same values as those passed to
During read, write, and array traces, the
trace procedure can read, write, or unset the traced
During unset traces the variable has already been completely expunged. It is possible for the trace procedure to read or write the variable, but this will be a new version of the variable. Traces are not disabled during unset traces as they are for read and write traces, but existing traces have been removed from the variable before any trace procedures are invoked. If new traces are set by unset trace procedures, these traces will be invoked on accesses to the variable by the trace procedures.
When read tracing has been specified for a variable, the trace
procedure will be invoked whenever the variable's value is
read. This includes set Tcl commands,
in Tcl commands, and invocations of the
When write tracing has been specified for a variable, the
trace procedure will be invoked whenever the variable's value
is modified. This includes set commands,
commands that modify variables as side effects (such as
catch and scan), and calls to the
When array tracing has been specified, the trace procedure
will be invoked at the beginning of the array command implementation,
before any of the operations like get, set, or names have been invoked.
The trace procedure can modify the array elements with
When unset tracing has been specified, the trace procedure will be invoked whenever the variable is destroyed. The traces will be called after the variable has been completely unset.
If a call to
It is possible for multiple traces to exist on the same variable. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. When there exist whole-array traces for an array as well as traces on individual elements, the whole-array traces are invoked before the individual-element traces. If a read or write trace unsets the variable then all of the unset traces will be invoked but the remainder of the read and write traces will be skipped.
Under normal conditions trace procedures should return NULL, indicating successful completion. If proc returns a non-NULL value it signifies that an error occurred. The return value must be a pointer to a static character string containing an error message. If a trace procedure returns an error, no further traces are invoked for the access and the traced access aborts with the given message. Trace procedures can use this facility to make variables read-only, for example (but note that the value of the variable will already have been modified before the trace procedure is called, so the trace procedure will have to restore the correct value).
The return value from proc is only used during read and write tracing. During unset traces, the return value is ignored and all relevant trace procedures will always be invoked.
A trace procedure can be called at any time, even when there
is a partially-formed result in the interpreter's result area. If
the trace procedure does anything that could damage this result (such
It is legal to set a trace on an undefined variable. The variable will still appear to be undefined until the first time its value is set. If an undefined variable is traced and then unset, the unset will fail with an error (no such variable), but the trace procedure will still be invoked.
In an unset callback to proc, the TCL_TRACE_DESTROYED bit is set in flags if the trace is being removed as part of the deletion. Traces on a variable are always removed whenever the variable is deleted; the only time TCL_TRACE_DESTROYED isn't set is for a whole-array trace invoked when only a single element of an array is unset.
When an interpreter is destroyed, unset traces are called for all of its variables. The TCL_INTERP_DESTROYED bit will be set in the flags argument passed to the trace procedures. Trace procedures must be extremely careful in what they do if the TCL_INTERP_DESTROYED bit is set. It is not safe for the procedures to invoke any Tcl procedures on the interpreter, since its state is partially deleted. All that trace procedures should do under these circumstances is to clean up and free their own internal data structures.
Tcl doesn't do any error checking to prevent trace procedures from misusing the interpreter during traces with TCL_INTERP_DESTROYED set.
Array traces are not yet integrated with the Tcl "info exists" command, nor is there Tcl-level access to array traces.
Windows Server 2012. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019.
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
PTC MKS Toolkit 10.3 Documentation Build 39.