diff options
Diffstat (limited to 'man/man1/acid.html')
| -rw-r--r-- | man/man1/acid.html | 486 |
1 files changed, 0 insertions, 486 deletions
diff --git a/man/man1/acid.html b/man/man1/acid.html deleted file mode 100644 index f04c9baa..00000000 --- a/man/man1/acid.html +++ /dev/null @@ -1,486 +0,0 @@ -<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> |