Tcl_TraceCommand(3)
Tcl_TraceCommand(3) Tcl Library Procedures Tcl_TraceCommand(3)
_________________________________________________________________
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 com-
mand.
const char *cmdName (in) Name of
command.
int flags (in) OR'ed col-
lection 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
Tcl Last change: 7.4 1
Tcl_TraceCommand(3) Tcl Library Procedures Tcl_TraceCommand(3)
by
Tcl_CommandTraceInfo,
so this
call will
return
informa-
tion about
next
trace. If
NULL, this
call will
return
informa-
tion 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 com-
mand, 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 com-
mand being renamed, and newName gives the name that the
Tcl Last change: 7.4 2
Tcl_TraceCommand(3) Tcl Library Procedures Tcl_TraceCommand(3)
command is being renamed to (or an empty string or NULL when
the command is being deleted.) Flags is an OR'ed combina-
tion of bits potentially providing several pieces of infor-
mation. 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 struc-
tures (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 speci-
fied 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 match-
ing 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
Tcl Last change: 7.4 3
Tcl_TraceCommand(3) Tcl Library Procedures Tcl_TraceCommand(3)
It is possible for multiple traces to exist on the same com-
mand. 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 inter-
preter, 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 pro-
cedures from misusing the interpreter during traces with
TCL_INTERP_DESTROYED set.
KEYWORDS
clientData, trace, command
Tcl Last change: 7.4 4
Man(1) output converted with
man2html