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