3 acid, truss, trump \- debugger
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
46 will store function definitions or print the value of expressions.
50 Allow the textfile to be modified.
53 Print variable renamings at startup.
58 at startup; see below.
61 Assume instructions are for the given CPU type
71 for the manufacturer-defined instruction notation for those processors)
72 instead of using the magic number to select
76 Debug the kernel state for the process, rather than the user state.
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
86 and further functions from
89 Definitions in any file may override previously defined functions.
92 is defined, it will be invoked after all libraries have been loaded.
95 for information about creating
97 functions for examining data structures.
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
105 When program symbols conflict with
107 words, distinguishing
110 Such renamings are reported at startup if the option
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
121 and separated by commas.
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.
133 .BI append " list", " element
135 .BI delete " list", " subscript
137 Format codes are the same as in
139 Formats may be attached to (unary) expressions with
143 There are two indirection operators,
145 to address a core image,
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.
153 .BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR]
155 .BI while " expr " do " statement
157 .BI loop " expr" , " expr " do " statement
159 .BI defn " name" ( args ") {" " statement \fP}
165 .BI builtin " name" ( args )
171 .BR whatis " [ \fI name \fP]
176 clears the definition for
180 may override a built-in function;
181 prefixing a function call with
183 ignores any overriding
185 forcing the use of the built-in function.
187 Here is a partial list of functions; see the manual for a complete list.
191 Print a stack trace for current process.
194 Print a stack trace with values of local variables.
197 Print general registers.
198 Registers can also be accessed by name, for example
202 Print special registers such as program counter and stack pointer.
205 Print floating-point registers.
211 .BI fmt( expr , format )
214 with format given by the character value of expression
218 Print 10 lines of source around the program address.
221 Get the source line for the program address
222 into a window of a running
227 Print source line nearest to the program address.
230 List current source directories.
232 .BI addsrcdir( string )
233 Add a source directory to the list.
236 Convert a string of the form
237 .IB sourcefile : linenumber
238 to a machine address.
240 .BI pcfile( address )
241 Convert a machine address to a source file name.
243 .BI pcline( address )
244 Convert a machine address to a source line number.
247 List breakpoints set in the current process.
250 Set a breakpoint in the current process at the given address.
253 Delete a breakpoint from the current process.
256 Continue execution of current process and wait for it to stop.
259 Execute a single machine instruction in the current process.
262 Step repeatedly until after a function return.
265 This replaceable function is called automatically when the given process
267 It normally prints the program counter and returns to the prompt.
270 Disassemble 30 machine instructions beginning at the given address.
272 .BI mem( address , string )
273 Print a block of memory
274 interpreted according to a string of format codes.
276 .BI dump( address , n , string\fP)
283 .BI print( expr , ... )
284 Print the values of the expressions.
286 .BI newproc( arguments )
287 Start a new process with arguments given as a string
288 and halt at the first instruction.
293 but take arguments (except
301 but run the process in a separate window.
304 Start a stopped process.
307 Kill the given process.
310 Make the given process current.
315 to execute the command string.
317 There are a number of
319 `libraries' that provide higher-level debugging facilities. Two notable
326 to trace system calls
328 and memory allocation
330 Both require starting
332 on the program, either by attaching to a running process or by
335 on a binary (perhaps after setting
337 stopping the process, and then running
341 to execute the program under the scaffolding.
342 The output will be a trace of the system calls
344 or memory allocation and free calls
346 executed by the program.
347 When finished tracing, stop the process and execute
357 set some breakpoints; run up to the first one:
361 /bin/ls: mips plan 9 executable
365 70094: system call _main ADD $-0x14,R29
366 70094: breakpoint main+0x4 MOVW R31,0x0(R29)
369 acid: argv0 = **main:argv\es
371 integer variable format s
376 70094: breakpoint ls ADD $-0x16c8,R29
380 Display elements of a linked list of structures:
383 complex Str { 'D' 0 val; 'X' 4 next; };
397 Display an array of bytes declared in C as
406 string format, then prints the string beginning at the address (in
411 Trace the system calls executed by
415 % acid -l truss /bin/ls
416 /bin/ls:386 plan 9 executable
422 acid: progargs = "-l lib/profile"
427 pread(3, 0x7fffeeac, 20, -1)
431 stat("lib/profile", 0x0000f8cc, 113)
433 open("/env/timezone", 0)
435 pread(3, 0x7fffd7c4, 1680, -1)
437 data: "EST -18000 EDT -14400
438 9943200 25664400 41392800 57718800 73447200 89168400
442 pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
444 --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
447 166: breakpoint _exits+0x5 INTB $0x40
459 .B /sys/lib/acid/$objtype
461 .B /sys/lib/acid/port
463 .B /sys/lib/acid/kernel
465 .B /sys/lib/acid/trump
467 .B /sys/lib/acid/truss
482 At termination, kill commands are proposed
483 for processes that are still active.
485 There is no way to redirect the standard input and standard output
488 Source line selection near the beginning of a file may pick
491 With the extant stepping commands, one cannot step through instructions
492 outside the text segment and it is hard to debug across process forks.