Tcl_CommandTraceInfo man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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  contain‐
							 ing 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  cmd‐
							 Name.

       ClientData	      clientData       (in)	 Arbitrary argument to
							 pass to proc.

       ClientData	      prevClientData   (in)	 If  non-NULL,	 gives
							 last  value  returned
							 by  Tcl_CommandTrace‐
							 Info,	so  this  call
							 will return  informa‐
							 tion	 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  com‐
       mand  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	proce‐
       dure  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 typ‐
       ically 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 spec‐
       ified  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	 argu‐
       ment  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 mis‐
       using the interpreter during traces with TCL_INTERP_DESTROYED set.

KEYWORDS
       clientData, trace, command

Tcl				      7.4		   Tcl_TraceCommand(3)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net