From 174e083345415f0c114546001d20baa96dca2445 Mon Sep 17 00:00:00 2001 From: Ed Maste Date: Tue, 3 Sep 2019 17:58:24 +0000 Subject: [PATCH] ld.lld.1: stylistic changes suggested by igor igor is an automated man page "proofreader" from FreeBSD - see http://www.wonkity.com/~wblock/igor/igor.pdf No content change. llvm-svn: 370799 --- lld/docs/ld.lld.1 | 59 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1 index fa1b6cc..91bcae3 100644 --- a/lld/docs/ld.lld.1 +++ b/lld/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,7 +39,6 @@ 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 .Bl -tag -width indent .It Fl -allow-multiple-definition @@ -164,8 +162,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 +219,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 +334,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 +345,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 +372,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 @@ -412,7 +418,8 @@ 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 +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. @@ -519,13 +526,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 @@ -552,13 +561,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 -- 2.7.4