diff options
Diffstat (limited to 'docs/ld.lld.1')
| -rw-r--r-- | docs/ld.lld.1 | 112 |
1 files changed, 87 insertions, 25 deletions
diff --git a/docs/ld.lld.1 b/docs/ld.lld.1 index c432aacf7f73..1746ae9f5fd4 100644 --- a/docs/ld.lld.1 +++ b/docs/ld.lld.1 @@ -14,7 +14,6 @@ .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 @@ -40,8 +39,18 @@ All these targets are always supported however was built, so you can always use .Nm as a native linker as well as a cross linker. - .Sh OPTIONS +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 preceding the option name. +Long options beginning with +.Cm o +require two dashes to avoid confusion with the +.Fl o Ar path +option. +.Pp .Bl -tag -width indent .It Fl -allow-multiple-definition Do not error if a symbol is defined multiple times. @@ -164,8 +173,8 @@ A value of zero indicates that there is no limit. .It Fl -error-unresolved-symbols Report unresolved symbols as errors. .It Fl -execute-only -Mark executable sections unreadable. This option is currently only -supported on AArch64. +Mark executable sections unreadable. +This option is currently only supported on AArch64. .It Fl -exclude-libs Ns = Ns Ar value Exclude static libraries from automatic export. .It Fl -export-dynamic , Fl E @@ -221,13 +230,16 @@ Enable safe identical code folding. Disable identical code folding. .It Fl -ignore-data-address-equality Ignore address equality of data. C/C++ requires each data to have a unique -address. This option allows lld to do unsafe optimization that breaks the +address. +This option allows lld to do unsafe optimization that breaks the requirement: create copies of read-only data or merge two or more read-only data that happen to have the same value. .It Fl -ignore-function-address-equality -Ignore address equality of functions. This option allows non-PIC calls to a -function with non-default visibility in a shared object. The function may have -different addresses within the executable and within the shared object. +Ignore address equality of functions. +This option allows non-PIC calls to a function with non-default visibility in +a shared object. +The function may have different addresses within the executable and within the +shared object. .It Fl -image-base Ns = Ns Ar value Set the base address to .Ar value . @@ -333,7 +345,8 @@ is .Cm binary , which produces output with no ELF header. .It Fl -omagic , Fl N -Set the text and data sections to be readable and writable, do not page align sections, link against static libraries. +Set the text and data sections to be readable and writable, do not page align +sections, link against static libraries. .It Fl -opt-remarks-filename Ar file Write optimization remarks in YAML format to .Ar file . @@ -343,8 +356,8 @@ Filter optimization remarks by only allowing the passes matching .It Fl -opt-remarks-with-hotness Include hotness information in the optimization remarks file. .It Fl -orphan-handling Ns = Ns Ar mode -Control how orphan sections are handled. An orphan section is one not -specifically mentioned in a linker script. +Control how orphan sections are handled. +An orphan section is one not specifically mentioned in a linker script. .Ar mode may be: .Pp @@ -370,17 +383,21 @@ may be: .Pp .Bl -tag -width 2n -compact .It Cm none -Don't pack. Dynamic relocations are encoded in SHT_REL(A). +Do not pack. +Dynamic relocations are encoded in SHT_REL(A). .It Cm android Pack dynamic relocations in SHT_ANDROID_REL(A). .It Cm relr -Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_REL(A). +Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in +SHT_REL(A). .It Cm android+relr -Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_ANDROID_REL(A). +Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in +SHT_ANDROID_REL(A). .El .Pp .Cm none -is the default. If +is the default. +If .Fl -use-android-relr-tags is specified, use SHT_ANDROID_RELR instead of SHT_RELR. .Pp @@ -407,8 +424,14 @@ Undo the effect of .Fl -push-state. .It Fl -relocatable , Fl r Create relocatable object file. -.It Fl -reproduce Ns = Ns Ar value -Dump linker invocation and input files for debugging. +.It Fl -reproduce Ns = Ns Ar path +Write a tar file to +.Ar path, +containing all the input files needed to reproduce the link, a text file called +response.txt containing the command line options and a text file called +version.txt containing the output of ld.lld --version. +The archive when +unpacked can be used to re-run the linker with the same options and input files. .It Fl -retain-symbols-file Ns = Ns Ar file Retain only the symbols listed in the file. .It Fl -rpath Ns = Ns Ar value , Fl R Ar value @@ -424,6 +447,8 @@ and .It Fl -script Ns = Ns Ar file , Fl T Ar file Read linker script from .Ar file . +If multiple linker scripts are given, they are processed as if they +were concatenated in the order they appeared on the command line. .It Fl -section-start Ns = Ns Ar section Ns = Ns Ar address Set address of section. .It Fl -shared , Fl -Bsharable @@ -512,13 +537,15 @@ to include the object file in the output file. .It Fl -undefined-glob Ns = Ns Ar pattern Synonym for .Fl -undefined , -except that it takes a glob pattern. In a glob pattern, +except that it takes a glob pattern. +In a glob pattern, .Cm * matches zero or more characters, .Cm ? matches any single character, and .Cm [...] -matches the characters within brackets. All symbols that match +matches the characters within brackets. +All symbols that match a given pattern are handled as if they were given as arguments of .Fl -undefined . .It Fl -unresolved-symbols Ns = Ns Ar value @@ -545,13 +572,17 @@ Warn about duplicate common symbols. Warn about using ifunc symbols in conjunction with text relocations. Older versions of glibc library (2.28 and earlier) has a bug that causes the segment that includes ifunc symbols to be marked as not executable when -they are relocated. As a result, although the program compiles and links +they are relocated. +As a result, although the program compiles and links successfully, it gives segmentation fault when the instruction pointer reaches -an ifunc symbol. Use -warn-ifunc-textrel to let lld give a warning, if the +an ifunc symbol. +Use -warn-ifunc-textrel to let lld give a warning, if the code may include ifunc symbols, may do text relocations and be linked with -an older glibc version. Otherwise, there is no need to use it, as the default -value does not give a warning. This flag has been introduced in late 2018, -has no counter part in ld and gold linkers, and may be removed in the future. +an older glibc version. +Otherwise, there is no need to use it, as the default value does not give a +warning. +This flag has been introduced in late 2018, has no counter part in ld and gold +linkers, and may be removed in the future. .It Fl -warn-unresolved-symbols Report unresolved symbols as warnings. .It Fl -whole-archive @@ -560,18 +591,21 @@ Force load of all members in a static library. Use wrapper functions for symbol. .It Fl z Ar option Linker option extensions. -.Bl -tag -width indent +.Bl -tag -width indent -compact +.Pp .It Cm execstack Make the main stack executable. Stack permissions are recorded in the .Dv PT_GNU_STACK segment. +.Pp .It Cm global Sets the .Dv DF_1_GLOBAL flag in the .Dv DYNAMIC section. Different loaders can decide how to handle this flag on their own. +.Pp .It Cm ifunc-noplt Do not emit PLT entries for ifunc symbols. Instead, emit text relocations referencing the resolver. @@ -580,64 +614,78 @@ environments where text relocations do not have the usual drawbacks. This option must be combined with the .Fl z Li notext option. +.Pp .It Cm initfirst Sets the .Dv DF_1_INITFIRST flag to indicate the module should be initialized first. +.Pp .It Cm interpose Set the .Dv DF_1_INTERPOSE flag to indicate to the runtime linker that the object is an interposer. During symbol resolution interposers are searched after the application but before other dependencies. +.Pp .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. +.Pp .It Cm nocombreloc Disable combining and sorting multiple relocation sections. +.Pp .It Cm nocopyreloc Disable the creation of copy relocations. +.Pp .It Cm nodefaultlib Set the .Dv DF_1_NODEFLIB flag to indicate that default library search paths should be ignored. +.Pp .It Cm nodelete Set the .Dv DF_1_NODELETE flag to indicate that the object cannot be unloaded from a process. +.Pp .It Cm nodlopen Set the .Dv DF_1_NOOPEN flag to indicate that the object may not be opened by .Xr dlopen 3 . +.Pp .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. +.Pp .It Cm notext Allow relocations against read-only segments. Sets the .Dv DT_TEXTREL flag in the .Dv DYNAMIC section. +.Pp .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. +.Pp .It Cm origin Set the .Dv DF_ORIGIN flag to indicate that the object requires $ORIGIN processing. +.Pp .It Cm retpolineplt Emit retpoline format PLT entries as a mitigation for CVE-2017-5715. +.Pp .It Cm rodynamic Make the .Li .dynamic @@ -645,6 +693,18 @@ section read-only. The .Dv DT_DEBUG tag will not be emitted. +.Pp +.It Cm separate-loadable-segments +.It Cm separate-code +.It Cm noseparate-code +Specify whether two adjacent PT_LOAD segments are allowed to overlap in pages. +.Cm noseparate-code +(default) allows overlap. +.Cm separate-code +allows overlap between two executable segments, or two non-executable segments. +.Cm separate-loadable-segments +disallows overlap. +.Pp .It Cm stack-size Ns = Ns Ar size Set the main thread's stack size to .Ar size . @@ -652,9 +712,11 @@ The stack size is recorded as the size of the .Ar size . .Dv PT_GNU_STACK program segment. +.Pp .It Cm text Do not allow relocations against read-only segments. This is the default. +.Pp .It Cm wxneeded Create a .Dv PT_OPENBSD_WXNEEDED |