acid(1) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man1/acid.html | 486 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 486 insertions(+) create mode 100644 man/man1/acid.html (limited to 'man/man1/acid.html') 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 @@ + +acid(1) - Plan 9 from User Space + + + + +

ACID(1) ACID(1) +

+
+

NAME
+ +
+ + acid, acidtypes – debugger
+ +
+

SYNOPSIS
+ +
+ + acid [ −l library ] [ −wq ] [ −m machine ] [ pid | core ] [ textfile + ] +
+ + acidtypes [ −p prefix ] file ...
+ +
+

DESCRIPTION
+ +
+ + 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 (a.out by default). + At the prompt, acid will store function definitions + or print the value of expressions. Options are
+ −w         Allow the textfile to be modified.
+ −q         Print variable renamings at startup.
+ −l library    Load from library at startup; see below.
+ −m machine   Assume instructions are for the given CPU type (see + mach(3)) instead of using the executable header to select the + CPU type.
+ −k         Debug the kernel state for the process, rather than the user + state. +
+ + At startup, acid obtains standard function definitions from the + library file /usr/local/plan9/acid/port, architecture-dependent + functions from /usr/local/plan9/acid/$objtype, user-specified + functions from $home/lib/acid, and further functions from −l files. + Definitions in any file may + override previously defined functions. If the function acidinit() + is defined, it will be invoked after all modules have been loaded. + Then the function acidmap() will be invoked if defined. /usr/local/plan9/acid/port + provides a definition of acidmap that attaches all the shared + libraries being used by the target + process and then runs acidtypes (q.v.) to create acid functions + for examining data structures.
+
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 main:argv. When program symbols conflict with acid + words, distinguishing $ signs are prefixed. Such + renamings are reported at startup; option −q suppresses them. + +
+ + Variable types (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 {} + and separated by commas. +
+ + 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.
+ +
+ + head list
+ tail list
+ append list, element
+ delete list, subscript +
+ + +
+ Format codes are the same as in db(1). Formats may be attached + to (unary) expressions with \, e.g. (32*7)\D. There are two indirection + operators, * to address a core image, @ 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. +
+ + Statements are
+ +
+ + if expr then statement [ else statement ]
+ while expr do statement
+ loop expr, expr do statement
+ defn name(args) { statement } + defn name
+ name(args) + builtin name(args) + local name
+ return expr
+ whatis [ name ] +
+ + +
+ The statement defn name clears the definition for name. A defn + may override a built-in function; prefixing a function call with + builtin ignores any overriding defn, forcing the use of the built-in + function. +
+ + Here is a partial list of functions; see the manual for a complete + list.
+ stk()          Print a stack trace for current process.
+ lstk()         Print a stack trace with values of local variables.
+ gpr()          Print general registers. Registers can also be accessed by + name, for example *R0.
+ spr()          Print special registers such as program counter and stack + pointer.
+ fpr()          Print floating-point registers.
+ regs()         Same as spr();gpr().
+ fmt(expr,format) + +
+ + +
+ + Expression expr with format given by the character value of expression + format.
+ +
+ +
+ src(address)     Print 10 lines of source around the program address.
+ Bsrc(address)    Get the source line for the program address into + a window of a running sam(1) and select it.
+ line(address)    Print source line nearest to the program address.
+ source()       List current source directories.
+ addsrcdir(string) + +
+ + +
+ + Add a source directory to the list.
+ +
+ +
+ filepc(where)   Convert a string of the form sourcefile:linenumber + to a machine address.
+ pcfile(address)Convert a machine address to a source file name.
+ pcline(address)Convert a machine address to a source line number.
+ bptab()        List breakpoints set in the current process.
+ bpset(address)   Set a breakpoint in the current process at the given + address. (Doesn’t work on Unix yet.)
+ bpdel(address)   Delete a breakpoint from the current process.
+ cont()         Continue execution of current process and wait for it to + stop.
+ step()         Execute a single machine instruction in the current process. + (Doesn’t work on Unix yet.)
+ func()         Step repeatedly until after a function return.
+ stopped(pid)    This replaceable function is called automatically + when the given process stops. It normally prints the program counter + and returns to the prompt.
+ asm(address)     Disassemble 30 machine instructions beginning at the + given address.
+ mem(address,string) + +
+ + +
+ + Print a block of memory interpreted according to a string of format + codes.
+ +
+ +
+ dump(address,n,string) + +
+ + +
+ + Like mem(), repeated for n consecutive blocks.
+ +
+ +
+ print(expr,...)   Print the values of the expressions.
+ newproc(arguments) + +
+ + +
+ + Start a new process with arguments given as a string and halt + at the first instruction.
+ +
+ +
+ new()          Like newproc(), but take arguments (except argv[0]) from + string variable progargs.
+ win()          Like new(), but run the process in a separate window.
+ start(pid)      Start a stopped process.
+ kill(pid)       Kill the given process.
+ setproc(pid)    Make the given process current.
+ rc(string)       Escape to the shell, rc(1), to execute the command string.
+ include(string)Read acid commands from the named file.
+ includepipe(string) + +
+ + +
+ + Run the command string, reading its standard output as acid commands.
+ +
+ +
+
Shared library segments
+ When a pid or core file is specified on the command line, 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 acid is started without a pid or core file and is subsequently + attached to a process via setproc, the shared library maps + can be initialized by calling dynamicmap().
+
Type information
+ Unix compilers conventionally include detailed type information + in the debugging symbol section of binaries. The external program + acidtypes extracts this information and formats it as acid program + text. Once the shared libraries have been mapped, the default + acid startup invokes acidtypes (via + includepipe) on the set of currently mapped text files. The function + acidtypes() can be called to rerun the command after changing + the set of mapped text files.
+
Acid Libraries
+ There are a number of acid ‘libraries’ that provide higher-level + debugging facilities. One notable example is trump, which uses + acid to trace memory allocation. Trump requires starting acid + on the program, either by attaching to a running process or by + executing new() on a binary (perhaps after setting progargs), + stopping the process, and then running 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 untrump() followed + by cont() to resume execution. + +
+

EXAMPLES
+ +
+ + Start to debug /bin/ls; set some breakpoints; run up to the first + one (this example doesn’t work on Unix yet):
+ +
+ + % 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\s + acid: whatis argv0 + integer variable format s + acid: *argv0 + /bin/ls + acid: bpset(ls) + acid: cont() + 70094: breakpoint ls ADD $−0x16c8,R29 + acid: + + + + +
+ Display elements of a linked list of structures:
+ +
+ + complex Str { 'D' 0 val; 'X' 4 next; }; + s = *headstr; + while s != 0 do{ + + + + complex Str s; + print(s.val, "\n"); + s = s.next; + + + } + + + + +
+ Note the use of the . operator instead of −>. +
+ + Display an array of bytes declared in C as char array[].
+ +
+ + *(array\s) + + + + +
+ This example gives array string format, then prints the string + beginning at the address (in acid notation) *array. +
+ + Trace the system calls executed by ls(1) (neither does this one):
+ +
+ + % 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() + +
+ +
+

FILES
+ +
+ + /usr/local/plan9/acid/$objtype + /usr/local/plan9/acid/port + /usr/local/plan9/acid/kernel + /usr/local/plan9/acid/trump + /usr/local/plan9/acid/truss + $home/lib/acid + +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/acid + +
+

SEE ALSO
+ +
+ + mk(1), db(1)
+ Phil Winterbottom, “Acid Manual”.
+ +
+

DIAGNOSTICS
+ +
+ + At termination, kill commands are proposed for processes that + are still active.
+ +
+

BUGS
+ +
+ + There is no way to redirect the standard input and standard output + of a new process. +
+ + Source line selection near the beginning of a file may pick an + adjacent file. +
+ + With the extant stepping commands, one cannot step through instructions + outside the text segment and it is hard to debug across process + forks. +
+ + Breakpoints do not work yet. Therefore, commands such as step, + new, and truss do not work either. New in particular will need + some help to cope with dynamic libraries.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3