From 0e8b7d26deb91d1d6d1eef87172698f5eafa6f35 Mon Sep 17 00:00:00 2001 From: markj Date: Tue, 2 Oct 2018 21:19:42 +0000 Subject: [PATCH] MFC r328810 (by emaste): ld.lld.1: miscellaneous style improvements MFC r329002 (by emaste): Update ld.lld.1 based on the version committed upstream MFC r329003 (by emaste): ld.lld.1: explain long options may use one or two dashes --- usr.bin/clang/lld/ld.lld.1 | 226 ++++++++++++++++++++++++++++++------- 1 file changed, 187 insertions(+), 39 deletions(-) diff --git a/usr.bin/clang/lld/ld.lld.1 b/usr.bin/clang/lld/ld.lld.1 index 6c13514572f..885c42bc132 100644 --- a/usr.bin/clang/lld/ld.lld.1 +++ b/usr.bin/clang/lld/ld.lld.1 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 10, 2018 +.Dd February 7, 2018 .Dt LD.LLD 1 .Os .Sh NAME @@ -36,7 +36,7 @@ .Op Ar options .Ar objfile ... .Sh DESCRIPTION -A linker takes one or more object, archive and library files, and combines +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 @@ -47,10 +47,22 @@ 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 -The following options are available: +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 -Allow multiple definitions. +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 @@ -69,18 +81,56 @@ Bind defined function symbols locally. 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 -Use colors in 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 value +.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 @@ -95,8 +145,9 @@ Keep all symbols in the symbol table. 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 value -Read a list of dynamic symbols. +.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 @@ -119,8 +170,10 @@ A value of zero indicates that there is no limit. Report unresolved symbols as errors. .It Fl -exclude-libs Ar value Exclude static libraries from automatic export. -.It Fl -export-dynamic-symbol Ar value -Put a symbol in the dynamic symbol table. +.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 @@ -132,10 +185,16 @@ field to the specified value. .It Fl -fini Ar symbol Specify a finalizer function. .It Fl -format= Ns Ar input-format -Change the input format of the inputs following this option. -.It Fl -full-shutdown -Perform a full shutdown instead of calling -.Fn _exit . +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 @@ -143,7 +202,15 @@ Generate .Li .gdb_index section. .It Fl -hash-style Ar value -Specify hash style (sysv, gnu or both). +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 @@ -169,8 +236,9 @@ Number of LTO codegen partitions. Add a directory to the library search path. .It Fl l Ar libName Root name of library to use. -.It Fl -Map Ar value -Print a link map to the specified file. +.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 @@ -203,22 +271,40 @@ Report unresolved symbols even if the linker is creating a shared library. Restores the default behavior of loading archive members. .It Fl -noinhibit-exec Retain the executable output file whenever it is still usable. -.It Fl -nopie +.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 binary format for the output object file. +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 value -YAML output file for optimization remarks. +.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 +Write the output executable, library, or object to .Ar path . If not specified, .Dv a.out @@ -245,9 +331,9 @@ The supported values are .Ar windows and .Ar posix . -.It Fl -script Ar value -Read linker script from the path -.Ar value . +.It Fl -script Ar file +Read linker script from +.Ar file . .It Fl -section-start Ar address Set address of section. .It Fl -shared @@ -266,8 +352,9 @@ in an archive. Strip all symbols. .It Fl -strip-debug Strip debugging information. -.It Fl -symbol-ordering-file Ar value -Lay out sections in the order specified by the symbol file. +.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 @@ -312,8 +399,10 @@ Pruning policy for the ThinLTO cache. Number of ThinLTO jobs. .It Fl -threads Run the linker multi-threaded. -.It Fl -trace-symbol Ar value -Trace references to symbols. +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 @@ -322,18 +411,21 @@ Same as with .Li .text as the sectionname. -.It Fl -undefined Ar value -Force undefined symbol during linking. +.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 value -Read a version script. +.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 +Display the version number and proceed with linking if object files are specified. .It Fl -warn-common Warn about duplicate common symbols. @@ -346,19 +438,75 @@ 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 -.Sh IMPLEMENTATION NOTES -The targets supported by -.Nm -are: -elf32-i386 elf32-iamcu elf32-littlearm elf32-ntradbigmips elf32-ntradlittlemips elf32-powerpc elf32-tradbigmips elf32-tradlittlemips elf32-x86-64 elf64-amdgpu elf64-littleaarch64 elf64-powerpc elf64-tradbigmips elf64-tradlittlemips elf64-x86-64 -- 2.45.0