\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2016 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2017 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 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-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2017 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
no difference in the linker's behaviour for different non-zero values
of this option. Again this may change with future releases.
+@kindex -plugin @var{name}
+@item -plugin @var{name}
+Involve a plugin in the linking process. The @var{name} parameter is
+the absolute filename of the plugin. Usually this parameter is
+automatically added by the complier, when using link time
+optimization, but users can also add their own plugins if they so
+wish.
+
+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
+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.
+
@kindex --push-state
@cindex push state governing input file handling
@item --push-state
be restored by specifying @samp{--no-print-gc-sections} on the command
line.
+@kindex --gc-keep-exported
+@cindex garbage collection
+@item --gc-keep-exported
+When @samp{--gc-sections} is enabled, this option prevents garbage
+collection of unused input sections that contain global symbols having
+default or protected visibility. This option is intended to be used for
+executables where unreferenced sections would otherwise be garbage
+collected regardless of the external visibility of contained symbols.
+Note that this option has no effect when linking shared objects since
+it is already the default behaviour. This option is only supported for
+ELF format targets.
+
@kindex --print-output-format
@cindex output format
@item --print-output-format
this option overrides it. @xref{BFD}.
@end ifclear
+@kindex --out-implib
+@item --out-implib @var{file}
+Create an import library in @var{file} corresponding to the executable
+the linker is generating (eg. a DLL or ELF program). This import
+library (which should be called @code{*.dll.a} or @code{*.a} for DLLs)
+may be used to link clients against the generated executable; this
+behaviour makes it possible to skip a separate import library creation
+step (eg. @code{dlltool} for DLLs). This option is only available for
+the i386 PE and ELF targetted ports of the linker.
+
@kindex -pie
@kindex --pic-executable
@item -pie
either by specifying a list of names separated by colons, or by
appearing multiple times.
+The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search
+directories. They will be replaced by the full path to the directory
+containing the program or shared object in the case of @var{$ORIGIN}
+and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
+64-bit binaries - in the case of @var{$LIB}.
+
+The alternative form of these tokens - @var{$@{ORIGIN@}} and
+@var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
+supported.
+
This option should be used with caution as it overrides the search path
that may have been hard compiled into a shared library. In such a case it
is possible to use unintentionally a different search path than the
call before the linker has a chance to wrap it to @code{malloc}.
@kindex --eh-frame-hdr
+@kindex --no-eh-frame-hdr
@item --eh-frame-hdr
-Request creation of @code{.eh_frame_hdr} section and ELF
-@code{PT_GNU_EH_FRAME} segment header.
+@itemx --no-eh-frame-hdr
+Request (@option{--eh-frame-hdr}) or suppress
+(@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
+section and ELF @code{PT_GNU_EH_FRAME} segment header.
@kindex --ld-generated-unwind-info
@item --no-ld-generated-unwind-info
@itemx --compress-debug-sections=zlib
@itemx --compress-debug-sections=zlib-gnu
@itemx --compress-debug-sections=zlib-gabi
-On ELF platforms , these options control how DWARF debug sections are
-compressed using zlib. @option{--compress-debug-sections=none} doesn't
-compress DWARF debug sections.
-@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
-sections and rename debug section names to begin with @samp{.zdebug}
-instead of @samp{.debug}. @option{--compress-debug-sections=zlib}
-and @option{--compress-debug-sections=zlib-gabi}
-compress DWARF debug sections with SHF_COMPRESSED from the ELF ABI.
-The default behaviour varies depending upon the target involved and
-the configure options used to build the toolchain. The default can be
-determined by examing the output from the linker's @option{--help} option.
+On ELF platforms, these options control how DWARF debug sections are
+compressed using zlib.
+
+@option{--compress-debug-sections=none} doesn't compress DWARF debug
+sections. @option{--compress-debug-sections=zlib-gnu} compresses
+DWARF debug sections and renames them to begin with @samp{.zdebug}
+instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
+also compresses DWARF debug sections, but rather than renaming them it
+sets the SHF_COMPRESSED flag in the sections' headers.
+
+The @option{--compress-debug-sections=zlib} option is an alias for
+@option{--compress-debug-sections=zlib-gabi}.
+
+Note that this option overrides any compression in input debug
+sections, so if a binary is linked with @option{--compress-debug-sections=none}
+for example, then any compressed debug sections in input files will be
+uncompressed before they are copied into the output binary.
+
+The default compression behaviour varies depending upon the target
+involved and the configure options used to build the toolchain. The
+default can be determined by examining the output from the linker's
+@option{--help} option.
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, creating
-@kindex --out-implib
-@item --out-implib @var{file}
-The linker will create the file @var{file} which will contain an
-import lib corresponding to the DLL the linker is generating. This
-import lib (which should be called @code{*.dll.a} or @code{*.a}
-may be used to link clients against the generated DLL; this behaviour
-makes it possible to skip a separate @code{dlltool} import library
-creation step.
-[This option is specific to the i386 PE targeted port of the linker]
-
@kindex --enable-auto-image-base
@item --enable-auto-image-base
@itemx --enable-auto-image-base=@var{value}
@c man begin OPTIONS
The following options are supported to control microMIPS instruction
-generation when linking for MIPS targets.
+generation and branch relocation checks for ISA mode transitions when
+linking for MIPS targets.
@table @gcctabopt
used, all instruction encodings are used, including 16-bit ones where
possible.
+@kindex --ignore-branch-isa
+@item --ignore-branch-isa
+@kindex --no-ignore-branch-isa
+@itemx --no-ignore-branch-isa
+These options control branch relocation checks for invalid ISA mode
+transitions. If @samp{--ignore-branch-isa} is used, then the linker
+accepts any branch relocations and any ISA mode transition required
+is lost in relocation calculation, except for some cases of @code{BAL}
+instructions which meet relaxation conditions and are converted to
+equivalent @code{JALX} instructions as the associated relocation is
+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.
+
@end table
@c man end
@code{NOCROSSREFS} command uses output section names, not input section
names.
+@item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
+@kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
+@cindex cross references
+This command may be used to tell @command{ld} to issue an error about any
+references to one section from a list of other sections.
+
+The @code{NOCROSSREFS} command is useful when ensuring that two or more
+output sections are entirely independent but there are situations where
+a one-way dependency is needed. For example, in a multi-core application
+there may be shared code that can be called from each core but for safety
+must never call back.
+
+The @code{NOCROSSREFS_TO} command takes a list of output section names.
+The first section can not be referenced from any of the other sections.
+If @command{ld} detects any references to the first section from any of
+the other sections, it reports an error and returns a non-zero exit
+status. Note that the @code{NOCROSSREFS_TO} command uses output section
+names, not input section names.
+
@ifclear SingleFormat
@item OUTPUT_ARCH(@var{bfdarch})
@kindex OUTPUT_ARCH(@var{bfdarch})
@end smallexample
@noindent
Here the @samp{*} is a wildcard which matches any file name. To exclude a list
+@cindex EXCLUDE_FILE
of files from matching the file name wildcard, EXCLUDE_FILE may be used to
match all files except the ones specified in the EXCLUDE_FILE list. For
example:
@smallexample
+EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
+@end smallexample
+@noindent
+will cause all .ctors sections from all files except @file{crtend.o}
+and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
+placed inside the section list, for example:
+@smallexample
*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
@end smallexample
-will cause all .ctors sections from all files except @file{crtend.o} and
-@file{otherfile.o} to be included.
+@noindent
+The result of this is identically to the previous example. Supporting
+two syntaxes for EXCLUDE_FILE is useful if the section list contains
+more than one section, as described below.
There are two ways to include more than one section:
@smallexample
@samp{.text} input sections will appear first, followed by all
@samp{.rdata} input sections.
+When using EXCLUDE_FILE with more than one section, if the exclusion
+is within the section list then the exclusion only applies to the
+immediately following section, for example:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text .rdata)
+@end smallexample
+@noindent
+will cause all @samp{.text} sections from all files except
+@file{somefile.o} to be included, while all @samp{.rdata} sections
+from all files, including @file{somefile.o}, will be included. To
+exclude the @samp{.rdata} sections from @file{somefile.o} the example
+could be modified to:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
+@end smallexample
+@noindent
+Alternatively, placing the EXCLUDE_FILE outside of the section list,
+before the input file selection, will cause the exclusion to apply for
+all sections. Thus the previous example can be rewritten as:
+@smallexample
+EXCLUDE_FILE (*somefile.o) *(.text .rdata)
+@end smallexample
+
You can specify a file name to include sections from a particular file.
You would do this if one or more of your files contain special data that
needs to be at a particular location in memory. For example:
@item @code{PT_PHDR} (6)
Indicates a segment where the program headers may be found.
+@item @code{PT_TLS} (7)
+Indicates a segment containing thread local storage.
+
@item @var{expression}
An expression giving the numeric type of the program header. This may
be used for types not defined above.
@item
The result of other binary arithmetic and logical operations on two
relative addresses in the same section or two absolute addresses
-(after above conversions) is also a number.
+(after above conversions) is also a number when
+@code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition
+but an absolute address otherwise.
@item
The result of other operations on relative addresses or one
relative address and a number, is a relative address in the same
which support up to 4Gb of code. The default is to use 12 byte PLT
entries which only support 512Mb of code.
+@kindex --no-apply-dynamic-relocs
+@cindex AArch64 rela addend
+The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
+link-time values for dynamic relocations.
+
+@cindex Placement of SG veneers
+All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
+Its start address must be set, either with the command line option
+@samp{--section-start} or in a linker script, to indicate where to place these
+veneers in memory.
+
+@kindex --cmse-implib
+@cindex Secure gateway import library
+The @samp{--cmse-implib} option requests that the import libraries
+specified by the @samp{--out-implib} and @samp{--in-implib} options are
+secure gateway import libraries, suitable for linking a non-secure
+executable against secure code as per ARMv8-M Security Extensions.
+
+@kindex --in-implib=@var{file}
+@cindex Input import library
+The @samp{--in-implib=file} specifies an input import library whose symbols
+must keep the same address in the executable being produced. A warning is
+given if no @samp{--out-implib} is given but new symbols have been introduced
+in the executable that should be listed in its import library. Otherwise, if
+@samp{--out-implib} is specified, the symbols are added to the output import
+library. A warning is also given if some symbols present in the input import
+library have disappeared from the executable. This option is only effective
+for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is
+specified.
+
@ifclear GENERIC
@lowersections
@end ifclear
or if @samp{--no-insn32} is used, all instruction encodings are used,
including 16-bit ones where possible.
+@cindex MIPS branch relocation check control
+@kindex --ignore-branch-isa
+@kindex --no-ignore-branch-isa
+The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
+control branch relocation checks for invalid ISA mode transitions. If
+@samp{--ignore-branch-isa} is used, then the linker accepts any branch
+relocations and any ISA mode transition required is lost in relocation
+calculation, except for some cases of @code{BAL} instructions which meet
+relaxation conditions and are converted to equivalent @code{JALX}
+instructions as the associated relocation is 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.
+
@ifclear GENERIC
@lowersections
@end ifclear
projects / binutils-gdb.git / blobdiff