Index of Section 3 Manual Pages
| Interix / SUA | Tcl_UntraceCommand.3 | Interix / SUA |
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
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) Inter-
preter
contain-
ing the
command.
CONST char *cmdName (in) Name of
command.
int flags (in) OR-ed
collec-
tion of
the
value
TCL_TRACE_RENAME
and
TCL_TRACE_DELETE.
Tcl_CommandTraceProc *proc (in) Proce-
dure to
call
when
speci-
fied
opera-
tions
occur to
cmdName.
ClientData clientData (in) Arbi-
trary
argument
to pass
to proc.
ClientData prevClientData (in) If non-
NULL,
gives
last
value
returned
by
Tcl_Com-
mandTra-
ceInfo,
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 opera-
tions 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 speci-
fies 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 applica-
tion-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
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 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 cor-
responding 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 proce-
dure must the same as the proc argument. If the pre-
vClientData argument is NULL then the return value corre-
sponds to the first (most recently created) matching
trace, or NULL if there are no matching traces. If the
prevClientData argument isn't 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 dele-
tion 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 pro-
cedures. 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 proce-
dures 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 doesn't do any error checking to prevent trace proce-
dures from misusing the interpreter during traces with
TCL_INTERP_DESTROYED set.
KEYWORDS
clientData, trace, command
Tcl 7.4 Tcl_TraceCommand(3)