1Tcl_TraceCommand(3) Tcl Library Procedures Tcl_TraceCommand(3)
2______________________________________________________________________________
6
8 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand - monitor
9 renames and deletes of a command
10
12 #include <tcl.h>
13 ClientData
15 Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)
16 int
18 Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)
19 void
21 Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)
22
24 Tcl_Interp *interp (in) Interpreter contain‐
25 ing the command.
26 const char *cmdName (in) Name of command.
28 int flags (in) OR'ed collection of
30 the values
31 TCL_TRACE_RENAME and
32 TCL_TRACE_DELETE.
33 Tcl_CommandTraceProc *proc (in) Procedure to call
35 when specified opera‐
36 tions occur to cmd‐
37 Name.
38 ClientData clientData (in) Arbitrary argument to
40 pass to proc.
41 ClientData prevClientData (in) If non-NULL, gives
43 last value returned
44 by Tcl_CommandTrace‐
45 Info, so this call
46 will return informa‐
47 tion about next
48 trace. If NULL, this
49 call will return
50 information about
51 first trace.
52______________________________________________________________________________
53
55 Tcl_TraceCommand allows a C procedure to monitor operations performed
56 on a Tcl command, so that the C procedure is invoked whenever the com‐
57 mand is renamed or deleted. If the trace is created successfully then
58 Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName
59 specifies a non-existent command) then TCL_ERROR is returned and an
60 error message is left in the interpreter's result.
61 The flags argument to Tcl_TraceCommand indicates when the trace proce‐
63 dure is to be invoked. It consists of an OR'ed combination of any of
64 the following values:
65 TCL_TRACE_RENAME
67 Invoke proc whenever the command is renamed.
68 TCL_TRACE_DELETE
70 Invoke proc when the command is deleted.
71 Whenever one of the specified operations occurs to the command, proc
73 will be invoked. It should have arguments and result that match the
74 type Tcl_CommandTraceProc:
75 typedef void Tcl_CommandTraceProc(
77 ClientData clientData,
78 Tcl_Interp *interp,
79 const char *oldName,
80 const char *newName,
81 int flags);
82 The clientData and interp parameters will have the same values as those
84 passed to Tcl_TraceCommand when the trace was created. ClientData typ‐
85 ically points to an application-specific data structure that describes
86 what to do when proc is invoked. OldName gives the name of the command
87 being renamed, and newName gives the name that the command is being
88 renamed to (or NULL when the command is being deleted.) Flags is an
89 OR'ed combination of bits potentially providing several pieces of
90 information. One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE
91 will be set in flags to indicate which operation is being performed on
92 the command. The bit TCL_TRACE_DESTROYED will be set in flags if the
93 trace is about to be destroyed; this information may be useful to proc
94 so that it can clean up its own internal data structures (see the sec‐
95 tion TCL_TRACE_DESTROYED below for more details). Because the deletion
96 of commands can take place as part of the deletion of the interp that
97 contains them, proc must be careful about checking what the passed in
98 interp value can be called upon to do. The routine Tcl_InterpDeleted
99 is an important tool for this. When Tcl_InterpDeleted returns 1, proc
100 will not be able to invoke any scripts in interp. The function of proc
101 in that circumstance is limited to the cleanup of its own data struc‐
102 tures.
103 Tcl_UntraceCommand may be used to remove a trace. If the command spec‐
105 ified by interp, cmdName, and flags has a trace set with flags, proc,
106 and clientData, then the corresponding trace is removed. If no such
107 trace exists, then the call to Tcl_UntraceCommand has no effect. The
108 same bits are valid for flags as for calls to Tcl_TraceCommand.
109 Tcl_CommandTraceInfo may be used to retrieve information about traces
111 set on a given command. The return value from Tcl_CommandTraceInfo is
112 the clientData associated with a particular trace. The trace must be
113 on the command specified by the interp, cmdName, and flags arguments
114 (note that currently the flags are ignored; flags should be set to 0
115 for future compatibility) and its trace procedure must the same as the
116 proc argument. If the prevClientData argument is NULL then the return
117 value corresponds to the first (most recently created) matching trace,
118 or NULL if there are no matching traces. If the prevClientData argu‐
119 ment is not NULL, then it should be the return value from a previous
120 call to Tcl_CommandTraceInfo. In this case, the new return value will
121 correspond to the next matching trace after the one whose clientData
122 matches prevClientData, or NULL if no trace matches prevClientData or
123 if there are no more matching traces after it. This mechanism makes it
124 possible to step through all of the traces for a given command that
125 have the same proc.
126
128 During rename traces, the command being renamed is visible with both
129 names simultaneously, and the command still exists during delete
130 traces, unless the interp that contains it is being deleted. However,
131 there is no mechanism for signaling that an error occurred in a trace
132 procedure, so great care should be taken that errors do not get
133 silently lost.
134
136 It is possible for multiple traces to exist on the same command. When
137 this happens, all of the trace procedures will be invoked on each
138 access, in order from most-recently-created to least-recently-created.
139 Attempts to delete the command during a delete trace will fail
140 silently, since the command is already scheduled for deletion anyway.
141 If the command being renamed is renamed by one of its rename traces,
142 that renaming takes precedence over the one that triggered the trace
143 and the collection of traces will not be reexecuted; if several traces
144 rename the command, the last renaming takes precedence.
145
147 In a delete callback to proc, the TCL_TRACE_DESTROYED bit is set in
148 flags.
149
151 clientData, trace, command
152Tcl 7.4 Tcl_TraceCommand(3)