diff options
Diffstat (limited to 'man/man1/acid.html')
-rw-r--r-- | man/man1/acid.html | 486 |
1 files changed, 486 insertions, 0 deletions
diff --git a/man/man1/acid.html b/man/man1/acid.html new file mode 100644 index 00000000..f04c9baa --- /dev/null +++ b/man/man1/acid.html @@ -0,0 +1,486 @@ +<head> +<title>acid(1) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>ACID(1)</b><td align=right><b>ACID(1)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + acid, acidtypes – debugger<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>acid</font></tt> [ <tt><font size=+1>−l</font></tt> <i>library</i> ] [ <tt><font size=+1>−wq</font></tt> ] [ <tt><font size=+1>−m</font></tt> <i>machine</i> ] [ <i>pid</i> | <i>core</i> ] [ <i>textfile</i> + ] + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>acidtypes</font></tt> [ <tt><font size=+1>−p</font></tt> <i>prefix</i> ] <i>file</i> ...<br> + +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Acid</i> 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 (<tt><font size=+1>a.out</font></tt> by default). + At the prompt, <i>acid</i> will store function definitions + or print the value of expressions. Options are<br> + <tt><font size=+1>−w</font></tt> Allow the textfile to be modified.<br> + <tt><font size=+1>−q</font></tt> Print variable renamings at startup.<br> + <tt><font size=+1>−l</font></tt> <i>library</i> Load from <i>library</i> at startup; see below.<br> + <tt><font size=+1>−m</font></tt> <i>machine</i> Assume instructions are for the given CPU type (see + <a href="../man3/mach.html"><i>mach</i>(3)</a>) instead of using the executable header to select the + CPU type.<br> + <tt><font size=+1>−k</font></tt> Debug the kernel state for the process, rather than the user + state. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + At startup, <i>acid</i> obtains standard function definitions from the + library file <tt><font size=+1>/usr/local/plan9/acid/port</font></tt>, architecture-dependent + functions from <tt><font size=+1>/usr/local/plan9/acid/$objtype</font></tt>, user-specified + functions from <tt><font size=+1>$home/lib/acid</font></tt>, and further functions from <tt><font size=+1>−l</font></tt> files. + Definitions in any file may + override previously defined functions. If the function <i>acidinit</i>() + is defined, it will be invoked after all modules have been loaded. + Then the function <i>acidmap</i>() will be invoked if defined. <tt><font size=+1>/usr/local/plan9/acid/port</font></tt> + provides a definition of <i>acidmap</i> that attaches all the shared + libraries being used by the target + process and then runs <i>acidtypes</i> (<i>q.v.</i>) to create <i>acid</i> functions + for examining data structures.<br> + <p><font size=+1><b>Language </b></font><br> + 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 <tt><font size=+1>main:argv</font></tt>. When program symbols conflict with <i>acid</i> + words, distinguishing <tt><font size=+1>$</font></tt> signs are prefixed. Such + renamings are reported at startup; option <tt><font size=+1>−q</font></tt> suppresses them. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Variable types (<i>integer, float, list, string</i>) 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 <tt><font size=+1>{}</font></tt> + and separated by commas. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + 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.<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>head</font></tt> <i>list<br> + </i><tt><font size=+1>tail</font></tt> <i>list<br> + </i><tt><font size=+1>append</font></tt> <i>list</i><tt><font size=+1>,</font></tt> <i>element<br> + </i><tt><font size=+1>delete</font></tt> <i>list</i><tt><font size=+1>,</font></tt> <i>subscript + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + + </table> + Format codes are the same as in <a href="../man1/db.html"><i>db</i>(1)</a>. Formats may be attached + to (unary) expressions with <tt><font size=+1>\</font></tt>, e.g. <tt><font size=+1>(32*7)\D</font></tt>. There are two indirection + operators, <tt><font size=+1>*</font></tt> to address a core image, <tt><font size=+1>@</font></tt> 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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Statements are<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>if</font></tt> <i>expr</i> <tt><font size=+1>then</font></tt> <i>statement</i> [ <tt><font size=+1>else</font></tt> <i>statement</i> ]<br> + <tt><font size=+1>while</font></tt> <i>expr</i> <tt><font size=+1>do</font></tt> <i>statement<br> + </i><tt><font size=+1>loop</font></tt> <i>expr</i><tt><font size=+1>,</font></tt> <i>expr</i> <tt><font size=+1>do</font></tt> <i>statement<br> + </i><tt><font size=+1>defn</font></tt> <i>name</i><tt><font size=+1>(</font></tt><i>args</i><tt><font size=+1>) {</font></tt> <i>statement</i> <tt><font size=+1>}<br> + defn</font></tt> <i>name<br> + name</i><tt><font size=+1>(</font></tt><i>args</i><tt><font size=+1>)<br> + builtin</font></tt> <i>name</i><tt><font size=+1>(</font></tt><i>args</i><tt><font size=+1>)<br> + local</font></tt> <i>name<br> + </i><tt><font size=+1>return</font></tt> <i>expr<br> + </i><tt><font size=+1>whatis</font></tt> [ <i>name</i> ] + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + + </table> + The statement <tt><font size=+1>defn</font></tt> <i>name</i> clears the definition for <i>name</i>. A <tt><font size=+1>defn</font></tt> + may override a built-in function; prefixing a function call with + <tt><font size=+1>builtin</font></tt> ignores any overriding <tt><font size=+1>defn</font></tt>, forcing the use of the built-in + function. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Here is a partial list of functions; see the manual for a complete + list.<br> + <tt><font size=+1>stk()</font></tt> Print a stack trace for current process.<br> + <tt><font size=+1>lstk()</font></tt> Print a stack trace with values of local variables.<br> + <tt><font size=+1>gpr()</font></tt> Print general registers. Registers can also be accessed by + name, for example <tt><font size=+1>*R0</font></tt>.<br> + <tt><font size=+1>spr()</font></tt> Print special registers such as program counter and stack + pointer.<br> + <tt><font size=+1>fpr()</font></tt> Print floating-point registers.<br> + <tt><font size=+1>regs()</font></tt> Same as <tt><font size=+1>spr();gpr()</font></tt>.<br> + <tt><font size=+1>fmt(</font></tt><i>expr</i><tt><font size=+1>,</font></tt><i>format</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Expression <i>expr</i> with format given by the character value of expression + <i>format</i>.<br> + + </table> + + </table> + <tt><font size=+1>src(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Print 10 lines of source around the program address.<br> + <tt><font size=+1>Bsrc(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Get the source line for the program address into + a window of a running <a href="../man1/sam.html"><i>sam</i>(1)</a> and select it.<br> + <tt><font size=+1>line(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Print source line nearest to the program address.<br> + <tt><font size=+1>source()</font></tt> List current source directories.<br> + <tt><font size=+1>addsrcdir(</font></tt><i>string</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Add a source directory to the list.<br> + + </table> + + </table> + <tt><font size=+1>filepc(</font></tt><i>where</i><tt><font size=+1>)</font></tt> Convert a string of the form <i>sourcefile</i><tt><font size=+1>:</font></tt><i>linenumber</i> + to a machine address.<br> + <tt><font size=+1>pcfile(</font></tt><i>address</i><tt><font size=+1>)</font></tt>Convert a machine address to a source file name.<br> + <tt><font size=+1>pcline(</font></tt><i>address</i><tt><font size=+1>)</font></tt>Convert a machine address to a source line number.<br> + <tt><font size=+1>bptab()</font></tt> List breakpoints set in the current process.<br> + <tt><font size=+1>bpset(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Set a breakpoint in the current process at the given + address. (Doesn’t work on Unix yet.)<br> + <tt><font size=+1>bpdel(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Delete a breakpoint from the current process.<br> + <tt><font size=+1>cont()</font></tt> Continue execution of current process and wait for it to + stop.<br> + <tt><font size=+1>step()</font></tt> Execute a single machine instruction in the current process. + (Doesn’t work on Unix yet.)<br> + <tt><font size=+1>func()</font></tt> Step repeatedly until after a function return.<br> + <tt><font size=+1>stopped(</font></tt><i>pid</i><tt><font size=+1>)</font></tt> This replaceable function is called automatically + when the given process stops. It normally prints the program counter + and returns to the prompt.<br> + <tt><font size=+1>asm(</font></tt><i>address</i><tt><font size=+1>)</font></tt> Disassemble 30 machine instructions beginning at the + given address.<br> + <tt><font size=+1>mem(</font></tt><i>address</i><tt><font size=+1>,</font></tt><i>string</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Print a block of memory interpreted according to a string of format + codes.<br> + + </table> + + </table> + <tt><font size=+1>dump(</font></tt><i>address</i><tt><font size=+1>,</font></tt><i>n</i><tt><font size=+1>,</font></tt><i>string</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Like <tt><font size=+1>mem</font></tt>(), repeated for <i>n</i> consecutive blocks.<br> + + </table> + + </table> + <tt><font size=+1>print(</font></tt><i>expr</i><tt><font size=+1>,</font></tt><i>...</i><tt><font size=+1>)</font></tt> Print the values of the expressions.<br> + <tt><font size=+1>newproc(</font></tt><i>arguments</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Start a new process with arguments given as a string and halt + at the first instruction.<br> + + </table> + + </table> + <tt><font size=+1>new()</font></tt> Like <i>newproc</i>(), but take arguments (except <tt><font size=+1>argv[0]</font></tt>) from + string variable <tt><font size=+1>progargs</font></tt>.<br> + <tt><font size=+1>win()</font></tt> Like <i>new</i>(), but run the process in a separate window.<br> + <tt><font size=+1>start(</font></tt><i>pid</i><tt><font size=+1>)</font></tt> Start a stopped process.<br> + <tt><font size=+1>kill(</font></tt><i>pid</i><tt><font size=+1>)</font></tt> Kill the given process.<br> + <tt><font size=+1>setproc(</font></tt><i>pid</i><tt><font size=+1>)</font></tt> Make the given process current.<br> + <tt><font size=+1>rc(</font></tt><i>string</i><tt><font size=+1>)</font></tt> Escape to the shell, <a href="../man1/rc.html"><i>rc</i>(1)</a>, to execute the command string.<br> + <tt><font size=+1>include(</font></tt><i>string</i><tt><font size=+1>)</font></tt>Read acid commands from the named file.<br> + <tt><font size=+1>includepipe(</font></tt><i>string</i><tt><font size=+1>)<br> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Run the command string, reading its standard output as acid commands.<br> + + </table> + + </table> + <p><font size=+1><b>Shared library segments </b></font><br> + When a pid or core file is specified on the command line, <i>acid</i> + 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</i> is started without a pid or core file and is subsequently + attached to a process via <tt><font size=+1>setproc</font></tt>, the shared library maps + can be initialized by calling <tt><font size=+1>dynamicmap()</font></tt>.<br> + <p><font size=+1><b>Type information </b></font><br> + Unix compilers conventionally include detailed type information + in the debugging symbol section of binaries. The external program + <tt><font size=+1>acidtypes</font></tt> extracts this information and formats it as <i>acid</i> program + text. Once the shared libraries have been mapped, the default + <i>acid</i> startup invokes <tt><font size=+1>acidtypes</font></tt> (via + <tt><font size=+1>includepipe</font></tt>) on the set of currently mapped text files. The function + <tt><font size=+1>acidtypes()</font></tt> can be called to rerun the command after changing + the set of mapped text files.<br> + <p><font size=+1><b>Acid Libraries </b></font><br> + There are a number of <i>acid</i> ‘libraries’ that provide higher-level + debugging facilities. One notable example is <i>trump</i>, which uses + <i>acid</i> to trace memory allocation. <i>Trump</i> requires starting <i>acid</i> + on the program, either by attaching to a running process or by + executing <tt><font size=+1>new()</font></tt> on a binary (perhaps after setting <tt><font size=+1>progargs</font></tt>), + stopping the process, and then running <tt><font size=+1>trump()</font></tt> 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 <tt><font size=+1>untrump()</font></tt> followed + by <tt><font size=+1>cont()</font></tt> to resume execution. + +</table> +<p><font size=+1><b>EXAMPLES </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Start to debug <tt><font size=+1>/bin/ls</font></tt>; set some breakpoints; run up to the first + one (this example doesn’t work on Unix yet):<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>% acid /bin/ls<br> + /bin/ls: mips plan 9 executable<br> + /sys/lib/acid/port<br> + /sys/lib/acid/mips<br> + acid: new()<br> + 70094: system call _main ADD $−0x14,R29<br> + 70094: breakpoint main+0x4 MOVW R31,0x0(R29)<br> + acid: pid<br> + 70094<br> + acid: argv0 = **main:argv\s<br> + acid: whatis argv0<br> + integer variable format s<br> + acid: *argv0<br> + /bin/ls<br> + acid: bpset(ls)<br> + acid: cont()<br> + 70094: breakpoint ls ADD $−0x16c8,R29<br> + acid: <br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Display elements of a linked list of structures:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>complex Str { 'D' 0 val; 'X' 4 next; };<br> + s = *headstr;<br> + while s != 0 do{<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + complex Str s;<br> + print(s.val, "\n");<br> + s = s.next;<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Note the use of the <tt><font size=+1>.</font></tt> operator instead of <tt><font size=+1>−></font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Display an array of bytes declared in C as <tt><font size=+1>char array[]</font></tt>.<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>*(array\s)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + This example gives <tt><font size=+1>array</font></tt> string format, then prints the string + beginning at the address (in <i>acid</i> notation) <tt><font size=+1>*array</font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Trace the system calls executed by <a href="../man1/ls.html"><i>ls</i>(1)</a> (neither does this one):<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>% acid −l truss /bin/ls<br> + /bin/ls:386 plan 9 executable<br> + /sys/lib/acid/port<br> + /sys/lib/acid/kernel<br> + /sys/lib/acid/truss<br> + /sys/lib/acid/386<br> + acid: progargs = "−l lib/profile"<br> + acid: new()<br> + acid: truss()<br> + open("#c/pid", 0)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 3<br> + + </table> + pread(3, 0x7fffeeac, 20, −1)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 12<br> + data: " 166 "<br> + + </table> + ...<br> + stat("lib/profile", 0x0000f8cc, 113)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 65<br> + + </table> + open("/env/timezone", 0)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 3<br> + + </table> + pread(3, 0x7fffd7c4, 1680, −1)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 1518<br> + data: "EST −18000 EDT −14400<br> + 9943200 25664400 41392800 57718800 73447200 89168400<br> + 104896800 ..."<br> + + </table> + close(3)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 0<br> + + </table> + pwrite(1, "−−rw−rw−r−− M 9 rob rob 2519 Mar 22 10:29 lib/profile<br> + ", 54, −1)<br> + −−rw−rw−r−− M 9 rob rob 2519 Mar 22 10:29 lib/profile<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + return value: 54<br> + + </table> + ...<br> + 166: breakpoint _exits+0x5 INTB $0x40<br> + acid: cont()<br> + </font></tt> + </table> + +</table> +<p><font size=+1><b>FILES </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/acid/$objtype<br> + /usr/local/plan9/acid/port<br> + /usr/local/plan9/acid/kernel<br> + /usr/local/plan9/acid/trump<br> + /usr/local/plan9/acid/truss<br> + $home/lib/acid<br> + </font></tt> +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/cmd/acid<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man1/mk.html"><i>mk</i>(1)</a>, <a href="../man1/db.html"><i>db</i>(1)</a><br> + Phil Winterbottom, “Acid Manual”.<br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + At termination, kill commands are proposed for processes that + are still active.<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + There is no way to redirect the standard input and standard output + of a new process. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Source line selection near the beginning of a file may pick an + adjacent file. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + With the extant stepping commands, one cannot step through instructions + outside the text segment and it is hard to debug across process + forks. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Breakpoints do not work yet. Therefore, commands such as <tt><font size=+1>step</font></tt>, + <tt><font size=+1>new</font></tt>, and <tt><font size=+1>truss</font></tt> do not work either. <tt><font size=+1>New</font></tt> in particular will need + some help to cope with dynamic libraries.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |