NAME

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

SYNOPSIS

       #include <tcl.h>

       ClientData
       Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)

       int
       Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)

       void
       Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)

ARGUMENTS

       Tcl_Interp *interp (in)                           Interpreter containing the command.

       const char *cmdName (in)                          Name of command.

       int flags (in)                                    OR'ed   collection   of    the    values
                                                         TCL_TRACE_RENAME and TCL_TRACE_DELETE.

       Tcl_CommandTraceProc *proc (in)                   Procedure   to   call   when   specified
                                                         operations occur to cmdName.

       ClientData clientData (in)                        Arbitrary argument to pass to proc.

       ClientData prevClientData (in)                    If non-NULL, gives last  value  returned
                                                         by  Tcl_CommandTraceInfo,  so  this call
                                                         will  return  information   about   next
                                                         trace.   If  NULL, this call will return
                                                         information about first trace.
_________________________________________________________________

DESCRIPTION

       Tcl_TraceCommand allows a C procedure to monitor operations performed on a Tcl command, so
       that  the C procedure is invoked whenever the command is renamed or deleted.  If the trace
       is created successfully then Tcl_TraceCommand returns TCL_OK. If an error  occurred  (e.g.
       cmdName  specifies a non-existent command) then TCL_ERROR is returned and an error message
       is left in the interpreter's result.

       The flags argument to Tcl_TraceCommand  indicates  when  the  trace  procedure  is  to  be
       invoked.  It consists of an OR'ed combination of any of the following values:

       TCL_TRACE_RENAME
              Invoke proc whenever the command is renamed.

       TCL_TRACE_DELETE
              Invoke proc when the command is deleted.

       Whenever  one of the specified operations occurs to the command, proc will be invoked.  It
       should have arguments and result that match the type Tcl_CommandTraceProc:

              typedef void Tcl_CommandTraceProc(
                      ClientData clientData,
                      Tcl_Interp *interp,
                      const char *oldName,
                      const char *newName,
                      int flags);

       The clientData and interp parameters  will  have  the  same  values  as  those  passed  to
       Tcl_TraceCommand   when  the  trace  was  created.   ClientData  typically  points  to  an
       application-specific data structure that describes  what  to  do  when  proc  is  invoked.
       OldName  gives  the name of the command being renamed, and newName gives the name that the
       command is being renamed to (or an  empty  string  or  NULL  when  the  command  is  being
       deleted.)   Flags  is an OR'ed combination of bits potentially providing several pieces of
       information.  One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE will be set  in  flags
       to   indicate   which   operation   is   being   performed   on   the  command.   The  bit
       TCL_TRACE_DESTROYED will be set in flags if the trace  is  about  to  be  destroyed;  this
       information may be useful to proc so that it can clean up its own internal data structures
       (see  the  section  TCL_TRACE_DESTROYED  below  for  more  details).   Lastly,   the   bit
       TCL_INTERP_DESTROYED  will be set if the entire interpreter is being destroyed.  When this
       bit is set, proc must be especially careful  in  the  things  it  does  (see  the  section
       TCL_INTERP_DESTROYED below).

       Tcl_UntraceCommand  may  be  used  to remove a trace.  If the command specified by interp,
       cmdName,  and  flags  has  a  trace  set  with  flags,  proc,  and  clientData,  then  the
       corresponding   trace   is   removed.    If  no  such  trace  exists,  then  the  call  to
       Tcl_UntraceCommand has no effect.  The same bits are valid  for  flags  as  for  calls  to
       Tcl_TraceCommand.

       Tcl_CommandTraceInfo  may  be  used  to  retrieve  information about traces set on a given
       command.  The return value from Tcl_CommandTraceInfo is the clientData associated  with  a
       particular  trace.  The trace must be on the command specified by the interp, cmdName, and
       flags arguments (note that currently the flags are ignored; flags should be set to  0  for
       future  compatibility) and its trace procedure must the same as the proc argument.  If the
       prevClientData argument is NULL then the return  value  corresponds  to  the  first  (most
       recently  created)  matching  trace,  or  NULL  if  there  are no matching traces.  If the
       prevClientData argument is not NULL, then it should be the return value  from  a  previous
       call  to  Tcl_CommandTraceInfo.  In this case, the new return value will correspond to the
       next matching trace after the one whose clientData matches prevClientData, or NULL  if  no
       trace  matches  prevClientData  or  if  there  are no more matching traces after it.  This
       mechanism makes it possible to step through all of the traces for  a  given  command  that
       have the same proc.

CALLING COMMANDS DURING TRACES

       During rename traces, the command being renamed is visible with both names simultaneously,
       and the command still exists during delete traces (if TCL_INTERP_DESTROYED  is  not  set).
       However,  there is no mechanism for signaling that an error occurred in a trace procedure,
       so great care should be taken that errors do not get silently lost.

MULTIPLE TRACES

       It is possible for multiple traces to exist on the same command.  When this  happens,  all
       of  the  trace  procedures  will  be  invoked on each access, in order from most-recently-
       created to least-recently-created.  Attempts to delete the command during a  delete  trace
       will  fail  silently,  since the command is already scheduled for deletion anyway.  If the
       command being renamed is renamed  by  one  of  its  rename  traces,  that  renaming  takes
       precedence  over the one that triggered the trace and the collection of traces will not be
       reexecuted; if several traces rename the command, the last renaming takes precedence.

TCL_TRACE_DESTROYED FLAG

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

TCL_INTERP_DESTROYED

       When an interpreter is destroyed, unset traces are called for all of  its  commands.   The
       TCL_INTERP_DESTROYED bit will be set in the flags argument passed to the trace procedures.
       Trace procedures must be extremely careful in what they do if the TCL_INTERP_DESTROYED bit
       is  set.   It  is  not  safe  for  the  procedures  to  invoke  any  Tcl procedures on the
       interpreter, since its state is partially deleted.  All that trace  procedures  should  do
       under these circumstances is to clean up and free their own internal data structures.

BUGS

       Tcl  does  not  do  any  error  checking  to  prevent  trace  procedures from misusing the
       interpreter during traces with TCL_INTERP_DESTROYED set.

KEYWORDS

       clientData, trace, command