Tcl_CreateTrace(3) Tcl Library Procedures Tcl_CreateTrace(3) ________________________________________________________________________________
NAME
Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for
command execution to be traced
SYNOPSIS
#include <tcl.h>
Tcl_Trace
Tcl_CreateTrace(interp, level, proc, clientData)
Tcl_Trace
Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
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
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.
int flags (in) Flags governing the
trace execution. See
below for details.
Tcl_CmdObjTraceProc *objProc (in) Procedure to call for
each command that is
executed. See below
for details of the
calling sequence.
Tcl_CmdTraceProc *proc (in) Procedure to call for
each command that is
executed. See below
for details on the
calling sequence.
ClientData clientData (in) Arbitrary one-word
value to pass to
objProc or proc.
Tcl_CmdObjTraceDeleteProc *deleteProc (in) 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.
Tcl_Trace trace (in) Token for trace to be
removed (return value
from previous call to
Tcl_CreateTrace).
________________________________________________________________________________
DESCRIPTION
Tcl_CreateObjTrace arranges for command tracing. After it is called,
objProc will be invoked before the Tcl interpreter calls any command
procedure when evaluating commands in interp. The return value from
Tcl_CreateObjTrace 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 interpreter.
objProc should have arguments and result that match the type,
Tcl_CmdObjTraceProc:
typedef int Tcl_CmdObjTraceProc(
ClientData clientData,
Tcl_Interp* interp,
int level,
const char *command,
Tcl_Command commandToken,
int objc,
Tcl_Obj *const objv[]);
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
objProc is invoked. The level parameter 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). The command parameter points
to a string containing the text of the command, before any argument
substitution. The commandToken parameter is a Tcl command token that
identifies the command to be invoked. The token may be passed to
Tcl_GetCommandName, Tcl_GetCommandInfoFromToken, or
Tcl_SetCommandInfoFromToken to manipulate the definition of the command.
The objc and objv parameters designate the final parameter count and
parameter vector that will be passed to the command, and have had all
substitutions performed.
The objProc callback is expected to return a standard Tcl status return
code. If this code is TCL_OK (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 not invoked.
The objProc callback must not modify objv in any way.
Tracing will only occur for commands at nesting level less than or equal
to the level parameter (i.e. the level parameter to objProc will always
be less than or equal to the level parameter to Tcl_CreateTrace).
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 if and while in order that they may be traced. If
traces for the built-in commands are not required, the flags parameter
may be set to the constant value TCL_ALLOW_INLINE_COMPILATION. 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 Tcl_CreateObjTrace to implement an
execution time profiler.)
Calls to objProc 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 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 objProc will
occur, one for each command.
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.
When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc
that was passed as a parameter to Tcl_CreateObjTrace. The deleteProc
must match the type, Tcl_CmdObjTraceDeleteProc:
typedef void Tcl_CmdObjTraceDeleteProc(
ClientData clientData);
The clientData parameter will be the same as the clientData parameter
that was originally passed to Tcl_CreateObjTrace.
Tcl_CreateTrace is an alternative interface for command tracing, not
recommended for new applications. It is provided for backward
compatibility with code that was developed for older versions of the Tcl
interpreter. It is similar to Tcl_CreateObjTrace, except that its proc
parameter should have arguments and result that match the type
Tcl_CmdTraceProc:
typedef void Tcl_CmdTraceProc(
ClientData clientData,
Tcl_Interp *interp,
int level,
char *command,
Tcl_CmdProc *cmdProc,
ClientData cmdClientData,
int argc,
const char *argv[]);
The parameters to the proc callback are similar to those of the objProc
callback above. The commandToken is replaced with cmdProc, a pointer to
the (string-based) command procedure that will be invoked; and
cmdClientData, the client data that will be passed to the procedure. The
objc parameter is replaced with an argv parameter, that gives the
arguments to the command as character strings. Proc must not modify the
command or argv strings.
If a trace created with Tcl_CreateTrace is in effect, inline compilation
of Tcl commands such as if and while is always disabled. There is no
notification when a trace created with Tcl_CreateTrace is deleted. There
is no way to be notified when the trace created by Tcl_CreateTrace is
deleted. There is no way for the proc associated with a call to
Tcl_CreateTrace to abort execution of command.
KEYWORDS
command, create, delete, interpreter, trace
Tcl Tcl_CreateTrace(3)
tcl 8.6.13 - Generated Sun Jan 8 15:33:31 CST 2023