<\/a> <\/h2>\nTcl_CreateObjTrace<\/b> arranges for command tracing. After it is called, objProc<\/i> will be invoked before the Tcl interpreter calls any command procedure when evaluating commands in interp<\/i>. The return value from Tcl_CreateObjTrace<\/b> is a token for the trace, which may be passed to Tcl_DeleteTrace<\/b> to remove the trace. There may be many traces in effect simultaneously for the same interpreter.<\/p>\n
objProc<\/i> should have arguments and result that match the type, Tcl_CmdObjTraceProc<\/b>:<\/p>\n
typedef int Tcl_CmdObjTraceProc<\/b>(
ClientData<\/b> clientData<\/i>,
Tcl_Interp<\/b>* interp<\/i>,
int level<\/i>,
const char *command<\/i>,
Tcl_Command<\/b> commandToken<\/i>,
int objc<\/i>,
Tcl_Obj<\/b> *const objv<\/i>[]);<\/p>\n
The clientData<\/i> and interp<\/i> parameters are copies of the corresponding arguments given to Tcl_CreateTrace<\/b>. ClientData<\/i> typically points to an application-specific data structure that describes what to do when objProc<\/i> is invoked. The level<\/i> parameter gives the nesting level of the command (1 for top-level commands passed to Tcl_Eval<\/b> by the application, 2 for the next-level commands passed to Tcl_Eval<\/b> as part of parsing or interpreting level-1 commands, and so on). The command<\/i> parameter points to a string containing the text of the command, before any argument substitution. The commandToken<\/i> parameter is a Tcl command token that identifies the command to be invoked. The token may be passed to Tcl_GetCommandName<\/b>, Tcl_GetCommandInfoFromToken<\/b>, or Tcl_SetCommandInfoFromToken<\/b> to manipulate the definition of the command. The objc<\/i> and objv<\/i> parameters designate the final parameter count and parameter vector that will be passed to the command, and have had all substitutions performed.<\/p>\n
The objProc<\/i> callback is expected to return a standard Tcl status return code. If this code is TCL_OK<\/b> (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<\/i> invoked.<\/p>\n
The objProc<\/i> callback must not modify objv<\/i> in any way. It is, however, permissible to change the command by calling Tcl_SetCommandTokenInfo<\/b> prior to returning. Any such change takes effect immediately, and the command is invoked with the new information.<\/p>\n
Tracing will only occur for commands at nesting level less than or equal to the level<\/i> parameter (i.e. the level<\/i> parameter to objProc<\/i> will always be less than or equal to the level<\/i> parameter to Tcl_CreateTrace<\/b>).<\/p>\n
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<\/b> and while<\/b> in order that they may be traced. If traces for the built-in commands are not required, the flags<\/i> parameter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION<\/b>. 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<\/b> to implement an execution time profiler.)<\/p>\n
Calls to objProc<\/i> will be made by the Tcl parser immediately before it calls the command procedure for the command (cmdProc<\/i>). 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<\/i> will occur, one for each command.<\/p>\n
Tcl_DeleteTrace<\/b> removes a trace, so that no future calls will be made to the procedure associated with the trace. After Tcl_DeleteTrace<\/b> returns, the caller should never again use the trace<\/i> token.<\/p>\n
When Tcl_DeleteTrace<\/b> is called, the interpreter invokes the deleteProc<\/i> that was passed as a parameter to Tcl_CreateObjTrace<\/b>. The deleteProc<\/i> must match the type, Tcl_CmdObjTraceDeleteProc<\/b>:<\/p>\n
typedef void Tcl_CmdObjTraceDeleteProc<\/b>(
ClientData<\/b> clientData<\/i>);<\/p>\n
The clientData<\/i> parameter will be the same as the clientData<\/i> parameter that was originally passed to Tcl_CreateObjTrace<\/b>.<\/p>\n
Tcl_CreateTrace<\/b> is an alternative interface for command tracing, not recommended for new applications<\/i>. It is provided for backward compatibility with code that was developed for older versions of the Tcl interpreter. It is similar to Tcl_CreateObjTrace<\/b>, except that its proc<\/i> parameter should have arguments and result that match the type Tcl_CmdTraceProc<\/b>:<\/p>\n
typedef void Tcl_CmdTraceProc<\/b>(
ClientData clientData<\/i>,
Tcl_Interp *interp<\/i>,
int level<\/i>,
char *command<\/i>,
Tcl_CmdProc *cmdProc<\/i>,
ClientData cmdClientData<\/i>,
int argc<\/i>,
const char *argv<\/i>[]);<\/p>\n
The parameters to the proc<\/i> callback are similar to those of the objProc<\/i> callback above. The commandToken<\/i> is replaced with cmdProc<\/i>, a pointer to the (string-based) command procedure that will be invoked; and cmdClientData<\/i>, the client data that will be passed to the procedure. The objc<\/i> parameter is replaced with an argv<\/i> parameter, that gives the arguments to the command as character strings. Proc<\/i> must not modify the command<\/i> or argv<\/i> strings.<\/p>\n
If a trace created with Tcl_CreateTrace<\/b> is in effect, inline compilation of Tcl commands such as if<\/b> and while<\/b> is always disabled. There is no notification when a trace created with Tcl_CreateTrace<\/b> is deleted. There is no way to be notified when the trace created by Tcl_CreateTrace<\/b> is deleted. There is no way for the proc<\/i> associated with a call to Tcl_CreateTrace<\/b> to abort execution of command<\/i>.<\/p>\n