gdb: Separate Debug Files
18.3 Debugging Information in Separate Files
============================================
GDB allows you to put a program's debugging information in a file
separate from the executable itself, in a way that allows GDB to find
and load the debugging information automatically. Since debugging
information can be very large--sometimes larger than the executable code
itself--some systems distribute debugging information for their
executables in separate files, which users can install only when they
need to debug a problem.
GDB supports two ways of specifying the separate debug info file:
* The executable contains a "debug link" that specifies the name of
the separate debug info file. The separate debug file's name is
usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the
corresponding executable file without leading directories (e.g.,
'ls.debug' for '/usr/bin/ls'). In addition, the debug link
specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the
debug file, which GDB uses to validate that the executable and the
debug file came from the same build.
* The executable contains a "build ID", 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 GNU Binutils.) For more
details about this feature, see the description of the '--build-id'
command-line option in 
Command Line Options (ld)Options.
The debug info file's name is not specified explicitly by the build
ID, but can be computed from the build ID, see below.
Depending on the way the debug info file is specified, GDB uses two
different methods of looking for the debug file:
* For the "debug link" method, GDB looks up the named file in the
directory of the executable file, then in a subdirectory of that
directory named '.debug', 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.
'd:/usr/bin/' is converted to '/d/usr/bin/', because Windows
filesystems disallow colons in file names.)
* For the "build ID" method, GDB looks in the '.build-id'
subdirectory of each one of the global debug directories for a file
named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters
of the build ID bit string, and NNNNNNNN are the rest of the bit
string. (Real build ID strings are 32 or more hex characters, not
10.)
So, for example, suppose you ask GDB to debug '/usr/bin/ls', which
has a debug link that specifies the file 'ls.debug', and a build ID
whose value in hex is 'abcdef1234'. If the list of the global debug
directories includes '/usr/lib/debug', then GDB will look for the
following debug information files, in the indicated order:
- '/usr/lib/debug/.build-id/ab/cdef1234.debug'
- '/usr/bin/ls.debug'
- '/usr/bin/.debug/ls.debug'
- '/usr/lib/debug/usr/bin/ls.debug'.
Global debugging info directories default to what is set by GDB
configure option '--with-separate-debug-dir'. During GDB run you can
also set the global debugging info directories, and view the list GDB is
currently using.
'set debug-file-directory DIRECTORIES'
Set the directories which GDB searches for separate debugging
information files to DIRECTORY. Multiple path components can be
set concatenating them by a path separator.
'show debug-file-directory'
Show the directories GDB searches for separate debugging
information files.
You can also adjust the current verbosity of the "build id" locating.
'set build-id-verbose 0'
No additional messages are printed.
'set build-id-verbose 1'
Missing separate debug filenames are printed.
'set build-id-verbose 2'
Missing separate debug filenames are printed and also all the
parsing of the binaries to find their "build id" content is
printed.
'show build-id-verbose'
Show the current verbosity value for the "build id" content
locating.
A debug link is a special section of the executable file named
'.gnu_debuglink'. The section must contain:
* A filename, with any leading directory components removed, followed
by a zero byte,
* zero to three bytes of padding, as needed to reach the next
four-byte boundary within the section, and
* 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 CRC argument.
Any executable file format can carry a debug link, as long as it can
contain a section named '.gnu_debuglink' with the contents described
above.
The build ID is a special section in the executable file (and in
other ELF binary files that GDB may consider). This section is often
named '.note.gnu.build-id', but that name is not mandatory. It contains
unique identification for the built files--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.
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--much like a '.bss' section in an
ordinary executable.
The GNU binary utilities (Binutils) package includes the 'objcopy'
utility that can produce the separated executable / debugging
information file pairs using the following commands:
objcopy --only-keep-debug foo foo.debug
strip -g foo
These commands remove the debugging information from the executable file
'foo' and place it in the file 'foo.debug'. You can use the first,
second or both methods to link the two files:
* The debug link method needs the following additional command to
also leave behind a debug link in 'foo':
objcopy --add-gnu-debuglink=foo.debug foo
Ulrich Drepper's 'elfutils' package, starting with version 0.53,
contains a version of the 'strip' command such that the command
'strip foo -f foo.debug' has the same functionality as the two
'objcopy' commands and the 'ln -s' command above, together.
* Build ID gets embedded into the main executable using 'ld
--build-id' or the GCC counterpart 'gcc -Wl,--build-id'. Build ID
support plus compatibility fixes for debug files separation are
present in GNU binary utilities (Binutils) package since version
2.18.
The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3
using the polynomial:
x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}
+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
The function is computed byte at a time, taking the least significant
bit of each byte first. The initial pattern '0xffffffff' is used, to
ensure leading zeros affect the CRC and the final result is inverted to
ensure trailing zeros also affect the CRC.
_Note:_ This is the same CRC polynomial as used in handling the
"Remote Serial Protocol" 'qCRC' packet (qCRC packet). However
in the case of the Remote Serial Protocol, the CRC is computed _most_
significant bit first, and the result is not inverted, so trailing zeros
have no effect on the CRC value.
To complete the description, we show below the code of the function
which produces the CRC used in '.gnu_debuglink'. Inverting the
initially supplied 'crc' argument means that an initial call to this
function passing in zero will start computing the CRC using
'0xffffffff'.
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 & 0xffffffff;
for (end = buf + len; buf < end; ++buf)
crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
return ~crc & 0xffffffff;
}
This computation does not apply to the "build ID" method.
Info Catalog
gdb: File Caching
gdb: GDB Files
gdb: MiniDebugInfo