Provided by: tcl9.0-doc_9.0.1+dfsg-1_all 
NAME
Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, 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_Trace
Tcl_CreateObjTrace2(interp, level, flags, objProc2, clientData, deleteProc)
Tcl_DeleteTrace(interp, trace)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter containing command to be traced or
untraced.
Tcl_Size 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_CmdObjTraceProc2 *objProc2 (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.
void *clientData (in) Arbitrary one-word value to pass to objProc, objProc2
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(
void * clientData,
Tcl_Interp* interp,
int level,
const char *command,
Tcl_Command commandToken,
int objc,
Tcl_Obj *const objv[]);
objProc2 should have arguments and result that match the type, Tcl_CmdObjTraceProc2:
typedef int Tcl_CmdObjTraceProc2(
void * clientData,
Tcl_Interp* interp,
Tcl_Size level,
const char *command,
Tcl_Command commandToken,
Tcl_Size 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(
void * 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(
void *clientData,
Tcl_Interp *interp,
int level,
char *command,
Tcl_CmdProc *cmdProc,
void *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.
REFERENCE COUNT MANAGEMENT
When the proc passed to Tcl_CreateObjTrace is called, the values in its objv argument will have a
reference count of at least 1, with that guaranteed reference being from the Tcl evaluation stack. You
should not call Tcl_DecrRefCount on any of those values unless you call Tcl_IncrRefCount on them first.
SEE ALSO
trace(3tcl)
KEYWORDS
command, create, delete, interpreter, trace
Tcl Tcl_CreateTrace(3tcl)