diff options
Diffstat (limited to 'doc/TraceCmd.3')
| -rw-r--r-- | doc/TraceCmd.3 | 31 |
1 files changed, 16 insertions, 15 deletions
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index a596cbd..3df4bc6 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -4,7 +4,7 @@ '\" 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.5 2002/07/01 18:24:39 jenglish Exp $ +'\" CVS: @(#) $Id: TraceCmd.3,v 1.6 2004/09/18 17:01:06 dkf Exp $ '\" .so man.macros .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" @@ -30,7 +30,8 @@ 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. +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 @@ -46,9 +47,9 @@ call will return information about first trace. \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 +successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. 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 +\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 @@ -80,16 +81,16 @@ data structure that describes what to do when \fIproc\fR is invoked. \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 +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 -TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is about +\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 -TCL_TRACE_DESTROYED below for more details). Lastly, the bit -TCL_INTERP_DESTROYED will be set if the entire interpreter is being +\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 TCL_INTERP_DESTROYED +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 @@ -124,7 +125,7 @@ traces for a given command that have the same \fIproc\fR. .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 +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. @@ -142,7 +143,7 @@ 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 +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 @@ -151,10 +152,10 @@ is set in \fIflags\fR. .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 +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 TCL_INTERP_DESTROYED bit is set. +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 @@ -163,7 +164,7 @@ 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 +from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR set. .SH KEYWORDS |