5.5. Auxiliary Symbol Records

Auxiliary Symbol Table records always follow and apply to some standard Symbol Table record. An auxiliary record can have any format that the tools are designed to recognize, but 18 bytes must be allocated for them so that Symbol Table is maintained as an array of regular size. Currently, Microsoft tools recognize auxiliary formats for the following kinds of records: function definitions, function begin and end symbols (.bf and .ef), weak externals, filenames, and section definitions.

The traditional COFF design also includes auxiliary-record formats for arrays and structures. Microsoft tools do not use these, and instead place that symbolic information in CodeView format in the debug sections.

5.5.1. Auxiliary Format 1: Function Definitions

A symbol table record marks the beginning of a function definition if all of the following are true: it has storage class EXTERNAL (2), a Type value indicating it is a function (0x20), and a section number greater than zero. Note that a symbol table record that has a section number of UNDEFINED (0) does not define the function and does not have an auxiliary record. Function-definition symbol records are followed by an auxiliary record with the format described below.

Offset	Size	Field	Description
0	4	TagIndex	Symbol-table index of the corresponding .bf (begin function) symbol record.
4	4	TotalSize	Size of the executable code for the function itself. If the function is in its own section, the Size of Raw Data in the section header will be greater or equal to this field, depending on alignment considerations.
8	4	PointerToLinenumber	File offset of the first COFF line-number entry for the function, or zero if none exists. See Section 5.3, “COFF Line Numbers,” for more information.
12	4	PointerToNextFunction	Symbol-table index of the record for the next function. If the function is the last in the symbol table, this field is set to zero.
16	2	Unused.

5.5.2. Auxiliary Format 2: .bf and .ef Symbols

For each function definition in the Symbol Table, there are three contiguous items that describe the beginning, ending, and number of lines. Each of these symbols has storage class FUNCTION (101):

A symbol record named .bf (begin function). The Value field is unused.
A symbol record named .lf (lines in function). The Value field gives the number of lines in the function.
A symbol record named .ef (end of function). The Value field has the same number as the Total Size field in the function-definition symbol record.

The .bf and .ef symbol records (but not .lf records) are followed by an auxiliary record with the following format:

Offset	Size	Field	Description
0	4	Unused.
4	2	Linenumber	Actual ordinal line number (1, 2, 3, etc.) within source file, corresponding to the .bf or .ef record.
6	6	Unused.
12	4	PointerToNextFunction (.bf only)	Symbol-table index of the next .bf symbol record. If the function is the last in the symbol table, this field is set to zero. Not used for .ef records.
16	2	Unused.

5.5.3. Auxiliary Format 3: Weak Externals

“Weak externals” are a mechanism for object files allowing flexibility at link time. A module can contain an unresolved external symbol (sym1), but it can also include an auxiliary record indicating that if sym1 is not present at link time, another external symbol (sym2) is used to resolve references instead.

If a definition of sym1 is linked, then an external reference to the symbol is resolved normally. If a definition of sym1 is not linked, then all references to the weak external for sym1 refer to sym2 instead. The external symbol, sym2, must always be linked; typically it is defined in the module containing the weak reference to sym1.

Weak externals are represented by a Symbol Table record with EXTERNAL storage class, UNDEF section number, and a value of 0. The weak-external symbol record is followed by an auxiliary record with the following format:

Offset	Size	Field	Description
0	4	TagIndex	Symbol-table index of sym2, the symbol to be linked if sym1 is not found.
4	4	Characteristics	A value of IMAGE_WEAK_EXTERN_SEARCH_NOLIBRARY indicates that no library search for sym1 should be performed. A value of IMAGE_WEAK_EXTERN_SEARCH_LIBRARY indicates that a library search for sym1 should be performed. A value of IMAGE_WEAK_EXTERN_SEARCH_ALIAS indicates that sym1 is an alias for sym2.
8	10	Unused.

Note that the Characteristics field is not defined in WINNT.H; instead, the Total Size field is used.

5.5.4. Auxiliary Format 4: Files

This format follows a symbol-table record with storage class FILE (103). The symbol name itself should be .file, and the auxiliary record that follows it gives the name of a source-code file.

Offset	Size	Field	Description
0	18	File Name	ASCII string giving the name of the source file; padded with nulls if less than maximum length.

5.5.5. Auxiliary Format 5: Section Definitions

This format follows a symbol-table record that defines a section: such a record has a symbol name that is the name of a section (such as .text or .drectve) and has storage class STATIC (3). The auxiliary record provides information on the section referred to. Thus it duplicates some of the information in the section header.

Offset	Size	Field	Description
0	4	Length	Size of section data; same as Size of Raw Data in the section header.
4	2	NumberOfRelocations	Number of relocation entries for the section.
6	2	NumberOfLinenumbers	Number of line-number entries for the section.
8	4	Check Sum	Checksum for communal data. Applicable if the IMAGE_SCN_LNK_COMDAT flag is set in the section header. See “COMDAT Sections” below, for more information.
12	2	Number	One-based index into the Section Table for the associated section; used when the COMDAT Selection setting is 5.
14	1	Selection	COMDAT selection number. Applicable if the section is a COMDAT section.
15	3	Unused.

5.5.6. COMDAT Sections (Object Only)

The Selection field of the Section Definition auxiliary format is applicable if the section is a COMDAT section: a section that can be defined by more than one object file. (The flag IMAGE_SCN_LNK_COMDAT is set in the Section Flags field of the section header.) The Selection field determines the way that the linker resolves the multiple definitions of COMDAT sections.

The first symbol having the section value of the COMDAT section must be the section symbol. This symbol has the name of the section, Value field equal to 0, the section number of the COMDAT section in question, Type field equal to IMAGE_SYM_TYPE_NULL, Class field equal to IMAGE_SYM_CLASS_STATIC, and one auxiliary record. The second symbol is called “the COMDAT symbol” and is used by the linker in conjunction with the Selection field.

Values for the Selection field are shown below.

Constant	Value	Description
IMAGE_COMDAT_SELECT_NODUPLICATES	1	The linker issues a multiply defined symbol error if this symbol is already defined.
IMAGE_COMDAT_SELECT_ANY	2	Any section defining the same COMDAT symbol may be linked; the rest are removed.
IMAGE_COMDAT_SELECT_SAME_SIZE	3	The linker chooses an arbitrary section among the definitions for this symbol. A multiply defined symbol error is issued if all definitions don’t have the same size.
IMAGE_COMDAT_SELECT_EXACT_MATCH	4	The linker chooses an arbitrary section among the definitions for this symbol. A multiply defined symbol error is issued if all definitions don’t match exactly.
IMAGE_COMDAT_SELECT_ASSOCIATIVE	5	The section is linked if a certain other COMDAT section is linked. This other section is indicated by the Number field of the auxiliary symbol record for the section definition. Use of this setting is useful for definitions that have components in multiple sections (for example, code in one and data in another), but where all must be linked or discarded as a set.
IMAGE_COMDAT_SELECT_LARGEST	6	The linker chooses the largest from the definitions for this symbol. If multiple definitions have this size the choice between them is arbitrary.