Return to pi.1 CVS log

Up to [Research Unix] / researchv9 / jtools / man / man1

Annotation of researchv9/jtools/man/man1/pi.1, revision 1.1

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.