Annotation of src/usr.bin/pmdb/pmdb.1, Revision 1.9
1.9 ! art 1: .\" $OpenBSD: pmdb.1,v 1.8 2002/06/09 02:44:34 todd 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.9 ! art 108: .It setenv Ar var Ar val
! 109: Sets the environment variable
! 110: .Ar var
! 111: to the value
! 112: .Ar val .
1.3 art 113: .It break Ar symname|addr
114: Sets a breakpoint at the symbol
115: .Ar symname
116: or the numerical address
117: .Ar addr .
118: .It step
119: Resumes execution just like
120: .Ic continue ,
121: but stops it again as soon as possible after executing at least
122: one instruction.
1.5 art 123: .It sym_load Ar fname Ar offs
124: Loads a symbol table from the file
125: .Ar fname
126: at the offset
127: .Ar offs .
1.1 art 128: .It help
129: Shows a short help.
130: .It quit
131: Kills the process (if necessary) and exits
132: .Nm .
133: .It exit
134: Alias for
135: .Ic quit .
136: .El
1.7 fgsch 137: .Sh SEE ALSO
138: .Xr core 5
1.1 art 139: .Sh HISTORY
140: The
141: .Nm
142: debugger was written because the author believed that
143: .Xr gdb 1
1.6 espie 144: was too bloated and hairy to run on OpenBSD/sparc64.
1.7 fgsch 145: .Sh BUGS
146: The command syntax is really poor and ad hoc at this moment. Most of the
147: command names and arguments will change as soon as the command line interface
148: is replaced.