Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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  un-

       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 in-
							   voked as  immediate
							   consequences	of ex-
							   ecuting   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 de-

       Tcl_CmdObjTraceProc *objProc (in)		   Procedure  to  call
							   for	 each  command
							   that	 is  executed.
							   See	below  for de-
							   tails of the	 call-
							   ing sequence.

       Tcl_CmdTraceProc	*proc (in)			   Procedure  to  call
							   for	each   command
							   that	 is  executed.
							   See below  for  de-
							   tails  on the call-
							   ing 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 re-
							   sults  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 ef-
       fect simultaneously for the same	interpreter.

       objProc should have arguments and result	that match the	type,  Tcl_Cm-

	      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 ob-
       jProc 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 af-
       ter  argument parsing and substitution, so tracing for substituted com-
       mands 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 oc-
       cur for that command.  If a string passed to Tcl_Eval contains multiple
       commands	(bracketed, or on different lines) then	multiple calls to  ob-
       jProc 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  re-
       turns, 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  in-
       terpreter.   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)


Want to link to this manual page? Use this URL:

home | help