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

NAME

8       Tcl_CommandTraceInfo,  Tcl_TraceCommand,  Tcl_UntraceCommand  - monitor
9       renames and deletes of a command
10

SYNOPSIS

12       #include <tcl.h>
13
14       ClientData
15       Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)
16
17       int
18       Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)
19
20       void
21       Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)
22

ARGUMENTS

24       Tcl_Interp *interp (in)                           Interpreter  contain‐
25                                                         ing the command.
26
27       const char *cmdName (in)                          Name of command.
28
29       int flags (in)                                    OR'ed  collection  of
30                                                         the            values
31                                                         TCL_TRACE_RENAME  and
32                                                         TCL_TRACE_DELETE.
33
34       Tcl_CommandTraceProc *proc (in)                   Procedure   to   call
35                                                         when specified opera‐
36                                                         tions occur  to  cmd‐
37                                                         Name.
38
39       ClientData clientData (in)                        Arbitrary argument to
40                                                         pass to proc.
41
42       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

DESCRIPTION

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
62       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
66       TCL_TRACE_RENAME
67              Invoke proc whenever the command is renamed.
68
69       TCL_TRACE_DELETE
70              Invoke proc when the command is deleted.
71
72       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
76              typedef void Tcl_CommandTraceProc(
77                      ClientData clientData,
78                      Tcl_Interp *interp,
79                      const char *oldName,
80                      const char *newName,
81                      int flags);
82
83       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
104       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
110       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

CALLING COMMANDS DURING TRACES

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

MULTIPLE TRACES

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

TCL_TRACE_DESTROYED FLAG

147       In  a  delete  callback  to proc, the TCL_TRACE_DESTROYED bit is set in
148       flags.
149

KEYWORDS

151       clientData, trace, command
152
153
154
155Tcl                                   7.4                  Tcl_TraceCommand(3)
Impressum