126 lines
5.2 KiB
Groff
126 lines
5.2 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||
|
|
'\" All rights reserved.
|
||
|
|
'\"
|
||
|
|
'\" Permission is hereby granted, without written agreement and without
|
||
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
||
|
|
'\" documentation for any purpose, provided that the above copyright
|
||
|
|
'\" notice and the following two paragraphs appear in all copies.
|
||
|
|
'\"
|
||
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
||
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
||
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
||
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
'\"
|
||
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
||
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
||
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
||
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
||
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
||
|
|
'\"
|
||
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/CrtTrace.3,v 1.8 93/04/01 09:25:26 ouster Exp $ SPRITE (Berkeley)
|
||
|
|
'\"
|
||
|
|
.so man.macros
|
||
|
|
.HS Tcl_CreateTrace tclc
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
Tcl_CreateTrace, 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
|
||
|
|
\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tcl_CmdTraceProc (clientData)()
|
||
|
|
.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. 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.
|
||
|
|
.AP Tcl_CmdTraceProc *proc in
|
||
|
|
Procedure to call for each command that's executed. See below for
|
||
|
|
details on the calling sequence.
|
||
|
|
.AP ClientData clientData in
|
||
|
|
Arbitrary one-word value to pass to \fIproc\fR.
|
||
|
|
.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_CreateTrace\fR arranges for command tracing. From now on, \fIproc\fR
|
||
|
|
will be invoked before Tcl calls command procedures to process
|
||
|
|
commands in \fIinterp\fR. The return value from
|
||
|
|
\fBTcl_CreateTrace\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 command interpreter.
|
||
|
|
.PP
|
||
|
|
\fIProc\fR should have arguments and result that match the
|
||
|
|
type \fBTcl_CmdTraceProc\fR:
|
||
|
|
.nf
|
||
|
|
.sp
|
||
|
|
.RS
|
||
|
|
typedef void Tcl_CmdTraceProc(
|
||
|
|
.RS
|
||
|
|
ClientData \fIclientData\fR,
|
||
|
|
Tcl_Interp *\fIinterp\fR,
|
||
|
|
int \fIlevel\fR,
|
||
|
|
char *\fIcommand\fR,
|
||
|
|
Tcl_CmdProc *\fIcmdProc\fR,
|
||
|
|
ClientData \fIcmdClientData\fR,
|
||
|
|
int \fIargc\fR,
|
||
|
|
char *\fIargv\fR[]));
|
||
|
|
.sp
|
||
|
|
.RE
|
||
|
|
.RE
|
||
|
|
.fi
|
||
|
|
The \fIclientData\fP and \fIinterp\fP 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 \fIproc\fR
|
||
|
|
is invoked. \fILevel\fR 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). \fICommand\fR
|
||
|
|
points to a string containing the text of the
|
||
|
|
command, before any argument substitution.
|
||
|
|
\fICmdProc\fR contains the address of the command procedure that
|
||
|
|
will be called to process the command (i.e. the \fIproc\fR argument
|
||
|
|
of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
|
||
|
|
contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
|
||
|
|
value passed to \fBTcl_CreateCommand\fR). \fIArgc\fR and \fIargv\fR give
|
||
|
|
the final argument information that will be passed to \fIcmdProc\fR, after
|
||
|
|
command, variable, and backslash substitution.
|
||
|
|
\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
|
||
|
|
.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 \fIproc\fR will always be less than or equal to the
|
||
|
|
\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
|
||
|
|
.PP
|
||
|
|
Calls to \fIproc\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 \fIproc\fR will occur,
|
||
|
|
one for each command. The \fIcommand\fR string for each of these
|
||
|
|
trace calls will reflect only a single command, not the entire string
|
||
|
|
passed to Tcl_Eval.
|
||
|
|
.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.
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
command, create, delete, interpreter, trace
|