1.\"- 2.\" Copyright (c) 2007-2008 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd December 24, 2008 29.Dt DDB 8 30.Os 31.Sh NAME 32.Nm ddb 33.Nd "configure DDB kernel debugger properties" 34.Sh SYNOPSIS 35.Nm 36.Cm capture 37.Op Fl M core 38.Op Fl N system 39.Cm print 40.Nm 41.Cm capture 42.Op Fl M core 43.Op Fl N system 44.Cm status 45.Nm 46.Cm script 47.Ar scriptname 48.Nm 49.Cm script 50.Ar scriptname Ns = Ns Ar script 51.Nm 52.Cm scripts 53.Nm 54.Cm unscript 55.Ar scriptname 56.Nm 57.Ar pathname 58.Sh DESCRIPTION 59The 60.Nm 61utility configures certain aspects of the 62.Xr ddb 4 63kernel debugger from user space that are not configured at compile-time or 64easily via 65.Xr sysctl 8 66MIB entries. 67.Pp 68To ease configuration, commands can be put in a file which is processed using 69.Nm 70as shown in the last synopsis line. 71An absolute 72.Ar pathname 73must be used. 74The file will be read line by line and applied as arguments to the 75.Nm 76utility. 77Whitespace at the beginning of lines will be ignored as will lines where the 78first non-whitespace character is 79.Ql # . 80.Sh OUTPUT CAPTURE 81The 82.Nm 83utility can be used to extract the contents of the 84.Xr ddb 4 85output capture buffer of the current live kernel, or from the crash dump of a 86kernel on disk. 87The following debugger commands are available from the command line: 88.Bl -tag -width indent 89.It Xo 90.Cm capture 91.Op Fl M Ar core 92.Op Fl N Ar system 93.Cm print 94.Xc 95Print the current contents of the 96.Xr ddb 4 97output capture buffer. 98.It Xo 99.Cm capture 100.Op Fl M Ar core 101.Op Fl N Ar system 102.Cm status 103.Xc 104Print the current status of the 105.Xr ddb 4 106output capture buffer. 107.El 108.Sh SCRIPTING 109The 110.Nm 111utility can be used to configure aspects of 112.Xr ddb 4 113scripting from user space; scripting support is described in more detail in 114.Xr ddb 4 . 115Each of the debugger commands is available from the command line: 116.Bl -tag -width indent 117.It Cm script Ar scriptname 118Print the script named 119.Ar scriptname . 120.It Cm script Ar scriptname Ns = Ns Ar script 121Define a script named 122.Ar scriptname . 123As many scripts contain characters interpreted in special ways by the shell, 124it is advisable to enclose 125.Ar script 126in quotes. 127.It Cm scripts 128List currently defined scripts. 129.It Cm unscript Ar scriptname 130Delete the script named 131.Ar scriptname . 132.El 133.Sh EXIT STATUS 134.Ex -std 135.Sh EXAMPLES 136The following example defines a script that will execute when the kernel 137debugger is entered as a result of a break signal: 138.Bd -literal -offset indent 139ddb script kdb.enter.break="show pcpu; bt" 140.Ed 141.Pp 142The following example will delete the script: 143.Pp 144.Dl "ddb unscript kdb.enter.break" 145.Pp 146For further examples, see the 147.Xr ddb 4 148and 149.Xr textdump 4 150manual pages. 151.Sh SEE ALSO 152.Xr ddb 4 , 153.Xr mac_ddb 4 , 154.Xr textdump 4 , 155.Xr sysctl 8 156.Sh HISTORY 157The 158.Nm 159utility first appeared in 160.Fx 7.1 . 161.Sh AUTHORS 162.An Robert N M Watson 163.Sh BUGS 164Ideally, 165.Nm 166would not exist, as all pertinent aspects of 167.Xr ddb 4 168could be configured directly via 169.Xr sysctl 8 . 170