192 lines
8.3 KiB
Groff
192 lines
8.3 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\" Copyright (c) 2002 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
|