.\" $Header$ .TH GRIND 1 "$Revision$" .SH NAME grind \- source-level debugger for ACK .SH SYNOPSIS .B grind [ ] [ ] .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 is an object file, produced by .IR ack (1) with the .B \-g option to include a symbol table. .LP If no .I 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 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.