diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:51:12 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:51:12 (GMT) |
commit | 3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7 (patch) | |
tree | 69afbb41089c8358615879f7cd3c4cf7997f4c7e /tcl8.6/doc/CrtTrace.3 | |
parent | a0e17db23c0fd7c771c0afce8cce350c98f90b02 (diff) | |
download | blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.zip blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.tar.gz blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.tar.bz2 |
update to tcl/tk 8.6.7
Diffstat (limited to 'tcl8.6/doc/CrtTrace.3')
-rw-r--r-- | tcl8.6/doc/CrtTrace.3 | 191 |
1 files changed, 0 insertions, 191 deletions
diff --git a/tcl8.6/doc/CrtTrace.3 b/tcl8.6/doc/CrtTrace.3 deleted file mode 100644 index d5353ac..0000000 --- a/tcl8.6/doc/CrtTrace.3 +++ /dev/null @@ -1,191 +0,0 @@ -'\" -'\" 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 |