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