Tcl_CreateTrace man page on Minix

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

Tcl_CreateTrace(3)	    Tcl Library Procedures	    Tcl_CreateTrace(3)

______________________________________________________________________________

NAME
       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com‐
       mand 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 con‐
							      taining  command
							      to be traced  or
							      untraced.

       int			   level	    (in)      Only commands at
							      or  below	  this
							      nesting	 level
							      will  be	traced
							      unless	0   is
							      specified.     1
							      means  top-level
							      commands only, 2
							      means  top-level
							      commands	    or
							      those  that  are
							      invoked as imme‐
							      diate	conse‐
							      quences of  exe‐
							      cuting top-level
							      commands (proce‐
							      dure     bodies,
							      bracketed	  com‐
							      mands, etc.) and
							      so on.  A	 value
							      of  0 means that
							      commands at  any
							      level	   are
							      traced.

       int			   flags	    (in)      Flags  governing
							      the trace execu‐
							      tion.  See below
							      for details.

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

       Tcl_CmdTraceProc		   *proc	    (in)      Procedure	    to
							      call   for  each
							      command	that's
							      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		      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 simultaneously 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  applica‐
       tion, 2 for the next-level commands passed to Tcl_Eval as part of pars‐
       ing or interpreting level-1 commands, and so on). The command parameter
       points to a string containing the text of the command, before any argu‐
       ment substitution.  The commandToken parameter is a Tcl	command	 token
       that  identifies the command to be invoked.  The token may be passed to
       Tcl_GetCommandName, Tcl_GetCommandTokenInfo, or Tcl_SetCommandTokenInfo
       to  manipulate the definition of the command. The objc and objv parame‐
       ters designate the final parameter count and parameter vector that will
       be passed to the command, and have had all substitutions 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	inter‐
       preter 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_Create‐
       Trace).

       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 parame‐
       ter 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 per‐
       formance will be improved significantly.	 (This functionality is desir‐
       able, for example, when using Tcl_CreateObjTrace to implement an execu‐
       tion 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 substitu‐
       tions.  If there is a syntax error in a command, or if there is no com‐
       mand procedure associated with a command name,  then  no	 tracing  will
       occur for that command.	If a string passed to Tcl_Eval contains multi‐
       ple 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_CmdObjTraceDeleteProc:
	      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 compati‐
       bility 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_Cmd‐
       TraceProc:
	      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  procedure	that will be invoked; and cmd‐
       ClientData, 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 compila‐
       tion 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_Create‐
       Trace  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)
[top]

List of man pages available for Minix

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