![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to acid CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Plan 9 NeXT] / lucent / sys / man / 1|
Return to acid CVS log | Up to [Plan 9 NeXT] / lucent / sys / man / 1 |
1.1 root 1: .TH ACID 1
2: .SH NAME
3: acid \- debugger
4: .SH SYNOPSIS
5: .B acid
6: [
7: .BI -l " libfile
8: ]
9: [
10: .B -wq
11: ] [
12: .B -m
13: .I machine
14: ] [
15: .I pid
16: ]
17: [
18: .I textfile
19: ]
20: .SH DESCRIPTION
21: .I Acid
22: is a programmable symbolic debugger.
23: It can inspect one or more processes that share an address space.
24: A program to be debugged may be specified by the process id of
25: a running or defunct process,
26: or by the name of the program's text file
27: .RB ( v.out
28: by default).
29: At the prompt,
30: .I acid
31: will store function definitions or print the value of expressions.
32: Options are
33: .TP .9i
34: .B -w
35: Allow the textfile to be modified.
36: .TP
37: .B -q
38: Don't print variable renamings at startup.
39: .TP
40: .BI -l " library
41: Load from
42: .I library
43: at startup; see below.
44: .TP
45: .BI -m " machine
46: Assume instructions are for the given CPU type
47: (one of
48: .BR 3210 ,
49: .BR 386 ,
50: .BR 68020 ,
51: .BR 960 ,
52: .BR mips ,
53: .BR mipsco ,
54: .BR sparc ,
55: or
56: .BR sunsparc )
57: instead of using the magic number to select
58: the CPU type.
59: .PP
60: At startup,
61: .I acid
62: obtains standard function definitions from the library file
63: .BR /lib/acid/port ,
64: architecture-dependent functions from
65: .BR /lib/acid/$objtype ,
66: user-specified functions from
67: .BR $home/lib/acid ,
68: and further functions from
69: .B -l
70: files.
71: Definitions in any file may override previously defined functions.
72: If the function
73: .IR acidinit ()
74: is defined, it will be invoked after all modules have been loaded.
75: See
76: .IR 2c (1)
77: and
78: .IR alef (1)
79: for information about creating
80: .I acid
81: functions for examining data structures.
82: .SS Language
83: Symbols of the program being debugged become integer
84: variables whose values are addresses.
85: Contents of addresses are obtained by indirection.
86: Local variables are qualified by
87: function name, for example
88: .BR main:argv .
89: When program symbols conflict with
90: .I acid
91: words, distinguishing
92: .B $
93: signs are prefixed.
94: Such renamings are reported at startup; option
95: .B -q
96: suppresses them.
97: .PP
98: Variable types
99: .RI ( "integer, float, list, string" )
100: and formats are inferred from assignments.
101: Truth values false/true are attributed to zero/nonzero
102: integers or floats and to empty/nonempty lists or strings.
103: Lists are sequences of expressions surrounded by
104: .BR {\^}
105: and separated by commas.
106: .PP
107: Expressions are much as in C or Alef,
108: but yield both a value and a format.
109: Alef-style casts to complex types are allowed.
110: Lists admit the following operators, with
111: subscripts counted from 0.
112: .IP
113: .BI head " list
114: .br
115: .BI tail " list
116: .br
117: .BI append " list", " element
118: .br
119: .BI delete " list", " subscript
120: .PP
121: Format codes are the same as in
122: .IR db (1).
123: Formats may be attached to (unary) expressions with
124: .BR \e ,
125: e.g.
126: .BR (32*7)\eD .
127: There are two indirection operators,
128: .B *
129: to address a core image,
130: .B @
131: to address a text file.
132: The type and format of the result are determined by the format of the operand,
133: whose type must be integer.
134: .PP
135: Statements are
136: .IP
137: .BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR]
138: .br
139: .BI while " expr " do " statement
140: .br
141: .BI loop " expr" , " expr " do " statement
142: .br
143: .BI defn " name" ( args ") {" " statement \fP}
144: .br
145: .BI local " name
146: .br
147: .BI return " expr
148: .br
149: .BR whatis " [ \fI name \fP]
150: .PP
151: Here is a partial list of functions; see the manual for a complete list.
152: .TF asm(address)
153: .TP
154: .B stk()
155: Print a stack trace for current process.
156: .TP
157: .B lstk()
158: Print a stack trace with values of local variables.
159: .TP
160: .B gpr()
161: Print general registers.
162: Registers can also be accessed by name, for example
163: .BR *R0 .
164: .TP
165: .B spr()
166: Print special registers such as program counter and stack pointer.
167: .TP
168: .B fpr()
169: Print floating-point registers.
170: .TP
171: .B regs()
172: Same as
173: .BR spr();gpr() .
174: .TP
175: .BI fmt( expr , format )
176: Expression
177: .I expr
178: with format given by the character value of expression
179: .IR format .
180: .TP
181: .BI src( address )
182: Print 10 lines of source around the program address.
183: .TP
184: .BI Bsrc( address )
185: Get the source line for the program address
186: into a window of a running
187: .IR sam (1)
188: and select it.
189: .TP
190: .BI line( address )
191: Print source line nearest to the program address.
192: .TP
193: .B source()
194: List current source directories.
195: .TP
196: .BI addsrcdir( string )
197: Add a source directory to the list.
198: .TP
199: .BI filepc( where )
200: Convert a string of the form
201: .IB sourcefile : linenumber
202: to a machine address.
203: .TP
204: .BI pcfile( address )
205: Convert a machine address to a source file name.
206: .TP
207: .BI pcline( address )
208: Convert a machine address to a source line number.
209: .TP
210: .BI bptab()
211: List breakpoints set in the current process.
212: .TP
213: .BI bpset( address )
214: Set a breakpoint in the current process at the given address.
215: .TP
216: .BI bpdel( address )
217: Delete a breakpoint from the current process.
218: .TP
219: .B cont()
220: Continue execution of current process and wait for it to stop.
221: .TP
222: .B step()
223: Execute a single machine instruction in the current process.
224: .TP
225: .B func()
226: Step repeatedly until after a function return.
227: .TP
228: .BI stopped( pid )
229: This replaceable function is called automatically when the given process
230: stops.
231: It normally prints the program counter and returns to the prompt.
232: .TP
233: .BI asm( address )
234: Disassemble 30 machine instructions beginning at the given address.
235: .TP
236: .BI mem( address , string )
237: Print a block of memory
238: interpreted according to a string of format codes.
239: .TP
240: .BI dump( address , n , string\fP)
241: Like
242: .BR mem (),
243: repeated for
244: .I n
245: consecutive blocks.
246: .TP
247: .BI print( expr , ... )
248: Print the values of the expressions.
249: .TP
250: .BI newproc( arguments )
251: Start a new process with arguments given as a string
252: and halt at the first instruction.
253: .TP
254: .B new()
255: Like
256: .IR newproc (),
257: but take arguments (except
258: .BR argv[0] )
259: from string variable
260: .BR progargs .
261: .TP
262: .B win()
263: Like
264: .IR new (),
265: but run the process in a separate window.
266: .TP
267: .BI start( pid )
268: Start a stopped process.
269: .TP
270: .BI kill( pid )
271: Kill the given process.
272: .TP
273: .BI setproc( pid )
274: Make the given process current.
275: .TP
276: .BI rc( string )
277: Escape to the shell,
278: .IR rc (1),
279: to execute the command string.
280: .SH EXAMPLES
281: Start to debug
282: .BR /bin/ls ;
283: set some breakpoints; run up to the first one:
284: .IP
285: .EX
286: % acid /bin/ls
287: /bin/ls: mips plan 9 executable
288: /lib/acid/port
289: /lib/acid/mips
290: acid: new()
291: 70094: system call _main ADD $-0x14,R29
292: 70094: breakpoint main+0x4 MOVW R31,0x0(R29)
293: acid: pid
294: 70094
295: acid: argv0 = **main:argv\es
296: acid: whatis argv0
297: integer variable format s
298: acid: *argv0
299: /bin/ls
300: acid: bpset(ls)
301: acid: cont()
302: 70094: breakpoint ls ADD $-0x16c8,R29
303: acid:
304: .EE
305: .PP
306: Display elements of a linked list of structures:
307: .IP
308: .EX
309: complex Str { 'D' 0 val; 'X' 4 next; };
310: complex Str s;
311: s = *headstr;
312: while s != 0 do{
313: print(s.val, "\en");
314: s = s.next;
315: }
316: .EE
317: .PP
318: Note the use of the
319: .B .
320: operator instead of
321: .BR -> .
322: .PP
323: Display an array of bytes declared in C as
324: .BR "char array[]" .
325: .IP
326: .EX
327: *(array\es)
328: .EE
329: .PP
330: This example gives
331: .B array
332: string format, then prints the string beginning at the address (in
333: .I acid
334: notation)
335: .BR *array .
336: .SH FILES
337: .B /proc/*/text
338: .br
339: .B /proc/*/mem
340: .br
341: .B /proc/*/ctl
342: .br
343: .B /proc/*/note
344: .br
345: .B /lib/acid/$objtype
346: .br
347: .B /lib/acid/port
348: .br
349: .B $home/lib/acid
350: .SH SOURCE
351: .B /sys/src/cmd/acid
352: .SH "SEE ALSO"
353: .IR 2a (1),
354: .IR 2c (1),
355: .IR 2l (1),
356: .IR alef (1),
357: .IR mk (1),
358: .IR db (1)
359: .br
360: Phil Winterbottom,
361: ``Acid Manual''.
362: .SH DIAGNOSTICS
363: At termination, kill commands are proposed
364: for processes that are still active.
365: .SH BUGS
366: There is no way to redirect the standard input and standard output
367: of a new process.
368: .br
369: Source line selection near the beginning of a file may pick
370: an adjacent file.
371: .br
372: With the extant stepping commands, one cannot step through instructions
373: outside the text segment and it is hard to debug across process forks.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.