sbin/ddb/ddb.8

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