doc/gdb/Separate-Debug-Files.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Separate Debug Files</title>

<meta name="description" content="Debugging with GDB: Separate Debug Files">
<meta name="keywords" content="Debugging with GDB: Separate Debug Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="GDB-Files.html#GDB-Files" rel="up" title="GDB Files">
<link href="MiniDebugInfo.html#MiniDebugInfo" rel="next" title="MiniDebugInfo">
<link href="File-Caching.html#File-Caching" rel="previous" title="File Caching">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Separate-Debug-Files"></a>
<div class="header">
<p>
Next: <a href="MiniDebugInfo.html#MiniDebugInfo" accesskey="n" rel="next">MiniDebugInfo</a>, Previous: <a href="File-Caching.html#File-Caching" accesskey="p" rel="previous">File Caching</a>, Up: <a href="GDB-Files.html#GDB-Files" accesskey="u" rel="up">GDB Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Debugging-Information-in-Separate-Files"></a>
<h3 class="section">18.3 Debugging Information in Separate Files</h3>
<a name="index-separate-debugging-information-files"></a>
<a name="index-debugging-information-in-separate-files"></a>
<a name="index-_002edebug-subdirectories"></a>
<a name="index-debugging-information-directory_002c-global"></a>
<a name="index-global-debugging-information-directories"></a>
<a name="index-build-ID_002c-and-separate-debugging-files"></a>
<a name="index-_002ebuild_002did-directory"></a>

<p><small>GDB</small> allows you to put a program&rsquo;s debugging information in a
file separate from the executable itself, in a way that allows
<small>GDB</small> to find and load the debugging information automatically.
Since debugging information can be very large&mdash;sometimes larger
than the executable code itself&mdash;some systems distribute debugging
information for their executables in separate files, which users can
install only when they need to debug a problem.
</p>
<p><small>GDB</small> supports two ways of specifying the separate debug info
file:
</p>
<ul>
<li> The executable contains a <em>debug link</em> that specifies the name of
the separate debug info file.  The separate debug file&rsquo;s name is
usually <samp><var>executable</var>.debug</samp>, where <var>executable</var> is the
name of the corresponding executable file without leading directories
(e.g., <samp>ls.debug</samp> for <samp>/usr/bin/ls</samp>).  In addition, the
debug link specifies a 32-bit <em>Cyclic Redundancy Check</em> (CRC)
checksum for the debug file, which <small>GDB</small> uses to validate that
the executable and the debug file came from the same build.

</li><li> <a name="build-ID"></a>The executable contains a <em>build ID</em>, a unique bit string that is
also present in the corresponding debug info file.  (This is supported
only on some operating systems, when using the ELF or PE file formats
for binary files and the <small>GNU</small> Binutils.)  For more details about
this feature, see the description of the <samp>--build-id</samp>
command-line option in <a href="http://sourceware.org/binutils/docs/ld/Options.html#Options">Command Line Options</a> in <cite>The GNU Linker</cite>.  The debug info file&rsquo;s name is not specified
explicitly by the build ID, but can be computed from the build ID, see
below.
</li></ul>

<p>Depending on the way the debug info file is specified, <small>GDB</small>
uses two different methods of looking for the debug file:
</p>
<ul>
<li> For the &ldquo;debug link&rdquo; method, <small>GDB</small> looks up the named file in
the directory of the executable file, then in a subdirectory of that
directory named <samp>.debug</samp>, and finally under each one of the
global debug directories, in a subdirectory whose name is identical to
the leading directories of the executable&rsquo;s absolute file name.  (On
MS-Windows/MS-DOS, the drive letter of the executable&rsquo;s leading
directories is converted to a one-letter subdirectory, i.e.
<samp>d:/usr/bin/</samp> is converted to <samp>/d/usr/bin/</samp>, because Windows
filesystems disallow colons in file names.)

</li><li> For the &ldquo;build ID&rdquo; method, <small>GDB</small> looks in the
<samp>.build-id</samp> subdirectory of each one of the global debug directories for
a file named <samp><var>nn</var>/<var>nnnnnnnn</var>.debug</samp>, where <var>nn</var> are the
first 2 hex characters of the build ID bit string, and <var>nnnnnnnn</var>
are the rest of the bit string.  (Real build ID strings are 32 or more
hex characters, not 10.)
</li></ul>

<p>So, for example, suppose you ask <small>GDB</small> to debug
<samp>/usr/bin/ls</samp>, which has a debug link that specifies the
file <samp>ls.debug</samp>, and a build ID whose value in hex is
<code>abcdef1234</code>.  If the list of the global debug directories includes
<samp>/usr/lib/debug</samp>, then <small>GDB</small> will look for the following
debug information files, in the indicated order:
</p>
<ul class="no-bullet">
<li>- <samp>/usr/lib/debug/.build-id/ab/cdef1234.debug</samp>
</li><li>- <samp>/usr/bin/ls.debug</samp>
</li><li>- <samp>/usr/bin/.debug/ls.debug</samp>
</li><li>- <samp>/usr/lib/debug/usr/bin/ls.debug</samp>.
</li></ul>

<a name="debug_002dfile_002ddirectory"></a><p>Global debugging info directories default to what is set by <small>GDB</small>
configure option <samp>--with-separate-debug-dir</samp>.  During <small>GDB</small> run
you can also set the global debugging info directories, and view the list
<small>GDB</small> is currently using.
</p>
<dl compact="compact">
<dd>
<a name="index-set-debug_002dfile_002ddirectory"></a>
</dd>
<dt><code>set debug-file-directory <var>directories</var></code></dt>
<dd><p>Set the directories which <small>GDB</small> searches for separate debugging
information files to <var>directory</var>.  Multiple path components can be set
concatenating them by a path separator.
</p>
<a name="index-show-debug_002dfile_002ddirectory"></a>
</dd>
<dt><code>show debug-file-directory</code></dt>
<dd><p>Show the directories <small>GDB</small> searches for separate debugging
information files.
</p>
</dd>
</dl>

<a name="index-_002egnu_005fdebuglink-sections"></a>
<a name="index-debug-link-sections"></a>
<p>A debug link is a special section of the executable file named
<code>.gnu_debuglink</code>.  The section must contain:
</p>
<ul>
<li> A filename, with any leading directory components removed, followed by
a zero byte,
</li><li> zero to three bytes of padding, as needed to reach the next four-byte
boundary within the section, and
</li><li> a four-byte CRC checksum, stored in the same endianness used for the
executable file itself.  The checksum is computed on the debugging
information file&rsquo;s full contents by the function given below, passing
zero as the <var>crc</var> argument.
</li></ul>

<p>Any executable file format can carry a debug link, as long as it can
contain a section named <code>.gnu_debuglink</code> with the contents
described above.
</p>
<a name="index-_002enote_002egnu_002ebuild_002did-sections"></a>
<a name="index-build-ID-sections"></a>
<p>The build ID is a special section in the executable file (and in other
ELF binary files that <small>GDB</small> may consider).  This section is
often named <code>.note.gnu.build-id</code>, but that name is not mandatory.
It contains unique identification for the built files&mdash;the ID remains
the same across multiple builds of the same build tree.  The default
algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
content for the build ID string.  The same section with an identical
value is present in the original built binary with symbols, in its
stripped variant, and in the separate debugging information file.
</p>
<p>The debugging information file itself should be an ordinary
executable, containing a full set of linker symbols, sections, and
debugging information.  The sections of the debugging information file
should have the same names, addresses, and sizes as the original file,
but they need not contain any data&mdash;much like a <code>.bss</code> section
in an ordinary executable.
</p>
<p>The <small>GNU</small> binary utilities (Binutils) package includes the
&lsquo;<samp>objcopy</samp>&rsquo; utility that can produce
the separated executable / debugging information file pairs using the
following commands:
</p>
<div class="smallexample">
<pre class="smallexample"><kbd>objcopy --only-keep-debug foo foo.debug</kbd>
<kbd>strip -g foo</kbd>
</pre></div>

<p>These commands remove the debugging
information from the executable file <samp>foo</samp> and place it in the file
<samp>foo.debug</samp>.  You can use the first, second or both methods to link the
two files:
</p>
<ul>
<li> The debug link method needs the following additional command to also leave
behind a debug link in <samp>foo</samp>:

<div class="smallexample">
<pre class="smallexample"><kbd>objcopy --add-gnu-debuglink=foo.debug foo</kbd>
</pre></div>

<p>Ulrich Drepper&rsquo;s <samp>elfutils</samp> package, starting with version 0.53, contains
a version of the <code>strip</code> command such that the command <kbd>strip foo -f
foo.debug</kbd> has the same functionality as the two <code>objcopy</code> commands and
the <code>ln -s</code> command above, together.
</p>
</li><li> Build ID gets embedded into the main executable using <code>ld --build-id</code> or
the <small>GCC</small> counterpart <code>gcc -Wl,--build-id</code>.  Build ID support plus
compatibility fixes for debug files separation are present in <small>GNU</small> binary
utilities (Binutils) package since version 2.18.
</li></ul>


<a name="index-CRC-algorithm-definition"></a>
<p>The CRC used in <code>.gnu_debuglink</code> is the CRC-32 defined in
IEEE 802.3 using the polynomial:
</p>
<div class="display">
<pre class="display"> <em>x</em><sup>32</sup> + <em>x</em><sup>26</sup> + <em>x</em><sup>23</sup> + <em>x</em><sup>22</sup> + <em>x</em><sup>16</sup> + <em>x</em><sup>12</sup> + <em>x</em><sup>11</sup>
 + <em>x</em><sup>10</sup> + <em>x</em><sup>8</sup> + <em>x</em><sup>7</sup> + <em>x</em><sup>5</sup> + <em>x</em><sup>4</sup> + <em>x</em><sup>2</sup> + <em>x</em> + 1</pre></div>

<p>The function is computed byte at a time, taking the least
significant bit of each byte first.  The initial pattern
<code>0xffffffff</code> is used, to ensure leading zeros affect the CRC and
the final result is inverted to ensure trailing zeros also affect the
CRC.
</p>
<p><em>Note:</em> This is the same CRC polynomial as used in handling the
<em>Remote Serial Protocol</em> <code>qCRC</code> packet (see <a href="General-Query-Packets.html#qCRC-packet">qCRC packet</a>).
However in the case of the Remote Serial Protocol, the CRC is computed
<em>most</em> significant bit first, and the result is not inverted, so
trailing zeros have no effect on the CRC value.
</p>
<p>To complete the description, we show below the code of the function
which produces the CRC used in <code>.gnu_debuglink</code>.  Inverting the
initially supplied <code>crc</code> argument means that an initial call to
this function passing in zero will start computing the CRC using
<code>0xffffffff</code>.
</p>
<a name="index-gnu_005fdebuglink_005fcrc32"></a>
<div class="smallexample">
<pre class="smallexample">unsigned long
gnu_debuglink_crc32 (unsigned long crc,
                     unsigned char *buf, size_t len)
{
  static const unsigned long crc32_table[256] =
    {
      0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
      0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
      0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
      0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
      0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
      0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
      0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
      0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
      0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
      0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
      0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
      0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
      0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
      0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
      0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
      0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
      0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
      0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
      0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
      0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
      0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
      0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
      0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
      0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
      0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
      0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
      0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
      0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
      0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
      0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
      0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
      0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
      0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
      0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
      0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
      0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
      0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
      0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
      0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
      0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
      0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
      0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
      0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
      0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
      0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
      0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
      0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
      0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
      0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
      0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
      0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
      0x2d02ef8d
    };
  unsigned char *end;

  crc = ~crc &amp; 0xffffffff;
  for (end = buf + len; buf &lt; end; ++buf)
    crc = crc32_table[(crc ^ *buf) &amp; 0xff] ^ (crc &gt;&gt; 8);
  return ~crc &amp; 0xffffffff;
}
</pre></div>

<p>This computation does not apply to the &ldquo;build ID&rdquo; method.
</p>
<hr>
<div class="header">
<p>
Next: <a href="MiniDebugInfo.html#MiniDebugInfo" accesskey="n" rel="next">MiniDebugInfo</a>, Previous: <a href="File-Caching.html#File-Caching" accesskey="p" rel="previous">File Caching</a>, Up: <a href="GDB-Files.html#GDB-Files" accesskey="u" rel="up">GDB Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>