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  value  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 isn't 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 doesn't do any error checking to prevent trace procedures from misusing the interpreter during traces
       with TCL_INTERP_DESTROYED set.

KEYWORDS

       clientData, trace, command

Tcl                                                    7.4                                Tcl_TraceCommand(3tcl)