acid 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492
  1. .TH ACID 1
  2. .SH NAME
  3. acid, truss, trump \- debugger
  4. .SH SYNOPSIS
  5. .B acid
  6. [
  7. .B -kqw
  8. ]
  9. [
  10. .BI -l " library
  11. ] [
  12. .B -m
  13. .I machine
  14. ] [
  15. .I pid
  16. ]
  17. [
  18. .I textfile
  19. ]
  20. .PP
  21. .B acid
  22. .B -l
  23. .B truss
  24. .I textfile
  25. .PP
  26. .B acid
  27. .B -l
  28. .B trump
  29. [
  30. .I pid
  31. ]
  32. [
  33. .I textfile
  34. ]
  35. .SH DESCRIPTION
  36. .I Acid
  37. is a programmable symbolic debugger.
  38. It can inspect one or more processes that share an address space.
  39. A program to be debugged may be specified by the process id of
  40. a running or defunct process,
  41. or by the name of the program's text file
  42. .RB ( 8.out
  43. by default).
  44. At the prompt,
  45. .I acid
  46. will store function definitions or print the value of expressions.
  47. Options are
  48. .TP .9i
  49. .B -w
  50. Allow the textfile to be modified.
  51. .TP
  52. .B -q
  53. Print variable renamings at startup.
  54. .TP
  55. .BI -l " library
  56. Load from
  57. .I library
  58. at startup; see below.
  59. .TP
  60. .BI -m " machine
  61. Assume instructions are for the given CPU type
  62. (one of
  63. .BR alpha ,
  64. .BR 386 ,
  65. etc., as listed in
  66. .IR 2c (1),
  67. or
  68. .B sunsparc
  69. or
  70. .B mipsco
  71. for the manufacturer-defined instruction notation for those processors)
  72. instead of using the magic number to select
  73. the CPU type.
  74. .TP
  75. .BI -k
  76. Debug the kernel state for the process, rather than the user state.
  77. .PP
  78. At startup,
  79. .I acid
  80. obtains standard function definitions from the library file
  81. .BR /sys/lib/acid/port ,
  82. architecture-dependent functions from
  83. .BR /sys/lib/acid/$objtype ,
  84. user-specified functions from
  85. .BR $home/lib/acid ,
  86. and further functions from
  87. .B -l
  88. files.
  89. Definitions in any file may override previously defined functions.
  90. If the function
  91. .IR acidinit ()
  92. is defined, it will be invoked after all libraries have been loaded.
  93. See
  94. .IR 2c (1)
  95. for information about creating
  96. .I acid
  97. functions for examining data structures.
  98. .SS Language
  99. Symbols of the program being debugged become integer
  100. variables whose values are addresses.
  101. Contents of addresses are obtained by indirection.
  102. Local variables are qualified by
  103. function name, for example
  104. .BR main:argv .
  105. When program symbols conflict with
  106. .I acid
  107. words, distinguishing
  108. .B $
  109. signs are prefixed.
  110. Such renamings are reported at startup if the option
  111. .B -q
  112. is enabled.
  113. .PP
  114. Variable types
  115. .RI ( "integer, float, list, string" )
  116. and formats are inferred from assignments.
  117. Truth values false/true are attributed to zero/nonzero
  118. integers or floats and to empty/nonempty lists or strings.
  119. Lists are sequences of expressions surrounded by
  120. .BR {\^}
  121. and separated by commas.
  122. .PP
  123. Expressions are much as in C,
  124. but yield both a value and a format.
  125. Casts to complex types are allowed.
  126. Lists admit the following operators, with
  127. subscripts counted from 0.
  128. .IP
  129. .BI head " list
  130. .br
  131. .BI tail " list
  132. .br
  133. .BI append " list", " element
  134. .br
  135. .BI delete " list", " subscript
  136. .PP
  137. Format codes are the same as in
  138. .IR db (1).
  139. Formats may be attached to (unary) expressions with
  140. .BR \e ,
  141. e.g.
  142. .BR (32*7)\eD .
  143. There are two indirection operators,
  144. .B *
  145. to address a core image,
  146. .B @
  147. to address a text file.
  148. The type and format of the result are determined by the format of the operand,
  149. whose type must be integer.
  150. .PP
  151. Statements are
  152. .IP
  153. .BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR]
  154. .br
  155. .BI while " expr " do " statement
  156. .br
  157. .BI loop " expr" , " expr " do " statement
  158. .br
  159. .BI defn " name" ( args ") {" " statement \fP}
  160. .br
  161. .BI defn " name"
  162. .br
  163. .IB name ( args )
  164. .br
  165. .BI builtin " name" ( args )
  166. .br
  167. .BI local " name
  168. .br
  169. .BI return " expr
  170. .br
  171. .BR whatis " [ \fI name \fP]
  172. .PP
  173. The statement
  174. .B defn
  175. .I name
  176. clears the definition for
  177. .IR name .
  178. A
  179. .B defn
  180. may override a built-in function;
  181. prefixing a function call with
  182. .B builtin
  183. ignores any overriding
  184. .BR defn ,
  185. forcing the use of the built-in function.
  186. .PP
  187. Here is a partial list of functions; see the manual for a complete list.
  188. .TF asm(address)
  189. .TP
  190. .B stk()
  191. Print a stack trace for current process.
  192. .TP
  193. .B lstk()
  194. Print a stack trace with values of local variables.
  195. .TP
  196. .B gpr()
  197. Print general registers.
  198. Registers can also be accessed by name, for example
  199. .BR *R0 .
  200. .TP
  201. .B spr()
  202. Print special registers such as program counter and stack pointer.
  203. .TP
  204. .B fpr()
  205. Print floating-point registers.
  206. .TP
  207. .B regs()
  208. Same as
  209. .BR spr();gpr() .
  210. .TP
  211. .BI fmt( expr , format )
  212. Expression
  213. .I expr
  214. with format given by the character value of expression
  215. .IR format .
  216. .TP
  217. .BI src( address )
  218. Print 10 lines of source around the program address.
  219. .TP
  220. .BI Bsrc( address )
  221. Get the source line for the program address
  222. into a window of a running
  223. .IR sam (1)
  224. and select it.
  225. .TP
  226. .BI line( address )
  227. Print source line nearest to the program address.
  228. .TP
  229. .B source()
  230. List current source directories.
  231. .TP
  232. .BI addsrcdir( string )
  233. Add a source directory to the list.
  234. .TP
  235. .BI filepc( where )
  236. Convert a string of the form
  237. .IB sourcefile : linenumber
  238. to a machine address.
  239. .TP
  240. .BI pcfile( address )
  241. Convert a machine address to a source file name.
  242. .TP
  243. .BI pcline( address )
  244. Convert a machine address to a source line number.
  245. .TP
  246. .BI bptab()
  247. List breakpoints set in the current process.
  248. .TP
  249. .BI bpset( address )
  250. Set a breakpoint in the current process at the given address.
  251. .TP
  252. .BI bpdel( address )
  253. Delete a breakpoint from the current process.
  254. .TP
  255. .B cont()
  256. Continue execution of current process and wait for it to stop.
  257. .TP
  258. .B step()
  259. Execute a single machine instruction in the current process.
  260. .TP
  261. .B func()
  262. Step repeatedly until after a function return.
  263. .TP
  264. .BI stopped( pid )
  265. This replaceable function is called automatically when the given process
  266. stops.
  267. It normally prints the program counter and returns to the prompt.
  268. .TP
  269. .BI asm( address )
  270. Disassemble 30 machine instructions beginning at the given address.
  271. .TP
  272. .BI mem( address , string )
  273. Print a block of memory
  274. interpreted according to a string of format codes.
  275. .TP
  276. .BI dump( address , n , string\fP)
  277. Like
  278. .BR mem (),
  279. repeated for
  280. .I n
  281. consecutive blocks.
  282. .TP
  283. .BI print( expr , ... )
  284. Print the values of the expressions.
  285. .TP
  286. .BI newproc( arguments )
  287. Start a new process with arguments given as a string
  288. and halt at the first instruction.
  289. .TP
  290. .B new()
  291. Like
  292. .IR newproc (),
  293. but take arguments (except
  294. .BR argv[0] )
  295. from string variable
  296. .BR progargs .
  297. .TP
  298. .B win()
  299. Like
  300. .IR new (),
  301. but run the process in a separate window.
  302. .TP
  303. .BI start( pid )
  304. Start a stopped process.
  305. .TP
  306. .BI kill( pid )
  307. Kill the given process.
  308. .TP
  309. .BI setproc( pid )
  310. Make the given process current.
  311. .TP
  312. .BI rc( string )
  313. Escape to the shell,
  314. .IR rc (1),
  315. to execute the command string.
  316. .SS Libraries
  317. There are a number of
  318. .I acid
  319. `libraries' that provide higher-level debugging facilities. Two notable
  320. examples are
  321. .I truss
  322. and
  323. .IR trump ,
  324. which use
  325. .I acid
  326. to trace system calls
  327. .RI ( truss )
  328. and memory allocation
  329. .RI ( trump ).
  330. Both require starting
  331. .I acid
  332. on the program, either by attaching to a running process or by
  333. executing
  334. .B new()
  335. on a binary (perhaps after setting
  336. .BR progargs ),
  337. stopping the process, and then running
  338. .B truss()
  339. or
  340. .B trump()
  341. to execute the program under the scaffolding.
  342. The output will be a trace of the system calls
  343. .RI ( truss )
  344. or memory allocation and free calls
  345. .RI ( trump )
  346. executed by the program.
  347. When finished tracing, stop the process and execute
  348. .B untruss()
  349. or
  350. .B untrump()
  351. followed by
  352. .B cont()
  353. to resume execution.
  354. .SH EXAMPLES
  355. Start to debug
  356. .BR /bin/ls ;
  357. set some breakpoints; run up to the first one:
  358. .IP
  359. .EX
  360. % acid /bin/ls
  361. /bin/ls: mips plan 9 executable
  362. /sys/lib/acid/port
  363. /sys/lib/acid/mips
  364. acid: new()
  365. 70094: system call _main ADD $-0x14,R29
  366. 70094: breakpoint main+0x4 MOVW R31,0x0(R29)
  367. acid: pid
  368. 70094
  369. acid: argv0 = **main:argv\es
  370. acid: whatis argv0
  371. integer variable format s
  372. acid: *argv0
  373. /bin/ls
  374. acid: bpset(ls)
  375. acid: cont()
  376. 70094: breakpoint ls ADD $-0x16c8,R29
  377. acid:
  378. .EE
  379. .PP
  380. Display elements of a linked list of structures:
  381. .IP
  382. .EX
  383. complex Str { 'D' 0 val; 'X' 4 next; };
  384. complex Str s;
  385. s = *headstr;
  386. while s != 0 do{
  387. print(s.val, "\en");
  388. s = s.next;
  389. }
  390. .EE
  391. .PP
  392. Note the use of the
  393. .B .
  394. operator instead of
  395. .BR -> .
  396. .PP
  397. Display an array of bytes declared in C as
  398. .BR "char array[]" .
  399. .IP
  400. .EX
  401. *(array\es)
  402. .EE
  403. .PP
  404. This example gives
  405. .B array
  406. string format, then prints the string beginning at the address (in
  407. .I acid
  408. notation)
  409. .BR *array .
  410. .PP
  411. Trace the system calls executed by
  412. .IR ls (1):
  413. .IP
  414. .EX
  415. % acid -l truss /bin/ls
  416. /bin/ls:386 plan 9 executable
  417. /sys/lib/acid/port
  418. /sys/lib/acid/kernel
  419. /sys/lib/acid/truss
  420. /sys/lib/acid/386
  421. acid: progargs = "-l lib/profile"
  422. acid: new()
  423. acid: truss()
  424. open("#c/pid", 0)
  425. return value: 3
  426. pread(3, 0x7fffeeac, 20, -1)
  427. return value: 12
  428. data: " 166 "
  429. \&...
  430. stat("lib/profile", 0x0000f8cc, 113)
  431. return value: 65
  432. open("/env/timezone", 0)
  433. return value: 3
  434. pread(3, 0x7fffd7c4, 1680, -1)
  435. return value: 1518
  436. data: "EST -18000 EDT -14400
  437. 9943200 25664400 41392800 57718800 73447200 89168400
  438. 104896800 ..."
  439. close(3)
  440. return value: 0
  441. pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
  442. ", 54, -1)
  443. --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
  444. return value: 54
  445. \&...
  446. 166: breakpoint _exits+0x5 INTB $0x40
  447. acid: cont()
  448. .EE
  449. .SH FILES
  450. .B /proc/*/text
  451. .br
  452. .B /proc/*/mem
  453. .br
  454. .B /proc/*/ctl
  455. .br
  456. .B /proc/*/note
  457. .br
  458. .B /sys/lib/acid/$objtype
  459. .br
  460. .B /sys/lib/acid/port
  461. .br
  462. .B /sys/lib/acid/kernel
  463. .br
  464. .B /sys/lib/acid/trump
  465. .br
  466. .B /sys/lib/acid/truss
  467. .br
  468. .B $home/lib/acid
  469. .SH SOURCE
  470. .B /sys/src/cmd/acid
  471. .SH "SEE ALSO"
  472. .IR 2a (1),
  473. .IR 2c (1),
  474. .IR 2l (1),
  475. .IR mk (1),
  476. .IR db (1)
  477. .br
  478. Phil Winterbottom,
  479. ``Acid Manual''.
  480. .SH DIAGNOSTICS
  481. At termination, kill commands are proposed
  482. for processes that are still active.
  483. .SH BUGS
  484. There is no way to redirect the standard input and standard output
  485. of a new process.
  486. .br
  487. Source line selection near the beginning of a file may pick
  488. an adjacent file.
  489. .br
  490. With the extant stepping commands, one cannot step through instructions
  491. outside the text segment and it is hard to debug across process forks.