Tcl_CreateTrace man page on AIX

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

Tcl_CreateTrace(3)	    Tcl Library Procedures	    Tcl_CreateTrace(3)


       Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for com‐
       mand execution to be traced

       #include <tcl.h>

       Tcl_CreateTrace(interp, level, proc, clientData)

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

       Tcl_DeleteTrace(interp, trace)

       Tcl_Interp *interp (in)				   Interpreter	  con‐
							   taining  command to
							   be	 traced	    or

       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  immedi‐
							   ate consequences of
							   executing top-level
							   commands (procedure
							   bodies,   bracketed
							   commands, etc.) and
							   so on.  A value  of
							   0  means  that com‐
							   mands at any	 level
							   are traced.

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

       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 call‐
							   back when the trace
							   is deleted.

       Tcl_Trace trace (in)				   Token  for trace to
							   be removed  (return
							   value from previous
							   call to Tcl_Create‐

       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,
	      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_GetCommandInfoFromToken,  or Tcl_SetCommandIn‐
       foFromToken to manipulate the definition of the command. The  objc  and
       objv  parameters designate the final parameter count and parameter vec‐
       tor that will be passed to the command, and have had all	 substitutions

       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‐

       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‐
	      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.

       command, create, delete, interpreter, trace

Tcl							    Tcl_CreateTrace(3)
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

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]
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