\input texinfo
@setfilename ld.info
-@c Copyright 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
@kindex --build-id=@var{style}
@item --build-id
@itemx --build-id=@var{style}
-Request creation of @code{.note.gnu.build-id} ELF note section.
-The contents of the note are unique bits identifying this linked
-file. @var{style} can be @code{uuid} to use 128 random bits,
-@code{sha1} to use a 160-bit @sc{SHA1} hash on the normative
-parts of the output contents, @code{md5} to use a 128-bit
-@sc{MD5} hash on the normative parts of the output contents, or
-@code{0x@var{hexstring}} to use a chosen bit string specified as
-an even number of hexadecimal digits (@code{-} and @code{:}
-characters between digit pairs are ignored). If @var{style} is
-omitted, @code{sha1} is used.
+Request the creation of a @code{.note.gnu.build-id} ELF note section
+or a @code{.build-id} COFF section. The contents of the note are
+unique bits identifying this linked file. @var{style} can be
+@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
+@sc{SHA1} hash on the normative parts of the output contents,
+@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
+the output contents, or @code{0x@var{hexstring}} to use a chosen bit
+string specified as an even number of hexadecimal digits (@code{-} and
+@code{:} characters between digit pairs are ignored). If @var{style}
+is omitted, @code{sha1} is used.
The @code{md5} and @code{sha1} styles produces an identifier
that is always the same in an identical output file, but will be
@kindex --enable-auto-image-base
@item --enable-auto-image-base
-Automatically choose the image base for DLLs, unless one is specified
-using the @code{--image-base} argument. By using a hash generated
-from the dllname to create unique image bases for each DLL, in-memory
-collisions and relocations which can delay program execution are
-avoided.
+@itemx --enable-auto-image-base=@var{value}
+Automatically choose the image base for DLLs, optionally starting with base
+@var{value}, unless one is specified using the @code{--image-base} argument.
+By using a hash generated from the dllname to create unique image bases
+for each DLL, in-memory collisions and relocations which can delay program
+execution are avoided.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-auto-image-base
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
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
@end group
@end smallexample
The whitespace around @var{section} is required, so that the section
name is unambiguous. The colon and the curly braces are also required.
+The comma at the end may be required if a @var{fillexp} is used and
+the next @var{sections-command} looks like a continuation of the expression.
The line breaks and other white space are optional.
Each @var{output-section-command} may be one of the following:
@dots{}
@} [:@var{phdr}@dots{}] [=@var{fill}]
@dots{}
- @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
+ @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
@end group
@end smallexample
except that no addresses and no memory regions may be defined for
sections within an @code{OVERLAY}.
+The comma at the end may be required if a @var{fill} is used and
+the next @var{sections-command} looks like a continuation of the expression.
+
The sections are all defined with the same starting address. The load
addresses of the sections are arranged such that they are consecutive in
memory starting at the load address used for the @code{OVERLAY} as a
@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