CentOS 7.0 - man page for tcl_createobjtrace (centos section 3)

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tcl_CreateTrace(3)		      Tcl Library Procedures		       Tcl_CreateTrace(3)

_________________________________________________________________________________________________

NAME
       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for command execution to be
       traced

SYNOPSIS
       #include <tcl.h>

       Tcl_Trace
       Tcl_CreateTrace(interp, level, proc, clientData)

       Tcl_Trace
       Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)

       Tcl_DeleteTrace(interp, trace)

ARGUMENTS
       Tcl_Interp *interp (in)				   Interpreter containing command  to  be
							   traced or untraced.

       int level (in)					   Only commands at or below this nesting
							   level will be traced unless 0 is spec-
							   ified.   1  means  top-level  commands
							   only, 2 means  top-level  commands  or
							   those  that	are  invoked as immediate
							   consequences  of  executing	top-level
							   commands  (procedure bodies, bracketed
							   commands, etc.) and so on.  A value of
							   0 means that commands at any level are
							   traced.

       int flags (in)					   Flags governing the	trace  execution.
							   See below for details.

       Tcl_CmdObjTraceProc *objProc (in)		   Procedure  to  call	for  each command
							   that  is  executed.	 See  below   for
							   details of the calling sequence.

       Tcl_CmdTraceProc *proc (in)			   Procedure  to  call	for  each command
							   that  is  executed.	 See  below   for
							   details on the calling sequence.

       ClientData clientData (in)			   Arbitrary  one-word	value  to pass to
							   objProc or proc.

       Tcl_CmdObjTraceDeleteProc *deleteProc (in)	   Procedure to call when  the	trace  is
							   deleted.  See below for details of the
							   calling sequence.  A NULL  pointer  is
							   permissible and results in no callback
							   when the trace is deleted.

       Tcl_Trace trace (in)				   Token for trace to be removed  (return
							   value  from	previous call to Tcl_Cre-
							   ateTrace).
_________________________________________________________________

DESCRIPTION
       Tcl_CreateObjTrace arranges for command tracing.  After it  is  called,	objProc  will  be
       invoked before the Tcl interpreter calls any command procedure when evaluating commands in
       interp.	The return value from Tcl_CreateObjTrace is a token for the trace, which  may  be
       passed  to Tcl_DeleteTrace to remove the trace.	There may be many traces in effect simul-
       taneously for the same interpreter.

       objProc should have arguments and result that match the type, Tcl_CmdObjTraceProc:
	      typedef int Tcl_CmdObjTraceProc(
		      ClientData clientData,
		      Tcl_Interp* interp,
		      int level,
		      const char *command,
		      Tcl_Command commandToken,
		      int objc,
		      Tcl_Obj *const objv[] );
       The clientData and interp parameters are copies of the corresponding  arguments	given  to
       Tcl_CreateTrace.   ClientData  typically  points to an application-specific data structure
       that describes what to do when objProc is invoked.  The level parameter gives the  nesting
       level  of  the  command (1 for top-level commands passed to Tcl_Eval by the application, 2
       for the next-level commands passed to Tcl_Eval as part of parsing or interpreting  level-1
       commands,  and so on). The command parameter points to a string containing the text of the
       command, before any argument substitution.  The commandToken parameter is  a  Tcl  command
       token  that  identifies the command to be invoked.  The token may be passed to Tcl_GetCom-
       mandName, Tcl_GetCommandInfoFromToken, or Tcl_SetCommandInfoFromToken  to  manipulate  the
       definition  of  the  command.  The  objc and objv parameters designate the final parameter
       count and parameter vector that will be passed to the command, and have had all	substitu-
       tions performed.

       The  objProc  callback  is  expected to return a standard Tcl status return code.  If this
       code is TCL_OK (the normal case), then the Tcl interpreter will invoke the  command.   Any
       other  return  code  is treated as if the command returned that status, and the command is
       not invoked.

       The objProc callback must not modify objv in any way.   It  is,	however,  permissible  to
       change the command by calling Tcl_SetCommandTokenInfo prior to returning.  Any such change
       takes effect immediately, and the command is invoked with the new information.

       Tracing will only occur for commands at nesting level less than	or  equal  to  the  level
       parameter  (i.e.  the  level parameter to objProc will always be less than or equal to the
       level parameter to Tcl_CreateTrace).

       Tracing has a significant effect on runtime performance because	it  causes  the  bytecode
       compiler  to refrain from generating in-line code for Tcl commands such as if and while in
       order that they may be traced.  If traces for the built-in commands are not required,  the
       flags  parameter  may  be set to the constant value TCL_ALLOW_INLINE_COMPILATION.  In this
       case, traces on built-in commands may or may not result in trace callbacks,  depending  on
       the  state  of  the  interpreter, but run-time performance will be improved significantly.
       (This functionality is desirable, for example, when using Tcl_CreateObjTrace to	implement
       an execution time profiler.)

       Calls  to  objProc  will be made by the Tcl parser immediately before it calls the command
       procedure for the command (cmdProc).  This occurs after argument parsing and substitution,
       so  tracing  for substituted commands occurs before tracing of the commands containing the
       substitutions.  If there is a syntax error in a command, or if there is no command  proce-
       dure  associated  with  a command name, then no tracing will occur for that command.  If a
       string passed to Tcl_Eval contains multiple commands (bracketed, or  on	different  lines)
       then multiple calls to objProc will occur, one for each command.

       Tcl_DeleteTrace	removes  a  trace,  so that no future calls will be made to the procedure
       associated with the trace.  After Tcl_DeleteTrace returns, the caller should  never  again
       use the trace token.

       When  Tcl_DeleteTrace is called, the interpreter invokes the deleteProc that was passed as
       a parameter to Tcl_CreateObjTrace.   The  deleteProc  must  match  the  type,  Tcl_CmdObj-
       TraceDeleteProc:
	      typedef void Tcl_CmdObjTraceDeleteProc(
		      ClientData clientData);
       The  clientData parameter will be the same as the clientData parameter that was originally
       passed to Tcl_CreateObjTrace.

       Tcl_CreateTrace is an alternative interface for command tracing, not recommended  for  new
       applications.   It is provided for backward compatibility with code that was developed for
       older versions of the Tcl interpreter.  It is similar to Tcl_CreateObjTrace,  except  that
       its proc parameter should have arguments and result that match the type Tcl_CmdTraceProc:
	      typedef void Tcl_CmdTraceProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      int level,
		      char *command,
		      Tcl_CmdProc *cmdProc,
		      ClientData cmdClientData,
		      int argc,
		      const char *argv[]);
       The  parameters	to  the proc callback are similar to those of the objProc callback above.
       The commandToken is replaced with cmdProc, a pointer to the (string-based) command  proce-
       dure  that  will be invoked; and cmdClientData, the client data that will be passed to the
       procedure.  The objc parameter is replaced with an argv parameter, that	gives  the  argu-
       ments  to  the  command	as  character  strings.  Proc must not modify the command or argv
       strings.

       If a trace created with Tcl_CreateTrace is in effect, inline compilation of  Tcl  commands
       such  as  if  and while is always disabled.  There is no notification when a trace created
       with Tcl_CreateTrace is deleted.  There is no way to be notified when the trace created by
       Tcl_CreateTrace	is  deleted.   There  is  no  way  for the proc associated with a call to
       Tcl_CreateTrace to abort execution of command.

KEYWORDS
       command, create, delete, interpreter, trace

Tcl									       Tcl_CreateTrace(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:06 AM.

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





Not a Forum Member?
Forgot Password?