Manual Pages for UNIX Operating System command usage for man Tcl_CommandTraceInfo

Tcl Library Procedures                     Tcl_TraceCommand(3TCL)



_________________________________________________________________

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

SYNOPSIS
     #include 

     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  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



Tcl                     Last change: 7.4                        1






Tcl Library Procedures                     Tcl_TraceCommand(3TCL)



                                                       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



Tcl                     Last change: 7.4                        2






Tcl Library Procedures                     Tcl_TraceCommand(3TCL)



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




Tcl                     Last change: 7.4                        3






Tcl Library Procedures                     Tcl_TraceCommand(3TCL)



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


KEYWORDS
     clientData, trace, command

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:











Tcl                     Last change: 7.4                        4






Tcl Library Procedures                     Tcl_TraceCommand(3TCL)



     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.













































Tcl                     Last change: 7.4                        5