diff options
Diffstat (limited to 'static/v10/man9/pi.9')
| -rw-r--r-- | static/v10/man9/pi.9 | 397 |
1 files changed, 0 insertions, 397 deletions
diff --git a/static/v10/man9/pi.9 b/static/v10/man9/pi.9 deleted file mode 100644 index f67d3868..00000000 --- a/static/v10/man9/pi.9 +++ /dev/null @@ -1,397 +0,0 @@ -.TH PI 9.1 -.CT 1 debug_tune -.SH NAME -pi, 3pi \- process inspector -.SH SYNOPSIS -.B pi -[ -.B -t -.I corefile objectfile -] -.PP -.B 3pi -[ -.B -p -.I person -] -.SH DESCRIPTION -.I Pi -is a C debugger that -is bound dynamically to multiple subject processes or core dumps. -It works better for programs compiled -.I cc -.IR \-g . -.I Pi -uses the -.IR Pads (9.5) -multi-window user interface. -There are three types of windows: -debugger control windows, -which access the global state of the debugger; -process control windows (exactly one per process), -which start and stop processes and connect to process-specific functions; -and process inspection windows, -which include viewers for source text and memory, formatted various ways. -.PP -The most important debugger control window is the -.I pi -window itself. -Each line within the -.I pi -window refers to a specific process. -These lines may be introduced to the window by running -.IR ps (1) -from the button 3 menu; -by typing a file name, either a -.IR proc (4) -name, or the name of a core image followed by the name of the binary that created -the core; -or by typing a command, prefixed by an exclamation -.LR ! , -to be executed as a child of -.IR pi . -There are several ways to access a process (using the button 2 menu), -each of which generates a process control window: -.TF hang\ &\ take\ over -.TP -.B open process -Attach to a running process, often one started with -.IR hang (1). -.PD0 -.TP -.B open core -Attach to a core image. -.TP -.B open child -Attach to a process forked by a process being debugged by the current -.IR pi. -.TP -.B take over -Rebind an existing process window hierarchy (pointed to with the mouse) -to the named process, -which must be an instance of the identical program. -.TP -.B hang & open proc -Execute a command afresh, beginning it in the -stopped state, and redirecting IO to -.FR /dev/null . -.TP -.B hang & take over -Same, also binding to an existing process window. -.PD -.PP -The process window indicates the process's state, -shows the call stack traceback -and connects to windows that access source text, -local variables within a stack frame, -raw memory, and so on. -These windows are cross-connected, so, for example, -an instruction in a process's assembly language window can -be inspected in hexadecimal in the raw memory window. -Closing the process control window closes all the windows under it. -.PP -The following menu functions are provided by -the various window types in -.IR pi . -Initially there are these windows available: -.TP 0.5i -.B Help -Reminder of user interface mechanics. -.TP -.B Pi -Overall control of processes, core dumps and programs. -A process is identified by its pathname or command line. -Process symbols are found in the executable file from which the process was loaded, -but may be overridden. -Symbols for core dumps must be supplied explicitly, after the core filename. -\fBSynopsis\fP: -Identify and open process or core dump; -run a program as -.I Pi's -child; -take over a process with the debugging environment of a different one. -.TP -.B Pwd/cd -change the working directory of the debugger. -.SS Process Window -Selecting and opening a process from the Pi window creates a new -window with overall control of that process. -It shows the process state, and a traceback if the process is halted or dead. -States are: -.TF EVENT\ PENDING -.TP -.SM -.B ACTIVE -running normally -.TP -.SM -.B HALTED -halted asynchronously by a debugger -.TP -.SM -.B BREAKPOINT -halted on reaching breakpoint -.TP -.SM -.B STMT STEPPED -halted after executing C source statement(s) -.TP -.SM -.B INSTR STEPPED -halted after executing machine instruction(s) -.TP -.SM -.B EVENT PENDING -halted about to receive a signal being traced -.TP -.SM -.B ERROR STATE -the process has probably exited -.PD -.LP -The menu operations on the process are: -.TF EVENT\ PENDING -.TP -.B go -let the process run -.PD 0 -.TP -.B stop -stop the process -.TP -.B kill -send -.B SIGKILL -to the process; see -.IR signal (2) -.TP -.B src text -open source text window(s) -.TP -.B Signals -open window for sending and trapping signals -.TP -.B Globals -open window for evaluating expression in global scope -.TP -.B RawMemory -open window for editing uninterpreted memory -.TP -.B Assembler -open window for disassembler -.PD -.LP -Each line of the call stack traceback describes one function. -Each function in the traceback can open an expression evaluator window -or display its current source line. -.SS Globals and Stack Frame Windows -.PP -These windows evaluate expressions with respect to global scope, -and scope in a function, respectively. -A stack frame window is opened from a line in the call stack traceback or -from a line of source text. -A stack frame can find its active source line in a source window or the stack -frame window of its caller. -.LP -C expressions can be entered by the keyboard or mouse. -The unary operators -.I fabs -and -.I sizeof -are supported; the only assignment operator is -.LR = . -Functions from the user program may be called. -New expressions can be derived from old ones by the keyboard or mouse. -In menus and the keyboard, -.B $ -means the expression in the current line. -The VAX registers are called -.B $r0 -to -.BR $r15 ; -the address of a register is -the location at which it was saved. -The format in which values are displayed can be changed. -The raw memory editor may be entered using an expression's value as address. -.PP -An expression may be made a -.IR spy . -The value of a spy expression is evaluated and displayed -each time the debugger looks at the process. -If the value of a spy changes the process is halted -at the next instruction, statement or breakpoint. -.LP -The comma operator is useful in conditional breakpoints because the values -of its subexpressions are displayed. -E.g. x, y, x==y traces the values of x and y when the condition fails; -x, y, 0 just traces. -.LP -To cross scope boundaries, the environment (a function identifier) -in which an expression is to be evaluated may be specified as: -{ expr } function. -From the source directory window, file static variables can be promoted -to appear in the menu of global variables. -.SS Source Text Windows -The source file directory window lists all the source files, if there are -two or more. -A textual prefix, entered from the keyboard, points to a source directory, -without changing the working directory. -Each source file is in a separate window, opened when needed. -The source file's pathname as given to -.I cc -can be overridden from the keyboard. -If things go wrong, use -.B reopen -to open the file afresh. -\fBSynopsis\fP: -set/clear (conditional) breakpoint; -single-step source statements; -step into (rather than over) a function; -go the process; -show the statement for the current PC; -open a stack frame window for a source line's function; -evaluate expression; -disassemble first instruction of source statement; -context search for string. -.SS Breakpoints Window -Lists all the active source and assembler breakpoints and related errors. -\fBSynopsis\fP: -show source or assembler for a breakpoint; -clear breakpoint; -clear all breakpoints. -.SS Signals Window -Lists all signal types, showing which ones are traced. -\fBSynopsis\fP: -Change which signals are traced; -send a signal to the subject process; -clear pending signal; -stop process on -.I exec. -.SS Raw Memory Window -In this window -memory is a viewed as a sequence of 1-, 2-, 4- or 8-byte cells. -\fBSynopsis\fP: -set cell address; -change cell size; -change display format; -display cells above and below; -indirect to cell; -change cell value; -spy on memory cell; -disassemble instruction at cell. -.SS (Dis)assembler Window -In this window memory is viewed as a sequence of instructions. -\fBSynopsis\fP: -set instruction address; -display more instructions; -change display format; -display instruction as cell in raw memory window; -set/clear breakpoint on instruction; -open stack frame window for instruction's function; -display instruction at current PC; -single step instruction(s); -step over a function call instead of into the function. -.SS Exec and Fork -If a process controlled by -.I pi -does an -.IR exec () -and an exec break is set in the Signals window, -the process is suspended as if started by -.IR hang (1). -To debug the process after the -.IR exec , -close the original process window and re-open it. -When re-opened it will get the new symbol tables. -.PP -To debug a child process: (i) set a breakpoint in code that will be executed -in the child after the fork; (ii) execute the fork -.I at full speed -(the child inherits the parent's breakpoints, which aren't there if the -parent is stepped); -(iii) -.I before altering any breakpoints, -get a fresh -.I ps -in the Pi window and apply -.B open child -to the child. -The child should be stopped on the inherited breakpoint, but it and all other -breakpoints should have been cleared. -.SS Kernel -The state of kernel variables associated with a process may be examined -by giving their name or virtual address. -The -.B UNIX -environment variable specifies the file from which the system was -loaded; the default is -.IR /unix . -Kernel dumps may be examined by opening the -`kernel pi' window. -.SS Just A Traceback -With the -.B -t -option -.I pi -writes a traceback on its standard output and quits. -.SS 3pi -.I 3pi -is a variant of -.I pi -for debugging 5620 programs running under -.IR mux (9.1). -It creates two terminal processes: one for its access to terminal memory -and graphics and a second for its -.IR Pads (9.5) -interface. -.SS Remote Debugging -With the -.B -p -option -.I 3pi -loads its first process, but not -.IR Pads . -Instead, it mails a -.I 3pi -command to -.IR person , -to be executed on any host in the local network. -That -.I 3pi -command loads -.I Pads -on -.IR person 's -terminal, and connects to the originator's terminal. -If separate hosts are involved and the versions of critical files differ, -be careful with pathnames. -.SS 3pi Graphics -Points, rectangles, textures and bitmaps can be displayed graphically. -.SS 3pi - pi -Most differences come from obvious differences in the hardware and -software architectures. -Also, in -.I 3pi -function calls are executed by a debugger process on its own call stack. -.SH SEE ALSO -T. A. Cargill, -`The Feel of Pi', -this manual, Volume 2 -.br -.IR hang (1), -.IR proc (4), -.IR adb (1), -.IR cin (1), -.IR nm (1), -.IR pads (9.5) -.SH BUGS -In switch statements there is no boundary between the last case -and the branch code; the program -.I appears -to jump to the last case (but is really in the branch) -and then to the real case. -.br -A changed spy only stops the process at a breakpoint or while stepping. -An expression can be cast only by menu. -.br -Functions may only be called when the process is stopped and not in a system call. |