ack/util/grind/grind.1

.\" $Header$
.TH GRIND 1
.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
.I dbx
commands are not available in
.BR grind ,
and some things are just different.
.LP
.I <object file>
is an object file, produced by
.IR ack (1)
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 (6)
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, do this when
.I condition
becomes true.
If no condition is given, do this 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 ]
.ti -0.5i
\fBw\fP [ \fIn\fP ]
.br
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 without arguments by entering an empty command line:
step, next, list, cont.
.SH SEE ALSO
.IR ack (1).
.IR led (6).
.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.