[The World of Linkers—Theory 03] One Name, Several Definitions: Who Wins?

A declaration says that a definition exists somewhere. It does not say where, whether another definition competes with it, or whether the linker will ever open the file containing it. That gap is where symbol resolution begins.

In the previous chapter, main.o needed add, and add.o supplied it. Here we complicate that seemingly simple arrangement until it explains two familiar diagnostics: undefined reference and multiple definition.

The recorded experiments use native x86-64 Linux, Clang¹ 21.1.8, GNU² ld 2.46, and LLD³ 21.1.8. Inspection uses GNU binutils⁴, with llvm-objdump for LLVM⁵ disassembly. Commands using ld -e main produce files for inspection: setting the entry address does not provide C startup code or a caller to receive main's return. Executed examples instead use native musl-gcc⁶ with the appropriate runtime.

A table of promises and definitions

LOCAL symbols belong to one input file. Two files may each contain a static helper without competing for a global name. GLOBAL and WEAK symbols enter a global table, usually indexed by a hash of the name. A table entry can record a definition, an unresolved reference, or a definition available from a library but not yet loaded.

Start with an ordinary call:

1
// main.c
2
int add(int a, int b);
3
int main(void) { return add(1, 2); }

1
// add.c
2
int add(int a, int b) { return a + b; }

1
clang -O1 -c main.c add.c
2
ld -e main main.o -o missing-add

Reading main.o creates an unresolved add; reading add.o would resolve it. Without that second input:

1
ld: main.o: in function `main':
2
main.c:(.text+0xb): undefined reference to `add'

At -O1, the call has become a tail jump. The relocation field begins at .text+0xb; this is a byte offset, not a source line. The linker has reached a relocation that needs an address it cannot supply.

Strong definitions, weak alternatives

Two ordinary definitions compete without any rule for choosing the intended one:

1
$ ld -e main a.o b.o
2
ld: b.o:(.data+0x0): multiple definition of `counter'; a.o:(.data+0x0): first defined here
3

4
$ ld.lld -e main a.o b.o
5
ld.lld: error: duplicate symbol: counter
6
>>> defined at a.c
7
>>>            a.o:(counter)
8
>>> defined at b.c
9
>>>            b.o:(.data+0x0)

The ELF⁷ gABI⁸ prohibits multiple definitions with the same GLOBAL name. A WEAK definition supplies an explicit alternative: an ordinary GLOBAL definition takes precedence. nm⁹ marks weak objects V, weak functions W, and ordinary initialized objects D:

1
$ nm w.o a.o
2

3
w.o:
4
0000000000000000 V counter
5

6
a.o:
7
0000000000000000 D counter
8
0000000000000000 T main

Here w.o contains __attribute__((weak)) int counter = 3;, while a.o defines counter = 1. Putting the weak definition first does not change the winner:

1
$ ld -e main w.o a.o -o s2
2
$ nm s2 | grep counter
3
0000000000403004 D counter
4
$ llvm-objdump -s -j .data s2 | tail -1
5
 403000 03000000 01000000                    ........

Notice what remains in .data: both 3 and 1. Resolution changes what the name denotes. It does not automatically delete the losing definition's bytes or its entire section.

For two weak definitions, the gABI leaves the choice unspecified. These versions of GNU ld and LLD retain the first:

1
$ ld -e main m.o w.o w2.o -o s3 && llvm-objdump -s -j .data s3 | tail -1
2
 403000 03000000 04000000                    ........
3
$ ld -e main m.o w2.o w.o -o s4 && llvm-objdump -s -j .data s4 | tail -1
4
 403000 04000000 03000000                    ........

That makes weak definitions useful for replaceable defaults, but unsuitable for expressing a required choice between two competing implementations.

A weak reference makes another promise: absence is acceptable.

1
extern void hook(void) __attribute__((weak));
2
int main(void) { if (hook) hook(); return 0; }

An unresolved weak symbol has value zero. The generated code checks a GOT¹⁰ entry before attempting the call:

1
$ ld -e main u.o -o s6
2
$ llvm-objdump -d --no-show-raw-insn s6
3
0000000000401000 <main>:
4
  401000:      	cmpq	$0x0, 0x2fd8(%rip)      # 0x403fe0
5
  401008:      	je	0x401014 <main+0x14>
6
  40100a:      	pushq	%rax
7
  40100b:      	callq	0x0
8
  ...
9
$ llvm-objdump -s -j .got s6
10
 403fe0 00000000 00000000                    ........

The zero-target call really exists, but the preceding condition prevents its execution. Position-independent code uses the GOT because the compiler must accommodate both a real definition and the absolute value zero. With -fno-pic, this example instead uses a direct address relocation.

Weakness is merged for the name as a whole. Let wk.o contain a weak hook reference and its relocation, and sk.o contain .globl hook without a relocation. The ordinary undefined declaration makes the merged requirement strong:

1
$ ld -e main wk.o sk.o
2
ld: wk.o: in function `main':
3
(.text+0x3): undefined reference to `hook'
4
$ ld.lld -e main wk.o sk.o
5
ld.lld: error: undefined symbol: hook
6
>>> referenced by wk.o:(.text+0x3)

Do not extend this static-link rule to every runtime lookup. The glibc¹¹ dynamic linker normally uses the first definition in its lookup scope without searching past a weak definition for a strong one. Its older behavior is described under LD_DYNAMIC_WEAK in ld.so(8).

Common storage is a different mechanism

With -fcommon, separate files containing int x; can contribute to one common allocation. This historical extension borrowed the storage-merging idea used for FORTRAN COMMON blocks. In ELF, SHN_COMMON means that storage has not yet been assigned; st_size gives the required size and st_value the alignment.

1
$ nm c1.o c2.o
2

3
c1.o:
4
0000000000000000 T main
5
0000000000000004 C x
6

7
c2.o:
8
0000000000000004 C x
9

10
$ readelf -sW c3.o     # c3.c contains long x;
11
   Num:    Value          Size Type    Bind   Vis      Ndx Name
12
     2: 0000000000000008     8 OBJECT  GLOBAL DEFAULT  COM x

The first column from nm happens to match alignment here, but GNU nm displays the size of a common symbol. A larger array exposes the distinction:

1
$ nm cb.o
2
0000000000000064 C buf
3
$ readelf -sW cb.o | grep buf
4
     2: 0000000000000010   100 OBJECT  GLOBAL DEFAULT  COM buf

The linker takes the largest size and strictest alignment, then allocates zero-initialized storage in .bss:

1
$ ld -e main c1.o c2.o -o a && nm -S a | grep ' x$'
2
0000000000403000 0000000000000004 B x
3
$ ld -e main c1.o c3.o -o b && nm -S b | grep ' x$'
4
0000000000403000 0000000000000008 B x

One file may believe x is an int and another a long; neither that merge nor successful linking establishes C type compatibility. GNU ld can flag the size disagreement:

1
ld: c3.o: warning: common of `x' overriding smaller common from c1.o

An ordinary strong definition such as int x = 5; overrides common storage. A common symbol in turn overrides a weak definition. Modern defaults make the historical case less common: GCC¹² 10 and Clang 11 switched to -fno-common, under which int x; becomes a real .bss definition:

1
$ nm n1.o n2.o     # same source, compiled with -fno-common
2

3
n1.o:
4
0000000000000000 T main
5
0000000000000000 B x
6

7
n2.o:
8
0000000000000000 B x
9

10
$ ld -e main n1.o n2.o
11
ld: n2.o:(.bss+0x0): multiple definition of `x'; n1.o:(.bss+0x0): first defined here

C tentative definitions apply within a translation unit. Multiple external definitions across translation units violate the language requirements; common merging is a documented extension, not a general guarantee of valid C. Use an extern declaration in a shared header and one actual definition.

Predict these results before reading the table. Module A also contains a main that reads n.

Reversing the last pair still makes common storage prevail:

1
$ ld -e main p5b.o p5a.o -o g5 && nm g5 | grep ' n$'
2
0000000000403004 B n
3
$ ld.lld -e main p5b.o p5a.o -o l5 && nm l5 | grep ' n$'
4
000000000020219c B n

Some textbook presentations call uninitialized common definitions “weak.” That teaching vocabulary is not ELF's STB_WEAK. In particular, it cannot predict the last row. Read the historical CS

Matching names does not check C types

Recall the opening chapter's program: one file defines int objects x and y; another declares extern double x and stores 1.0. The incompatible declarations make this UB¹³. The following explanation concerns the displayed build, rather than a result guaranteed by C. The reference contains no record saying “this must be a double”:

1
$ readelf -sW main.o | grep -E ' [xy]$'
2
     6: 0000000000000004     4 OBJECT  GLOBAL DEFAULT    2 y
3
     7: 0000000000000000     4 OBJECT  GLOBAL DEFAULT    2 x
4
$ readelf -sW other.o | grep ' x$'
5
     5: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT  UND x

Its assumption has already become an eight-byte store:

1
$ llvm-objdump -dr other.o
2
0000000000000000 <set_x>:
3
       0: 48 8b 05 00 00 00 00         	movq	(%rip), %rax
4
		0000000000000003:  R_X86_64_PC32	.LC0-0x4
5
       7: 48 89 05 00 00 00 00         	movq	%rax, (%rip)
6
		000000000000000a:  R_X86_64_PC32	x-0x4
7
       e: c3                           	retq

Two separate decisions matter: the relocation determines where the instruction writes, while the instruction determines how many bytes it writes.

The R_X86_64_PC32 field at offset 0xa receives the displacement S + A - P, where S is the final address of x, A = -4, and P is the final address of the relocation field. The field occupies four bytes. Adding the displacement to the following RIP gives (P + 4) + (S - 4 - P) = S; the field does not contain the absolute address of x.

The definition's st_size is four, whereas the undefined reference's size is zero. These records do not encode the C types needed to compare the declarations. Ordinary symbol resolution and this relocation calculation do not recover C types from instructions. Linker relaxation may inspect and rewrite instructions, but that is not C type checking.

In the displayed .data layout, x starts at offset zero and y at offset four. If x has final address X, y is at X + 4. The IEEE 754 binary64 encoding of 1.0 is 0x3ff0000000000000, whose little-endian bytes are 00 00 00 00 00 00 f0 3f. The eight-byte store writes zero into x and 0x3ff00000, or 1072693248, into the adjacent y. This accounts for the observed result in that build. Different layouts or optimizations can change the manifestation of UB.

Even a function and an object can be confused:

1
// fmain.c
2
#include <stdio.h>
3
extern int answer;          /* incorrectly declared as an object */
4
int main(void) {
5
    printf("answer = %#x\n", answer);
6
    return 0;
7
}

1
// fanswer.c
2
int answer(void) { return 42; }

Built with musl-gcc -O1 -Wall -static fmain.c fanswer.c -o fm, this prints answer = 0xfa1e0ff3 on the recorded machine. Those are the first four instruction bytes, f3 0f 1e fa, interpreted as an integer: GCC emitted CET's endbr64 before mov $42,%eax. The program reads code, not the function's return value.

Likewise, defining char msg[]="hi" while declaring extern char *msg elsewhere makes the user read the string bytes as a pointer. The recorded pointer was 0x6968; passing it to puts faulted. These are explanations of particular artifacts, not portable outcomes.

The reliable first defense is a shared header included by both users and the defining file. LTO¹⁴ can also expose cross-file type information to the compiler:

1
$ musl-gcc -O2 -flto -static main.lto.o other.lto.o -o prog_lto
2
other.c:1:15: warning: type of 'x' does not match original declaration [-Wlto-type-mismatch]
3
    1 | extern double x;
4
      |               ^
5
main.c:4:5: note: type 'int' should match type 'double'

GCC's -Wlto-type-mismatch is enabled by default with LTO, but this is a warning, not a repair. In that optimized build the output changed to x = 0, y = 5: the invalid store remained, while the compiler folded y to a constant. C++'s corresponding -Wodr can diagnose some inconsistent class definitions. Neither mechanism makes ordinary ELF symbol resolution a language type checker.

Archives delay the decision

The archive is a container; its members are objects

An ordinary System V/GNU ar file begins with eight bytes, !<arch>\n, followed by repeated member headers and payloads. Each header occupies 60 bytes, with numeric fields encoded as ASCII; its decimal size field gives the following payload length. An odd-length payload is followed by one padding byte so the next header begins at an even file offset. GNU ar emits a newline for this padding. The byte is not included in size or in the payload.

If a member header begins at file offset h, its payload occupies [h+60, h+60+size). The next header begins at h+60+size+(size%2). An ELF parser receives the payload slice, excluding archive magic, member headers, and padding. Symbol indexes and long-name tables are special members, not ordinary object files.

Names are byte strings and need not be UTF-8. GNU archives store long names in a // member and refer to them using /decimal-offset in ordinary member headers. That offset is relative to the long-name table’s payload; entries end in /\n. A short name commonly appears as name.o/ with space padding. The / index member associates symbols with member locations. It accelerates discovery without making the archive one large ELF file or selecting every member.

Thus /17 identifies a name at offset 17 within the long-name table, not archive file offset 17 or member number 17. Members may have duplicate names, so position identifies a member. Ordinary archives embed payloads; thin archives can reference external files and require a different reading contract.

Extraction follows symbol requirements

Create a fresh directory for this independent example: main calls add, which calls scale; unused_helper has no caller.

1
// main.c
2
int add(int, int);
3
int main(void) { return add(1, 2); }

1
// add.c
2
int scale(int);
3
int add(int a, int b) { return scale(a + b); }

1
// other.c
2
int unused_helper(void) { return 99; }

1
// scale.c
2
int scale(int x) { return x * 2; }

1
clang -O1 -fno-pic \
2
  -fno-asynchronous-unwind-tables -c main.c add.c other.c scale.c
3
ar rcs libscale.a scale.o

An archive built with ar¹⁵ contains object-file members and, normally, an index of their defined symbols:

1
$ ar rcs libmath.a add.o other.o
2
$ ar t libmath.a
3
add.o
4
other.o
5
$ nm -s libmath.a | head -4
6

7
Archive index:
8
add in add.o
9
unused_helper in other.o

An ordinary object is admitted unconditionally. An archive member is extracted when it satisfies an unresolved requirement, after which all its definitions and references participate. Extracting one member can create a need for another. GNU ld uses the archive index; if it is missing, ranlib can generate it.

GNU ld scans the command line from left to right, repeatedly extracting from the current archive until that archive cannot satisfy another current requirement. It then moves on. An archive before its users is too early:

1
$ ld -e main libmath.a libscale.a main.o
2
ld: main.o: in function `main':
3
main.c:(.text+0xb): undefined reference to `add'

An archive providing a dependency can also be too early:

1
$ ld -e main main.o libscale.a libmath.a
2
ld: libmath.a(add.o): in function `add':
3
add.c:(.text+0x3): undefined reference to `scale'

main.o libmath.a libscale.a works. Cycles make a single left-to-right ordering insufficient. Build this one:

1
// cm.c
2
int log_value(int);
3
int main(void) { return log_value(42); }

1
// x1.c
2
int fmt(int);
3
int log_value(int x) { return fmt(x); }

1
// x2.c
2
int fmt_impl(int x) { return x; }

1
// y.c
2
int fmt_impl(int);
3
int fmt(int x) { return fmt_impl(x); }

1
clang -O1 -fno-pic \
2
  -fno-asynchronous-unwind-tables -c cm.c x1.c x2.c y.c
3
ar rcs libx.a x1.o x2.o
4
ar rcs liby.a y.o

log_value brings in fmt, which needs an as-yet-unused member of the archive already visited:

1
$ ld -e main cm.o libx.a liby.a
2
ld: liby.a(y.o): in function `fmt':
3
y.c:(.text+0x1): undefined reference to `fmt_impl'

Either repeat libx.a, or group the libraries: cm.o --start-group libx.a liby.a --end-group. A group is rescanned to a fixed point; use it for actual cycles rather than hiding every library in one expensive group.

LLD remembers archive definitions as lazy symbols. A later reference can extract a member from an earlier archive, so these particular backward-reference failures disappear. This does not make arbitrary reordering harmless when multiple libraries offer competing definitions. --warn-backrefs identifies links that depend on the difference:

1
$ ld.lld -e main cm.o libx.a liby.a --warn-backrefs
2
ld.lld: warning: backward reference detected: fmt_impl in liby.a(y.o) refers to libx.a(x2.o)

Weak requirements add another boundary. Prepare these inputs:

1
// u.c
2
extern void hook(void) __attribute__((weak));
3
int main(void) { if (hook) hook(); return 0; }

1
// hook.c
2
void hook(void) {}

1
// m.c
2
extern int counter;
3
int main(void) { return counter; }

1
// w.c
2
__attribute__((weak)) int counter = 3;

1
// strong.c
2
int counter = 9;

1
clang -O1 -fno-pic \
2
  -fno-asynchronous-unwind-tables -fno-builtin -c u.c hook.c m.c w.c strong.c
3
ar rcs libhook.a hook.o
4
ar rcs libcnt.a strong.o
5
ar rcs libweak.a w.o

An unresolved weak hook does not extract hook.o by itself. Nor does a previously supplied weak definition make the linker search for a stronger alternative in an archive:

1
$ ld -e main m.o w.o libcnt.a -o k1
2
$ llvm-objdump -s -j .data k1 | tail -1
3
 402000 03000000                             ....

The value remains 3 because the member defining 9 never enters the link. Conversely, an archive's weak definition can satisfy an unresolved strong requirement. Common symbols are a further GNU/LLD difference: GNU ld may extract an initialized definition to replace common storage; LLD requires --fortran-common for that behavior.

Extraction operates on members, not individual functions. This makes partial replacements surprising:

1
// app.c
2
#include <stddef.h>
3
void *malloc(size_t size) { static unsigned char buf[16]; (void)size; return buf; }
4
void free(void *);
5
int main(void) {
6
#ifdef CALL_FREE
7
    free(malloc(1));
8
#else
9
    (void)malloc(1);
10
#endif
11
    return 0;
12
}

1
// mem.c
2
#include <stddef.h>
3
void *malloc(size_t size) { (void)size; return 0; }
4
void free(void *p) { (void)p; }

1
clang -O1 -fno-pic -fno-asynchronous-unwind-tables -fno-builtin -c mem.c
2
clang -O1 -fno-pic \
3
  -fno-asynchronous-unwind-tables -fno-builtin -c app.c -DCALL_FREE -o app.o
4
clang -O1 -fno-pic \
5
  -fno-asynchronous-unwind-tables -fno-builtin -c app.c -o app-only.o
6
ar rcs libmem.a mem.o
7
ld -e main app-only.o libmem.a -o malloc-only

-fno-builtin preserves the deliberately replaced allocator calls. Without free, the archive member stays out. Once free is needed, its member brings another strong malloc with it:

1
$ ld -e main app.o libmem.a
2
ld: libmem.a(mem.o): in function `malloc':
3
mem.c:(.text+0x0): multiple definition of `malloc'; app.o:app.c:(.text+0x0): first defined here

This particular archive requires coordinated replacement of its member's functions. A real library may use weak definitions or a different member organization. If your replacement wins, other admitted code's references to the same global name also bind to it.

Ask the linker why it extracted a member rather than guessing:

1
$ ld -e main main.o libmath.a libscale.a -Map=-
2
Archive member included to satisfy reference by file (symbol)
3

4
libmath.a(add.o)              main.o (add)
5
libscale.a(scale.o)           libmath.a(add.o) (scale)
6
...
7
$ ld.lld -e main main.o libscale.a libmath.a --why-extract=-
8
reference	extracted	symbol
9
libmath.a(add.o)	libscale.a(scale.o)	scale
10
main.o	libmath.a(add.o)	add

Shared libraries and visibility

A .so contributes definitions from its dynamic symbol table, .dynsym, without copying their code into the output. The output records a dependency through DT_NEEDED; its runtime address remains to be resolved. An ordinary object-file definition takes precedence over a shared-library definition, regardless of their relative order:

1
$ ld -e main main.o libadd.so add.o -o e1
2
$ nm e1 | grep add
3
0000000000401010 T add
4
$ readelf -dW e1 | grep NEEDED
5
 0x0000000000000001 (NEEDED)             Shared library: [libadd.so]

The unused shared dependency remains in this link unless a policy such as --as-needed removes it.

Binding alone cannot express “visible to every object forming this library, but private to the library.” Visibility supplies that boundary:

internal is also defined, with processor-specific details; general tools commonly treat it like hidden. Try:

1
__attribute__((visibility("hidden")))    int internal_counter = 1;
2
__attribute__((visibility("protected"))) int api_level = 2;
3
int bump(void) { return ++internal_counter + api_level; }

1
$ readelf -sW vis.o
2
   Num:    Value          Size Type    Bind   Vis      Ndx Name
3
     3: 0000000000000000    21 FUNC    GLOBAL DEFAULT    2 bump
4
     4: 0000000000000000     4 OBJECT  GLOBAL HIDDEN     4 internal_counter
5
     5: 0000000000000004     4 OBJECT  GLOBAL PROTECTED    4 api_level

The hidden input symbol is still GLOBAL, so another object in the same link can use it. After constructing the library:

1
$ ld.lld -shared vis.o -o libvis.so
2
$ readelf --dyn-syms -W libvis.so
3
   Num:    Value          Size Type    Bind   Vis      Ndx Name
4
     1: 00000000000012e0    21 FUNC    GLOBAL DEFAULT    6 bump
5
     2: 000000000000336c     4 OBJECT  GLOBAL PROTECTED    9 api_level
6
$ readelf -sW libvis.so | grep internal
7
     2: 0000000000003368     4 OBJECT  LOCAL  HIDDEN     9 internal_counter

Other modules cannot find that name through .dynsym:

1
$ ld.lld -e main useh.o libvis.so
2
ld.lld: error: undefined symbol: internal_counter
3
>>> referenced by useh.c
4
>>>               useh.o:(main)

Visibility changes generated code as well:

1
# internal_counter is hidden; api_level is protected
2
0000000000000000 <bump>:
3
       0:      	movl	(%rip), %eax
4
		0000000000000002:  R_X86_64_PC32	internal_counter-0x4
5
       ...
6
       e:      	addl	(%rip), %eax
7
		0000000000000010:  R_X86_64_PC32	api_level-0x4
8
      14:      	retq
9

10
# internal_counter is hidden; api_level is default
11
0000000000000000 <bump>:
12
       0:      	movl	(%rip), %eax
13
		0000000000000002:  R_X86_64_PC32	internal_counter-0x4
14
       ...
15
       e:      	movq	(%rip), %rcx
16
		0000000000000011:  R_X86_64_REX_GOTPCRELX	api_level-0x4
17
      15:      	addl	(%rcx), %eax
18
      17:      	retq

A default-visible variable may be replaced by another module's definition, so PIC¹⁶ commonly obtains its address through the GOT. Clang can use direct PC-relative access for these hidden and protected definitions. GCC 15 remains more conservative for protected data because copy relocations complicate the relationship between the executable's storage and the library's storage. Theory 07 develops that issue.

A missing table entry is not always an error

These assembly files isolate diagnostic boundaries:

1
# ug.s
2
.text
3
.globl main
4
main: ret
5
.globl ghost

1
# dbg.s
2
.text
3
.globl main
4
main: ret
5
.section .debug_info,"",@progbits
6
.quad dref

1
# hg.s
2
.text
3
.globl main
4
main: ret
5
.globl ghost
6
.hidden ghost

1
clang -c ug.s dbg.s hg.s

A GLOBAL UND entry with no relocation need not make a link fail:

1
$ readelf -sW ug.o | grep ghost
2
     2: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT  UND ghost
3
$ readelf -rW ug.o
4

5
There are no relocations in this file.
6
$ ld -e main ug.o -o g_ug; echo $?
7
0
8
$ ld.lld -e main ug.o -o l_ug; echo $?; nm l_ug
9
0
10
                 U ghost
11
0000000000201120 T main

GNU ld drops ghost; LLD retains the undefined table entry. The tools diverge further for a reference from a non-allocated debug section and for an unreferenced hidden undefined symbol:

1
$ ld -e main dbg.o
2
ld: dbg.o:(.debug_info+0x0): undefined reference to `dref'
3
$ ld.lld -e main dbg.o; echo $?
4
0
5
$ readelf -sW hg.o | grep ghost
6
     2: 0000000000000000     0 NOTYPE  GLOBAL HIDDEN   UND ghost
7
$ ld -e main hg.o -o g_hg
8
ld: g_hg: hidden symbol `ghost' isn't defined
9
ld: final link failed: bad value
10
$ ld.lld -e main hg.o; echo $?
11
0

GNU ld rejects both; this LLD version accepts both. GNU's hidden-symbol check requires non-weak symbols with non-default visibility to have a local definition independently of relocation use. Resolution, relocation processing, and visibility validation are distinct checks.

COMDAT chooses a group, not a proof of equivalence

C++ inline functions and template instantiations may need an out-of-line body in several translation units:

1
// t1.cpp
2
inline int version() { return 1; }
3
int from_t1() { return version(); }
4
int main() { return from_t1(); }

1
$ nm t1.o
2
0000000000000000 T _Z7from_t1v
3
0000000000000000 W _Z7versionv
4
0000000000000010 T main
5
$ readelf -gW t1.o
6

7
COMDAT group section [    4] `.group' [_Z7versionv] contains 1 sections:
8
   [Index]    Name
9
   [    5]   .text._Z7versionv

Name mangling produces _Z7versionv: the Itanium C++ ABI¹⁷ encodes the name and parameter information into a string. The function's section belongs to an ELF COMDAT¹⁸ group. Its SHT_GROUP payload contains a flag followed by member section indices; sh_info identifies the symbol supplying the group signature.

GNU ld and LLD retain the first group with a given signature and discard later groups in their entirety. Code, constants, relocation sections, and exception data may have to survive or disappear together. A weak function symbol complements this mechanism but is not a substitute for group selection.

If two supposedly interchangeable groups have different contents, selection can lose a required definition:

1
$ ld -e main gm.o g2.o g1.o
2
ld: gm.o: in function `main':
3
(.text+0x6): undefined reference to `foo_extra'
4

5
$ ld.lld -e main gm.o g2.o g1.o
6
ld.lld: error: relocation refers to a symbol in a discarded section: foo_extra
7
>>> defined in g1.o
8
>>> section group signature: foo
9
>>> prevailing definition is in g2.o
10
...

Here the discarded foo group alone contained foo_extra. LLD identifies the discarded section and prevailing group; GNU ld presents the resulting unresolved reference.

The language's ODR¹⁹ requires the appropriate source-level consistency, including token sequences and name lookup, for permitted repeated definitions. It does not require identical machine bytes across optimization levels. Nor does COMDAT selection prove ODR compliance. Make the second version() return 2:

1
$ ld -e main t1.o t2.o -o o12
2
0000000000401030 <_Z7versionv>:
3
  401034:      	movl	$0x1, %eax
4
$ ld -e main t2.o t1.o -o o21
5
0000000000401010 <_Z7versionv>:
6
  401014:      	movl	$0x2, %eax

At -O0, input order selects the observed answer. Compile the second translation unit at -O1, and its caller may inline 2 while an out-of-line call elsewhere still returns 1. Successful linking has hidden the source inconsistency, not resolved it.

C inline rules differ. In C11, an inline definition without extern need not supply the required external definition:

1
$ nm ci.o
2
0000000000000000 T main
3
                 U twice
4
$ ld -e main ci.o
5
ld: ci.o: in function `main':
6
ci.c:(.text+0x15): undefined reference to `twice'

At -O0, the unresolved call survives. At -O1, inlining can make it disappear. GNU89's historical inline rules differ again. A small header-local C helper usually uses static inline, giving each translation unit its own LOCAL definition.

Definitions supplied by the linker

Some addresses can only be known after layout. Conventional linker-defined symbols expose them:

1
// syn.c
2
#include <stdio.h>
3
#include <elf.h>
4

5
extern char etext[], edata[], end[];
6
extern const Elf64_Ehdr __ehdr_start;
7

8
int counter = 1;     /* .data */
9
int zeros[100];      /* .bss  */
10

11
int main(void) {
12
    printf("__ehdr_start = %p  magic = %.3s\n",
13
           (void *)&__ehdr_start, (const char *)__ehdr_start.e_ident + 1);
14
    printf("etext        = %p\n", (void *)etext);
15
    printf("edata        = %p\n", (void *)edata);
16
    printf("end          = %p\n", (void *)end);
17
    return 0;
18
}

1
$ ./syn
2
__ehdr_start = 0x400000  magic = ELF
3
etext        = 0x405947
4
edata        = 0x408110
5
end          = 0x408958
6
$ readelf -SW syn | grep -E "fini|data|bss"
7
  [ 3] .fini             PROGBITS        0000000000405944 005944 000003 00  AX  0   0  1
8
  [ 4] .rodata           PROGBITS        0000000000406000 006000 000cba 00   A  0   0 32
9
  [ 7] .fini_array       FINI_ARRAY      0000000000407fc8 006fc8 000008 08  WA  0   0  8
10
  [ 8] .data.rel.ro      PROGBITS        0000000000407fd0 006fd0 000010 00  WA  0   0  8
11
  [11] .data             PROGBITS        0000000000408000 007000 000110 00  WA  0   0 32
12
  [12] .bss              NOBITS          0000000000408120 007110 000838 00  WA  0   0 32
13
$ readelf -lW syn | grep LOAD
14
  LOAD           0x000000 0x0000000000400000 0x0000000000400000 0x000190 0x000190 R   0x1000
15
  LOAD           0x001000 0x0000000000401000 0x0000000000401000 0x004947 0x004947 R E 0x1000
16
  LOAD           0x006000 0x0000000000406000 0x0000000000406000 0x000cf4 0x000cf4 R   0x1000
17
  LOAD           0x006fc0 0x0000000000407fc0 0x0000000000407fc0 0x000150 0x000998 RW  0x1000

In this recorded image, __ehdr_start is 0x400000, the mapped ELF header. etext is the executable segment's end, 0x401000 + 0x4947. edata is .data's end, 0x408000 + 0x110. end includes .bss, reaching 0x407fc0 + 0x998.

GNU ld's default script expresses the convention with the location counter .:

1
  PROVIDE (etext = .);
2
  _edata = .;
3
  PROVIDE (edata = .);
4
  _end = .;
5
  PROVIDE (end = .);

PROVIDE only supplies a referenced name that has no input definition. Defining your own int end=3 overrides that fallback; an unconditional script assignment such as _end=. behaves differently. LLD implements corresponding conventional definitions in code rather than a default script.

Related names include _GLOBAL_OFFSET_TABLE_, __start_NAME/__stop_NAME for suitably named sections, and _binary_NAME_start, _end, _size when importing raw binary data. An address-only symbol is commonly declared extern char end[]: array decay gives the address without reading a fictitious stored pointer. xv6²⁰ uses precisely this boundary to begin freeing physical pages after its kernel image.

Resolution as a state machine

LLD's symbol states—Undefined, Lazy, Shared, Common, Defined—turn these cases into merge operations. Strong undefined plus lazy triggers extraction; weak undefined does not. A real definition blocks unnecessary lazy extraction. Strong replaces weak; common replaces weak; ordinary strong replaces common or shared. Two commons combine size and alignment. Visibility constraints merge as well.

Compatibility introduces exceptions. This LLD 21.1.8 check accepts repeated absolute definitions with equal nonzero values:

1
  // Allow absolute symbols with the same value for GNU ld compatibility.
2
  if (!d->section && !errSec && errOffset && d->value == errOffset)
3
    return;

The extra errOffset test explains a small difference from GNU ld:

1
$ ld -e main r.o abs_a5.o abs_b5.o; echo $?     # both define lim = 5
2
0
3
$ ld.lld -e main r.o abs_a5.o abs_b5.o; echo $?
4
0
5
$ ld -e main r.o abs_a0.o abs_b0.o; echo $?     # both define lim = 0
6
0
7
$ ld.lld -e main r.o abs_a0.o abs_b0.o
8
ld.lld: error: duplicate symbol: lim
9
>>> defined in abs_a0.o
10
>>> defined in abs_b0.o
11
$ ld -e main r.o abs_a5.o abs_c6.o              # lim = 5 versus lim = 6
12
ld: abs_c6.o: in function `lim':
13
(*ABS*+0x6): multiple definition of `lim'

Both accept duplicate absolute value 5; only GNU accepts the tested duplicate zero. Both reject differing values. Such version-specific observations belong beside the rule, not inside a claim that every linker must behave identically.

Reading the diagnostics

For an undefined name, check omitted objects, archive order or cycles, visibility, discarded COMDAT groups, and the actual symbol spelling. C and C++ source names may look identical while their symbol names differ:

1
$ nm ver.o verc.o
2

3
ver.o:
4
0000000000000000 T _Z7versionv
5

6
verc.o:
7
0000000000000000 T version
8
$ ld -e main cmain.o ver.o
9
ld: cmain.o: in function `main':
10
cmain.c:(.text+0x10): undefined reference to `version'

An extern "C" declaration on the C++ interface supplies the matching linkage. For duplicates, look for definitions in headers, old common assumptions, or archive members bringing extra definitions.

One error can hide another:

1
$ ld -e main da.o db.o
2
ld: db.o:(.data+0x0): multiple definition of `counter'; da.o:(.data+0x0): first defined here
3
ld: da.o: in function `main':
4
da.c:(.text+0x2): undefined reference to `missing'
5
$ ld.lld -e main da.o db.o
6
ld.lld: error: duplicate symbol: counter
7
>>> defined at da.c
8
>>>            da.o:(counter)
9
>>> defined at db.c
10
>>>            db.o:(.data+0x0)

GNU ld reports both problems here. LLD stops after name-resolution errors, before its relocation scan would diagnose missing. Fixing the duplicate merely exposes the already-existing undefined reference. --allow-multiple-definition chooses the first definition; it suppresses the diagnostic without establishing that this is the intended program.

Use nm -A to inspect all candidates, then trace the decision:

1
$ ld -e main main.o libmath.a libscale.a -y scale
2
ld: libmath.a(add.o): reference to scale
3
ld: libscale.a(scale.o): definition of scale

When invoking a compiler driver, pass that option as -Wl,-y,scale. Trace output records events, not necessarily every ignored definition:

1
$ ld -e main mref.o s.o w.o -y counter
2
ld: mref.o: reference to counter
3
ld: s.o: definition of counter
4
$ ld.lld -e main mref.o s.o w.o -y counter
5
mref.o: reference to counter
6
s.o: definition of counter
7
$ ld.lld -e main mref.o cm.o -y counter
8
mref.o: reference to counter
9
cm.o: common definition of counter
10
cm.o: definition of counter

A losing weak definition may produce no trace line. LLD prints common storage once when encountered and again when converted into an allocated definition. GNU ld has its own differences for ignored common/weak entries. Combine traces with -Map or --why-extract; absence from a trace does not prove absence from a file.

--defsym=limit=real_limit can explicitly create an alias. --wrap=malloc redirects undefined malloc references to __wrap_malloc and undefined __real_malloc references to the original:

1
$ ld -e main wm.o wr.o --wrap=malloc -o wrp
2
0000000000401000 <main>:
3
  401001:      	movl	$0x10, %edi
4
  401006:      	callq	0x401020 <__wrap_malloc>

The qualifier undefined matters. A call whose definition is already in the same object is not rewritten merely because its machine code retains a relocation.

From a definition to an address

Symbol resolution identifies the definition associated with a reference and determines how an absent definition may be treated. For an ordinary definition in an object file, that identity includes the input file, the section, and an offset within that section. A common symbol still describes storage to allocate, with a merged size and alignment. An absolute symbol already has a fixed value. A permitted unresolved weak reference is handled according to the applicable relocation rules; it does not designate a definition in an input section.

A selected definition need not have a final address. Consider an ordinary symbol in a static link whose offset within an input .text section is 8. If layout places that input section at output virtual address 0x401020, the symbol's address is 0x401028. The value 8 is relative to an input section, while 0x401020 belongs to the output address space. A byte offset within the file is a separate coordinate.

Resolution may also retain references that remain unsatisfied. Whether they require an error depends on whether their referring sections survive, the output kind, and the diagnostic rules discussed above. Garbage collection and other later processing still determine which input sections enter the output. Resolution supplies reference relationships, layout places the surviving contents, and relocation writes the required values at the reference sites.

Thus, “add is defined at offset 0 in add.o's .text” identifies a definition without yet determining the bytes of a jump instruction. Once output positions are known, the relocation type, addend, and patch location determine the value to write. The next chapter develops that calculation.

Exercises

The native comparison also records the expected failures.

1. Inspect the opening chapter's main.o, other.o, and prog with nm -A, then relink with -Wl,--trace-symbol=x. Which file defines x, which references it, and does any diagnostic mention double?
2. Statically link a program including the proper headers and returning puts(strdup(argv[0])) < 0. Trace strdup and malloc. Which musl²¹ archive member supplies malloc, and is its definition strong?
3. Inspect syn. Which nm letters describe etext, edata, end, and __ehdr_start?
4. Use REF(name.module) → DEF(name.module) to predict these -O0 links: (a) buf[4] and buf[8] in separate files, with/without -fcommon; (b) strong level=3 and weak level=1, each with a reader; (c) weak functions returning 1 and 2, with the second file first; (d) a hidden secret=7, once linked directly and once supplied through a .so; (e) inconsistent inline ver() functions returning 1 and 2, second file first; (f) a LOCAL static n=1 and an ordinary global n=2.
5. Find the shortest GNU ld library sequence for this graph, a grouped alternative, the error from one p,q,r pass, and LLD's result:

1
main.o -> p1
2
libp.a:  p1.o (p1 -> q1)    p2.o (p2 -> q2)
3
libq.a:  q1.o (q1 -> r1)    q2.o (q2 has no further calls)
4
libr.a:  r1.o (r1 -> p2)

6. Identify the failing stage with GCC 15 via musl-gcc: (a) missing config.h; (b) undeclared twice(21); (c) inline assembly movq %eax,%rbx; (d) declared but undefined twice; (e) a linked libfoo.so absent from the runtime search path; (f) declaring the function answer as an integer and writing to it.

Answers

1. main.o defines x and y as D; other.o shows U x; the recorded executable places x at 0x408008. The trace names a definition in main.o and a reference in other.o. No C double type appears.
2. The trace is:

1
ld: dup.o: reference to strdup
2
ld: .../libc.a(strdup.lo): definition of strdup
3
ld: .../libc.a(strdup.lo): reference to malloc
4
ld: .../libc.a(lite_malloc.lo): definition of malloc

lite_malloc.lo supplies a weak W malloc, so an application strong definition can replace it without the duplicate from the artificial libmem.a example. This program does not call free; adding free can select a different musl allocator implementation.

3. The letters are T, D, B, and lowercase t. These symbols have NOTYPE and zero size; the letters reflect section association and local/global status, not allocated objects of those types.
4. (a) Common merges to 32 bytes; -fno-common fails. (b) Both references select module 1 and read 3. (c) Module 2 wins and main returns 2. (d) Direct objects resolve successfully; the hidden definition is unavailable through the shared library. (e) The first COMDAT group wins, returning 2 in this -O0 experiment; the source violates ODR. (f) Each reference selects its own distinct definition; LOCAL n never competes in the global table.
5. The shortest sequence is main.o libp.a libq.a libr.a libp.a libq.a, because requirements arise in the order p1, q1, r1, p2, q2:

1
libp.a(p1.o)                  main.o (p1)
2
libq.a(q1.o)                  libp.a(p1.o) (q1)
3
libr.a(r1.o)                  libq.a(q1.o) (r1)
4
libp.a(p2.o)                  libr.a(r1.o) (p2)
5
libq.a(q2.o)                  libp.a(p2.o) (q2)

Group the three libraries to permit rescanning. One ungrouped p,q,r pass leaves p2 undefined; omit only the final q from the five-library sequence and q2 remains undefined. LLD resolves this graph with each archive once in any order because their definitions do not compete.

6. (a) Preprocessing: missing include. (b) Compilation: GCC 15 diagnoses the implicit function declaration as an error; older GCC versions might continue to a link failure. (c) Assembly: operand type mismatch for movq; gcc -S itself succeeds. (d) Linking: undefined reference, followed by collect2's²² link-failure message. (e) Loading: musl reports the missing shared library and exits 127; -L. is a link-time search path, while LD_LIBRARY_PATH=. ./b5 supplies the runtime path and returns 42. (f) Execution: writing to the read/execute code segment causes SIGSEGV; the shell reports 139 in the recorded run.

References and terminology

• ELF symbol table rules and section groups.
• GNU ld options and LLD backward-reference diagnostics.
• GCC 10 migration, Clang 11 release notes, and GCC warning options.
• C11 draft N1570, especially 6.9, 6.9.2, and J.5.11; C++ ODR.
• Itanium C++ name mangling, LLD 21.1.8 symbol implementation, and xv6 kernel allocator.
• Exercise forms draw on CMU 15-213 linking and its class activity.