diff options
Diffstat (limited to 'static/freebsd/man4/ddb.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ddb.4 3.html | 1449 |
1 files changed, 1449 insertions, 0 deletions
diff --git a/static/freebsd/man4/ddb.4 3.html b/static/freebsd/man4/ddb.4 3.html new file mode 100644 index 00000000..196eff35 --- /dev/null +++ b/static/freebsd/man4/ddb.4 3.html @@ -0,0 +1,1449 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DDB(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">DDB(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">ddb</code> — <span class="Nd">interactive + kernel debugger</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">In order to enable kernel debugging facilities include:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options KDB</code> +<br/> +<code class="Cd">options DDB</code></div> +<p class="Pp">To prevent activation of the debugger on kernel + <a class="Xr">panic(9)</a>:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options + KDB_UNATTENDED</code></div> +<p class="Pp">In order to print a stack trace of the current thread on the + console for a panic:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options KDB_TRACE</code></div> +<p class="Pp">To print the numerical value of symbols in addition to the + symbolic representation, define:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options DDB_NUMSYM</code></div> +<p class="Pp">To enable the <a class="Xr">gdb(4)</a> backend, so that remote + debugging with <a class="Xr">kgdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>) is possible, include:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">options GDB</code></div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">ddb</code> kernel debugger is an interactive + debugger with a syntax inspired by <a class="Xr">gdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>). If linked into the running + kernel, it can be invoked locally with the + ‘<code class="Li">debug</code>’ <a class="Xr">keymap(5)</a> + action, usually mapped to Ctrl+Alt+Esc, or by setting the + <var class="Va">debug.kdb.enter</var> sysctl to 1. The debugger is also + invoked on kernel <a class="Xr">panic(9)</a> if the + <var class="Va">debug.debugger_on_panic</var> <a class="Xr">sysctl(8)</a> + MIB variable is set non-zero, which is the default unless the + <code class="Dv">KDB_UNATTENDED</code> option is specified. Similarly, if + the <var class="Va">debug.debugger_on_recursive_panic</var> variable is set + to <code class="Dv">1</code>, then the debugger will be invoked on a + recursive kernel panic. This variable has a default value of + <code class="Dv">0</code>, and has no effect if + <var class="Va">debug.debugger_on_panic</var> is already set non-zero.</p> +<p class="Pp">The current location is called <var class="Va">dot</var>. The + <var class="Va">dot</var> is displayed with a hexadecimal format at a + prompt. The commands <code class="Ic">examine</code> and + <code class="Ic">write</code> update <var class="Va">dot</var> to the + address of the last line examined or the last location modified, and set + <var class="Va">next</var> to the address of the next location to be + examined or changed. Other commands do not change <var class="Va">dot</var>, + and set <var class="Va">next</var> to be the same as + <var class="Va">dot</var>.</p> +<p class="Pp">The general command syntax is: + <var class="Ar">command</var>[<code class="Li">/</code><var class="Ar">modifier</var>] + [<var class="Ar">addr</var>][,<var class="Ar">count</var>]</p> +<p class="Pp">A blank line repeats the previous command from the address + <var class="Va">next</var> with count 1 and no modifiers. Specifying + <var class="Ar">addr</var> sets <var class="Va">dot</var> to the address. + Omitting <var class="Ar">addr</var> uses <var class="Va">dot</var>. A + missing <var class="Ar">count</var> is taken to be 1 for printing commands + or infinity for stack traces. A <var class="Ar">count</var> of -1 is + equivalent to a missing <var class="Ar">count</var>. Options that are + supplied but not supported by the given <var class="Ar">command</var> are + usually ignored.</p> +<p class="Pp">The <code class="Nm">ddb</code> debugger has a pager feature (like + the <a class="Xr">more(1)</a> command) for the output. If an output line + exceeds the number set in the <var class="Va">lines</var> variable, it + displays “<code class="Li">--More--</code>” and waits for a + response. The valid responses for it are:</p> +<p class="Pp"></p> +<dl class="Bl-tag Bl-compact"> + <dt id="SPC"><a class="permalink" href="#SPC"><code class="Li">SPC</code></a></dt> + <dd>one more page</dd> + <dt id="RET"><a class="permalink" href="#RET"><code class="Li">RET</code></a></dt> + <dd>one more line</dd> + <dt id="q"><a class="permalink" href="#q"><code class="Li">q</code></a></dt> + <dd>abort the current command, and return to the command input mode</dd> +</dl> +<p class="Pp">Finally, <code class="Nm">ddb</code> provides a small (currently + 10 items) command history, and offers simple + <code class="Nm">emacs</code>-style command line editing capabilities. In + addition to the <code class="Nm">emacs</code> control keys, the usual ANSI + arrow keys may be used to browse through the history buffer, and move the + cursor within the current line.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMMANDS"><a class="permalink" href="#COMMANDS">COMMANDS</a></h1> +<section class="Ss"> +<h2 class="Ss" id="COMMON_DEBUGGER_COMMANDS"><a class="permalink" href="#COMMON_DEBUGGER_COMMANDS">COMMON + DEBUGGER COMMANDS</a></h2> +<dl class="Bl-tag Bl-compact"> + <dt id="help"><a class="permalink" href="#help"><code class="Ic">help</code></a></dt> + <dd>Print a short summary of the available commands and command abbreviations. + <p class="Pp"></p> + </dd> + <dt id="examine"><a class="permalink" href="#examine"><code class="Ic">examine</code></a>[<code class="Li">/</code><code class="Cm">AISabcdghilmorsuxz + ...</code>] [<var class="Ar">addr</var>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="x"><a class="permalink" href="#x"><code class="Ic">x</code></a>[<code class="Li">/</code><code class="Cm">AISabcdghilmorsuxz + ...</code>] [<var class="Ar">addr</var>][,<var class="Ar">count</var>]</dt> + <dd>Display the addressed locations according to the formats in the modifier. + Multiple modifier formats display multiple locations. If no format is + specified, the last format specified for this command is used. + <p class="Pp">The format characters are:</p> + <dl class="Bl-tag Bl-compact"> + <dt id="b"><a class="permalink" href="#b"><code class="Cm">b</code></a></dt> + <dd>look at by bytes (8 bits)</dd> + <dt id="h"><a class="permalink" href="#h"><code class="Cm">h</code></a></dt> + <dd>look at by half words (16 bits)</dd> + <dt id="l"><a class="permalink" href="#l"><code class="Cm">l</code></a></dt> + <dd>look at by long words (32 bits)</dd> + <dt id="g"><a class="permalink" href="#g"><code class="Cm">g</code></a></dt> + <dd>look at by quad words (64 bits)</dd> + <dt id="a"><a class="permalink" href="#a"><code class="Cm">a</code></a></dt> + <dd>print the location being displayed</dd> + <dt id="A"><a class="permalink" href="#A"><code class="Cm">A</code></a></dt> + <dd>print the location with a line number if possible</dd> + <dt id="x~2"><a class="permalink" href="#x~2"><code class="Cm">x</code></a></dt> + <dd>display in unsigned hex</dd> + <dt id="z"><a class="permalink" href="#z"><code class="Cm">z</code></a></dt> + <dd>display in signed hex</dd> + <dt id="o"><a class="permalink" href="#o"><code class="Cm">o</code></a></dt> + <dd>display in unsigned octal</dd> + <dt id="d"><a class="permalink" href="#d"><code class="Cm">d</code></a></dt> + <dd>display in signed decimal</dd> + <dt id="u"><a class="permalink" href="#u"><code class="Cm">u</code></a></dt> + <dd>display in unsigned decimal</dd> + <dt id="r"><a class="permalink" href="#r"><code class="Cm">r</code></a></dt> + <dd>display in current radix, signed</dd> + <dt id="c"><a class="permalink" href="#c"><code class="Cm">c</code></a></dt> + <dd>display low 8 bits as a character. Non-printing characters are + displayed as an octal escape code (e.g., + ‘<code class="Li">\000</code>’).</dd> + <dt id="s"><a class="permalink" href="#s"><code class="Cm">s</code></a></dt> + <dd>display the null-terminated string at the location. Non-printing + characters are displayed as octal escapes.</dd> + <dt id="m"><a class="permalink" href="#m"><code class="Cm">m</code></a></dt> + <dd>display in unsigned hex with character dump at the end of each line. + The location is also displayed in hex at the beginning of each + line.</dd> + <dt id="i"><a class="permalink" href="#i"><code class="Cm">i</code></a></dt> + <dd>display as a disassembled instruction</dd> + <dt id="I"><a class="permalink" href="#I"><code class="Cm">I</code></a></dt> + <dd>display as a disassembled instruction with possible alternate formats + depending on the machine. On i386, this selects the alternate format + for the instruction decoding (16 bits in a 32-bit code segment and + vice versa).</dd> + <dt id="S"><a class="permalink" href="#S"><code class="Cm">S</code></a></dt> + <dd>display a symbol name for the pointer stored at the address</dd> + </dl> + <p class="Pp"></p> + </dd> + <dt id="xf"><a class="permalink" href="#xf"><code class="Ic">xf</code></a></dt> + <dd>Examine forward: execute an <code class="Ic">examine</code> command with + the last specified parameters to it except that the next address displayed + by it is used as the start address. + <p class="Pp"></p> + </dd> + <dt id="xb"><a class="permalink" href="#xb"><code class="Ic">xb</code></a></dt> + <dd>Examine backward: execute an <code class="Ic">examine</code> command with + the last specified parameters to it except that the last start address + subtracted by the size displayed by it is used as the start address. + <p class="Pp"></p> + </dd> + <dt id="print"><a class="permalink" href="#print"><code class="Ic">print</code></a>[<code class="Li">/</code><code class="Cm">acdoruxz</code>]</dt> + <dd style="width: auto;"> </dd> + <dt id="p"><a class="permalink" href="#p"><code class="Ic">p</code></a>[<code class="Li">/</code><code class="Cm">acdoruxz</code>]</dt> + <dd>Print <var class="Ar">addr</var>s according to the modifier character (as + described above for <code class="Cm">examine</code>). Valid formats are: + <code class="Cm">a</code>, <code class="Cm">x</code>, + <code class="Cm">z</code>, <code class="Cm">o</code>, + <code class="Cm">d</code>, <code class="Cm">u</code>, + <code class="Cm">r</code>, and <code class="Cm">c</code>. If no modifier + is specified, the last one specified to it is used. The argument + <var class="Ar">addr</var> can be a string, in which case it is printed as + it is. For example: + <div class="Bd Pp Bd-indent Li"> + <pre>print/x "eax = " $eax "\necx = " $ecx "\n"</pre> + </div> + <p class="Pp">will print like:</p> + <div class="Bd Pp Bd-indent Li"> + <pre>eax = xxxxxx +ecx = yyyyyy</pre> + </div> + <p class="Pp"></p> + </dd> + <dt id="pprint"><a class="permalink" href="#pprint"><code class="Ic">pprint</code></a>[<code class="Li">/</code><code class="Cm">d + depth</code>] [<var class="Ar">name</var>]</dt> + <dd>Pretty-print symbol specified by <var class="Ar">name</var> using CTF + debugging data. Works for all symbols exported by the kernel and loaded + kernel modules. + <p class="Pp">If the <code class="Cm">d</code> modifier has been specified, + contents of structs nested up to <var class="Ar">depth</var> levels deep + will also be included in the output.</p> + <p class="Pp"></p> + </dd> + <dt><code class="Ic">pprint + struct</code>[<code class="Li">/</code><code class="Cm">d depth</code>] + [<var class="Ar">name</var>][<var class="Ar">addr</var>]</dt> + <dd>Print memory at <var class="Ar">addr</var> as struct + <var class="Ar">name</var>. Works for all structs defined by the kernel + and loaded kernel modules. + <p class="Pp">If the <code class="Cm">d</code> modifier has been specified, + contents of structs nested up to <var class="Ar">depth</var> levels deep + will also be included in the output.</p> + <p class="Pp"></p> + </dd> + <dt id="write"><a class="permalink" href="#write"><code class="Ic">write</code></a>[<code class="Li">/</code><code class="Cm">bhl</code>] + <var class="Ar">addr expr1</var> [<var class="Ar">expr2 ...</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="w"><a class="permalink" href="#w"><code class="Ic">w</code></a>[<code class="Li">/</code><code class="Cm">bhl</code>] + <var class="Ar">addr expr1</var> [<var class="Ar">expr2 ...</var>]</dt> + <dd>Write the expressions specified after <var class="Ar">addr</var> on the + command line at succeeding locations starting with + <var class="Ar">addr</var>. The write unit size can be specified in the + modifier with a letter <code class="Cm">b</code> (byte), + <code class="Cm">h</code> (half word) or <code class="Cm">l</code> (long + word) respectively. If omitted, long word is assumed. + <p class="Pp"><b class="Sy">Warning</b>: since there is no delimiter between + expressions, strange things may happen. It is best to enclose each + expression in parentheses.</p> + <p class="Pp"></p> + </dd> + <dt id="set"><a class="permalink" href="#set"><code class="Ic">set</code></a> + <code class="Li">$</code><var class="Ar">variable</var> + [<code class="Li">=</code>] <var class="Ar">expr</var></dt> + <dd>Set the named variable or register with the value of + <var class="Ar">expr</var>. Valid variable names are described below. + <p class="Pp"></p> + </dd> + <dt id="break"><a class="permalink" href="#break"><code class="Ic">break</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">addr</var>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="b~2"><a class="permalink" href="#b~2"><code class="Ic">b</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">addr</var>][,<var class="Ar">count</var>]</dt> + <dd>Set a break point at <var class="Ar">addr</var>. If + <var class="Ar">count</var> is supplied, the + <code class="Ic">continue</code> command will not stop at this break point + on the first <var class="Ar">count</var> - 1 times that it is hit. If the + break point is set, a break point number is printed with + ‘<code class="Li">#</code>’. This number can be used in + deleting the break point or adding conditions to it. + <p class="Pp">If the <code class="Cm">u</code> modifier is specified, this + command sets a break point in user address space. Without the + <code class="Cm">u</code> option, the address is considered to be in the + kernel space, and a wrong space address is rejected with an error + message. This modifier can be used only if it is supported by machine + dependent routines.</p> + <p class="Pp"><b class="Sy">Warning</b>: If a user text is shadowed by a + normal user space debugger, user space break points may not work + correctly. Setting a break point at the low-level code paths may also + cause strange behavior.</p> + <p class="Pp"></p> + </dd> + <dt id="delete"><a class="permalink" href="#delete"><code class="Ic">delete</code></a> + [<var class="Ar">addr</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="d~2"><a class="permalink" href="#d~2"><code class="Ic">d</code></a> + [<var class="Ar">addr</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="delete~2"><a class="permalink" href="#delete~2"><code class="Ic">delete</code></a> + <code class="Li">#</code><var class="Ar">number</var></dt> + <dd style="width: auto;"> </dd> + <dt id="d~3"><a class="permalink" href="#d~3"><code class="Ic">d</code></a> + <code class="Li">#</code><var class="Ar">number</var></dt> + <dd>Delete the specified break point. The break point can be specified by a + break point number with ‘<code class="Li">#</code>’, or by + using the same <var class="Ar">addr</var> specified in the original + <code class="Ic">break</code> command, or by omitting + <var class="Ar">addr</var> to get the default address of + <var class="Va">dot</var>. + <p class="Pp"></p> + </dd> + <dt id="halt"><a class="permalink" href="#halt"><code class="Ic">halt</code></a></dt> + <dd>Halt the system. + <p class="Pp"></p> + </dd> + <dt id="watch"><a class="permalink" href="#watch"><code class="Ic">watch</code></a> + [<var class="Ar">addr</var>][,<var class="Ar">size</var>]</dt> + <dd>Set a watchpoint for a region. Execution stops when an attempt to modify + the region occurs. The <var class="Ar">size</var> argument defaults to 4. + If you specify a wrong space address, the request is rejected with an + error message. + <p class="Pp"><b class="Sy">Warning</b>: Attempts to watch wired kernel + memory may cause unrecoverable error in some systems such as i386. + Watchpoints on user addresses work best.</p> + <p class="Pp"></p> + </dd> + <dt id="hwatch"><a class="permalink" href="#hwatch"><code class="Ic">hwatch</code></a> + [<var class="Ar">addr</var>][,<var class="Ar">size</var>]</dt> + <dd>Set a hardware watchpoint for a region if supported by the architecture. + Execution stops when an attempt to modify the region occurs. The + <var class="Ar">size</var> argument defaults to 4. + <p class="Pp"><b class="Sy">Warning</b>: The hardware debug facilities do + not have a concept of separate address spaces like the watch command + does. Use <code class="Ic">hwatch</code> for setting watchpoints on + kernel address locations only, and avoid its use on user mode address + spaces.</p> + <p class="Pp"></p> + </dd> + <dt id="dhwatch"><a class="permalink" href="#dhwatch"><code class="Ic">dhwatch</code></a> + [<var class="Ar">addr</var>][,<var class="Ar">size</var>]</dt> + <dd>Delete specified hardware watchpoint. + <p class="Pp"></p> + </dd> + <dt id="kill"><a class="permalink" href="#kill"><code class="Ic">kill</code></a> + <var class="Ar">sig pid</var></dt> + <dd>Send signal <var class="Ar">sig</var> to process + <var class="Ar">pid</var>. The signal is acted on upon returning from the + debugger. This command can be used to kill a process causing resource + contention in the case of a hung system. See <a class="Xr">signal(3)</a> + for a list of signals. Note that the arguments are reversed relative to + <a class="Xr">kill(2)</a>. + <p class="Pp"></p> + </dd> + <dt id="step"><a class="permalink" href="#step"><code class="Ic">step</code></a>[<code class="Li">/</code><code class="Cm">p</code>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="s~2"><a class="permalink" href="#s~2"><code class="Ic">s</code></a>[<code class="Li">/</code><code class="Cm">p</code>][,<var class="Ar">count</var>]</dt> + <dd>Single step <var class="Ar">count</var> times. If the + <code class="Cm">p</code> modifier is specified, print each instruction at + each step. Otherwise, only print the last instruction. + <p class="Pp"><b class="Sy">Warning</b>: depending on machine type, it may + not be possible to single-step through some low-level code paths or user + space code. On machines with software-emulated single-stepping (e.g., + pmax), stepping through code executed by interrupt handlers will + probably do the wrong thing.</p> + <p class="Pp"></p> + </dd> + <dt id="continue"><a class="permalink" href="#continue"><code class="Ic">continue</code></a>[<code class="Li">/</code><code class="Cm">c</code>]</dt> + <dd style="width: auto;"> </dd> + <dt id="c~2"><a class="permalink" href="#c~2"><code class="Ic">c</code></a>[<code class="Li">/</code><code class="Cm">c</code>]</dt> + <dd>Continue execution until a breakpoint or watchpoint. If the + <code class="Cm">c</code> modifier is specified, count instructions while + executing. Some machines (e.g., pmax) also count loads and stores. + <p class="Pp"><b class="Sy">Warning</b>: when counting, the debugger is + really silently single-stepping. This means that single-stepping on + low-level code may cause strange behavior.</p> + <p class="Pp"></p> + </dd> + <dt id="until"><a class="permalink" href="#until"><code class="Ic">until</code></a>[<code class="Li">/</code><code class="Cm">p</code>]</dt> + <dd>Stop at the next call or return instruction. If the + <code class="Cm">p</code> modifier is specified, print the call nesting + depth and the cumulative instruction count at each call or return. + Otherwise, only print when the matching return is hit. + <p class="Pp"></p> + </dd> + <dt id="next"><a class="permalink" href="#next"><code class="Ic">next</code></a>[<code class="Li">/</code><code class="Cm">p</code>]</dt> + <dd style="width: auto;"> </dd> + <dt id="match"><a class="permalink" href="#match"><code class="Ic">match</code></a>[<code class="Li">/</code><code class="Cm">p</code>]</dt> + <dd>Stop at the matching return instruction. If the <code class="Cm">p</code> + modifier is specified, print the call nesting depth and the cumulative + instruction count at each call or return. Otherwise, only print when the + matching return is hit. + <p class="Pp"></p> + </dd> + <dt id="trace"><a class="permalink" href="#trace"><code class="Ic">trace</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">pid</var> | + <var class="Ar">tid</var>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="t"><a class="permalink" href="#t"><code class="Ic">t</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">pid</var> | + <var class="Ar">tid</var>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="where"><a class="permalink" href="#where"><code class="Ic">where</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">pid</var> | + <var class="Ar">tid</var>][,<var class="Ar">count</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="bt"><a class="permalink" href="#bt"><code class="Ic">bt</code></a>[<code class="Li">/</code><code class="Cm">u</code>] + [<var class="Ar">pid</var> | + <var class="Ar">tid</var>][,<var class="Ar">count</var>]</dt> + <dd>Stack trace. The <code class="Cm">u</code> option traces user space; if + omitted, <code class="Ic">trace</code> only traces kernel space. The + optional argument <var class="Ar">count</var> is the number of frames to + be traced. If <var class="Ar">count</var> is omitted, all frames are + printed. + <p class="Pp"><b class="Sy">Warning</b>: User space stack trace is valid + only if the machine dependent code supports it.</p> + <p class="Pp"></p> + </dd> + <dt id="search"><a class="permalink" href="#search"><code class="Ic">search</code></a>[<code class="Li">/</code><code class="Cm">bhl</code>] + <var class="Ar">addr</var> <var class="Ar">value</var> + [<var class="Ar">mask</var>][,<var class="Ar">count</var>]</dt> + <dd>Search memory for <var class="Ar">value</var>. The optional + <var class="Ar">count</var> argument limits the search. + <p class="Pp"></p> + </dd> + <dt id="reboot"><a class="permalink" href="#reboot"><code class="Ic">reboot</code></a>[<code class="Li">/</code><code class="Cm">s</code>] + [<var class="Ar">seconds</var>]</dt> + <dd style="width: auto;"> </dd> + <dt id="reset"><a class="permalink" href="#reset"><code class="Ic">reset</code></a>[<code class="Li">/</code><code class="Cm">s</code>] + [<var class="Ar">seconds</var>]</dt> + <dd>Hard reset the system. If the optional argument + <var class="Ar">seconds</var> is given, the debugger will wait for this + long, at most a week, before rebooting. When the <code class="Cm">s</code> + modifier is given, the command will skip running any registered shutdown + handlers and attempt the most basic reset. + <p class="Pp"></p> + </dd> + <dt id="thread"><a class="permalink" href="#thread"><code class="Ic">thread</code></a> + <var class="Ar">addr</var> | <var class="Ar">tid</var></dt> + <dd>Switch the debugger to the thread with ID <var class="Ar">tid</var>, if + the argument is a decimal number, or address <var class="Ar">addr</var>, + otherwise. + <p class="Pp"></p> + </dd> + <dt id="watchdog"><a class="permalink" href="#watchdog"><code class="Ic">watchdog</code></a> + [<var class="Ar">exp</var>]</dt> + <dd>Program the <a class="Xr">watchdog(4)</a> timer to fire in + 2^<var class="Ar">exp</var> seconds. If no argument is provided, the + watchdog timer is disabled.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="SPECIALIZED_HELPER_COMMANDS"><a class="permalink" href="#SPECIALIZED_HELPER_COMMANDS">SPECIALIZED + HELPER COMMANDS</a></h2> +<dl class="Bl-tag Bl-compact"> + <dt id="findstack"><a class="permalink" href="#findstack"><code class="Ic">findstack</code></a> + <var class="Ar">addr</var></dt> + <dd>Prints the address of the thread whose kernel-mode stack contains + <var class="Ar">addr</var>, if any. + <p class="Pp"></p> + </dd> + <dt id="show"><a class="permalink" href="#show"><code class="Ic">show</code></a> + <code class="Cm">active trace</code></dt> + <dd style="width: auto;"> </dd> + <dt id="acttrace"><a class="permalink" href="#acttrace"><code class="Ic">acttrace</code></a></dt> + <dd>Show a stack trace for every thread running on a CPU. + <p class="Pp"></p> + </dd> + <dt id="show~2"><a class="permalink" href="#show~2"><code class="Ic">show</code></a> + <code class="Cm">all + procs</code>[<code class="Li">/</code><code class="Cm">a</code>]</dt> + <dd style="width: auto;"> </dd> + <dt id="ps"><a class="permalink" href="#ps"><code class="Ic">ps</code></a>[<code class="Li">/</code><code class="Cm">a</code>]</dt> + <dd>Display all process information. The process information may not be shown + if it is not supported in the machine, or the bottom of the stack of the + target process is not in the main memory at that time. The + <code class="Cm">a</code> modifier will print command line arguments for + each process. + <p class="Pp"></p> + </dd> + <dt id="show~3"><a class="permalink" href="#show~3"><code class="Ic">show</code></a> + <code class="Cm">all + tcpcbs</code>[<code class="Li">/</code><code class="Cm">b</code><code class="Cm">i</code><code class="Cm">l</code>]</dt> + <dd>Show the same output as "show tcpcb" does, but for all TCP + control blocks within the system. The <code class="Cm">b</code> modifier + will request BBLog entries to be printed. If the <code class="Cm">i</code> + modifier is provided, the corresponding IP control block is also shown. + Using the <code class="Cm">l</code> modifier will limit the output to TCP + control blocks, which are locked. + <p class="Pp"></p> + </dd> + <dt id="show~4"><a class="permalink" href="#show~4"><code class="Ic">show</code></a> + <code class="Cm">all trace</code></dt> + <dd style="width: auto;"> </dd> + <dt id="alltrace"><a class="permalink" href="#alltrace"><code class="Ic">alltrace</code></a></dt> + <dd>Show a stack trace for every thread in the system. + <p class="Pp"></p> + </dd> + <dt id="show~5"><a class="permalink" href="#show~5"><code class="Ic">show</code></a> + <code class="Cm">all ttys</code></dt> + <dd>Show all TTY's within the system. Output is similar to + <a class="Xr">pstat(8)</a>, but also includes the address of the TTY + structure. + <p class="Pp"></p> + </dd> + <dt id="show~6"><a class="permalink" href="#show~6"><code class="Ic">show</code></a> + <code class="Cm">all vnets</code></dt> + <dd>Show the same output as "show vnet" does, but lists all + virtualized network stacks within the system. + <p class="Pp"></p> + </dd> + <dt id="show~7"><a class="permalink" href="#show~7"><code class="Ic">show</code></a> + <code class="Cm">allchains</code></dt> + <dd>Show the same information like "show lockchain" does, but for + every thread in the system. + <p class="Pp"></p> + </dd> + <dt id="show~8"><a class="permalink" href="#show~8"><code class="Ic">show</code></a> + <code class="Cm">alllocks</code></dt> + <dd>Show all locks that are currently held. This command is only available if + <a class="Xr">witness(4)</a> is included in the kernel. + <p class="Pp"></p> + </dd> + <dt id="show~9"><a class="permalink" href="#show~9"><code class="Ic">show</code></a> + <code class="Cm">allpcpu</code></dt> + <dd>The same as "show pcpu", but for every CPU present in the + system. + <p class="Pp"></p> + </dd> + <dt id="show~10"><a class="permalink" href="#show~10"><code class="Ic">show</code></a> + <code class="Cm">allrman</code></dt> + <dd>Show information related with resource management, including interrupt + request lines, DMA request lines, I/O ports, I/O memory addresses, and + Resource IDs. + <p class="Pp"></p> + </dd> + <dt id="show~11"><a class="permalink" href="#show~11"><code class="Ic">show</code></a> + <code class="Cm">apic</code></dt> + <dd>Dump data about APIC IDT vector mappings. + <p class="Pp"></p> + </dd> + <dt id="show~12"><a class="permalink" href="#show~12"><code class="Ic">show</code></a> + <code class="Cm">badstacks</code></dt> + <dd>Walk the <a class="Xr">witness(4)</a> graph and print any lock-order + violations. This command is only available if <a class="Xr">witness(4)</a> + is included in the kernel. + <p class="Pp"></p> + </dd> + <dt id="show~13"><a class="permalink" href="#show~13"><code class="Ic">show</code></a> + <code class="Cm">breaks</code></dt> + <dd>Show breakpoints set with the "break" command. + <p class="Pp"></p> + </dd> + <dt id="show~14"><a class="permalink" href="#show~14"><code class="Ic">show</code></a> + <code class="Cm">bio</code> <var class="Ar">addr</var></dt> + <dd>Show information about the bio structure <var class="Vt">struct bio</var> + present at <var class="Ar">addr</var>. See the + <span class="Pa">sys/bio.h</span> header file and + <a class="Xr">g_bio(9)</a> for more details on the exact meaning of the + structure fields. + <p class="Pp"></p> + </dd> + <dt id="show~15"><a class="permalink" href="#show~15"><code class="Ic">show</code></a> + <code class="Cm">buffer</code> <var class="Ar">addr</var></dt> + <dd>Show information about the buf structure <var class="Vt">struct buf</var> + present at <var class="Ar">addr</var>. See the + <span class="Pa">sys/buf.h</span> header file for more details on the + exact meaning of the structure fields. + <p class="Pp"></p> + </dd> + <dt id="show~16"><a class="permalink" href="#show~16"><code class="Ic">show</code></a> + <code class="Cm">callout</code> <var class="Ar">addr</var></dt> + <dd>Show information about the callout structure <var class="Vt">struct + callout</var> present at <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~17"><a class="permalink" href="#show~17"><code class="Ic">show</code></a> + <code class="Cm">cdev</code> [<var class="Ar">addr</var>]</dt> + <dd>Show the internal devfs state of the cdev structure located at + <var class="Ar">addr</var>. If no argument is provided, show the list of + all created cdevs, consisting of the devfs node name and the + <var class="Vt">struct cdev</var> address. + <p class="Pp"></p> + </dd> + <dt id="show~18"><a class="permalink" href="#show~18"><code class="Ic">show</code></a> + <code class="Cm">conifhk</code></dt> + <dd>Lists hooks currently waiting for completion in + <a class="permalink" href="#run_interrupt_driven_config_hooks"><code class="Fn" id="run_interrupt_driven_config_hooks">run_interrupt_driven_config_hooks</code></a>(). + <p class="Pp"></p> + </dd> + <dt id="show~19"><a class="permalink" href="#show~19"><code class="Ic">show</code></a> + <code class="Cm">cpusets</code></dt> + <dd>Print numbered root and assigned CPU affinity sets. See + <a class="Xr">cpuset(2)</a> for more details. + <p class="Pp"></p> + </dd> + <dt id="show~20"><a class="permalink" href="#show~20"><code class="Ic">show</code></a> + <code class="Cm">cyrixreg</code></dt> + <dd>Show registers specific to the Cyrix processor. + <p class="Pp"></p> + </dd> + <dt id="show~21"><a class="permalink" href="#show~21"><code class="Ic">show</code></a> + <code class="Cm">devmap</code></dt> + <dd>Prints the contents of the static device mapping table. Currently only + available on the ARM architecture. + <p class="Pp"></p> + </dd> + <dt id="show~22"><a class="permalink" href="#show~22"><code class="Ic">show</code></a> + <code class="Cm">domain</code> <var class="Ar">addr</var></dt> + <dd>Print protocol domain structure <var class="Vt">struct domain</var> at + address <var class="Ar">addr</var>. See the + <span class="Pa">sys/domain.h</span> header file for more details on the + exact meaning of the structure fields. + <p class="Pp"></p> + </dd> + <dt id="show~23"><a class="permalink" href="#show~23"><code class="Ic">show</code></a> + <code class="Cm">ffs</code> [<var class="Ar">addr</var>]</dt> + <dd>Show brief information about ffs mount at the address + <var class="Ar">addr</var>, if argument is given. Otherwise, provides the + summary about each ffs mount. + <p class="Pp"></p> + </dd> + <dt id="show~24"><a class="permalink" href="#show~24"><code class="Ic">show</code></a> + <code class="Cm">file</code> <var class="Ar">addr</var></dt> + <dd>Show information about the file structure <var class="Vt">struct + file</var> present at address <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~25"><a class="permalink" href="#show~25"><code class="Ic">show</code></a> + <code class="Cm">files</code></dt> + <dd>Show information about every file structure in the system. + <p class="Pp"></p> + </dd> + <dt id="show~26"><a class="permalink" href="#show~26"><code class="Ic">show</code></a> + <code class="Cm">freepages</code></dt> + <dd>Show the number of physical pages in each of the free lists. + <p class="Pp"></p> + </dd> + <dt id="show~27"><a class="permalink" href="#show~27"><code class="Ic">show</code></a> + <code class="Cm">geom</code> [<var class="Ar">addr</var>]</dt> + <dd>If the <var class="Ar">addr</var> argument is not given, displays the + entire GEOM topology. If <var class="Ar">addr</var> is given, displays + details about the given GEOM object (class, geom, provider or consumer). + <p class="Pp"></p> + </dd> + <dt id="show~28"><a class="permalink" href="#show~28"><code class="Ic">show</code></a> + <code class="Cm">idt</code></dt> + <dd>Show IDT layout. The first column specifies the IDT vector. The second one + is the name of the interrupt/trap handler. Those functions are machine + dependent. + <p class="Pp"></p> + </dd> + <dt id="show~29"><a class="permalink" href="#show~29"><code class="Ic">show</code></a> + <code class="Cm">igi_list</code> <var class="Ar">addr</var></dt> + <dd>Show information about the IGMP structure <var class="Vt">struct + igmp_ifsoftc</var> present at <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~30"><a class="permalink" href="#show~30"><code class="Ic">show</code></a> + <code class="Cm">iosched</code> <var class="Ar">addr</var></dt> + <dd>Show information about the I/O scheduler <var class="Vt">struct + cam_iosched_softc</var> located at <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~31"><a class="permalink" href="#show~31"><code class="Ic">show</code></a> + <code class="Cm">inodedeps</code> [<var class="Ar">addr</var>]</dt> + <dd>Show brief information about each inodedep structure. If + <var class="Ar">addr</var> is given, only inodedeps belonging to the fs + located at the supplied address are shown. + <p class="Pp"></p> + </dd> + <dt id="show~32"><a class="permalink" href="#show~32"><code class="Ic">show</code></a> + <code class="Cm">inpcb</code> <var class="Ar">addr</var></dt> + <dd>Show information on IP Control Block <var class="Vt">struct in_pcb</var> + present at <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~33"><a class="permalink" href="#show~33"><code class="Ic">show</code></a> + <code class="Cm">intr</code></dt> + <dd>Dump information about interrupt handlers. + <p class="Pp"></p> + </dd> + <dt id="show~34"><a class="permalink" href="#show~34"><code class="Ic">show</code></a> + <code class="Cm">intrcnt</code></dt> + <dd>Dump the interrupt statistics. + <p class="Pp"></p> + </dd> + <dt id="show~35"><a class="permalink" href="#show~35"><code class="Ic">show</code></a> + <code class="Cm">irqs</code></dt> + <dd>Show interrupt lines and their respective kernel threads. + <p class="Pp"></p> + </dd> + <dt id="show~36"><a class="permalink" href="#show~36"><code class="Ic">show</code></a> + <code class="Cm">ktr</code>[<code class="Li">/</code><code class="Cm">a</code><code class="Cm">v</code><code class="Cm">V</code>]</dt> + <dd>Print the contents of the <a class="Xr">ktr(4)</a> trace buffer. The + <code class="Cm">v</code> modifier will request fully verbose output, + causing the file, line number, and timestamp to be printed for each trace + entry. The <code class="Cm">V</code> modifier will request only the + timestamps to be printed. The <code class="Cm">a</code> modifier will + request that the output be unpaginated. + <p class="Pp"></p> + </dd> + <dt id="show~37"><a class="permalink" href="#show~37"><code class="Ic">show</code></a> + <code class="Cm">lapic</code></dt> + <dd>Show information from the local APIC registers for this CPU. + <p class="Pp"></p> + </dd> + <dt id="show~38"><a class="permalink" href="#show~38"><code class="Ic">show</code></a> + <code class="Cm">lock</code> <var class="Ar">addr</var></dt> + <dd>Show lock structure. The output format is as follows: + <dl class="Bl-tag"> + <dt id="class"><a class="permalink" href="#class"><code class="Ic">class</code></a>:</dt> + <dd>Class of the lock. Possible types include <a class="Xr">mutex(9)</a>, + <a class="Xr">rmlock(9)</a>, <a class="Xr">rwlock(9)</a>, + <a class="Xr">sx(9)</a>.</dd> + <dt id="name"><a class="permalink" href="#name"><code class="Ic">name</code></a>:</dt> + <dd>Name of the lock.</dd> + <dt id="flags"><a class="permalink" href="#flags"><code class="Ic">flags</code></a>:</dt> + <dd>Flags passed to the lock initialization function. + <i class="Em">flags</i> values are lock class specific.</dd> + <dt id="state"><a class="permalink" href="#state"><code class="Ic">state</code></a>:</dt> + <dd>Current state of a lock. <i class="Em">state</i> values are lock class + specific.</dd> + <dt id="owner"><a class="permalink" href="#owner"><code class="Ic">owner</code></a>:</dt> + <dd>Lock owner.</dd> + </dl> + <p class="Pp"></p> + </dd> + <dt id="show~39"><a class="permalink" href="#show~39"><code class="Ic">show</code></a> + <code class="Cm">lockchain</code> <var class="Ar">addr</var></dt> + <dd>Show all threads a particular thread at address <var class="Ar">addr</var> + is waiting on based on non-spin locks. + <p class="Pp"></p> + </dd> + <dt id="show~40"><a class="permalink" href="#show~40"><code class="Ic">show</code></a> + <code class="Cm">lockedbufs</code></dt> + <dd>Show the same information as "show buf", but for every locked + <var class="Vt">struct buf</var> object. + <p class="Pp"></p> + </dd> + <dt id="show~41"><a class="permalink" href="#show~41"><code class="Ic">show</code></a> + <code class="Cm">lockedvnods</code></dt> + <dd>List all locked vnodes in the system. + <p class="Pp"></p> + </dd> + <dt id="show~42"><a class="permalink" href="#show~42"><code class="Ic">show</code></a> + <code class="Cm">locks</code></dt> + <dd>Prints all locks that are currently acquired. This command is only + available if <a class="Xr">witness(4)</a> is included in the kernel. + <p class="Pp"></p> + </dd> + <dt id="show~43"><a class="permalink" href="#show~43"><code class="Ic">show</code></a> + <code class="Cm">locktree</code></dt> + <dd> + <p class="Pp"></p> + </dd> + <dt id="show~44"><a class="permalink" href="#show~44"><code class="Ic">show</code></a> + <code class="Cm">malloc</code>[<code class="Li">/</code><code class="Cm">i</code>]</dt> + <dd>Prints <a class="Xr">malloc(9)</a> memory allocator statistics. If the + <code class="Cm">i</code> modifier is specified, format output as + machine-parseable comma-separated values ("CSV"). The output + columns are as follows: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="Type"><a class="permalink" href="#Type"><code class="Ic">Type</code></a></dt> + <dd>Specifies a type of memory. It is the same as a description string + used while defining the given memory type with + <a class="Xr">MALLOC_DECLARE(9)</a>.</dd> + <dt id="InUse"><a class="permalink" href="#InUse"><code class="Ic">InUse</code></a></dt> + <dd>Number of memory allocations of the given type, for which + <a class="Xr">free(9)</a> has not been called yet.</dd> + <dt id="MemUse"><a class="permalink" href="#MemUse"><code class="Ic">MemUse</code></a></dt> + <dd>Total memory consumed by the given allocation type.</dd> + <dt id="Requests"><a class="permalink" href="#Requests"><code class="Ic">Requests</code></a></dt> + <dd>Number of memory allocation requests for the given memory type.</dd> + </dl> + </div> + <p class="Pp">The same information can be gathered in userspace with + “<code class="Nm">vmstat</code> + <code class="Fl">-m</code>”.</p> + <p class="Pp"></p> + </dd> + <dt id="show~45"><a class="permalink" href="#show~45"><code class="Ic">show</code></a> + <code class="Cm">map</code>[<code class="Li">/</code><code class="Cm">f</code>] + <var class="Ar">addr</var></dt> + <dd>Prints the VM map at <var class="Ar">addr</var>. If the + <code class="Cm">f</code> modifier is specified the complete map is + printed. + <p class="Pp"></p> + </dd> + <dt id="show~46"><a class="permalink" href="#show~46"><code class="Ic">show</code></a> + <code class="Cm">msgbuf</code></dt> + <dd>Print the system's message buffer. It is the same output as in the + “<code class="Nm">dmesg</code>” case. It is useful if you + got a kernel panic, attached a serial cable to the machine and want to get + the boot messages from before the system hang. + <p class="Pp"></p> + </dd> + <dt id="show~47"><a class="permalink" href="#show~47"><code class="Ic">show</code></a> + <code class="Cm">mount</code> [<var class="Ar">addr</var>]</dt> + <dd>Displays details about the mount point located at + <var class="Ar">addr</var>. If no <var class="Ar">addr</var> is specified, + displays short info about all currently mounted file systems. + <p class="Pp"></p> + </dd> + <dt id="show~48"><a class="permalink" href="#show~48"><code class="Ic">show</code></a> + <code class="Cm">object</code>[<code class="Li">/</code><code class="Cm">f</code>] + <var class="Ar">addr</var></dt> + <dd>Prints the VM object at <var class="Ar">addr</var>. If the + <code class="Cm">f</code> option is specified the complete object is + printed. + <p class="Pp"></p> + </dd> + <dt id="show~49"><a class="permalink" href="#show~49"><code class="Ic">show</code></a> + <code class="Cm">panic</code></dt> + <dd>Print the panic message if set. + <p class="Pp"></p> + </dd> + <dt id="show~50"><a class="permalink" href="#show~50"><code class="Ic">show</code></a> + <code class="Cm">page</code></dt> + <dd>Show statistics on VM pages. + <p class="Pp"></p> + </dd> + <dt id="show~51"><a class="permalink" href="#show~51"><code class="Ic">show</code></a> + <code class="Cm">pageq</code></dt> + <dd>Show statistics on VM page queues. + <p class="Pp"></p> + </dd> + <dt id="show~52"><a class="permalink" href="#show~52"><code class="Ic">show</code></a> + <code class="Cm">pciregs</code></dt> + <dd>Print PCI bus registers. The same information can be gathered in userspace + by running “<code class="Nm">pciconf</code> + <code class="Fl">-lv</code>”. + <p class="Pp"></p> + </dd> + <dt id="show~53"><a class="permalink" href="#show~53"><code class="Ic">show</code></a> + <code class="Cm">pcpu</code></dt> + <dd>Print current processor state. The output format is as follows: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="cpuid"><a class="permalink" href="#cpuid"><code class="Ic">cpuid</code></a></dt> + <dd>Processor identifier.</dd> + <dt id="curthread"><a class="permalink" href="#curthread"><code class="Ic">curthread</code></a></dt> + <dd>Thread pointer, process identifier and the name of the process.</dd> + <dt id="curpcb"><a class="permalink" href="#curpcb"><code class="Ic">curpcb</code></a></dt> + <dd>Control block pointer.</dd> + <dt id="fpcurthread"><a class="permalink" href="#fpcurthread"><code class="Ic">fpcurthread</code></a></dt> + <dd>FPU thread pointer.</dd> + <dt id="idlethread"><a class="permalink" href="#idlethread"><code class="Ic">idlethread</code></a></dt> + <dd>Idle thread pointer.</dd> + <dt id="APIC"><a class="permalink" href="#APIC"><code class="Ic">APIC + ID</code></a></dt> + <dd>CPU identifier coming from APIC.</dd> + <dt id="currentldt"><a class="permalink" href="#currentldt"><code class="Ic">currentldt</code></a></dt> + <dd>LDT pointer.</dd> + <dt id="spin"><a class="permalink" href="#spin"><code class="Ic">spin + locks held</code></a></dt> + <dd>Names of spin locks held.</dd> + </dl> + </div> + <p class="Pp"></p> + </dd> + <dt id="show~54"><a class="permalink" href="#show~54"><code class="Ic">show</code></a> + <code class="Cm">pgrpdump</code></dt> + <dd>Dump process groups present within the system. + <p class="Pp"></p> + </dd> + <dt id="show~55"><a class="permalink" href="#show~55"><code class="Ic">show</code></a> + <code class="Cm">prison</code> [<var class="Ar">addr</var>]</dt> + <dd>Show the prison structure located at <var class="Ar">addr</var>. If no + <var class="Ar">addr</var> argument is specified, show information about + all prisons in the system. + <p class="Pp"></p> + </dd> + <dt id="show~56"><a class="permalink" href="#show~56"><code class="Ic">show</code></a> + <code class="Cm">proc</code> [<var class="Ar">addr</var>]</dt> + <dd>Show information about the process structure located at address + <var class="Ar">addr</var>, or the current process if no argument is + specified. + <p class="Pp"></p> + </dd> + <dt id="show~57"><a class="permalink" href="#show~57"><code class="Ic">show</code></a> + <code class="Cm">procvm</code> [<var class="Ar">addr</var>]</dt> + <dd>Show process virtual memory layout for the process located at + <var class="Ar">addr</var>, or the current process if no argument is + specified. + <p class="Pp"></p> + </dd> + <dt id="show~58"><a class="permalink" href="#show~58"><code class="Ic">show</code></a> + <code class="Cm">protosw</code> <var class="Ar">addr</var></dt> + <dd>Print protocol switch structure <var class="Vt">struct protosw</var> at + address <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~59"><a class="permalink" href="#show~59"><code class="Ic">show</code></a> + <code class="Cm">registers</code>[<code class="Li">/</code><code class="Cm">u</code>]</dt> + <dd>Display the register set. If the <code class="Cm">u</code> modifier is + specified, the register contents of the thread's previous trapframe are + displayed instead. Usually, this corresponds to the saved state from + userspace. + <p class="Pp"></p> + </dd> + <dt id="show~60"><a class="permalink" href="#show~60"><code class="Ic">show</code></a> + <code class="Cm">rman</code> <var class="Ar">addr</var></dt> + <dd>Show resource manager object <var class="Vt">struct rman</var> at address + <var class="Ar">addr</var>. Addresses of particular pointers can be + gathered with "show allrman" command. + <p class="Pp"></p> + </dd> + <dt id="show~61"><a class="permalink" href="#show~61"><code class="Ic">show</code></a> + <code class="Cm">route</code> <var class="Ar">addr</var></dt> + <dd>Show route table result for destination <var class="Ar">addr</var>. At + this time, INET and INET6 formatted addresses are supported. + <p class="Pp"></p> + </dd> + <dt id="show~62"><a class="permalink" href="#show~62"><code class="Ic">show</code></a> + <code class="Cm">routetable</code> [<var class="Ar">af</var>]</dt> + <dd>Show full route table or tables. If <var class="Ar">af</var> is specified, + show only routes for the given numeric address family. If no argument is + specified, dump the route table for all address families. + <p class="Pp"></p> + </dd> + <dt id="show~63"><a class="permalink" href="#show~63"><code class="Ic">show</code></a> + <code class="Cm">rtc</code></dt> + <dd>Show real time clock value. Useful for long debugging sessions. + <p class="Pp"></p> + </dd> + <dt id="show~64"><a class="permalink" href="#show~64"><code class="Ic">show</code></a> + <code class="Cm">sleepchain</code></dt> + <dd>Deprecated. Now an alias for <code class="Ic">show</code> + <code class="Cm">lockchain</code>. + <p class="Pp"></p> + </dd> + <dt id="show~65"><a class="permalink" href="#show~65"><code class="Ic">show</code></a> + <code class="Cm">sleepq</code> <var class="Ar">addr</var></dt> + <dd style="width: auto;"> </dd> + <dt id="show~66"><a class="permalink" href="#show~66"><code class="Ic">show</code></a> + <code class="Cm">sleepqueue</code> <var class="Ar">addr</var></dt> + <dd>Show the <a class="Xr">sleepqueue(9)</a> structure located at + <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~67"><a class="permalink" href="#show~67"><code class="Ic">show</code></a> + <code class="Cm">sockbuf</code> <var class="Ar">addr</var></dt> + <dd>Show the socket buffer <var class="Va">struct sockbuf</var> located at + <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~68"><a class="permalink" href="#show~68"><code class="Ic">show</code></a> + <code class="Cm">socket</code> <var class="Ar">addr</var></dt> + <dd>Show the socket object <var class="Vt">struct socket</var> located at + <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~69"><a class="permalink" href="#show~69"><code class="Ic">show</code></a> + <code class="Cm">sysregs</code></dt> + <dd>Show system registers (e.g., <code class="Li">cr0-4</code> on i386.) Not + present on some platforms. + <p class="Pp"></p> + </dd> + <dt id="show~70"><a class="permalink" href="#show~70"><code class="Ic">show</code></a> + <code class="Cm">tcpcb</code>[<code class="Li">/</code><code class="Cm">b</code><code class="Cm">i</code>] + <var class="Ar">addr</var></dt> + <dd>Print TCP control block <var class="Vt">struct tcpcb</var> lying at + address <var class="Ar">addr</var>. For exact interpretation of output, + visit <span class="Pa">netinet/tcp.h</span> header file. The + <code class="Cm">b</code> modifier will request BBLog entries to be + printed. If the <code class="Cm">i</code> modifier is provided, the + corresponding IP control block is also shown. + <p class="Pp"></p> + </dd> + <dt id="show~71"><a class="permalink" href="#show~71"><code class="Ic">show</code></a> + <code class="Cm">thread</code> [<var class="Ar">addr</var> | + <var class="Ar">tid</var>]</dt> + <dd>If no <var class="Ar">addr</var> or <var class="Ar">tid</var> is + specified, show detailed information about current thread. Otherwise, + print information about the thread with ID <var class="Ar">tid</var> or + kernel address <var class="Ar">addr</var>. (If the argument is a decimal + number, it is assumed to be a tid.) + <p class="Pp"></p> + </dd> + <dt id="show~72"><a class="permalink" href="#show~72"><code class="Ic">show</code></a> + <code class="Cm">threads</code></dt> + <dd>Show all threads within the system. Output format is as follows: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="First"><a class="permalink" href="#First"><code class="Ic">First + column</code></a></dt> + <dd>Thread identifier (TID)</dd> + <dt id="Second"><a class="permalink" href="#Second"><code class="Ic">Second + column</code></a></dt> + <dd>Thread structure address</dd> + <dt id="Third"><a class="permalink" href="#Third"><code class="Ic">Third + column</code></a></dt> + <dd>Backtrace.</dd> + </dl> + </div> + <p class="Pp"></p> + </dd> + <dt id="show~73"><a class="permalink" href="#show~73"><code class="Ic">show</code></a> + <code class="Cm">tty</code> <var class="Ar">addr</var></dt> + <dd>Display the contents of a TTY structure in a readable form. + <p class="Pp"></p> + </dd> + <dt id="show~74"><a class="permalink" href="#show~74"><code class="Ic">show</code></a> + <code class="Cm">turnstile</code> <var class="Ar">addr</var></dt> + <dd>Show turnstile <var class="Vt">struct turnstile</var> structure at address + <var class="Ar">addr</var>. Turnstiles are structures used within the + <span class="Ux">FreeBSD</span> kernel to implement synchronization + primitives which, while holding a specific type of lock, cannot sleep or + context switch to another thread. Currently, those are: + <a class="Xr">mutex(9)</a>, <a class="Xr">rwlock(9)</a>, + <a class="Xr">rmlock(9)</a>. + <p class="Pp"></p> + </dd> + <dt id="show~75"><a class="permalink" href="#show~75"><code class="Ic">show</code></a> + <code class="Cm">uma</code>[<code class="Li">/</code><code class="Cm">i</code>]</dt> + <dd>Show UMA allocator statistics. If the <code class="Cm">i</code> modifier + is specified, format output as machine-parseable comma-separated values + ("CSV"). The output contains the following columns: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="Zone"><a class="permalink" href="#Zone"><code class="Cm">Zone</code></a></dt> + <dd>Name of the UMA zone. The same string that was passed to + <a class="Xr">uma_zcreate(9)</a> as a first argument.</dd> + <dt id="Size"><a class="permalink" href="#Size"><code class="Cm">Size</code></a></dt> + <dd>Size of a given memory object (slab).</dd> + <dt id="Used"><a class="permalink" href="#Used"><code class="Cm">Used</code></a></dt> + <dd>Number of slabs being currently used.</dd> + <dt id="Free"><a class="permalink" href="#Free"><code class="Cm">Free</code></a></dt> + <dd>Number of free slabs within the UMA zone.</dd> + <dt id="Requests~2"><a class="permalink" href="#Requests~2"><code class="Cm">Requests</code></a></dt> + <dd>Number of allocations requests to the given zone.</dd> + <dt id="Total"><a class="permalink" href="#Total"><code class="Cm">Total + Mem</code></a></dt> + <dd>Total memory in use (either allocated or free) by a zone, in + bytes.</dd> + <dt id="XFree"><a class="permalink" href="#XFree"><code class="Cm">XFree</code></a></dt> + <dd>Number of free slabs within the UMA zone that were freed on a + different NUMA domain than allocated. (The count in the + <code class="Cm">Free</code> column is inclusive of + <code class="Cm">XFree</code>.)</dd> + </dl> + </div> + <p class="Pp">The same information might be gathered in the userspace with + the help of “<code class="Nm">vmstat</code> + <code class="Fl">-z</code>”.</p> + <p class="Pp"></p> + </dd> + <dt id="show~76"><a class="permalink" href="#show~76"><code class="Ic">show</code></a> + <code class="Cm">unpcb</code> <var class="Ar">addr</var></dt> + <dd>Shows UNIX domain socket private control block <var class="Vt">struct + unpcb</var> present at the address <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~77"><a class="permalink" href="#show~77"><code class="Ic">show</code></a> + <code class="Cm">vmochk</code></dt> + <dd>Prints, whether the internal VM objects are in a map somewhere and none + have zero ref counts. + <p class="Pp"></p> + </dd> + <dt id="show~78"><a class="permalink" href="#show~78"><code class="Ic">show</code></a> + <code class="Cm">vmopag</code></dt> + <dd>Walk the list of VM objects in the system, printing the indices and + physical addresses of the VM pages belonging to each object. + <p class="Pp"></p> + </dd> + <dt id="show~79"><a class="permalink" href="#show~79"><code class="Ic">show</code></a> + <code class="Cm">vnet</code> <var class="Ar">addr</var></dt> + <dd>Prints virtualized network stack <var class="Vt">struct vnet</var> + structure present at the address <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~80"><a class="permalink" href="#show~80"><code class="Ic">show</code></a> + <code class="Cm">vnode</code> <var class="Ar">addr</var></dt> + <dd>Prints vnode <var class="Vt">struct vnode</var> structure lying at + <var class="Ar">addr</var>. For the exact interpretation of the output, + look at the <span class="Pa">sys/vnode.h</span> header file. + <p class="Pp"></p> + </dd> + <dt id="show~81"><a class="permalink" href="#show~81"><code class="Ic">show</code></a> + <code class="Cm">vnodebufs</code> <var class="Ar">addr</var></dt> + <dd>Shows clean/dirty buffer lists of the vnode located at + <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~82"><a class="permalink" href="#show~82"><code class="Ic">show</code></a> + <code class="Cm">vpath</code> <var class="Ar">addr</var></dt> + <dd>Walk the namecache to lookup the pathname of the vnode located at + <var class="Ar">addr</var>. + <p class="Pp"></p> + </dd> + <dt id="show~83"><a class="permalink" href="#show~83"><code class="Ic">show</code></a> + <code class="Cm">watches</code></dt> + <dd>Displays all watchpoints. Shows watchpoints set with "watch" + command. + <p class="Pp"></p> + </dd> + <dt id="show~84"><a class="permalink" href="#show~84"><code class="Ic">show</code></a> + <code class="Cm">witness</code></dt> + <dd>Shows information about lock acquisition coming from the + <a class="Xr">witness(4)</a> subsystem.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="OFFLINE_DEBUGGING_COMMANDS"><a class="permalink" href="#OFFLINE_DEBUGGING_COMMANDS">OFFLINE + DEBUGGING COMMANDS</a></h2> +<dl class="Bl-tag Bl-compact"> + <dt id="dump"><a class="permalink" href="#dump"><code class="Ic">dump</code></a></dt> + <dd>Initiate a kernel core dump to the device(s) configured by + <a class="Xr">dumpon(8)</a>. + <p class="Pp"></p> + </dd> + <dt id="gdb"><a class="permalink" href="#gdb"><code class="Ic">gdb</code></a></dt> + <dd>Switches to remote GDB mode. In remote GDB mode, another machine is + required that runs <a class="Xr">gdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>) using the remote debug feature, + with a connection to the serial console port on the target machine. + <p class="Pp"></p> + </dd> + <dt id="netdump"><a class="permalink" href="#netdump"><code class="Ic">netdump</code></a> + <code class="Fl">-s</code> <var class="Ar">server</var> + [<code class="Fl">-g</code> <var class="Ar">gateway</var> + <code class="Fl">-c</code> <var class="Ar">client</var> + <code class="Fl">-i</code> <var class="Ar">iface</var>]</dt> + <dd>Configure <a class="Xr">netdump(4)</a> with the provided parameters, and + immediately perform a netdump. + <p class="Pp">There are some known limitations. Principally, + <a class="Xr">netdump(4)</a> only supports IPv4 at this time. The + address arguments to the <code class="Ic">netdump</code> command must be + dotted decimal IPv4 addresses. (Hostnames are not supported.) At + present, the command only works if the machine is in a panic state. + Finally, the <code class="Nm">ddb</code> <code class="Ic">netdump</code> + command does not provide any way to configure compression or + encryption.</p> + <p class="Pp"></p> + </dd> + <dt id="netgdb"><a class="permalink" href="#netgdb"><code class="Ic">netgdb</code></a> + <code class="Fl">-s</code> <var class="Ar">server</var> + [<code class="Fl">-g</code> <var class="Ar">gateway</var> + <code class="Fl">-c</code> <var class="Ar">client</var> + <code class="Fl">-i</code> <var class="Ar">iface</var>]</dt> + <dd>Initiate a <a class="Xr">netgdb(4)</a> session with the provided + parameters. + <p class="Pp"><code class="Ic">netgdb</code> has identical limitations to + <code class="Ic">netdump</code>.</p> + <p class="Pp"></p> + </dd> + <dt id="capture"><a class="permalink" href="#capture"><code class="Ic">capture + on</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="capture~2"><a class="permalink" href="#capture~2"><code class="Ic">capture + off</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="capture~3"><a class="permalink" href="#capture~3"><code class="Ic">capture + reset</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="capture~4"><a class="permalink" href="#capture~4"><code class="Ic">capture + status</code></a></dt> + <dd><code class="Nm">ddb</code> supports a basic output capture facility, + which can be used to retrieve the results of debugging commands from + userspace using <a class="Xr">sysctl(3)</a>. <code class="Ic">capture + on</code> enables output capture; <code class="Ic">capture off</code> + disables capture. <code class="Ic">capture reset</code> will clear the + capture buffer and disable capture. <code class="Ic">capture status</code> + will report current buffer use, buffer size, and disposition of output + capture. + <p class="Pp">Userspace processes may inspect and manage + <code class="Nm">ddb</code> capture state using + <a class="Xr">sysctl(8)</a>:</p> + <p class="Pp"><var class="Va">debug.ddb.capture.bufsize</var> may be used to + query or set the current capture buffer size.</p> + <p class="Pp"><var class="Va">debug.ddb.capture.maxbufsize</var> may be used + to query the compile-time limit on the capture buffer size.</p> + <p class="Pp"><var class="Va">debug.ddb.capture.bytes</var> may be used to + query the number of bytes of output currently in the capture buffer.</p> + <p class="Pp"><var class="Va">debug.ddb.capture.data</var> returns the + contents of the buffer as a string to an appropriately privileged + process.</p> + <p class="Pp">This facility is particularly useful in concert with the + scripting and <a class="Xr">textdump(4)</a> facilities, allowing + scripted debugging output to be captured and committed to disk as part + of a textdump for later analysis. The contents of the capture buffer may + also be inspected in a kernel core dump using <a class="Xr">kgdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>).</p> + <p class="Pp"></p> + </dd> + <dt id="run"><a class="permalink" href="#run"><code class="Ic">run</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="script"><a class="permalink" href="#script"><code class="Ic">script</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="scripts"><a class="permalink" href="#scripts"><code class="Ic">scripts</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="unscript"><a class="permalink" href="#unscript"><code class="Ic">unscript</code></a></dt> + <dd>Run, define, list, and delete scripts. See the + <a class="Sx" href="#SCRIPTING">SCRIPTING</a> section for more information + on the scripting facility. + <p class="Pp"></p> + </dd> + <dt id="textdump"><a class="permalink" href="#textdump"><code class="Ic">textdump + dump</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="textdump~2"><a class="permalink" href="#textdump~2"><code class="Ic">textdump + set</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="textdump~3"><a class="permalink" href="#textdump~3"><code class="Ic">textdump + status</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="textdump~4"><a class="permalink" href="#textdump~4"><code class="Ic">textdump + unset</code></a></dt> + <dd>Use the <code class="Ic">textdump dump</code> command to immediately + perform a textdump. More information may be found in + <a class="Xr">textdump(4)</a>. The <code class="Ic">textdump set</code> + command may be used to force the next kernel core dump to be a textdump + rather than a traditional memory dump or minidump. + <code class="Ic">textdump status</code> reports whether a textdump has + been scheduled. <code class="Ic">textdump unset</code> cancels a request + to perform a textdump as the next kernel core dump.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="VARIABLES"><a class="permalink" href="#VARIABLES">VARIABLES</a></h1> +<p class="Pp">The debugger accesses registers and variables as + <code class="Li">$</code><var class="Ar">name</var>. Register names are as + in the “<code class="Ic">show</code> + <code class="Cm">registers</code>” command. Some variables are + suffixed with numbers, and may have some modifier following a colon + immediately after the variable name. For example, register variables can + have a <code class="Cm">u</code> modifier to indicate user register (e.g., + “<code class="Li">$eax:u</code>”).</p> +<p class="Pp">Built-in variables currently supported are:</p> +<p class="Pp"></p> +<dl class="Bl-tag Bl-compact"> + <dt id="radix"><var class="Va">radix</var></dt> + <dd>Input and output radix.</dd> + <dt id="maxoff"><var class="Va">maxoff</var></dt> + <dd>Addresses are printed as + “<var class="Ar">symbol</var><code class="Li">+</code><var class="Ar">offset</var>” + unless <var class="Ar">offset</var> is greater than + <var class="Va">maxoff</var>.</dd> + <dt id="maxwidth"><var class="Va">maxwidth</var></dt> + <dd>The width of the displayed line.</dd> + <dt id="lines"><var class="Va">lines</var></dt> + <dd>The number of lines. It is used by the built-in pager. Setting it to 0 + disables paging.</dd> + <dt id="tabstops"><var class="Va">tabstops</var></dt> + <dd>Tab stop width.</dd> + <dt id="work"><var class="Va">work</var><var class="Ar">xx</var></dt> + <dd>Work variable; <var class="Ar">xx</var> can take values from 0 to 31.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXPRESSIONS"><a class="permalink" href="#EXPRESSIONS">EXPRESSIONS</a></h1> +<p class="Pp">Most expression operators in C are supported except + ‘<code class="Li">~</code>’, + ‘<code class="Li">^</code>’, and unary + ‘<code class="Li">&</code>’. Special rules in + <code class="Nm">ddb</code> are:</p> +<dl class="Bl-tag"> + <dt>Identifiers</dt> + <dd>The name of a symbol is translated to the value of the symbol, which is + the address of the corresponding object. + ‘<code class="Li">.</code>’ and + ‘<code class="Li">:</code>’ can be used in the identifier. + If supported by an object format dependent routine, + [<var class="Ar">filename</var>:]<var class="Ar">func</var>:<var class="Ar">lineno</var>, + [<var class="Ar">filename</var>:]<var class="Ar">variable</var>, and + [<var class="Ar">filename</var>:]<var class="Ar">lineno</var> can be + accepted as a symbol.</dd> + <dt>Numbers</dt> + <dd>Radix is determined by the first two letters: + ‘<code class="Li">0x</code>’: hex, + ‘<code class="Li">0o</code>’: octal, + ‘<code class="Li">0t</code>’: decimal; otherwise, follow + current radix.</dd> + <dt id="."><a class="permalink" href="#."><code class="Li">.</code></a></dt> + <dd><var class="Va">dot</var></dd> + <dt id="+"><a class="permalink" href="#+"><code class="Li">+</code></a></dt> + <dd><var class="Va">next</var></dd> + <dt id=".."><a class="permalink" href="#.."><code class="Li">..</code></a></dt> + <dd>address of the start of the last line examined. Unlike + <var class="Va">dot</var> or <var class="Va">next</var>, this is only + changed by <code class="Ic">examine</code> or + <code class="Ic">write</code> command.</dd> + <dt id="'"><a class="permalink" href="#'"><code class="Li">'</code></a></dt> + <dd>last address explicitly specified.</dd> + <dt id="$"><a class="permalink" href="#$"><code class="Li">$</code></a><var class="Ar">variable</var></dt> + <dd>Translated to the value of the specified variable. It may be followed by a + ‘<code class="Li">:</code>’ and modifiers as described + above.</dd> + <dt><var class="Ar">a</var><code class="Li">#</code><var class="Ar">b</var></dt> + <dd>A binary operator which rounds up the left hand side to the next multiple + of right hand side.</dd> + <dt id="*"><a class="permalink" href="#*"><code class="Li">*</code></a><var class="Ar">expr</var></dt> + <dd>Indirection. It may be followed by a + ‘<code class="Li">:</code>’ and modifiers as described + above.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SCRIPTING"><a class="permalink" href="#SCRIPTING">SCRIPTING</a></h1> +<p class="Pp"><code class="Nm">ddb</code> supports a basic scripting facility to + allow automating tasks or responses to specific events. Each script consists + of a list of DDB commands to be executed sequentially, and is assigned a + unique name. Certain script names have special meaning, and will be + automatically run on various <code class="Nm">ddb</code> events if scripts + by those names have been defined.</p> +<p class="Pp">The <code class="Ic">script</code> command may be used to define a + script by name. Scripts consist of a series of <code class="Nm">ddb</code> + commands separated with the ‘<code class="Li">;</code>’ + character. For example:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>script kdb.enter.panic=bt; show pcpu +script lockinfo=show alllocks; show lockedvnods</pre> +</div> +<p class="Pp">The <code class="Ic">scripts</code> command lists currently + defined scripts.</p> +<p class="Pp">The <code class="Ic">run</code> command execute a script by name. + For example:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>run lockinfo</pre> +</div> +<p class="Pp">The <code class="Ic">unscript</code> command may be used to delete + a script by name. For example:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>unscript kdb.enter.panic</pre> +</div> +<p class="Pp">These functions may also be performed from userspace using the + <a class="Xr">ddb(8)</a> command.</p> +<p class="Pp">Certain scripts are run automatically, if defined, for specific + <code class="Nm">ddb</code> events. The follow scripts are run when various + events occur:</p> +<dl class="Bl-tag"> + <dt id="kdb.enter.acpi"><var class="Va">kdb.enter.acpi</var></dt> + <dd>The kernel debugger was entered as a result of an + <a class="Xr">acpi(4)</a> event.</dd> + <dt id="kdb.enter.bootflags"><var class="Va">kdb.enter.bootflags</var></dt> + <dd>The kernel debugger was entered at boot as a result of the debugger boot + flag being set.</dd> + <dt id="kdb.enter.break"><var class="Va">kdb.enter.break</var></dt> + <dd>The kernel debugger was entered as a result of a serial or console + break.</dd> + <dt id="kdb.enter.cam"><var class="Va">kdb.enter.cam</var></dt> + <dd>The kernel debugger was entered as a result of a <a class="Xr">CAM(4)</a> + event.</dd> + <dt id="kdb.enter.mac"><var class="Va">kdb.enter.mac</var></dt> + <dd>The kernel debugger was entered as a result of an assertion failure in the + <a class="Xr">mac_test(4)</a> module of the TrustedBSD MAC Framework.</dd> + <dt id="kdb.enter.netgraph"><var class="Va">kdb.enter.netgraph</var></dt> + <dd>The kernel debugger was entered as a result of a + <a class="Xr">netgraph(4)</a> event.</dd> + <dt id="kdb.enter.panic"><var class="Va">kdb.enter.panic</var></dt> + <dd><a class="Xr">panic(9)</a> was called.</dd> + <dt id="kdb.enter.powerpc"><var class="Va">kdb.enter.powerpc</var></dt> + <dd>The kernel debugger was entered as a result of an unimplemented interrupt + type on the powerpc platform.</dd> + <dt id="kdb.enter.sysctl"><var class="Va">kdb.enter.sysctl</var></dt> + <dd>The kernel debugger was entered as a result of the + <var class="Va">debug.kdb.enter</var> sysctl being set.</dd> + <dt id="kdb.enter.unionfs"><var class="Va">kdb.enter.unionfs</var></dt> + <dd>The kernel debugger was entered as a result of an assertion failure in the + union file system.</dd> + <dt id="kdb.enter.unknown"><var class="Va">kdb.enter.unknown</var></dt> + <dd>The kernel debugger was entered, but no reason has been set.</dd> + <dt id="kdb.enter.vfslock"><var class="Va">kdb.enter.vfslock</var></dt> + <dd>The kernel debugger was entered as a result of a VFS lock violation.</dd> + <dt id="kdb.enter.watchdog"><var class="Va">kdb.enter.watchdog</var></dt> + <dd>The kernel debugger was entered as a result of a watchdog firing.</dd> + <dt id="kdb.enter.witness"><var class="Va">kdb.enter.witness</var></dt> + <dd>The kernel debugger was entered as a result of a + <a class="Xr">witness(4)</a> violation.</dd> +</dl> +<p class="Pp">In the event that none of these scripts is found, + <code class="Nm">ddb</code> will attempt to execute a default script:</p> +<dl class="Bl-tag"> + <dt id="kdb.enter.default"><var class="Va">kdb.enter.default</var></dt> + <dd>The kernel debugger was entered, but a script exactly matching the reason + for entering was not defined. This can be used as a catch-all to handle + cases not specifically of interest; for example, + <var class="Va">kdb.enter.witness</var> might be defined to have special + handling, and <var class="Va">kdb.enter.default</var> might be defined to + simply panic and reboot.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="HINTS"><a class="permalink" href="#HINTS">HINTS</a></h1> +<p class="Pp">On machines with an ISA expansion bus, a simple NMI generation + card can be constructed by connecting a push button between the A01 and B01 + (CHCHK# and GND) card fingers. Momentarily shorting these two fingers + together may cause the bridge chipset to generate an NMI, which causes the + kernel to pass control to <code class="Nm">ddb</code>. Some bridge chipsets + do not generate a NMI on CHCHK#, so your mileage may vary. The NMI allows + one to break into the debugger on a wedged machine to diagnose problems. + Other bus' bridge chipsets may be able to generate NMI using bus specific + methods. There are many PCI and PCIe add-in cards which can generate NMI for + debugging. Modern server systems typically use IPMI to generate signals to + enter the debugger. The <var class="Va">devel/ipmitool</var> port can be + used to send the <code class="Cd">chassis power diag</code> command which + delivers an NMI to the processor. Embedded systems often use JTAG for + debugging, but rarely use it in combination with + <code class="Nm">ddb</code>.</p> +<p class="Pp">Serial consoles can break to the debugger by sending a BREAK + condition on the serial line. This requires a kernel built with + <code class="Cd">options BREAK_TO_DEBUGGER</code> is specified in the + kernel. Most terminal emulation programs can send a break sequence with a + special key sequence or menu selection. Sending the break can be difficult + or even happen spuriously in some setups. An alternative method is to build + a kernel with <code class="Cd">options ALT_BREAK_TO_DEBUGGER</code> then the + sequence of CR TILDE CTRL-B enters the debugger; CR TILDE CTRL-P causes a + panic; and CR TILDE CTRL-R causes an immediate reboot. In all these + sequences, CR represents Carriage Return and is usually sent by pressing the + Enter or Return key. TILDE is the ASCII tilde character (~). CTRL-x is + Control x, sent by pressing the Control key, then x, then releasing + both.</p> +<p class="Pp">The break-to-debugger behavior can be enabled by setting + <a class="Xr">sysctl(8)</a> + <var class="Va">debug.kdb.break_to_debugger</var> to 1. The + alt-break-to-debugger behavior can be enabled by setting + <a class="Xr">sysctl(8)</a> + <var class="Va">debug.kdb.alt_break_to_debugger</var> to 1. The debugger can + be entered by setting <a class="Xr">sysctl(8)</a> + <var class="Va">debug.kdb.enter</var> to 1.</p> +<p class="Pp">Output can be interrupted, paused, and resumed with the control + characters CTRL-C, CTRL-S, and CTRL-Q. Because these control characters are + received as in-band data from the console, there is an input buffer, and + once that buffer fills <code class="Nm">ddb</code> must either stop + responding to control characters or drop additional input while continuing + to search for control characters. This behavior is controlled by the tunable + <a class="Xr">sysctl(8)</a> + <var class="Va">debug.ddb.prioritize_control_input</var>, which defaults to + 1. The input buffer size is 512 bytes.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<p class="Pp">Header files mentioned in this manual page can be found below + <span class="Pa">/usr/include</span> directory.</p> +<p class="Pp"></p> +<ul class="Bl-dash Bl-compact"> + <li><span class="Pa">sys/buf.h</span></li> + <li><span class="Pa">sys/domain.h</span></li> + <li><span class="Pa">netinet/in_pcb.h</span></li> + <li><span class="Pa">sys/socket.h</span></li> + <li><span class="Pa">sys/vnode.h</span></li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">gdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>), <a class="Xr">kgdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>), <a class="Xr">acpi(4)</a>, + <a class="Xr">CAM(4)</a>, <a class="Xr">gdb(4)</a>, + <a class="Xr">mac_ddb(4)</a>, <a class="Xr">mac_test(4)</a>, + <a class="Xr">netgraph(4)</a>, <a class="Xr">textdump(4)</a>, + <a class="Xr">witness(4)</a>, <a class="Xr">ddb(8)</a>, + <a class="Xr">sysctl(8)</a>, <a class="Xr">panic(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ddb</code> debugger was developed for Mach, + and ported to <span class="Ux">386BSD-0.1</span>. This manual page + translated from <a class="Xr">man(7)</a> macros by <span class="An">Garrett + Wollman</span>.</p> +<p class="Pp"><span class="An">Robert N. M. Watson</span> added support for + <code class="Nm">ddb</code> output capture, <a class="Xr">textdump(4)</a> + and scripting in <span class="Ux">FreeBSD 7.1</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 31, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |