diff options
Diffstat (limited to 'tcl8.6/doc/CrtTrace.3')
-rw-r--r-- | tcl8.6/doc/CrtTrace.3 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/tcl8.6/doc/CrtTrace.3 b/tcl8.6/doc/CrtTrace.3 new file mode 100644 index 0000000..d5353ac --- /dev/null +++ b/tcl8.6/doc/CrtTrace.3 @@ -0,0 +1,191 @@ +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +Tcl_Trace +\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR) +.sp +Tcl_Trace +\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) +.sp +\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) +.SH ARGUMENTS +.AS Tcl_CmdObjTraceDeleteProc *deleteProc +.AP Tcl_Interp *interp in +Interpreter containing command to be traced or untraced. +.AP 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 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. +.AP int flags in +Flags governing the trace execution. See below for details. +.AP Tcl_CmdObjTraceProc *objProc in +Procedure to call for each command that is executed. See below for +details of the calling sequence. +.AP Tcl_CmdTraceProc *proc in +Procedure to call for each command that is executed. See below for +details on the calling sequence. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. +.AP 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. +.AP Tcl_Trace trace in +Token for trace to be removed (return value from previous call +to \fBTcl_CreateTrace\fR). +.BE +.SH DESCRIPTION +.PP +\fBTcl_CreateObjTrace\fR arranges for command tracing. After it is +called, \fIobjProc\fR will be invoked before the Tcl interpreter calls +any command procedure when evaluating commands in \fIinterp\fR. +The return value from \fBTcl_CreateObjTrace\fR is a token for the trace, +which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. +There may be many traces in effect simultaneously for the same +interpreter. +.PP +\fIobjProc\fR should have arguments and result that match the type, +\fBTcl_CmdObjTraceProc\fR: +.PP +.CS +typedef int \fBTcl_CmdObjTraceProc\fR( + \fBClientData\fR \fIclientData\fR, + \fBTcl_Interp\fR* \fIinterp\fR, + int \fIlevel\fR, + const char *\fIcommand\fR, + \fBTcl_Command\fR \fIcommandToken\fR, + int \fIobjc\fR, + \fBTcl_Obj\fR *const \fIobjv\fR[]); +.CE +.PP +The \fIclientData\fR and \fIinterp\fR parameters are copies of the +corresponding arguments given to \fBTcl_CreateTrace\fR. +\fIClientData\fR typically points to an application-specific data +structure that describes what to do when \fIobjProc\fR is invoked. The +\fIlevel\fR parameter gives the nesting level of the command (1 for +top-level commands passed to \fBTcl_Eval\fR by the application, 2 for +the next-level commands passed to \fBTcl_Eval\fR as part of parsing or +interpreting level-1 commands, and so on). The \fIcommand\fR parameter +points to a string containing the text of the command, before any +argument substitution. The \fIcommandToken\fR parameter is a Tcl +command token that identifies the command to be invoked. The token +may be passed to \fBTcl_GetCommandName\fR, +\fBTcl_GetCommandInfoFromToken\fR, or \fBTcl_SetCommandInfoFromToken\fR to +manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR +parameters designate the final parameter count and parameter vector +that will be passed to the command, and have had all substitutions +performed. +.PP +The \fIobjProc\fR callback is expected to return a standard Tcl status +return code. If this code is \fBTCL_OK\fR (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 +\fInot\fR invoked. +.PP +The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It +is, however, permissible to change the command by calling +\fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change +takes effect immediately, and the command is invoked with the new +information. +.PP +Tracing will only occur for commands at nesting level less than +or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR +parameter to \fIobjProc\fR will always be less than or equal to the +\fIlevel\fR parameter to \fBTcl_CreateTrace\fR). +.PP +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 \fBif\fR and \fBwhile\fR in order that they +may be traced. If traces for the built-in commands are not required, +the \fIflags\fR parameter may be set to the constant value +\fBTCL_ALLOW_INLINE_COMPILATION\fR. 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 \fBTcl_CreateObjTrace\fR to implement an execution time +profiler.) +.PP +Calls to \fIobjProc\fR will be made by the Tcl parser immediately before +it calls the command procedure for the command (\fIcmdProc\fR). 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 procedure 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 \fIobjProc\fR will occur, +one for each command. +.PP +\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be +made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR +returns, the caller should never again use the \fItrace\fR token. +.PP +When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the +\fIdeleteProc\fR that was passed as a parameter to +\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, +\fBTcl_CmdObjTraceDeleteProc\fR: +.PP +.CS +typedef void \fBTcl_CmdObjTraceDeleteProc\fR( + \fBClientData\fR \fIclientData\fR); +.CE +.PP +The \fIclientData\fR parameter will be the same as the +\fIclientData\fR parameter that was originally passed to +\fBTcl_CreateObjTrace\fR. +.PP +\fBTcl_CreateTrace\fR is an alternative interface for command tracing, +\fInot recommended for new applications\fR. It is provided for backward +compatibility with code that was developed for older versions of the +Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except +that its \fIproc\fR parameter should have arguments and result that +match the type \fBTcl_CmdTraceProc\fR: +.PP +.CS +typedef void \fBTcl_CmdTraceProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + int \fIlevel\fR, + char *\fIcommand\fR, + Tcl_CmdProc *\fIcmdProc\fR, + ClientData \fIcmdClientData\fR, + int \fIargc\fR, + const char *\fIargv\fR[]); +.CE +.PP +The parameters to the \fIproc\fR callback are similar to those of the +\fIobjProc\fR callback above. The \fIcommandToken\fR is +replaced with \fIcmdProc\fR, a pointer to the (string-based) command +procedure that will be invoked; and \fIcmdClientData\fR, the client +data that will be passed to the procedure. The \fIobjc\fR parameter +is replaced with an \fIargv\fR parameter, that gives the arguments to +the command as character strings. +\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. +.PP +If a trace created with \fBTcl_CreateTrace\fR is in effect, inline +compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always +disabled. There is no notification when a trace created with +\fBTcl_CreateTrace\fR is deleted. +There is no way to be notified when the trace created by +\fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR +associated with a call to \fBTcl_CreateTrace\fR to abort execution of +\fIcommand\fR. +.SH KEYWORDS +command, create, delete, interpreter, trace |