grind.1 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417
  1. .\" $Header$
  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. .SH USAGE
  42. Some
  43. .B grind
  44. commands take an expression argument.
  45. .SS Expressions
  46. .B Grind
  47. expressions are combinations of variables, constants, and operators.
  48. The syntax and the operators depend on the source language of the program
  49. being debugged. However, the type rules are probably less strict than the
  50. rules of this language. For instance, in Modula-2 one cannot combine
  51. values of type INTEGER with values of type REAL in an expression without
  52. using conversion routines. In
  53. .BR grind ,
  54. the conversions needed are performed automatically.
  55. .LP
  56. Expressions whose value is to be printed can be given a "format" by appending
  57. a `\e', followed by a format. A format consists of a string of letters.
  58. The following letters are available:
  59. .LP
  60. .nf
  61. c print all integer values as a char
  62. d print all integer values in signed decimal format
  63. o print all integer values in octal format
  64. x print all integer values in hexadecimal format
  65. h print all integer values in hexadecimal format
  66. u print all integer values in unsigned decimal format
  67. s for "pointer to char" types, make an attempt to print
  68. the indicated string
  69. .fi
  70. .SS Operators
  71. .LP
  72. .B Grind
  73. supports operators for addition, subtraction, multiplication, division,
  74. remainder, bitwise or, bitwise xor, bitwise and, boolean or,
  75. boolean and, left-shift, right-shift, address-of, dereference, less than,
  76. less than or equal, equal, not equal, greater than, greater than or equal,
  77. selection, array subscripting.
  78. .LP
  79. The syntax and priority of these operators depends on the source language.
  80. Parentheses can be used for grouping.
  81. .SS "Scope Rules"
  82. .LP
  83. .B Grind
  84. uses the current file and function to resolve scope conflicts.
  85. Their values are updated as files and functions are entered and exited
  86. during execution.
  87. Names can also be qualified with procedure- or module names, as in
  88. \fImodule\fP`\fIprocedure\fP`\fIname\fP.
  89. .B Grind
  90. tries to be intelligent about names; qualification is only needed when
  91. names are used for more than one object in a program and the current scope
  92. does not help.
  93. .SS "Positions"
  94. In general, there are two ways to specify a position; the first way is
  95. to specify file name and line number, in a so-called at-clause, like this:
  96. .RS
  97. \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
  98. .RE
  99. The
  100. .I filename
  101. part is optional.
  102. The second way is to specify a function name, like this:
  103. .RS
  104. \fBin \fIfunction\fP
  105. .RE
  106. This indicates the first statement within the named function (except for
  107. the trace command discussed later).
  108. The following way is also accepted:
  109. .RS
  110. \fBin\fP \fIfunction\fP \fBat\fP [ "\fIfilename\fP": ] \fIlinenumber\fP
  111. .RE
  112. In this case, consistency of the information given is checked. This last
  113. form is useful for "stuffing" output from the status command described later.
  114. .SS "Command numbers"
  115. .LP
  116. Some command numbers have a command number associated with them. Other commands
  117. refer to these command numbers. These command numbers can either be given as
  118. an absolute number, or as a negative number. In the last case, the number
  119. is interpreted relative to the last number assigned. This feature is normally
  120. only used for commands that are put in a log file, so that "sourceing" these
  121. log files is safer (see also the description of the \fBsource\fP and \fBlog\fP
  122. commands).
  123. .SS "Commands"
  124. .TP
  125. .B ^C
  126. Interrupt. Stop the program being debugged and enter
  127. .BR grind .
  128. .TP
  129. \fBrun\fP [ \fIargs\fP ] [ < \fIinfile\fP ] [ > \fIoutfile\fP ]
  130. Start executing
  131. .I <object file>
  132. with command line arguments
  133. .IR args ,
  134. and possible redirection of standard input and/or standard output.
  135. .TP
  136. .B rerun
  137. Repeats the last
  138. .B run
  139. command.
  140. .TP
  141. .B "rerun ?"
  142. Prints the last
  143. .B run
  144. command.
  145. .TP
  146. \fBcont\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
  147. .ti -0.5i
  148. \fBc\fP [ \fIcount\fP ] [ \fBat\fP \fIsourceline\fP ]
  149. .br
  150. Continue execution from where it stopped, or, if \fIsourceline\fP is
  151. given, at that source line. If \fIcount\fP is given, pass \fIcount\fP-1
  152. breakpoints. \fIsourceline\fP must be in the same function.
  153. .TP
  154. \fBtrace\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  155. .ti -0.5i
  156. \fBt\fP [ \fBon\fP \fIexpression\fP ] [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  157. .br
  158. Display tracing information.
  159. If no argument is specified, each source line is displayed before
  160. execution.
  161. In addition, if an \fBon\fP-clause is given, the value of the expression
  162. is printed.
  163. If a position is given there are two possibilities: if the position is
  164. given as \fBin\fP \fIfunction\fP, then the tracing information is
  165. displayed only while executing the function or
  166. procedure
  167. .IR function .
  168. If the position is given as \fBat\fP \fIlinenumber\fP,
  169. then the tracing information is displayed only whenever the source line
  170. indicated is reached.
  171. If the position is given as \fBat\fP \fIlinenumber\fP \fBin\fP \fIfunction\fP,
  172. the behavior is as if it was given as \fBat\fP \fIlinenumber\fP.
  173. If a condition is given, tracing information is only displayed when
  174. .I condition
  175. is true.
  176. .TP
  177. \fBstop\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ]
  178. Stop execution when the
  179. .I position
  180. is reached, and then when
  181. .I condition
  182. becomes true.
  183. If no position is given, stop when
  184. .I condition
  185. becomes true.
  186. If no condition is given, stop when
  187. .I position
  188. is reached.
  189. Either a position or a condition (or both) must be given.
  190. .TP
  191. \fBwhen\fP [ \fIposition\fP ] [ \fBif\fP \fIcondition\fP ] { \fIcommand\fP [ ; \fIcommand\fP ] ... }
  192. Execute the
  193. .B grind
  194. .IR command (s)
  195. when the
  196. .I position
  197. is reached, and then when
  198. .I condition
  199. becomes true.
  200. If no position is given, do this when
  201. .I condition
  202. becomes true.
  203. If no condition is given, do this when
  204. .I position
  205. is reached.
  206. Either a position or a condition (or both) must be given.
  207. .TP
  208. \fBprint\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
  209. .ti -0.5i
  210. \fBp\fP [ \fIexpression\fP [ , \fIexpression\fP ] ... ]
  211. .br
  212. Print the value of each expression. If no argument is given, repeat the
  213. last
  214. .B print
  215. command.
  216. .TP
  217. \fBdisplay\fP \fIexpression\fP [ , \fIexpression\fP ] ...
  218. Print the value of each expression whenever the program stops.
  219. .TP
  220. .B dump
  221. Saves the data (global data + stack) of the program. These data can
  222. be restore with the
  223. .B restore
  224. command discussed later.
  225. .B Dump
  226. and
  227. .B restore
  228. combinations can be used as a poor man's implementation of an "undo"
  229. facility.
  230. .TP
  231. .B status
  232. Display active
  233. .BR trace ,
  234. .BR stop ,
  235. .BR when ,
  236. and
  237. .B display
  238. commands, and associated command numbers.
  239. Also display current
  240. .B dump
  241. records.
  242. .TP
  243. \fBdelete\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  244. .ti -0.5i
  245. \fBd\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  246. .br
  247. Remove the commands corresponding to the \fIcommandnumber\fP's given
  248. (as displayed by
  249. .BR status ).
  250. If no argument is given and there is a "current" breakpoint, remove that
  251. breakpoint.
  252. .TP
  253. \fBrestore\fP [ \fIcommandnumber\fP ]
  254. .ti -0.5i
  255. \fBr\fP [ \fIcommandnumber\fP ]
  256. .br
  257. Restore the data corresponding to the dump of \fIcommandnumber\fP
  258. (as displayed by
  259. .BR status ).
  260. This restores the values of all variables of the program to the values
  261. at the time the dump was made. The program counter is also restored.
  262. This effectively puts the program back into the state it was when the
  263. dump was made, except for file-handling: the state of the files that
  264. the program handles is not changed.
  265. Apart from this,
  266. .B restore
  267. even works when the program is finished.
  268. If no \fIcommandnumber\fP is given, the last dump is restored.
  269. .TP
  270. \fBstep\fP [ \fIn\fP ]
  271. .ti -0.5i
  272. \fBs\fP [ \fIn\fP ]
  273. .br
  274. Execute the next
  275. .I n
  276. source lines.
  277. If omitted,
  278. .I n
  279. is taken to be 1.
  280. This command steps into functions.
  281. .TP
  282. \fBnext\fP [ \fIn\fP ]
  283. .ti -0.5i
  284. \fBn\fP [ \fIn\fP ]
  285. .br
  286. Execute the next
  287. .I n
  288. source lines.
  289. If omitted,
  290. .I n
  291. is taken to be 1.
  292. .B Next
  293. steps past function-calls.
  294. .TP
  295. \fBwhich\fP \fIname\fP
  296. Print the fully-qualified name of the given name.
  297. .TP
  298. \fBfind\fP \fIname\fP
  299. Print the fully qualified name of all symbols matching
  300. .IR name .
  301. .TP
  302. \fBset\fP \fIexpression\fP \fBto\fP \fIexpression\fP
  303. Assign the value of the second
  304. .I expression
  305. to the designator indicated by the first
  306. .IR expression .
  307. Needless to say, the first
  308. .I expression
  309. must indicate a designator (something that can be assigned to).
  310. If the types do not match,
  311. .B grind
  312. tries to apply conversions.
  313. .TP
  314. \fBwhere\fP [ \fIn\fP | -\fIn\fP ]
  315. .ti -0.5i
  316. \fBw\fP [ \fIn\fP | -\fIn\fP ]
  317. .br
  318. List all, or the top
  319. .IR n ,
  320. or the bottom
  321. .IR n ,
  322. active functions on the stack.
  323. .TP
  324. \fBfile\fP [ \fIfilename\fP ]
  325. Print the name of the current source file, or
  326. change the current source file to
  327. .IR filename .
  328. .TP
  329. \fBlist\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
  330. .ti -0.5i
  331. \fBl\fP [ \fIstartline\fP | \fIfunction\fP ] [ , \fIcount\fP | - [ \fIendline\fP ] ]
  332. .br
  333. If no arguments are given, list the next \fIws\fP (default 10) lines from current source file,
  334. if a
  335. .I startline
  336. is given, list from
  337. .IR startline ,
  338. if a
  339. .I function
  340. is given, list from the first statement of
  341. .IR function .
  342. If a \fIcount\fP is given, list \fIcount\fP lines and set \fIws\fP to \fIcount\fP.
  343. If an \fIendline\fP is given, list up until this line; if a - is given without
  344. an \fIendline\fP, list up until the end of the file.
  345. .TP
  346. \fBhelp\fP [ \fIcommand\fP ]
  347. .ti -0.5i
  348. \fB?\fP [ \fIcommand\fP ]
  349. .br
  350. Print a summary of \fBgrind\fP commands, or print a message explaining
  351. \fIcommand\fP.
  352. .TP
  353. \fBsource\fP \fIfilename\fP
  354. .br
  355. Read and execute \fBgrind\fP commands from \fIfilename\fP. This is useful for
  356. executing \fBgrind\fP log files created with the \fBlog\fP command.
  357. .TP
  358. \fBlog\fP [ \fIfilename\fP | off ]
  359. .br
  360. Start logging the \fBgrind\fP commands given on file \fIfilename\fP, or
  361. stop logging. If no argument is given, the current log file is printed.
  362. In logged commands, an absolute command number is replaced by a relative one.
  363. .TP
  364. \fBdisable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  365. .br
  366. Disable the commands corresponding to the \fIcommandnumber\fP's given
  367. (as displayed by
  368. .BR status ).
  369. If no argument is given and there is a "current" breakpoint, disable that
  370. breakpoint.
  371. Disabling commands keeps them in the status, but makes them inoperative.
  372. Disabled commands can be enabled again with the \fBenable\fP command.
  373. .TP
  374. \fBenable\fP [ \fIcommandnumber\fP [ , \fIcommandnumber\fP ... ] ]
  375. .br
  376. Enable the commands corresponding to the \fIcommandnumber\fP's given
  377. (as displayed by
  378. .BR status ).
  379. If no argument is given and there is a "current" breakpoint, enable that
  380. breakpoint.
  381. .TP
  382. \fB!\fP \fIshellcommand\fP
  383. .br
  384. Invoke the shell with \fIshellcommand\fP. \fIshellcommand\fP extends to the
  385. end of the line. In the command, the characters `%' and `!' are replaced
  386. with the current file name and the previous shell command respectively.
  387. The sequences `\e%' and `\e!' are replaced by `%' and `!' respectively.
  388. .TP
  389. \fBframe\fP [ \fIcount\fP | + \fIcount\fP | - \fIcount\fP ]
  390. .br
  391. The currently active procedure has frame number 0, the one that invoked this
  392. one has frame number 1, etc. The \fBframe\fP command allows the user to
  393. examine stack frames beyond the current one. For instance, after giving the
  394. command `frame 1', variables of the frame invoking the currently active
  395. procedure can be examined. There is a relative and an absolute version of this
  396. command.
  397. .TP
  398. .B quit
  399. .br
  400. Exit
  401. .BR grind .
  402. .LP
  403. Some commands can be repeated without arguments by entering an empty command line:
  404. step, next, list, cont.
  405. .SH SEE ALSO
  406. .IR ack (1).
  407. .IR led (6).
  408. .SH REMARKS
  409. .LP
  410. .B Grind
  411. does not understand the scope of WITH statements. The scope information needed
  412. is not available in the symbol table.
  413. .SH BUGS
  414. .LP
  415. .B Grind
  416. does not correctly handle bit-fields.