\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2015 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2014 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2015 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-2014 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2015 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 specified.
If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
-by the @dfn{sysroot prefix}, a path specified when the linker is configured.
+by the @dfn{sysroot prefix}, controlled by the @samp{--sysroot} option, or
+specified when the linker is configured.
@ifset UsesEnvVars
The default set of paths searched (without being specified with
no difference in the linker's behaviour for different non-zero values
of this option. Again this may change with future releases.
+@kindex --push-state
+@cindex push state governing input file handling
+@item --push-state
+The @option{--push-state} allows to preserve the current state of the
+flags which govern the input file handling so that they can all be
+restored with one corresponding @option{--pop-state} option.
+
+The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
+@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
+@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
+@option{--no-whole-archive}, @option{-r}, @option{-Ur},
+@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
+@option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
+
+One target for this option are specifications for @file{pkg-config}. When
+used with the @option{--libs} option all possibly needed libraries are
+listed and then possibly linked with all the time. It is better to return
+something as follows:
+
+@smallexample
+-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
+@end smallexample
+
+@kindex --pop-state
+@cindex pop state governing input file handling
+Undoes the effect of --push-state, restores the previous values of the
+flags governing input file handling.
+
@kindex -q
@kindex --emit-relocs
@cindex retain relocations in final executable
Disables multiple reloc sections combining.
@item nocopyreloc
-Disables production of copy relocs.
+Disable linker generated .dynbss variables used in place of variables
+defined in shared libraries. May result in dynamic text relocations.
@item nodefaultlib
Marks the object that the search for dependencies of this object will
@item noexecstack
Marks the object as not requiring executable stack.
+@item text
+Treat DT_TEXTREL in shared object as error.
+
+@item notext
+Don't treat DT_TEXTREL in shared object as error.
+
+@item textoff
+Don't treat DT_TEXTREL in shared object as error.
+
@item norelro
Don't create an ELF @code{PT_GNU_RELRO} segment header in the object.
Specifying zero will override any default non-zero sized
@code{PT_GNU_STACK} segment creation.
+@item bndplt
+Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
+
+@item noextern-protected-data
+Don't treat protected data symbol as external when building shared
+library. This option overrides linker backend default. It can be used
+to workaround incorrect relocations against protected data symbols
+generated by compiler. Updates on protected data symbols by another
+module aren't visibile to the resulting shared library. Supported for
+i386 and x86-64.
+
@end table
Other keywords are ignored for Solaris compatibility.
needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
emitted for a library that @emph{at that point in the link} satisfies a
non-weak undefined symbol reference from a regular object file or, if
-the library is not found in the DT_NEEDED lists of other libraries, a
-non-weak undefined symbol reference from another dynamic library.
+the library is not found in the DT_NEEDED lists of other needed libraries, a
+non-weak undefined symbol reference from another needed dynamic library.
Object files or libraries appearing on the command line @emph{after}
the library in question do not affect whether the library is seen as
needed. This is similar to the rules for extraction of object files
context: you may give a hexadecimal constant or the name of an existing
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
constants or symbols. If you need more elaborate expressions, consider
-using the linker command language from a script (@pxref{Assignments,,
-Assignment: Symbol Definitions}). @emph{Note:} there should be no white
-space between @var{symbol}, the equals sign (``@key{=}''), and
-@var{expression}.
+using the linker command language from a script (@pxref{Assignments}).
+@emph{Note:} there should be no white space between @var{symbol}, the
+equals sign (``@key{=}''), and @var{expression}.
@cindex demangling, from command line
@kindex --demangle[=@var{style}]
Only warn once for each undefined symbol, rather than once per module
which refers to it.
+@kindex --warn-orphan
+@kindex --no-warn-orphan
+@cindex warnings, on orphan sections
+@cindex orphan sections, warnings on
+@item --warn-orphan
+The @option{--warn-orphan} option tells the linker to generate a
+warning message whenever it has to place an orphan section into the
+output file. @xref{Orphan Sections} The @option{--no-warn-orphan}
+option restores the default behaviour of just silently placing these
+sections.
+
@kindex --warn-section-align
@cindex warnings, on section alignment
@cindex section alignment, warnings on
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
hash tables. The default is @code{sysv}.
+@kindex --compress-debug-sections=none
+@kindex --compress-debug-sections=zlib
+@kindex --compress-debug-sections=zlib-gnu
+@kindex --compress-debug-sections=zlib-gabi
+@item --compress-debug-sections=none
+@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}
+and @option{--compress-debug-sections=zlib-gnu} compress DWARF debug
+sections and rename debug section names to begin with @samp{.zdebug}
+instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
+compresses DWARF debug sections with SHF_COMPRESSED from the ELF ABI.
+
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
This option reduces memory requirements at ld runtime, at the expense of
of the PE file header:
[These options are specific to PE targeted ports of the linker]
+@kindex --high-entropy-va
+@item --high-entropy-va
+Image is compatible with 64-bit address space layout randomization
+(ASLR).
+
@kindex --dynamicbase
@item --dynamicbase
The image base address may be relocated using address space layout
@kindex --insert-timestamp
@item --insert-timestamp
-Insert a real timestamp into the image, rather than the default value
-of zero. This will result in a slightly different results with each
-invocation, which could be helpful for distributing unique images.
+@itemx --no-insert-timestamp
+Insert a real timestamp into the image. This is the default behaviour
+as it matches legacy code and it means that the image will work with
+other, proprietary tools. The problem with this default is that it
+will result in slightly different images being produced each tiem the
+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 indentical sources will compare
+identically.
@end table
@c man end
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. See 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. See also the
description of @samp{-L} in @ref{Options,,Command Line Options}.
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
with an error code, and print @var{message}.
+Note that assertions are checked before the final stages of linking
+take place. This means that expressions involving symbols PROVIDEd
+inside section definitions will fail if the user has not set values
+for those symbols. The only exception to this rule is PROVIDEd
+symbols that just reference dot. Thus an assertion like this:
+
+@smallexample
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ PROVIDE (__stack_size = 0x100);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will fail if @code{__stack_size} is not defined elsewhere. Symbols
+PROVIDEd outside of section definitions are evaluated earlier, so they
+can be used inside ASSERTions. Thus:
+
+@smallexample
+ PROVIDE (__stack_size = 0x100);
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will work.
+
@item EXTERN(@var{symbol} @var{symbol} @dots{})
@kindex EXTERN
@cindex undefined symbol in linker script
@cindex BE8
@kindex --be8
The @samp{--be8} switch instructs @command{ld} to generate BE8 format
-executables. This option is only valid when linking big-endian objects.
-The resulting image will contain big-endian data and little-endian code.
+executables. This option is only valid when linking big-endian
+objects - ie ones which have been assembled with the @option{-EB}
+option. The resulting image will contain big-endian data and
+little-endian code.
@cindex TARGET1
@kindex --target1-rel
The erratum only affects Thumb-2 code. Please contact ARM for further details.
+@cindex Cortex-A53 erratum 835769 workaround
+@kindex --fix-cortex-a53-835769
+@kindex --no-fix-cortex-a53-835769
+The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
+
+Please contact ARM for further details.
+
@kindex --merge-exidx-entries
@kindex --no-merge-exidx-entries
@cindex Merging exidx entries
@item --plt-align
@itemx --no-plt-align
Use these options to control whether individual PLT call stubs are
-aligned to a 32-byte boundary, or to the specified power of two
-boundary when using @code{--plt-align=}. By default PLT call stubs
-are packed tightly.
+padded so that they don't cross a 32-byte boundary, or to the
+specified power of two boundary when using @code{--plt-align=}. Note
+that this isn't alignment in the usual sense. By default PLT call
+stubs are packed tightly.
@cindex PowerPC64 PLT call stub static chain
@kindex --plt-static-chain
but will fail to respect the alignment instructions, and may issue noisy
warnings about unknown linker directives.
-@cindex default manifest
-@item default manifest
-The linker will automatically add a default manifest to the .rsrc
-section of any fully linked cygwin or MingGW binary. This manifest is
-necessary in order to be able to execute the binary under Windows 8
-(or later). An application can supply its own manifest, and if it
-does so then this manifest will be used in preference to the default
-one.
@end table
@ifclear GENERIC
projects / binutils-gdb.git / blobdiff