\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
@set MSP430
@set NDS32
@set NIOSII
+@set PDP11
@set POWERPC
@set POWERPC64
@set Renesas
@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
option is only meaningful on ELF platforms supporting the rtld-audit interface.
The -P option is provided for Solaris compatibility.
+@kindex --enable-non-contiguous-regions
+@item --enable-non-contiguous-regions
+This option avoids generating an error if an input section does not
+fit a matching output section. The linker tries to allocate the input
+section to subseque nt matching output sections, and generates an
+error only if no output section is large enough. This is useful when
+several non-contiguous memory regions are available and the input
+section does not require a particular one. The order in which input
+sections are evaluated does not change, for instance:
+
+@smallexample
+ MEMORY @{
+ MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14
+ MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40
+ MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40
+ @}
+ SECTIONS @{
+ mem1 : @{ *(.data.*); @} > MEM1
+ mem2 : @{ *(.data.*); @} > MEM2
+ mem3 : @{ *(.data.*); @} > MEM2
+ @}
+
+ with input sections:
+ .data.1: size 8
+ .data.2: size 0x10
+ .data.3: size 4
+
+ results in .data.1 affected to mem1, and .data.2 and .data.3
+ affected to mem2, even though .data.3 would fit in mem3.
+@end smallexample
+
+This option is incompatible with INSERT statements because it changes
+the way input sections are mapped to output sections.
+
+@kindex --enable-non-contiguous-regions-warnings
+@item --enable-non-contiguous-regions-warnings
+This option enables warnings when
+@code{--enable-non-contiguous-regions} allows possibly unexpected
+matches in sections mapping, potentially leading to silently
+discarding a section instead of failing because it does not fit any
+output region.
+
@cindex entry point, from command line
@kindex -e @var{entry}
@kindex --entry=@var{entry}
support a similar function to export all symbols from a DLL or EXE; see
the description of @samp{--export-all-symbols} below.
+@kindex --export-dynamic-symbol=@var{glob}
+@cindex export dynamic symbol
+@item --export-dynamic-symbol=@var{glob}
+When creating a dynamically linked executable, symbols matching
+@var{glob} will be added to the dynamic symbol table. When creating a
+shared library, references to symbols matching @var{glob} will not be
+bound to the definitions within the shared library. This option is a
+no-op when creating a shared library and @samp{-Bsymbolic} or
+@samp{--dynamic-list} are not specified. This option is only meaningful
+on ELF platforms which support shared libraries.
+
+@kindex --export-dynamic-symbol-list=@var{file}
+@cindex export dynamic symbol list
+@item --export-dynamic-symbol-list=@var{file}
+Specify a @samp{--export-dynamic-symbol} for each pattern in the file.
+The format of the file is the same as the version node without
+scope and node name. See @ref{VERSION} for more information.
+
@ifclear SingleFormat
@cindex big-endian objects
@cindex endianness
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
@cindex input files, displaying
@item -t
@itemx --trace
-Print the names of the input files as @command{ld} processes them.
+Print the names of the input files as @command{ld} processes them. If
+@samp{-t} is given twice then members within archives are also printed.
+@samp{-t} output is useful to generate a list of all the object files
+and scripts involved in linking, for example, when packaging files for
+a linker bug report.
@kindex -T @var{script}
@kindex --script=@var{script}
@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
@item text
@itemx notext
@itemx textoff
-Report an error if DT_TEXTREL is set, i.e., if the binary has dynamic
-relocations in read-only sections. Don't report an error if
-@samp{notext} or @samp{textoff}.
+Report an error if DT_TEXTREL is set, i.e., if the position-independent
+or shared object has dynamic relocations in read-only sections. Don't
+report an error if @samp{notext} or @samp{textoff}.
@item undefs
Do not report unresolved symbol references from regular object files,
archive is needed to resolve an undefined symbol referred to by an
object in an archive that appears later on the command line, the linker
would not be able to resolve that reference. By grouping the archives,
-they all be searched repeatedly until all possible references are
+they will all be searched repeatedly until all possible references are
resolved.
Using this option has a significant performance cost. It is best to use
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}
Print a link map to the file @var{mapfile}. See the description of the
-@option{-M} option, above.
+@option{-M} option, above. Specifying a directory as @var{mapfile}
+causes the linker map to be written into a file inside the directory.
+The name of the file is based upon the @var{output} filename with
+@code{.map} appended.
@cindex memory usage
@kindex --no-keep-memory
@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
is, if the @code{SECTIONS} command does not specify a start address for
the section (@pxref{SECTIONS}).
-@kindex --warn-shared-textrel
-@item --warn-shared-textrel
-Warn if the linker adds a DT_TEXTREL to a shared object.
+@kindex --warn-textrel
+@item --warn-textrel
+Warn if the linker adds DT_TEXTREL to a position-independent executable
+or shared object.
@kindex --warn-alternate-em
@item --warn-alternate-em
@}
@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
+@itemx --no-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
+@end ifset
+
+
+@ifset PDP11
+@subsection Options specific to PDP11 targets
+
+@c man begin OPTIONS
+
+For the pdp11-aout target, three variants of the output format can be
+produced as selected by the following options. The default variant
+for pdp11-aout is the @samp{--omagic} option, whereas for other
+targets @samp{--nmagic} is the default. The @samp{--imagic} option is
+defined only for the pdp11-aout target, while the others are described
+here as they apply to the pdp11-aout target.
+
+@table @gcctabopt
+
+@kindex -N
+@item -N
+@kindex --omagic
+@itemx --omagic
+
+Mark the output as @code{OMAGIC} (0407) in the @file{a.out} header to
+indicate that the text segment is not to be write-protected and
+shared. Since the text and data sections are both readable and
+writable, the data section is allocated immediately contiguous after
+the text segment. This is the oldest format for PDP11 executable
+programs and is the default for @command{ld} on PDP11 Unix systems
+from the beginning through 2.11BSD.
+
+@kindex -n
+@item -n
+@kindex --nmagic
+@itemx --nmagic
+
+Mark the output as @code{NMAGIC} (0410) in the @file{a.out} header to
+indicate that when the output file is executed, the text portion will
+be read-only and shareable among all processes executing the same
+file. This involves moving the data areas up to the first possible 8K
+byte page boundary following the end of the text. This option creates
+a @emph{pure executable} format.
+
+@kindex -z
+@item -z
+@kindex --imagic
+@itemx --imagic
+
+Mark the output as @code{IMAGIC} (0411) in the @file{a.out} header to
+indicate that when the output file is executed, the program text and
+data areas will be loaded into separate address spaces using the split
+instruction and data space feature of the memory management unit in
+larger models of the PDP11. This doubles the address space available
+to the program. The text segment is again pure, write-protected, and
+shareable. The only difference in the output format between this
+option and the others, besides the magic number, is that both the text
+and data sections start at location 0. The @samp{-z} option selected
+this format in 2.11BSD. This option creates a @emph{separate
+executable} format.
+
+@kindex --no-omagic
+@item --no-omagic
+
+Equivalent to @samp{--nmagic} for pdp11-aout.
+
@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
In case a @dfn{sysroot prefix} is configured, and the filename starts
with the @samp{/} character, and the script being processed was
located inside the @dfn{sysroot prefix}, the filename will be looked
-for in the @dfn{sysroot prefix}. Otherwise, the linker will try to
-open the file in the current directory. If it is not found, the
-linker will search through the archive library search path.
-The @dfn{sysroot prefix} can also be forced by specifying @code{=}
-as the first character in the filename path, or prefixing the filename
-path with @code{$SYSROOT}. See also the description of @samp{-L} in
-@ref{Options,,Command-line Options}.
+for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying
+@code{=} as the first character in the filename path, or prefixing the
+filename path with @code{$SYSROOT}. See also the description of
+@samp{-L} in @ref{Options,,Command-line Options}.
+
+If a @dfn{sysroot prefix} is not used then the linker will try to open
+the file in the directory containing the linker script. If it is not
+found the linker will then search the current directory. If it is still
+not found the linker will search through the archive library search
+path.
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
name to @code{lib@var{file}.a}, as with the command-line argument
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