422 lines
12 KiB
Groff
422 lines
12 KiB
Groff
.\" $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.
|
|
.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.
|