[rld] Symbol Resolution Rules

Table of Contents

• Internal symbols
• The global symbol table
  • Key

Internal Symbols

A definition of an internal/internal_no_symbol will always supplant an identically named entry in the global symbol table. That is, a reference will always prefer to bind to an internal or internal_no_symbol name over a name in the global symbol table.

The Global Symbol Table

This table shows the rules for symbol definition and overriding. That is, it shows what happens when the linker encounters a name either for the first time, or where there is an existing symbol table entry. The table columns show the “before” state of the symbol (every symbol starts as undef); the rows show each symbol type for a colliding name, and each cell then defines how the linker reacts to a redefinition.

The current implementation treats link_once_any, link_once_odr, weak_any, and weak_odr as synonyms. In the table below, the row and column for link-once applies to both link_once_any and link_once_odr; likewise the row and column for weak applies to both weak_any and weak_odr.

		Existing Definition
		undef	append	common	external	link-once	weak
New Definition	append	✓	Appends	✗	✗	✗	✗
	common	✓	✗	Largest	Ignored	✗	Replaces
	external	✓	✗	Replaces	✗	✗	Replaces
	link-once	✓	✗	✗	✗	Lowest Ordinal	Lowest Ordinal
	weak	✓	✗	Ignored	Ignored	Lowest Ordinal	Lowest Ordinal

Key

• “undef” can be thought of as the initial state of every symbol, whether it has been entered into the symbol table yet or not. An “undef” entry is created in the symbol table for a symbol that is referenced but not yet defined.
• ✓ — The new symbol is unconditionally accepted.
• ✗ — The linker emits an error: probably “duplicate symbol”.
• “Appends” — The new definition is added to the existing (order is given by the compilation’s ordinal value).
• “Replaces” — The original symbol definition is discarded and replaced with the new. Note that rld’s layout algorithm runs in parallel with symbol resolution. Consequently, space in the output file that was assigned to the original definition will be “leaked” and not reassigned.
• “Ignored” — The new symbol definition is discarded; the original definition is not affected.
• “Lowest Ordinal” — The linker chooses the definition from the compilation with the lowest ordinal value. If the new definition has a lower ordinal that the existing, the new replaces the existing; if the new ordinal is greater, the existing definition is retained. This ensures that the linker’s output is identical even whilst its use of threads makes the order of processing definitions unpredictable.
• “Largest” — If the new symbol is larger than the existing, the new symbol Replaces the existing; if the sizes are equal, select the Lowest Ordinal; otherwise it is Ignored.