Arm: Fix LSB of GOT for Thumb2 only PLT.

[deliverable/binutils-gdb.git] / ld / ld.texi

diff --git a/ld/ld.texi b/ld/ld.texi
index 964af12a081521803d7f2eb0be8d9f3ae63d2290..9f562935bed06d67708e2cd72d276de5ec694f71 100644 (file)
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1,6 +1,6 @@
 \input texinfo
 @setfilename ld.info
 \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
 @syncodeindex ky cp
 @c man begin INCLUDE
 @include configdoc.texi


@@ -56,7 +56,7 @@ This file documents the @sc{gnu} linker LD
 @end ifset
 version @value{VERSION}.
 
 @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
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3


@@ -93,7 +93,7 @@ section entitled ``GNU Free Documentation License''.
 
 @vskip 0pt plus 1filll
 @c man begin COPYRIGHT
 
 @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
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3


@@ -459,6 +459,48 @@ will contain a colon separated list of audit interfaces to use.  This
 option is only meaningful on ELF platforms supporting the rtld-audit interface.
 The -P option is provided for Solaris compatibility.
 
 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}
 @cindex entry point, from command line
 @kindex -e @var{entry}
 @kindex --entry=@var{entry}


@@ -760,25 +802,26 @@ option is used:
 See @ref{Expressions} for more information about expressions in linker
 scripts.
 
 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
 
 
 @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
 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
 
 @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
 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


@@ -854,7 +897,7 @@ Note that the location of the compiler originated plugins is different
 from the place where the @command{ar}, @command{nm} and
 @command{ranlib} programs search for their plugins.  In order for
 those commands to make use of a compiler based plugin it must first be
 from the place where the @command{ar}, @command{nm} and
 @command{ranlib} programs search for their plugins.  In order for
 those commands to make use of a compiler based plugin it must first be

-copied into the @file{$@{bindir@}/../lib/bfd-plugins} directory.  All gcc
+copied into the @file{$@{libdir@}/bfd-plugins} directory.  All gcc

 based linker plugins are backward compatible, so it is sufficient to
 just copy in the newest one.
 
 based linker plugins are backward compatible, so it is sufficient to
 just copy in the newest one.
 


@@ -1435,21 +1478,15 @@ libraries.
 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
 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.
 
 @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
 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 --dynamic-list=@var{dynamic-list-file}
 @item --dynamic-list=@var{dynamic-list-file}


@@ -1957,12 +1994,17 @@ line.  It overrides @samp{-s} and @samp{-S}.
 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
 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 @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


@@ -2011,6 +2053,7 @@ runtime linker would do.
 
 The linker uses the following search paths to locate required shared
 libraries:
 
 The linker uses the following search paths to locate required shared
 libraries:

+

 @enumerate
 @item
 Any directories specified by @option{-rpath-link} options.
 @enumerate
 @item
 Any directories specified by @option{-rpath-link} options.


@@ -2040,8 +2083,18 @@ libraries needed by it. The @code{DT_RPATH} entries are ignored if
 @item
 The default directories, normally @file{/lib} and @file{/usr/lib}.
 @item
 @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 enumerate
 
 If the required shared library is not found, the linker will issue a


@@ -2995,12 +3048,15 @@ of the PE file header:
 @item --high-entropy-va
 Image is compatible with 64-bit address space layout randomization
 (ASLR).
 @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.
 
 @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
 
 @kindex --forceinteg
 @item --forceinteg


@@ -3043,6 +3099,11 @@ same sources are linked.  The option @option{--no-insert-timestamp}
 can be used to insert a zero value for the timestamp, this ensuring
 that binaries produced from identical sources will compare
 identically.
 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
 @end table
 
 @c man end


@@ -3196,6 +3257,13 @@ calculated.  By default or if @samp{--no-ignore-branch-isa} is used
 a check is made causing the loss of an ISA mode transition to produce
 an error.
 
 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
 @end table
 
 @c man end


@@ -4617,17 +4685,20 @@ pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}).  When the
 into ascending order by name before placing them in the output file.
 
 @cindex SORT_BY_ALIGNMENT
 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
 
 @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}.
 
 @cindex SORT
 @code{SORT} is an alias for @code{SORT_BY_NAME}.


@@ -4984,6 +5055,11 @@ The special output section name @samp{/DISCARD/} may be used to discard
 input sections.  Any input sections which are assigned to an output
 section named @samp{/DISCARD/} are not included in the output file.
 
 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
 @node Output Section Attributes
 @subsection Output Section Attributes
 @cindex output section attributes


@@ -7572,18 +7648,27 @@ disable the optimization.
 @cindex PowerPC64 __tls_get_addr optimization
 @kindex --tls-get-addr-optimize
 @kindex --no-tls-get-addr-optimize
 @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
 @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 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
 
 @cindex PowerPC64 OPD optimization
 @kindex --no-opd-optimize