mirror of
https://github.com/rui314/mold.git
synced 2024-10-05 09:07:10 +03:00
1092 lines
30 KiB
Groff
1092 lines
30 KiB
Groff
.\"
|
|
.\" This manpage is written in mdoc(7).
|
|
.\"
|
|
.\" * Language reference:
|
|
.\" https://man.openbsd.org/mdoc.7
|
|
.\"
|
|
.\" * Atom editor support:
|
|
.\" https://atom.io/packages/language-roff
|
|
.\"
|
|
.\" * Linting changes:
|
|
.\" mandoc -Wall -Tlint /path/to/this.file # BSD
|
|
.\" groff -w all -z /path/to/this.file # GNU/Linux, macOS
|
|
.\"
|
|
.\"
|
|
.\" When making changes, please keep the following in mind:
|
|
.\"
|
|
.\" * In Roff, each new sentence should begin on a new line. This gives
|
|
.\" the Roff formatter better control over text-spacing, line-wrapping,
|
|
.\" and paragraph justification.
|
|
.\"
|
|
.\" * If a line exceeds the maximum length enforced by a project's \
|
|
.\" coding style, prefer line-continuation instead of hard-wrapping; \
|
|
.\" that is, end each incomplete (physical) line with a backslash, \
|
|
.\" like in this paragraph.
|
|
.\"
|
|
.\" * Do not leave blank lines in the markup. If whitespace is desired
|
|
.\" for readability, put a dot in the first column to indicate a null/empty
|
|
.\" command. Comments and horizontal whitespace may optionally follow: each
|
|
.\" of these lines are an example of a null command immediately followed by
|
|
.\" a comment.
|
|
.\"
|
|
.\"=============================================================================
|
|
.
|
|
.Dd $Mdocdate$
|
|
.Dt MOLD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mold
|
|
.Nd a modern linker
|
|
.
|
|
.\"=============================================================================
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl options
|
|
.Ar objfile ...
|
|
.
|
|
.\"=============================================================================
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a faster drop-in replacement for the default GNU
|
|
.Xr ld 1 .
|
|
.
|
|
.\"-----------------------------------------------------------------------------
|
|
.Ss How to use Nm
|
|
See
|
|
.Lk https://github.com/rui314/mold#how-to-use .
|
|
.\"-----------------------------------------------------------------------------
|
|
.Ss Compatibility
|
|
.Nm
|
|
is designed to be a drop-in replacement for the GNU linkers for linking user\
|
|
-land programs.
|
|
If your user-land program cannot be built due to missing command-line options, \
|
|
please file a bug at
|
|
.Lk https://github.com/rui314/mold/issues .
|
|
.
|
|
.Pp
|
|
.Nm
|
|
supports a very limited set of linker script features,
|
|
which is just sufficient to read
|
|
.Pa /usr/lib/x86_64-linux-gnu/libc.so
|
|
on Linux systems (on Linux, that file is despite its name not a shared \
|
|
library but an ASCII linker script that loads a real
|
|
.Pa libc.so
|
|
file.)
|
|
Beyond that, we have no plan to support any linker script features.
|
|
The linker script is an ad-hoc, over-designed, complex language which \
|
|
we believe needs to be disrupted by a simpler mechanism.
|
|
We have a plan to add a replacement for the linker script to
|
|
.Nm
|
|
instead.
|
|
.
|
|
.\"-----------------------------------------------------------------------------
|
|
.Ss Archive symbol resolution
|
|
Traditionally, Unix linkers are sensitive to the order in which input files \
|
|
appear on command line.
|
|
They process input files from the first (left-most) file to the \
|
|
last (right-most) file one-by-one.
|
|
While reading input files, they maintain sets of defined and \
|
|
undefined symbols.
|
|
When visiting an archive file
|
|
.Pf ( Li \.a
|
|
files), they pull out object files to resolve as many undefined symbols as \
|
|
possible and go on to the next input file.
|
|
Object files that weren't pulled out will never have a chance for a second look.
|
|
.
|
|
.Pp
|
|
Due to this semantics, you usually have to add archive files at the end of a \
|
|
command line, so that when a linker reaches archive files, it knows what \
|
|
symbols are remain undefined.
|
|
If you put archive files at the beginning of a command line, a linker doesn't \
|
|
have any undefined symbol, and thus no object files will be pulled out from \
|
|
archives.
|
|
.
|
|
.Pp
|
|
You can change the processing order by
|
|
.Fl -start-group
|
|
and
|
|
.Fl -end-group
|
|
options, though they make a linker slower.
|
|
.
|
|
.Pp
|
|
.Nm
|
|
as well as LLVM
|
|
.Xr lld 1
|
|
linker take a different approach.
|
|
They memorize what symbols can be resolved from archive files instead of \
|
|
forgetting it after processing each archive.
|
|
Therefore,
|
|
.Nm
|
|
and
|
|
.Xr lld 1
|
|
can "go back" in a command line to pull out object files from archives,
|
|
if they are needed to resolve remaining undefined symbols.
|
|
They are not sensitive to the input file order.
|
|
.
|
|
.Pp
|
|
.Fl -start-group
|
|
and
|
|
.Fl -end-group
|
|
are still accepted by
|
|
.Nm
|
|
and
|
|
.Xr lld 1
|
|
for compatibility with traditional linkers,
|
|
but they are silently ignored.
|
|
.
|
|
.\"-----------------------------------------------------------------------------
|
|
.Ss Dynamic symbol resolution
|
|
Some Unix linker features are unable to be understood without understanding \
|
|
the semantics of dynamic symbol resolution.
|
|
Therefore, even though that's not specific to
|
|
.Nm ,
|
|
we'll explain it here.
|
|
.Pp
|
|
We use "ELF module" or just "module" as a collective term to refer an
|
|
executable or a shared library file in the ELF format.
|
|
.Pp
|
|
An ELF module may have lists of imported symbols and exported symbols,
|
|
as well as a list of shared library names from which imported symbols
|
|
should be imported.
|
|
The point is that imported symbols are not bound to any specific shared \
|
|
library until runtime.
|
|
.Pp
|
|
Here is how the Unix dynamic linker resolves dynamic symbols.
|
|
Upon the start of an ELF program, the dynamic linker construct a list of ELF \
|
|
modules which as a whole consist of a complete program.
|
|
The executable file is always at the beginning of the list followed \
|
|
by its depending shared libraries.
|
|
An imported symbol is searched from the beginning of the list to the end.
|
|
If two or more modules define the same symbol, the one that appears first in \
|
|
the list takes precedence over the others.
|
|
.Pp
|
|
This Unix semantics are contrary to systems such as Windows that have the \
|
|
two-level namespace for dynamic symbols.
|
|
On Windows, for example, dynamic symbols are represented as a tuple of
|
|
.Pq Sy symbol-name , shared-library-name ,
|
|
so that each dynamic symbol is guaranteed to be resolved from some specific \
|
|
library.
|
|
.Pp
|
|
Typically, an ELF module that exports a symbol also imports the same symbol.
|
|
Such a symbol is usually resolved to itself, but that's not the case if a \
|
|
module that appears before in the symbol search list provides another \
|
|
definition of the same symbol.
|
|
.Pp
|
|
Let me take
|
|
.Xr malloc 3
|
|
as an example.
|
|
Assume that you define your version of
|
|
.Xr malloc 3
|
|
in your main executable file.
|
|
Then, all
|
|
.Sy malloc
|
|
calls from any module are resolved to your function instead of that in libc,
|
|
because the executable is always at the beginning of the dynamic symbol \
|
|
search list. Note that even
|
|
.Xr malloc 3
|
|
calls within libc are resolved to your definition since libc exports and imports
|
|
.Sy malloc .
|
|
Therefore, by defining
|
|
.Sy malloc
|
|
yourself, you can overwrite a library function, and the
|
|
.Xr malloc 3
|
|
in libc becomes dead code.
|
|
.Pp
|
|
These Unix semantics are tricky and sometimes considered harmful.
|
|
For example, assume that you accidentally define
|
|
.Xr atoi 3
|
|
as a global function in your executable that behaves completely differently \
|
|
from the one in the C standard.
|
|
Then, all
|
|
.Sy atoi
|
|
function calls from any modules (even function calls within libc) are \
|
|
redirected to your function instead of the one in libc which obviously causes \
|
|
a problem.
|
|
That is a somewhat surprising consequence for an accidental name conflict.
|
|
On the other hand, this semantic is sometimes considered useful because it \
|
|
allows users to overwrite library functions without recompiling modules \
|
|
containing them.
|
|
Whether good or bad, you should keep this semantic in mind to understand the \
|
|
Unix linkers behaviors.
|
|
.
|
|
.\"-----------------------------------------------------------------------------
|
|
.Ss Build reproducibility
|
|
.Nm Ap s
|
|
output is deterministic.
|
|
That is, if you pass the same object files and the same command-line options to
|
|
the same version of
|
|
.Nm ,
|
|
it is guaranteed to always produce the same output.
|
|
The linker's internal randomness, such as the timing of thread scheduling or \
|
|
iteration orders of hash tables, doesn't affect the output.
|
|
.
|
|
.Pp
|
|
.Nm
|
|
does not have any host-specific default settings.
|
|
This is contrary to the GNU linkers to which some configurable values, \
|
|
such as system-dependent library search paths, are hard-coded.
|
|
.Nm
|
|
depends only on its command-line arguments.
|
|
.
|
|
.\"=============================================================================
|
|
.Sh OPTIONS
|
|
.Bl -tag -width 6n -compact
|
|
.It Fl -help
|
|
Report usage information to stdout and exit.
|
|
.Pp
|
|
.It Fl v , Fl -version
|
|
Report version information to stdout.
|
|
.Pp
|
|
.It Fl V
|
|
Report version and target information to stdout.
|
|
.Pp
|
|
.It Fl C Ar dir , Fl -directory Ar dir
|
|
Change to
|
|
.Ar dir
|
|
before doing anything.
|
|
.Pp
|
|
.It Fl E , Fl -export-dynamic
|
|
.It Fl -no-export-dynamic
|
|
When creating an executable, using the
|
|
.Fl E
|
|
option causes all global symbols to be put into the dynamic symbol table,
|
|
so that the symbols are visible from other ELF modules at runtime.
|
|
.Pp
|
|
By default, or if
|
|
.Fl -no-export-dynamic
|
|
is given, only symbols
|
|
that are referenced by DSOs at link-time are exported from an executable.
|
|
.Pp
|
|
.It Fl F Ar libname , Fl -filter Ns = Ns Ar libname
|
|
Set the
|
|
.Dv DT_FILTER
|
|
dynamic section field to
|
|
.Ar libname .
|
|
.Pp
|
|
.It Fl I Ns Ar file , Fl -dynamic-linker Ns = Ns Ar file
|
|
.It Fl -no-dynamic-linker
|
|
Set the dynamic linker path to
|
|
.Ar file .
|
|
If no
|
|
.Fl I
|
|
option is given, or if
|
|
.Fl -no-dynamic-linker
|
|
is given, no dynamic linker path is set to an output file.
|
|
This is contrary to the GNU linkers which sets a default dynamic linker path \
|
|
in that case.
|
|
However, this difference doesn't usually make any difference because the \
|
|
compiler driver always passes
|
|
.Fl I
|
|
to a linker.
|
|
.Pp
|
|
.It Fl L Ns Ar dir , Fl -library-path Ns = Ns Ar dir
|
|
Add
|
|
.Ar dir
|
|
to the list of library search paths from which
|
|
.Nm
|
|
searches libraries for the \fB-l\fR option.
|
|
.Pp
|
|
Unlike the GNU linkers,
|
|
.Nm
|
|
does not have the default search paths.
|
|
This difference doesn't usually make any difference because the
|
|
compiler driver always passes all necessary search paths to a linker.
|
|
.Pp
|
|
.It Fl M , Fl -print-map
|
|
Write a map file to stdout.
|
|
.Pp
|
|
.It Fl N , Fl -omagic
|
|
.It Fl -no-omagic
|
|
Force
|
|
.Nm
|
|
to emit an output file with an old-fashioned memory layout.
|
|
First, it makes the first data segment to not be aligned to a page boundary.
|
|
Second, text segments are marked as writable if the option is given.
|
|
.Pp
|
|
.It Fl S , Fl -strip-debug
|
|
Omit
|
|
.Li \.debug_*
|
|
sections from the output file.
|
|
.Pp
|
|
.It Fl T Ar file , Fl -script Ns = Ns Ar file
|
|
Read linker script from
|
|
.Ar file .
|
|
.Pp
|
|
.It Fl X , Fl -discard-locals
|
|
Discard temporary local symbols to reduce the sizes of the \
|
|
symbol table and the string table.
|
|
Temporary local symbols are local symbols starting with
|
|
.Li \.L .
|
|
Compilers usually generate such symbols for unnamed program elements such as \
|
|
string literals or floating-point literals.
|
|
.Pp
|
|
.It Fl e Ar symbol , Fl -entry Ns = Ns Ar symbol
|
|
Use
|
|
.Ar symbol
|
|
as the entry point symbol instead of the default
|
|
entry point symbol
|
|
.Sy _start .
|
|
.Pp
|
|
.It Fl f Ar shlib , Fl -auxiliary Ns = Ns Ar shlib
|
|
Set the
|
|
.Dv DT_AUXILIARY
|
|
dynamic section field to
|
|
.Ar shlib .
|
|
.Pp
|
|
.It Fl h Ar libname , Fl -soname Ns = Ns Ar libname
|
|
Set the
|
|
.Dv DT_SONAME
|
|
dynamic section field to
|
|
.Ar libname .
|
|
This option is used when creating a shared object file.
|
|
Typically, when you create
|
|
.Pf Sy XXX lib Ar foo Ns Sy .so ,
|
|
you want to pass
|
|
.Fl -soname Ns = Ns Ar foo
|
|
to a linker.
|
|
.Pp
|
|
.It Fl l Ns Ar libname
|
|
Search for
|
|
.Pf Sy lib Ar libname Ns Sy \.so
|
|
or
|
|
.Pf Sy lib Ar libname Ns Sy \.a
|
|
from library search paths.
|
|
.Pp
|
|
.It Fl m Op Sy elf_x86_64 | elf_i386 | aarch64linux
|
|
Choose a target.
|
|
.Pp
|
|
.It Fl o Ar file , Fl -output Ns = Ns Ar file
|
|
Use
|
|
.Ar file
|
|
as the output file name instead of the default name
|
|
.Sy a.out .
|
|
.Pp
|
|
.It Fl r , Fl -relocatable
|
|
Instead of generating an executable or a shared object file, combine
|
|
input object files to generate another object file that can be used as
|
|
an input to a linker.
|
|
.Pp
|
|
.It Fl s , Fl -strip-all
|
|
Omit
|
|
.Li \.symtab
|
|
section from the output file.
|
|
.Pp
|
|
.It Fl u Ar symbol , Fl -undefined Ns = Ns Ar symbol
|
|
If
|
|
.Ar symbol
|
|
remains as an undefined symbol after reading all object files,
|
|
and if there is an static archive that contains an object file defining
|
|
.Ar symbol ,
|
|
pull out the object file and link it so that the \
|
|
output file contains a definition of
|
|
.Ar symbol .
|
|
.Pp
|
|
.It Fl -Bdynamic
|
|
Link against shared libraries.
|
|
.Pp
|
|
.It Fl -Bstatic
|
|
Do not link against shared libraries.
|
|
.Pp
|
|
.It Fl -Bsymbolic
|
|
When creating a shared library, make global symbols export-only
|
|
(i.e. do not import the same symbol).
|
|
As a result, references within a shared library is always resolved locally, \
|
|
negating symbol override at runtime.
|
|
See
|
|
.Sx Dynamic symbol resolution
|
|
for more information about symbol imports and exports.
|
|
.Pp
|
|
.It Fl -Bsymbolic-functions
|
|
Have the same effect as
|
|
.Fl -Bsymbolic
|
|
but works only for function symbols.
|
|
Data symbols remains being both imported and exported.
|
|
.Pp
|
|
.It Fl -Bno-symbolic
|
|
Cancel
|
|
.Fl -Bsymbolic
|
|
and
|
|
.Fl -Bsymbolic-functions .
|
|
.Pp
|
|
.It Fl -Map Ns = Ns Ar file
|
|
Write map file to
|
|
.Ar file .
|
|
.Pp
|
|
.It Fl -Tbss Ns = Ns Ar address
|
|
Alias for
|
|
.Fl -section-start=.bss Ns = Ns Ar address .
|
|
.Pp
|
|
.It Fl -Tdata Ns = Ns Ar address
|
|
Alias for
|
|
.Fl -section-start=.data Ns = Ns Ar address .
|
|
.Pp
|
|
.It Fl -Ttext Ns = Ns Ar address
|
|
Alias for
|
|
.Fl -section-start=.text Ns = Ns Ar address .
|
|
.Pp
|
|
.It Fl -allow-multiple-definition
|
|
Normally, the linker reports an error if there are more than one \
|
|
definition of a symbol.
|
|
This option changes the default behavior so that it doesn't report an error \
|
|
for duplicate definitions and instead use the first definition.
|
|
.Pp
|
|
.It Fl -as-needed
|
|
.It Fl -no-as-needed
|
|
By default, shared libraries given to a linker are unconditionally added to \
|
|
the list of required libraries in an output file.
|
|
However, shared libraries after
|
|
.Fl -as-needed
|
|
are added to the list only when at least one symbol is actually used by an \
|
|
object file.
|
|
In other words, shared libraries after
|
|
.Fl -as-needed
|
|
are not added to the list of needed libraries if they are not needed by a program.
|
|
.Pp
|
|
The
|
|
.Fl -no-as-needed
|
|
option restores the default behavior for subsequent files.
|
|
.Pp
|
|
.It Fl -build-id
|
|
.It Fl -build-id Ns = Ns Op Sy none | md5 | sha1 | sha256 | uuid | 0x Ns Ar hexstring
|
|
.It Fl -no-build-id
|
|
Create a
|
|
.Li .note.gnu.build-id
|
|
section containing a byte string to
|
|
uniquely identify an output file.
|
|
.Fl -build-id
|
|
and
|
|
.Fl -build-id Ns = Ns Sy sha256
|
|
compute a 256-bit cryptographic hash of an output file and set it to build-id.
|
|
.Sy md5
|
|
and
|
|
.Sy sha1
|
|
compute the same hash but truncate it to 128 and 160 bits, respectively, \
|
|
before setting it to build-id.
|
|
.Sy uuid
|
|
sets a random 128-bit UUID.
|
|
.Sy 0x Ns Ar hexstring
|
|
sets
|
|
.Ar hexstring .
|
|
.Pp
|
|
.It Fl -chroot Ns = Ns Ar dir
|
|
Set
|
|
.Ar dir
|
|
to root directory.
|
|
.Pp
|
|
.It Fl -compress-debug-sections Ns = Ns Op Sy none | zlib | zlib-gabi | zlib-gnu
|
|
Compress DWARF debug info
|
|
.Pf ( Sy .debug_*
|
|
sections) using the zlib compression algorithm.
|
|
.Pp
|
|
.It Fl -defsym Ns = Ns Ar symbol Ns = Ns Ar value
|
|
Define
|
|
.Ar symbol
|
|
as an alias for
|
|
.Ar value .
|
|
.Pp
|
|
.Ar value
|
|
is either
|
|
an integer (in decimal or hexadecimal with
|
|
.Sq 0x
|
|
prefix) or a symbol name.
|
|
If an integer is given as a value,
|
|
.Ar symbol
|
|
is defined as an absolute symbol with the given value.
|
|
.Pp
|
|
.It Fl -default-symver
|
|
Use soname as a symbol version and append that version to all symbols.
|
|
.Pp
|
|
.It Fl -demangle
|
|
.It Fl -no-demangle
|
|
Demangle C++ symbols in log messages.
|
|
.Pp
|
|
.It Fl -dependency-file Ns = Ns Ar file
|
|
Write a dependency file to
|
|
.Ar file .
|
|
The contents of the written file is readable by
|
|
.Cm make ,
|
|
which defines only one rule with the linker's output file as a target \
|
|
and all input fiels as its prerequisite. Users are expected to include \
|
|
the generated dependency file into a Makefile to automate the \
|
|
dependency management. This option is analogous to the compiler's
|
|
.Fl MM Fl MF
|
|
options.
|
|
.Pp
|
|
.It Fl -dynamic-list Ns = Ns Ar file
|
|
Read a list of dynamic symbols from
|
|
.Ar file .
|
|
.Pp
|
|
.It Fl -eh-frame-hdr
|
|
.It Fl -no-eh-frame-hdr
|
|
Create
|
|
.Li .eh_frame_hdr
|
|
section.
|
|
.Pp
|
|
.It Fl -emit-relocs
|
|
A linker usually "consumes" relocation sections. That is, a linker \
|
|
applies relocations to other sections, and relocation sections themselves \
|
|
are discarded.
|
|
.Pp
|
|
The
|
|
.Fl -emit-relocs
|
|
instructs the linker to leave relocation sections in the output file. \
|
|
Some post-link binary analysis or optimization tools such as LLVM Bolt \
|
|
need them.
|
|
.Pp
|
|
.Nm
|
|
always creates RELA-type relocation sections even if the native \
|
|
ELF format is REL-type so that it is easy to read addends.
|
|
.Pp
|
|
.It Fl -enable-new-dtags
|
|
.It Fl -disable-new-dtags
|
|
By default,
|
|
.Nm
|
|
emits DT_RUNPATH for
|
|
.Fl -rpath .
|
|
If you pass
|
|
.Fl -disable-new-dtags,
|
|
mold emits DT_RPATH for
|
|
.Fl -rpath
|
|
instead.
|
|
.Pp
|
|
.Pp
|
|
.It Fl -exclude-libs Ns = Ns Ar libraries Ns ...
|
|
Mark all symbols in the given
|
|
.Ar libraries
|
|
hidden.
|
|
.Pp
|
|
.It Fl -fini Ns = Ns Ar symbol
|
|
Call
|
|
.Ar symbol
|
|
at unload-time.
|
|
.Pp
|
|
.It Fl -fork
|
|
.It Fl -no-fork
|
|
Spawn a child process and let it do the actual linking.
|
|
When linking a large program, the OS kernel can take a few hundred \
|
|
milliseconds to terminate a
|
|
.Nm
|
|
process.
|
|
.Fl -fork
|
|
hides that latency.
|
|
.Pp
|
|
.It Fl -gc-sections
|
|
.It Fl -no-gc-sections
|
|
Remove unreferenced sections.
|
|
.Pp
|
|
.It Fl -hash-style Ns = Ns Op Sy sysv | gnu | both
|
|
Set hash style.
|
|
.Pp
|
|
.It Fl -icf Ns = Ns Sy all
|
|
.It Fl -no-icf
|
|
Fold identical code.
|
|
.Pp
|
|
.It Fl -image-base Ns = Ns Ar addr
|
|
Set the base address to
|
|
.Ar addr .
|
|
.Pp
|
|
.It Fl -init Ns = Ns Ar symbol
|
|
Call
|
|
.Ar symbol
|
|
at load-time.
|
|
.Pp
|
|
.It Fl -no-undefined
|
|
Report undefined symbols (even with
|
|
.Fl -shared ) .
|
|
.Pp
|
|
.It Fl -noinhibit-exec
|
|
Create an output file even if errors occur.
|
|
.Pp
|
|
.It Fl -pack-dyn-relocs Ns = Ns Op Sy none | relr
|
|
If
|
|
.Sy relr
|
|
is specified, all
|
|
.Li R_*_RELATIVE
|
|
relocations are put into
|
|
.Li .relr.dyn
|
|
section instead of
|
|
.Li .rel.dyn
|
|
or
|
|
.Li .rela.dyn
|
|
section. Since
|
|
.Li .relr.dyn
|
|
section uses a space-efficient encoding scheme, specifying this flag \
|
|
can reduce the size of the output. This is typically most effective \
|
|
for position-independent executable.
|
|
.Pp
|
|
Note that a runtime loader has to support
|
|
.Li .relr.dyn
|
|
to run executables or shared libraries linked with
|
|
.Fl -pack-dyn-relocs=relr ,
|
|
and only ChromeOS, Android and Fuchsia support it as of now in 2022.
|
|
.Pp
|
|
.It Fl -perf
|
|
Print performance statistics.
|
|
.Pp
|
|
.It Fl -pie , -pic-executable
|
|
.It Fl -no-pie , -no-pic-executable
|
|
Create a position-independent executable.
|
|
.Pp
|
|
.It Fl -preload
|
|
Preload object files.
|
|
.Pp
|
|
.It Fl -print-gc-sections
|
|
.It Fl -no-print-gc-sections
|
|
Print removed unreferenced sections.
|
|
.Pp
|
|
.It Fl -print-icf-sections
|
|
.It Fl -no-print-icf-sections
|
|
Print folded identical sections.
|
|
.Pp
|
|
.It Fl -push-state
|
|
.It Fl -pop-state
|
|
.Fl -push-state
|
|
saves the current values of
|
|
.Fl -as-needed ,
|
|
.Fl -whole-archive ,
|
|
.Fl -static ,
|
|
and
|
|
.Fl -start-lib .
|
|
The saved values can be restored by
|
|
.Fl -pop-state .
|
|
.Pp
|
|
.Fl -push-state
|
|
and
|
|
.Fl -pop-state
|
|
pairs can nest.
|
|
.Pp
|
|
These options are useful when you want to construct linker command line \
|
|
options programmatically. For example, if you want to link
|
|
.Ar libfoo.so
|
|
by as-needed basis but don't want to change the global state of
|
|
.Fl -as-needed ,
|
|
you can append "--push-state --as-needed -lfoo --pop-state" to the \
|
|
linker command line options.
|
|
.Pp
|
|
.It Fl -quick-exit
|
|
.It Fl -no-quick-exit
|
|
Use
|
|
.Dv quick_exit
|
|
to exit.
|
|
.Pp
|
|
.It Fl -relax
|
|
.It Fl -no-relax
|
|
Rewrite machine instructions with more efficient ones for some relocations.
|
|
The feature is enabled by default.
|
|
.Pp
|
|
.It Fl -require-defined Ns = Ns Ar symbol
|
|
Like
|
|
.Fl -undefined ,
|
|
except the new symbol must be defined by the end of the link.
|
|
.Pp
|
|
.It Fl -repro
|
|
Embed input files into
|
|
.Dv .repro
|
|
section.
|
|
.Pp
|
|
.It Fl -retain-symbols-file Ns = Ns Ar file
|
|
Keep only symbols listed in
|
|
.Ar file .
|
|
.Pp
|
|
.Ar file
|
|
is a text file
|
|
containing a symbol name on each line.
|
|
.Nm
|
|
discards all local
|
|
symbols as well as global sybmol that are not in
|
|
.Ar file .
|
|
Note that this option removes symbols only from
|
|
.Dv .symtab
|
|
section and does not affect
|
|
.Dv .dynsym
|
|
section, which is used for dynamic linking.
|
|
.Pp
|
|
.It Fl -reverse-sections
|
|
Reverses the order of input sections before assigning them the offsets \
|
|
in the output file.
|
|
.Pp
|
|
.It Fl -rpath Ns = Ns Ar dir
|
|
Add
|
|
.Ar dir
|
|
to runtime search path.
|
|
.Pp
|
|
.It Fl -run Cm command Ar arg Ar
|
|
Run
|
|
.Cm command
|
|
with
|
|
.Nm
|
|
as
|
|
.Pa /usr/bin/ld .
|
|
.Pp
|
|
.It Fl -section-start Ns = Ns Ar section Ns = Ns Ar address
|
|
Set
|
|
.Ar address
|
|
to
|
|
.Ar section .
|
|
.Ar address
|
|
is a hexadecimal number that may start with an optional
|
|
.Sq 0x .
|
|
.Pp
|
|
.It Fl -shared , -Bshareable
|
|
Create a share library.
|
|
.Pp
|
|
.It Fl -shuffle-sections
|
|
.It Fl -shuffle-sections Ns = Ns Ar number
|
|
Randomizes the output by shuffleing the order of input sections before \
|
|
assigning them the offsets in the output file. If
|
|
.Ar number
|
|
is given, it's used as a seed for the random number generator, so that \
|
|
the linker produces the same output as for the same seed. If no seed \
|
|
is given, it uses a random number as a seed.
|
|
.Pp
|
|
.It Fl -spare-dynamic-tags Ns = Ns Ar number
|
|
Reserve given
|
|
.Ar number
|
|
of tags in
|
|
.Dv .dynamic
|
|
section.
|
|
.Pp
|
|
.It Fl -start-lib
|
|
.It Fl -end-lib
|
|
Handle object files between
|
|
.Fl -start-lib
|
|
and
|
|
.Fl -end-lib
|
|
as if they were in an archive file. That means object files between them \
|
|
are linked only when they are needed to resolve undefined symbols. \
|
|
The options are useful if you want to link object files only when they are \
|
|
needed but want to avoid the overhead of running
|
|
.Xr ar 3 .
|
|
.Pp
|
|
.It Fl -static
|
|
Do not link against shared libraries.
|
|
.Pp
|
|
.It Fl -stats
|
|
Print input statistics.
|
|
.Pp
|
|
.It Fl -sysroot Ns = Ns Ar dir
|
|
Set target system root directory to
|
|
.Ar dir .
|
|
.Pp
|
|
.It Fl -thread-count Ns = Ns Ar count
|
|
Use
|
|
.Ar count
|
|
number of threads.
|
|
.Pp
|
|
.It Fl -threads
|
|
.It Fl -no-threads
|
|
Use multiple threads.
|
|
By default,
|
|
.Nm
|
|
uses as many threads as the number of cores or 32, whichever is the smallest.
|
|
The reason why it is capped to 32 is because
|
|
.Nm
|
|
doesn't scale well beyond that point.
|
|
To use only one thread, pass
|
|
.Fl -no-threads
|
|
or
|
|
.Fl -thread-count Ns = Ns Sy 1 .
|
|
.Pp
|
|
.It Fl -trace
|
|
Print name of each input file.
|
|
.Pp
|
|
.It Fl -unique Ns = Ns Ar pattern
|
|
Don't merge input sections that match
|
|
.Ar pattern .
|
|
.Pp
|
|
.It Fl -unresolved-symbols Ns = Ns Op Sy \
|
|
report-all | ignore-all | ignore-in-object-files | ignore-in-shared-libs
|
|
How to handle undefined symbols.
|
|
.Pp
|
|
.It Fl -version-script Ns = Ns Ar file
|
|
Read version script from
|
|
.Ar file .
|
|
.Pp
|
|
.It Fl -warn-common
|
|
.It Fl -no-warn-common
|
|
Warn about common symbols.
|
|
.Pp
|
|
.It Fl -warn-once
|
|
Only warn once for each undefined symbol instead of warn for each relocation
|
|
referring an undefined symbol.
|
|
.Pp
|
|
.It Fl -warn-unresolved-symbols
|
|
.It Fl -error-unresolved-symbols
|
|
Normally, the linker reports an error for unresolved symbols.
|
|
.Fl -warn-unresolved-symbols
|
|
option turns it into a warning.
|
|
.Fl -error-unresolved-symbols
|
|
option restores the default behavior.
|
|
.Pp
|
|
.It Fl -whole-archive
|
|
.It Fl -no-whole-archive
|
|
When archive files
|
|
.Pf ( Sy .a
|
|
files) are given to a linker, only object
|
|
files that are needed to resolve undefined symbols are extracted from
|
|
them and linked to an output file.
|
|
.Fl -whole-archive
|
|
changes that behavior for subsequent archives so that a linker extracts all
|
|
object files and link them to an output.
|
|
For example, if you are creating a shared object file and you want to include \
|
|
all archive members to the output, you should pass
|
|
.Fl -whole-archive .
|
|
.Fl -no-whole-archive
|
|
restores the default behavior for subsequent archives.
|
|
.Pp
|
|
.It Fl -wrap Ns = Ns Ar symbol
|
|
Make
|
|
.Ar symbol
|
|
to be resolved to
|
|
.Sy __wrap_ Ns Ar symbol .
|
|
The original symbol can be resolved as
|
|
.Sy __real_ Ns Ar symbol .
|
|
This option is typically used for wrapping an existing function.
|
|
.Pp
|
|
.It Fl z Cm cet-report Ns = Ns Op Sy none | warning | error
|
|
Intel Control-flow Enforcement Technology (CET) is a new x86 feature \
|
|
available since Tiger Lake which is released in 2020.
|
|
It defines new instructions to harden security to protect programs from \
|
|
control hijacking attacks. You can tell compiler to use the feature by \
|
|
specifying the
|
|
.Fl fcf-protection
|
|
flag.
|
|
.Pp
|
|
.Fl z Cm cet-report
|
|
flag is used to make sure that all object files were compiled with a correct
|
|
.Fl fcf-protection
|
|
flag. If
|
|
.Sy warning
|
|
or
|
|
.Sy error
|
|
are given,
|
|
.Nm
|
|
prints out a warning or an error message if an object file was not compiled \
|
|
with the compiler flag.
|
|
.Pp
|
|
.Nm
|
|
looks for
|
|
.Li GNU_PROPERTY_X86_FEATURE_1_IBT
|
|
bit and
|
|
.Li GNU_PROPERTY_X86_FEATURE_1_SHSTK
|
|
bit in
|
|
.Li .note.gnu.property
|
|
section to determine whether or not an object file was compiled with
|
|
.Fl fcf-protection .
|
|
.Pp
|
|
.It Fl z Cm now
|
|
.It Fl z Cm lazy
|
|
By default, functions referring other ELF modules are resolved by the
|
|
dynamic linker when they are called for the first time.
|
|
.Fl z Cm now
|
|
marks an executable or a shared library file so that all dynamic
|
|
symbols are loaded when a file is loaded to memory.
|
|
.Fl z Cm lazy
|
|
restores the default behavior.
|
|
.Pp
|
|
.It Fl z Cm origin
|
|
Mark object requiring immediate
|
|
.Dv $ORIGIN
|
|
processing at runtime.
|
|
.Pp
|
|
.It Fl z Cm ibt
|
|
Turn on
|
|
.Li GNU_PROPERTY_X86_FEATURE_1_IBT
|
|
bit in
|
|
.Li .note.gnu.property
|
|
section to indicate that the output uses IBT-enabled PLT. This option implies
|
|
.Fl z Cm ibtplt .
|
|
.Pp
|
|
.It Fl z Cm ibtplt
|
|
Generate Intel Branch Tracking (IBT)-enabled PLT.
|
|
.Pp
|
|
IBT is part of Intel Control-flow Enforcement Technology (CET).
|
|
IBT is a new x86 feature available since Tiger Lake which is released in 2020.
|
|
If IBT is enabled, all indirect branch instructions have to branch to a \
|
|
so-called "landing pad" instruction. Landing pad itself is a no-op, but \
|
|
it works as a marker that branching to that instruction is expected.
|
|
If there's no landing pad after branch, the CPU raises an exception.
|
|
This mechanism makes ROP attacks difficult.
|
|
.Pp
|
|
Since PLT can be used as an indirect branch target, we need a different \
|
|
instruction sequence for IBT-enabled PLT. If
|
|
.Sy -z Cm ibtplt
|
|
is specified,
|
|
.Nm
|
|
generates PLT entries that start with a landing pad. The size of IBT-enabled \
|
|
PLT is 24 bytes as opposed to 16 bytes regular PLT.
|
|
.Pp
|
|
.It Fl z Cm execstack
|
|
.It Fl z Cm noexecstack
|
|
By default, the pages for the stack area (i.e. the pages where local
|
|
variables reside) are not executable for security reasons.
|
|
.Fl z Cm execstack
|
|
makes it executable.
|
|
.Fl z Cm noexecstack
|
|
restores the default behavior.
|
|
.Pp
|
|
.It Fl z Cm keep-text-section-prefix
|
|
.It Fl z Cm nokeep-text-section-prefix
|
|
Keep
|
|
.Dv .text.hot ,
|
|
.Dv .text.unknown ,
|
|
.Dv .text.unlikely ,
|
|
.Dv .text.startup
|
|
and
|
|
.Dv .text.exit
|
|
as separate sections in the final binary.
|
|
.Pp
|
|
.It Fl z Cm relro
|
|
.It Fl z Cm norelro
|
|
Some sections such as
|
|
.Dv .dynamic
|
|
have to be writable only during an executable or \
|
|
a shared library file is being loaded to memory.
|
|
Once the dynamic linker finishes its job,
|
|
such sections won't be mutated by anyone.
|
|
As a security mitigation,
|
|
it is preferred to make such segments read-only during program execution.
|
|
.Pp
|
|
.Fl z Cm relro
|
|
puts such sections into a special section called
|
|
.Dv relro .
|
|
The dynamic linker make a relro segment read-only after it finishes its job.
|
|
.Pp
|
|
By default,
|
|
.Nm
|
|
generates a
|
|
.Sy relro
|
|
segment.
|
|
.Fl z Cm norelro
|
|
disables the feature.
|
|
.Pp
|
|
.It Fl z Cm separate-loadable-segments
|
|
.It Fl z Cm separate-code
|
|
.It Fl z Cm noseparate-code
|
|
If one memory page contains multiple segments,
|
|
the page protection bits are set in such a way that needed attributes \
|
|
(writable or executable) are satisifed for all segments.
|
|
This usually happens at a boundary of two segments with two different \
|
|
attributes.
|
|
.Pp
|
|
.Cm separate-loadable-segments
|
|
adds paddings between segments with different attributes so that they \
|
|
do not share the same page.
|
|
This is the default.
|
|
.Pp
|
|
.Cm separate-code
|
|
adds paddings only between executable and non-executable segments.
|
|
.Pp
|
|
.Cm noseparate-code
|
|
does not add any paddings between segments.
|
|
.Pp
|
|
.It Fl z Cm defs
|
|
.It Fl z Cm nodefs
|
|
Report undefined symbols (even with
|
|
.Fl -shared ) .
|
|
.Pp
|
|
.It Fl z Cm shstk
|
|
Enforce shadow stack by turning GNU_PROPERTY_X86_FEATURE_1_SHSTK bit in
|
|
.Li .note.gnu.property
|
|
output section. Shadow stack is part of Intel Control-flow Enforcement \
|
|
Technology (CET), which is available since Tiger Lake (2020).
|
|
.Pp
|
|
.It Fl z Cm text
|
|
.It Fl z Cm notext , Fl z Cm textoff
|
|
.Nm
|
|
by default reports an error if dynamic relocations are created in read-only \
|
|
sections.
|
|
If
|
|
.Fl z Cm notext
|
|
or
|
|
.Fl z Cm textoff
|
|
are given,
|
|
.Nm
|
|
creates such dynamic relocations without reporting an error.
|
|
.Fl z Cm text
|
|
restores the default behavior.
|
|
.Pp
|
|
.It Fl z Cm max-page-size
|
|
Some CPU ISAs support multiple different memory page sizes.
|
|
This option specifies the maximum page size that an output binary can run on.
|
|
If you specify a large value, the output can run on both large and small page \
|
|
systems, but it wastes a bit of memory at page boundaries on systems with \
|
|
small pages.
|
|
.Pp
|
|
The default value is 4 KiB for i386, x86-64 and RISC-V, and 64 KiB for ARM64.
|
|
.Pp
|
|
.It Fl z Cm nodefaultlib
|
|
Make the dynamic loader to ignore default search paths.
|
|
.Pp
|
|
.It Fl z Cm nodelete
|
|
Mark DSO non-deletable at runtime.
|
|
.Pp
|
|
.It Fl z Cm nodlopen
|
|
Mark DSO not available to
|
|
.Xr dlopen 3 .
|
|
.Pp
|
|
.It Fl z Cm nodump
|
|
Mark DSO not available to
|
|
.Xr dldump 3 .
|
|
.Pp
|
|
.It Fl z Cm nocopyreloc
|
|
Do not create copy relocations.
|
|
.Pp
|
|
.It Fl z Cm initfirst
|
|
Mark DSO to be initialized first at runtime.
|
|
.Pp
|
|
.It Fl z Cm interpose
|
|
Mark object to interpose all DSOs but executable.
|
|
.Pp
|
|
.ig
|
|
.It Fl (
|
|
.It Fl )
|
|
.It Fl EL
|
|
.It Fl O Ns Ar number
|
|
.It Fl -allow-shlib-undefined
|
|
.It Fl -color-diagnostics
|
|
.It Fl -dc
|
|
.It Fl -dp
|
|
.It Fl -end-group
|
|
.It Fl -fatal-warnings
|
|
.It Fl -gdb-index
|
|
.It Fl -no-add-needed
|
|
.It Fl -no-allow-shlib-undefined
|
|
.It Fl -no-copy-dt-needed-entries
|
|
.It Fl -no-fatal-warnings
|
|
.It Fl -no-undefined-version
|
|
.It Fl -nostdlib
|
|
.It Fl -plugin
|
|
.It Fl -plugin-opt
|
|
.It Fl -rpath-link Ns = Ns Ar dir
|
|
.It Fl -sort-common
|
|
.It Fl -sort-section
|
|
.It Fl -start-group
|
|
.It Fl -warn-constructors
|
|
.It Fl -warn-once
|
|
.It Fl fix-cortex-a53-835769
|
|
.It Fl fix-cortex-a53-843419
|
|
.It Fl z combreloc
|
|
.It Fl z common-page-size
|
|
.It Fl z nocombreloc
|
|
Ignored
|
|
..
|
|
.
|
|
.El \" End of options list
|
|
.
|
|
.\"=============================================================================
|
|
.Sh SEE ALSO
|
|
.Xr gold 1 ,
|
|
.Xr ld 1 ,
|
|
.Xr elf 5
|
|
.Xr ld.so 8
|
|
.
|
|
.\"=============================================================================
|
|
.Sh AUTHORS
|
|
.An Rui Ueyama Aq Mt ruiu@cs.stanford.edu
|
|
.
|
|
.\"=============================================================================
|
|
.Sh BUGS
|
|
Report bugs to
|
|
.Lk https://github.com/rui314/mold/issues .
|