\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}
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
@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
@kindex --compact-branches
@item --compact-branches
@kindex --no-compact-branches
-@item --compact-branches
+@itemx --no-compact-branches
These options control the generation of compact instructions by the linker
in the PLT entries for MIPS R6.
@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
+@end ifset
+
@ifset UsesEnvVars
@node Environment
@section Environment Variables
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
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
@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