Tcl_CommandTraceInfo - monitor renames and deletes of a command
#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)
Tcl_TraceCommand(3tcl) Tcl Library Procedures Tcl_TraceCommand(3tcl)
______________________________________________________________________________
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 contain-
ing 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 opera-
tions occur to cmd-
Name.
ClientData clientData (in) Arbitrary argument to
pass to proc.
ClientData prevClientData (in) If non-NULL, gives
last value returned
by Tcl_CommandTrace-
Info, so this call
will return informa-
tion 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 com-
mand 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 proce-
dure 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 typ-
ically 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 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 sec-
tion TCL_TRACE_DESTROYED below for more details). Because the deletion
of commands can take place as part of the deletion of the interp that
contains them, proc must be careful about checking what the passed in
interp value can be called upon to do. The routine Tcl_InterpDeleted
is an important tool for this. When Tcl_InterpDeleted returns 1, proc
will not be able to invoke any scripts in interp. The function of proc
in that circumstance is limited to the cleanup of its own data struc-
tures.
Tcl_UntraceCommand may be used to remove a trace. If the command spec-
ified 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 argu-
ment 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, unless the interp that contains it is being deleted. 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.
KEYWORDS
clientData, trace, command
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tcl-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/tcl/tcl-
core8.6.7-src.tar.gz.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tcl 7.4 Tcl_TraceCommand(3tcl)