Gdb/Separate-Debug-Files
Next: MiniDebugInfo, Previous: File Caching, Up: GDB Files [Contents][Index]
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
, whereexecutable
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 in The GNU Linker. 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 namednn/nnnnnnnn.debug
, wherenn
are the first 2 hex characters of the build ID bit string, andnnnnnnnn
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.
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 thestrip
command such that the command strip foo -f foo.debug has the same functionality as the twoobjcopy
commands and theln -s
command above, together.- Build ID gets embedded into the main executable using
ld --build-id
or the GCC counterpartgcc -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:
x32 + x26 + x23 + x22 + x16 + x12 + x11 + x10 + x8 + x7 + x5 + x4 + x2 + 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 (see 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.
Next: MiniDebugInfo, Previous: File Caching, Up: GDB Files [Contents][Index]