V9/jtools/man/man1/pi.1

Compare this file to the similar file:
Show the results in this format: 

.TH PI 1
.CT 1 debug_tune
.SH NAME
pi, rtpi \- process inspector
.SH SYNOPSIS
.B pi
[
.B -t
.I corefile objectfile
]
.PP
.B rtpi
.I internetid
.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 (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
process id number followed by the name of the binary which is executing,
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:
.B
open process
.RB ( open\ core dump )
attaches to a running process (core image);
.B
open child
attaches to a process forked by a process being debugged by the current
.IR pi ;
and
.B
take over
rebinds an existing process window hierarchy (pointed to with the mouse)
to the named process,
which must be an instance of the same program.
A command may be instantiated afresh
.RB ( hang\ &\ open\ proc )
or restarted and bound to an existing process window
.RB ( hang\ &\ take\ over );
in either case, IO is redirected to
.IR /dev/null .
.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.
.B Synopsis:
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:
.TP 1.5i
.PD 0
.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:
.PD 0
.TP 1i
.B go
let the process run
.TP
.B stop
stop the process
.TP
.B kill
send signal SIGKILL to the process
.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.
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.
.LP
New C expressions can be derived from old ones by the keyboard or mouse.
In menus and the keyboard, $ means the expression in the current line.
The VAX registers are called $r0 to $r15; 68000 registers are called
$a0 to $a7, $d0 - $d7; 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.
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.
A stack frame can find its active source line in a source window or the stack
frame window of its caller.
.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.
.B Synopsis:
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.
.B Synopsis:
show source or assembler for a breakpoint;
clear breakpoint;
clear all breakpoints.
.SS Signals Window
Lists all signal types, showing which ones are traced.
.B Synopsis:
Change which signals are traced;
send a signal to the subject process;
clear pending signal;
stop process on
.I exec.
.SS Raw Memory Window
A ``memory editor'' in which
memory is a viewed as a sequence of 1-, 2-, 4- or 8-byte cells.
.B Synopsis:
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
Disassembler in which memory is viewed as a sequence of instructions.
.B Synopsis:
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
executes an
.IR exec (),
it is suspended as if started by
.IR hang (1),
if an
.IR exec ()
break is set in the Signals window.
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
.I 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 /vmunix .
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 Terminal Process Loading
.I Pi
looks at the environment variable
.I TERM
to determine where to load
.IR pads (5)
from.
If it is set to \fIxterm\fR or \fIsun\fR it will look for
an executable called
.I pads
in the current environment variable
.IR PATH .
Otherwise it assumes it is being used with an AT&T 5620 terminal.
.SS rtpi
.I Rtpi
is a variant of
.I pi
for remote debugging of real-time processes on 680X0 boards connected
via Ethernet.
.I Internetid
is the internet name of the board.
.SH SEE ALSO
.PP
.IR hang (1), 
.IR strip (1), 
.IR pads (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.
A changed spy only stops the process at a breakpoint or while stepping.
An expression can be cast only by menu.
Functions may only be called when the process is stopped and not in a system call.
.PP
On the Sun if a
.I ps
command is issued in the
.I pi
window and an attempt is made to open the process,
attaching to the process it will only successfully if
the last component of arg[0] of the process is somewhere in the
environment variable PATH.
If
.IR hang (1)
is used to stop a process, some code may be executed before
.I pi
can attach to it.
On the Sun, debugged processes share text so it not possible to debug
two instances of the same binary.  This will create problems if breakpoints
are set in code which are executed by a forked child of a debugged process.