通讯编程

开发平台：
Visual C++

TraceCmd.3：源码内容
							'"
'" 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.5 2002/07/01 18:24:39 jenglish 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, prevClientDatafB)fR
.sp
int
fBTcl_TraceCommand(fIinterp, cmdName, flags, proc, clientDatafB)fR
.sp
void
fBTcl_UntraceCommand(fIinterp, cmdName, flags, proc, clientDatafB)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 fIcmdNamefR.
.AP ClientData clientData in
Arbitrary argument to pass to fIprocfR.
.AP ClientData prevClientData in
If non-NULL, gives last value returned by fBTcl_CommandTraceInfofR,
so this call will return information about next trace.  If NULL, this
call will return information about first trace.
.BE
.SH DESCRIPTION
.PP
fBTcl_TraceCommandfR 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_TraceCommandfR returns TCL_OK.  If an error
occurred (e.g. fIcmdNamefR specifies a non-existent command) then
TCL_ERROR is returned and an error message is left in the
interpreter's result.
.PP
The fIflagsfR argument to fBTcl_TraceCommandfR 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_RENAMEfR
Invoke fIprocfR whenever the command is renamed.
.TP
fBTCL_TRACE_DELETEfR
Invoke fIprocfR when the command is deleted.
.PP
Whenever one of the specified operations occurs to the command,
fIprocfR will be invoked.  It should have arguments and result that
match the type fBTcl_CommandTraceProcfR:
.CS
typedef void Tcl_CommandTraceProc(
	ClientData fIclientDatafR,
        Tcl_Interp *fIinterpfR,
	CONST char *fIoldNamefR,
	CONST char *fInewNamefR,
        int fIflagsfR);
.CE
The fIclientDatafR and fIinterpfR parameters will have the same
values as those passed to fBTcl_TraceCommandfR when the trace was
created.  fIClientDatafR typically points to an application-specific
data structure that describes what to do when fIprocfR is invoked.
fIOldNamefR gives the name of the command being renamed, and
fInewNamefR gives the name that the command is being renamed to (or
an empty string or NULL when the command is being deleted.)
fIFlagsfR 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 fIflagsfR to indicate which
operation is being performed on the command.  The bit
TCL_TRACE_DESTROYED will be set in fIflagsfR if the trace is about
to be destroyed; this information may be useful to fIprocfR 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, fIprocfR must be especially
careful in the things it does (see the section TCL_INTERP_DESTROYED
below).
.PP
fBTcl_UntraceCommandfR may be used to remove a trace.  If the
command specified by fIinterpfR, fIcmdNamefR, and fIflagsfR has
a trace set with fIflagsfR, fIprocfR, and fIclientDatafR, then
the corresponding trace is removed.  If no such trace exists, then the
call to fBTcl_UntraceCommandfR has no effect.  The same bits are
valid for fIflagsfR as for calls to fBTcl_TraceCommandfR.
.PP
fBTcl_CommandTraceInfofR may be used to retrieve information about
traces set on a given command.
The return value from fBTcl_CommandTraceInfofR is the fIclientDatafR
associated with a particular trace.
The trace must be on the command specified by the fIinterpfR,
fIcmdNamefR, and fIflagsfR arguments (note that currently the
flags are ignored; fIflagsfR should be set to 0 for future
compatibility) and its trace procedure must the same as the fIprocfR
argument.
If the fIprevClientDatafR 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 fIprevClientDatafR argument isn't NULL, then it should
be the return value from a previous call to fBTcl_CommandTraceInfofR.
In this case, the new return value will correspond to the next
matching trace after the one whose fIclientDatafR matches
fIprevClientDatafR, or NULL if no trace matches fIprevClientDatafR
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 fIprocfR.
.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 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 fIprocfR, the TCL_TRACE_DESTROYED bit
is set in fIflagsfR.
'" 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 fIflagsfR
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

						