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 alpha ,
  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 .B cont()
 256 Continue execution of current process and wait for it to stop.
 257 .TP
 258 .B step()
 259 Execute a single machine instruction in the current process.
 260 .TP
 261 .B func()
 262 Step repeatedly until after a function return.
 263 .TP
 264 .BI stopped( pid )
 265 This replaceable function is called automatically when the given process
 266 stops.
 267 It normally prints the program counter and returns to the prompt.
 268 .TP
 269 .BI asm( address )
 270 Disassemble 30 machine instructions beginning at the given address.
 271 .TP
 272 .BI mem( address , string )
 273 Print a block of memory
 274 interpreted according to a string of format codes.
 275 .TP
 276 .BI dump( address , n , string\fP)
 277 Like
 278 .BR mem (),
 279 repeated for
 280 .I n
 281 consecutive blocks.
 282 .TP
 283 .BI print( expr , ... )
 284 Print the values of the expressions.
 285 .TP
 286 .BI newproc( arguments )
 287 Start a new process with arguments given as a string
 288 and halt at the first instruction.
 289 .TP
 290 .B new()
 291 Like
 292 .IR newproc (),
 293 but take arguments (except
 294 .BR argv[0] )
 295 from string variable
 296 .BR progargs .
 297 .TP
 298 .B win()
 299 Like
 300 .IR new (),
 301 but run the process in a separate window.
 302 .TP
 303 .BI start( pid )
 304 Start a stopped process.
 305 .TP
 306 .BI kill( pid )
 307 Kill the given process.
 308 .TP
 309 .BI setproc( pid )
 310 Make the given process current.
 311 .TP
 312 .BI rc( string )
 313 Escape to the shell,
 314 .IR rc (1),
 315 to execute the command string.
 316 .SS Libraries
 317 There are a number of
 318 .I acid
 319 `libraries' that provide higher-level debugging facilities.  Two notable
 320 examples are
 321 .I truss
 322 and
 323 .IR trump ,
 324 which use
 325 .I acid
 326 to trace system calls
 327 .RI ( truss )
 328 and memory allocation
 329 .RI ( trump ).
 330 Both require starting
 331 .I acid
 332 on the program, either by attaching to a running process or by
 333 executing
 334 .B new()
 335 on a binary (perhaps after setting
 336 .BR progargs ),
 337 stopping the process, and then running
 338 .B truss()
 339 or
 340 .B trump()
 341 to execute the program under the scaffolding.
 342 The output will be a trace of the system calls
 343 .RI ( truss )
 344 or memory allocation and free calls
 345 .RI ( trump )
 346 executed by the program.
 347 When finished tracing, stop the process and execute
 348 .B untruss()
 349 or
 350 .B untrump()
 351 followed by
 352 .B cont()
 353 to resume execution.
 354 .SH EXAMPLES
 355 Start to debug
 356 .BR /bin/ls ;
 357 set some breakpoints; run up to the first one:
 358 .IP
 359 .EX
 360 % acid /bin/ls
 361 /bin/ls: mips plan 9 executable
 362 /sys/lib/acid/port
 363 /sys/lib/acid/mips
 364 acid: new()
 365 70094: system call      _main   ADD     $-0x14,R29
 366 70094: breakpoint       main+0x4        MOVW    R31,0x0(R29)
 367 acid: pid
 368 70094
 369 acid: argv0 = **main:argv\es
 370 acid: whatis argv0
 371 integer variable format s
 372 acid: *argv0
 373 /bin/ls
 374 acid: bpset(ls)
 375 acid: cont()
 376 70094: breakpoint  ls   ADD     $-0x16c8,R29
 377 acid:
 378 .EE
 379 .PP
 380 Display elements of a linked list of structures:
 381 .IP
 382 .EX
 383 complex Str { 'D' 0 val; 'X' 4 next; };
 384 complex Str s;
 385 s = *headstr;
 386 while s != 0 do{
 387         print(s.val, "\en");
 388         s = s.next;
 389 }
 390 .EE
 391 .PP
 392 Note the use of the
 393 .B .
 394 operator instead of
 395 .BR -> .
 396 .PP
 397 Display an array of bytes declared in C as
 398 .BR "char array[]" .
 399 .IP
 400 .EX
 401 *(array\es)
 402 .EE
 403 .PP
 404 This example gives
 405 .B array
 406 string format, then prints the string beginning at the address (in
 407 .I acid
 408 notation)
 409 .BR *array .
 410 .PP
 411 Trace the system calls executed by
 412 .IR ls (1):
 413 .IP
 414 .EX
 415 % acid -l truss /bin/ls
 416 /bin/ls:386 plan 9 executable
 417
 418 /sys/lib/acid/port
 419 /sys/lib/acid/kernel
 420 /sys/lib/acid/truss
 421 /sys/lib/acid/386
 422 acid: progargs = "-l lib/profile"
 423 acid: new()
 424 acid: truss()
 425 open("#c/pid", 0)
 426         return value: 3
 427 pread(3, 0x7fffeeac, 20, -1)
 428         return value: 12
 429         data: "        166 "
 430 \&...
 431 stat("lib/profile", 0x0000f8cc, 113)
 432         return value: 65
 433 open("/env/timezone", 0)
 434         return value: 3
 435 pread(3, 0x7fffd7c4, 1680, -1)
 436         return value: 1518
 437         data: "EST -18000 EDT -14400
 438    9943200   25664400   41392800   57718800   73447200   89168400
 439  104896800  ..."
 440 close(3)
 441         return value: 0
 442 pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
 443 ", 54, -1)
 444 --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
 445         return value: 54
 446 \&...
 447 166: breakpoint _exits+0x5      INTB    $0x40
 448 acid: cont()
 449 .EE
 450 .SH FILES
 451 .B /proc/*/text
 452 .br
 453 .B /proc/*/mem
 454 .br
 455 .B /proc/*/ctl
 456 .br
 457 .B /proc/*/note
 458 .br
 459 .B /sys/lib/acid/$objtype
 460 .br
 461 .B /sys/lib/acid/port
 462 .br
 463 .B /sys/lib/acid/kernel
 464 .br
 465 .B /sys/lib/acid/trump
 466 .br
 467 .B /sys/lib/acid/truss
 468 .br
 469 .B $home/lib/acid
 470 .SH SOURCE
 471 .B /sys/src/cmd/acid
 472 .SH "SEE ALSO"
 473 .IR 2a (1),
 474 .IR 2c (1),
 475 .IR 2l (1),
 476 .IR mk (1),
 477 .IR db (1)
 478 .br
 479 Phil Winterbottom,
 480 ``Acid Manual''.
 481 .SH DIAGNOSTICS
 482 At termination, kill commands are proposed
 483 for processes that are still active.
 484 .SH BUGS
 485 There is no way to redirect the standard input and standard output
 486 of a new process.
 487 .br
 488 Source line selection near the beginning of a file may pick
 489 an adjacent file.
 490 .br
 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.