@syncodeindex ky cp
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
+@include ldver.texi
@c @smallbook
@end ifinfo
@ifinfo
-This file documents the @sc{gnu} linker LD.
+This file documents the @sc{gnu} linker LD version @value{VERSION}.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
@subtitle The GNU linker
@sp 1
@subtitle @code{ld} version 2
-@subtitle January 1994
+@subtitle Version @value{VERSION}
@author Steve Chamberlain
-@author Cygnus Support
+@author Ian Lance Taylor
+@author Cygnus Solutions
@page
@tex
{\parskip=0pt
-\hfill Cygnus Support\par
-\hfill steve\@cygnus.com, doc\@cygnus.com\par
+\hfill Cygnus Solutions\par
+\hfill ian\@cygnus.com, doc\@cygnus.com\par
\hfill {\it Using LD, the GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
@ifinfo
@node Top
@top Using ld
-This file documents the @sc{gnu} linker ld.
+This file documents the @sc{gnu} linker ld version @value{VERSION}.
@menu
* Overview:: Overview
@item -e @var{entry}
@itemx --entry=@var{entry}
Use @var{entry} as the explicit symbol for beginning execution of your
-program, rather than the default entry point. @xref{Entry Point}, for a
-discussion of defaults and other ways of specifying the
-entry point.
+program, rather than the default entry point. If there is no symbol
+named @var{entry}, the linker will try to parse @var{entry} as a number,
+and use that as the entry address (the number will be interpreted in
+base 10; you may use a leading @samp{0x} for base 16, or a leading
+@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
+and other ways of specifying the entry point.
@cindex dynamic symbol table
@kindex -E
MIPS ECOFF which supports putting large and small objects into different
sections. This is ignored for other object file formats.
+@kindex --gc-sections
+@cindex garbage collection
+@item --gc-sections
+Enable garbage collection of unused input sections. It is ignored on
+targets that do not support this option. This option is not compatible
+with @samp{-r}, nor should it be used with dynamic linking.
+
@cindex runtime library name
@kindex -h@var{name}
@kindex -soname=@var{name}
option is not specified, the name @file{a.out} is used by default. The
script command @code{OUTPUT} can also specify the output file name.
+@kindex -O @var{level}
+@cindex generating optimized output
+@item -O @var{level}
+If @var{level} is a numeric values greater than zero @code{ld} optimizes
+the output. This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+
@cindex partial link
@cindex relocatable output
@kindex -r
@cindex undefined symbol
@item -u @var{symbol}
@itemx --undefined=@var{symbol}
-Force @var{symbol} to be entered in the output file as an undefined symbol.
-Doing this may, for example, trigger linking of additional modules from
-standard libraries. @samp{-u} may be repeated with different option
-arguments to enter additional undefined symbols.
-@c Nice idea, but no such command: This option is equivalent
-@c to the @code{EXTERN} linker command.
+Force @var{symbol} to be entered in the output file as an undefined
+symbol. Doing this may, for example, trigger linking of additional
+modules from standard libraries. @samp{-u} may be repeated with
+different option arguments to enter additional undefined symbols. This
+option is equivalent to the @code{EXTERN} linker script command.
@kindex -v
@kindex -V
@xref{i960,, @code{ld} and the Intel 960 family}.
@end ifset
+
On some platforms, the @samp{--relax} option performs global
optimizations that become possible when the linker resolves addressing
in the program, such as relaxing address modes and synthesizing new
instructions in the output object file.
+On some platforms these link time global optimizations may make symbolic
+debugging of the resulting executable impossible.
+@ifset GENERIC
+This is known to be
+the case for the Matsushita MN10200 and MN10300 family of processors.
+@end ifset
+
@ifset GENERIC
On platforms where this is not supported, @samp{--relax} is accepted,
but ignored.
@code{LD_LIBRARY_PATH}.
@item
The default directories, normally @file{/lib} and @file{/usr/lib}.
+@item
+For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
+exists, the list of directories found in that file.
@end enumerate
If the required shared library is not found, the linker will issue a
Every loadable or allocatable output section has two addresses. The
first is the @dfn{VMA}, or virtual memory address. This is the address
-the sectin will have when the output file is run. The second is the
+the section will have when the output file is run. The second is the
@dfn{LMA}, or load memory address. This is the address at which the
section will be loaded. In most cases the two addresses will be the
same. An example of when they might be different is when a data section
address is set from the current value of the location counter. The
location counter is then incremented by the size of the output section.
+The first line inside the @samp{SECTIONS} command of the above example
+sets the value of the special symbol @samp{.}, which is the location
+counter. If you do not specify the address of an output section in some
+other way (other ways are described later), the address is set from the
+current value of the location counter. The location counter is then
+incremented by the size of the output section. At the start of the
+@samp{SECTIONS} command, the location counter has the value @samp{0}.
+
The second line defines an output section, @samp{.text}. The colon is
required syntax which may be ignored for now. Within the curly braces
after the output section name, you list the names of the input sections
@samp{.text} section in the output file to be @samp{0x10000}.
The remaining lines define the @samp{.data} and @samp{.bss} sections in
-the output file. The @samp{.data} output section will be at address
-@samp{0x8000000}. When the @samp{.bss} output section is defined, the
-value of the location counter will be @samp{0x8000000} plus the size of
-the @samp{.data} output section. The effect is that the @samp{.bss}
-output section will follow immediately after the @samp{.data} output
-section in memory.
+the output file. The linker will place the @samp{.data} output section
+at address @samp{0x8000000}. After the linker places the @samp{.data}
+output section, the value of the location counter will be
+@samp{0x8000000} plus the size of the @samp{.data} output section. The
+effect is that the linker will place the @samp{.bss} output section
+immediately after the @samp{.data} output section in memory
+
+The linker will ensure that each output section has the required
+alignment, by increasing the location counter if necessary. In this
+example, the specified addresses for the @samp{.text} and @samp{.data}
+sections will probably satisfy any alignment constraints, but the linker
+may have to create a small gap between the @samp{.data} and @samp{.bss}
+sections.
That's it! That's a simple and complete linker script.
There are a few other linker scripts commands.
@table @code
+@item ASSERT(@var{exp}, @var{message})
+@kindex ASSERT
+@cindex assertion in linker script
+Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
+with an error code, and print @var{message}.
+
+@item EXTERN(@var{symbol} @var{symbol} @dots{})
+@kindex EXTERN
+@cindex undefined symbol in linker script
+Force @var{symbol} to be entered in the output file as an undefined
+symbol. Doing this may, for example, trigger linking of additional
+modules from standard libraries. You may list several @var{symbol}s for
+each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
+command has the same effect as the @samp{-u} command-line option.
+
@item FORCE_COMMON_ALLOCATION
@kindex FORCE_COMMON_ALLOCATION
-@cindex common allocation
+@cindex common allocation in linker script
This command has the same effect as the @samp{-d} command-line option:
to make @code{ld} assign space to common symbols even if a relocatable
output file is specified (@samp{-r}).
@}
@end smallexample
-In this example, if the program defines @samp{_etext}, the linker will
-give a multiple definition error. If, on the other hand, the program
-defines @samp{etext}, the linker will silently use the definition in the
-program. If the program references @samp{etext} but does not define it,
-the linker will use the definition in the linker script.
+In this example, if the program defines @samp{_etext} (with a leading
+underscore), the linker will give a multiple definition error. If, on
+the other hand, the program defines @samp{etext} (with no leading
+underscore), the linker will silently use the definition in the program.
+If the program references @samp{etext} but does not define it, the
+linker will use the definition in the linker script.
@node SECTIONS
@section SECTIONS command
* Input Section Basics:: Input section basics
* Input Section Wildcards:: Input section wildcard patterns
* Input Section Common:: Input section for common symbols
+* Input Section Keep:: Input section and garbage collection
* Input Section Example:: Input section example
@end menu
.data1 : @{ data.o(.data) @}
@end smallexample
+@cindex SORT
+Normally, the linker will place files and sections matched by wildcards
+in the order in which they are seen during the link. You can change
+this by using the @code{SORT} keyword, which appears before a wildcard
+pattern in parentheses (e.g., @code{SORT(.text*)}). When the
+@code{SORT} keyword is used, the linker will sort the files or sections
+into ascending order by name before placing them in the output file.
+
If you ever get confused about where input sections are going, use the
@samp{-M} linker option to generate a map file. The map file shows
precisely how input sections are mapped to output sections.
notation is now considered obsolete. It is equivalent to
@samp{*(COMMON)}.
+@node Input Section Keep
+@subsubsection Input section and garbage collection
+@cindex KEEP
+@cindex garbage collection
+When link-time garbage collection is in use (@samp{--gc-sections}),
+it is often useful to mark sections that should not be eliminated.
+This is accomplished by surrounding an input section's wildcard entry
+with @code{KEEP()}, as in @code{KEEP(*(.init))} or
+@code{KEEP(SORT(*)(.ctors))}.
+
@node Input Section Example
@subsubsection Input section example
The following example is a complete linker script. It tells the linker
__DTOR_END__ = .;
@end smallexample
+If you are using the @sc{gnu} C++ support for initialization priority,
+which provides some control over the order in which global constructors
+are run, you must sort the constructors at link time to ensure that they
+are executed in the correct order. When using the @code{CONSTRUCTORS}
+command, use @samp{SORT(CONSTRUCTORS)} instead. When using the
+@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
+@samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and
+@samp{*(.dtors)}.
+
Normally the compiler and linker will handle these issues automatically,
and you will not need to concern yourself with them. However, you may
need to consider this if you are using C++ and writing your own linker
scripts.
+
@end table
@node Output Section Discarding
section command, such as a symbol assignment, then the output section
will always be created, even if there are no matching input sections.
+@cindex /DISCARD/
The special output section name @samp{/DISCARD/} may be used to discard
input sections. Any input sections which are assigned to an output
section named @samp{/DISCARD/} are not included in the output file.
using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
one or more segments, then all subsequent allocated sections will be
assigned to those segments as well, unless they use an explicitly
-@code{:@var{phdr}} modifier. To prevent a section from being assigned
-to a segment when it would normally default to one, use @code{:NONE}.
+@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
+linker to not put the section in any segment at all.
Here is a simple example:
@smallexample
@end group
@end smallexample
-If you have defined a memory region named @samp{mem}, you can direct the
-linker to place specific output sections into that memory region by
-using the @samp{>@var{region}} output section attribute. @xref{Output
-Section Region}. If no address was specified for the output section,
-the linker will set the address to the next available address within the
-memory region. If the combined output sections directed to a memory
-region are too large for the region, the linker will issue an error
-message.
+Once you define a memory region, you can direct the linker to place
+specific output sections into that memory region by using the
+@samp{>@var{region}} output section attribute. For example, if you have
+a memory region named @samp{mem}, you would use @samp{>mem} in the
+output section definition. @xref{Output Section Region}. If no address
+was specified for the output section, the linker will set the address to
+the next available address within the memory region. If the combined
+output sections directed to a memory region are too large for the
+region, the linker will issue an error message.
@node PHDRS
@section PHDRS Command
then the linker will place all subsequent allocatable sections which do
not specify @samp{:@var{phdr}} in the same segments. This is for
convenience, since generally a whole set of contiguous sections will be
-placed in a single segment. To prevent a section from being assigned to
-a segment when it would normally default to one, use @code{:NONE}.
+placed in a single segment. You can use @code{:NONE} to override the
+default segment and tell the linker to not put the section in any
+segment at all.
@kindex FILEHDR
@kindex PHDRS
@smallexample
@group
-SECTIONS@{ @dots{}
+SECTIONS @{ @dots{}
.text : @{
begin = DEFINED(begin) ? begin : . ;
@dots{}
@}
-@dots{} @}
+ @dots{}
+@}
@end group
@end smallexample
@menu
* H8/300:: @code{ld} and the H8/300
* i960:: @code{ld} and the Intel 960 family
+* ARM:: @code{ld} and the ARM family
@end menu
@end ifset
@ifclear GENERIC
@raisesections
@end ifclear
+
@node H8/300
@section @code{ld} and the H8/300
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
top page of memory).
@end table
+
@ifclear GENERIC
@lowersections
@end ifclear
@ifclear GENERIC
@raisesections
@end ifclear
+
@node i960
@section @code{ld} and the Intel 960 family
@end ifclear
@end ifset
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node ARM
+@section @code{ld}'s support for interworking between ARM and Thumb code
+
+@cindex ARM interworking support
+@cindex --support-old-code
+For the ARM, @code{ld} will generate code stubs to allow functions calls
+betweem ARM and Thumb code. These stubs only work with code that has
+been compiled and assembled with the @samp{-mthumb-interwork} command
+line option. If it is necessary to link with old ARM object files or
+libraries, which have not been compiled with the -mthumb-interwork
+option then the @samp{--support-old-code} command line switch should be
+given to the linker. This will make it generate larger stub functions
+which will work with non-interworking aware ARM code. Note, however,
+the linker does not support generating stubs for function calls to
+non-interworking aware Thumb code.
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+
@ifclear SingleFormat
@node BFD
@chapter BFD
projects / deliverable / binutils-gdb.git / blobdiff