home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / CrtTrace.3 < prev    next >
Encoding:
Text File  |  1995-07-10  |  5.6 KB  |  133 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/CrtTrace.3,v 1.8 93/04/01 09:25:26 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. '\"----------------------------------------------------------------------------
  24. '\"    @(#) CrtTrace.3 26.1 93/10/22 SCOINC
  25. '\"
  26. '\"     Copyright (C) The Santa Cruz Operation, 1992-1993.
  27. '\"     This Module contains Proprietary Information of
  28. '\"    The Santa Cruz Operation, and should be treated as Confidential.
  29. '\"----------------------------------------------------------------------------
  30. .so ../man.macros
  31. .HS Tcl_CreateTrace tclc
  32. .BS
  33. .SH NAME
  34. Tcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include <tcl.h>\fR
  38. .sp
  39. Tcl_Trace
  40. \fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
  41. .sp
  42. \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
  43. .SH ARGUMENTS
  44. .AS Tcl_CmdTraceProc (clientData)()
  45. .AP Tcl_Interp *interp in
  46. Interpreter containing command to be traced or untraced.
  47. .AP int level in
  48. Only commands at or below this nesting level will be traced.  1 means
  49. top-level commands only, 2 means top-level commands or those that are
  50. invoked as immediate consequences of executing top-level commands
  51. (procedure bodies, bracketed commands, etc.) and so on.
  52. .AP Tcl_CmdTraceProc *proc in
  53. Procedure to call for each command that's executed.  See below for
  54. details on the calling sequence.
  55. .AP ClientData clientData in
  56. Arbitrary one-word value to pass to \fIproc\fR.
  57. .AP Tcl_Trace trace in
  58. Token for trace to be removed (return value from previous call
  59. to \fBTcl_CreateTrace\fR).
  60. .BE
  61.  
  62. .SH DESCRIPTION
  63. .PP
  64. \fBTcl_CreateTrace\fR arranges for command tracing.  From now on, \fIproc\fR
  65. will be invoked before Tcl calls command procedures to process
  66. commands in \fIinterp\fR.  The return value from
  67. \fBTcl_CreateTrace\fR is a token for the trace,
  68. which may be passed to \fBTcl_DeleteTrace\fR to remove the trace.  There may
  69. be many traces in effect simultaneously for the same command interpreter.
  70. .PP
  71. \fIProc\fR should have arguments and result that match the
  72. type \fBTcl_CmdTraceProc\fR:
  73. .nf
  74. .sp
  75. .RS
  76. typedef void Tcl_CmdTraceProc(
  77. .RS
  78. ClientData \fIclientData\fR,
  79. Tcl_Interp *\fIinterp\fR,
  80. int \fIlevel\fR,
  81. char *\fIcommand\fR,
  82. Tcl_CmdProc *\fIcmdProc\fR,
  83. ClientData \fIcmdClientData\fR,
  84. int \fIargc\fR,
  85. char *\fIargv\fR[]));
  86. .sp
  87. .RE
  88. .RE
  89. .fi
  90. The \fIclientData\fP and \fIinterp\fP parameters are
  91. copies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
  92. \fIClientData\fR typically points to an application-specific
  93. data structure that describes what to do when \fIproc\fR
  94. is invoked.  \fILevel\fR gives the nesting level of the command
  95. (1 for top-level commands passed to \fBTcl_Eval\fR by the application,
  96. 2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
  97. or interpreting level-1 commands, and so on).  \fICommand\fR
  98. points to a string containing the text of the
  99. command, before any argument substitution.
  100. \fICmdProc\fR contains the address of the command procedure that
  101. will be called to process the command (i.e. the \fIproc\fR argument
  102. of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
  103. contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
  104. value passed to \fBTcl_CreateCommand\fR).  \fIArgc\fR and \fIargv\fR give
  105. the final argument information that will be passed to \fIcmdProc\fR, after
  106. command, variable, and backslash substitution.
  107. \fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
  108. .PP
  109. Tracing will only occur for commands at nesting level less than
  110. or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
  111. parameter to \fIproc\fR will always be less than or equal to the
  112. \fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
  113. .PP
  114. Calls to \fIproc\fR will be made by the Tcl parser immediately before
  115. it calls the command procedure for the command (\fIcmdProc\fR).  This
  116. occurs after argument parsing and substitution, so tracing for
  117. substituted commands occurs before tracing of the commands
  118. containing the substitutions.  If there is a syntax error in a
  119. command, or if there is no command procedure associated with a
  120. command name, then no tracing will occur for that command.  If a
  121. string passed to Tcl_Eval contains multiple commands (bracketed, or
  122. on different lines) then multiple calls to \fIproc\fR will occur,
  123. one for each command.  The \fIcommand\fR string for each of these
  124. trace calls will reflect only a single command, not the entire string
  125. passed to Tcl_Eval.
  126. .PP
  127. \fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
  128. made to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR
  129. returns, the caller should never again use the \fItrace\fR token.
  130.  
  131. .SH KEYWORDS
  132. command, create, delete, interpreter, trace
  133.