From a01e58366c54804f15f84d6e21d13f2e4080977a Mon Sep 17 00:00:00 2001 From: rsc Date: Wed, 21 Apr 2004 22:06:17 +0000 Subject: how did i miss this? --- man/man1/acid.1 | 532 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 man/man1/acid.1 (limited to 'man') diff --git a/man/man1/acid.1 b/man/man1/acid.1 new file mode 100644 index 00000000..2d1523af --- /dev/null +++ b/man/man1/acid.1 @@ -0,0 +1,532 @@ +.TH ACID 1 +.SH NAME +acid, acidtypes \- debugger +.SH SYNOPSIS +.B acid +[ +.BI -l " libfile +] +[ +.B -wq +] [ +.B -m +.I machine +] [ +.I pid +| +.I core +] +[ +.I textfile +] +.PP +.B acidtypes +[ +.B -p +.I prefix +] +.I file +... +.\" .PP +.\" .B acid +.\" .B -l +.\" .B truss +.\" .I textfile +.\" .PP +.\" .B acid +.\" .B -l +.\" .B trump +.\" [ +.\" .I pid +.\" ] +.\" [ +.\" .I textfile +.\" ] +.SH DESCRIPTION +.I Acid +is a programmable symbolic debugger. +It can inspect one or more processes that share an address space. +A program to be debugged may be specified by the process id of +a running or defunct process, +or by the name of the program's text file +.RB ( 8.out +by default). +At the prompt, +.I acid +will store function definitions or print the value of expressions. +Options are +.TP .9i +.B -w +Allow the textfile to be modified. +.TP +.B -q +Print variable renamings at startup. +.TP +.BI -l " library +Load from +.I library +at startup; see below. +.TP +.BI -m " machine +Assume instructions are for the given CPU type +(one of +.BR 3210 , +.BR 386 , +etc., as listed in +.IR 2c (1), +or +.B sunsparc +or +.B mipsco +for the manufacturer-defined instruction notation for those processors) +instead of using the magic number to select +the CPU type. +.TP +.BI -k +Debug the kernel state for the process, rather than the user state. +.PP +At startup, +.I acid +obtains standard function definitions from the library file +.BR /usr/local/plan9/acid/port , +architecture-dependent functions from +.BR /usr/local/plan9/acid/$objtype , +user-specified functions from +.BR $home/lib/acid , +and further functions from +.B -l +files. +Definitions in any file may override previously defined functions. +If the function +.IR acidinit () +is defined, it will be invoked after all modules have been loaded. +See +.IR 2c (1) +for information about creating +.I acid +functions for examining data structures. +.SS Language +Symbols of the program being debugged become integer +variables whose values are addresses. +Contents of addresses are obtained by indirection. +Local variables are qualified by +function name, for example +.BR main:argv . +When program symbols conflict with +.I acid +words, distinguishing +.B $ +signs are prefixed. +Such renamings are reported at startup; option +.B -q +suppresses them. +.PP +Variable types +.RI ( "integer, float, list, string" ) +and formats are inferred from assignments. +Truth values false/true are attributed to zero/nonzero +integers or floats and to empty/nonempty lists or strings. +Lists are sequences of expressions surrounded by +.BR {\^} +and separated by commas. +.PP +Expressions are much as in C, +but yield both a value and a format. +Casts to complex types are allowed. +Lists admit the following operators, with +subscripts counted from 0. +.IP +.BI head " list +.br +.BI tail " list +.br +.BI append " list", " element +.br +.BI delete " list", " subscript +.PP +Format codes are the same as in +.IR db (1). +Formats may be attached to (unary) expressions with +.BR \e , +e.g. +.BR (32*7)\eD . +There are two indirection operators, +.B * +to address a core image, +.B @ +to address a text file. +The type and format of the result are determined by the format of the operand, +whose type must be integer. +.PP +Statements are +.IP +.BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR] +.br +.BI while " expr " do " statement +.br +.BI loop " expr" , " expr " do " statement +.br +.BI defn " name" ( args ") {" " statement \fP} +.br +.BI defn " name" +.br +.IB name ( args ) +.br +.BI builtin " name" ( args ) +.br +.BI local " name +.br +.BI return " expr +.br +.BR whatis " [ \fI name \fP] +.PP +The statement +.B defn +.I name +clears the definition for +.IR name . +A +.B defn +may override a built-in function; +prefixing a function call with +.B builtin +ignores any overriding +.BR defn , +forcing the use of the built-in function. +.PP +Here is a partial list of functions; see the manual for a complete list. +.TF asm(address) +.TP +.B stk() +Print a stack trace for current process. +.TP +.B lstk() +Print a stack trace with values of local variables. +.TP +.B gpr() +Print general registers. +Registers can also be accessed by name, for example +.BR *R0 . +.TP +.B spr() +Print special registers such as program counter and stack pointer. +.TP +.B fpr() +Print floating-point registers. +.TP +.B regs() +Same as +.BR spr();gpr() . +.TP +.BI fmt( expr , format ) +Expression +.I expr +with format given by the character value of expression +.IR format . +.TP +.BI src( address ) +Print 10 lines of source around the program address. +.TP +.BI Bsrc( address ) +Get the source line for the program address +into a window of a running +.IR sam (1) +and select it. +.TP +.BI line( address ) +Print source line nearest to the program address. +.TP +.B source() +List current source directories. +.TP +.BI addsrcdir( string ) +Add a source directory to the list. +.TP +.BI filepc( where ) +Convert a string of the form +.IB sourcefile : linenumber +to a machine address. +.TP +.BI pcfile( address ) +Convert a machine address to a source file name. +.TP +.BI pcline( address ) +Convert a machine address to a source line number. +.TP +.BI bptab() +List breakpoints set in the current process. +.TP +.BI bpset( address ) +Set a breakpoint in the current process at the given address. +(Doesn't work on Unix yet.) +.TP +.BI bpdel( address ) +Delete a breakpoint from the current process. +.TP +.B cont() +Continue execution of current process and wait for it to stop. +.TP +.B step() +Execute a single machine instruction in the current process. +(Doesn't work on Unix yet.) +.TP +.B func() +Step repeatedly until after a function return. +.TP +.BI stopped( pid ) +This replaceable function is called automatically when the given process +stops. +It normally prints the program counter and returns to the prompt. +.TP +.BI asm( address ) +Disassemble 30 machine instructions beginning at the given address. +.TP +.BI mem( address , string ) +Print a block of memory +interpreted according to a string of format codes. +.TP +.BI dump( address , n , string\fP) +Like +.BR mem (), +repeated for +.I n +consecutive blocks. +.TP +.BI print( expr , ... ) +Print the values of the expressions. +.TP +.BI newproc( arguments ) +Start a new process with arguments given as a string +and halt at the first instruction. +.TP +.B new() +Like +.IR newproc (), +but take arguments (except +.BR argv[0] ) +from string variable +.BR progargs . +.TP +.B win() +Like +.IR new (), +but run the process in a separate window. +.TP +.BI start( pid ) +Start a stopped process. +.TP +.BI kill( pid ) +Kill the given process. +.TP +.BI setproc( pid ) +Make the given process current. +.TP +.BI rc( string ) +Escape to the shell, +.IR rc (1), +to execute the command string. +.TP +.BI include( string ) +Read acid commands from the named file. +.TP +.BI includepipe( string ) +Run the command string, reading its standard output as acid commands. +.PD 0 +.SS "Shared library segments +When a pid or core file is specified on the command line, +.I acid +will, as part of its startup, determine the set of shared libraries +in use by the process image and map those at appropriate locations. +If +.I acid +is started without a pid or core file +and is subsequently attached to a process via +.BR setproc , +the shared library maps can be initialized by calling +.BR dynamicmap() . +.SS "Type information +Unix compilers conventionally include detailed type information +in the debugging symbol section of binaries. +The external program +.B acidtypes +extracts this information and formats it as +.I acid +program text. +Once the shared libraries have been mapped, the default +.I acid +startup invokes +.B acidtypes +(via +.BR includepipe ) +on the set of currently mapped text files. +The function +.B acidtypes() +can be called to rerun the command after changing +the set of mapped text files. +.SS "Acid Libraries +There are a number of +.I acid +`libraries' that provide higher-level debugging facilities. One notable +example is +.IR trump , +which uses +.I acid +to trace memory allocation. +.I Trump +requires starting +.I acid +on the program, either by attaching to a running process or by +executing +.B new() +on a binary (perhaps after setting +.BR progargs ), +stopping the process, and then running +.B trump() +to execute the program under the scaffolding. +The output will be a trace of the memory allocation and free calls +executed by the program. +When finished tracing, stop the process and execute +.B untrump() +followed by +.B cont() +to resume execution. +.SH EXAMPLES +Start to debug +.BR /bin/ls ; +set some breakpoints; run up to the first one +(this example doesn't work on Unix yet): +.IP +.EX +% acid /bin/ls +/bin/ls: mips plan 9 executable +/sys/lib/acid/port +/sys/lib/acid/mips +acid: new() +70094: system call _main ADD $-0x14,R29 +70094: breakpoint main+0x4 MOVW R31,0x0(R29) +acid: pid +70094 +acid: argv0 = **main:argv\es +acid: whatis argv0 +integer variable format s +acid: *argv0 +/bin/ls +acid: bpset(ls) +acid: cont() +70094: breakpoint ls ADD $-0x16c8,R29 +acid: +.EE +.PP +Display elements of a linked list of structures: +.IP +.EX +complex Str { 'D' 0 val; 'X' 4 next; }; +s = *headstr; +while s != 0 do{ + complex Str s; + print(s.val, "\en"); + s = s.next; +} +.EE +.PP +Note the use of the +.B . +operator instead of +.BR -> . +.PP +Display an array of bytes declared in C as +.BR "char array[]" . +.IP +.EX +*(array\es) +.EE +.PP +This example gives +.B array +string format, then prints the string beginning at the address (in +.I acid +notation) +.BR *array . +.PP +Trace the system calls executed by +.IR ls (1) +(neither does this one): +.IP +.EX +% acid -l truss /bin/ls +/bin/ls:386 plan 9 executable + +/sys/lib/acid/port +/sys/lib/acid/kernel +/sys/lib/acid/truss +/sys/lib/acid/386 +acid: progargs = "-l lib/profile" +acid: new() +acid: truss() +open("#c/pid", 0) + return value: 3 +pread(3, 0x7fffeeac, 20, -1) + return value: 12 + data: " 166 " +\&... +stat("lib/profile", 0x0000f8cc, 113) + return value: 65 +open("/env/timezone", 0) + return value: 3 +pread(3, 0x7fffd7c4, 1680, -1) + return value: 1518 + data: "EST -18000 EDT -14400 + 9943200 25664400 41392800 57718800 73447200 89168400 + 104896800 ..." +close(3) + return value: 0 +pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile +", 54, -1) +--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile + return value: 54 +\&... +166: breakpoint _exits+0x5 INTB $0x40 +acid: cont() +.EE +.SH FILES +.B /usr/local/plan9/acid/$objtype +.br +.B /usr/local/plan9/acid/port +.br +.B /usr/local/plan9/acid/kernel +.br +.B /usr/local/plan9/acid/trump +.br +.B /usr/local/plan9/acid/truss +.br +.B $home/lib/acid +.SH SOURCE +.B /usr/local/plan9/src/cmd/acid +.SH "SEE ALSO" +.IR mk (1), +.IR db (1) +.br +Phil Winterbottom, +``Acid Manual''. +.SH DIAGNOSTICS +At termination, kill commands are proposed +for processes that are still active. +.SH BUGS +There is no way to redirect the standard input and standard output +of a new process. +.br +Source line selection near the beginning of a file may pick +an adjacent file. +.br +With the extant stepping commands, one cannot step through instructions +outside the text segment and it is hard to debug across process forks. +.br +Breakpoints do not work yet. +Therefore, commands such as +.BR step , +.BR new , +and +.B truss +do not work either. +.B New +in particular will need some help to cope with dynamic libraries. -- cgit v1.2.3