Stab Section Basics (STABS)

### F.1 How to Embed Stabs in Sections ¶

The assembler creates two custom sections, a section named `.stab` which contains an array of fixed length structures, one struct per stab, and a section named `.stabstr` containing all the variable length strings that are referenced by stabs in the `.stab` section. The byte order of the stabs binary data depends on the object file format. For ELF, it matches the byte order of the ELF file itself, as determined from the `EI_DATA` field in the `e_ident` member of the ELF header. For SOM, it is always big-endian (is this true??? FIXME). For COFF, it matches the byte order of the COFF headers. The meaning of the fields is the same as for a.out (see Symbol Table Format), except that the `n_strx` field is relative to the strings for the current compilation unit (which can be found using the synthetic N_UNDF stab described below), rather than the entire string table.

The first stab in the `.stab` section for each compilation unit is synthetic, generated entirely by the assembler, with no corresponding `.stab` directive as input to the assembler. This stab contains the following fields:

`n_strx`

  Offset in the `.stabstr` section to the source filename.

`n_type`

  `N_UNDF`.

`n_other`

  Unused field, always zero. This may eventually be used to hold overflows from the count in the `n_desc` field.

`n_desc`

  Count of upcoming symbols, i.e., the number of remaining stabs for this source file.

`n_value`

  Size of the string table fragment associated with this source file, in bytes.

The `.stabstr` section always starts with a null byte (so that string offsets of zero reference a null string), followed by random length strings, each of which is null byte terminated.

The ELF section header for the `.stab` section has its `sh_link` member set to the section number of the `.stabstr` section, and the `.stabstr` section has its ELF section header `sh_type` member set to `SHT_STRTAB` to mark it as a string table. SOM and COFF have no way of linking the sections together or marking them as string tables.

For COFF, the `.stab` and `.stabstr` sections may be simply concatenated by the linker. GDB then uses the `n_desc` fields to figure out the extent of the original sections. Similarly, the `n_value` fields of the header symbols are added together in order to get the actual position of the strings in a desired `.stabstr` section. Although this design obviates any need for the linker to relocate or otherwise manipulate `.stab` and `.stabstr` sections, it also requires some care to ensure that the offsets are calculated correctly. For instance, if the linker were to pad in between the `.stabstr` sections before concatenating, then the offsets to strings in the middle of the executable’s `.stabstr` section would be wrong.

The GNU linker is able to optimize stabs information by merging duplicate strings and removing duplicate header file information (see Names of Include Files). When some versions of the GNU linker optimize stabs in sections, they remove the leading `N_UNDF` symbol and arranges for all the `n_strx` fields to be relative to the start of the `.stabstr` section.