\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2018 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2019 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@set GENERIC
@set ARM
@set C6X
+@set CSKY
@set H8300
@set HPPA
@set M68HC11
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2019 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-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2019 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
See @ref{Expressions} for more information about expressions in linker
scripts.
+
+@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
+
+@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
+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)
+@end smallexample
+
+It 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
@kindex -n
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{$@{libdir@}/bfd-plugins} directory. All gcc
+copied into the @file{$@{bindir@}/../lib/bfd-plugins} directory. All gcc
based linker plugins are backward compatible, so it is sufficient to
just copy in the newest one.
@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
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
libraries, the linker must assume that any visible symbol is
referenced. Once this initial set of sections has been determined,
the linker recursively marks as used any section referenced by their
-relocations. See @samp{--entry} and @samp{--undefined}.
+relocations. See @samp{--entry}, @samp{--undefined}, and
+@samp{--gc-keep-exported}.
This option can be set when doing a partial link (enabled with option
@samp{-r}). In this case the root of symbols kept must be explicitly
-specified either by an @samp{--entry} or @samp{--undefined} option or by
-a @code{ENTRY} command in the linker script.
+specified either by one of the options @samp{--entry},
+@samp{--undefined}, or @samp{--gc-keep-exported} or by a @code{ENTRY}
+command in the linker script.
@kindex --print-gc-sections
@kindex --no-print-gc-sections
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to @code{malloc}.
+Only undefined references are replaced by the linker. So, translation unit
+internal references to @var{symbol} are not resolved to
+@code{__wrap_@var{symbol}}. In the next example, the call to @code{f} in
+@code{g} is not resolved to @code{__wrap_f}.
+
+@smallexample
+int
+f (void)
+@{
+ return 123;
+@}
+
+int
+g (void)
+@{
+ return f();
+@}
+@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
@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
new style GNU @code{.gnu.hash} section or @code{both} for both
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
-hash tables. The default is @code{sysv}.
+hash tables. The default depends upon how the linker was configured,
+but for most Linux based systems it will be @code{both}.
@kindex --compress-debug-sections=none
@kindex --compress-debug-sections=zlib
@c man end
@end ifset
+@ifset CSKY
+@subsection Options specific to C-SKY targets
+
+@c man begin OPTIONS
+
+@table @gcctabopt
+
+@kindex --branch-stub on C-SKY
+@item --branch-stub
+This option enables linker branch relaxation by inserting branch stub
+sections when needed to extend the range of branches. This option is
+usually not required since C-SKY supports branch and call instructions that
+can access the full memory range and branch relaxation is normally handled by
+the compiler or assembler.
+
+@kindex --stub-group-size on C-SKY
+@item --stub-group-size=@var{N}
+This option allows finer control of linker branch stub creation.
+It sets the maximum size of a group of input sections that can
+be handled by one stub section. A negative value of @var{N} locates
+stub sections after their branches, while a positive value allows stub
+sections to appear either before or after the branches. Values of
+@samp{1} or @samp{-1} indicate that the
+linker should choose suitable defaults.
+
+@end table
+
+@c man end
+@end ifset
+
@ifset M68HC11
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
the @code{ENTRY(@var{symbol})} command in a linker script;
@item
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
+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
the address of the first byte of the @samp{.text} section, if present;
Invert the sense of any of the attributes that follow
@end table
-If a unmapped section matches any of the listed attributes other than
+If an unmapped section matches any of the listed attributes other than
@samp{!}, it will be placed in the memory region. The @samp{!}
-attribute reverses this test, so that an unmapped section will be placed
-in the memory region only if it does not match any of the listed
-attributes.
+attribute reverses the test for the characters that follow, so that an
+unmapped section will be placed in the memory region only if it does
+not match any of the attributes listed afterwards. Thus an attribute
+string of @samp{RW!X} will match any unmapped section that has either
+or both of the @samp{R} and @samp{W} attributes, but only as long as
+the section does not also have the @samp{X} attribute.
@kindex ORIGIN =
@kindex o =
projects / deliverable / binutils-gdb.git / blobdiff