123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423 |
- .\" $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.
|