Added documentation for command tracing API [Bug 414927]

2 files changed, 175 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 4bd1566..fc63942 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2002-04-23  Donal K. Fellows  <fellowsd@cs.man.ac.uk>
+
+	* doc/TraceCmd.3: New file that documents Tcl_CommandTraceInfo,
+	Tcl_TraceCommand and Tcl_UntraceCommand [Bug 414927]
+
 2002-04-22  Jeff Hobbs  <jeffh@ActiveState.com>
 
 	* generic/tclIOUtil.c (Tcl_FSRegister, Tcl_FSUnregister):
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
new file mode 100644
index 0000000..f39d458
--- /dev/null
+++ b/doc/TraceCmd.3
@@ -0,0 +1,170 @@
+'\"
+'\" 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.
+'\" 
+'\" CVS: @(#) $Id: TraceCmd.3,v 1.1 2002/04/23 13:09:51 dkf Exp $
+'\" 
+.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 value TCL_TRACE_RENAME and TCL_TRACE_DELETE.
+.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 TCL_OK.  If an error
+occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
+TCL_ERROR 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 TCL_TRACE_RENAME and
+TCL_TRACE_DELETE will be set in \fIflags\fR to indicate which
+operation is being performed on the command.  The bit
+TCL_TRACE_DESTROYED 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
+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, \fIproc\fR must be especially
+careful in the things it does (see the section TCL_INTERP_DESTROYED
+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
+compatability) 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 isn't 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 TCL_INTERP_DESTROYED is not set).  However, there is no
+mechanism for signalling 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 TCL_TRACE_DESTROYED 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 TCL_INTERP_DESTROYED 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 TCL_INTERP_DESTROYED 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 doesn't do any error checking to prevent trace procedures
+from misusing the interpreter during traces with TCL_INTERP_DESTROYED
+set.
+
+.SH KEYWORDS
+clientData, trace, command