DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CommandTraceInfo(3tcl)




Tcl_TraceCommand(3)  Tcl Library Procedures   Tcl_TraceCommand(3)

_________________________________________________________________


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   com-
                                                       mand.

     const char *cmdName (in)                          Name    of
                                                       command.

     int flags (in)                                    OR'ed col-
                                                       lection 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

Tcl                     Last change: 7.4                        1

Tcl_TraceCommand(3)  Tcl Library Procedures   Tcl_TraceCommand(3)

                                                       by
                                                       Tcl_CommandTraceInfo,
                                                       so    this
                                                       call  will
                                                       return
                                                       informa-
                                                       tion about
                                                       next
                                                       trace.  If
                                                       NULL, this
                                                       call  will
                                                       return
                                                       informa-
                                                       tion 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  com-
     mand,  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 com-
     mand  being  renamed,  and  newName  gives the name that the

Tcl                     Last change: 7.4                        2

Tcl_TraceCommand(3)  Tcl Library Procedures   Tcl_TraceCommand(3)

     command is being renamed to (or an empty string or NULL when
     the  command  is being deleted.)  Flags is an OR'ed combina-
     tion of bits potentially providing several pieces of  infor-
     mation.     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  struc-
     tures  (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 speci-
     fied 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 match-
     ing 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


Tcl                     Last change: 7.4                        3

Tcl_TraceCommand(3)  Tcl Library Procedures   Tcl_TraceCommand(3)

     It is possible for multiple traces to exist on the same com-
     mand.   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 inter-
     preter, 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  pro-
     cedures  from  misusing  the  interpreter during traces with
     TCL_INTERP_DESTROYED set.


KEYWORDS

     clientData, trace, command

Tcl                     Last change: 7.4                        4


Man(1) output converted with man2html