Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenDarwin 7.2.1 - man page for tcl_commandtraceinfo (opendarwin section 3)

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    value
							 TCL_TRACE_RENAME and TCL_TRACE_DELETE.

       Tcl_CommandTraceProc   *proc	       (in)	 Procedure  to call when specified opera-
							 tions 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 applica-
       tion-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 correspond-
       ing 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 com-
       mand.  The return value from Tcl_CommandTraceInfo is the clientData associated with a par-
       ticular	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 pre-
       vClientData 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-cre-
       ated 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 procedures from misusing the inter-
       preter during traces with TCL_INTERP_DESTROYED set.

KEYWORDS
       clientData, trace, command

Tcl					       7.4			      Tcl_TraceCommand(3)


All times are GMT -4. The time now is 05:18 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password