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 value
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
56 Tcl_TraceCommand allows a C procedure to monitor operations performed
57 on a Tcl command, so that the C procedure is invoked whenever the com‐
58 mand is renamed or deleted. If the trace is created successfully then
59 Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName
60 specifies a non-existent command) then TCL_ERROR is returned and an
61 error message is left in the interpreter's result.
62 The flags argument to Tcl_TraceCommand indicates when the trace proce‐
64 dure is to be invoked. It consists of an OR-ed combination of any of
65 the following values:
66 TCL_TRACE_RENAME
68 Invoke proc whenever the command is renamed.
69 TCL_TRACE_DELETE
71 Invoke proc when the command is deleted.
72 Whenever one of the specified operations occurs to the command, proc
74 will be invoked. It should have arguments and result that match the
75 type Tcl_CommandTraceProc:
76 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
83 passed to Tcl_TraceCommand when the trace was created. ClientData typ‐
84 ically points to an application-specific data structure that describes
85 what to do when proc is invoked. OldName gives the name of the command
86 being renamed, and newName gives the name that the command is being
87 renamed to (or an empty string or NULL when the command is being
88 deleted.) Flags is an OR-ed combination of bits potentially providing
89 several pieces of information. One of the bits TCL_TRACE_RENAME and
90 TCL_TRACE_DELETE will be set in flags to indicate which operation is
91 being performed on the command. The bit TCL_TRACE_DESTROYED will be
92 set in flags if the trace is about to be destroyed; this information
93 may be useful to proc so that it can clean up its own internal data
94 structures (see the section TCL_TRACE_DESTROYED below for more
95 details). Lastly, the bit TCL_INTERP_DESTROYED will be set if the
96 entire interpreter is being destroyed. When this bit is set, proc must
97 be especially careful in the things it does (see the section
98 TCL_INTERP_DESTROYED below).
99 Tcl_UntraceCommand may be used to remove a trace. If the command spec‐
101 ified by interp, cmdName, and flags has a trace set with flags, proc,
102 and clientData, then the corresponding trace is removed. If no such
103 trace exists, then the call to Tcl_UntraceCommand has no effect. The
104 same bits are valid for flags as for calls to Tcl_TraceCommand.
105 Tcl_CommandTraceInfo may be used to retrieve information about traces
107 set on a given command. The return value from Tcl_CommandTraceInfo is
108 the clientData associated with a particular trace. The trace must be
109 on the command specified by the interp, cmdName, and flags arguments
110 (note that currently the flags are ignored; flags should be set to 0
111 for future compatibility) and its trace procedure must the same as the
112 proc argument. If the prevClientData argument is NULL then the return
113 value corresponds to the first (most recently created) matching trace,
114 or NULL if there are no matching traces. If the prevClientData argu‐
115 ment isn't NULL, then it should be the return value from a previous
116 call to Tcl_CommandTraceInfo. In this case, the new return value will
117 correspond to the next matching trace after the one whose clientData
118 matches prevClientData, or NULL if no trace matches prevClientData or
119 if there are no more matching traces after it. This mechanism makes it
120 possible to step through all of the traces for a given command that
121 have the same proc.
122
125 During rename traces, the command being renamed is visible with both
126 names simultaneously, and the command still exists during delete traces
127 (if TCL_INTERP_DESTROYED is not set). However, there is no mechanism
128 for signaling that an error occurred in a trace procedure, so great
129 care should be taken that errors do not get silently lost.
130
133 It is possible for multiple traces to exist on the same command. When
134 this happens, all of the trace procedures will be invoked on each
135 access, in order from most-recently-created to least-recently-created.
136 Attempts to delete the command during a delete trace will fail
137 silently, since the command is already scheduled for deletion anyway.
138 If the command being renamed is renamed by one of its rename traces,
139 that renaming takes precedence over the one that triggered the trace
140 and the collection of traces will not be reexecuted; if several traces
141 rename the command, the last renaming takes precedence.
142
145 In a delete callback to proc, the TCL_TRACE_DESTROYED bit is set in
146 flags.
147
151 When an interpreter is destroyed, unset traces are called for all of
152 its commands. The TCL_INTERP_DESTROYED bit will be set in the flags
153 argument passed to the trace procedures. Trace procedures must be
154 extremely careful in what they do if the TCL_INTERP_DESTROYED bit is
155 set. It is not safe for the procedures to invoke any Tcl procedures on
156 the interpreter, since its state is partially deleted. All that trace
157 procedures should do under these circumstances is to clean up and free
158 their own internal data structures.
159
162 Tcl doesn't do any error checking to prevent trace procedures from mis‐
163 using the interpreter during traces with TCL_INTERP_DESTROYED set.
164
167 clientData, trace, command
168Tcl 7.4 Tcl_TraceCommand(3)