Return to pi.9 CVS log

Up to [Research Unix] / researchv10dc / man / man9

Annotation of researchv10dc/man/man9/pi.9, revision 1.1

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.