NAME¶
Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand - monitor renames and
deletes of a command
SYNOPSIS¶
#include <tcl.h>
ClientData
Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)
int
Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)
void
Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)
ARGUMENTS¶
- Tcl_Interp *interp (in)
- Interpreter containing the command.
- const char *cmdName (in)
- Name of command.
- int flags (in)
- OR'ed collection of the values TCL_TRACE_RENAME and
TCL_TRACE_DELETE.
- Tcl_CommandTraceProc *proc (in)
- Procedure to call when specified operations occur to
cmdName.
- ClientData clientData (in)
- Arbitrary argument to pass to proc.
- ClientData prevClientData (in)
- If non-NULL, gives last value returned by
Tcl_CommandTraceInfo, so this call will return information about
next trace. If NULL, this call will return information about first trace.
DESCRIPTION¶
Tcl_TraceCommand allows a C procedure to monitor operations performed on
a Tcl command, so that the C procedure is invoked whenever the command is
renamed or deleted. If the trace is created successfully then
Tcl_TraceCommand returns
TCL_OK. If an error occurred (e.g.
cmdName specifies a non-existent command) then
TCL_ERROR is
returned and an error message is left in the interpreter's result.
The
flags argument to
Tcl_TraceCommand indicates when the trace
procedure is to be invoked. It consists of an OR'ed combination of any of the
following values:
- TCL_TRACE_RENAME
- Invoke proc whenever the command is renamed.
- TCL_TRACE_DELETE
- Invoke proc when the command is deleted.
Whenever one of the specified operations occurs to the command,
proc will
be invoked. It should have arguments and result that match the type
Tcl_CommandTraceProc:
typedef void Tcl_CommandTraceProc(
ClientData clientData,
Tcl_Interp * interp,
const char * oldName,
const char * newName,
int flags);
The
clientData and
interp parameters will have the same values as
those passed to
Tcl_TraceCommand when the trace was created.
ClientData typically points to an application-specific data structure
that describes what to do when
proc is invoked.
OldName gives
the name of the command being renamed, and
newName gives the name that
the command is being renamed to (or an empty string or NULL when the command
is being deleted.)
Flags is an OR'ed combination of bits potentially
providing several pieces of information. One of the bits
TCL_TRACE_RENAME and
TCL_TRACE_DELETE will be set in
flags to indicate which operation is being performed on the command.
The bit
TCL_TRACE_DESTROYED will be set in
flags if the trace is
about to be destroyed; this information may be useful to
proc so that
it can clean up its own internal data structures (see the section
TCL_TRACE_DESTROYED below for more details). Lastly, the bit
TCL_INTERP_DESTROYED will be set if the entire interpreter is being
destroyed. When this bit is set,
proc must be especially careful in the
things it does (see the section
TCL_INTERP_DESTROYED below).
Tcl_UntraceCommand may be used to remove a trace. If the command
specified by
interp,
cmdName, and
flags has a trace set
with
flags,
proc, and
clientData, then the corresponding
trace is removed. If no such trace exists, then the call to
Tcl_UntraceCommand has no effect. The same bits are valid for
flags as for calls to
Tcl_TraceCommand.
Tcl_CommandTraceInfo may be used to retrieve information about traces set
on a given command. The return value from
Tcl_CommandTraceInfo is the
clientData associated with a particular trace. The trace must be on the
command specified by the
interp,
cmdName, and
flags
arguments (note that currently the flags are ignored;
flags should be
set to 0 for future compatibility) and its trace procedure must the same as
the
proc argument. If the
prevClientData argument is NULL then
the return value corresponds to the first (most recently created) matching
trace, or NULL if there are no matching traces. If the
prevClientData
argument is not NULL, then it should be the return value from a previous call
to
Tcl_CommandTraceInfo. In this case, the new return value will
correspond to the next matching trace after the one whose
clientData
matches
prevClientData, or NULL if no trace matches
prevClientData or if there are no more matching traces after it. This
mechanism makes it possible to step through all of the traces for a given
command that have the same
proc.
CALLING COMMANDS DURING TRACES¶
During rename traces, the command being renamed is visible with both names
simultaneously, and the command still exists during delete traces (if
TCL_INTERP_DESTROYED is not set). However, there is no mechanism for
signaling that an error occurred in a trace procedure, so great care should be
taken that errors do not get silently lost.
MULTIPLE TRACES¶
It is possible for multiple traces to exist on the same command. When this
happens, all of the trace procedures will be invoked on each access, in order
from most-recently-created to least-recently-created. Attempts to delete the
command during a delete trace will fail silently, since the command is already
scheduled for deletion anyway. If the command being renamed is renamed by one
of its rename traces, that renaming takes precedence over the one that
triggered the trace and the collection of traces will not be reexecuted; if
several traces rename the command, the last renaming takes precedence.
TCL_TRACE_DESTROYED FLAG¶
In a delete callback to
proc, the
TCL_TRACE_DESTROYED bit is set
in
flags.
TCL_INTERP_DESTROYED¶
When an interpreter is destroyed, unset traces are called for all of its
commands. 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.
BUGS¶
Tcl does not do any error checking to prevent trace procedures from misusing the
interpreter during traces with
TCL_INTERP_DESTROYED set.
KEYWORDS¶
clientData, trace, command