1.\" $OpenBSD: pmdb.1,v 1.15 2003/08/02 17:40:51 mickey Exp $ 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 February 20, 2002 27.Dt PMDB 1 28.Os 29.Sh NAME 30.Nm pmdb 31.Nd debugger 32.Sh SYNOPSIS 33.Nm pmdb 34.Op Fl c Ar core 35.Op Fl p Ar pid 36.Ar program Op Ar ... 37.Sh DESCRIPTION 38The 39.Nm 40utility can be used to see what is happening inside a running process or 41to catch program crashes and examine the state at the time of the crash. 42The only way to start 43.Nm 44at this moment is to specify the name of the program to be debugged and all 45its arguments on the command line. 46Optionally, 47.Fl c 48can be used to specify a core file to examine. 49It is also possible to debug a process that is already running by specifying 50the process's PID to the 51.Fl p 52flag. 53This causes the process to be put in STOPPED state until execution 54is resumed either by an explicit command to pmdb or by exiting pmdb. 55The program is controlled from a command line which usually gives the 56prompt "pmdb>". 57.Sh PROCESS STATES 58A loaded program can be in one of three possible states: 59.Bl -tag -width RUNNING 60.It LOADED 61This is the initial state. 62The program is not running, it can't be examined (because it doesn't have 63any state). 64The only thing that can be done to the process is to start it with the 65.Ic run 66command. 67.It RUNNING 68When a process is 69.Ic RUNNING , 70the only way to affect it is through signals sent to it. 71Unless a signal is ignored with the 72.Ic signal ignore 73command, it will be caught by 74.Nm 75and the process will go into the 76.Ic STOPPED 77state. 78.It STOPPED 79A stopped process can be examined, changed and restarted with the 80.Ic continue 81command. 82.El 83.Sh COMMANDS 84.Bl -tag -width continueXXXX 85.It examine Ar symbol|address 86Fetch and display in hex a word at 87.Ar address 88or 89.Ar symbol . 90.It regs 91Show the contents of the processor registers at the moment the process was 92.Ic STOPPED . 93.It trace 94Show the function call trace of the currently 95.Ic STOPPED 96process. 97.It run 98Start running a 99.Ic LOADED 100process. 101.It continue 102Continue a 103.Ic STOPPED 104process. 105.It kill 106Unconditionally kills the debugged process and puts it in the 107.Ic LOADED 108state. 109.It signal Ar ignore|stop Ar signum|signame 110Sets the signal state for the specified signal to either ignore it and 111pass it to the process or to stop the process. 112.It sigstate 113Shows which signals are currently ignored. 114.It setenv Ar var Ar val 115Sets the environment variable 116.Ar var 117to the value 118.Ar val . 119.It break Ar symname|addr 120Sets a breakpoint at the symbol 121.Ar symname 122or the numerical address 123.Ar addr . 124.It step 125Resumes execution just like 126.Ic continue , 127but stops it again as soon as possible after executing at least 128one instruction. 129.It sym_load Ar fname Ar offs 130Loads a symbol table from the file 131.Ar fname 132at the offset 133.Ar offs . 134.It help 135Shows a short help. 136.It quit 137Kills the process (if necessary) and exits. 138.It exit 139Alias for 140.Ic quit . 141.El 142.Sh SEE ALSO 143.Xr core 5 144.Sh HISTORY 145The 146.Nm 147debugger was written because the author believed that 148.Xr gdb 1 149was too bloated and hairy to run on OpenBSD/sparc64. 150.Sh BUGS 151The command syntax is really poor and ad hoc at this moment. Most of the 152command names and arguments will change as soon as the command line interface 153is replaced. 154