path: root/static/freebsd/man4/gdb.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">GDB(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">GDB(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">gdb</code> &#x2014; <span class="Nd">external
    kernel debugger</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">makeoptions DEBUG=-g</code>
  <br/>
  <code class="Cd">options DDB</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">gdb</code> kernel debugger is a variation of
    <a class="Xr">gdb(1)</a> (<span class="Pa">ports/devel/gdb</span>) which
    understands some aspects of the <span class="Ux">FreeBSD</span> kernel
    environment. It can be used in a number of ways:</p>
<ul class="Bl-bullet">
  <li>It can be used to examine the memory of the processor on which it
    runs.</li>
  <li>It can be used to analyse a processor dump after a panic.</li>
  <li>It can be used to debug another system interactively via a serial or
      firewire link. In this mode, the processor can be stopped and single
      stepped.</li>
  <li>With a firewire link, it can be used to examine the memory of a remote
      system without the participation of that system. In this mode, the
      processor cannot be stopped and single stepped, but it can be of use when
      the remote system has crashed and is no longer responding.</li>
</ul>
<p class="Pp">When used for remote debugging, <code class="Nm">gdb</code>
    requires the presence of the <a class="Xr">ddb(4)</a> kernel debugger.
    Commands exist to switch between <code class="Nm">gdb</code> and
    <a class="Xr">ddb(4)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="PREPARING_FOR_DEBUGGING"><a class="permalink" href="#PREPARING_FOR_DEBUGGING">PREPARING
  FOR DEBUGGING</a></h1>
<p class="Pp">When debugging kernels, it is practically essential to have built
    a kernel with debugging symbols (<code class="Cd">makeoptions
    DEBUG=-g</code>). It is easiest to perform operations from the kernel build
    directory, by default
  <span class="Pa">/usr/obj/usr/src/sys/GENERIC</span>.</p>
<p class="Pp">First, ensure you have a copy of the debug macros in the
    directory:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">make gdbinit</code></div>
<p class="Pp">This command performs some transformations on the macros installed
    in <span class="Pa">/usr/src/tools/debugscripts</span> to adapt them to the
    local environment.</p>
<section class="Ss">
<h2 class="Ss" id="Inspecting_the_environment_of_the_local_machine"><a class="permalink" href="#Inspecting_the_environment_of_the_local_machine">Inspecting
  the environment of the local machine</a></h2>
<p class="Pp">To look at and change the contents of the memory of the system you
    are running on,</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">gdb -k -wcore kernel.debug
  /dev/mem</code></div>
<p class="Pp">In this mode, you need the <code class="Fl">-k</code> flag to
    indicate to <a class="Xr">gdb(1)</a>
    (<span class="Pa">ports/devel/gdb</span>) that the &#x201C;dump file&#x201D;
    <span class="Pa">/dev/mem</span> is a kernel data file. You can look at live
    data, and if you include the <code class="Fl">-wcore</code> option, you can
    change it at your peril. The system does not stop (obviously), so a number
    of things will not work. You can set breakpoints, but you cannot
    &#x201C;continue&#x201D; execution, so they will not work.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Debugging_a_crash_dump"><a class="permalink" href="#Debugging_a_crash_dump">Debugging
  a crash dump</a></h2>
<p class="Pp">By default, crash dumps are stored in the directory
    <span class="Pa">/var/crash</span>. Investigate them from the kernel build
    directory with:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">gdb -k kernel.debug
  /var/crash/vmcore.29</code></div>
<p class="Pp">In this mode, the system is obviously stopped, so you can only
    look at it.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Debugging_a_live_system_with_a_remote_link"><a class="permalink" href="#Debugging_a_live_system_with_a_remote_link">Debugging
  a live system with a remote link</a></h2>
<p class="Pp">In the following discussion, the term &#x201C;local system&#x201D;
    refers to the system running the debugger, and &#x201C;remote system&#x201D;
    refers to the live system being debugged.</p>
<p class="Pp">To debug a live system with a remote link, the kernel must be
    compiled with the option <code class="Cd">options DDB</code>. The option
    <code class="Cd">options BREAK_TO_DEBUGGER</code> enables the debugging
    machine stop the debugged machine once a connection has been established by
    pressing &#x2018;<code class="Li">^C</code>&#x2019;.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Debugging_a_live_system_with_a_remote_serial_link"><a class="permalink" href="#Debugging_a_live_system_with_a_remote_serial_link">Debugging
  a live system with a remote serial link</a></h2>
<p class="Pp">When using a serial port for the remote link on the i386 platform,
    the serial port must be identified by setting the flag bit
    <code class="Li">0x80</code> for the specified interface. Generally, this
    port will also be used as a serial console (flag bit
    <code class="Li">0x10</code>), so the entry in
    <span class="Pa">/boot/device.hints</span> should be:</p>
<p class="Pp"></p>
<div class="Bd
  Bd-indent"><code class="Li">hint.sio.0.flags=&quot;0x90&quot;</code></div>
</section>
<section class="Ss">
<h2 class="Ss" id="Debugging_a_live_system_with_a_remote_firewire_link"><a class="permalink" href="#Debugging_a_live_system_with_a_remote_firewire_link">Debugging
  a live system with a remote firewire link</a></h2>
<p class="Pp">As with serial debugging, to debug a live system with a firewire
    link, the kernel must be compiled with the option <code class="Cd">options
    DDB</code>.</p>
<p class="Pp">A number of steps must be performed to set up a firewire link:</p>
<ul class="Bl-bullet">
  <li>Ensure that both systems have <a class="Xr">firewire(4)</a> support, and
      that the kernel of the remote system includes the
      <a class="Xr">dcons(4)</a> and <a class="Xr">dcons_crom(4)</a> drivers. If
      they are not compiled into the kernel, load the KLDs:
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">kldload firewire</code></div>
    <p class="Pp">On the remote system only:</p>
    <div class="Bd Pp Bd-indent Li">
    <pre>kldload dcons
kldload dcons_crom</pre>
    </div>
    <p class="Pp">You should see something like this in the
        <a class="Xr">dmesg(8)</a> output of the remote system:</p>
    <div class="Bd Pp Bd-indent Li">
    <pre>fwohci0: BUS reset
fwohci0: node_id=0x8800ffc0, gen=2, non CYCLEMASTER mode
firewire0: 2 nodes, maxhop &lt;= 1, cable IRM = 1
firewire0: bus manager 1
firewire0: New S400 device ID:00c04f3226e88061
dcons_crom0: &lt;dcons configuration ROM&gt; on firewire0
dcons_crom0: bus_addr 0x22a000</pre>
    </div>
    <p class="Pp">It is a good idea to load these modules at boot time with the
        following entry in <span class="Pa">/boot/loader.conf</span>:</p>
    <p class="Pp"></p>
    <div class="Bd
      Bd-indent"><code class="Li">dcons_crom_enable=&quot;YES&quot;</code></div>
    <p class="Pp">This ensures that all three modules are loaded. There is no
        harm in loading <a class="Xr">dcons(4)</a> and
        <a class="Xr">dcons_crom(4)</a> on the local system, but if you only
        want to load the <a class="Xr">firewire(4)</a> module, include the
        following in <span class="Pa">/boot/loader.conf</span>:</p>
    <p class="Pp"></p>
    <div class="Bd
      Bd-indent"><code class="Li">firewire_enable=&quot;YES&quot;</code></div>
  </li>
  <li>Next, use <a class="Xr">fwcontrol(8)</a> to find the firewire node
      corresponding to the remote machine. On the local machine you might see:
    <div class="Bd Pp Bd-indent Li">
    <pre># fwcontrol
2 devices (info_len=2)
node        EUI64        status
   1  0x00c04f3226e88061      0
   0  0x000199000003622b      1</pre>
    </div>
    <p class="Pp">The first node is always the local system, so in this case,
        node 0 is the remote system. If there are more than two systems, check
        from the other end to find which node corresponds to the remote system.
        On the remote machine, it looks like this:</p>
    <div class="Bd Pp Bd-indent Li">
    <pre># fwcontrol
2 devices (info_len=2)
node        EUI64        status
   0  0x000199000003622b      0
   1  0x00c04f3226e88061      1</pre>
    </div>
  </li>
  <li>Next, establish a firewire connection with <a class="Xr">dconschat(8)</a>:
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">dconschat -br -G 5556 -t
      0x000199000003622b</code></div>
    <p class="Pp"><code class="Li">0x000199000003622b</code> is the EUI64
        address of the remote node, as determined from the output of
        <a class="Xr">fwcontrol(8)</a> above. When started in this manner,
        <a class="Xr">dconschat(8)</a> establishes a local tunnel connection
        from port <code class="Li">localhost:5556</code> to the remote debugger.
        You can also establish a console port connection with the
        <code class="Fl">-C</code> option to the same invocation
        <a class="Xr">dconschat(8)</a>. See the <a class="Xr">dconschat(8)</a>
        manpage for further details.</p>
    <p class="Pp">The <a class="Xr">dconschat(8)</a> utility does not return
        control to the user. It displays error messages and console output for
        the remote system, so it is a good idea to start it in its own
      window.</p>
  </li>
  <li>Finally, establish connection:
    <div class="Bd Pp Bd-indent Li">
    <pre># gdb kernel.debug
GNU gdb 5.2.1 (FreeBSD)
<a class="permalink" href="#(political"><i class="Em" id="(political">(political statements omitted)</i></a>
Ready to go.  Enter 'tr' to connect to the remote target
with /dev/cuau0, 'tr /dev/cuau1' to connect to a different port
or 'trf portno' to connect to the remote target with the firewire
interface.  portno defaults to 5556.

Type 'getsyms' after connection to load kld symbols.

If you are debugging a local system, you can use 'kldsyms' instead
to load the kld symbols.  That is a less obnoxious interface.
(gdb) trf
0xc21bd378 in ?? ()</pre>
    </div>
    <p class="Pp">The <code class="Ic">trf</code> macro assumes a connection on
        port 5556. If you want to use a different port (by changing the
        invocation of <a class="Xr">dconschat(8)</a> above), use the
        <code class="Ic">tr</code> macro instead. For example, if you want to
        use port 4711, run <a class="Xr">dconschat(8)</a> like this:</p>
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">dconschat -br -G 4711 -t
      0x000199000003622b</code></div>
    <p class="Pp">Then establish connection with:</p>
    <div class="Bd Pp Bd-indent Li">
    <pre>(gdb) tr localhost:4711
0xc21bd378 in ?? ()</pre>
    </div>
  </li>
</ul>
</section>
<section class="Ss">
<h2 class="Ss" id="Non-cooperative_debugging_a_live_system_with_a_remote_firewire_link"><a class="permalink" href="#Non-cooperative_debugging_a_live_system_with_a_remote_firewire_link">Non-cooperative
  debugging a live system with a remote firewire link</a></h2>
<p class="Pp">In addition to the conventional debugging via firewire described
    in the previous section, it is possible to debug a remote system without its
    cooperation, once an initial connection has been established. This
    corresponds to debugging a local machine using
    <span class="Pa">/dev/mem</span>. It can be very useful if a system crashes
    and the debugger no longer responds. To use this method, set the
    <a class="Xr">sysctl(8)</a> variables
    <var class="Va">hw.firewire.fwmem.eui64_hi</var> and
    <var class="Va">hw.firewire.fwmem.eui64_lo</var> to the upper and lower
    halves of the EUI64 ID of the remote system, respectively. From the previous
    example, the remote machine shows:</p>
<div class="Bd Pp Bd-indent Li">
<pre># fwcontrol
2 devices (info_len=2)
node        EUI64        status
   0  0x000199000003622b      0
   1  0x00c04f3226e88061      1</pre>
</div>
<p class="Pp">Enter:</p>
<div class="Bd Pp Bd-indent Li">
<pre># sysctl -w hw.firewire.fwmem.eui64_hi=0x00019900
hw.firewire.fwmem.eui64_hi: 0 -&gt; 104704
# sysctl -w hw.firewire.fwmem.eui64_lo=0x0003622b
hw.firewire.fwmem.eui64_lo: 0 -&gt; 221739</pre>
</div>
<p class="Pp">Note that the variables must be explicitly stated in hexadecimal.
    After this, you can examine the remote machine's state with the following
    input:</p>
<div class="Bd Pp Bd-indent Li">
<pre># gdb -k kernel.debug /dev/fwmem0.0
GNU gdb 5.2.1 (FreeBSD)
<a class="permalink" href="#(messages"><i class="Em" id="(messages">(messages omitted)</i></a>
Reading symbols from /boot/kernel/dcons.ko...done.
Loaded symbols for /boot/kernel/dcons.ko
Reading symbols from /boot/kernel/dcons_crom.ko...done.
Loaded symbols for /boot/kernel/dcons_crom.ko
#0  sched_switch (td=0xc0922fe0) at /usr/src/sys/kern/sched_4bsd.c:621
0xc21bd378 in ?? ()</pre>
</div>
<p class="Pp">In this case, it is not necessary to load the symbols explicitly.
    The remote system continues to run.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="COMMANDS"><a class="permalink" href="#COMMANDS">COMMANDS</a></h1>
<p class="Pp">The user interface to <code class="Nm">gdb</code> is via
    <a class="Xr">gdb(1)</a> (<span class="Pa">ports/devel/gdb</span>), so
    <a class="Xr">gdb(1)</a> (<span class="Pa">ports/devel/gdb</span>) commands
    also work. This section discusses only the extensions for kernel debugging
    that get installed in the kernel build directory.</p>
<section class="Ss">
<h2 class="Ss" id="Debugging_environment"><a class="permalink" href="#Debugging_environment">Debugging
  environment</a></h2>
<p class="Pp">The following macros manipulate the debugging environment:</p>
<dl class="Bl-tag">
  <dt id="ddb"><a class="permalink" href="#ddb"><code class="Ic">ddb</code></a></dt>
  <dd>Switch back to <a class="Xr">ddb(4)</a>. This command is only meaningful
      when performing remote debugging.</dd>
  <dt id="getsyms"><a class="permalink" href="#getsyms"><code class="Ic">getsyms</code></a></dt>
  <dd>Display <code class="Ic">kldstat</code> information for the target machine
      and invite user to paste it back in. This is required because
      <code class="Nm">gdb</code> does not allow data to be passed to shell
      scripts. It is necessary for remote debugging and crash dumps; for local
      memory debugging use <code class="Ic">kldsyms</code> instead.</dd>
  <dt id="kldsyms"><a class="permalink" href="#kldsyms"><code class="Ic">kldsyms</code></a></dt>
  <dd>Read in the symbol tables for the debugging machine. This does not work
      for remote debugging and crash dumps; use <code class="Ic">getsyms</code>
      instead.</dd>
  <dt id="tr"><a class="permalink" href="#tr"><code class="Ic">tr</code></a>
    <var class="Ar">interface</var></dt>
  <dd>Debug a remote system via the specified serial or firewire interface.</dd>
  <dt id="tr0"><a class="permalink" href="#tr0"><code class="Ic">tr0</code></a></dt>
  <dd>Debug a remote system via serial interface
      <span class="Pa">/dev/cuau0</span>.</dd>
  <dt id="tr1"><a class="permalink" href="#tr1"><code class="Ic">tr1</code></a></dt>
  <dd>Debug a remote system via serial interface
      <span class="Pa">/dev/cuau1</span>.</dd>
  <dt id="trf"><a class="permalink" href="#trf"><code class="Ic">trf</code></a></dt>
  <dd>Debug a remote system via firewire interface at default port 5556.</dd>
</dl>
<p class="Pp">The commands <code class="Ic">tr0</code>,
    <code class="Ic">tr1</code> and <code class="Ic">trf</code> are convenience
    commands which invoke <code class="Ic">tr</code>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="The_current_process_environment"><a class="permalink" href="#The_current_process_environment">The
  current process environment</a></h2>
<p class="Pp">The following macros are convenience functions intended to make
    things easier than the standard <a class="Xr">gdb(1)</a>
    (<span class="Pa">ports/devel/gdb</span>) commands.</p>
<dl class="Bl-tag">
  <dt id="f0"><a class="permalink" href="#f0"><code class="Ic">f0</code></a></dt>
  <dd>Select stack frame 0 and show assembler-level details.</dd>
  <dt id="f1"><a class="permalink" href="#f1"><code class="Ic">f1</code></a></dt>
  <dd>Select stack frame 1 and show assembler-level details.</dd>
  <dt id="f2"><a class="permalink" href="#f2"><code class="Ic">f2</code></a></dt>
  <dd>Select stack frame 2 and show assembler-level details.</dd>
  <dt id="f3"><a class="permalink" href="#f3"><code class="Ic">f3</code></a></dt>
  <dd>Select stack frame 3 and show assembler-level details.</dd>
  <dt id="f4"><a class="permalink" href="#f4"><code class="Ic">f4</code></a></dt>
  <dd>Select stack frame 4 and show assembler-level details.</dd>
  <dt id="f5"><a class="permalink" href="#f5"><code class="Ic">f5</code></a></dt>
  <dd>Select stack frame 5 and show assembler-level details.</dd>
  <dt id="xb"><a class="permalink" href="#xb"><code class="Ic">xb</code></a></dt>
  <dd>Show 12 words in hex, starting at current <var class="Va">ebp</var>
    value.</dd>
  <dt id="xi"><a class="permalink" href="#xi"><code class="Ic">xi</code></a></dt>
  <dd>List the next 10 instructions from the current <var class="Va">eip</var>
      value.</dd>
  <dt id="xp"><a class="permalink" href="#xp"><code class="Ic">xp</code></a></dt>
  <dd>Show the register contents and the first four parameters of the current
      stack frame.</dd>
  <dt id="xp0"><a class="permalink" href="#xp0"><code class="Ic">xp0</code></a></dt>
  <dd>Show the first parameter of current stack frame in various formats.</dd>
  <dt id="xp1"><a class="permalink" href="#xp1"><code class="Ic">xp1</code></a></dt>
  <dd>Show the second parameter of current stack frame in various formats.</dd>
  <dt id="xp2"><a class="permalink" href="#xp2"><code class="Ic">xp2</code></a></dt>
  <dd>Show the third parameter of current stack frame in various formats.</dd>
  <dt id="xp3"><a class="permalink" href="#xp3"><code class="Ic">xp3</code></a></dt>
  <dd>Show the fourth parameter of current stack frame in various formats.</dd>
  <dt id="xp4"><a class="permalink" href="#xp4"><code class="Ic">xp4</code></a></dt>
  <dd>Show the fifth parameter of current stack frame in various formats.</dd>
  <dt id="xs"><a class="permalink" href="#xs"><code class="Ic">xs</code></a></dt>
  <dd>Show the last 12 words on stack in hexadecimal.</dd>
  <dt id="xxp"><a class="permalink" href="#xxp"><code class="Ic">xxp</code></a></dt>
  <dd>Show the register contents and the first ten parameters.</dd>
  <dt id="z"><a class="permalink" href="#z"><code class="Ic">z</code></a></dt>
  <dd>Single step 1 instruction (over calls) and show next instruction.</dd>
  <dt id="zs"><a class="permalink" href="#zs"><code class="Ic">zs</code></a></dt>
  <dd>Single step 1 instruction (through calls) and show next instruction.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Examining_other_processes"><a class="permalink" href="#Examining_other_processes">Examining
  other processes</a></h2>
<p class="Pp">The following macros access other processes. The
    <code class="Nm">gdb</code> debugger does not understand the concept of
    multiple processes, so they effectively bypass the entire
    <code class="Nm">gdb</code> environment.</p>
<dl class="Bl-tag">
  <dt id="btp"><a class="permalink" href="#btp"><code class="Ic">btp</code></a>
    <var class="Ar">pid</var></dt>
  <dd>Show a backtrace for the process <var class="Ar">pid</var>.</dd>
  <dt id="btpa"><a class="permalink" href="#btpa"><code class="Ic">btpa</code></a></dt>
  <dd>Show backtraces for all processes in the system.</dd>
  <dt id="btpp"><a class="permalink" href="#btpp"><code class="Ic">btpp</code></a></dt>
  <dd>Show a backtrace for the process previously selected with
      <code class="Ic">defproc</code>.</dd>
  <dt id="btr"><a class="permalink" href="#btr"><code class="Ic">btr</code></a>
    <var class="Ar">ebp</var></dt>
  <dd>Show a backtrace from the <var class="Ar">ebp</var> address
    specified.</dd>
  <dt id="defproc"><a class="permalink" href="#defproc"><code class="Ic">defproc</code></a>
    <var class="Ar">pid</var></dt>
  <dd>Specify the PID of the process for some other commands in this
    section.</dd>
  <dt id="fr"><a class="permalink" href="#fr"><code class="Ic">fr</code></a>
    <var class="Ar">frame</var></dt>
  <dd>Show frame <var class="Ar">frame</var> of the stack of the process
      previously selected with <code class="Ic">defproc</code>.</dd>
  <dt id="pcb"><a class="permalink" href="#pcb"><code class="Ic">pcb</code></a>
    <var class="Ar">proc</var></dt>
  <dd>Show some PCB contents of the process <var class="Ar">proc</var>.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Examining_data_structures"><a class="permalink" href="#Examining_data_structures">Examining
  data structures</a></h2>
<p class="Pp">You can use standard <a class="Xr">gdb(1)</a>
    (<span class="Pa">ports/devel/gdb</span>) commands to look at most data
    structures. The macros in this section are convenience functions which
    typically display the data in a more readable format, or which omit less
    interesting parts of the structure.</p>
<dl class="Bl-tag">
  <dt id="bp"><a class="permalink" href="#bp"><code class="Ic">bp</code></a></dt>
  <dd>Show information about the buffer header pointed to by the variable
      <var class="Va">bp</var> in the current frame.</dd>
  <dt id="bpd"><a class="permalink" href="#bpd"><code class="Ic">bpd</code></a></dt>
  <dd>Show the contents (<var class="Vt">char *</var>) of
      <var class="Va">bp-&gt;data</var> in the current frame.</dd>
  <dt id="bpl"><a class="permalink" href="#bpl"><code class="Ic">bpl</code></a></dt>
  <dd>Show detailed information about the buffer header (<var class="Vt">struct
      bp</var>) pointed at by the local variable <var class="Va">bp</var>.</dd>
  <dt id="bpp"><a class="permalink" href="#bpp"><code class="Ic">bpp</code></a>
    <var class="Ar">bp</var></dt>
  <dd>Show summary information about the buffer header (<var class="Vt">struct
      bp</var>) pointed at by the parameter <var class="Ar">bp</var>.</dd>
  <dt id="bx"><a class="permalink" href="#bx"><code class="Ic">bx</code></a></dt>
  <dd>Print a number of fields from the buffer header pointed at in by the
      pointer <var class="Ar">bp</var> in the current environment.</dd>
  <dt id="vdev"><a class="permalink" href="#vdev"><code class="Ic">vdev</code></a></dt>
  <dd>Show some information of the <var class="Vt">vnode</var> pointed to by the
      local variable <var class="Va">vp</var>.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Miscellaneous_macros"><a class="permalink" href="#Miscellaneous_macros">Miscellaneous
  macros</a></h2>
<dl class="Bl-tag">
  <dt id="checkmem"><a class="permalink" href="#checkmem"><code class="Ic">checkmem</code></a></dt>
  <dd>Check unallocated memory for modifications. This assumes that the kernel
      has been compiled with <code class="Cd">options DIAGNOSTIC</code>. This
      causes the contents of free memory to be set to
      <code class="Li">0xdeadc0de</code>.</dd>
  <dt id="dmesg"><a class="permalink" href="#dmesg"><code class="Ic">dmesg</code></a></dt>
  <dd>Print the system message buffer. This corresponds to the
      <a class="Xr">dmesg(8)</a> utility. This macro used to be called
      <code class="Ic">msgbuf</code>. It can take a very long time over a serial
      line, and it is even slower via firewire or local memory due to
      inefficiencies in <code class="Nm">gdb</code>. When debugging a crash dump
      or over firewire, it is not necessary to start <code class="Nm">gdb</code>
      to access the message buffer: instead, use an appropriate variation of
    <div class="Bd Pp Bd-indent Li">
    <pre>dmesg -M /var/crash/vmcore.0 -N kernel.debug
dmesg -M /dev/fwmem0.0 -N kernel.debug</pre>
    </div>
  </dd>
  <dt id="kldstat"><a class="permalink" href="#kldstat"><code class="Ic">kldstat</code></a></dt>
  <dd>Equivalent of the <a class="Xr">kldstat(8)</a> utility without
    options.</dd>
  <dt id="pname"><a class="permalink" href="#pname"><code class="Ic">pname</code></a></dt>
  <dd>Print the command name of the current process.</dd>
  <dt id="ps"><a class="permalink" href="#ps"><code class="Ic">ps</code></a></dt>
  <dd>Show process status. This corresponds in concept, but not in appearance,
      to the <a class="Xr">ps(1)</a> utility. When debugging a crash dump or
      over firewire, it is not necessary to start <code class="Nm">gdb</code> to
      display the <a class="Xr">ps(1)</a> output: instead, use an appropriate
      variation of
    <div class="Bd Pp Bd-indent Li">
    <pre>ps -M /var/crash/vmcore.0 -N kernel.debug
ps -M /dev/fwmem0.0 -N kernel.debug</pre>
    </div>
  </dd>
  <dt id="y"><a class="permalink" href="#y"><code class="Ic">y</code></a></dt>
  <dd>Kludge for writing macros. When writing macros, it is convenient to paste
      them back into the <code class="Nm">gdb</code> window. Unfortunately, if
      the macro is already defined, <code class="Nm">gdb</code> insists on
      asking
    <p class="Pp"></p>
    <div class="Bd Bd-indent"><code class="Li">Redefine foo?</code></div>
    <p class="Pp">It will not give up until you answer
        &#x2018;<code class="Li">y</code>&#x2019;. This command is that answer.
        It does nothing else except to print a warning message to remind you to
        remove it again.</p>
  </dd>
</dl>
</section>
</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">ps(1)</a>,
    <a class="Xr">ddb(4)</a>, <a class="Xr">firewire(4)</a>,
    <a class="Xr">dconschat(8)</a>, <a class="Xr">dmesg(8)</a>,
    <a class="Xr">fwcontrol(8)</a>, <a class="Xr">kldload(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This man page was written by <span class="An">Greg Lehey</span>
    &lt;<a class="Mt" href="mailto:grog@FreeBSD.org">grog@FreeBSD.org</a>&gt;.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">The <a class="Xr">gdb(1)</a>
    (<span class="Pa">ports/devel/gdb</span>) debugger was never designed to
    debug kernels, and it is not a very good match. Many problems exist.</p>
<p class="Pp">The <code class="Nm">gdb</code> implementation is very
    inefficient, and many operations are slow.</p>
<p class="Pp">Serial debugging is even slower, and race conditions can make it
    difficult to run the link at more than 9600 bps. Firewire connections do not
    have this problem.</p>
<p class="Pp">The debugging macros &#x201C;just grew.&#x201D; In general, the
    person who wrote them did so while looking for a specific problem, so they
    may not be general enough, and they may behave badly when used in ways for
    which they were not intended, even if those ways make sense.</p>
<p class="Pp">Many of these commands only work on the ia32 architecture.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">May 17, 2016</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>