Return to pmdb.1 CVS log

Up to [local] / src / usr.bin / pmdb

Annotation of src/usr.bin/pmdb/pmdb.1, Revision 1.8

1.8     ! todd        1: .\"    $OpenBSD: pmdb.1,v 1.7 2002/06/05 18:30:59 fgsch Exp $
1.1       art         2: .\"
                      3: .\" Copyright (c) 2002 Artur Grabowski <art@openbsd.org>
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\"
                     10: .\" 1. Redistributions of source code must retain the above copyright
                     11: .\"    notice, this list of conditions and the following disclaimer.
                     12: .\" 2. The name of the author may not be used to endorse or promote products
                     13: .\"    derived from this software without specific prior written permission.
                     14: .\"
                     15: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
                     16: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
                     17: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
                     18: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
                     19: .\" EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLUDING, BUT NOT LIMITED TO,
                     20: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
                     21: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
                     22: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
                     23: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
                     24: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
                     25: .\"
                     26: .Dd Feb 20, 2002
                     27: .Dt PMDB 1
                     28: .Os
                     29: .Sh NAME
                     30: .Nm pmdb
                     31: .Nd debugger.
                     32: .Sh SYNOPSIS
                     33: .Nm pmdb
1.7       fgsch      34: .Op Fl c Ar core
1.8     ! todd       35: .Op Fl p Ar pid
1.1       art        36: .Ar program Op Ar ...
                     37: .Sh DESCRIPTION
                     38: The
                     39: .Nm
                     40: utility can be used to see what is happening inside a running process or
                     41: to catch program crashes and examine the state at the time of the crash.
                     42: The only way to start
                     43: .Nm
1.6       espie      44: at this moment is to specify the name of the program to be debugged and all
1.1       art        45: its arguments on the command line.
1.7       fgsch      46: Optionally,
                     47: .Fl c
                     48: can be used to specify a core file to examine.
1.8     ! todd       49: It is also possible to debug a process that is already running by specifying
        !            50: the process's PID to the
        !            51: .Fl p
        !            52: flag.  This causes the process to be put in STOPPED state until execution
        !            53: is resumed either by an explicit command to pmdb or by exiting pmdb.
1.1       art        54: The program is controlled from a command line which usually gives the
                     55: prompt "pmdb>".
                     56: .Sh PROCESS STATES
                     57: A loaded program can be in one of three possible states:
                     58: .Bl -tag -width RUNNING
                     59: .It LOADED
                     60: This is the initial state.
                     61: The program is not running, it can't be examined (because it doesn't have
                     62: any state).
                     63: The only thing that can be done to the process is to start it with the
                     64: .Ic run
                     65: command.
                     66: .It RUNNING
                     67: When a process is
                     68: .Ic RUNNING ,
                     69: the only way to affect it is through signals sent to it.
                     70: Unless a signal is ignored with the
                     71: .Ic signal ignore
1.6       espie      72: command, it will be catched by
                     73: .Nm
                     74: and the process will go into the
1.1       art        75: .Ic STOPPED
                     76: state.
                     77: .It STOPPED
                     78: A stopped process can be examined, changed and restarted with the
                     79: .Ic continue
                     80: command.
                     81: .El
                     82: .Sh COMMANDS
                     83: .Bl -tag -width continue
                     84: .It regs
                     85: Show the contents of the processor registers at the moment the process was
                     86: .Ic STOPPED .
                     87: .It trace
                     88: Show the function call trace of the currently
                     89: .Ic STOPPED
                     90: process.
                     91: .It run
                     92: Start running a
                     93: .Ic LOADED
                     94: process.
                     95: .It continue
                     96: Continue a
                     97: .Ic STOPPED
                     98: process.
                     99: .It kill
                    100: Unconditionally kills the debugged process and puts it in the
                    101: .Ic LOADED
                    102: state.
                    103: .It signal Ar ignore|stop Ar signum|signame
                    104: Sets the signal state for the specified signal to either ignore it and
                    105: pass it to the process or to stop the process.
                    106: .It sigstate
                    107: Shows which signals are currently ignored.
1.3       art       108: .It break Ar symname|addr
                    109: Sets a breakpoint at the symbol
                    110: .Ar symname
                    111: or the numerical address
                    112: .Ar addr .
                    113: .It step
                    114: Resumes execution just like
                    115: .Ic continue ,
                    116: but stops it again as soon as possible after executing at least
                    117: one instruction.
1.5       art       118: .It sym_load Ar fname Ar offs
                    119: Loads a symbol table from the file
                    120: .Ar fname
                    121: at the offset
                    122: .Ar offs .
1.1       art       123: .It help
                    124: Shows a short help.
                    125: .It quit
                    126: Kills the process (if necessary) and exits
                    127: .Nm .
                    128: .It exit
                    129: Alias for
                    130: .Ic quit .
                    131: .El
1.7       fgsch     132: .Sh SEE ALSO
                    133: .Xr core 5
1.1       art       134: .Sh HISTORY
                    135: The
                    136: .Nm
                    137: debugger was written because the author believed that
                    138: .Xr gdb 1
1.6       espie     139: was too bloated and hairy to run on OpenBSD/sparc64.
1.7       fgsch     140: .Sh BUGS
                    141: The command syntax is really poor and ad hoc at this moment. Most of the
                    142: command names and arguments will change as soon as the command line interface
                    143: is replaced.