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.Dd December 24, 2008 27.Dt DDB 8 28.Os 29.Sh NAME 30.Nm ddb 31.Nd "configure DDB kernel debugger properties" 32.Sh SYNOPSIS 33.Nm 34.Cm capture 35.Op Fl M core 36.Op Fl N system 37.Cm print 38.Nm 39.Cm capture 40.Op Fl M core 41.Op Fl N system 42.Cm status 43.Nm 44.Cm script 45.Ar scriptname 46.Nm 47.Cm script 48.Ar scriptname Ns = Ns Ar script 49.Nm 50.Cm scripts 51.Nm 52.Cm unscript 53.Ar scriptname 54.Nm 55.Ar pathname 56.Sh DESCRIPTION 57The 58.Nm 59utility configures certain aspects of the 60.Xr ddb 4 61kernel debugger from user space that are not configured at compile-time or 62easily via 63.Xr sysctl 8 64MIB entries. 65.Pp 66To ease configuration, commands can be put in a file which is processed using 67.Nm 68as shown in the last synopsis line. 69An absolute 70.Ar pathname 71must be used. 72The file will be read line by line and applied as arguments to the 73.Nm 74utility. 75Whitespace at the beginning of lines will be ignored as will lines where the 76first non-whitespace character is 77.Ql # . 78.Sh OUTPUT CAPTURE 79The 80.Nm 81utility can be used to extract the contents of the 82.Xr ddb 4 83output capture buffer of the current live kernel, or from the crash dump of a 84kernel on disk. 85The following debugger commands are available from the command line: 86.Bl -tag -width indent 87.It Xo 88.Cm capture 89.Op Fl M Ar core 90.Op Fl N Ar system 91.Cm print 92.Xc 93Print the current contents of the 94.Xr ddb 4 95output capture buffer. 96.It Xo 97.Cm capture 98.Op Fl M Ar core 99.Op Fl N Ar system 100.Cm status 101.Xc 102Print the current status of the 103.Xr ddb 4 104output capture buffer. 105.El 106.Sh SCRIPTING 107The 108.Nm 109utility can be used to configure aspects of 110.Xr ddb 4 111scripting from user space; scripting support is described in more detail in 112.Xr ddb 4 . 113Each of the debugger commands is available from the command line: 114.Bl -tag -width indent 115.It Cm script Ar scriptname 116Print the script named 117.Ar scriptname . 118.It Cm script Ar scriptname Ns = Ns Ar script 119Define a script named 120.Ar scriptname . 121As many scripts contain characters interpreted in special ways by the shell, 122it is advisable to enclose 123.Ar script 124in quotes. 125.It Cm scripts 126List currently defined scripts. 127.It Cm unscript Ar scriptname 128Delete the script named 129.Ar scriptname . 130.El 131.Sh EXIT STATUS 132.Ex -std 133.Sh EXAMPLES 134The following example defines a script that will execute when the kernel 135debugger is entered as a result of a break signal: 136.Bd -literal -offset indent 137ddb script kdb.enter.break="show pcpu; bt" 138.Ed 139.Pp 140The following example will delete the script: 141.Pp 142.Dl "ddb unscript kdb.enter.break" 143.Pp 144For further examples, see the 145.Xr ddb 4 146and 147.Xr textdump 4 148manual pages. 149.Sh SEE ALSO 150.Xr ddb 4 , 151.Xr mac_ddb 4 , 152.Xr textdump 4 , 153.Xr sysctl 8 154.Sh HISTORY 155The 156.Nm 157utility first appeared in 158.Fx 7.1 . 159.Sh AUTHORS 160.An Robert N M Watson 161.Sh BUGS 162Ideally, 163.Nm 164would not exist, as all pertinent aspects of 165.Xr ddb 4 166could be configured directly via 167.Xr sysctl 8 . 168