320 lines
7.9 KiB
Groff
320 lines
7.9 KiB
Groff
.\" $Header$
|
|
.TH GRIND 1ACK
|
|
.SH NAME
|
|
grind \- source-level debugger for ACK
|
|
.SH SYNOPSIS
|
|
.B grind
|
|
[
|
|
.I <ACK object file>
|
|
]
|
|
[
|
|
.I <object file>
|
|
]
|
|
.SH DESCRIPTION
|
|
.B Grind
|
|
is a utility for source-level debugging and execution of
|
|
programs written in C, Modula-2, or Pascal.
|
|
Its operation resembles the operation of
|
|
.IR dbx ,
|
|
a source-level debugger
|
|
available on many Unix systems. However, some
|
|
.B grind
|
|
commands are not available in
|
|
.IR dbx ,
|
|
some more
|
|
.I dbx
|
|
commands are not available in
|
|
.BR grind ,
|
|
and some things are just plain different.
|
|
.LP
|
|
.I <object file>
|
|
is an object file, produced by
|
|
.IR ack (1ACK)
|
|
with the
|
|
.B \-g
|
|
option to include a symbol table.
|
|
.LP
|
|
If no
|
|
.I <object file>
|
|
is specified, "a.out" is used.
|
|
.LP
|
|
For some machines, the debugger does not recognize the object file
|
|
format. For these machines, the result of the
|
|
.IR led (6ACK)
|
|
program must be saved and offered to
|
|
.BR grind .
|
|
.SH USAGE
|
|
Some
|
|
.B grind
|
|
commands take an expression argument.
|
|
.SS Expressions
|
|
.B Grind
|
|
expressions are combinations of variables, constants, and operators.
|
|
The syntax and the operators depend on the source language of the program
|
|
being debugged. However, the type rules are probably less strict than the
|
|
rules of this language. For instance, in Modula-2 one cannot combine
|
|
values of type INTEGER with values of type REAL in an expression without
|
|
using conversion routines. In
|
|
.BR grind ,
|
|
the conversions needed are performed automatically.
|
|
.SS Operators
|
|
.LP
|
|
.B Grind
|
|
supports operators for addition, subtraction, multiplication, division,
|
|
remainder, bitwise or, bitwise xor, bitwise and, boolean or,
|
|
boolean and, left-shift, right-shift, address-of, dereference, less than,
|
|
less than or equal, equal, not equal, greater than, greater than or equal,
|
|
selection.
|
|
.LP
|
|
The syntax and priority of these operators depends on the source language.
|
|
Parentheses can be used for grouping.
|
|
.SS "Scope Rules"
|
|
.LP
|
|
.B Grind
|
|
uses the current file and function to resolve scope conflicts.
|
|
Their values are updated as files and functions are entered and exited
|
|
during execution.
|
|
Names can also be qualified with procedure- or module names, as in
|
|
\fImodule\fP`\fIproc\fP`\fIname\fP.
|
|
.B Grind
|
|
tries to be intelligent about names; qualification is only needed when
|
|
names are used for more than one object in a program and the current scope
|
|
does not help.
|
|
.SS "Positions"
|
|
In general, there are two ways to specify a position; the first way is
|
|
to specify file name and line number, in a so-called at-clause, like this:
|
|
.RS
|
|
\fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
|
|
.RE
|
|
The
|
|
.I filename
|
|
part is optional.
|
|
The second way is to specify a function name, like this:
|
|
.RS
|
|
\fBin \fIfunction\fP
|
|
.RE
|
|
This indicates the first statement within the named function (except for
|
|
the trace command discussed later).
|
|
.SS "Commands"
|
|
.TP
|
|
.B ^C
|
|
Interrupt. Stop the program being debugged and enter
|
|
.BR grind .
|
|
.TP
|
|
\fBrun\fP [ \fIargs\fP ] [ < \fIinfile\fP ] [ > \fIoutfile\fP ]
|
|
Start executing
|
|
.I <object file>
|
|
with command line arguments
|
|
.IR args ,
|
|
and possible redirection of standard input and/or standard output.
|
|
.TP
|
|
.B rerun
|
|
Repeats the last
|
|
.B run
|
|
command.
|
|
.TP
|
|
\fBcont\fP [ \fBat\fP \fIsourceline\fP ]
|
|
.ti -0.5i
|
|
\fBc\fP [ \fBat\fP \fIsourceline\fP ]
|
|
.br
|
|
Continue execution from where it stopped, or, if \fIsourceline\fP is
|
|
given, at that source line.
|
|
.TP
|
|
\fBtrace\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
|
|
.ti -0.5i
|
|
\fBt\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
|
|
.br
|
|
Display tracing information.
|
|
If no argument is specified, each source line is displayed before
|
|
execution.
|
|
In addition, if an \fBon\fP-clause is given, the value of the expression
|
|
is printed.
|
|
If a position is given there are two possibilities: if the position is
|
|
given as \fBin\fP \fIfunction\fP, then the tracing information is
|
|
displayed only while executing the function or
|
|
procedure
|
|
.IR function .
|
|
If the position is given as \fBat\fP \fIlinenumber\fP,
|
|
then the tracing information is displayed only whenever the source line
|
|
indicated is reached.
|
|
If a condition is given, tracing information is only displayed when
|
|
.I condition
|
|
is true.
|
|
.TP
|
|
\fBstop\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
|
|
Stop execution when the
|
|
.I position
|
|
is reached, and then when
|
|
.I condition
|
|
becomes true.
|
|
If no position is given, stop when
|
|
.I condition
|
|
becomes true.
|
|
If no condition is given, stop when
|
|
.I position
|
|
is reached.
|
|
Either a position or a condition (or both) must be given.
|
|
.TP
|
|
\fBwhen\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ] { \fIcommand\fP [ ; \fIcommand ] ... }
|
|
Execute the
|
|
.B grind
|
|
.IR command (s)
|
|
when the
|
|
.I position
|
|
is reached, and then when
|
|
.I condition
|
|
becomes true.
|
|
If no position is given, stop when
|
|
.I condition
|
|
becomes true.
|
|
If no condition is given, stop when
|
|
.I position
|
|
is reached.
|
|
Either a position or a condition (or both) must be given.
|
|
.TP
|
|
\fBprint\fP \fIexpression\fP [ , \fIexpression\fP ] ...
|
|
.ti -0.5i
|
|
\fBp\fP \fIexpression\fP [ , \fIexpression\fP ] ...
|
|
.br
|
|
Print the value of each expression.
|
|
.TP
|
|
\fBdisplay\fP \fIexpression\fP [ , \fIexpression\fP ] ...
|
|
Print the value of each expression whenever the program stops.
|
|
.TP
|
|
.B dump
|
|
Saves the data (global data + stack) of the program. These data can
|
|
be restore with the
|
|
.B restore
|
|
command discussed later.
|
|
.B Dump
|
|
and
|
|
.B restore
|
|
combinations can be used as a poor man's implementation of an "undo"
|
|
facility.
|
|
.TP
|
|
.B status
|
|
Display active
|
|
.BR trace ,
|
|
.BR stop ,
|
|
.BR when ,
|
|
and
|
|
.B display
|
|
commands, and associated command numbers.
|
|
Also display current
|
|
.B dump
|
|
records.
|
|
.TP
|
|
\fBdelete\fP \fIcommandnumber\fP
|
|
.ti -0.5i
|
|
\fBd\fP \fIcommandnumber\fP
|
|
.br
|
|
Remove the command corresponding to \fIcommandnumber\fP
|
|
(as displayed by
|
|
.BR status ).
|
|
.TP
|
|
\fBrestore\fP \fIcommandnumber\fP
|
|
.ti -0.5i
|
|
\fBr\fP \fIcommandnumber\fP
|
|
.br
|
|
Restore the data corresponding to the dump of \fIcommandnumber\fP
|
|
(as displayed by
|
|
.BR status ).
|
|
This restores the values of all variables of the program to the values
|
|
at the time the dump was made. The program counter is also restored.
|
|
This effectively puts the program back into the state it was when the
|
|
dump was made, except for file-handling: the state of the files that
|
|
the program handles is not changed.
|
|
Apart from this,
|
|
.B restore
|
|
even works when the program is finished.
|
|
.TP
|
|
\fBstep\fP [ \fIn\fP ]
|
|
.ti -0.5i
|
|
\fBs\fP [ \fIn\fP ]
|
|
.br
|
|
Execute the next
|
|
.I n
|
|
source lines.
|
|
If omitted,
|
|
.I n
|
|
is taken to be 1.
|
|
This command steps into functions.
|
|
.TP
|
|
\fBnext\fP [ \fIn\fP ]
|
|
.ti -0.5i
|
|
\fBn\fP [ \fIn\fP ]
|
|
.br
|
|
Execute the next
|
|
.I n
|
|
source lines.
|
|
If omitted,
|
|
.I n
|
|
is taken to be 1.
|
|
.B Next
|
|
steps past function-calls.
|
|
.TP
|
|
\fBwhich\fP \fIname\fP
|
|
Print the fully-qualified name of the given name.
|
|
.TP
|
|
\fBfind\fP \fIname\fP
|
|
Print the fully qualified name of all symbols matching
|
|
.IR name .
|
|
.TP
|
|
\fBset\fP \fIexpression\fP \fBto\fP \fIexpression\fP
|
|
Assign the value of the second
|
|
.I expression
|
|
to the designator indicated by the first
|
|
.IR expression .
|
|
Needless to say, the first
|
|
.I expression
|
|
must indicate a designator (something that can be assigned to).
|
|
If the types do not match,
|
|
.B grind
|
|
tries to apply conversions.
|
|
.TP
|
|
\fBwhere\fP [ \fIn\fP ]
|
|
List all, or the top
|
|
.IR n ,
|
|
active functions on the stack.
|
|
.TP
|
|
\fBfile\fP [ \fIfilename\fP ]
|
|
Print the name of the current source file, or
|
|
change the current source file to
|
|
.IR filename .
|
|
.TP
|
|
\fBlist\fP [ \fIstartline\fP [ , \fIendline\fP ] | \fIfunction\fP ]
|
|
.ti -0.5i
|
|
\fBl\fP [ \fIstartline\fP [ , \fIendline\fP ] | \fIfunction\fP ]
|
|
.br
|
|
If no arguments are given, list the next ten lines from current source file,
|
|
if a
|
|
.I startline
|
|
is given, list from
|
|
.I startline
|
|
through
|
|
.IR endline ,
|
|
or
|
|
list from five lines above, to five lines below
|
|
the first statement of
|
|
.IR function .
|
|
.TP
|
|
.B quit
|
|
Exit
|
|
.BR grind .
|
|
.LP
|
|
Some commands can be repeated by entering an empty command line: step,
|
|
next, print, list, status, cont.
|
|
.SH ENVIRONMENT
|
|
P.M.
|
|
.SH SEE ALSO
|
|
.IR ack (1ACK).
|
|
.IR led (6ACK).
|
|
.SH REMARKS
|
|
.LP
|
|
.B Grind
|
|
does not understand the scope of WITH statements. The scope information needed
|
|
is not available in the symbol table.
|
|
.SH BUGS
|
|
.LP
|
|
.B Grind
|
|
does not correctly handle bit-fields.
|