通讯编程

开发平台：
Visual C++

CrtTrace.3：源码内容
							'"
'" Copyright (c) 1989-1993 The Regents of the University of California.
'" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'" Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: CrtTrace.3,v 1.6.2.1 2003/07/18 15:20:51 dgp Exp $
'" 
.so man.macros
.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for command execution to be traced
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
Tcl_Trace
fBTcl_CreateTracefR(fIinterp, level, proc, clientDatafR)
.sp
Tcl_Trace
fBTcl_CreateObjTracefR(fIinterp, level, flags, objProc, clientData, deleteProcfR)
.sp
fBTcl_DeleteTracefR(fIinterp, tracefR)
.SH ARGUMENTS
.AS Tcl_CmdObjTraceDeleteProc (clientData)()
.AP Tcl_Interp *interp in
Interpreter containing command to be traced or untraced.
.AP int level in
Only commands at or below this nesting level will be traced unless
0 is specified.  1 means
top-level commands only, 2 means top-level commands or those that are
invoked as immediate consequences of executing top-level commands
(procedure bodies, bracketed commands, etc.) and so on.
A value of 0 means that commands at any level are traced.
.AP int flags in
Flags governing the trace execution.  See below for details.
.AP Tcl_CmdObjTraceProc *objProc in
Procedure to call for each command that's executed.  See below for
details of the calling sequence.
.AP Tcl_CmdTraceProc *proc in
Procedure to call for each command that's executed.  See below for
details on the calling sequence.
.AP ClientData clientData in
Arbitrary one-word value to pass to fIobjProcfR or fIprocfR.
.AP Tcl_CmdObjTraceDeleteProc *deleteProc
Procedure to call when the trace is deleted.  See below for details of
the calling sequence.  A NULL pointer is permissible and results in no
callback when the trace is deleted.
.AP Tcl_Trace trace in
Token for trace to be removed (return value from previous call
to fBTcl_CreateTracefR).
.BE
.SH DESCRIPTION
.PP
fBTcl_CreateObjTracefR arranges for command tracing.  After it is
called, fIobjProcfR will be invoked before the Tcl interpreter calls
any command procedure when evaluating commands in fIinterpfR.
The return value from fBTcl_CreateObjTracefR is a token for the trace,
which may be passed to fBTcl_DeleteTracefR to remove the trace.
There may be many traces in effect simultaneously for the same
interpreter.
.PP
fIobjProcfR should have arguments and result that match the type,
fBTcl_CmdObjTraceProcfR:
.CS
typedef int fBTcl_CmdObjTraceProcfR( 
    fBClientDatafR fIclientDatafR,
    fBTcl_InterpfR* fIinterpfR,
    int fIlevelfR,
    CONST char* fIcommandfR,
    fBTcl_CommandfR fIcommandTokenfR,
    int fIobjcfR,
    fBTcl_ObjfR *CONST fIobjvfR[] );
.CE
The fIclientDatafR and fIinterpfR parameters are copies of the
corresponding arguments given to fBTcl_CreateTracefR.
fIClientDatafR typically points to an application-specific data
structure that describes what to do when fIobjProcfR is invoked.  The
fIlevelfR parameter gives the nesting level of the command (1 for
top-level commands passed to fBTcl_EvalfR by the application, 2 for
the next-level commands passed to fBTcl_EvalfR as part of parsing or
interpreting level-1 commands, and so on). The fIcommandfR parameter
points to a string containing the text of the command, before any
argument substitution.  The fIcommandTokenfR parameter is a Tcl
command token that identifies the command to be invoked.  The token
may be passed to fBTcl_GetCommandNamefR,
fBTcl_GetCommandTokenInfofR, or fBTcl_SetCommandTokenInfofR to
manipulate the definition of the command. The fIobjcfR and fIobjvfR
parameters designate the final parameter count and parameter vector
that will be passed to the command, and have had all substitutions
performed.
.PP
The fIobjProcfR callback is expected to return a standard Tcl status
return code.  If this code is fBTCL_OKfR (the normal case), then
the Tcl interpreter will invoke the command.  Any other return code
is treated as if the command returned that status, and the command is
fInotfR invoked.
.PP
The fIobjProcfR callback must not modify fIobjvfR in any way.  It
is, however, permissible to change the command by calling
fBTcl_SetCommandTokenInfofR prior to returning.  Any such change
takes effect immediately, and the command is invoked with the new
information.
.PP
Tracing will only occur for commands at nesting level less than
or equal to the fIlevelfR parameter (i.e. the fIlevelfR
parameter to fIobjProcfR will always be less than or equal to the
fIlevelfR parameter to fBTcl_CreateTracefR).
.PP
Tracing has a significant effect on runtime performance because it
causes the bytecode compiler to refrain from generating in-line code
for Tcl commands such as fBiffR and fBwhilefR in order that they
may be traced.  If traces for the built-in commands are not required,
the fIflagsfR parameter may be set to the constant value
fBTCL_ALLOW_INLINE_COMPILATIONfR.  In this case, traces on built-in
commands may or may not result in trace callbacks, depending on the
state of the interpreter, but run-time performance will be improved
significantly.  (This functionality is desirable, for example, when
using fBTcl_CreateObjTracefR to implement an execution time
profiler.)
.PP
Calls to fIobjProcfR will be made by the Tcl parser immediately before
it calls the command procedure for the command (fIcmdProcfR).  This
occurs after argument parsing and substitution, so tracing for
substituted commands occurs before tracing of the commands
containing the substitutions.  If there is a syntax error in a
command, or if there is no command procedure associated with a
command name, then no tracing will occur for that command.  If a
string passed to Tcl_Eval contains multiple commands (bracketed, or
on different lines) then multiple calls to fIobjProcfR will occur,
one for each command.
.PP
fBTcl_DeleteTracefR removes a trace, so that no future calls will be
made to the procedure associated with the trace.  After fBTcl_DeleteTracefR
returns, the caller should never again use the fItracefR token.
.PP
When fBTcl_DeleteTracefR is called, the interpreter invokes the
fIdeleteProcfR that was passed as a parameter to
fBTcl_CreateObjTracefR.  The fIdeleteProcfR must match the type,
fBTcl_CmdObjTraceDeleteProcfR:
.CS
typedef void fBTcl_CmdObjTraceDeleteProcfR( 
    fBClientDatafR fIclientDatafR
);
.CE
The fIclientDatafR parameter will be the same as the
fIclientDatafR parameter that was originally passed to
fBTcl_CreateObjTracefR.
.PP
fBTcl_CreateTracefR is an alternative interface for command tracing,
fInot recommended for new applicationsfR.  It is provided for backward
compatibility with code that was developed for older versions of the
Tcl interpreter.  It is similar to fBTcl_CreateObjTracefR, except
that its fIprocfR parameter should have arguments and result that
match the type fBTcl_CmdTraceProcfR:
.CS
typedef void Tcl_CmdTraceProc(
	ClientData fIclientDatafR,
	Tcl_Interp *fIinterpfR,
	int fIlevelfR,
	char *fIcommandfR,
	Tcl_CmdProc *fIcmdProcfR,
	ClientData fIcmdClientDatafR,
	int fIargcfR,
	CONST char *fIargvfR[]);
.CE
The parameters to the fIprocfR callback are similar to those of the
fIobjProcfR callback above. The fIcommandTokenfR is
replaced with fIcmdProcfR, a pointer to the (string-based) command
procedure that will be invoked; and fIcmdClientDatafR, the client
data that will be passed to the procedure.  The fIobjcfR parameter
is replaced with an fIargvfR parameter, that gives the arguments to
the command as character strings.
fIProcfR must not modify the fIcommandfR or fIargvfR strings.
.PP
If a trace created with fBTcl_CreateTracefR is in effect, inline
compilation of Tcl commands such as fBiffR and fBwhilefR is always
disabled.  There is no notification when a trace created with
fBTcl_CreateTracefR is deleted.
There is no way to be notified when the trace created by
fBTcl_CreateTracefR is deleted.  There is no way for the fIprocfR
associated with a call to fBTcl_CreateTracefR to abort execution of
fIcommandfR.
.SH KEYWORDS
command, create, delete, interpreter, trace

						