diff options
Diffstat (limited to 'doc/CrtTrace.3')
| -rw-r--r-- | doc/CrtTrace.3 | 67 |
1 files changed, 18 insertions, 49 deletions
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index 519f348..ec83c91 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -1,16 +1,16 @@ '\" '\" 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. +'\" 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_CreateObjTrace2, Tcl_DeleteTrace \- arrange for command execution to be traced +Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,9 +21,6 @@ Tcl_Trace Tcl_Trace \fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) .sp -Tcl_Trace -\fBTcl_CreateObjTrace2\fR(\fIinterp, level, flags, objProc2, clientData, deleteProc\fR) -.sp \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) .SH ARGUMENTS .AS Tcl_CmdObjTraceDeleteProc *deleteProc @@ -41,14 +38,11 @@ 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_CmdObjTraceProc2 *objProc2 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 void *clientData in -Arbitrary one-word value to pass to \fIobjProc\fR, \fIobjProc2\fR or \fIproc\fR. +.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 @@ -69,32 +63,16 @@ interpreter. .PP \fIobjProc\fR should have arguments and result that match the type, \fBTcl_CmdObjTraceProc\fR: -.PP .CS -typedef int \fBTcl_CmdObjTraceProc\fR( - \fBvoid *\fR \fIclientData\fR, +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[]); + \fBTcl_Obj\fR *const \fIobjv\fR[] ); .CE -.PP -\fIobjProc2\fR should have arguments and result that match the type, -\fBTcl_CmdObjTraceProc2\fR: -.PP -.CS -typedef int \fBTcl_CmdObjTraceProc2\fR( - \fBvoid *\fR \fIclientData\fR, - \fBTcl_Interp\fR* \fIinterp\fR, - Tcl_Size \fIlevel\fR, - const char *\fIcommand\fR, - \fBTcl_Command\fR \fIcommandToken\fR, - Tcl_Size \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 @@ -119,7 +97,11 @@ 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. +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 @@ -157,12 +139,10 @@ 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( - \fBvoid *\fR \fIclientData\fR); +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. @@ -173,19 +153,17 @@ 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( - void *\fIclientData\fR, +typedef void Tcl_CmdTraceProc( + ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIlevel\fR, char *\fIcommand\fR, Tcl_CmdProc *\fIcmdProc\fR, - void *\fIcmdClientData\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 @@ -203,14 +181,5 @@ 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 "REFERENCE COUNT MANAGEMENT" -.PP -When the \fIproc\fR passed to \fBTcl_CreateObjTrace\fR is called, -the values in its \fIobjv\fR argument will have a reference count of -at least 1, with that guaranteed reference being from the Tcl -evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of -those values unless you call \fBTcl_IncrRefCount\fR on them first. -.SH "SEE ALSO" -trace(n) .SH KEYWORDS command, create, delete, interpreter, trace |