15.2 Debugging Information in Separate Files

No value for GDBN allows you to put a program's debugging information in a file separate from the executable itself, in a way that allows No value for GDBN 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.

No value for GDBN 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 CRC32 checksum for the debug file, which No value for GDBN uses to validate that the executable and the debug file came from the same build.
• The executable contains a build ID, a unique signature that is also present in the corresponding debug info file. (This is supported only on some operating systems, notably on GNU/Linux. For more details about this feature, see the Fedora Project's description of the buid ID feature.) 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, No value for GDBN uses two different methods of looking for the debug file:

• For the “debug link” method, No value for GDBN looks up the named file in the directory of the executable file, then in a subdirectory of that directory named ‘.debug’, and finally under the global debug directory, in a subdirectory whose name is identical to the leading directories of the executable's absolute file name.
• For the “build ID” method, No value for GDBN looks in the ‘.build-id’ subdirectory of the global debug directory for a file named ‘nn/nnnnnnnn.debug’, where nn are the first 2 hex characters of the build ID signature, and nnnnnnnn are the rest of the signature. (Real signatures are 32 or more characters, not 10.)

So, for example, suppose you ask No value for GDBN 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 global debug directory is ‘/usr/lib/debug’, then No value for GDBN 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’.

You can set the global debugging info directory's name, and view the name No value for GDBN is currently using.

set debug-file-directory directory

Set the directory which No value for GDBN searches for separate debugging information files to directory.

show debug-file-directory

Show the directory No value for GDBN 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.

A build ID is a special section of the executable file named .note.gnu.build-id. This section contains unique identification for the built files—it remains the same across multiple builds of the same build tree. The default algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the content. 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.

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 No value for NGCC counterpart gcc -Wl,--build-id. Build ID support plus compatibility fixes for debug files separation are present in GNU binary utilities (Binutils) since version 2.18.

Since there are many different ways to compute CRC's for the debug link (different polynomials, reversals, byte ordering, etc.), the simplest way to describe the CRC used in .gnu_debuglink sections is to give the complete code for a function that computes it:

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.