About Us Documentation

Contact Site Map




Tcl_CreateTrace(3)   Tcl Library Procedures



Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command exe- cution to be traced


#include <tcl.h> Tcl_Trace Tcl_CreateTrace(interp, level, proc, clientData) Tcl_DeleteTrace(interp, trace)


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 com- mands or those that are invoked as immediate consequences of executing top-level com- mands (pro- cedure bodies, bracketed com- mands, etc.) and so on. Tcl_CmdTraceProc *proc (in) Procedure to call for each command that's executed. See below for details on the calling sequence. Tcl 1 Tcl_CreateTrace(3) Tcl Library Procedures 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). _________________________________________________________________


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_CmdTraceProc: 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. Client- Data typically points to an application-specific data struc- ture that describes what to do when proc is invoked. Level gives the nesting level of the command (1 for top-level com- mands 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 Tcl 2 Tcl_CreateTrace(3) Tcl Library Procedures 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 parame- ter to proc will always be less than or equal to the level parameter to Tcl_CreateTrace). 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 substitu- tion, 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 com- mand procedure associated with a command name, then no trac- ing will occur for that command. If a string passed to Tcl_Eval contains multiple commands (bracketed, or on dif- ferent 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.


command, create, delete, interpreter, trace Tcl 3 Prepared by Ready-to-Run Software, Inc.


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002

To return to the Ready-to-Run Software WinPak Table of contents please presshere