home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 0 / 0998 / CreateTrac.3 < prev    next >
Text File  |  1990-12-28  |  4KB  |  105 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/tcl/RCS/Tcl_CreateTrace.man,v 1.2 89/03/24 14:16:01 ouster Exp $ SPRITE (Berkeley)
  10. '\" 
  11. .so \*(]ltmac.sprite
  12. .HS Tcl_CreateTrace tcl
  13. .BS
  14. .SH NAME
  15. Tcl_CreateTrace \- arrange for command execution to be traced
  16. .SH SYNOPSIS
  17. .nf
  18. \fB#include <tcl.h>\fR
  19. .sp
  20. Tcl_Trace
  21. \fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
  22. .SH ARGUMENTS
  23. .AS ClientData (clientData)()
  24. .AP Tcl_Interp *interp in
  25. Interpreter in which to create new command.
  26. .AP int level in
  27. Only commands at or below this nesting level will be traced.  1 means
  28. top-level commands only, 2 means top-level commands or those that are
  29. invoked as immediate consequences of executing top-level commands
  30. (procedure bodies, bracketed commands, etc.) and so on.
  31. .AP void (*proc)() in
  32. Procedure to call for each command that's executed.  See below for
  33. details on the calling sequence.
  34. .AP ClientData clientData in
  35. Arbitrary one-word value to pass to \fIproc\fR.
  36. .BE
  37.  
  38. .SH DESCRIPTION
  39. .PP
  40. \fBTcl_CreateTrace\fR arranges for command tracing.  From now on, \fIproc\fR
  41. will be invoked before Tcl calls command procedures to process
  42. commands in \fIinterp\fR.  The return value from
  43. \fBTcl_CreateTrace\fR is a token for the trace,
  44. which may be passed to \fBTcl_DeleteTrace\fR to remove the trace.  There may
  45. be many traces in effect simultaneously for the same command interpreter.
  46. .PP
  47. \fIProc\fR should have the following structure:
  48. .nf
  49. .RS
  50. void
  51. proc(\fIclientData, interp, level, command, cmdProc, cmdClientData, argc, argv\fP)
  52. .RS
  53. ClientData \fIclientData\fP;
  54. Tcl_Interp *\fIinterp\fP;
  55. int \fIlevel\fP;
  56. char *\fIcommand\fP;
  57. int (*\fIcmdProc\fP)();
  58. ClientData \fIcmdClientData\fP;
  59. int \fIargc\fP;
  60. char *\fIargv\fP[];
  61. .RE
  62. {
  63. }
  64. .RE
  65. .fi
  66. The \fIclientData\fP and \fIinterp\fP parameters are
  67. copies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
  68. \fIClientData\fR typically points to an application-specific
  69. data structure that describes what to do when \fIproc\fR
  70. is invoked.  \fILevel\fR gives the nesting level of the command
  71. (1 for top-level commands passed to \fBTcl_Eval\fR by the application,
  72. 2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
  73. or interpreting level-1 commands, and so on).  \fICommand\fR
  74. points to a string containing the text of the
  75. command, before any argument substitution.
  76. \fICmdProc\fR contains the address of the command procedure that
  77. will be called to process the command (i.e. the \fIproc\fR argument
  78. of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
  79. contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
  80. value passed to \fBTcl_CreateCommand\fR).  \fIArgc\fR and \fIargv\fR give
  81. the final argument information that will be passed to \fIcmdProc\fR, after
  82. command, variable, and backslash substitution.
  83. \fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
  84. .PP
  85. Tracing will only occur for commands at nesting level less than
  86. or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
  87. parameter to \fIproc\fR will always be less than or equal to the
  88. \fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
  89. .PP
  90. Calls to \fIproc\fR will be made by the Tcl parser immediately before
  91. it calls the command procedure for the command (\fIcmdProc\fR).  This
  92. occurs after argument parsing and substitution, so tracing for
  93. substituted commands occurs before tracing of the commands
  94. containing the substitutions.  If there is a syntax error in a
  95. command, or if there is no command procedure associated with a
  96. command name, then no tracing will occur for that command.  If a
  97. string passed to Tcl_Eval contains multiple commands (bracketed, or
  98. on different lines) then multiple calls to \fIproc\fR will occur,
  99. one for each command.  The \fIcommand\fR string for each of these
  100. trace calls will reflect only a single command, not the entire string
  101. passed to Tcl_Eval.
  102.  
  103. .SH KEYWORDS
  104. command, create, interpreter, trace
  105.