<html lang="en">
<head>
<title>Separate Debug Files - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="GDB-Files.html#GDB-Files" title="GDB Files">
<link rel="prev" href="File-Caching.html#File-Caching" title="File Caching">
<link rel="next" href="MiniDebugInfo.html#MiniDebugInfo" title="MiniDebugInfo">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 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.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Separate-Debug-Files"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="MiniDebugInfo.html#MiniDebugInfo">MiniDebugInfo</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="File-Caching.html#File-Caching">File Caching</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="GDB-Files.html#GDB-Files">GDB Files</a>
<hr>
</div>

<h3 class="section">18.3 Debugging Information in Separate Files</h3>

<p><a name="index-separate-debugging-information-files-1275"></a><a name="index-debugging-information-in-separate-files-1276"></a><a name="index-g_t_0040file_007b_002edebug_007d-subdirectories-1277"></a><a name="index-debugging-information-directory_002c-global-1278"></a><a name="index-global-debugging-information-directories-1279"></a><a name="index-build-ID_002c-and-separate-debugging-files-1280"></a><a name="index-g_t_0040file_007b_002ebuild_002did_007d-directory-1281"></a>
<span class="sc">gdb</span> allows you to put a program's debugging information in a
file separate from the executable itself, in a way that allows
<span class="sc">gdb</span> 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><span class="sc">gdb</span> supports two ways of specifying the separate debug info
file:

     <ul>
<li>The executable contains a <dfn>debug link</dfn> that specifies the name of
the separate debug info file.  The separate debug file's name is
usually <samp><var>executable</var><span class="file">.debug</span></samp>, where <var>executable</var> is the
name of the corresponding executable file without leading directories
(e.g., <samp><span class="file">ls.debug</span></samp> for <samp><span class="file">/usr/bin/ls</span></samp>).  In addition, the
debug link specifies a 32-bit <dfn>Cyclic Redundancy Check</dfn> (CRC)
checksum for the debug file, which <span class="sc">gdb</span> uses to validate that
the executable and the debug file came from the same build.

     <li>The executable contains a <dfn>build ID</dfn>, 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 <span class="sc">gnu</span> Binutils.)  For more details about
this feature, see the description of the <samp><span class="option">--build-id</span></samp>
command-line option in <a href="../ld/Options.html#Options">Command Line Options</a>.  The debug info file's name is not specified
explicitly by the build ID, but can be computed from the build ID, see
below. 
</ul>

   <p>Depending on the way the debug info file is specified, <span class="sc">gdb</span>
uses two different methods of looking for the debug file:

     <ul>
<li>For the &ldquo;debug link&rdquo; method, <span class="sc">gdb</span> looks up the named file in
the directory of the executable file, then in a subdirectory of that
directory named <samp><span class="file">.debug</span></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's absolute file name.  (On
MS-Windows/MS-DOS, the drive letter of the executable's leading
directories is converted to a one-letter subdirectory, i.e. 
<samp><span class="file">d:/usr/bin/</span></samp> is converted to <samp><span class="file">/d/usr/bin/</span></samp>, because Windows
filesystems disallow colons in file names.)

     <li>For the &ldquo;build ID&rdquo; method, <span class="sc">gdb</span> looks in the
<samp><span class="file">.build-id</span></samp> subdirectory of each one of the global debug directories for
a file named <samp><var>nn</var><span class="file">/</span><var>nnnnnnnn</var><span class="file">.debug</span></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.) 
</ul>

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

     <ul>
<li><samp><span class="file">/usr/lib/debug/.build-id/ab/cdef1234.debug</span></samp>
<li><samp><span class="file">/usr/bin/ls.debug</span></samp>
<li><samp><span class="file">/usr/bin/.debug/ls.debug</span></samp>
<li><samp><span class="file">/usr/lib/debug/usr/bin/ls.debug</span></samp>. 
</ul>

   <p><a name="debug_002dfile_002ddirectory"></a>Global debugging info directories default to what is set by <span class="sc">gdb</span>
configure option <samp><span class="option">--with-separate-debug-dir</span></samp>.  During <span class="sc">gdb</span> run
you can also set the global debugging info directories, and view the list
<span class="sc">gdb</span> is currently using.

     
<a name="index-set-debug_002dfile_002ddirectory-1282"></a>
<dl><dt><code>set debug-file-directory </code><var>directories</var><dd>Set the directories which <span class="sc">gdb</span> 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-1283"></a><br><dt><code>show debug-file-directory</code><dd>Show the directories <span class="sc">gdb</span> searches for separate debugging
information files.

   </dl>

   <p><a name="index-g_t_0040code_007b_002egnu_005fdebuglink_007d-sections-1284"></a><a name="index-debug-link-sections-1285"></a>A debug link is a special section of the executable file named
<code>.gnu_debuglink</code>.  The section must contain:

     <ul>
<li>A filename, with any leading directory components removed, followed by
a zero byte,
<li>zero to three bytes of padding, as needed to reach the next four-byte
boundary within the section, and
<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's full contents by the function given below, passing
zero as the <var>crc</var> argument. 
</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-g_t_0040code_007b_002enote_002egnu_002ebuild_002did_007d-sections-1286"></a><a name="index-build-ID-sections-1287"></a>The build ID is a special section in the executable file (and in other
ELF binary files that <span class="sc">gdb</span> 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>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>The <span class="sc">gnu</span> binary utilities (Binutils) package includes the
&lsquo;<samp><span class="samp">objcopy</span></samp>&rsquo; utility that can produce
the separated executable / debugging information file pairs using the
following commands:

<pre class="smallexample">     <kbd>objcopy --only-keep-debug foo foo.debug</kbd>
     <kbd>strip -g foo</kbd>
</pre>
   <p class="noindent">These commands remove the debugging
information from the executable file <samp><span class="file">foo</span></samp> and place it in the file
<samp><span class="file">foo.debug</span></samp>.  You can use the first, second or both methods to link the
two files:

     <ul>
<li>The debug link method needs the following additional command to also leave
behind a debug link in <samp><span class="file">foo</span></samp>:

     <pre class="smallexample">          <kbd>objcopy --add-gnu-debuglink=foo.debug foo</kbd>
</pre>
     <p>Ulrich Drepper's <samp><span class="file">elfutils</span></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.

     <li>Build ID gets embedded into the main executable using <code>ld --build-id</code> or
the <span class="sc">gcc</span> counterpart <code>gcc -Wl,--build-id</code>.  Build ID support plus
compatibility fixes for debug files separation are present in <span class="sc">gnu</span> binary
utilities (Binutils) package since version 2.18. 
</ul>

<p class="noindent"><a name="index-CRC-algorithm-definition-1288"></a>The CRC used in <code>.gnu_debuglink</code> is the CRC-32 defined in
IEEE 802.3 using the polynomial:

<!-- TexInfo requires naked braces for multi-digit exponents for Tex -->
<!-- output, but this causes HTML output to barf. HTML has to be set using -->
<!-- raw commands. So we end up having to specify this equation in 2 -->
<!-- different ways! -->
<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>
   <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><em>Note:</em> This is the same CRC polynomial as used in handling the
<dfn>Remote Serial Protocol</dfn> <code>qCRC</code> packet (see <a href="qCRC-packet.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>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-1289"></a>
<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>
   <p class="noindent">This computation does not apply to the &ldquo;build ID&rdquo; method.

   </body></html>