\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@set UsesEnvVars
@set GENERIC
@set ARM
+@set C6X
@set H8300
@set HPPA
@set I960
@end ifset
@c man end
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
+@ifnottex
+@dircategory Software development
+@direntry
* Ld: (ld). The GNU linker.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
+@end direntry
+@end ifnottex
@copying
This file documents the @sc{gnu} linker LD
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
+Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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
@itemx --no-copy-dt-needed-entries
This option affects the treatment of dynamic libraries referred to
by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
-command line. Normally the linker will add a DT_NEEDED tag to the
+command line. Normally the linker won't add a DT_NEEDED tag to the
output binary for each library mentioned in a DT_NEEDED tag in an
-input dynamic library. With @option{--no-copy-dt-needed-entries}
+input dynamic library. With @option{--copy-dt-needed-entries}
specified on the command line however any dynamic libraries that
-follow it will have their DT_NEEDED entries ignored. The default
-behaviour can be restored with @option{--copy-dt-needed-entries}.
+follow it will have their DT_NEEDED entries added. The default
+behaviour can be restored with @option{--no-copy-dt-needed-entries}.
This option also has an effect on the resolution of symbols in dynamic
-libraries. With the default setting dynamic libraries mentioned on
-the command line will be recursively searched, following their
-DT_NEEDED tags to other libraries, in order to resolve symbols
-required by the output binary. With
-@option{--no-copy-dt-needed-entries} specified however the searching
-of dynamic libraries that follow it will stop with the dynamic
-library itself. No DT_NEEDED links will be traversed to resolve
+libraries. With @option{--copy-dt-needed-entries} dynamic libraries
+mentioned on the command line will be recursively searched, following
+their DT_NEEDED tags to other libraries, in order to resolve symbols
+required by the output binary. With the default setting however
+the searching of dynamic libraries that follow it will stop with the
+dynamic library itself. No DT_NEEDED links will be traversed to resolve
symbols.
@cindex cross reference table
be restored by specifying @samp{--no-print-gc-sections} on the command
line.
+@kindex --print-output-format
+@cindex output format
+@item --print-output-format
+Print the name of the default output format (perhaps influenced by
+other command-line options). This is the string that would appear
+in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
+
@cindex help
@cindex usage
@kindex --help
unresolved symbol but the option @option{--warn-unresolved-symbols}
can change this to a warning.
-@kindex --verbose
-@cindex verbose
+@kindex --verbose[=@var{NUMBER}]
+@cindex verbose[=@var{NUMBER}]
@item --dll-verbose
-@itemx --verbose
+@itemx --verbose[=@var{NUMBER}]
Display the version number for @command{ld} and list the linker emulations
supported. Display which input files can and cannot be opened. Display
-the linker script being used by the linker.
+the linker script being used by the linker. If the optional @var{NUMBER}
+argument > 1, plugin symbol status will also be displayed.
@kindex --version-script=@var{version-scriptfile}
@cindex version script, symbol versions
Request 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
+Request creation of @code{.eh_frame} unwind info for linker
+generated code sections like PLT. This option is on by default
+if linker generated unwind info is supported.
+
@kindex --enable-new-dtags
@kindex --disable-new-dtags
@item --enable-new-dtags
mismatches are considered to be errors.
[This option is specific to the i386 PE targeted port of the linker]
+@kindex --leading-underscore
+@kindex --no-leading-underscore
+@item --leading-underscore
+@itemx --no-leading-underscore
+For most targets default symbol-prefix is an underscore and is defined
+in target's description. By this option it is possible to
+disable/enable the default underscore symbol-prefix.
+
@cindex DLLs, creating
@kindex --export-all-symbols
@item --export-all-symbols
@c man end
+@ifset C6X
+@subsection Options specific to C6X uClinux targets
+
+@c man begin OPTIONS
+
+The C6X uClinux target uses a binary format called DSBT to support shared
+libraries. Each shared library in the system needs to have a unique index;
+all executables use an index of 0.
+
+@table @gcctabopt
+
+@kindex --dsbt-size
+@item --dsbt-size @var{size}
+This option sets the number of entires in the DSBT of the current executable
+or shared library to @var{size}. The default is to create a table with 64
+entries.
+
+@kindex --dsbt-index
+@item --dsbt-index @var{index}
+This option sets the DSBT index of the current executable or shared library
+to @var{index}. The default is 0, which is appropriate for generating
+executables. If a shared library is generated with a DSBT index of 0, the
+@code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
+
+@kindex --no-merge-exidx-entries
+The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
+exidx entries in frame unwind info.
+
+@end table
+
+@c man end
+@end ifset
+
@ifset M68HC11
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
architecture of an object file by using the @code{objdump} program with
the @samp{-f} option.
@end ifclear
+
+@item LD_FEATURE(@var{string})
+@kindex LD_FEATURE(@var{string})
+This command may be used to modify @command{ld} behavior. If
+@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
+in a script are simply treated as numbers everywhere.
+@xref{Expression Section}.
@end table
@node Assignments
@cindex address, section
@cindex section address
The @var{address} is an expression for the VMA (the virtual memory
-address) of the output section. If you do not provide @var{address},
-the linker will set it based on @var{region} if present, or otherwise
-based on the current value of the location counter.
-
-If you provide @var{address}, the address of the output section will be
-set to precisely that. If you provide neither @var{address} nor
-@var{region}, then the address of the output section will be set to the
-current value of the location counter aligned to the alignment
-requirements of the output section. The alignment requirement of the
-output section is the strictest alignment of any input section contained
-within the output section.
-
-For example,
+address) of the output section. This address is optional, but if it
+is provided then the output address will be set exactly as specified.
+
+If the output address is not specified then one will be chosen for the
+section, based on the heuristic below. This address will be adjusted
+to fit the alignment requirement of the output section. The
+alignment requirement is the strictest alignment of any input section
+contained within the output section.
+
+The output section address heuristic is as follows:
+
+@itemize @bullet
+@item
+If an output memory @var{region} is set for the section then it
+is added to this region and its address will be the next free address
+in that region.
+
+@item
+If the MEMORY command has been used to create a list of memory
+regions then the first region which has attributes compatible with the
+section is selected to contain it. The section's output address will
+be the next free address in that region; @ref{MEMORY}.
+
+@item
+If no memory regions were specified, or none match the section then
+the output address will be based on the current value of the location
+counter.
+@end itemize
+
+@noindent
+For example:
+
@smallexample
.text . : @{ *(.text) @}
@end smallexample
+
@noindent
and
+
@smallexample
.text : @{ *(.text) @}
@end smallexample
+
@noindent
are subtly different. The first will set the address of the
@samp{.text} output section to the current value of the location
counter. The second will set it to the current value of the location
-counter aligned to the strictest alignment of a @samp{.text} input
-section.
+counter aligned to the strictest alignment of any of the @samp{.text}
+input sections.
The @var{address} may be an arbitrary expression; @ref{Expressions}.
For example, if you want to align the section on a 0x10 byte boundary,
data.o(.data)
@end smallexample
+To refine the sections that are included based on the section flags
+of an input section, INPUT_SECTION_FLAGS may be used.
+
+Here is a simple example for using Section header flags for ELF sections:
+
+@smallexample
+@group
+SECTIONS @{
+ .text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
+ .text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
+@}
+@end group
+@end smallexample
+
+In this example, the output section @samp{.text} will be comprised of any
+input section matching the name *(.text) whose section header flags
+@code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section
+@samp{.text2} will be comprised of any input section matching the name *(.text)
+whose section header flag @code{SHF_WRITE} is clear.
+
You can also specify files within archives by writing a pattern
matching the archive, a colon, then the pattern matching the file,
with no whitespace around the colon.
difference is @code{SORT_BY_ALIGNMENT} will sort sections into
ascending order by alignment before placing them in the output file.
+@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.
+
@cindex SORT
@code{SORT} is an alias for @code{SORT_BY_NAME}.
the input sections which map into it. You can override this by using
the section type. For example, in the script sample below, the
@samp{ROM} section is addressed at memory location @samp{0} and does not
-need to be loaded when the program is run. The contents of the
-@samp{ROM} section will appear in the linker output file as usual.
+need to be loaded when the program is run.
@smallexample
@group
SECTIONS @{
@cindex load address
@cindex section load address
Every section has a virtual address (VMA) and a load address (LMA); see
-@ref{Basic Script Concepts}. The address expression which may appear in
-an output section description sets the VMA (@pxref{Output Section
-Address}).
-
-The expression @var{lma} that follows the @code{AT} keyword specifies
-the load address of the section.
+@ref{Basic Script Concepts}. The virtual address is specified by the
+@pxref{Output Section Address} described earlier. The load address is
+specified by the @code{AT} or @code{AT>} keywords. Specifying a load
+address is optional.
-Alternatively, with @samp{AT>@var{lma_region}} expression, you may
-specify a memory region for the section's load address. @xref{MEMORY}.
-Note that if the section has not had a VMA assigned to it then the
-linker will use the @var{lma_region} as the VMA region as well.
+The @code{AT} keyword takes an expression as an argument. This
+specifies the exact load address of the section. The @code{AT>} keyword
+takes the name of a memory region as an argument. @xref{MEMORY}. The
+load address of the section is set to the next free address in the
+region, aligned to the section's alignment requirements.
If neither @code{AT} nor @code{AT>} is specified for an allocatable
-section, the linker will set the LMA such that the difference between
-VMA and LMA for the section is the same as the preceding output
-section in the same region. If there is no preceding output section
-or the section is not allocatable, the linker will set the LMA equal
-to the VMA.
-@xref{Output Section Region}.
+section, the linker will use the following heuristic to determine the
+load address:
+
+@itemize @bullet
+@item
+If the section has a specific VMA address, then this is used as
+the LMA address as well.
+
+@item
+If the section is not allocatable then its LMA is set to its VMA.
+
+@item
+Otherwise if a memory region can be found that is compatible
+with the current section, and this region contains at least one
+section, then the LMA is set so the difference between the
+VMA and LMA is the same as the difference between the VMA and LMA of
+the last section in the located region.
+
+@item
+If no memory regions have been declared then a default region
+that covers the entire address space is used in the previous step.
+
+@item
+If no suitable region could be found, or there was no previous
+section then the LMA is set equal to the VMA.
+@end itemize
@cindex ROM initialized data
@cindex initialized data in ROM
char *src = &_etext;
char *dst = &_data;
-/* ROM has data at end of text; copy it. */
-while (dst < &_edata) @{
+/* ROM has data at end of text; copy it. */
+while (dst < &_edata)
*dst++ = *src++;
-@}
-/* Zero bss */
+/* Zero bss. */
for (dst = &_bstart; dst< &_bend; dst++)
*dst = 0;
@end group
@item L
Same as @samp{I}
@item !
-Invert the sense of any of the preceding attributes
+Invert the sense of any of the attributes that follow
@end table
If a unmapped section matches any of the listed attributes other than
bar1; bar2;
extern "C++" @{
ns::*;
- "int f(int, double)";
- @}
+ "f(int, double)";
+ @};
@} VERS_1.2;
@end smallexample
The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
The linker will iterate over the list of symbols at the link time and
demangle them according to @samp{lang} before matching them to the
-patterns specified in @samp{version-script-commands}.
+patterns specified in @samp{version-script-commands}. The default
+@samp{lang} is @samp{C}.
Demangled names may contains spaces and other special characters. As
described above, you can use a glob pattern to match demangled names,
@cindex absolute and relocatable symbols
@cindex relocatable and absolute symbols
@cindex symbols, relocatable and absolute
-When the linker evaluates an expression, the result is either absolute
-or relative to some section. A relative expression is expressed as a
-fixed offset from the base of a section.
+Addresses and symbols may be section relative, or absolute. A section
+relative symbol is relocatable. If you request relocatable output
+using the @samp{-r} option, a further link operation may change the
+value of a section relative symbol. On the other hand, an absolute
+symbol will retain the same value throughout any further link
+operations.
+
+Some terms in linker expressions are addresses. This is true of
+section relative symbols and for builtin functions that return an
+address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
+@code{SEGMENT_START}. Other terms are simply numbers, or are builtin
+functions that return a non-address value, such as @code{LENGTH}.
+One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
+(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
+differently depending on their location, for compatibility with older
+versions of @code{ld}. Expressions appearing outside an output
+section definition treat all numbers as absolute addresses.
+Expressions appearing inside an output section definition treat
+absolute symbols as numbers. If @code{LD_FEATURE ("SANE_EXPR")} is
+given, then absolute symbols and numbers are simply treated as numbers
+everywhere.
+
+In the following simple example,
+
+@smallexample
+@group
+SECTIONS
+ @{
+ . = 0x100;
+ __executable_start = 0x100;
+ .data :
+ @{
+ . = 0x10;
+ __data_start = 0x10;
+ *(.data)
+ @}
+ @dots{}
+ @}
+@end group
+@end smallexample
+
+both @code{.} and @code{__executable_start} are set to the absolute
+address 0x100 in the first two assignments, then both @code{.} and
+@code{__data_start} are set to 0x10 relative to the @code{.data}
+section in the second two assignments.
-The position of the expression within the linker script determines
-whether it is absolute or relative. An expression which appears within
-an output section definition is relative to the base of the output
-section. An expression which appears elsewhere will be absolute.
+For expressions involving numbers, relative addresses and absolute
+addresses, ld follows these rules to evaluate terms:
-A symbol set to a relative expression will be relocatable if you request
-relocatable output using the @samp{-r} option. That means that a
-further link operation may change the value of the symbol. The symbol's
-section will be the section of the relative expression.
+@itemize @bullet
+@item
+Unary operations on a relative address, and binary operations on two
+relative addresses in the same section or between one relative address
+and a number, apply the operator to the offset part of the address(es).
+@item
+Unary operations on an absolute address, and binary operations on one
+or more absolute addresses or on two relative addresses not in the
+same section, first convert any non-absolute term to an absolute
+address before applying the operator.
+@end itemize
-A symbol set to an absolute expression will retain the same value
-through any further link operation. The symbol will be absolute, and
-will not have any particular associated section.
+The result section of each sub-expression is as follows:
+
+@itemize @bullet
+@item
+An operation involving only numbers results in a number.
+@item
+The result of comparisons, @samp{&&} and @samp{||} is also a number.
+@item
+The result of other binary arithmetic and logical operations on two
+relative addresses in the same section or two absolute addresess
+(after above conversions) is also a number.
+@item
+The result of other operations on relative addresses or one
+relative address and a number, is a relative address in the same
+section as the relative operand(s).
+@item
+The result of other operations on absolute addresses (after above
+conversions) is an absolute address.
+@end itemize
You can use the builtin function @code{ABSOLUTE} to force an expression
to be absolute when it would otherwise be relative. For example, to
If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
@samp{.data} section.
+Using @code{LOADADDR} also forces an expression absolute, since this
+particular builtin function returns an absolute address.
+
@node Builtin Functions
@subsection Builtin Functions
@cindex functions in expressions
@item ADDR(@var{section})
@kindex ADDR(@var{section})
@cindex section address in expression
-Return the absolute address (the VMA) of the named @var{section}. Your
+Return the address (VMA) of the named @var{section}. Your
script must previously have defined the location of that section. In
-the following example, @code{symbol_1} and @code{symbol_2} are assigned
-identical values:
+the following example, @code{start_of_output_1}, @code{symbol_1} and
+@code{symbol_2} are assigned equivalent values, except that
+@code{symbol_1} will be relative to the @code{.output1} section while
+the other two will be absolute:
@smallexample
@group
SECTIONS @{ @dots{}
@item LOADADDR(@var{section})
@kindex LOADADDR(@var{section})
@cindex section load address in expression
-Return the absolute LMA of the named @var{section}. This is normally
-the same as @code{ADDR}, but it may be different if the @code{AT}
-attribute is used in the output section definition (@pxref{Output
+Return the absolute LMA of the named @var{section}. (@pxref{Output
Section LMA}).
@kindex MAX
option) that value will be returned; otherwise the value will be
@var{default}. At present, the @samp{-T} command-line option can only
be used to set the base address for the ``text'', ``data'', and
-``bss'' sections, but you use @code{SEGMENT_START} with any segment
+``bss'' sections, but you can use @code{SEGMENT_START} with any segment
name.
@item SIZEOF(@var{section})
The erratum only affects Thumb-2 code. Please contact ARM for further details.
+@kindex --merge-exidx-entries
+@kindex --no-merge-exidx-entries
+The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
+
@ifclear GENERIC
@lowersections
@end ifclear
the veneer. The extra cycles required to call and return from the veneer
are sufficient to avoid the erratum in both the scalar and vector cases.
+@cindex ARM1176 erratum workaround
+@kindex --fix-arm1176
+@kindex --no-fix-arm1176
+The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum
+in certain ARM1176 processors. The workaround is enabled by default if you
+are targetting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled
+unconditionally by specifying @samp{--no-fix-arm1176}.
+
+Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S
+Programmer Advice Notice'' available on the ARM documentaion website at:
+http://infocenter.arm.com/.
+
@cindex NO_ENUM_SIZE_WARNING
@kindex --no-enum-size-warning
The @option{--no-enum-size-warning} switch prevents the linker from
@cindex PowerPC64 multi-TOC
@kindex --no-multi-toc
@item --no-multi-toc
-By default, PowerPC64 GCC generates code for a TOC model where TOC
+If given any toc option besides @code{-mcmodel=medium} or
+@code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model
+where TOC
entries are accessed with a 16-bit offset from r2. This limits the
total TOC size to 64K. PowerPC64 @command{ld} extends this limit by
grouping code sections such that each group uses less than 64K for its
help if a single input file has a @code{.toc} section that exceeds
64K, most likely from linking multiple files with @command{ld -r}.
Use this option to turn off this feature.
+
+@cindex PowerPC64 TOC sorting
+@kindex --no-toc-sort
+@item --no-toc-sort
+By default, @command{ld} sorts TOC sections so that those whose file
+happens to have a section called @code{.init} or @code{.fini} are
+placed first, followed by TOC sections referenced by code generated
+with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
+referenced only by code generated with PowerPC64 gcc's
+@code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this
+results in better TOC grouping for multi-TOC. Use this option to turn
+off this feature.
+
+@cindex PowerPC64 PLT stub alignment
+@kindex --plt-align
+@kindex --no-plt-align
+@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.
+
+@cindex PowerPC64 PLT call stub static chain
+@kindex --plt-static-chain
+@kindex --no-plt-static-chain
+@item --plt-static-chain
+@itemx --no-plt-static-chain
+Use these options to control whether PLT call stubs load the static
+chain pointer (r11). @code{ld} defaults to not loading the static
+chain since there is never any need to do so on a PLT call.
+
+@cindex PowerPC64 PLT call stub thread safety
+@kindex --plt-thread-safe
+@kindex --no-plt-thread-safe
+@item --plt-thread-safe
+@itemx --no-thread-safe
+With power7's weakly ordered memory model, it is possible when using
+lazy binding for ld.so to update a plt entry in one thread and have
+another thread see the individual plt entry words update in the wrong
+order, despite ld.so carefully writing in the correct order and using
+memory write barriers. To avoid this we need some sort of read
+barrier in the call stub, or use LD_BIND_NOW=1. By default, @code{ld}
+looks for calls to commonly used functions that create threads, and if
+seen, adds the necessary barriers. Use these options to change the
+default behaviour.
@end table
@ifclear GENERIC
projects / deliverable / binutils-gdb.git / blobdiff