llvm-project/lld/docs/ld.lld.1

.\" This file is distributed under the University of Illinois Open Source
.\" License. See LICENSE.TXT for details.
.\"
.\" This man page documents only lld's ELF linking support, obtained originally
.\" from FreeBSD.
.Dd February 7, 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
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 fast ,
.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 fast ,
.Cm md5 ,
.Cm sha1 ,
and
.Cm tree
are calculated from the object contents.
.Cm fast
is not intended to be cryptographically secure.
.It Fl -build-id
Synonym for
.Fl -build-id= Ns Cm fast .
.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 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