tcldbg.man

Linux下的tcl语言调试器

.TH TCLDBG N "5 November 1996" Tcldbg "Tcl Interactive Debugger"

.IX "Expect" "Debugger" "TCL" "TK" "exp_debug" "debug"
.SH NAME
tcl debugger \- interactive debugger for Tcl and Expect
.SH INTRODUCTION
The Tcl debugger allows debugging of Tcl scripts in a manner very similar
to classical debuggers such as dbx and gdb.  The Tcl debugger can be used
with Tcl extensions such as Expect and Tk.  The debugger can:
.TP 5
o
Perform a step-by-step execution of a script and its procedures.
.TP
o
Create user-defined breakpoints. Any number of breakpoints can be set,
and they can be triggered by the value of a variable, by the value of
an expression, or by pattern matching on a command or its arguments.
.BE
You can customize the action taken when a breakpoint is triggered. The
default action is to stop the script's execution, but any block of 
TCL statements can be specified.
.TP
o
Examine the current values of variables and expressions. You can also
step up or down through nested procedures to examine the values of variables
as known by those procedures.
.TP
o
Display the current state of the program stack.
.PP
This man page describes a large percentage of the debugger but does
not describe all of it.  See the Expect book for further discussion of
the debugger including a tutorial.
.SH USAGE
.PP
The debugger may be invoked in two ways: from the UNIX command line or
by a Tcl command.  Not all extensions support both of these.  Since
the Expect extensions supports both, this man page demonstrates the
debugger using Expect.  For example, to start the debugger from the
command line, enter:

      % \fBexpect \-D 1 \-i \fR[ \fIcmdfile\fR ] [ \fIargs\fR ]

where
.I cmdfile
is an optional script file and
.I args 
are optional arguments for the script.

To turn on the debugging flag when you are already in 
.B Tcl's
interactive mode, enter the following command at the
.B Expect
prompt:

      expect1.1> \fBexp_debug 1\fR

This command can also be given as \fBdebug\fR.

Once the debugger flag has been turned on, the debugger is activated
at the next error or signal, or at the next \fBexp_debug\fR (or \fBdebug\fR)
command. 

To turn on the debugger flag and enter the debugger immediately,
enter the following command:

      \fBexp_debug \-now 1\fR

When you are in the \fBTcl\fR
debugger, the prompt changes to \fBdbg\fI#.#\fB\>\fR, where the first
number is the number of pending calls to Tcl_Eval and the second is
the history number (this is the same format as the default \fBExpect\fR
prompt). If you give an incomplete command, the prompt changes to 
\fBdbg+>\fR to indicate additional input is needed.

To leave the debugger and return to the normal \fBTcl\fR
prompt, give the \fBreturn\fR command. 

.TP 6
\fBNOTE:\fR
Unlike \fBExpect's\fR prompts, the debugger prompts cannot
be redefined from within \fBExpect\fR. To change them, you must edit the
\fBDbg.c\fR source file and recompile.

.SH COMMANDS
.PP
When the interactive debugger is running, you can give any TCL or
extension commands. In addition, the following debugger commands are
available:

.TP 6
\fBb\fR
Sets, clears, or shows \fBb\fRreakpoints. See \fBBREAKPOINTS\fR below.
.TP
\fBc\fR
\fBC\fRontinue program execution until the end of the script, until the 
script hits a signal, or until a breakpoint is triggered, whichever
comes first.
.TP
\fBd\fR
Move the scope of the debugger \fBd\fRown one or more levels so as 
to view the state of variables at that level. Use \fBd\fR \fIn\fR to
move \fIn\fR levels down. Use \fBd #\fIn\fR to move to absolute scope
number \fIn\fR.

Changing the scope only changes the view you have of the variables that
are defined at that point. If you continue program execution, the scope
is automatically reset to whatever is appropriate for the next command.
.TP
\fBh\fR
Display a \fBh\fRelp screen listing the debugger commands.
.TP
\fBn\fR
Execute the \fBn\fRext pending command and display the next command to be
executed. If the next command is a complex expression, such as: 

     \fBset a [expr 1+[expr 2+[expr 3+$b]]\fR

\fBn\fR evaluates each sub-expression at a time; \fBn\fR works
outward, using \fBTCL's\fR usual rules of precedence and evaluation.

To step through more than one command, follow \fBn\fR with the number of
expressions to evaluate, such as \fBn 3\fR.
.TP
\fBN\fR
Execute the \fBN\fRext pending command, and if it is a complex expression,
evaluate all parts. Thus, if the next command is:

     \fBset a [expr 1+[expr 2+[expr 3+$b]]\fR

\fBN\fR evaluates all parts and assigns the proper value to \fB$a\fR.

To step through more than one command, follow \fBN\fR with the number of
expressions to evaluate, such as \fBN 3\fR.
.TP
\fBr\fR
Complete execution of the current procedure and \fBr\fReturn to the 
debugger. If no procedure has been called, \fBTcl\fR displays 
\fBnowhere to return to\fR and redisplays the debugger prompt.
.TP
\fBs\fR
If the next pending command is a procedure, \fBs\fRtep into the next procedure
and stop before executing the procedure's first command. If the next
command is not a procedure, \fBs\fR is identical to the \fBn\fR command.

To step through more than one command, follow \fBs\fR with the number of
expressions to evaluate, such as \fBs 3\fR.
.TP
\fBu\fR
Move the scope of the debugger \fBu\fRp one or more levels so as
to view the state of variables at that level. Use \fBu\fR \fIn\fR to
move \fIn\fR levels up. Use \fBu #\fIn\fR to move to absolute scope
number \fIn\fR.

Changing the scope only changes the view you have of the variables that
are defined at that point. If you continue program execution, the scope
is automatically reset to whatever is appropriate for the next command.
.TP
\fBw\fR
Show \fBw\fRhere the current scope of the program is. 0 is the top-level
scope and always shows the command used to invoke the current program.
The last line of the display shows the current value of the Tcl_Eval stack
and the next command to be executed, with all parameters replaced with
their current literal values.

The \fBw\fR command also controls the \fBw\fRindow display. The 

     \fBw \-w\fI n\fR 

command sets the width of the display to \fIn\fR
characters. If a line is longer than this width, the debugger shows 
an ellipses (...) to represent the additional characters. 
The default width is 75. Use 

     \fBw \-w\fR 

to display the current width. 

The \fBw \-c\fR command sets the compression mode, which displays
all control characters using their escape sequences (such as "\\n").
This is particularly useful when procedures and blocks of statements
are spread over several lines and you would prefer to see the entire
definition on one line.

To turn off the compression mode (the default), use 

     \fBw \-c 0\fR

To turn on the compression mode, use 

     \fBw \-c 1\fR

To display the current setting, use 

     \fBw \-c\fR

.PP 
To repeat the last debugger command given, enter a blank line.

.SS BREAKPOINTS
.PP
The \fBb\fR command can be used to set, clear, and display breakpoints
that are used when executing a script (breakpoints are not available for
commands entered at the debugger prompt).
Breakpoints can be triggered either when a given expression becomes true
when evaluated, or when a specified pattern is found in the next command
to be executed. 

An action can be defined along with a breakpoint, so that when the 
breakpoint is triggered, the associated action is performed before the 
debugger prompt reappears. An action can be any set of TCL or extension
commands. Debugger commands can also be included but commands
that that control the flow of program execution (\fBc\fR, \fBn\fR,
\fBN\fR, \fBr\fR, \fBs\fR) are queued until the 
breakpoint action is completed.

If no action was specified when the breakpoint was set, 
the debugger prints the number and definition of the breakpoint that was
triggered before redisplaying the the debugger prompt.

Multiple breakpoints can be triggered at once. If so, all of the 
actions associated with those breakpoints are done.

The following breakpoint commands exist:
.TP 10
\fBb\fR
Display all currently defined breakpoints.
.TP
\fBb if {\fIexpr\fB} then {\fIcommands\fB}
Set a breakpoint based on the value of the given \fIexpr\fR. 
If \fIexpr\fR is true, the \fIcommands\fR are executed and the debugger