@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 April 1998
+@subtitle Version @value{VERSION}
@author Steve Chamberlain
@author Ian Lance Taylor
@author Cygnus Solutions
@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
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 in linker script
* 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.
@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
@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