grind.1 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423
  1. .\" $Id$
  2. .TH GRIND 1 "$Revision$"
  3. .SH NAME
  4. grind \- source-level debugger for ACK
  5. .SH SYNOPSIS
  6. .B grind
  7. [ <ACK object file> ] [ <object file> ]
  8. .SH DESCRIPTION
  9. .B Grind
  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
  13. .IR dbx ,
  14. a source-level debugger
  15. available on many Unix systems. However, some
  16. .B grind
  17. commands are not available in
  18. .IR dbx ,
  19. some
  20. .I dbx
  21. commands are not available in
  22. .BR grind ,
  23. and some things are just different.
  24. .LP
  25. .I <object file>
  26. is an object file, produced by
  27. .IR ack (1)
  28. with the
  29. .B \-g
  30. option to include a symbol table.
  31. .LP
  32. If no
  33. .I <object file>
  34. is specified, "a.out" is used.
  35. .LP
  36. For some machines, the debugger does not recognize the object file
  37. format. For these machines, the result of the
  38. .IR led (6)
  39. program must be saved and offered to
  40. .BR grind ,
  41. for instance:
  42. .DS
  43. m68020 -c.out -g blabla.c
  44. m68020 blabla.out
  45. grind blabla.out a.out
  46. .DE
  47. .SH USAGE
  48. Some
  49. .B grind
  50. commands take an expression argument.
  51. .SS Expressions
  52. .B Grind
  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
  59. .BR grind ,
  60. the conversions needed are performed automatically.
  61. .LP
  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:
  65. .LP
  66. .nf
  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
  74. the indicated string
  75. .fi
  76. .SS Operators
  77. .LP
  78. .B Grind
  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.
  84. .LP
  85. The syntax and priority of these operators depends on the source language.
  86. Parentheses can be used for grouping.
  87. .SS "Scope Rules"
  88. .LP
  89. .B Grind
  90. uses the current file and function to resolve scope conflicts.
  91. Their values are updated as files and functions are entered and exited
  92. during execution.
  93. Names can also be qualified with procedure- or module names, as in
  94. \fImodule\fP`\fIprocedure\fP`\fIname\fP.
  95. .B Grind
  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
  98. does not help.
  99. .SS "Positions"
  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:
  102. .RS
  103. \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
  104. .RE
  105. The
  106. .I filename
  107. part is optional.
  108. The second way is to specify a function name, like this:
  109. .RS
  110. \fBin \fIfunction\fP
  111. .RE
  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:
  115. .RS
  116. \fBin\fP \fIfunction\fP \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
  117. .RE
  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"
  121. .LP
  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
  128. commands).
  129. .SS "Commands"
  130. .TP
  131. .B ^C
  132. Interrupt. Stop the program being debugged and enter
  133. .BR grind .
  134. .TP
  135. \fBrun\fP [ \fIargs\fP ] [ < \fIinfile\fP ] [ > \fIoutfile\fP ]
  136. Start executing
  137. .I <object file>
  138. with command line arguments
  139. .IR args ,
  140. and possible redirection of standard input and/or standard output.
  141. .TP
  142. .B rerun
  143. Repeats the last
  144. .B run
  145. command.
  146. .TP
  147. .B "rerun ?"
  148. Prints the last
  149. .B run
  150. command.
  151. .TP
  152. \fBcont\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
  153. .ti -0.5i
  154. \fBc\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
  155. .br
  156. Continue execution from where it stopped, or, if \fIsourceline\fP is
  157. given, at that source line. If \fIcount\fP is given, pass \fIcount\fP-1
  158. breakpoints. \fIsourceline\fP must be in the same function.
  159. .TP
  160. \fBtrace\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  161. .ti -0.5i
  162. \fBt\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  163. .br
  164. Display tracing information.
  165. If no argument is specified, each source line is displayed before
  166. execution.
  167. In addition, if an \fBon\fP-clause is given, the value of the expression
  168. is printed.
  169. If a position is given there are two possibilities: if the position is
  170. given as \fBin\fP \fIfunction\fP, then the tracing information is
  171. displayed only while executing the function or
  172. procedure
  173. .IR function .
  174. If the position is given as \fBat\fP \fIlinenumber\fP,
  175. then the tracing information is displayed only whenever the source line
  176. indicated is reached.
  177. If the position is given as \fBat\fP \fIlinenumber\fP \fBin\fP \fIfunction\fP,
  178. the behavior is as if it was given as \fBat\fP \fIlinenumber\fP.
  179. If a condition is given, tracing information is only displayed when
  180. .I condition
  181. is true.
  182. .TP
  183. \fBstop\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  184. Stop execution when the
  185. .I position
  186. is reached, and then when
  187. .I condition
  188. becomes true.
  189. If no position is given, stop when
  190. .I condition
  191. becomes true.
  192. If no condition is given, stop when
  193. .I position
  194. is reached.
  195. Either a position or a condition (or both) must be given.
  196. .TP
  197. \fBwhen\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ] { \fIcommand\fP [ ; \fIcommand\fP ] ... }
  198. Execute the
  199. .B grind
  200. .IR command (s)
  201. when the
  202. .I position
  203. is reached, and then when
  204. .I condition
  205. becomes true.
  206. If no position is given, do this when
  207. .I condition
  208. becomes true.
  209. If no condition is given, do this when
  210. .I position
  211. is reached.
  212. Either a position or a condition (or both) must be given.
  213. .TP
  214. \fBprint\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
  215. .ti -0.5i
  216. \fBp\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
  217. .br
  218. Print the value of each expression. If no argument is given, repeat the
  219. last
  220. .B print
  221. command.
  222. .TP
  223. \fBdisplay\fP \fIexpression\fP [ , \fIexpression\fP ] ...
  224. Print the value of each expression whenever the program stops.
  225. .TP
  226. .B dump
  227. Saves the data (global data + stack) of the program. These data can
  228. be restore with the
  229. .B restore
  230. command discussed later.
  231. .B Dump
  232. and
  233. .B restore
  234. combinations can be used as a poor man's implementation of an "undo"
  235. facility.
  236. .TP
  237. .B status
  238. Display active
  239. .BR trace ,
  240. .BR stop ,
  241. .BR when ,
  242. and
  243. .B display
  244. commands, and associated command numbers.
  245. Also display current
  246. .B dump
  247. records.
  248. .TP
  249. \fBdelete\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  250. .ti -0.5i
  251. \fBd\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  252. .br
  253. Remove the commands corresponding to the \fIcommandnumber\fP's given
  254. (as displayed by
  255. .BR status ).
  256. If no argument is given and there is a "current" breakpoint, remove that
  257. breakpoint.
  258. .TP
  259. \fBrestore\fP [ \fIcommandnumber\fP ]
  260. .ti -0.5i
  261. \fBr\fP [ \fIcommandnumber\fP ]
  262. .br
  263. Restore the data corresponding to the dump of \fIcommandnumber\fP
  264. (as displayed by
  265. .BR status ).
  266. This restores the values of all variables of the program to the values
  267. at the time the dump was made. The program counter is also restored.
  268. This effectively puts the program back into the state it was when the
  269. dump was made, except for file-handling: the state of the files that
  270. the program handles is not changed.
  271. Apart from this,
  272. .B restore
  273. even works when the program is finished.
  274. If no \fIcommandnumber\fP is given, the last dump is restored.
  275. .TP
  276. \fBstep\fP [ \fIn\fP ]
  277. .ti -0.5i
  278. \fBs\fP [ \fIn\fP ]
  279. .br
  280. Execute the next
  281. .I n
  282. source lines.
  283. If omitted,
  284. .I n
  285. is taken to be 1.
  286. This command steps into functions.
  287. .TP
  288. \fBnext\fP [ \fIn\fP ]
  289. .ti -0.5i
  290. \fBn\fP [ \fIn\fP ]
  291. .br
  292. Execute the next
  293. .I n
  294. source lines.
  295. If omitted,
  296. .I n
  297. is taken to be 1.
  298. .B Next
  299. steps past function-calls.
  300. .TP
  301. \fBwhich\fP \fIname\fP
  302. Print the fully-qualified name of the given name.
  303. .TP
  304. \fBfind\fP \fIname\fP
  305. Print the fully qualified name of all symbols matching
  306. .IR name .
  307. .TP
  308. \fBset\fP \fIexpression\fP \fBto\fP \fIexpression\fP
  309. Assign the value of the second
  310. .I expression
  311. to the designator indicated by the first
  312. .IR expression .
  313. Needless to say, the first
  314. .I expression
  315. must indicate a designator (something that can be assigned to).
  316. If the types do not match,
  317. .B grind
  318. tries to apply conversions.
  319. .TP
  320. \fBwhere\fP [ \fIn\fP | -\fIn\fP ]
  321. .ti -0.5i
  322. \fBw\fP [ \fIn\fP | -\fIn\fP ]
  323. .br
  324. List all, or the top
  325. .IR n ,
  326. or the bottom
  327. .IR n ,
  328. active functions on the stack.
  329. .TP
  330. \fBfile\fP [ \fIfilename\fP ]
  331. Print the name of the current source file, or
  332. change the current source file to
  333. .IR filename .
  334. .TP
  335. \fBlist\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
  336. .ti -0.5i
  337. \fBl\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
  338. .br
  339. If no arguments are given, list the next \fIws\fP (default 10) lines from current source file,
  340. if a
  341. .I startline
  342. is given, list from
  343. .IR startline ,
  344. if a
  345. .I function
  346. is given, list from the first statement of
  347. .IR function .
  348. If a \fIcount\fP is given, list \fIcount\fP lines and set \fIws\fP to \fIcount\fP.
  349. If an \fIendline\fP is given, list up until this line; if a - is given without
  350. an \fIendline\fP, list up until the end of the file.
  351. .TP
  352. \fBhelp\fP [ \fIcommand\fP ]
  353. .ti -0.5i
  354. \fB?\fP [ \fIcommand\fP ]
  355. .br
  356. Print a summary of \fBgrind\fP commands, or print a message explaining
  357. \fIcommand\fP.
  358. .TP
  359. \fBsource\fP \fIfilename\fP
  360. .br
  361. Read and execute \fBgrind\fP commands from \fIfilename\fP. This is useful for
  362. executing \fBgrind\fP log files created with the \fBlog\fP command.
  363. .TP
  364. \fBlog\fP [ \fIfilename\fP | off ]
  365. .br
  366. Start logging the \fBgrind\fP commands given on file \fIfilename\fP, or
  367. stop logging. If no argument is given, the current log file is printed.
  368. In logged commands, an absolute command number is replaced by a relative one.
  369. .TP
  370. \fBdisable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  371. .br
  372. Disable the commands corresponding to the \fIcommandnumber\fP's given
  373. (as displayed by
  374. .BR status ).
  375. If no argument is given and there is a "current" breakpoint, disable that
  376. breakpoint.
  377. Disabling commands keeps them in the status, but makes them inoperative.
  378. Disabled commands can be enabled again with the \fBenable\fP command.
  379. .TP
  380. \fBenable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  381. .br
  382. Enable the commands corresponding to the \fIcommandnumber\fP's given
  383. (as displayed by
  384. .BR status ).
  385. If no argument is given and there is a "current" breakpoint, enable that
  386. breakpoint.
  387. .TP
  388. \fB!\fP \fIshellcommand\fP
  389. .br
  390. Invoke the shell with \fIshellcommand\fP. \fIshellcommand\fP extends to the
  391. end of the line. In the command, the characters `%' and `!' are replaced
  392. with the current file name and the previous shell command respectively.
  393. The sequences `\e%' and `\e!' are replaced by `%' and `!' respectively.
  394. .TP
  395. \fBframe\fP [ \fIcount\fP | + \fIcount\fP | - \fIcount\fP ]
  396. .br
  397. The currently active procedure has frame number 0, the one that invoked this
  398. one has frame number 1, etc. The \fBframe\fP command allows the user to
  399. examine stack frames beyond the current one. For instance, after giving the
  400. command `frame 1', variables of the frame invoking the currently active
  401. procedure can be examined. There is a relative and an absolute version of this
  402. command.
  403. .TP
  404. .B quit
  405. .br
  406. Exit
  407. .BR grind .
  408. .LP
  409. Some commands can be repeated without arguments by entering an empty command line:
  410. step, next, list, cont.
  411. .SH SEE ALSO
  412. .IR ack (1).
  413. .IR led (6).
  414. .SH REMARKS
  415. .LP
  416. .B Grind
  417. does not understand the scope of WITH statements. The scope information needed
  418. is not available in the symbol table.
  419. .SH BUGS
  420. .LP
  421. .B Grind
  422. does not correctly handle bit-fields.