1Tcl_CreateTrace(3)          Tcl Library Procedures          Tcl_CreateTrace(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com‐
9       mand execution to be traced
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Trace
15       Tcl_CreateTrace(interp, level, proc, clientData)
16
17       Tcl_Trace
18       Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
19
20       Tcl_DeleteTrace(interp, trace)
21

ARGUMENTS

23       Tcl_Interp *interp (in)                             Interpreter    con‐
24                                                           taining  command to
25                                                           be  traced  or  un‐
26                                                           traced.
27
28       int level (in)                                      Only commands at or
29                                                           below this  nesting
30                                                           level    will    be
31                                                           traced unless 0  is
32                                                           specified.  1 means
33                                                           top-level  commands
34                                                           only,  2 means top-
35                                                           level  commands  or
36                                                           those  that are in‐
37                                                           voked as  immediate
38                                                           consequences of ex‐
39                                                           ecuting   top-level
40                                                           commands (procedure
41                                                           bodies,   bracketed
42                                                           commands, etc.) and
43                                                           so on.  A value  of
44                                                           0  means  that com‐
45                                                           mands at any  level
46                                                           are traced.
47
48       int flags (in)                                      Flags governing the
49                                                           trace    execution.
50                                                           See  below  for de‐
51                                                           tails.
52
53       Tcl_CmdObjTraceProc *objProc (in)                   Procedure  to  call
54                                                           for   each  command
55                                                           that  is  executed.
56                                                           See  below  for de‐
57                                                           tails of the  call‐
58                                                           ing sequence.
59
60       Tcl_CmdTraceProc *proc (in)                         Procedure  to  call
61                                                           for  each   command
62                                                           that  is  executed.
63                                                           See below  for  de‐
64                                                           tails  on the call‐
65                                                           ing sequence.
66
67       ClientData clientData (in)                          Arbitrary  one-word
68                                                           value  to  pass  to
69                                                           objProc or proc.
70
71       Tcl_CmdObjTraceDeleteProc *deleteProc (in)          Procedure  to  call
72                                                           when  the  trace is
73                                                           deleted.  See below
74                                                           for  details of the
75                                                           calling   sequence.
76                                                           A  NULL  pointer is
77                                                           permissible and re‐
78                                                           sults  in  no call‐
79                                                           back when the trace
80                                                           is deleted.
81
82       Tcl_Trace trace (in)                                Token  for trace to
83                                                           be removed  (return
84                                                           value from previous
85                                                           call to Tcl_Create‐
86                                                           Trace).
87______________________________________________________________________________
88

DESCRIPTION

90       Tcl_CreateObjTrace  arranges  for command tracing.  After it is called,
91       objProc will be invoked before the Tcl interpreter  calls  any  command
92       procedure  when  evaluating  commands in interp.  The return value from
93       Tcl_CreateObjTrace is a token for the trace, which  may  be  passed  to
94       Tcl_DeleteTrace  to  remove the trace.  There may be many traces in ef‐
95       fect simultaneously for the same interpreter.
96
97       objProc should have arguments and result that match the  type,  Tcl_Cm‐
98       dObjTraceProc:
99
100              typedef int Tcl_CmdObjTraceProc(
101                      ClientData clientData,
102                      Tcl_Interp* interp,
103                      int level,
104                      const char *command,
105                      Tcl_Command commandToken,
106                      int objc,
107                      Tcl_Obj *const objv[]);
108
109       The  clientData  and  interp parameters are copies of the corresponding
110       arguments given to Tcl_CreateTrace.  ClientData typically points to  an
111       application-specific  data structure that describes what to do when ob‐
112       jProc is invoked.  The level parameter gives the nesting level  of  the
113       command  (1  for  top-level commands passed to Tcl_Eval by the applica‐
114       tion, 2 for the next-level commands passed to Tcl_Eval as part of pars‐
115       ing or interpreting level-1 commands, and so on). The command parameter
116       points to a string containing the text of the command, before any argu‐
117       ment  substitution.   The commandToken parameter is a Tcl command token
118       that identifies the command to be invoked.  The token may be passed  to
119       Tcl_GetCommandName,  Tcl_GetCommandInfoFromToken,  or Tcl_SetCommandIn‐
120       foFromToken to manipulate the definition of the command. The  objc  and
121       objv  parameters designate the final parameter count and parameter vec‐
122       tor that will be passed to the command, and have had all  substitutions
123       performed.
124
125       The objProc callback is expected to return a standard Tcl status return
126       code.  If this code is TCL_OK (the normal case), then  the  Tcl  inter‐
127       preter will invoke the command.  Any other return code is treated as if
128       the command returned that status, and the command is not invoked.
129
130       The objProc callback must not modify objv in any way.  It is,  however,
131       permissible  to  change  the command by calling Tcl_SetCommandTokenInfo
132       prior to returning.  Any such change takes effect immediately, and  the
133       command is invoked with the new information.
134
135       Tracing  will  only  occur  for  commands at nesting level less than or
136       equal to the level parameter (i.e. the level parameter to objProc  will
137       always  be  less  than  or  equal to the level parameter to Tcl_Create‐
138       Trace).
139
140       Tracing has a significant effect  on  runtime  performance  because  it
141       causes  the  bytecode  compiler to refrain from generating in-line code
142       for Tcl commands such as if and while in order that they may be traced.
143       If traces for the built-in commands are not required, the flags parame‐
144       ter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION.   In
145       this  case,  traces on built-in commands may or may not result in trace
146       callbacks, depending on the state of the interpreter, but run-time per‐
147       formance will be improved significantly.  (This functionality is desir‐
148       able, for example, when using Tcl_CreateObjTrace to implement an execu‐
149       tion time profiler.)
150
151       Calls  to  objProc will be made by the Tcl parser immediately before it
152       calls the command procedure for the command (cmdProc).  This occurs af‐
153       ter  argument parsing and substitution, so tracing for substituted com‐
154       mands occurs before tracing of the commands  containing  the  substitu‐
155       tions.  If there is a syntax error in a command, or if there is no com‐
156       mand procedure associated with a command name, then no tracing will oc‐
157       cur for that command.  If a string passed to Tcl_Eval contains multiple
158       commands (bracketed, or on different lines) then multiple calls to  ob‐
159       jProc will occur, one for each command.
160
161       Tcl_DeleteTrace  removes  a trace, so that no future calls will be made
162       to the procedure associated with the trace.  After Tcl_DeleteTrace  re‐
163       turns, the caller should never again use the trace token.
164
165       When  Tcl_DeleteTrace is called, the interpreter invokes the deleteProc
166       that was passed as a parameter to Tcl_CreateObjTrace.   The  deleteProc
167       must match the type, Tcl_CmdObjTraceDeleteProc:
168
169              typedef void Tcl_CmdObjTraceDeleteProc(
170                      ClientData clientData);
171
172       The  clientData  parameter will be the same as the clientData parameter
173       that was originally passed to Tcl_CreateObjTrace.
174
175       Tcl_CreateTrace is an alternative interface for  command  tracing,  not
176       recommended for new applications.  It is provided for backward compati‐
177       bility with code that was developed for older versions of the  Tcl  in‐
178       terpreter.   It  is similar to Tcl_CreateObjTrace, except that its proc
179       parameter should have arguments and result that match the type Tcl_Cmd‐
180       TraceProc:
181
182              typedef void Tcl_CmdTraceProc(
183                      ClientData clientData,
184                      Tcl_Interp *interp,
185                      int level,
186                      char *command,
187                      Tcl_CmdProc *cmdProc,
188                      ClientData cmdClientData,
189                      int argc,
190                      const char *argv[]);
191
192       The parameters to the proc callback are similar to those of the objProc
193       callback above. The commandToken is replaced with cmdProc, a pointer to
194       the  (string-based)  command  procedure  that will be invoked; and cmd‐
195       ClientData, the client data that will be passed to the procedure.   The
196       objc parameter is replaced with an argv parameter, that gives the argu‐
197       ments to the command as character strings.  Proc must  not  modify  the
198       command or argv strings.
199
200       If  a  trace created with Tcl_CreateTrace is in effect, inline compila‐
201       tion of Tcl commands such as if and while is always disabled.  There is
202       no  notification  when a trace created with Tcl_CreateTrace is deleted.
203       There is no way to be notified when the trace  created  by  Tcl_Create‐
204       Trace  is deleted.  There is no way for the proc associated with a call
205       to Tcl_CreateTrace to abort execution of command.
206

KEYWORDS

208       command, create, delete, interpreter, trace
209
210
211
212Tcl                                                         Tcl_CreateTrace(3)
Impressum