acid.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.