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 (Note: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 (Note: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.