sys/man/1/acid

   1 .TH ACID 1
   2 .SH NAME
   3 acid, truss, trump \- debugger
   4 .SH SYNOPSIS
   5 .B acid
   6 [
   7 .B -kqw
   8 ]
   9 [
  10 .BI -l " library
  11 ] [
  12 .B -m
  13 .I machine
  14 ] [
  15 .I pid
  16 ]
  17 [
  18 .I textfile
  19 ]
  20 .PP
  21 .B acid
  22 .B -l
  23 .B truss
  24 .I textfile
  25 .PP
  26 .B acid
  27 .B -l
  28 .B trump
  29 [
  30 .I pid
  31 ]
  32 [
  33 .I textfile
  34 ]
  35 .SH DESCRIPTION
  36 .I Acid
  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
  42 .RB ( 8.out
  43 by default).
  44 At the prompt,
  45 .I acid
  46 will store function definitions or print the value of expressions.
  47 Options are
  48 .TP .9i
  49 .B -w
  50 Allow the textfile to be modified.
  51 .TP
  52 .B -q
  53 Print variable renamings at startup.
  54 .TP
  55 .BI -l " library
  56 Load from
  57 .I library
  58 at startup; see below.
  59 .TP
  60 .BI -m " machine
  61 Assume instructions are for the given CPU type
  62 (one of
  63 .BR amd64 ,
  64 .BR 386 ,
  65 etc., as listed in
  66 .IR 2c (1),
  67 or
  68 .B sunsparc
  69 or
  70 .B mipsco
  71 for the  manufacturer-defined instruction notation for those processors)
  72 instead of using the magic number to select
  73 the CPU type.
  74 .TP
  75 .BI -k
  76 Debug the kernel state for the process, rather than the user state.
  77 .PP
  78 At startup,
  79 .I acid
  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
  85 .BR $home/lib/acid ,
  86 and further functions from
  87 .B -l
  88 files.
  89 Definitions in any file may override previously defined functions.
  90 If the function
  91 .IR acidinit ()
  92 is defined, it will be invoked after all libraries have been loaded.
  93 See
  94 .IR 2c (1)
  95 for information about creating
  96 .I acid
  97 functions for examining data structures.
  98 .SS Language
  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
 104 .BR main:argv .
 105 When program symbols conflict with
 106 .I acid
 107 words, distinguishing
 108 .B $
 109 signs are prefixed.
 110 Such renamings are reported at startup if the option
 111 .B -q
 112 is enabled.
 113 .PP
 114 Variable types
 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
 120 .BR {\^}
 121 and separated by commas.
 122 .PP
 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.
 128 .IP
 129 .BI head " list
 130 .br
 131 .BI tail " list
 132 .br
 133 .BI append " list", " element
 134 .br
 135 .BI delete " list", " subscript
 136 .PP
 137 Format codes are the same as in
 138 .IR db (1).
 139 Formats may be attached to (unary) expressions with
 140 .BR \e ,
 141 e.g.
 142 .BR (32*7)\eD .
 143 There are two indirection operators,
 144 .B *
 145 to address a core image,
 146 .B @
 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.
 150 .PP
 151 Statements are
 152 .IP
 153 .BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR]
 154 .br
 155 .BI while " expr " do " statement
 156 .br
 157 .BI loop " expr" , " expr " do " statement
 158 .br
 159 .BI defn " name" ( args ") {" " statement \fP}
 160 .br
 161 .BI defn " name"
 162 .br
 163 .IB name ( args )
 164 .br
 165 .BI builtin " name" ( args )
 166 .br
 167 .BI local " name
 168 .br
 169 .BI return " expr
 170 .br
 171 .BR whatis " [ \fI name \fP]
 172 .PP
 173 The statement
 174 .B defn
 175 .I name
 176 clears the definition for
 177 .IR name .
 178 A
 179 .B defn
 180 may override a built-in function;
 181 prefixing a function call with
 182 .B builtin
 183 ignores any overriding
 184 .BR defn ,
 185 forcing the use of the built-in function.
 186 .PP
 187 Here is a partial list of functions; see the manual for a complete list.
 188 .TF asm(address)
 189 .TP
 190 .B stk()
 191 Print a stack trace for current process.
 192 .TP
 193 .B lstk()
 194 Print a stack trace with values of local variables.
 195 .TP
 196 .B gpr()
 197 Print general registers.
 198 Registers can also be accessed by name, for example
 199 .BR *R0 .
 200 .TP
 201 .B spr()
 202 Print special registers such as program counter and stack pointer.
 203 .TP
 204 .B fpr()
 205 Print floating-point registers.
 206 .TP
 207 .B regs()
 208 Same as
 209 .BR spr();gpr() .
 210 .TP
 211 .BI fmt( expr , format )
 212 Expression
 213 .I expr
 214 with format given by the character value of expression
 215 .IR format .
 216 .TP
 217 .BI src( address )
 218 Print 10 lines of source around the program address.
 219 .TP
 220 .BI Bsrc( address )
 221 Get the source line for the program address
 222 into a window of a running
 223 .IR sam (1)
 224 and select it.
 225 .TP
 226 .BI line( address )
 227 Print source line nearest to the program address.
 228 .TP
 229 .B source()
 230 List current source directories.
 231 .TP
 232 .BI addsrcdir( string )
 233 Add a source directory to the list.
 234 .TP
 235 .BI filepc( where )
 236 Convert a string of the form
 237 .IB sourcefile : linenumber
 238 to a machine address.
 239 .TP
 240 .BI pcfile( address )
 241 Convert a machine address to a source file name.
 242 .TP
 243 .BI pcline( address )
 244 Convert a machine address to a source line number.
 245 .TP
 246 .BI bptab()
 247 List breakpoints set in the current process.
 248 .TP
 249 .BI bpset( address )
 250 Set a breakpoint in the current process at the given address.
 251 .TP
 252 .BI bpdel( address )
 253 Delete a breakpoint from the current process.
 254 .TP
 255 .BI wptab()
 256 List watchpoints set in the current process.
 257 .TP
 258 \fLwpset(\fItype\fL,\fIaddr\fL,\fIlen\fL)
 259 Set a watchpoint for the \fIlen\fR bytes at the given address.
 260 \fItype\fR is \fL"r"\fR, \fL"w"\fR or \fL"rw"\fR to trap read accesses, write accesses or both, respectively.
 261 .TP
 262 .BI wpdel( address )
 263 Delete all watchpoints set for the given address.
 264 .TP
 265 .B cont()
 266 Continue execution of current process and wait for it to stop.
 267 .TP
 268 .B step()
 269 Execute a single machine instruction in the current process.
 270 .TP
 271 .B func()
 272 Step repeatedly until after a function return.
 273 .TP
 274 .BI stopped( pid )
 275 This replaceable function is called automatically when the given process
 276 stops.
 277 It normally prints the program counter and returns to the prompt.
 278 .TP
 279 .BI asm( address )
 280 Disassemble 30 machine instructions beginning at the given address.
 281 .TP
 282 .BI mem( address , string )
 283 Print a block of memory
 284 interpreted according to a string of format codes.
 285 .TP
 286 .BI dump( address , n , string\fP)
 287 Like
 288 .BR mem (),
 289 repeated for
 290 .I n
 291 consecutive blocks.
 292 .TP
 293 .BI print( expr , ... )
 294 Print the values of the expressions.
 295 .TP
 296 .BI newproc( arguments )
 297 Start a new process with arguments given as a string
 298 and halt at the first instruction.
 299 .TP
 300 .B new()
 301 Like
 302 .IR newproc (),
 303 but take arguments (except
 304 .BR argv[0] )
 305 from string variable
 306 .BR progargs .
 307 .TP
 308 .B win()
 309 Like
 310 .IR new (),
 311 but run the process in a separate window.
 312 .TP
 313 .BI start( pid )
 314 Start a stopped process.
 315 .TP
 316 .BI kill( pid )
 317 Kill the given process.
 318 .TP
 319 .BI setproc( pid )
 320 Make the given process current.
 321 .TP
 322 .BI rc( string )
 323 Escape to the shell,
 324 .IR rc (1),
 325 to execute the command string.
 326 .SS Libraries
 327 There are a number of
 328 .I acid
 329 `libraries' that provide higher-level debugging facilities.  Two notable
 330 examples are
 331 .I truss
 332 and
 333 .IR trump ,
 334 which use
 335 .I acid
 336 to trace system calls
 337 .RI ( truss )
 338 and memory allocation
 339 .RI ( trump ).
 340 Both require starting
 341 .I acid
 342 on the program, either by attaching to a running process or by
 343 executing
 344 .B new()
 345 on a binary (perhaps after setting
 346 .BR progargs ),
 347 stopping the process, and then running
 348 .B truss()
 349 or
 350 .B trump()
 351 to execute the program under the scaffolding.
 352 The output will be a trace of the system calls
 353 .RI ( truss )
 354 or memory allocation and free calls
 355 .RI ( trump )
 356 executed by the program.
 357 When finished tracing, stop the process and execute
 358 .B untruss()
 359 or
 360 .B untrump()
 361 followed by
 362 .B cont()
 363 to resume execution.
 364 .SH EXAMPLES
 365 Start to debug
 366 .BR /bin/ls ;
 367 set some breakpoints; run up to the first one:
 368 .IP
 369 .EX
 370 % acid /bin/ls
 371 /bin/ls: mips plan 9 executable
 372 /sys/lib/acid/port
 373 /sys/lib/acid/mips
 374 acid: new()
 375 70094: system call      _main   ADD     $-0x14,R29
 376 70094: breakpoint       main+0x4        MOVW    R31,0x0(R29)
 377 acid: pid
 378 70094
 379 acid: argv0 = **main:argv\es
 380 acid: whatis argv0
 381 integer variable format s
 382 acid: *argv0
 383 /bin/ls
 384 acid: bpset(ls)
 385 acid: cont()
 386 70094: breakpoint  ls   ADD     $-0x16c8,R29
 387 acid:
 388 .EE
 389 .PP
 390 Display elements of a linked list of structures:
 391 .IP
 392 .EX
 393 complex Str { 'D' 0 val; 'X' 4 next; };
 394 complex Str s;
 395 s = *headstr;
 396 while s != 0 do{
 397         print(s.val, "\en");
 398         s = s.next;
 399 }
 400 .EE
 401 .PP
 402 Note the use of the
 403 .B .
 404 operator instead of
 405 .BR -> .
 406 .PP
 407 Display an array of bytes declared in C as
 408 .BR "char array[]" .
 409 .IP
 410 .EX
 411 *(array\es)
 412 .EE
 413 .PP
 414 This example gives
 415 .B array
 416 string format, then prints the string beginning at the address (in
 417 .I acid
 418 notation)
 419 .BR *array .
 420 .PP
 421 Trace the system calls executed by
 422 .IR ls (1):
 423 .IP
 424 .EX
 425 % acid -l truss /bin/ls
 426 /bin/ls:386 plan 9 executable
 427
 428 /sys/lib/acid/port
 429 /sys/lib/acid/kernel
 430 /sys/lib/acid/truss
 431 /sys/lib/acid/386
 432 acid: progargs = "-l lib/profile"
 433 acid: new()
 434 acid: truss()
 435 open("#c/pid", 0)
 436         return value: 3
 437 pread(3, 0x7fffeeac, 20, -1)
 438         return value: 12
 439         data: "        166 "
 440 \&...
 441 stat("lib/profile", 0x0000f8cc, 113)
 442         return value: 65
 443 open("/env/timezone", 0)
 444         return value: 3
 445 pread(3, 0x7fffd7c4, 1680, -1)
 446         return value: 1518
 447         data: "EST -18000 EDT -14400
 448    9943200   25664400   41392800   57718800   73447200   89168400
 449  104896800  ..."
 450 close(3)
 451         return value: 0
 452 pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
 453 ", 54, -1)
 454 --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
 455         return value: 54
 456 \&...
 457 166: breakpoint _exits+0x5      INTB    $0x40
 458 acid: cont()
 459 .EE
 460 .SH FILES
 461 .B /proc/*/text
 462 .br
 463 .B /proc/*/mem
 464 .br
 465 .B /proc/*/ctl
 466 .br
 467 .B /proc/*/note
 468 .br
 469 .B /sys/lib/acid/$objtype
 470 .br
 471 .B /sys/lib/acid/port
 472 .br
 473 .B /sys/lib/acid/kernel
 474 .br
 475 .B /sys/lib/acid/trump
 476 .br
 477 .B /sys/lib/acid/truss
 478 .br
 479 .B $home/lib/acid
 480 .SH SOURCE
 481 .B /sys/src/cmd/acid
 482 .SH "SEE ALSO"
 483 .IR 2a (1),
 484 .IR 2c (1),
 485 .IR 2l (1),
 486 .IR mk (1),
 487 .IR db (1)
 488 .br
 489 Phil Winterbottom,
 490 ``Acid Manual''.
 491 .SH DIAGNOSTICS
 492 At termination, kill commands are proposed
 493 for processes that are still active.
 494 .SH BUGS
 495 There is no way to redirect the standard input and standard output
 496 of a new process.
 497 .br
 498 Source line selection near the beginning of a file may pick
 499 an adjacent file.
 500 .br
 501 With the extant stepping commands, one cannot step through instructions
 502 outside the text segment and it is hard to debug across process forks.