![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pi.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv9 / jtools / man / man1|
Return to pi.1 CVS log | Up to [Research Unix] / researchv9 / jtools / man / man1 |
1.1 root 1: .TH PI 1
2: .CT 1 debug_tune
3: .SH NAME
4: pi, rtpi \- process inspector
5: .SH SYNOPSIS
6: .B pi
7: [
8: .B -t
9: .I corefile objectfile
10: ]
11: .PP
12: .B rtpi
13: .I internetid
14: .SH DESCRIPTION
15: .I Pi
16: is a C debugger that
17: is bound dynamically to multiple subject processes or core dumps.
18: It works better for programs compiled
19: .I cc
20: .IR -g .
21: .I Pi
22: uses the
23: .IR Pads (5)
24: multi-window user interface.
25: There are three types of windows:
26: debugger control windows,
27: which access the global state of the debugger;
28: process control windows (exactly one per process),
29: which start and stop processes and connect to process-specific functions;
30: and process inspection windows,
31: which include viewers for source text and memory, formatted various ways.
32: .PP
33: The most important debugger control window is the
34: .I pi
35: window itself.
36: Each line within the
37: .I pi
38: window refers to a specific process.
39: These lines may be introduced to the window by running
40: .IR ps (1)
41: from the button 3 menu;
42: by typing a file name, either a
43: process id number followed by the name of the binary which is executing,
44: or the name of a core image followed by the name of the binary that created
45: the core;
46: or by typing a command, prefixed by an exclamation
47: .LR ! ,
48: to be executed as a child of
49: .IR pi .
50: There are several ways to access a process (using the button 2 menu),
51: each of which generates a process control window:
52: .B
53: open process
54: .RB ( open\ core dump )
55: attaches to a running process (core image);
56: .B
57: open child
58: attaches to a process forked by a process being debugged by the current
59: .IR pi ;
60: and
61: .B
62: take over
63: rebinds an existing process window hierarchy (pointed to with the mouse)
64: to the named process,
65: which must be an instance of the same program.
66: A command may be instantiated afresh
67: .RB ( hang\ &\ open\ proc )
68: or restarted and bound to an existing process window
69: .RB ( hang\ &\ take\ over );
70: in either case, IO is redirected to
71: .IR /dev/null .
72: .PP
73: The process window indicates the process's state,
74: shows the call stack traceback
75: and connects to windows that access source text,
76: local variables within a stack frame,
77: raw memory, and so on.
78: These windows are cross-connected, so, for example,
79: an instruction in a process's assembly language window can
80: be inspected in hexadecimal in the raw memory window.
81: Closing the process control window closes all the windows under it.
82: .PP
83: The following menu functions are provided by
84: the various window types in
85: .IR pi .
86: Initially there are these windows available:
87: .TP 0.5i
88: .B Help
89: Reminder of user interface mechanics.
90: .TP
91: .B Pi
92: Overall control of processes, core dumps and programs.
93: A process is identified by its pathname or command line.
94: Process symbols are found in the executable file from which the process was loaded,
95: but may be overridden.
96: Symbols for core dumps must be supplied explicitly, after the core filename.
97: .B Synopsis:
98: Identify and open process or core dump;
99: run a program as
100: .I Pi's
101: child;
102: take over a process with the debugging environment of a different one.
103: .TP
104: .B Pwd/cd
105: change the working directory of the debugger.
106: .SS Process Window
107: Selecting and opening a process from the Pi window creates a new
108: window with overall control of that process.
109: It shows the process state, and a traceback if the process is halted or dead.
110: States are:
111: .TP 1.5i
112: .PD 0
113: .SM
114: .B ACTIVE
115: running normally
116: .TP
117: .SM
118: .B HALTED
119: halted asynchronously by a debugger
120: .TP
121: .SM
122: .B BREAKPOINT
123: halted on reaching breakpoint
124: .TP
125: .SM
126: .B STMT STEPPED
127: halted after executing C source statement(s)
128: .TP
129: .SM
130: .B INSTR STEPPED
131: halted after executing machine instruction(s)
132: .TP
133: .SM
134: .B EVENT PENDING
135: halted about to receive a signal being traced
136: .TP
137: .SM
138: .B ERROR STATE
139: the process has probably exited.
140: .PD
141: .LP
142: The menu operations on the process are:
143: .PD 0
144: .TP 1i
145: .B go
146: let the process run
147: .TP
148: .B stop
149: stop the process
150: .TP
151: .B kill
152: send signal SIGKILL to the process
153: .TP
154: .B src text
155: open source text window(s)
156: .TP
157: .B Signals
158: open window for sending and trapping signals
159: .TP
160: .B Globals
161: open window for evaluating expression in global scope
162: .TP
163: .B RawMemory
164: open window for editing uninterpreted memory
165: .TP
166: .B Assembler
167: open window for disassembler
168: .PD
169: .LP
170: Each line of the call stack traceback describes one function.
171: Each function in the traceback can open an expression evaluator window
172: or display its current source line.
173: .SS Globals and Stack Frame Windows
174: .PP
175: These windows evaluate expressions with respect to global scope,
176: and scope in a function, respectively.
177: A stack frame window is opened from a line in the call stack traceback or
178: from a line of source text.
179: C expressions can be entered by the keyboard or mouse.
180: The unary operators
181: .I fabs
182: and
183: .I sizeof
184: are supported; the only assignment operator is
185: .LR = .
186: Functions from the user program may be called.
187: .LP
188: New C expressions can be derived from old ones by the keyboard or mouse.
189: In menus and the keyboard, $ means the expression in the current line.
190: The VAX registers are called $r0 to $r15; 68000 registers are called
191: $a0 to $a7, $d0 - $d7; the address of a register is
192: the location at which it was saved.
193: The format in which values are displayed can be changed.
194: The raw memory editor may be entered using an expression's value as address.
195: An expression may be made a
196: .IR spy .
197: The value of a spy expression is evaluated and displayed
198: each time the debugger looks at the process.
199: If the value of a spy changes the process is halted
200: at the next instruction, statement or breakpoint.
201: A stack frame can find its active source line in a source window or the stack
202: frame window of its caller.
203: .LP
204: The comma operator is useful in conditional breakpoints because the values
205: of its subexpressions are displayed.
206: E.g. x, y, x==y traces the values of x and y when the condition fails;
207: x, y, 0 just traces.
208: .LP
209: To cross scope boundaries, the environment (a function identifier)
210: in which an expression is to be evaluated may be specified as:
211: { expr } function.
212: From the source directory window, file static variables can be promoted
213: to appear in the menu of global variables.
214: .SS Source Text Windows
215: The source file directory window lists all the source files, if there are
216: two or more.
217: A textual prefix, entered from the keyboard, points to a source directory,
218: without changing the working directory.
219: Each source file is in a separate window, opened when needed.
220: The source file's pathname as given to
221: .I cc
222: can be overridden from the keyboard.
223: If things go wrong, use
224: .B reopen
225: to open the file afresh.
226: .B Synopsis:
227: set/clear (conditional) breakpoint;
228: single-step source statements;
229: step into (rather than over) a function;
230: go the process;
231: show the statement for the current PC;
232: open a stack frame window for a source line's function;
233: evaluate expression;
234: disassemble first instruction of source statement;
235: context search for string.
236: .SS Breakpoints Window
237: Lists all the active source and assembler breakpoints and related errors.
238: .B Synopsis:
239: show source or assembler for a breakpoint;
240: clear breakpoint;
241: clear all breakpoints.
242: .SS Signals Window
243: Lists all signal types, showing which ones are traced.
244: .B Synopsis:
245: Change which signals are traced;
246: send a signal to the subject process;
247: clear pending signal;
248: stop process on
249: .I exec.
250: .SS Raw Memory Window
251: A ``memory editor'' in which
252: memory is a viewed as a sequence of 1-, 2-, 4- or 8-byte cells.
253: .B Synopsis:
254: set cell address;
255: change cell size;
256: change display format;
257: display cells above and below;
258: indirect to cell;
259: change cell value;
260: spy on memory cell;
261: disassemble instruction at cell.
262: .SS (Dis)assembler Window
263: Disassembler in which memory is viewed as a sequence of instructions.
264: .B Synopsis:
265: set instruction address;
266: display more instructions;
267: change display format;
268: display instruction as cell in raw memory window;
269: set/clear breakpoint on instruction;
270: open stack frame window for instruction's function;
271: display instruction at current PC;
272: single step instruction(s);
273: step over a function call instead of into the function.
274: .SS Exec and Fork
275: If a process controlled by
276: .I pi
277: executes an
278: .IR exec (),
279: it is suspended as if started by
280: .IR hang (1),
281: if an
282: .IR exec ()
283: break is set in the Signals window.
284: To debug the process after the
285: .IR exec ,
286: close the original process window and re-open it.
287: When re-opened it will get the new symbol tables.
288: .PP
289: To debug a child process: (i) set a breakpoint in code that will be executed
290: in the child after the fork; (ii) execute the fork
291: .I at full speed
292: (the child inherits the parent's breakpoints, which aren't there if the
293: parent is stepped);
294: (iii)
295: .I before altering any breakpoints,
296: get a fresh
297: .I ps
298: in the Pi window and apply
299: .I open child
300: to the child.
301: The child should be stopped on the inherited breakpoint, but it and all other
302: breakpoints should have been cleared.
303: .SS Kernel
304: The state of kernel variables associated with a process may be examined
305: by giving their name or virtual address.
306: The
307: .B UNIX
308: environment variable specifies the file from which the system was
309: loaded; the default is
310: .IR /vmunix .
311: Kernel dumps may be examined by opening the
312: `kernel pi' window.
313: .SS Just A Traceback
314: With the
315: .B -t
316: option
317: .I pi
318: writes a traceback on its standard output and quits.
319: .SS Terminal Process Loading
320: .I Pi
321: looks at the environment variable
322: .I TERM
323: to determine where to load
324: .IR pads (5)
325: from.
326: If it is set to \fIxterm\fR or \fIsun\fR it will look for
327: an executable called
328: .I pads
329: in the current environment variable
330: .IR PATH .
331: Otherwise it assumes it is being used with an AT&T 5620 terminal.
332: .SS rtpi
333: .I Rtpi
334: is a variant of
335: .I pi
336: for remote debugging of real-time processes on 680X0 boards connected
337: via Ethernet.
338: .I Internetid
339: is the internet name of the board.
340: .SH SEE ALSO
341: .PP
342: .IR hang (1),
343: .IR strip (1),
344: .IR pads (5)
345: .SH BUGS
346: In switch statements there is no boundary between the last case
347: and the branch code; the program
348: .I appears
349: to jump to the last case (but is really in the branch)
350: and then to the real case.
351: A changed spy only stops the process at a breakpoint or while stepping.
352: An expression can be cast only by menu.
353: Functions may only be called when the process is stopped and not in a system call.
354: .PP
355: On the Sun if a
356: .I ps
357: command is issued in the
358: .I pi
359: window and an attempt is made to open the process,
360: attaching to the process it will only successfully if
361: the last component of arg[0] of the process is somewhere in the
362: environment variable PATH.
363: If
364: .IR hang (1)
365: is used to stop a process, some code may be executed before
366: .I pi
367: can attach to it.
368: On the Sun, debugged processes share text so it not possible to debug
369: two instances of the same binary. This will create problems if breakpoints
370: are set in code which are executed by a forked child of a debugged process.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.