line endings

1 files changed, 163 insertions, 163 deletions

diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 1278269..c86dd5b 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -1,163 +1,163 @@
-'\"

-'\" 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.9 2007/10/28 14:17:40 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 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

+'\"
+'\" 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.10 2007/10/29 17:17:54 dgp 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 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