aboutsummaryrefslogtreecommitdiffstats
path: root/docs/ld.lld.1
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ld.lld.1')
-rw-r--r--docs/ld.lld.1112
1 files changed, 87 insertions, 25 deletions
diff --git a/docs/ld.lld.1 b/docs/ld.lld.1
index c432aacf7f73..1746ae9f5fd4 100644
--- a/docs/ld.lld.1
+++ b/docs/ld.lld.1
@@ -14,7 +14,6 @@
.Nm ld.lld
.Op Ar options
.Ar objfile ...
-
.Sh DESCRIPTION
A linker takes one or more object, archive, and library files, and combines
them into an output file (an executable, a shared library, or another object
@@ -40,8 +39,18 @@ All these targets are always supported however
was built, so you can always use
.Nm
as a native linker as well as a cross linker.
-
.Sh OPTIONS
+Many options have both a single-letter and long form.
+When using the long form options other than those beginning with the
+letter
+.Cm o
+may be specified using either one or two dashes preceding the option name.
+Long options beginning with
+.Cm o
+require two dashes to avoid confusion with the
+.Fl o Ar path
+option.
+.Pp
.Bl -tag -width indent
.It Fl -allow-multiple-definition
Do not error if a symbol is defined multiple times.
@@ -164,8 +173,8 @@ A value of zero indicates that there is no limit.
.It Fl -error-unresolved-symbols
Report unresolved symbols as errors.
.It Fl -execute-only
-Mark executable sections unreadable. This option is currently only
-supported on AArch64.
+Mark executable sections unreadable.
+This option is currently only supported on AArch64.
.It Fl -exclude-libs Ns = Ns Ar value
Exclude static libraries from automatic export.
.It Fl -export-dynamic , Fl E
@@ -221,13 +230,16 @@ Enable safe identical code folding.
Disable identical code folding.
.It Fl -ignore-data-address-equality
Ignore address equality of data. C/C++ requires each data to have a unique
-address. This option allows lld to do unsafe optimization that breaks the
+address.
+This option allows lld to do unsafe optimization that breaks the
requirement: create copies of read-only data or merge two or more read-only data
that happen to have the same value.
.It Fl -ignore-function-address-equality
-Ignore address equality of functions. This option allows non-PIC calls to a
-function with non-default visibility in a shared object. The function may have
-different addresses within the executable and within the shared object.
+Ignore address equality of functions.
+This option allows non-PIC calls to a function with non-default visibility in
+a shared object.
+The function may have different addresses within the executable and within the
+shared object.
.It Fl -image-base Ns = Ns Ar value
Set the base address to
.Ar value .
@@ -333,7 +345,8 @@ is
.Cm binary ,
which produces output with no ELF header.
.It Fl -omagic , Fl N
-Set the text and data sections to be readable and writable, do not page align sections, link against static libraries.
+Set the text and data sections to be readable and writable, do not page align
+sections, link against static libraries.
.It Fl -opt-remarks-filename Ar file
Write optimization remarks in YAML format to
.Ar file .
@@ -343,8 +356,8 @@ Filter optimization remarks by only allowing the passes matching
.It Fl -opt-remarks-with-hotness
Include hotness information in the optimization remarks file.
.It Fl -orphan-handling Ns = Ns Ar mode
-Control how orphan sections are handled. An orphan section is one not
-specifically mentioned in a linker script.
+Control how orphan sections are handled.
+An orphan section is one not specifically mentioned in a linker script.
.Ar mode
may be:
.Pp
@@ -370,17 +383,21 @@ may be:
.Pp
.Bl -tag -width 2n -compact
.It Cm none
-Don't pack. Dynamic relocations are encoded in SHT_REL(A).
+Do not pack.
+Dynamic relocations are encoded in SHT_REL(A).
.It Cm android
Pack dynamic relocations in SHT_ANDROID_REL(A).
.It Cm relr
-Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_REL(A).
+Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in
+SHT_REL(A).
.It Cm android+relr
-Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_ANDROID_REL(A).
+Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in
+SHT_ANDROID_REL(A).
.El
.Pp
.Cm none
-is the default. If
+is the default.
+If
.Fl -use-android-relr-tags
is specified, use SHT_ANDROID_RELR instead of SHT_RELR.
.Pp
@@ -407,8 +424,14 @@ Undo the effect of
.Fl -push-state.
.It Fl -relocatable , Fl r
Create relocatable object file.
-.It Fl -reproduce Ns = Ns Ar value
-Dump linker invocation and input files for debugging.
+.It Fl -reproduce Ns = Ns Ar path
+Write a tar file to
+.Ar path,
+containing all the input files needed to reproduce the link, a text file called
+response.txt containing the command line options and a text file called
+version.txt containing the output of ld.lld --version.
+The archive when
+unpacked can be used to re-run the linker with the same options and input files.
.It Fl -retain-symbols-file Ns = Ns Ar file
Retain only the symbols listed in the file.
.It Fl -rpath Ns = Ns Ar value , Fl R Ar value
@@ -424,6 +447,8 @@ and
.It Fl -script Ns = Ns Ar file , Fl T Ar file
Read linker script from
.Ar file .
+If multiple linker scripts are given, they are processed as if they
+were concatenated in the order they appeared on the command line.
.It Fl -section-start Ns = Ns Ar section Ns = Ns Ar address
Set address of section.
.It Fl -shared , Fl -Bsharable
@@ -512,13 +537,15 @@ to include the object file in the output file.
.It Fl -undefined-glob Ns = Ns Ar pattern
Synonym for
.Fl -undefined ,
-except that it takes a glob pattern. In a glob pattern,
+except that it takes a glob pattern.
+In a glob pattern,
.Cm *
matches zero or more characters,
.Cm ?
matches any single character, and
.Cm [...]
-matches the characters within brackets. All symbols that match
+matches the characters within brackets.
+All symbols that match
a given pattern are handled as if they were given as arguments of
.Fl -undefined .
.It Fl -unresolved-symbols Ns = Ns Ar value
@@ -545,13 +572,17 @@ Warn about duplicate common symbols.
Warn about using ifunc symbols in conjunction with text relocations.
Older versions of glibc library (2.28 and earlier) has a bug that causes
the segment that includes ifunc symbols to be marked as not executable when
-they are relocated. As a result, although the program compiles and links
+they are relocated.
+As a result, although the program compiles and links
successfully, it gives segmentation fault when the instruction pointer reaches
-an ifunc symbol. Use -warn-ifunc-textrel to let lld give a warning, if the
+an ifunc symbol.
+Use -warn-ifunc-textrel to let lld give a warning, if the
code may include ifunc symbols, may do text relocations and be linked with
-an older glibc version. Otherwise, there is no need to use it, as the default
-value does not give a warning. This flag has been introduced in late 2018,
-has no counter part in ld and gold linkers, and may be removed in the future.
+an older glibc version.
+Otherwise, there is no need to use it, as the default value does not give a
+warning.
+This flag has been introduced in late 2018, has no counter part in ld and gold
+linkers, and may be removed in the future.
.It Fl -warn-unresolved-symbols
Report unresolved symbols as warnings.
.It Fl -whole-archive
@@ -560,18 +591,21 @@ Force load of all members in a static library.
Use wrapper functions for symbol.
.It Fl z Ar option
Linker option extensions.
-.Bl -tag -width indent
+.Bl -tag -width indent -compact
+.Pp
.It Cm execstack
Make the main stack executable.
Stack permissions are recorded in the
.Dv PT_GNU_STACK
segment.
+.Pp
.It Cm global
Sets the
.Dv DF_1_GLOBAL flag in the
.Dv DYNAMIC
section.
Different loaders can decide how to handle this flag on their own.
+.Pp
.It Cm ifunc-noplt
Do not emit PLT entries for ifunc symbols.
Instead, emit text relocations referencing the resolver.
@@ -580,64 +614,78 @@ environments where text relocations do not have the usual drawbacks.
This option must be combined with the
.Fl z Li notext
option.
+.Pp
.It Cm initfirst
Sets the
.Dv DF_1_INITFIRST
flag to indicate the module should be initialized first.
+.Pp
.It Cm interpose
Set the
.Dv DF_1_INTERPOSE
flag to indicate to the runtime linker that the object is an interposer.
During symbol resolution interposers are searched after the application
but before other dependencies.
+.Pp
.It Cm muldefs
Do not error if a symbol is defined multiple times.
The first definition will be used.
This is a synonym for
.Fl -allow-multiple-definition.
+.Pp
.It Cm nocombreloc
Disable combining and sorting multiple relocation sections.
+.Pp
.It Cm nocopyreloc
Disable the creation of copy relocations.
+.Pp
.It Cm nodefaultlib
Set the
.Dv DF_1_NODEFLIB
flag to indicate that default library search paths should be ignored.
+.Pp
.It Cm nodelete
Set the
.Dv DF_1_NODELETE
flag to indicate that the object cannot be unloaded from a process.
+.Pp
.It Cm nodlopen
Set the
.Dv DF_1_NOOPEN
flag to indicate that the object may not be opened by
.Xr dlopen 3 .
+.Pp
.It Cm norelro
Do not indicate that portions of the object shold be mapped read-only
after initial relocation processing.
The object will omit the
.Dv PT_GNU_RELRO
segment.
+.Pp
.It Cm notext
Allow relocations against read-only segments.
Sets the
.Dv DT_TEXTREL flag in the
.Dv DYNAMIC
section.
+.Pp
.It Cm now
Set the
.Dv DF_BIND_NOW
flag to indicate that the run-time loader should perform all relocation
processing as part of object initialization.
By default relocations may be performed on demand.
+.Pp
.It Cm origin
Set the
.Dv DF_ORIGIN
flag to indicate that the object requires
$ORIGIN
processing.
+.Pp
.It Cm retpolineplt
Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
+.Pp
.It Cm rodynamic
Make the
.Li .dynamic
@@ -645,6 +693,18 @@ section read-only.
The
.Dv DT_DEBUG
tag will not be emitted.
+.Pp
+.It Cm separate-loadable-segments
+.It Cm separate-code
+.It Cm noseparate-code
+Specify whether two adjacent PT_LOAD segments are allowed to overlap in pages.
+.Cm noseparate-code
+(default) allows overlap.
+.Cm separate-code
+allows overlap between two executable segments, or two non-executable segments.
+.Cm separate-loadable-segments
+disallows overlap.
+.Pp
.It Cm stack-size Ns = Ns Ar size
Set the main thread's stack size to
.Ar size .
@@ -652,9 +712,11 @@ The stack size is recorded as the size of the
.Ar size .
.Dv PT_GNU_STACK
program segment.
+.Pp
.It Cm text
Do not allow relocations against read-only segments.
This is the default.
+.Pp
.It Cm wxneeded
Create a
.Dv PT_OPENBSD_WXNEEDED