Provided by: lld-7_7.0.1-12_amd64 bug

NAME

       ld.lld — ELF linker from the LLVM project

SYNOPSIS

       ld.lld [options] objfile ...

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.

       ld.lld  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.

       These options are available:

       --allow-multiple-definition
               Do not error if a symbol is defined multiple times.  The first definition will be used.

       --apply-dynamic-relocs
               Apply link-time values for dynamic relocations.

       --as-needed
               Only set DT_NEEDED for shared libraries if used.

       --auxiliary=value
               Set the DT_AUXILIARY field to the specified name.

       --Bdynamic, --dy
               Link against shared libraries.

       --Bstatic, --static, --dn
               Do not link against shared libraries.

       --Bsymbolic
               Bind defined symbols locally.

       --Bsymbolic-functions
               Bind defined function symbols locally.

       --build-id=value
               Generate a build ID note.  value may be one of fast, md5, sha1,  tree,  uuid,  0xhex-string,  and
               none.   tree  is  an  alias for sha1.  Build-IDs of type fast, md5, sha1, and tree are calculated
               from the object contents.  fast is not intended to be cryptographically secure.

       --build-id
               Synonym for --build-id=fast.

       --color-diagnostics=value
               Use colors in diagnostics.  value may be one of always, auto, and never.  auto enables  color  if
               and only if output is to a terminal.

       --color-diagnostics
               Alias for --color-diagnostics=auto.

       --compress-debug-sections=value
               Compress DWARF debug sections.  value may be none or zlib.

       --cref  Output cross reference table.

       --define-common, -d
               Assign space to common symbols.

       --defsym=symbol=expression
               Define  a  symbol  alias.   expression  may be another symbol or a linker script expression.  For
               example, ‘--defsym=foo=bar’ or ‘--defsym=foo=bar+0x100’.

       --demangle
               Demangle symbol names.

       --disable-new-dtags
               Disable new dynamic tags.

       --discard-all, -x
               Delete all local symbols.

       --discard-locals, -X
               Delete temporary local symbols.

       --discard-none
               Keep all symbols in the symbol table.

       --dynamic-linker=value
               Specify the dynamic linker to be used for a dynamically linked executable.  This is  recorded  in
               an ELF segment of type PT_INTERP.

       --dynamic-list=file
               Read a list of dynamic symbols from file.

       --eh-frame-hdr
               Request creation of .eh_frame_hdr section and PT_GNU_EH_FRAME segment header.

       --emit-relocs, -q
               Generate relocations in the output.

       --enable-new-dtags
               Enable new dynamic tags.

       --end-lib
               End a grouping of objects that should be treated as if they were together in an archive.

       --entry=entry
               Name of entry point symbol.

       --error-limit=value
               Maximum  number  of  errors  to emit before stopping.  A value of zero indicates that there is no
               limit.

       --error-unresolved-symbols
               Report unresolved symbols as errors.

       --exclude-libs=value
               Exclude static libraries from automatic export.

       --export-dynamic, -E
               Put symbols in the dynamic symbol table.

       --export-dynamic-symbol=symbol
               Include symbol in the dynamic symbol table.

       --fatal-warnings
               Treat warnings as errors.

       --filter=value, -F value
               Set the DT_FILTER field to the specified value.

       --fini=symbol
               Specify a finalizer function.

       --format=input-format, -b input-format
               Specify the format of the inputs following this option.  input-format may be one of binary,  elf,
               and default.  default is a synonym for elf.

       --gc-sections
               Enable garbage collection of unused sections.

       --gdb-index
               Generate .gdb_index section.

       --hash-style=value
               Specify hash style.  value may be sysv, gnu, or both.  both is the default.

       --help  Print a help message.

       --icf=all
               Enable identical code folding.

       --icf=safe
               Enable safe identical code folding.

       --icf=none
               Disable identical code folding.

       --image-base=value
               Set the base address to value.

       --init=symbol
               Specify an initializer function.

       --keep-unique=symbol
               Do not fold symbol during ICF.

       -l libName, --library=libName
               Root name of library to use.

       -L dir, --library-path=dir
               Add a directory to the library search path.

       --lto-aa-pipeline=value
               AA pipeline to run during LTO.  Used in conjunction with --lto-newpm-passes.

       --lto-newpm-passes=value
               Passes to run during LTO.

       --lto-Oopt-level
               Optimization level for LTO.

       --lto-partitions=value
               Number of LTO codegen partitions.

       -m value
               Set target emulation.

       --Map=file, -M file
               Print a link map to file.

       --no-as-needed
               Always set DT_NEEDED for shared libraries.

       --no-color-diagnostics
               Do not use colors in diagnostics.

       --no-define-common
               Do not assign space to common symbols.

       --no-demangle
               Do not demangle symbol names.

       --no-dynamic-linker
               Inhibit output of an .interp section.

       --no-gc-sections
               Disable garbage collection of unused sections.

       --no-gnu-unique
               Disable STB_GNU_UNIQUE symbol binding.

       --no-rosegment
               Do not put read-only non-executable sections in their own segment.

       --no-threads
               Do not run the linker multi-threaded.

       --no-undefined-version
               Report version scripts that refer undefined symbols.

       --no-undefined
               Report unresolved symbols even if the linker is creating a shared library.

       --no-whole-archive
               Restores the default behavior of loading archive members.

       --no-pie
               Do not create a position independent executable.

       --noinhibit-exec
               Retain the executable output file whenever it is still usable.

       --nostdlib
               Only search directories specified on the command line.

       -o path
               Write  the  output  executable, library, or object to path.  If not specified, a.out is used as a
               default.

       -Ovalue
               Optimize output file size.  value may be:

               0   Disable string merging.
               1   Enable string merging.
               2   Enable string tail merging.

               -O1 is the default.

       --oformat=format
               Specify the format for the output object file.   The  only  supported  format  is  binary,  which
               produces output with no ELF header.

       --omagic, -N
               Set the text and data sections to be readable and writable.

       --opt-remarks-filename file
               Write optimization remarks in YAML format to file.

       --opt-remarks-with-hotness
               Include hotness information in the optimization remarks file.

       --pie   Create a position independent executable.

       --print-gc-sections
               List removed unused sections.

       --print-map
               Print a link map to the standard output.

       --push-state
               Save the current state of --as-needed, --static, and --while-archive.

       --pop-state
               Undo the effect of --push-state.

       --relocatable, -r
               Create relocatable object file.

       --reproduce=value
               Dump linker invocation and input files for debugging.

       --retain-symbols-file=file
               Retain only the symbols listed in the file.

       --rpath=value, -R value
               Add a DT_RUNPATH to the output.

       --rsp-quoting=value
               Quoting style for response files.  The supported values are windows and posix.

       --script=file, -T file
               Read linker script from file.

       --section-start=section=address
               Set address of section.

       --shared, --Bsharable
               Build a shared object.

       --soname=value, -h value
               Set DT_SONAME to value.

       --sort-section=value
               Specifies sections sorting rule when linkerscript is used.

       --start-lib
               Start a grouping of objects that should be treated as if they were together in an archive.

       --strip-all, -s
               Strip all symbols.

       --strip-debug, -S
               Strip debugging information.

       --symbol-ordering-file=file
               Lay out sections in the order specified by file.

       --sysroot=value
               Set the system root.

       --target1-abs
               Interpret R_ARM_TARGET1 as R_ARM_ABS32.

       --target1-rel
               Interpret R_ARM_TARGET1 as R_ARM_REL32.

       --target2=type
               Interpret R_ARM_TARGET2 as type, where type is one of rel, abs, or got-rel.

       --Tbss=value
               Same as --section-start with .bss as the sectionname.

       --Tdata=value
               Same as --section-start with .data as the sectionname.

       --Ttext=value
               Same as --section-start with .text as the sectionname.

       --thinlto-cache-dir=value
               Path to ThinLTO cached object file directory.

       --thinlto-cache-policy=value
               Pruning policy for the ThinLTO cache.

       --thinlto-jobs=value
               Number of ThinLTO jobs.

       --threads
               Run the linker multi-threaded.  This option is enabled by default.

       --trace
               Print the names of the input files.

       --trace-symbol=symbol, -y symbol
               Trace references to symbol.

       --undefined=symbol, -u symbol
               Force symbol to be an undefined symbol during linking.

       --unresolved-symbols=value
               Determine how to handle unresolved symbols.

       -v      Display the version number and proceed with linking if object files are specified.

       -V, --version
               Display the version number and exit.

       --verbose
               Verbose mode.

       --version-script=file
               Read version script from file.

       --warn-backrefs
               Warn  about  reverse  or  cyclic dependencies to or between static archives.  This can be used to
               ensure linker invocation remains compatible with traditional Unix-like linkers.

       --warn-common
               Warn about duplicate common symbols.

       --warn-unresolved-symbols
               Report unresolved symbols as warnings.

       --whole-archive
               Force load of all members in a static library.

       --wrap=symbol
               Use wrapper functions for symbol.

       -z option
               Linker option extensions.

               execstack
                       Make the main stack executable.  Stack  permissions  are  recorded  in  the  PT_GNU_STACK
                       segment.

               initfirst
                       Sets the DF_1_INITFIRST flag to indicate the module should be initialized first.

               muldefs
                       Do  not  error if a symbol is defined multiple times.  The first definition will be used.
                       This is a synonym for --allow-multiple-definition.

               nocombreloc
                       Disable combining and sorting multiple relocation sections.

               nocopyreloc
                       Disable the creation of copy relocations.

               nodelete
                       Set the DF_1_NODELETE flag to indicate that the object cannot be unloaded from a process.

               nodlopen
                       Set the DF_1_NOOPEN flag to indcate that the object may not be opened by dlopen(3).

               norelro
                       Do not indicate that portions of the object  shold  be  mapped  read-only  after  initial
                       relocation processing.  The object will omit the PT_GNU_RELRO segment.

               notext  Allow  relocations  against  read-only segments.  Sets the DT_TEXTREL flag in the DYNAMIC
                       section.

               now     Set the 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.

               origin  Set the DF_ORIGIN flag to indicate that the object requires $ORIGIN processing.

               retpolineplt
                       Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.

               rodynamic
                       Make the .dynamic section read-only.  The DT_DEBUG tag will not be emitted.

               stack-size=size
                       Set the main thread's stack size to size.  The stack size is recorded as the size of  the
                       size.  PT_GNU_STACK program segment.

               text    Do not allow relocations against read-only segments.  This is the default.

               wxneeded
                       Create a PT_OPENBSD_WXNEEDED segment.

IMPLEMENTATION NOTES

       ld.lld's  handing of archive files (those with a .a file extension) is different from traditional linkers
       used on Unix-like systems.

       Traditional linkers maintain a set of undefined symbols during linking.  The linker processes  each  file
       in  the  order in which it appears on the command line, until the set of undefined symbols becomes empty.
       An object file is linked into the output object when it is encountered, with its undefined symbols  added
       to  the  set.   Upon  encountering  an  archive  file a traditional linker searches the objects contained
       therein, and processes those that satisfy symbols in the unresolved set.

       Handling mutually dependent archives may be awkward when using a traditional linker.  Archive  files  may
       have  to  be  specified multiple times, or the special command line options --start-group and --end-group
       may be used to have the linker loop over the files in the group until no new symbols  are  added  to  the
       set.

       ld.lld  records  all  symbols  found  in objects and archives as it iterates over command line arguments.
       When ld.lld encounters an undefined symbol that can  be  resolved  by  an  object  file  contained  in  a
       previously processed archive file, it immediately extracts and links it into the output object.

       With  certain  archive  inputs  ld.lld may produce different results compared to traditional linkers.  In
       practice, large bodies of third party software have been linked with ld.lld without material issues.

       The --warn-backrefs option may be used to identify a linker invocation  that  may  be  incompatible  with
       traditional Unix-like linker behavior.

Debian                                            July 30, 2018                                        LD.LLD(1)