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