1 .\" $Id: grind.1,v 1.8 1994/06/24 10:59:57 ceriel Exp $
2 .TH GRIND 1 "$Revision: 1.8 $"
4 grind \- source-level debugger for ACK
7 [ <ACK object file> ] [ <object file> ]
10 is a utility for source-level debugging and execution of
11 programs written in C, Modula-2, or Pascal.
12 Its operation resembles the operation of
14 a source-level debugger
15 available on many Unix systems. However, some
17 commands are not available in
21 commands are not available in
23 and some things are just different.
26 is an object file, produced by
30 option to include a symbol table.
34 is specified, "a.out" is used.
36 For some machines, the debugger does not recognize the object file
37 format. For these machines, the result of the
39 program must be saved and offered to
43 m68020 -c.out -g blabla.c
45 grind blabla.out a.out
50 commands take an expression argument.
53 expressions are combinations of variables, constants, and operators.
54 The syntax and the operators depend on the source language of the program
55 being debugged. However, the type rules are probably less strict than the
56 rules of this language. For instance, in Modula-2 one cannot combine
57 values of type INTEGER with values of type REAL in an expression without
58 using conversion routines. In
60 the conversions needed are performed automatically.
62 Expressions whose value is to be printed can be given a "format" by appending
63 a `\e', followed by a format. A format consists of a string of letters.
64 The following letters are available:
67 c print all integer values as a char
68 d print all integer values in signed decimal format
69 o print all integer values in octal format
70 x print all integer values in hexadecimal format
71 h print all integer values in hexadecimal format
72 u print all integer values in unsigned decimal format
73 s for "pointer to char" types, make an attempt to print
79 supports operators for addition, subtraction, multiplication, division,
80 remainder, bitwise or, bitwise xor, bitwise and, boolean or,
81 boolean and, left-shift, right-shift, address-of, dereference, less than,
82 less than or equal, equal, not equal, greater than, greater than or equal,
83 selection, array subscripting.
85 The syntax and priority of these operators depends on the source language.
86 Parentheses can be used for grouping.
90 uses the current file and function to resolve scope conflicts.
91 Their values are updated as files and functions are entered and exited
93 Names can also be qualified with procedure- or module names, as in
94 \fImodule\fP`\fIprocedure\fP`\fIname\fP.
96 tries to be intelligent about names; qualification is only needed when
97 names are used for more than one object in a program and the current scope
100 In general, there are two ways to specify a position; the first way is
101 to specify file name and line number, in a so-called at-clause, like this:
103 \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
108 The second way is to specify a function name, like this:
112 This indicates the first statement within the named function (except for
113 the trace command discussed later).
114 The following way is also accepted:
116 \fBin\fP \fIfunction\fP \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
118 In this case, consistency of the information given is checked. This last
119 form is useful for "stuffing" output from the status command described later.
120 .SS "Command numbers"
122 Some command numbers have a command number associated with them. Other commands
123 refer to these command numbers. These command numbers can either be given as
124 an absolute number, or as a negative number. In the last case, the number
125 is interpreted relative to the last number assigned. This feature is normally
126 only used for commands that are put in a log file, so that "sourceing" these
127 log files is safer (see also the description of the \fBsource\fP and \fBlog\fP
133 Interrupt. Stop the program being debugged and enter
136 \fBrun\fP [ \fIargs\fP ] [ < \fIinfile\fP ] [ > \fIoutfile\fP ]
139 with command line arguments
141 and possible redirection of standard input and/or standard output.
153 \fBcont\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
155 \fBc\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
157 Continue execution from where it stopped, or, if \fIsourceline\fP is
158 given, at that source line. If \fIcount\fP is given, pass \fIcount\fP-1
159 breakpoints. \fIsourceline\fP must be in the same function.
161 \fBtrace\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
163 \fBt\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
165 Display tracing information.
166 If no argument is specified, each source line is displayed before
168 In addition, if an \fBon\fP-clause is given, the value of the expression
170 If a position is given there are two possibilities: if the position is
171 given as \fBin\fP \fIfunction\fP, then the tracing information is
172 displayed only while executing the function or
175 If the position is given as \fBat\fP \fIlinenumber\fP,
176 then the tracing information is displayed only whenever the source line
177 indicated is reached.
178 If the position is given as \fBat\fP \fIlinenumber\fP \fBin\fP \fIfunction\fP,
179 the behavior is as if it was given as \fBat\fP \fIlinenumber\fP.
180 If a condition is given, tracing information is only displayed when
184 \fBstop\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
185 Stop execution when the
187 is reached, and then when
190 If no position is given, stop when
193 If no condition is given, stop when
196 Either a position or a condition (or both) must be given.
198 \fBwhen\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ] { \fIcommand\fP [ ; \fIcommand\fP ] ... }
204 is reached, and then when
207 If no position is given, do this when
210 If no condition is given, do this when
213 Either a position or a condition (or both) must be given.
215 \fBprint\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
217 \fBp\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
219 Print the value of each expression. If no argument is given, repeat the
224 \fBdisplay\fP \fIexpression\fP [ , \fIexpression\fP ] ...
225 Print the value of each expression whenever the program stops.
228 Saves the data (global data + stack) of the program. These data can
231 command discussed later.
235 combinations can be used as a poor man's implementation of an "undo"
245 commands, and associated command numbers.
250 \fBdelete\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
252 \fBd\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
254 Remove the commands corresponding to the \fIcommandnumber\fP's given
257 If no argument is given and there is a "current" breakpoint, remove that
260 \fBrestore\fP [ \fIcommandnumber\fP ]
262 \fBr\fP [ \fIcommandnumber\fP ]
264 Restore the data corresponding to the dump of \fIcommandnumber\fP
267 This restores the values of all variables of the program to the values
268 at the time the dump was made. The program counter is also restored.
269 This effectively puts the program back into the state it was when the
270 dump was made, except for file-handling: the state of the files that
271 the program handles is not changed.
274 even works when the program is finished.
275 If no \fIcommandnumber\fP is given, the last dump is restored.
277 \fBstep\fP [ \fIn\fP ]
287 This command steps into functions.
289 \fBnext\fP [ \fIn\fP ]
300 steps past function-calls.
302 \fBwhich\fP \fIname\fP
303 Print the fully-qualified name of the given name.
305 \fBfind\fP \fIname\fP
306 Print the fully qualified name of all symbols matching
309 \fBset\fP \fIexpression\fP \fBto\fP \fIexpression\fP
310 Assign the value of the second
312 to the designator indicated by the first
314 Needless to say, the first
316 must indicate a designator (something that can be assigned to).
317 If the types do not match,
319 tries to apply conversions.
321 \fBwhere\fP [ \fIn\fP | -\fIn\fP ]
323 \fBw\fP [ \fIn\fP | -\fIn\fP ]
329 active functions on the stack.
331 \fBfile\fP [ \fIfilename\fP ]
332 Print the name of the current source file, or
333 change the current source file to
336 \fBlist\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
338 \fBl\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
340 If no arguments are given, list the next \fIws\fP (default 10) lines from current source file,
347 is given, list from the first statement of
349 If a \fIcount\fP is given, list \fIcount\fP lines and set \fIws\fP to \fIcount\fP.
350 If an \fIendline\fP is given, list up until this line; if a - is given without
351 an \fIendline\fP, list up until the end of the file.
353 \fBhelp\fP [ \fIcommand\fP ]
355 \fB?\fP [ \fIcommand\fP ]
357 Print a summary of \fBgrind\fP commands, or print a message explaining
360 \fBsource\fP \fIfilename\fP
362 Read and execute \fBgrind\fP commands from \fIfilename\fP. This is useful for
363 executing \fBgrind\fP log files created with the \fBlog\fP command.
365 \fBlog\fP [ \fIfilename\fP | off ]
367 Start logging the \fBgrind\fP commands given on file \fIfilename\fP, or
368 stop logging. If no argument is given, the current log file is printed.
369 In logged commands, an absolute command number is replaced by a relative one.
371 \fBdisable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
373 Disable the commands corresponding to the \fIcommandnumber\fP's given
376 If no argument is given and there is a "current" breakpoint, disable that
378 Disabling commands keeps them in the status, but makes them inoperative.
379 Disabled commands can be enabled again with the \fBenable\fP command.
381 \fBenable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
383 Enable the commands corresponding to the \fIcommandnumber\fP's given
386 If no argument is given and there is a "current" breakpoint, enable that
389 \fB!\fP \fIshellcommand\fP
391 Invoke the shell with \fIshellcommand\fP. \fIshellcommand\fP extends to the
392 end of the line. In the command, the characters `%' and `!' are replaced
393 with the current file name and the previous shell command respectively.
394 The sequences `\e%' and `\e!' are replaced by `%' and `!' respectively.
396 \fBframe\fP [ \fIcount\fP | + \fIcount\fP | - \fIcount\fP ]
398 The currently active procedure has frame number 0, the one that invoked this
399 one has frame number 1, etc. The \fBframe\fP command allows the user to
400 examine stack frames beyond the current one. For instance, after giving the
401 command `frame 1', variables of the frame invoking the currently active
402 procedure can be examined. There is a relative and an absolute version of this
410 Some commands can be repeated without arguments by entering an empty command line:
411 step, next, list, cont.
418 does not understand the scope of WITH statements. The scope information needed
419 is not available in the symbol table.
423 does not correctly handle bit-fields.