ack/util/grind/grind.1

.\" $Id$
.TH GRIND 1 "$Revision$"
.SH NAME
grind \- source-level debugger for ACK
.SH SYNOPSIS
.B grind
[ <ACK object file> ] [ <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 ,
for instance:
.DS
m68020 -c.out -g blabla.c
m68020 blabla.out
grind blabla.out a.out
.DE
.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.
.LP
Expressions whose value is to be printed can be given a "format" by appending
a `\e', followed by a format. A format consists of a string of letters.
The following letters are available:
.LP
.nf
c	print all integer values as a char
d	print all integer values in signed decimal format
o	print all integer values in octal format
x	print all integer values in hexadecimal format
h	print all integer values in hexadecimal format
u	print all integer values in unsigned decimal format
s	for "pointer to char" types, make an attempt to print
	the indicated string
.fi
.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, array subscripting.
.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`\fIprocedure\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).
The following way is also accepted:
.RS
\fBin\fP \fIfunction\fP \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
.RE
In this case, consistency of the information given is checked. This last
form is useful for "stuffing" output from the status command described later.
.SS "Command numbers"
.LP
Some command numbers have a command number associated with them. Other commands
refer to these command numbers. These command numbers can either be given as
an absolute number, or as a negative number. In the last case, the number
is interpreted relative to the last number assigned. This feature is normally
only used for commands that are put in a log file, so that "sourceing" these
log files is safer (see also the description of the \fBsource\fP and \fBlog\fP
commands).

.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
.B "rerun ?"
Prints the last 
.B run
command.
.TP
\fBcont\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
.ti -0.5i
\fBc\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
.br
Continue execution from where it stopped, or, if \fIsourceline\fP is
given, at that source line. If \fIcount\fP is given, pass \fIcount\fP-1
breakpoints. \fIsourceline\fP must be in the same function.
.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 the position is given as \fBat\fP \fIlinenumber\fP \fBin\fP \fIfunction\fP,
the behavior is as if it was given as \fBat\fP \fIlinenumber\fP.
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\fP ] ... }
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. If no argument is given, repeat the
last
.B print
command.
.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 [ , \fIcommandnumber\fP ... ] ]
.ti -0.5i
\fBd\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
.br
Remove the commands corresponding to the \fIcommandnumber\fP's given
(as displayed by
.BR status ).
If no argument is given and there is a "current" breakpoint, remove that
breakpoint.
.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.
If no \fIcommandnumber\fP is given, the last dump is restored.
.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 | -\fIn\fP ]
.ti -0.5i
\fBw\fP [ \fIn\fP | -\fIn\fP ]
.br
List all, or the top
.IR n ,
or the bottom
.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 | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
.ti -0.5i
\fBl\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
.br
If no arguments are given, list the next \fIws\fP (default 10) lines from current source file,
if a
.I startline
is given, list from
.IR startline ,
if a
.I function
is given, list from the first statement of
.IR function .
If a \fIcount\fP is given, list \fIcount\fP lines and set \fIws\fP to \fIcount\fP.
If an \fIendline\fP is given, list up until this line; if a - is given without
an \fIendline\fP, list up until the end of the file.
.TP
\fBhelp\fP [ \fIcommand\fP ]
.ti -0.5i
\fB?\fP [ \fIcommand\fP ]
.br
Print a summary of \fBgrind\fP commands, or print a message explaining
\fIcommand\fP.
.TP
\fBsource\fP \fIfilename\fP
.br
Read and execute \fBgrind\fP commands from \fIfilename\fP. This is useful for
executing \fBgrind\fP log files created with the \fBlog\fP command.
.TP
\fBlog\fP [ \fIfilename\fP | off ]
.br
Start logging the \fBgrind\fP commands given on file \fIfilename\fP, or
stop logging. If no argument is given, the current log file is printed.
In logged commands, an absolute command number is replaced by a relative one.
.TP
\fBdisable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
.br
Disable the commands corresponding to the \fIcommandnumber\fP's given
(as displayed by
.BR status ).
If no argument is given and there is a "current" breakpoint, disable that
breakpoint.
Disabling commands keeps them in the status, but makes them inoperative.
Disabled commands can be enabled again with the \fBenable\fP command.
.TP
\fBenable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
.br
Enable the commands corresponding to the \fIcommandnumber\fP's given
(as displayed by
.BR status ).
If no argument is given and there is a "current" breakpoint, enable that
breakpoint.
.TP
\fB!\fP \fIshellcommand\fP
.br
Invoke the shell with \fIshellcommand\fP. \fIshellcommand\fP extends to the
end of the line. In the command, the characters `%' and `!' are replaced
with the current file name and the previous shell command respectively.
The sequences `\e%' and `\e!' are replaced by `%' and `!' respectively.
.TP
\fBframe\fP [ \fIcount\fP | + \fIcount\fP | - \fIcount\fP ]
.br
The currently active procedure has frame number 0, the one that invoked this
one has frame number 1, etc. The \fBframe\fP command allows the user to
examine stack frames beyond the current one. For instance, after giving the
command `frame 1', variables of the frame invoking the currently active
procedure can be examined. There is a relative and an absolute version of this
command.
.TP
.B quit
.br
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.