5.4. COFF Symbol Table

The Symbol Table described in this section is inherited from the traditional COFF format. It is distinct from CodeView® information. A file may contain both a COFF Symbol Table and CodeView debug information, and the two are kept separate. Some Microsoft tools use the Symbol Table for limited but important purposes, such as communicating COMDAT information to the linker. Section names and file names, as well as code and data symbols, are listed in the Symbol Table.

The location of the Symbol Table is indicated in the COFF Header.

The Symbol Table is an array of records, each 18 bytes long. Each record is either a standard or auxiliary symbol-table record. A standard record defines a symbol or name, and has the following format:

Offset Size Field Description
0 8 Name (*) Name of the symbol, represented by union of three structures. An array of eight bytes is used if the name is not more than eight bytes long. See Section 5.4.1, “Symbol Name Representation, ” for more information.
8 4 Value Value associated with the symbol. The interpretation of this field depends on Section Number and Storage Class. A typical meaning is the relocatable address.
12 2 SectionNumber Signed integer identifying the section, using a one-based index into the Section Table. Some values have special meaning defined in “Section Number Values.”
14 2 Type A number representing type. Microsoft tools set this field to 0x20 (function) or 0x0 (not a function). See Section 5.4.3, “Type Representation,” for more information.
16 1 StorageClass Enumerated value representing storage class. See Section 5.4.4, “Storage Class,” for more information.
17 1 NumberOfAuxSymbols Number of auxiliary symbol table entries that follow this record.

Zero or more auxiliary symbol-table records immediately follow each standard symbol-table record. However, typically not more than one auxiliary symbol-table record follows a standard symbol-table record (except for .file records with long file names). Each auxiliary record is the same size as a standard symbol-table record (18 bytes), but rather than define a new symbol, the auxiliary record gives additional information on the last symbol defined. The choice of which of several formats to use depends on the Storage Class field. Currently defined formats for auxiliary symbol table records are shown in “Auxiliary Symbol Records.”

Tools that read COFF symbol tables must ignore auxiliary symbol records whose interpretation is unknown. This allows the symbol table format to be extended to add new auxiliary records, without breaking existing tools.

5.4.1. Symbol Name Representation

The Name field in a symbol table consists of eight bytes that contain the name itself, if not too long, or else give an offset into the String Table. To determine whether the name itself or an offset is given, test the first four bytes for equality to zero.

Offset Size Field Description
0 8 Short Name An array of eight bytes. This array is padded with nulls on the right if the name is less than eight bytes long.
0 4 Zeroes Set to all zeros if the name is longer than eight bytes.
4 4 Offset Offset into the String Table.

5.4.2. Section Number Values

Normally, the Section Value field in a symbol table entry is a one-based index into the Section Table. However, this field is a signed integer and may take negative values. The following values, less than one, have special meanings:

Constant Value Description
IMAGE_SYM_UNDEFINED 0 Symbol record is not yet assigned a section. If the value is 0 this indicates a references to an external symbol defined elsewhere. If the value is non-zero this is a common symbol with a size specified by the value.
IMAGE_SYM_ABSOLUTE -1 The symbol has an absolute (non-relocatable) value and is not an address.
IMAGE_SYM_DEBUG -2 The symbol provides general type or debugging information but does not correspond to a section. Microsoft tools use this setting along with .file records (storage class FILE).

5.4.3. Type Representation

The Type field of a symbol table entry contains two bytes, each byte representing type information. The least-significant byte represents simple (base) data type, and the most-significant byte represents complex type, if any:

MSB LSB
Complex type: none, pointer, function, array. Base type: integer, floating-point, etc.

The following values are defined for base type, although Microsoft tools generally do not use this field, setting the least-significant byte to 0. Instead, CodeView information is used to indicate types. However, the possible COFF values are listed here for completeness.

Constant Value Description
IMAGE_SYM_TYPE_NULL 0 No type information or unknown base type. Microsoft tools use this setting.
IMAGE_SYM_TYPE_VOID 1 No valid type; used with void pointers and functions.
IMAGE_SYM_TYPE_CHAR 2 Character (signed byte).
IMAGE_SYM_TYPE_SHORT 3 Two-byte signed integer.
IMAGE_SYM_TYPE_INT 4 Natural integer type (normally four bytes in Windows NT).
IMAGE_SYM_TYPE_LONG 5 Four-byte signed integer.
IMAGE_SYM_TYPE_FLOAT 6 Four-byte floating-point number.
IMAGE_SYM_TYPE_DOUBLE 7 Eight-byte floating-point number.
IMAGE_SYM_TYPE_STRUCT 8 Structure.
IMAGE_SYM_TYPE_UNION 9 Union.
IMAGE_SYM_TYPE_ENUM 10 Enumerated type.
IMAGE_SYM_TYPE_MOE 11 Member of enumeration (a specific value).
IMAGE_SYM_TYPE_BYTE 12 Byte; unsigned one-byte integer.
IMAGE_SYM_TYPE_WORD 13 Word; unsigned two-byte integer.
IMAGE_SYM_TYPE_UINT 14 Unsigned integer of natural size (normally, four bytes).
IMAGE_SYM_TYPE_DWORD 15 Unsigned four-byte integer.

The most significant byte specifies whether the symbol is a pointer to, function returning, or array of the base type specified in the least significant byte. Microsoft tools use this field only to indicate whether or not the symbol is a function, so that the only two resulting values are 0x0 and 0x20 for the Type field. However, other tools can use this field to communicate more information.

It is very important to specify the function attribute correctly. This information is required for incremental linking to work correctly. For some architectures the information may be required for other purposes.

Constant Value Description
IMAGE_SYM_DTYPE_NULL 0 No derived type; the symbol is a simple scalar variable.
IMAGE_SYM_DTYPE_POINTER 1 Pointer to base type.
IMAGE_SYM_DTYPE_FUNCTION 2 Function returning base type.
IMAGE_SYM_DTYPE_ARRAY 3 Array of base type.

5.4.4. Storage Class

The Storage Class field of the Symbol Table indicates what kind of definition a symbol represents. The following table shows possible values. Note that the Storage Class field is an unsigned one-byte integer. The special value -1 should therefore be taken to mean its unsigned equivalent, 0xFF.

Although traditional COFF format makes use of many storage-class values, Microsoft tools rely on CodeView format for most symbolic information and generally use only four storage-class values: EXTERNAL (2), STATIC (3), FUNCTION (101), and STATIC (103). Except in the second column heading below, “Value” should be taken to mean the Value field of the symbol record (whose interpretation depends on the number found as the storage class).

Constant Value Description / Interpretation of Value Field
IMAGE_SYM_CLASS_END_OF_FUNCTION -1 (0xFF) Special symbol representing end of function, for debugging purposes.
IMAGE_SYM_CLASS_NULL 0 No storage class assigned.
IMAGE_SYM_CLASS_AUTOMATIC 1 Automatic (stack) variable. The Value field specifies stack frame offset.
IMAGE_SYM_CLASS_EXTERNAL 2 Used by Microsoft tools for external symbols. The Value field indicates the size if the section number is IMAGE_SYM_UNDEFINED (0). If the section number is not 0, then the Value field specifies the offset within the section.
IMAGE_SYM_CLASS_STATIC 3 The Value field specifies the offset of the symbol within the section. If the Value is 0, then the symbol represents a section name.
IMAGE_SYM_CLASS_REGISTER 4 Register variable. The Value field specifies register number.
IMAGE_SYM_CLASS_EXTERNAL_DEF 5 Symbol is defined externally.
IMAGE_SYM_CLASS_LABEL 6 Code label defined within the module. The Value field specifies the offset of the symbol within the section.
IMAGE_SYM_CLASS_UNDEFINED_LABEL 7 Reference to a code label not defined.
IMAGE_SYM_CLASS_MEMBER_OF_STRUCT 8 Structure member. The Value field specifies nth member.
IMAGE_SYM_CLASS_ARGUMENT 9 Formal argument (parameter)of a function. The Value field specifies nth argument.
IMAGE_SYM_CLASS_STRUCT_TAG 10 Structure tag-name entry.
IMAGE_SYM_CLASS_MEMBER_OF_UNION 11 Union member. The Value field specifies nth member.
IMAGE_SYM_CLASS_UNION_TAG 12 Union tag-name entry.
IMAGE_SYM_CLASS_TYPE_DEFINITION 13 Typedef entry.
IMAGE_SYM_CLASS_UNDEFINED_STATIC 14 Static data declaration.
IMAGE_SYM_CLASS_ENUM_TAG 15 Enumerated type tagname entry.
IMAGE_SYM_CLASS_MEMBER_OF_ENUM 16 Member of enumeration. Value specifies nth member.
IMAGE_SYM_CLASS_REGISTER_PARAM 17 Register parameter.
IMAGE_SYM_CLASS_BIT_FIELD 18 Bit-field reference. Value specifies nth bit in the bit field.
IMAGE_SYM_CLASS_BLOCK 100 A .bb (beginning of block) or .eb (end of block) record. Value is the relocatable address of the code location.
IMAGE_SYM_CLASS_FUNCTION 101 Used by Microsoft tools for symbol records that define the extent of a function: begin function (named .bf), end function (.ef), and lines in function (.lf). For .lf records, Value gives the number of source lines in the function. For .ef records, Value gives the size of function code.
IMAGE_SYM_CLASS_END_OF_STRUCT 102 End of structure entry.
IMAGE_SYM_CLASS_FILE 103 Used by Microsoft tools, as well as traditional COFF format, for the source-file symbol record. The symbol is followed by auxiliary records that name the file.
IMAGE_SYM_CLASS_SECTION 104 Definition of a section (Microsoft tools use STATIC storage class instead).
IMAGE_SYM_CLASS_WEAK_EXTERNAL 105 Weak external. See Section 5.5.3, “Auxiliary Format 3: Weak Externals,” for more information.