3 acid, acidtypes \- debugger
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
56 will store function definitions or print the value of expressions.
60 Allow the textfile to be modified.
63 Print variable renamings at startup.
68 at startup; see below.
71 Assume instructions are for the given CPU type
74 instead of using the executable header to select
78 Debug the kernel state for the process, rather than the user state.
82 obtains standard function definitions from the library file
84 architecture-dependent functions from
85 .BR \*9/acid/$objtype ,
86 user-specified functions from
88 and further functions from
91 Definitions in any file may override previously defined functions.
94 is defined, it will be invoked after all modules have been loaded.
97 will be invoked if defined.
99 provides a definition of
101 that attaches all the shared libraries being used by the target process
107 functions for examining data structures.
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
115 When program symbols conflict with
117 words, distinguishing
120 Such renamings are reported at startup; option
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
131 and separated by commas.
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.
143 .BI append " list", " element
145 .BI delete " list", " subscript
147 Format codes are the same as in
149 Formats may be attached to (unary) expressions with
153 There are two indirection operators,
155 to address a core image,
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.
163 .BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR]
165 .BI while " expr " do " statement
167 .BI loop " expr" , " expr " do " statement
169 .BI defn " name" ( args ") {" " statement \fP}
175 .BI builtin " name" ( args )
181 .BR whatis " [ \fI name \fP]
186 clears the definition for
190 may override a built-in function;
191 prefixing a function call with
193 ignores any overriding
195 forcing the use of the built-in function.
197 Here is a partial list of functions; see the manual for a complete list.
201 Print a stack trace for current process.
204 Print a stack trace with values of local variables.
207 Print general registers.
208 Registers can also be accessed by name, for example
212 Print special registers such as program counter and stack pointer.
215 Print floating-point registers.
221 .BI fmt( expr , format )
224 with format given by the character value of expression
228 Print 10 lines of source around the program address.
231 Get the source line for the program address
232 into a window of a running
237 Print source line nearest to the program address.
240 List current source directories.
242 .BI addsrcdir( string )
243 Add a source directory to the list.
246 Convert a string of the form
247 .IB sourcefile : linenumber
248 to a machine address.
250 .BI pcfile( address )
251 Convert a machine address to a source file name.
253 .BI pcline( address )
254 Convert a machine address to a source line number.
257 List breakpoints set in the current process.
260 Set a breakpoint in the current process at the given address.
261 (Doesn't work on Unix yet.)
264 Delete a breakpoint from the current process.
267 Continue execution of current process and wait for it to stop.
270 Execute a single machine instruction in the current process.
271 (Doesn't work on Unix yet.)
274 Step repeatedly until after a function return.
277 This replaceable function is called automatically when the given process
279 It normally prints the program counter and returns to the prompt.
282 Disassemble 30 machine instructions beginning at the given address.
284 .BI mem( address , string )
285 Print a block of memory
286 interpreted according to a string of format codes.
288 .BI dump( address , n , string\fP)
295 .BI print( expr , ... )
296 Print the values of the expressions.
298 .BI newproc( arguments )
299 Start a new process with arguments given as a string
300 and halt at the first instruction.
305 but take arguments (except
313 but run the process in a separate window.
316 Start a stopped process.
319 Kill the given process.
322 Make the given process current.
327 to execute the command string.
329 .BI include( string )
330 Read acid commands from the named file.
332 .BI includepipe( string )
333 Run the command string, reading its standard output as acid commands.
335 .SS "Shared library segments
336 When a pid or core file is specified on the command line,
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.
342 is started without a pid or core file
343 and is subsequently attached to a process via
345 the shared library maps can be initialized by calling
347 .SS "Type information
348 Unix compilers conventionally include detailed type information
349 in the debugging symbol section of binaries.
352 extracts this information and formats it as
355 Once the shared libraries have been mapped, the default
361 on the set of currently mapped text files.
364 can be called to rerun the command after changing
365 the set of mapped text files.
367 There are a number of
369 `libraries' that provide higher-level debugging facilities. One notable
374 to trace memory allocation.
378 on the program, either by attaching to a running process or by
381 on a binary (perhaps after setting
383 stopping the process, and then running
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
396 set some breakpoints; run up to the first one
397 (this example doesn't work on Unix yet):
401 /bin/ls: mips plan 9 executable
405 70094: system call _main ADD $-0x14,R29
406 70094: breakpoint main+0x4 MOVW R31,0x0(R29)
409 acid: argv0 = **main:argv\es
411 integer variable format s
416 70094: breakpoint ls ADD $-0x16c8,R29
420 Display elements of a linked list of structures:
423 complex Str { 'D' 0 val; 'X' 4 next; };
437 Display an array of bytes declared in C as
446 string format, then prints the string beginning at the address (in
451 Trace the system calls executed by
453 (neither does this one):
456 % acid -l truss /bin/ls
457 /bin/ls:386 plan 9 executable
463 acid: progargs = "-l lib/profile"
468 pread(3, 0x7fffeeac, 20, -1)
472 stat("lib/profile", 0x0000f8cc, 113)
474 open("/env/timezone", 0)
476 pread(3, 0x7fffd7c4, 1680, -1)
478 data: "EST -18000 EDT -14400
479 9943200 25664400 41392800 57718800 73447200 89168400
483 pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
485 --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
488 166: breakpoint _exits+0x5 INTB $0x40
512 At termination, kill commands are proposed
513 for processes that are still active.
515 There is no way to redirect the standard input and standard output
518 Source line selection near the beginning of a file may pick
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.
524 Breakpoints do not work yet.
525 Therefore, commands such as
532 in particular will need some help to cope with dynamic libraries.
