Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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 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_Com-mandTraceInfo, Tcl_CommandTraceInfo,
                                                         mandTraceInfo, 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  success-fully successfully
       fully  then Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName specifies a non-exis-tent non-existent
       tent 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  con-sists consists
       sists 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 sec-tion section
       tion 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  cur-rently currently
       rently the flags are ignored; flags should be set to 0 for future compatibility) and its trace proce-dure procedure
       dure 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 match-ing matching
       ing 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-cre-ated. least-recently-created.
       ated.   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  prece-dence. precedence.
       dence.

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  par-tially partially
       tially  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



Tcl                                                  7.4                                 Tcl_TraceCommand(3)