diff options
Diffstat (limited to 'tcl8.6/doc/TraceCmd.3')
-rw-r--r-- | tcl8.6/doc/TraceCmd.3 | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/tcl8.6/doc/TraceCmd.3 b/tcl8.6/doc/TraceCmd.3 new file mode 100644 index 0000000..99914a6 --- /dev/null +++ b/tcl8.6/doc/TraceCmd.3 @@ -0,0 +1,150 @@ +'\" +'\" 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. +'\" +.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" +.so man.macros +.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: +.PP +.CS +typedef void \fBTcl_CommandTraceProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + const char *\fIoldName\fR, + const char *\fInewName\fR, + int \fIflags\fR); +.CE +.PP +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 +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). Because the +deletion of commands can take place as part of the deletion of the interp +that contains them, \fIproc\fR must be careful about checking what +the passed in \fIinterp\fR value can be called upon to do. +The routine \fBTcl_InterpDeleted\fR is an important tool for this. +When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able +to invoke any scripts in \fIinterp\fR. The function of \fIproc\fR +in that circumstance is limited to the cleanup of its own data structures. +.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, 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. +.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 KEYWORDS +clientData, trace, command |