1ae9615a9a
-z interpose sets the DF_1_INTERPOSE flag, marking the object as an interposer. Committed upstream as LLVM r342239. PR: 230604 Reported by: jbeich Reviewed by: markj Approved by: re (kib) MFC after: 1 week Relnotes: Yes Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D17172
526 lines
13 KiB
Groff
526 lines
13 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2018 Kirill Ponomarev
|
|
.\" Copyright (c) 2018 The FreeBSD Foundation
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 14, 2018
|
|
.Dt LD.LLD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ld.lld
|
|
.Nd ELF linker from the LLVM project
|
|
.Sh SYNOPSIS
|
|
.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
|
|
file).
|
|
It relocates code and data from the input files and resolves symbol
|
|
references between them.
|
|
.Pp
|
|
.Nm
|
|
is a drop-in replacement for the GNU BFD and gold linkers.
|
|
It accepts most of the same command line arguments and linker scripts
|
|
as GNU linkers.
|
|
.Pp
|
|
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 preceeding the option name.
|
|
Long options beginning with
|
|
.Cm o
|
|
require two dashes to avoid confusion with the
|
|
.Fl o Ar path
|
|
option.
|
|
.Pp
|
|
These options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl -allow-multiple-definition
|
|
Do not error if a symbol is defined multiple times.
|
|
The first definition will be used.
|
|
.It Fl -as-needed
|
|
Only set
|
|
.Dv DT_NEEDED
|
|
for shared libraries if used.
|
|
.It Fl -auxiliary Ar value
|
|
Set the
|
|
.Dv DT_AUXILIARY
|
|
field to the specified name.
|
|
.It Fl -Bdynamic
|
|
Link against shared libraries.
|
|
.It Fl -Bstatic
|
|
Do not link against shared libraries.
|
|
.It Fl -Bsymbolic-functions
|
|
Bind defined function symbols locally.
|
|
.It Fl -Bsymbolic
|
|
Bind defined symbols locally.
|
|
.It Fl -build-id= Ns Ar value
|
|
Generate a build ID note.
|
|
.Ar value
|
|
may be one of
|
|
.Cm md5 ,
|
|
.Cm sha1 ,
|
|
.Cm tree ,
|
|
.Cm uuid ,
|
|
.Cm 0x Ns Ar hex-string ,
|
|
and
|
|
.Cm none .
|
|
.Cm tree
|
|
is an alias for
|
|
.Cm sha1 .
|
|
Build-IDs of type
|
|
.Cm md5 ,
|
|
.Cm sha1 ,
|
|
and
|
|
.Cm tree
|
|
are calculated from the object contents.
|
|
.It Fl -build-id
|
|
Generate a build ID note.
|
|
.It Fl -color-diagnostics= Ns Ar value
|
|
Use colors in diagnostics.
|
|
.Ar value
|
|
may be one of
|
|
.Cm always ,
|
|
.Cm auto ,
|
|
and
|
|
.Cm never .
|
|
.Cm auto
|
|
enables color if and only if output is to a terminal.
|
|
.It Fl -color-diagnostics
|
|
Alias for
|
|
.Fl -color-diagnostics= Ns Cm auto .
|
|
.It Fl -compress-debug-sections= Ns Ar value
|
|
Compress DWARF debug sections.
|
|
.Ar value
|
|
may be
|
|
.Cm none
|
|
or
|
|
.Cm zlib .
|
|
.It Fl -define-common
|
|
Assign space to common symbols.
|
|
.It Fl -defsym= Ns Ar symbol= Ns Ar expression
|
|
Define a symbol alias.
|
|
.Ar expression
|
|
may be another symbol or a linker script expression.
|
|
For example,
|
|
.Fl -defsym= Ns Cm foo= Ns Cm bar
|
|
or
|
|
.Fl -defsym= Ns Cm foo= Ns Cm bar+0x100 .
|
|
.It Fl -demangle
|
|
Demangle symbol names.
|
|
.It Fl -disable-new-dtags
|
|
Disable new dynamic tags.
|
|
.It Fl -discard-all
|
|
Delete all local symbols.
|
|
.It Fl -discard-locals
|
|
Delete temporary local symbols.
|
|
.It Fl -discard-none
|
|
Keep all symbols in the symbol table.
|
|
.It Fl -dynamic-linker Ar value
|
|
Specify the dynamic linker to be used for a dynamically linked executable.
|
|
This is recorded in an ELF segment of type
|
|
.Dv PT_INTERP .
|
|
.It Fl -dynamic-list Ar file
|
|
Read a list of dynamic symbols from
|
|
.Ar file .
|
|
.It Fl -eh-frame-hdr
|
|
Request creation of
|
|
.Li .eh_frame_hdr
|
|
section and
|
|
.Dv PT_GNU_EH_FRAME
|
|
segment header.
|
|
.It Fl -emit-relocs
|
|
Generate relocations in the output.
|
|
.It Fl -enable-new-dtags
|
|
Enable new dynamic tags.
|
|
.It Fl -end-lib
|
|
End a grouping of objects that should be treated as if they were together
|
|
in an archive.
|
|
.It Fl -entry Ar entry
|
|
Name of entry point symbol.
|
|
.It Fl -error-limit Ar value
|
|
Maximum number of errors to emit before stopping.
|
|
A value of zero indicates that there is no limit.
|
|
.It Fl -error-unresolved-symbols
|
|
Report unresolved symbols as errors.
|
|
.It Fl -exclude-libs Ar value
|
|
Exclude static libraries from automatic export.
|
|
.It Fl -export-dynamic-symbol Ar symbol
|
|
Include
|
|
.Ar symbol
|
|
in the dynamic symbol table.
|
|
.It Fl -export-dynamic
|
|
Put symbols in the dynamic symbol table.
|
|
.It Fl -fatal-warnings
|
|
Treat warnings as errors.
|
|
.It Fl -filter= Ns Ar value
|
|
Set the
|
|
.Dv DT_FILTER
|
|
field to the specified value.
|
|
.It Fl -fini Ar symbol
|
|
Specify a finalizer function.
|
|
.It Fl -format= Ns Ar input-format
|
|
Specify the format of the inputs following this option.
|
|
.Ar input-format
|
|
may be one of
|
|
.Cm binary ,
|
|
.Cm elf ,
|
|
and
|
|
.Cm default .
|
|
.Cm default
|
|
is a synonym for
|
|
.Cm elf .
|
|
.It Fl -gc-sections
|
|
Enable garbage collection of unused sections.
|
|
.It Fl -gdb-index
|
|
Generate
|
|
.Li .gdb_index
|
|
section.
|
|
.It Fl -hash-style Ar value
|
|
Specify hash style.
|
|
.Ar value
|
|
may be
|
|
.Cm sysv ,
|
|
.Cm gnu ,
|
|
or
|
|
.Cm both .
|
|
.Cm both
|
|
is the default.
|
|
.It Fl -help
|
|
Print a usage message.
|
|
.It Fl -icf=all
|
|
Enable identical code folding.
|
|
.It Fl -icf=none
|
|
Disable identical code folding.
|
|
.It Fl -image-base= Ns Ar value
|
|
Set the base address to
|
|
.Ar value .
|
|
.It Fl -init Ar symbol
|
|
Specify an initializer function.
|
|
.It Fl -lto-aa-pipeline= Ns Ar value
|
|
AA pipeline to run during LTO.
|
|
Used in conjunction with
|
|
.Fl -lto-newpm-passes .
|
|
.It Fl -lto-newpm-passes= Ns Ar value
|
|
Passes to run during LTO.
|
|
.It Fl -lto-O Ar opt-level
|
|
Optimization level for LTO.
|
|
.It Fl -lto-partitions= Ns Ar value
|
|
Number of LTO codegen partitions.
|
|
.It Fl L Ar dir
|
|
Add a directory to the library search path.
|
|
.It Fl l Ar libName
|
|
Root name of library to use.
|
|
.It Fl -Map Ar file
|
|
Print a link map to
|
|
.Ar file .
|
|
.It Fl m Ar value
|
|
Set target emulation.
|
|
.It Fl -no-as-needed
|
|
Always set
|
|
.Dv DT_NEEDED
|
|
for shared libraries.
|
|
.It Fl -no-color-diagnostics
|
|
Do not use colors in diagnostics.
|
|
.It Fl -no-define-common
|
|
Do not assign space to common symbols.
|
|
.It Fl -no-demangle
|
|
Do not demangle symbol names.
|
|
.It Fl -no-dynamic-linker
|
|
Inhibit output of an
|
|
.Li .interp
|
|
section.
|
|
.It Fl -no-gc-sections
|
|
Disable garbage collection of unused sections.
|
|
.It Fl -no-gnu-unique
|
|
Disable STB_GNU_UNIQUE symbol binding.
|
|
.It Fl -no-rosegment
|
|
Do not put read-only non-executable sections in their own segment.
|
|
.It Fl -no-threads
|
|
Do not run the linker multi-threaded.
|
|
.It Fl -no-undefined-version
|
|
Report version scripts that refer undefined symbols.
|
|
.It Fl -no-undefined
|
|
Report unresolved symbols even if the linker is creating a shared library.
|
|
.It Fl -no-whole-archive
|
|
Restores the default behavior of loading archive members.
|
|
.It Fl -noinhibit-exec
|
|
Retain the executable output file whenever it is still usable.
|
|
.It Fl -no-pie
|
|
Do not create a position independent executable.
|
|
.It Fl -nostdlib
|
|
Only search directories specified on the command line.
|
|
.It Fl -oformat Ar format
|
|
Specify the format for the output object file.
|
|
The only supported
|
|
.Ar format
|
|
is
|
|
.Cm binary ,
|
|
which produces output with no ELF header.
|
|
.It Fl -omagic
|
|
Set the text and data sections to be readable and writable.
|
|
.It Fl -opt-remarks-filename Ar file
|
|
Write optimization remarks in YAML format to
|
|
.Ar file .
|
|
.It Fl -opt-remarks-with-hotness
|
|
Include hotness information in the optimization remarks file.
|
|
.It Fl O Ar value
|
|
Optimize output file size.
|
|
.Ar value
|
|
may be:
|
|
.Bl -tag -width indent
|
|
.It Cm O0
|
|
Disable string merging.
|
|
.It Cm O1
|
|
Enable string merging.
|
|
.It Cm O2
|
|
Enable string tail merging.
|
|
.El
|
|
.Cm O1
|
|
is the default.
|
|
.It Fl o Ar path
|
|
Write the output executable, library, or object to
|
|
.Ar path .
|
|
If not specified,
|
|
.Dv a.out
|
|
is used as a default.
|
|
.It Fl -pie
|
|
Create a position independent executable.
|
|
.It Fl -print-gc-sections
|
|
List removed unused sections.
|
|
.It Fl -print-map
|
|
Print a link map to the standard output.
|
|
.It Fl -relocatable
|
|
Create relocatable object file.
|
|
.It Fl -reproduce Ar value
|
|
Dump linker invocation and input files for debugging.
|
|
.It Fl -retain-symbols-file= Ns Ar file
|
|
Retain only the symbols listed in the file.
|
|
.It Fl -rpath Ar value
|
|
Add a
|
|
.Dv DT_RUNPATH
|
|
to the output.
|
|
.It Fl -rsp-quoting= Ns Ar value
|
|
Quoting style for response files.
|
|
The supported values are
|
|
.Ar windows
|
|
and
|
|
.Ar posix .
|
|
.It Fl -script Ar file
|
|
Read linker script from
|
|
.Ar file .
|
|
.It Fl -section-start Ar address
|
|
Set address of section.
|
|
.It Fl -shared
|
|
Build a shared object.
|
|
.It Fl -soname= Ns Ar value
|
|
Set
|
|
.Dv DT_SONAME
|
|
to
|
|
.Ar value .
|
|
.It Fl -sort-section Ar value
|
|
Specifies sections sorting rule when linkerscript is used.
|
|
.It Fl -start-lib
|
|
Start a grouping of objects that should be treated as if they were together
|
|
in an archive.
|
|
.It Fl -strip-all
|
|
Strip all symbols.
|
|
.It Fl -strip-debug
|
|
Strip debugging information.
|
|
.It Fl -symbol-ordering-file Ar file
|
|
Lay out sections in the order specified by
|
|
.Ar file .
|
|
.It Fl -sysroot= Ns Ar value
|
|
Set the system root.
|
|
.It Fl -target1-abs
|
|
Interpret
|
|
.Dv R_ARM_TARGET1
|
|
as
|
|
.Dv R_ARM_ABS32 .
|
|
.It Fl -target1-rel
|
|
Interpret
|
|
.Dv R_ARM_TARGET1
|
|
as
|
|
.Dv R_ARM_REL32 .
|
|
.It Fl -target2=type
|
|
Interpret
|
|
.Dv R_ARM_TARGET2
|
|
as
|
|
.Ar type ,
|
|
where
|
|
.Ar type
|
|
is one of
|
|
.Li rel ,
|
|
.Li abs ,
|
|
or
|
|
.Li got-rel .
|
|
.It Fl -Tbss Ar value
|
|
Same as
|
|
.Fl -section-start
|
|
with
|
|
.Li .bss
|
|
as the sectionname.
|
|
.It Fl -Tdata Ar value
|
|
Same as
|
|
.Fl -section-start
|
|
with
|
|
.Li .data
|
|
as the sectionname.
|
|
.It Fl -thinlto-cache-dir= Ns Ar value
|
|
Path to ThinLTO cached object file directory.
|
|
.It Fl -thinlto-cache-policy Ar value
|
|
Pruning policy for the ThinLTO cache.
|
|
.It Fl -thinlto-jobs= Ns Ar value
|
|
Number of ThinLTO jobs.
|
|
.It Fl -threads
|
|
Run the linker multi-threaded.
|
|
This option is enabled by default.
|
|
.It Fl -trace-symbol Ar symbol
|
|
Trace references to
|
|
.Ar symbol .
|
|
.It Fl -trace
|
|
Print the names of the input files.
|
|
.It Fl -Ttext Ar value
|
|
Same as
|
|
.Fl -section-start
|
|
with
|
|
.Li .text
|
|
as the sectionname.
|
|
.It Fl -undefined Ar symbol
|
|
Force
|
|
.Ar symbol
|
|
to be an undefined symbol during linking.
|
|
.It Fl -unresolved-symbols= Ns Ar value
|
|
Determine how to handle unresolved symbols.
|
|
.It Fl -verbose
|
|
Verbose mode.
|
|
.It Fl -version-script Ar file
|
|
Read version script from
|
|
.Ar file .
|
|
.It Fl V , Fl -version
|
|
Display the version number and exit.
|
|
.It Fl v
|
|
Display the version number and proceed with linking if object files are
|
|
specified.
|
|
.It Fl -warn-common
|
|
Warn about duplicate common symbols.
|
|
.It Fl -warn-unresolved-symbols
|
|
Report unresolved symbols as warnings.
|
|
.It Fl -whole-archive
|
|
Force load of all members in a static library.
|
|
.It Fl -wrap Ar symbol
|
|
Use wrapper functions for symbol.
|
|
.It Fl z Ar option
|
|
Linker option extensions.
|
|
.Bl -tag -width indent
|
|
.It Cm execstack
|
|
Make the main stack executable.
|
|
Stack permissions are recorded in the
|
|
.Dv PT_GNU_STACK
|
|
segment.
|
|
.It Cm ifunc-noplt
|
|
Do not emit PLT entries for GNU ifuncs.
|
|
Instead, preserve relocations for ifunc call sites so that they may
|
|
be applied by a run-time loader.
|
|
Note that this feature requires special loader support and will
|
|
generally result in application crashes when used outside of freestanding
|
|
environments.
|
|
.It Cm interpose
|
|
Set the
|
|
.Dv DF_1_INTERPOSE
|
|
flag to indicate that the object is an interposer.
|
|
Runtime linkers perform symbol resolution by first searching the application,
|
|
followed by interposers, and then any other dependencies.
|
|
.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.
|
|
.It Cm nocombreloc
|
|
Disable combining and sorting multiple relocation sections.
|
|
.It Cm nocopyreloc
|
|
Disable the creation of copy relocations.
|
|
.It Cm nodelete
|
|
Set the
|
|
.Dv DF_1_NODELETE
|
|
flag to indicate that the object cannot be unloaded from a process.
|
|
.It Cm nodlopen
|
|
Set the
|
|
.Dv DF_1_NOOPEN
|
|
flag to indcate that the object may not be opened by
|
|
.Xr dlopen 3 .
|
|
.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.
|
|
.It Cm notext
|
|
Allow relocations against read-only segments.
|
|
Sets the
|
|
.Dv DT_TEXTREL flag in the
|
|
.Dv DYNAMIC
|
|
section.
|
|
.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.
|
|
.It Cm origin
|
|
Set the
|
|
.Dv DF_ORIGIN
|
|
flag to indicate that the object requires
|
|
$ORIGIN
|
|
processing.
|
|
.It Cm retpolineplt
|
|
Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
|
|
.It Cm rodynamic
|
|
Make the
|
|
.Li .dynamic
|
|
section read-only.
|
|
The
|
|
.Dv DT_DEBUG
|
|
tag will not be emitted.
|
|
.It Cm stack-size= Ns Ar size
|
|
Set the main thread's stack size to
|
|
.Ar size .
|
|
The stack size is recorded as the size of the
|
|
.Ar size .
|
|
.Dv PT_GNU_STACK
|
|
program segment.
|
|
.It Cm text
|
|
Do not allow relocations against read-only segments.
|
|
This is the default.
|
|
.It Cm wxneeded
|
|
Create a
|
|
.Dv PT_OPENBSD_WXNEEDED
|
|
segment.
|
|
.El
|
|
.El
|