Annotation of src/usr.bin/pmdb/pmdb.1, Revision 1.18
1.18 ! jmc 1: .\" $OpenBSD: pmdb.1,v 1.17 2007/08/06 19:16:05 sobrado Exp $
1.1 art 2: .\"
3: .\" Copyright (c) 2002 Artur Grabowski <art@openbsd.org>
1.13 jmc 4: .\" All rights reserved.
1.1 art 5: .\"
1.13 jmc 6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
1.1 art 9: .\"
1.13 jmc 10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
1.1 art 12: .\" 2. The name of the author may not be used to endorse or promote products
1.13 jmc 13: .\" derived from this software without specific prior written permission.
1.1 art 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
1.13 jmc 24: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.1 art 25: .\"
1.17 sobrado 26: .Dd $Mdocdate: May 31 2007 $
1.1 art 27: .Dt PMDB 1
28: .Os
29: .Sh NAME
30: .Nm pmdb
1.12 david 31: .Nd debugger
1.1 art 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.17 sobrado 36: .Ar program ...
1.1 art 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.13 jmc 46: Optionally,
1.7 fgsch 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
1.13 jmc 52: flag.
53: This causes the process to be put in STOPPED state until execution
1.8 todd 54: is resumed either by an explicit command to pmdb or by exiting pmdb.
1.1 art 55: The program is controlled from a command line which usually gives the
56: prompt "pmdb>".
57: .Sh PROCESS STATES
58: A loaded program can be in one of three possible states:
59: .Bl -tag -width RUNNING
60: .It LOADED
61: This is the initial state.
62: The program is not running, it can't be examined (because it doesn't have
63: any state).
64: The only thing that can be done to the process is to start it with the
65: .Ic run
66: command.
67: .It RUNNING
68: When a process is
69: .Ic RUNNING ,
70: the only way to affect it is through signals sent to it.
71: Unless a signal is ignored with the
72: .Ic signal ignore
1.10 mcbride 73: command, it will be caught by
1.13 jmc 74: .Nm
1.6 espie 75: and the process will go into the
1.1 art 76: .Ic STOPPED
77: state.
78: .It STOPPED
79: A stopped process can be examined, changed and restarted with the
80: .Ic continue
81: command.
82: .El
83: .Sh COMMANDS
1.15 mickey 84: .Bl -tag -width continueXXXX
85: .It examine Ar symbol|address
86: Fetch and display in hex a word at
87: .Ar address
88: or
89: .Ar symbol .
1.1 art 90: .It regs
91: Show the contents of the processor registers at the moment the process was
92: .Ic STOPPED .
93: .It trace
94: Show the function call trace of the currently
95: .Ic STOPPED
96: process.
97: .It run
98: Start running a
99: .Ic LOADED
100: process.
101: .It continue
102: Continue a
103: .Ic STOPPED
104: process.
105: .It kill
106: Unconditionally kills the debugged process and puts it in the
107: .Ic LOADED
108: state.
109: .It signal Ar ignore|stop Ar signum|signame
110: Sets the signal state for the specified signal to either ignore it and
111: pass it to the process or to stop the process.
112: .It sigstate
113: Shows which signals are currently ignored.
1.9 art 114: .It setenv Ar var Ar val
115: Sets the environment variable
116: .Ar var
117: to the value
118: .Ar val .
1.3 art 119: .It break Ar symname|addr
120: Sets a breakpoint at the symbol
121: .Ar symname
122: or the numerical address
123: .Ar addr .
124: .It step
125: Resumes execution just like
126: .Ic continue ,
127: but stops it again as soon as possible after executing at least
128: one instruction.
1.5 art 129: .It sym_load Ar fname Ar offs
130: Loads a symbol table from the file
131: .Ar fname
132: at the offset
133: .Ar offs .
1.1 art 134: .It help
135: Shows a short help.
136: .It quit
1.14 pvalchev 137: Kills the process (if necessary) and exits.
1.1 art 138: .It exit
139: Alias for
140: .Ic quit .
141: .El
1.7 fgsch 142: .Sh SEE ALSO
143: .Xr core 5
1.1 art 144: .Sh HISTORY
145: The
146: .Nm
147: debugger was written because the author believed that
148: .Xr gdb 1
1.6 espie 149: was too bloated and hairy to run on OpenBSD/sparc64.
1.7 fgsch 150: .Sh BUGS
1.18 ! jmc 151: The command syntax is really poor and ad hoc at this moment.
! 152: Most of the command names and arguments will change
! 153: as soon as the command line interface is replaced.