162 lines
7.1 KiB
Groff
162 lines
7.1 KiB
Groff
'\"
|
|
'\" Copyright (c) 2002 Donal K. Fellows
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
ClientData
|
|
\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
|
|
.sp
|
|
int
|
|
\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
|
|
.sp
|
|
void
|
|
\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
|
|
.SH ARGUMENTS
|
|
.AS Tcl_CommandTraceProc prevClientData
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter containing the command.
|
|
.AP "const char" *cmdName in
|
|
Name of command.
|
|
.AP int flags in
|
|
OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
|
|
\fBTCL_TRACE_DELETE\fR.
|
|
.AP Tcl_CommandTraceProc *proc in
|
|
Procedure to call when specified operations occur to \fIcmdName\fR.
|
|
.AP ClientData clientData in
|
|
Arbitrary argument to pass to \fIproc\fR.
|
|
.AP ClientData prevClientData in
|
|
If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
|
|
so this call will return information about next trace. If NULL, this
|
|
call will return information about first trace.
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTcl_TraceCommand\fR 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 \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
|
|
occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
|
|
\fBTCL_ERROR\fR is returned and an error message is left in the
|
|
interpreter's result.
|
|
.PP
|
|
The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
|
|
trace procedure is to be invoked. It consists of an OR'ed combination
|
|
of any of the following values:
|
|
.TP
|
|
\fBTCL_TRACE_RENAME\fR
|
|
Invoke \fIproc\fR whenever the command is renamed.
|
|
.TP
|
|
\fBTCL_TRACE_DELETE\fR
|
|
Invoke \fIproc\fR when the command is deleted.
|
|
.PP
|
|
Whenever one of the specified operations occurs to the command,
|
|
\fIproc\fR will be invoked. It should have arguments and result that
|
|
match the type \fBTcl_CommandTraceProc\fR:
|
|
.CS
|
|
typedef void Tcl_CommandTraceProc(
|
|
ClientData \fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
const char *\fIoldName\fR,
|
|
const char *\fInewName\fR,
|
|
int \fIflags\fR);
|
|
.CE
|
|
The \fIclientData\fR and \fIinterp\fR parameters will have the same
|
|
values as those passed to \fBTcl_TraceCommand\fR when the trace was
|
|
created. \fIClientData\fR typically points to an application-specific
|
|
data structure that describes what to do when \fIproc\fR is invoked.
|
|
\fIOldName\fR gives the name of the command being renamed, and
|
|
\fInewName\fR gives the name that the command is being renamed to (or
|
|
an empty string or NULL when the command is being deleted.)
|
|
\fIFlags\fR is an OR'ed combination of bits potentially providing
|
|
several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and
|
|
\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
|
|
operation is being performed on the command. The bit
|
|
\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
|
|
to be destroyed; this information may be useful to \fIproc\fR so that
|
|
it can clean up its own internal data structures (see the section
|
|
\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit
|
|
\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being
|
|
destroyed. When this bit is set, \fIproc\fR must be especially
|
|
careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR
|
|
below).
|
|
.PP
|
|
\fBTcl_UntraceCommand\fR may be used to remove a trace. If the
|
|
command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
|
|
a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then
|
|
the corresponding trace is removed. If no such trace exists, then the
|
|
call to \fBTcl_UntraceCommand\fR has no effect. The same bits are
|
|
valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR.
|
|
.PP
|
|
\fBTcl_CommandTraceInfo\fR may be used to retrieve information about
|
|
traces set on a given command.
|
|
The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR
|
|
associated with a particular trace.
|
|
The trace must be on the command specified by the \fIinterp\fR,
|
|
\fIcmdName\fR, and \fIflags\fR arguments (note that currently the
|
|
flags are ignored; \fIflags\fR should be set to 0 for future
|
|
compatibility) and its trace procedure must the same as the \fIproc\fR
|
|
argument.
|
|
If the \fIprevClientData\fR 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 \fIprevClientData\fR argument is not NULL, then it should
|
|
be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
|
|
In this case, the new return value will correspond to the next
|
|
matching trace after the one whose \fIclientData\fR matches
|
|
\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
|
|
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 \fIproc\fR.
|
|
.SH "CALLING COMMANDS DURING TRACES"
|
|
.PP
|
|
During rename traces, the command being renamed is visible with both
|
|
names simultaneously, and the command still exists during delete
|
|
traces (if \fBTCL_INTERP_DESTROYED\fR 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.
|
|
.SH "MULTIPLE TRACES"
|
|
.PP
|
|
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.
|
|
.SH "TCL_TRACE_DESTROYED FLAG"
|
|
.PP
|
|
In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
|
|
is set in \fIflags\fR.
|
|
.\" Perhaps need some more comments here? - DKF
|
|
.SH "TCL_INTERP_DESTROYED"
|
|
.PP
|
|
When an interpreter is destroyed, unset traces are called for
|
|
all of its commands.
|
|
The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
|
|
argument passed to the trace procedures.
|
|
Trace procedures must be extremely careful in what they do if
|
|
the \fBTCL_INTERP_DESTROYED\fR 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.
|
|
.SH BUGS
|
|
.PP
|
|
Tcl does not do any error checking to prevent trace procedures
|
|
from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
|
|
set.
|
|
.SH KEYWORDS
|
|
clientData, trace, command
|