Section Basics,  Next: ELF Linker Relocation,  Up: Stab Sections

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 (*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.