\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2019 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2020 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2020 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
in the filter object. The shared object @var{name} need not exist.
Thus the shared object @var{name} may be used to provide an alternative
implementation of certain functions, perhaps for debugging or for
-machine specific performance.
+machine-specific performance.
This option may be specified more than once. The DT_AUXILIARY entries
will be created in the order in which they appear on the command line.
See @ref{Expressions} for more information about expressions in linker
scripts.
-@item How GNU properties are merged.
+@item
+How GNU properties are merged.
-When linker merges input .note.gnu.property sections into one output
-.note.gnu.property section, some properties are removed or updated,
-which are reported in the link map as
+When the linker merges input .note.gnu.property sections into one output
+.note.gnu.property section, some properties are removed or updated.
+These actions are reported in the link map. For example:
@smallexample
Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
@end smallexample
-It indicates that property 0xc0000002 is removed from output when
+This indicates that property 0xc0000002 is removed from output when
merging properties in @file{foo.o}, whose property 0xc0000002 value
is 0x1, and @file{bar.o}, which doesn't have property 0xc0000002.
@smallexample
-Updated property 0xc0000002 (0x1) to merge foo.o (0x1) and bar.o (0x1)
+Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
@end smallexample
-It indicates that property 0xc0010001 value is updated to 0x1 in output
+This indicates that property 0xc0010001 value is updated to 0x1 in output
when merging properties in @file{foo.o}, whose 0xc0010001 property value
is 0x1, and @file{bar.o}, whose 0xc0010001 property value is 0x1.
@end itemize
+@cindex link map discarded
+@kindex --print-map-discarded
+@kindex --no-print-map-discarded
+@item --print-map-discarded
+@itemx --no-print-map-discarded
+Print (or do not print) the list of discarded and garbage collected sections
+in the link map. Enabled by default.
+
@kindex -n
@cindex read-only text
@cindex NMAGIC
@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
Supported for i386 and x86_64.
+@item cet-report=none
+@itemx cet-report=warning
+@itemx cet-report=error
+Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and
+GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property
+section. @option{cet-report=none}, which is the default, will make the
+linker not report missing properties in input files.
+@option{cet-report=warning} will make the linker issue a warning for
+missing properties in input files. @option{cet-report=error} will make
+the linker issue an error for missing properties in input files.
+Note that @option{ibt} will turn off the missing
+GNU_PROPERTY_X86_FEATURE_1_IBT property report and @option{shstk} will
+turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
+Supported for Linux/i386 and Linux/x86_64.
+
@item combreloc
@itemx nocombreloc
Combine multiple dynamic relocation sections and sort to improve
When creating a shared library, bind references to global symbols to the
definition within the shared library, if any. Normally, it is possible
for a program linked against a shared library to override the definition
-within the shared library. This option can also be used with the
-@option{--export-dynamic} option, when creating a position independent
-executable, to bind references to global symbols to the definition within
-the executable. This option is only meaningful on ELF platforms which
-support shared libraries and position independent executables.
+within the shared library. This option is only meaningful on ELF
+platforms which support shared libraries.
@kindex -Bsymbolic-functions
@item -Bsymbolic-functions
When creating a shared library, bind references to global function
symbols to the definition within the shared library, if any.
-This option can also be used with the @option{--export-dynamic} option,
-when creating a position independent executable, to bind references
-to global function symbols to the definition within the executable.
This option is only meaningful on ELF platforms which support shared
-libraries and position independent executables.
+libraries.
@kindex --dynamic-list=@var{dynamic-list-file}
@item --dynamic-list=@var{dynamic-list-file}
@kindex --embedded-relocs
@item --embedded-relocs
This option is similar to the @option{--emit-relocs} option except
-that the relocs are stored in a target specific section. This option
+that the relocs are stored in a target-specific section. This option
is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
targets.
@kindex --target-help
@item --target-help
-Print a summary of all target specific options on the standard output and exit.
+Print a summary of all target-specific options on the standard output and exit.
@kindex -Map=@var{mapfile}
@item -Map=@var{mapfile}
@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
@end ifset
-On some platforms the @samp{--relax} option performs target specific,
+On some platforms the @samp{--relax} option performs target-specific,
global optimizations that become possible when the linker resolves
addressing in the program, such as relaxing address modes,
synthesizing new instructions, selecting shorter version of current
Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All @option{-rpath}
arguments are concatenated and passed to the runtime linker, which uses
-them to locate shared objects at runtime. The @option{-rpath} option is
-also used when locating shared objects which are needed by shared
-objects explicitly included in the link; see the description of the
-@option{-rpath-link} option. If @option{-rpath} is not used when linking an
-ELF executable, the contents of the environment variable
-@code{LD_RUN_PATH} will be used if it is defined.
+them to locate shared objects at runtime.
+
+The @option{-rpath} option is also used when locating shared objects which
+are needed by shared objects explicitly included in the link; see the
+description of the @option{-rpath-link} option. Searching @option{-rpath}
+in this way is only supported by native linkers and cross linkers which
+have been configured with the @option{--with-sysroot} option.
+
+If @option{-rpath} is not used when linking an ELF executable, the
+contents of the environment variable @code{LD_RUN_PATH} will be used if it
+is defined.
The @option{-rpath} option may also be used on SunOS. By default, on
SunOS, the linker will form a runtime search path out of all the
The linker uses the following search paths to locate required shared
libraries:
+
@enumerate
@item
Any directories specified by @option{-rpath-link} options.
@item
The default directories, normally @file{/lib} and @file{/usr/lib}.
@item
-For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
-exists, the list of directories found in that file.
+For a linker for a Linux system, if the file @file{/etc/ld.so.conf}
+exists, the list of directories found in that file. Note: the path
+to this file is prefixed with the @code{sysroot} value, if that is
+defined, and then any @code{prefix} string if the linker was
+configured with the @command{--prefix=<path>} option.
+@item
+For a native linker on a FreeBSD system, any directories specified by
+the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h}
+header file.
+@item
+Any directories specifed by a @code{SEARCH_DIR} command in the
+linker script being used.
@end enumerate
If the required shared library is not found, the linker will issue a
@}
@end smallexample
-Please keep in mind that with link-time optimization (LTO) enabled, your whole
-program may be a translation unit.
-
@kindex --eh-frame-hdr
@kindex --no-eh-frame-hdr
@item --eh-frame-hdr
@item --high-entropy-va
Image is compatible with 64-bit address space layout randomization
(ASLR).
+This option also implies @option{--dynamicbase} and
+@option{--enable-reloc-section}.
@kindex --dynamicbase
@item --dynamicbase
The image base address may be relocated using address space layout
randomization (ASLR). This feature was introduced with MS Windows
Vista for i386 PE targets.
+This option also implies @option{--enable-reloc-section}.
@kindex --forceinteg
@item --forceinteg
can be used to insert a zero value for the timestamp, this ensuring
that binaries produced from identical sources will compare
identically.
+
+@kindex --enable-reloc-section
+@item --enable-reloc-section
+Create the base relocation table, which is necessary if the image
+is loaded at a different image base than specified in the PE header.
@end table
@c man end
a check is made causing the loss of an ISA mode transition to produce
an error.
+@kindex --compact-branches
+@item --compact-branches
+@kindex --no-compact-branches
+@item --compact-branches
+These options control the generation of compact instructions by the linker
+in the PLT entries for MIPS R6.
+
@end table
@c man end
@item
the @code{ENTRY(@var{symbol})} command in a linker script;
@item
-the value of a target specific symbol, if it is defined; For many
+the value of a target-specific symbol, if it is defined; For many
targets this is @code{start}, but PE- and BeOS-based systems for example
check a list of possible entry symbols, matching the first one found.
@item
into ascending order by name before placing them in the output file.
@cindex SORT_BY_ALIGNMENT
-@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
-difference is @code{SORT_BY_ALIGNMENT} will sort sections into
-descending order by alignment before placing them in the output file.
-Larger alignments are placed before smaller alignments in order to
-reduce the amount of padding necessary.
+@code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
+@code{SORT_BY_ALIGNMENT} will sort sections into descending order of
+alignment before placing them in the output file. Placing larger
+alignments before smaller alignments can reduce the amount of padding
+needed.
@cindex SORT_BY_INIT_PRIORITY
-@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The
-difference is @code{SORT_BY_INIT_PRIORITY} will sort sections into
-ascending order by numerical value of the GCC init_priority attribute
-encoded in the section name before placing them in the output file.
+@code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
+@code{SORT_BY_INIT_PRIORITY} will sort sections into ascending
+numerical order of the GCC init_priority attribute encoded in the
+section name before placing them in the output file. In
+@code{.init_array.NNNNN} and @code{.fini_array.NNNNN}, @code{NNNNN} is
+the init_priority. In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
+@code{NNNNN} is 65535 minus the init_priority.
@cindex SORT
@code{SORT} is an alias for @code{SORT_BY_NAME}.
input sections. Any input sections which are assigned to an output
section named @samp{/DISCARD/} are not included in the output file.
+Note, sections that match the @samp{/DISCARD/} output section will be
+discarded even if they are in an ELF section group which has other
+members which are not being discarded. This is deliberate.
+Discarding takes precedence over grouping.
+
@node Output Section Attributes
@subsection Output Section Attributes
@cindex output section attributes
@group
@var{section} [@var{address}] [(@var{type})] :
[AT(@var{lma})]
- [ALIGN(@var{section_align})]
+ [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
[SUBALIGN(@var{subsection_align})]
[@var{constraint}]
@{
@subsection Symbolic Constants
@cindex symbolic constants
@kindex CONSTANT
-It is possible to refer to target specific constants via the use of
+It is possible to refer to target-specific constants via the use of
the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
@table @code
@cindex PowerPC64 __tls_get_addr optimization
@kindex --tls-get-addr-optimize
@kindex --no-tls-get-addr-optimize
+@kindex --tls-get-addr-regsave
+@kindex --no-tls-get-addr-regsave
@item --tls-get-addr-optimize
@itemx --no-tls-get-addr-optimize
-These options control whether PowerPC64 @command{ld} uses a special
+These options control how PowerPC64 @command{ld} uses a special
stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
an optimization that allows the second and subsequent calls to
@code{__tls_get_addr} for a given symbol to be resolved by the special
-stub without calling in to glibc. By default the linker enables this
-option when glibc advertises the availability of __tls_get_addr_opt.
-Forcing this option on when using an older glibc won't do much besides
-slow down your applications, but may be useful if linking an
-application against an older glibc with the expectation that it will
-normally be used on systems having a newer glibc.
+stub without calling in to glibc. By default the linker enables
+generation of the stub when glibc advertises the availability of
+__tls_get_addr_opt.
+Using @option{--tls-get-addr-optimize} with an older glibc won't do
+much besides slow down your applications, but may be useful if linking
+an application against an older glibc with the expectation that it
+will normally be used on systems having a newer glibc.
+@option{--tls-get-addr-regsave} forces generation of a stub that saves
+and restores volatile registers around the call into glibc. Normally,
+this is done when the linker detects a call to __tls_get_addr_desc.
+Such calls then go via the register saving stub to __tls_get_addr_opt.
+@option{--no-tls-get-addr-regsave} disables generation of the
+register saves.
@cindex PowerPC64 OPD optimization
@kindex --no-opd-optimize
projects / deliverable / binutils-gdb.git / blobdiff