Updated in 2023-09.
In GNU ld,
-r produces a relocatable object file. This
is known as relocatable linking or partial linking. This mode suppresses
many passes done for an executable or shared object output (in
specify 4 different modes. The 4 options are mutually exclusive.
The relocatable output can be used for analysis and binary manipulation. Then, the output can be used to link the final executable or shared object.
clang -pie a.o b.o
Let's go through various linker passes and see how relocatable linking changes the operation.
Find and scan input files
Only relocatable object files, archive files, and linker scripts are allowed as input. To support LTO, another kind of files may be allowed as well. Other files lead to an error.
% ld -r a.o b.so
COMDAT resolution is performed and may discard some sections and hence symbols defined relative to them.
The linker does not do special treatment for symbol versioning.
@@ in symbol names are left as is.
The linker does not define reserved symbols (e.g.
__ehdr_start, _GLOBAL_OFFSET_TABLE_). The linker does not
define encapsulation symbols
__start_$section, _stop_$section) for C identifier name
When LTO is used, LTO assumes all non-local symbols may be used and avoids eliminating them.
Create synthetic sections
The linker does not create synthesized sections
.interp, .gnu.hash, .got, .plt, .comment, etc).
Map input sections and synthetic sections into output sections
GNU ld suppresses the internal linker script. There is no default
One may write a linker script to map sections.
Unfortunately, the linker script language does not support matching section groups. Using a linker script is generally problematic when section groups are present in a relocatable link.
This pass is skipped. The linker does not determine whether GOT/PLT/TLSDESC/TLSGD/etc are needed.
Layout and assign addresses
Output sections just get zero addresses.
The ELF header and the section header table are created as usual. Program headers are suppressed.
Symbols are generally concatenated. However,
symbols need to be coalesced.
Copy section contents to output and resolve relocations
The linker transforms relocations relative to input sections to
relocations relative to output sections. This is similar to
--emit-relocs. Addends may be changed and implicit addends
may result in section content changes.
Some sections may be discarded. For a non-
section, ld.lld applies tombstone values for relocations referencing a
symbol defined relative to a discarded section.
COMMON symbols are not allocated.
For major passes mentioned above, relocatable linking seems to skip
most of them. However, there are a large number of minor features that
relocatable linking shares with regular linking modes
-no-pie, -pie, -shared):
--wrap, --compress-debug-sections, --build-id, -Map,
A linker implementation may use a separate file to describe passes for relocatable linking, but it can easily miss the miscellaneous features.
The output combines sections and loses granularity than using all input files, therefore garbage collection for the final link will be less effective.
-r --gc-sections can be used together. I added the
support to ld.lld in https://reviews.llvm.org/D84131. A relocatable link does
not set a default entry symbol (usually
_start). One shall
set up GC roots (
-u) to use
Output differences due to a relocatable link step
The following two links may produce different output.
clang -pie a.o b.o -lz -ltinfo
clang -r a.o b.o -o r.o
clang -pie r.o -lz -ltinfo
Say both relocatable object files define
(The section names are due to
-fdata-sections.) In the
first link, the 4 input sections are combined in this order:
a.o:.rodata._ZL7indent8, a.o:.rodata._ZL7indent16, b.o:.rodata._ZL7indent8, b.o:.rodata._ZL7indent16.
In the second link, the relocatable link combines
b.o:.rodata._ZL7indent8 (and the same with
.rodata._ZL7indent8), so the final order appears
This grouping effect may affect the output section size due to alignment padding.
glibc provides many crt1 files:
Scrt1.o, rcrt1.o, crt1.o, grcrt1.o, gcrt1.o. These files
share a lot of common code but have customization. glibc uses
relocatable linking to create these files, e.g.
Scrt1.ois the relocatable link output of
crt1.ois the relocatable link output of
elf/Makefile performs the following steps to build
elf/dl-allobjs.osfrom a relocatable link of rtld
- Create link map
elf/librtld.mapfrom a relocatable link of
- Get a list of extracted archive members
elf/librtld.osfrom a relocatable link of
elf/librtld.oswith the version script
Here relocatable links are used for its symbol resolution: figure out
what libc components need to go into
elf/ld.so. The version
ld.map is used to localize the libc symbols.
grub-core/genmod.sh.in uses relocatable linking to
generate modules (e.g.
grub-core/gensyminfo.sh.in dumps symbols into
grub-core/syminfo.lst which is then used to generate a
module dependency list.
tools/objtool/objtool-in.o is a relocatable output
tools/objtool/objtool. I do not know why this
step is needed.
vmlinux.o is a relocatable output for analysis (see
- used by modules
- objtool uses
vmlinux.oto perform "noinstr" (no-instrumentation) validation.
ld.lld -m elf_x86_64 -z noexecstack -r -o vmlinux.o --whole-archive vmlinux.a --no-whole-archive --start-group --end-group
Unsurprisingly, the ClangBuiltLinux project's contributors have identified some interesting corner cases with ld.lld. I think most issues were reported in 2019 and fixed by me.
Sanitizer internal symbolizer
Sanitizers can symbolize with an external tool
llvm-symbolizer or an internal symbolizer.
The internal symbolizer uses a script
- Build a portion of LLVM with
llvm-linkto link LLVM bitcode files.
- Internalize most symbols with
opt -internalize -internalize-public-api-list=$list. Only
__sanitizer_symbolize_*are kept as global symbols.
- Compile the bitcode into
The bitcode compiles with
llvm-link are an alternative
to relocatable linking.
The built runtime libraries will be used by user programs.
clang -fsanitize=address links
--whole-archive mode, so
the output will link in
symbolizer.o with internal
symbolizer functionality. The output may use LLVM as well and the linked
LLVM may be of a different version. The internalization in
symbolizer.o avoids symbol collision.
The previous section mentions a trick with
can achieve the same effect with relocatable linking. After relocatable
objcopy --keep-global-symbol to keep a few
entry symbols and localize the rest symbols. The output can be
distributed as a single
.o file or as part of an archive
llvm-link approach and the relocatable linking
approach need extra care dealing with COMDAT groups. See COMDAT and
section group#GRP_COMDAT for why all COMDAT group signatures should
be kept global to avoid pitfalls.
Find more projects using relocatable linking
Many projects have complex build systems and it's difficult to know
-r is used. I use a ld wrapper
/usr/local/bin/ld to retrieve linker command lines
for i in "$@"; do
if [[ $i == -r ]]; then
echo "$@" >> /tmp/link.log
LD_PRELOAD=path/to/libmimalloc.so ~/Stable/bin/ld.lld --threads=8 "$@"