Index: head/usr.bin/clang/lld/ld.lld.1
===================================================================
--- head/usr.bin/clang/lld/ld.lld.1	(revision 329002)
+++ head/usr.bin/clang/lld/ld.lld.1	(revision 329003)
@@ -1,501 +1,512 @@
 .\"-
 .\" 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 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
+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 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