grind.1 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  1. .\" $Header$
  2. .TH GRIND 1ACK
  3. .SH NAME
  4. grind \- source-level debugger for ACK
  5. .SH SYNOPSIS
  6. .B grind
  7. [
  8. .I <ACK object file>
  9. ]
  10. [
  11. .I <object file>
  12. ]
  13. .SH DESCRIPTION
  14. .B Grind
  15. is a utility for source-level debugging and execution of
  16. programs written in C, Modula-2, or Pascal.
  17. Its operation resembles the operation of
  18. .IR dbx ,
  19. a source-level debugger
  20. available on many Unix systems. However, some
  21. .B grind
  22. commands are not available in
  23. .IR dbx ,
  24. some more
  25. .I dbx
  26. commands are not available in
  27. .BR grind ,
  28. and some things are just plain different.
  29. .LP
  30. .I <object file>
  31. is an object file, produced by
  32. .IR ack (1ACK)
  33. with the
  34. .B \-g
  35. option to include a symbol table.
  36. .LP
  37. If no
  38. .I <object file>
  39. is specified, "a.out" is used.
  40. .LP
  41. For some machines, the debugger does not recognize the object file
  42. format. For these machines, the result of the
  43. .IR led (6ACK)
  44. program must be saved and offered to
  45. .BR grind .
  46. .SH USAGE
  47. Some
  48. .B grind
  49. commands take an expression argument.
  50. .SS Expressions
  51. .B Grind
  52. expressions are combinations of variables, constants, and operators.
  53. The syntax and the operators depend on the source language of the program
  54. being debugged. However, the type rules are probably less strict than the
  55. rules of this language. For instance, in Modula-2 one cannot combine
  56. values of type INTEGER with values of type REAL in an expression without
  57. using conversion routines. In
  58. .BR grind ,
  59. the conversions needed are performed automatically.
  60. .SS Operators
  61. .LP
  62. .B Grind
  63. supports operators for addition, subtraction, multiplication, division,
  64. remainder, bitwise or, bitwise xor, bitwise and, boolean or,
  65. boolean and, left-shift, right-shift, address-of, dereference, less than,
  66. less than or equal, equal, not equal, greater than, greater than or equal,
  67. selection.
  68. .LP
  69. The syntax and priority of these operators depends on the source language.
  70. Parentheses can be used for grouping.
  71. .SS "Scope Rules"
  72. .LP
  73. .B Grind
  74. uses the current file and function to resolve scope conflicts.
  75. Their values are updated as files and functions are entered and exited
  76. during execution.
  77. Names can also be qualified with procedure- or module names, as in
  78. \fImodule\fP`\fIproc\fP`\fIname\fP.
  79. .B Grind
  80. tries to be intelligent about names; qualification is only needed when
  81. names are used for more than one object in a program and the current scope
  82. does not help.
  83. .SS "Positions"
  84. In general, there are two ways to specify a position; the first way is
  85. to specify file name and line number, in a so-called at-clause, like this:
  86. .RS
  87. \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
  88. .RE
  89. The
  90. .I filename
  91. part is optional.
  92. The second way is to specify a function name, like this:
  93. .RS
  94. \fBin \fIfunction\fP
  95. .RE
  96. This indicates the first statement within the named function (except for
  97. the trace command discussed later).
  98. .SS "Commands"
  99. .TP
  100. .B ^C
  101. Interrupt. Stop the program being debugged and enter
  102. .BR grind .
  103. .TP
  104. \fBrun\fP [ \fIargs\fP ] [ < \fIinfile\fP ] [ > \fIoutfile\fP ]
  105. Start executing
  106. .I <object file>
  107. with command line arguments
  108. .IR args ,
  109. and possible redirection of standard input and/or standard output.
  110. .TP
  111. .B rerun
  112. Repeats the last
  113. .B run
  114. command.
  115. .TP
  116. \fBcont\fP [ \fBat\fP \fIsourceline\fP ]
  117. .ti -0.5i
  118. \fBc\fP [ \fBat\fP \fIsourceline\fP ]
  119. .br
  120. Continue execution from where it stopped, or, if \fIsourceline\fP is
  121. given, at that source line.
  122. .TP
  123. \fBtrace\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  124. .ti -0.5i
  125. \fBt\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  126. .br
  127. Display tracing information.
  128. If no argument is specified, each source line is displayed before
  129. execution.
  130. In addition, if an \fBon\fP-clause is given, the value of the expression
  131. is printed.
  132. If a position is given there are two possibilities: if the position is
  133. given as \fBin\fP \fIfunction\fP, then the tracing information is
  134. displayed only while executing the function or
  135. procedure
  136. .IR function .
  137. If the position is given as \fBat\fP \fIlinenumber\fP,
  138. then the tracing information is displayed only whenever the source line
  139. indicated is reached.
  140. If a condition is given, tracing information is only displayed when
  141. .I condition
  142. is true.
  143. .TP
  144. \fBstop\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  145. Stop execution when the
  146. .I position
  147. is reached, and then when
  148. .I condition
  149. becomes true.
  150. If no position is given, stop when
  151. .I condition
  152. becomes true.
  153. If no condition is given, stop when
  154. .I position
  155. is reached.
  156. Either a position or a condition (or both) must be given.
  157. .TP
  158. \fBwhen\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ] { \fIcommand\fP [ ; \fIcommand ] ... }
  159. Execute the
  160. .B grind
  161. .IR command (s)
  162. when the
  163. .I position
  164. is reached, and then when
  165. .I condition
  166. becomes true.
  167. If no position is given, stop when
  168. .I condition
  169. becomes true.
  170. If no condition is given, stop when
  171. .I position
  172. is reached.
  173. Either a position or a condition (or both) must be given.
  174. .TP
  175. \fBprint\fP \fIexpression\fP [ , \fIexpression\fP ] ...
  176. .ti -0.5i
  177. \fBp\fP \fIexpression\fP [ , \fIexpression\fP ] ...
  178. .br
  179. Print the value of each expression.
  180. .TP
  181. \fBdisplay\fP \fIexpression\fP [ , \fIexpression\fP ] ...
  182. Print the value of each expression whenever the program stops.
  183. .TP
  184. .B dump
  185. Saves the data (global data + stack) of the program. These data can
  186. be restore with the
  187. .B restore
  188. command discussed later.
  189. .B Dump
  190. and
  191. .B restore
  192. combinations can be used as a poor man's implementation of an "undo"
  193. facility.
  194. .TP
  195. .B status
  196. Display active
  197. .BR trace ,
  198. .BR stop ,
  199. .BR when ,
  200. and
  201. .B display
  202. commands, and associated command numbers.
  203. Also display current
  204. .B dump
  205. records.
  206. .TP
  207. \fBdelete\fP \fIcommandnumber\fP
  208. .ti -0.5i
  209. \fBd\fP \fIcommandnumber\fP
  210. .br
  211. Remove the command corresponding to \fIcommandnumber\fP
  212. (as displayed by
  213. .BR status ).
  214. .TP
  215. \fBrestore\fP \fIcommandnumber\fP
  216. .ti -0.5i
  217. \fBr\fP \fIcommandnumber\fP
  218. .br
  219. Restore the data corresponding to the dump of \fIcommandnumber\fP
  220. (as displayed by
  221. .BR status ).
  222. This restores the values of all variables of the program to the values
  223. at the time the dump was made. The program counter is also restored.
  224. This effectively puts the program back into the state it was when the
  225. dump was made, except for file-handling: the state of the files that
  226. the program handles is not changed.
  227. Apart from this,
  228. .B restore
  229. even works when the program is finished.
  230. .TP
  231. \fBstep\fP [ \fIn\fP ]
  232. .ti -0.5i
  233. \fBs\fP [ \fIn\fP ]
  234. .br
  235. Execute the next
  236. .I n
  237. source lines.
  238. If omitted,
  239. .I n
  240. is taken to be 1.
  241. This command steps into functions.
  242. .TP
  243. \fBnext\fP [ \fIn\fP ]
  244. .ti -0.5i
  245. \fBn\fP [ \fIn\fP ]
  246. .br
  247. Execute the next
  248. .I n
  249. source lines.
  250. If omitted,
  251. .I n
  252. is taken to be 1.
  253. .B Next
  254. steps past function-calls.
  255. .TP
  256. \fBwhich\fP \fIname\fP
  257. Print the fully-qualified name of the given name.
  258. .TP
  259. \fBfind\fP \fIname\fP
  260. Print the fully qualified name of all symbols matching
  261. .IR name .
  262. .TP
  263. \fBset\fP \fIexpression\fP \fBto\fP \fIexpression\fP
  264. Assign the value of the second
  265. .I expression
  266. to the designator indicated by the first
  267. .IR expression .
  268. Needless to say, the first
  269. .I expression
  270. must indicate a designator (something that can be assigned to).
  271. If the types do not match,
  272. .B grind
  273. tries to apply conversions.
  274. .TP
  275. \fBwhere\fP [ \fIn\fP ]
  276. List all, or the top
  277. .IR n ,
  278. active functions on the stack.
  279. .TP
  280. \fBfile\fP [ \fIfilename\fP ]
  281. Print the name of the current source file, or
  282. change the current source file to
  283. .IR filename .
  284. .TP
  285. \fBlist\fP [ \fIstartline\fP [ , \fIendline\fP ] | \fIfunction\fP ]
  286. .ti -0.5i
  287. \fBl\fP [ \fIstartline\fP [ , \fIendline\fP ] | \fIfunction\fP ]
  288. .br
  289. If no arguments are given, list the next ten lines from current source file,
  290. if a
  291. .I startline
  292. is given, list from
  293. .I startline
  294. through
  295. .IR endline ,
  296. or
  297. list from five lines above, to five lines below
  298. the first statement of
  299. .IR function .
  300. .TP
  301. .B quit
  302. Exit
  303. .BR grind .
  304. .LP
  305. Some commands can be repeated by entering an empty command line: step,
  306. next, print, list, status, cont.
  307. .SH ENVIRONMENT
  308. P.M.
  309. .SH SEE ALSO
  310. .IR ack (1ACK).
  311. .IR led (6ACK).
  312. .SH REMARKS
  313. .LP
  314. .B Grind
  315. does not understand the scope of WITH statements. The scope information needed
  316. is not available in the symbol table.
  317. .SH BUGS
  318. .LP
  319. .B Grind
  320. does not correctly handle bit-fields.