Tcl_CreateTrace
Tcl_CreateTrace(3) Tcl Library Procedures Tcl_CreateTrace(3)
______________________________________________________________________________
NAME
Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command execution to be
traced
SYNOPSIS
#include <tcl.h>
Tcl_Trace
Tcl_CreateTrace(interp, level, proc, clientData)
Tcl_DeleteTrace(interp, trace)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter containing
command to be traced or
untraced.
int level (in) Only commands at or below
this nesting level will
be traced. 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 bod-
ies, bracketed commands,
etc.) and so on.
Tcl_CmdTraceProc *proc (in) Procedure to call for
each command that's exe-
cuted. See below for
details on the calling
sequence.
ClientData clientData (in) Arbitrary one-word value
to pass to proc.
Tcl_Trace trace (in) Token for trace to be
removed (return value
from previous call to
Tcl_CreateTrace).
_________________________________________________________________
DESCRIPTION
Tcl_CreateTrace arranges for command tracing. From now on, proc will
be invoked before Tcl calls command procedures to process commands in
interp. The return value from Tcl_CreateTrace is a token for the
trace, which may be passed to Tcl_DeleteTrace to remove the trace.
There may be many traces in effect simultaneously for the same command
interpreter.
Proc should have arguments and result that match the type Tcl_CmdTrace-
Proc:
typedef void Tcl_CmdTraceProc(
ClientData clientData,
Tcl_Interp *interp,
int level,
char *command,
Tcl_CmdProc *cmdProc,
ClientData cmdClientData,
int argc,
char *argv[]);
The clientData and interp parameters are copies of the corresponding
arguments given to Tcl_CreateTrace. ClientData typically points to an
application-specific data structure that describes what to do when proc
is invoked. Level gives the nesting level of the command (1 for top-
level commands passed to Tcl_Eval by the application, 2 for the next-
level commands passed to Tcl_Eval as part of parsing or interpreting
level-1 commands, and so on). Command points to a string containing
the text of the command, before any argument substitution. CmdProc
contains the address of the command procedure that will be called to
process the command (i.e. the proc argument of some previous call to
Tcl_CreateCommand) and cmdClientData contains the associated client
data for cmdProc (the clientData value passed to Tcl_CreateCommand).
Argc and argv give the final argument information that will be passed
to cmdProc, after command, variable, and backslash substitution. Proc
must not modify the command or argv strings.
Tracing will only occur for commands at nesting level less than or
equal to the level parameter (i.e. the level parameter to proc will
always be less than or equal to the level parameter to Tcl_Create-
Trace).
Calls to proc will be made by the Tcl parser immediately before it
calls the command procedure for the command (cmdProc). This occurs
after argument parsing and substitution, so tracing for substituted
commands occurs before tracing of the commands containing the substitu-
tions. If there is a syntax error in a command, or if there is no com-
mand procedure associated with a command name, then no tracing will
occur for that command. If a string passed to Tcl_Eval contains multi-
ple commands (bracketed, or on different lines) then multiple calls to
proc will occur, one for each command. The command string for each of
these trace calls will reflect only a single command, not the entire
string passed to Tcl_Eval.
Tcl_DeleteTrace removes a trace, so that no future calls will be made
to the procedure associated with the trace. After Tcl_DeleteTrace
returns, the caller should never again use the trace token.
KEYWORDS
command, create, delete, interpreter, trace
Tcl Tcl_CreateTrace(3)
