Manual Pages for UNIX Darwin command on man CrtTrace

TclCreateTrace(3) Tcl Library Procedures TclCreateTrace(3)

NAME

TclCreateTrace, TclCreateObjTrace, TclDeleteTrace - arrange for com-

mand execution to be traced

SYNOPSIS

##iinncclluuddee <>

TclTrace TTccllCCrreeaatteeTTrraaccee(interp, level, proc, clientData) TclTrace TTccllCCrreeaatteeOObbjjTTrraaccee(interp, level, flags, objProc, clientData, deleteProc) TTccllDDeelleetteeTTrraaccee(interp, trace) AARRGGUUMMEENNTTSS

TclInterp *interp (in) Interpreter con-

taining 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 imme-

diate conse-

quences of exe-

cuting top-level

commands (proce-

dure bodies,

bracketed com-

mands, etc.) and so on. A value of 0 means that commands at any level are traced. int flags (in) Flags governing

the trace execu-

tion. See below for details. TclCmdObjTraceProc *objProc (in) Procedure to call for each command that's executed. See below for details of the calling sequence. TclCmdTraceProc *proc (in) Procedure to call for each command that's executed. See below for details on the calling sequence.

ClientData clientData (in) Arbitrary one-

word value to pass to objProc or proc. TclCmdObjTraceDeleteProc *deleteProc 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. TclTrace trace (in) Token for trace to be removed (return value from previous

call to TTccllCCrree-

aatteeTTrraaccee).

DESCRIPTION

TTccllCCrreeaatteeOObbjjTTrraaccee 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 TTccllCCrreeaatteeOObbjjTTrraaccee is a token for the trace, which may be passed to TTccllDDeelleetteeTTrraaccee 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, TTccllCCmmddOObbjjTTrraacceePPrroocc: typedef int TTccllCCmmddOObbjjTTrraacceePPrroocc( CClliieennttDDaattaa clientData, TTccllIInntteerrpp* interp, int level, CONST char* command, TTccllCCoommmmaanndd commandToken, int objc, TTccllOObbjj *CONST objv[] ); The clientData and interp parameters are copies of the corresponding arguments given to TTccllCCrreeaatteeTTrraaccee. 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 TTccllEEvvaall by the applica-

tion, 2 for the next-level commands passed to TTccllEEvvaall as part of pars-

ing or interpreting level-1 commands, and so on). The command parameter

points to a string containing the text of the command, before any argu-

ment substitution. The commandToken parameter is a Tcl command token that identifies the command to be invoked. The token may be passed to TTccllGGeettCCoommmmaannddNNaammee, TTccllGGeettCCoommmmaannddTTookkeennIInnffoo, or TTccllSSeettCCoommmmaannddTTookkeennIInnffoo

to manipulate the definition of the command. The objc and objv parame-

ters 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 TTCCLLOOKK (the normal case), then the Tcl inter-

preter 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. It is, however, permissible to change the command by calling TTccllSSeettCCoommmmaannddTTookkeennIInnffoo prior to returning. Any such change takes effect immediately, and the command is invoked with the new information. 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 TTccllCCrreeaattee-

TTrraaccee). 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 iiff and wwhhiillee in order that they may be traced.

If traces for the built-in commands are not required, the flags parame-

ter may be set to the constant value TTCCLLAALLLLOOWWIINNLLIINNEECCOOMMPPIILLAATTIIOONN. 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 per-

formance will be improved significantly. (This functionality is desir-

able, for example, when using TTccllCCrreeaatteeOObbjjTTrraaccee to implement an execu-

tion 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 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 TclEval contains multi-

ple commands (bracketed, or on different lines) then multiple calls to objProc will occur, one for each command. TTccllDDeelleetteeTTrraaccee removes a trace, so that no future calls will be made to the procedure associated with the trace. After TTccllDDeelleetteeTTrraaccee returns, the caller should never again use the trace token. When TTccllDDeelleetteeTTrraaccee is called, the interpreter invokes the deleteProc that was passed as a parameter to TTccllCCrreeaatteeOObbjjTTrraaccee. The deleteProc must match the type, TTccllCCmmddOObbjjTTrraacceeDDeelleetteePPrroocc: typedef void TTccllCCmmddOObbjjTTrraacceeDDeelleetteePPrroocc( CClliieennttDDaattaa clientData ); The clientData parameter will be the same as the clientData parameter that was originally passed to TTccllCCrreeaatteeOObbjjTTrraaccee. TTccllCCrreeaatteeTTrraaccee is an alternative interface for command tracing, not

recommended for new applications. It is provided for backward compati-

bility with code that was developed for older versions of the Tcl interpreter. It is similar to TTccllCCrreeaatteeOObbjjTTrraaccee, except that its proc

parameter should have arguments and result that match the type TTccllCCmmdd-

TTrraacceePPrroocc: typedef void TclCmdTraceProc( ClientData clientData, TclInterp *interp, int level, char *command, TclCmdProc *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 cmd-

ClientData, the client data that will be passed to the procedure. The

objc parameter is replaced with an argv parameter, that gives the argu-

ments to the command as character strings. Proc must not modify the command or argv strings.

If a trace created with TTccllCCrreeaatteeTTrraaccee is in effect, inline compila-

tion of Tcl commands such as iiff and wwhhiillee is always disabled. There is no notification when a trace created with TTccllCCrreeaatteeTTrraaccee is deleted.

There is no way to be notified when the trace created by TTccllCCrreeaattee-

TTrraaccee is deleted. There is no way for the proc associated with a call to TTccllCCrreeaatteeTTrraaccee to abort execution of command. KKEEYYWWOORRDDSS command, create, delete, interpreter, trace Tcl TclCreateTrace(3)