GRIND(1)

NAME
grind - source-level debugger for ACK

SYNOPSIS
grind [ <ACK object file> ] [ <object file> ]

DESCRIPTION
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 dbx, a source-level debugger available on many Unix systems. However, some grind commands are not available in dbx, some dbx commands are not available in grind, and some things are just different.

<object file> is an object file, produced by ack(1) with the -g option to include a symbol table.

If no <object file> is specified, "a.out" is used.

For some machines, the debugger does not recognize the object file format. For these machines, the result of the led(6) program must be saved and offered to grind, for instance: m68020 -c.out -g blabla.c m68020 blabla.out grind blabla.out a.out

USAGE
Some grind commands take an expression argument.

  Expressions
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 grind, the conversions needed are performed automatically.

Expressions whose value is to be printed can be given a "format" by appending a `\', followed by a format. A format consists of a string of letters. The following letters are available:

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

  Operators

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.

The syntax and priority of these operators depends on the source language. Parentheses can be used for grouping.

  Scope Rules

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 module`procedure`name. 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.

  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:
    at [ "filename": ] linenumber
The filename part is optional. The second way is to specify a function name, like this:
    in function
This indicates the first statement within the named function (except for the trace command discussed later). The following way is also accepted:
    in function at [ "filename": ] linenumber
In this case, consistency of the information given is checked. This last form is useful for "stuffing" output from the status command described later.

  Command numbers

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 source and log commands).

  Commands

^C  Interrupt. Stop the program being debugged and enter grind.

run [ args ] [ < infile ] [ > outfile ]
    Start executing <object file> with command line arguments args, and possible redirection of standard input and/or standard output.

rerun
    Repeats the last run command.

rerun ?
    Prints the last run command.

cont [ count ] [ at sourceline ]
    c [ count ] [ at sourceline ]
    Continue execution from where it stopped, or, if sourceline is given, at that source line. If count is given, pass count-1 breakpoints. sourceline must be in the same function.

trace [ on expression ] [ position ] [ if condition ]
    t [ on expression ] [ position ] [ if condition ]
    Display tracing information. If no argument is specified, each source line is displayed before execution. In addition, if an on-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 in function, then the tracing information is displayed only while executing the function or procedure function. If the position is given as at linenumber, then the tracing information is displayed only whenever the source line indicated is reached. If the position is given as at linenumber in function, the behavior is as if it was given as at linenumber. If a condition is given, tracing information is only displayed when condition is true.

stop [ position ] [ if condition ]
    Stop execution when the position is reached, and then when condition becomes true. If no position is given, stop when condition becomes true. If no condition is given, stop when position is reached. Either a position or a condition (or both) must be given.

when [ position ] [ if condition ] { command [ ; command ] ... }
    Execute the grind command(s) when the position is reached, and then when condition becomes true. If no position is given, do this when condition becomes true. If no condition is given, do this when position is reached. Either a position or a condition (or both) must be given.

print [ expression [ , expression ] ... ]
    p [ expression [ , expression ] ... ]
    Print the value of each expression. If no argument is given, repeat the last print command.

display expression [ , expression ] ...
    Print the value of each expression whenever the program stops.

dump
    Saves the data (global data + stack) of the program. These data can be restore with the restore command discussed later. Dump and restore combinations can be used as a poor man's implementation of an "undo" facility.

status
    Display active trace, stop, when, and display commands, and associated command numbers. Also display current dump records.

delete [ commandnumber [ , commandnumber ... ] ]
    d [ commandnumber [ , commandnumber ... ] ]
    Remove the commands corresponding to the commandnumber's given (as displayed by status). If no argument is given and there is a "current" breakpoint, remove that breakpoint.

restore [ commandnumber ]
    r [ commandnumber ]
    Restore the data corresponding to the dump of commandnumber (as displayed by 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, restore even works when the program is finished. If no commandnumber is given, the last dump is restored.

step [ n ]
    s [ n ]
    Execute the next n source lines. If omitted, n is taken to be 1. This command steps into functions.

next [ n ]
    n [ n ]
    Execute the next n source lines. If omitted, n is taken to be 1. Next steps past function-calls.

which name
    Print the fully-qualified name of the given name.

find name
    Print the fully qualified name of all symbols matching name.

set expression to expression
    Assign the value of the second expression to the designator indicated by the first expression. Needless to say, the first expression must indicate a designator (something that can be assigned to). If the types do not match, grind tries to apply conversions.

where [ n | -n ]
    w [ n | -n ]
    List all, or the top n, or the bottom n, active functions on the stack.

file [ filename ]
    Print the name of the current source file, or change the current source file to filename.

list [ startline | function ] [ , count | - [ endline ] ]
    l [ startline | function ] [ , count | - [ endline ] ]
    If no arguments are given, list the next ws (default 10) lines from current source file, if a startline is given, list from startline, if a function is given, list from the first statement of function. If a count is given, list count lines and set ws to count. If an endline is given, list up until this line; if a - is given without an endline, list up until the end of the file.

help [ command ]
    ? [ command ]
    Print a summary of grind commands, or print a message explaining command.

source filename
    Read and execute grind commands from filename. This is useful for executing grind log files created with the log command.

log [ filename | off ]
    Start logging the grind commands given on file filename, 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.

disable [ commandnumber [ , commandnumber ... ] ]
    Disable the commands corresponding to the commandnumber's given (as displayed by 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 enable command.

enable [ commandnumber [ , commandnumber ... ] ]
    Enable the commands corresponding to the commandnumber's given (as displayed by status). If no argument is given and there is a "current" breakpoint, enable that breakpoint.

! shellcommand
    Invoke the shell with shellcommand. shellcommand 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 `\%' and `\!' are replaced by `%' and `!' respectively.

frame [ count | + count | - count ]
    The currently active procedure has frame number 0, the one that invoked this one has frame number 1, etc. The frame 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.

quit
    Exit grind.

Some commands can be repeated without arguments by entering an empty command line: step, next, list, cont.

SEE ALSO
ack(1). led(6).

REMARKS

Grind does not understand the scope of WITH statements. The scope information needed is not available in the symbol table.

BUGS

Grind does not correctly handle bit-fields.